0
# Core Storage API
1

2
The core storage API provides basic, cross-browser persistent storage operations that work consistently across all supported browsers.
3

4
## Capabilities
5

6
### Basic Storage Operations
7

8
#### Set Value
9

10
Stores a value at the specified key. If the value is undefined, the key is removed.
11

12
```javascript { .api }
13
/**
14
 * Store a value at the given key
15
 * @param {string} key - Storage key
16
 * @param {any} value - Value to store (undefined removes the key)
17
 * @returns {any} The stored value
18
 */
19
store.set(key, value)
20
```
21

22
**Usage Examples:**
23

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

31
// Remove a key by setting to undefined
32
store.set('temporary', undefined) // Equivalent to store.remove('temporary')
33
```
34

35
#### Get Value
36

37
Retrieves a value by key, with optional default value if the key doesn't exist.
38

39
```javascript { .api }
40
/**
41
 * Get the value of the given key
42
 * @param {string} key - Storage key to retrieve
43
 * @param {any} [defaultValue] - Default value if key doesn't exist
44
 * @returns {any} Stored value or default value
45
 */
46
store.get(key, defaultValue?)
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
// Basic retrieval
53
var user = store.get('user')
54
console.log(user.name) // 'Alice'
55

56
// With default values
57
var theme = store.get('theme', 'light')     // Returns 'light' if 'theme' not set
58
var settings = store.get('settings', {})    // Returns {} if 'settings' not set
59
var count = store.get('count', 0)           // Returns 0 if 'count' not set
60
```
61

62
#### Remove Value
63

64
Deletes a key-value pair from storage.
65

66
```javascript { .api }
67
/**
68
 * Remove a key-value pair from storage
69
 * @param {string} key - Storage key to remove
70
 */
71
store.remove(key)
72
```
73

74
**Usage Examples:**
75

76
```javascript
77
// Remove specific keys
78
store.remove('user')
79
store.remove('temporary-data')
80

81
// Check if removal was successful
82
store.set('test', 'value')
83
store.remove('test')
84
console.log(store.get('test')) // undefined
85
```
86

87
#### Clear All Values
88

89
Removes all stored key-value pairs.
90

91
```javascript { .api }
92
/**
93
 * Clear all stored key-value pairs
94
 */
95
store.clearAll()
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
// Clear everything
102
store.set('key1', 'value1')
103
store.set('key2', 'value2')
104
store.clearAll()
105

106
console.log(store.get('key1')) // undefined
107
console.log(store.get('key2')) // undefined
108
```
109

110
#### Iterate Over Values
111

112
Iterates over all stored key-value pairs.
113

114
```javascript { .api }
115
/**
116
 * Iterate over all stored key-value pairs
117
 * @param {function} callback - Function called for each key-value pair
118
 */
119
store.each(callback)
120

121
// Callback signature
122
type EachCallback = (value: any, key: string) => void
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
// Basic iteration
129
store.set('user1', { name: 'Alice' })
130
store.set('user2', { name: 'Bob' })
131
store.set('count', 42)
132

133
store.each(function(value, key) {
134
    console.log(key + ' = ' + JSON.stringify(value))
135
})
136
// Output:
137
// user1 = {"name":"Alice"}
138
// user2 = {"name":"Bob"}  
139
// count = 42
140

141
// Conditional processing
142
var users = []
143
store.each(function(value, key) {
144
    if (key.startsWith('user')) {
145
        users.push(value)
146
    }
147
})
148
```
149

150
### Store Information
151

152
#### Version
153

154
The current version of the store.js library.
155

156
```javascript { .api }
157
/**
158
 * Library version string
159
 * @type {string}
160
 */
161
store.version
162
```
163

164
#### Enabled Status
165

166
Indicates whether storage is enabled and functional.
167

168
```javascript { .api }
169
/**
170
 * Whether storage is enabled and functional
171
 * @type {boolean}
172
 */
173
store.enabled
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
console.log('Store.js version:', store.version)  // '2.0.12'
180

