Core Storage API

/**
 * Store a value at the given key
 * @param {string} key - Storage key
 * @param {any} value - Value to store (undefined removes the key)
 * @returns {any} The stored value
 */
store.set(key, value)

// Store various data types
store.set('user', { name: 'Alice', age: 30 })
store.set('count', 42)
store.set('active', true)
store.set('tags', ['javascript', 'storage'])

// Remove a key by setting to undefined
store.set('temporary', undefined) // Equivalent to store.remove('temporary')

/**
 * Get the value of the given key
 * @param {string} key - Storage key to retrieve
 * @param {any} [defaultValue] - Default value if key doesn't exist
 * @returns {any} Stored value or default value
 */
store.get(key, defaultValue?)

// Basic retrieval
var user = store.get('user')
console.log(user.name) // 'Alice'

// With default values
var theme = store.get('theme', 'light')     // Returns 'light' if 'theme' not set
var settings = store.get('settings', {})    // Returns {} if 'settings' not set
var count = store.get('count', 0)           // Returns 0 if 'count' not set

/**
 * Remove a key-value pair from storage
 * @param {string} key - Storage key to remove
 */
store.remove(key)

// Remove specific keys
store.remove('user')
store.remove('temporary-data')

// Check if removal was successful
store.set('test', 'value')
store.remove('test')
console.log(store.get('test')) // undefined

/**
 * Clear all stored key-value pairs
 */
store.clearAll()

// Clear everything
store.set('key1', 'value1')
store.set('key2', 'value2')
store.clearAll()

console.log(store.get('key1')) // undefined
console.log(store.get('key2')) // undefined

/**
 * Iterate over all stored key-value pairs
 * @param {function} callback - Function called for each key-value pair
 */
store.each(callback)

// Callback signature
type EachCallback = (value: any, key: string) => void

// Basic iteration
store.set('user1', { name: 'Alice' })
store.set('user2', { name: 'Bob' })
store.set('count', 42)

store.each(function(value, key) {
    console.log(key + ' = ' + JSON.stringify(value))
})
// Output:
// user1 = {"name":"Alice"}
// user2 = {"name":"Bob"}  
// count = 42

// Conditional processing
var users = []
store.each(function(value, key) {
    if (key.startsWith('user')) {
        users.push(value)
    }
})

/**
 * Library version string
 * @type {string}
 */
store.version

/**
 * Whether storage is enabled and functional
 * @type {boolean}
 */
store.enabled

console.log('Store.js version:', store.version)  // '2.0.12'

if (store.enabled) {
    // Storage is working
    store.set('data', { message: 'Storage is available' })
} else {
    // Storage is not available (rare - store.js has extensive fallbacks)
    console.warn('Storage is not available')
}

/**
 * Create a new store instance
 * @param {Array|Object} storages - Storage backend(s) to use
 * @param {Array|Function} plugins - Plugin(s) to apply  
 * @param {string} [namespace] - Optional namespace for isolation
 * @returns {Object} New store instance
 */
store.createStore(storages, plugins, namespace?)

var engine = require('store/src/store-engine')
var localStorage = require('store/storages/localStorage')
var eventsPlugin = require('store/plugins/events')

// Create custom store with specific storage and plugins
var customStore = store.createStore(localStorage, eventsPlugin)

// Create namespaced store
var userStore = store.createStore([localStorage], [], 'users')
userStore.set('current', { name: 'Alice' })

var settingsStore = store.createStore([localStorage], [], 'settings')  
settingsStore.set('theme', 'dark')

// Keys are isolated by namespace
console.log(userStore.get('current'))    // { name: 'Alice' }
console.log(settingsStore.get('current')) // undefined

/**
 * Add a plugin to the current store instance
 * @param {Function|Array} plugin - Plugin function or array of plugins
 */
store.addPlugin(plugin)

var expirePlugin = require('store/plugins/expire')
var eventsPlugin = require('store/plugins/events')

// Add single plugin
store.addPlugin(expirePlugin)

// Now expiration methods are available
store.set('temp', 'data', Date.now() + 60000) // Expires in 1 minute

// Add multiple plugins
store.addPlugin([eventsPlugin, expirePlugin])

/**
 * Create a namespaced store instance
 * @param {string} namespace - Namespace for the new store
 * @returns {Object} New namespaced store instance
 */
store.namespace(namespace)

// Create namespaced stores for different contexts
var userStore = store.namespace('user')
var appStore = store.namespace('app')

userStore.set('preferences', { theme: 'dark' })
appStore.set('preferences', { language: 'en' })

// Values are isolated by namespace
console.log(userStore.get('preferences')) // { theme: 'dark' }
console.log(appStore.get('preferences'))  // { language: 'en' }

/**
 * Check if store has the given namespace
 * @param {string} namespace - Namespace to check
 * @returns {boolean} True if store has the namespace
 */
store.hasNamespace(namespace)

var userStore = store.namespace('user')
var mainStore = store

console.log(userStore.hasNamespace('user'))  // true
console.log(userStore.hasNamespace('app'))   // false
console.log(mainStore.hasNamespace('user'))  // false

/**
 * Raw API access without plugin modifications
 * @type {Object} Object containing unmodified store methods
 */
store.raw

// Raw methods available:
store.raw.get(key, defaultValue?)      // Unmodified get method
store.raw.set(key, value)              // Unmodified set method  
store.raw.remove(key)                  // Unmodified remove method
store.raw.clearAll()                   // Unmodified clearAll method
store.raw.each(callback)               // Unmodified each method

// If you have plugins that modify set/get behavior,
// raw gives you access to the unmodified methods
store.addPlugin(require('store/plugins/events'))
store.addPlugin(require('store/plugins/expire'))

// These trigger plugin behavior (events, expiration handling)
store.set('key', 'value')
store.set('temp', 'data', Date.now() + 60000) // expire plugin

// These bypass all plugin modifications
store.raw.set('key', 'value')          // No events triggered
store.raw.get('temp')                  // No expiration checking

// Useful for plugin development or when you need guaranteed
// access to the core storage functionality
var rawValue = store.raw.get('plugin-managed-key')