181
if (store.enabled) {
182
    // Storage is working
183
    store.set('data', { message: 'Storage is available' })
184
} else {
185
    // Storage is not available (rare - store.js has extensive fallbacks)
186
    console.warn('Storage is not available')
187
}
188
```
189

190
### Store Management
191

192
#### Create Store Instance
193

194
Creates a new store instance with specified storage backends and plugins.
195

196
```javascript { .api }
197
/**
198
 * Create a new store instance
199
 * @param {Array|Object} storages - Storage backend(s) to use
200
 * @param {Array|Function} plugins - Plugin(s) to apply  
201
 * @param {string} [namespace] - Optional namespace for isolation
202
 * @returns {Object} New store instance
203
 */
204
store.createStore(storages, plugins, namespace?)
205
```
206

207
**Usage Examples:**
208

209
```javascript
210
var engine = require('store/src/store-engine')
211
var localStorage = require('store/storages/localStorage')
212
var eventsPlugin = require('store/plugins/events')
213

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

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

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

224
// Keys are isolated by namespace
225
console.log(userStore.get('current'))    // { name: 'Alice' }
226
console.log(settingsStore.get('current')) // undefined
227
```
228

229
#### Add Plugin
230

231
Adds a plugin to the current store instance.
232

233
```javascript { .api }
234
/**
235
 * Add a plugin to the current store instance
236
 * @param {Function|Array} plugin - Plugin function or array of plugins
237
 */
238
store.addPlugin(plugin)
239
```
240

241
**Usage Examples:**
242

243
```javascript
244
var expirePlugin = require('store/plugins/expire')
245
var eventsPlugin = require('store/plugins/events')
246

247
// Add single plugin
248
store.addPlugin(expirePlugin)
249

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

253
// Add multiple plugins
254
store.addPlugin([eventsPlugin, expirePlugin])
255
```
256

257
#### Create Namespaced Store
258

259
Creates a new store instance with the same storage and plugins but in a different namespace.
260

261
```javascript { .api }
262
/**
263
 * Create a namespaced store instance
264
 * @param {string} namespace - Namespace for the new store
265
 * @returns {Object} New namespaced store instance
266
 */
267
store.namespace(namespace)
268
```
269

270
**Usage Examples:**
271

272
```javascript
273
// Create namespaced stores for different contexts
274
var userStore = store.namespace('user')
275
var appStore = store.namespace('app')
276

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

280
// Values are isolated by namespace
281
console.log(userStore.get('preferences')) // { theme: 'dark' }
282
console.log(appStore.get('preferences'))  // { language: 'en' }
283
```
284

285
#### Check Namespace
286

287
Checks if the current store instance has a specific namespace.
288

289
```javascript { .api }
290
/**
291
 * Check if store has the given namespace
292
 * @param {string} namespace - Namespace to check
293
 * @returns {boolean} True if store has the namespace
294
 */
295
store.hasNamespace(namespace)
296
```
297

298
**Usage Examples:**
299

300
```javascript
301
var userStore = store.namespace('user')
302
var mainStore = store
303

304
console.log(userStore.hasNamespace('user'))  // true
305
console.log(userStore.hasNamespace('app'))   // false
306
console.log(mainStore.hasNamespace('user'))  // false
307
```
308

309
### Raw API Access
310

311
Direct access to store methods without plugin modifications. The `raw` property provides access to the original, unmodified store methods before any plugins have been applied.
312

313
```javascript { .api }
314
/**
315
 * Raw API access without plugin modifications
316
 * @type {Object} Object containing unmodified store methods
317
 */
318
store.raw
319

320
// Raw methods available:
321
store.raw.get(key, defaultValue?)      // Unmodified get method
322
store.raw.set(key, value)              // Unmodified set method  
323
store.raw.remove(key)                  // Unmodified remove method
324
store.raw.clearAll()                   // Unmodified clearAll method
325
store.raw.each(callback)               // Unmodified each method
326
```
327

328
**Usage Examples:**
329

330
```javascript
331
// If you have plugins that modify set/get behavior,
332
// raw gives you access to the unmodified methods
333
store.addPlugin(require('store/plugins/events'))
334
store.addPlugin(require('store/plugins/expire'))
335

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

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

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