0
# Store.js
1

2
Store.js is a cross-browser localStorage wrapper library that provides persistent client-side storage without using cookies or flash. It automatically detects and falls back to the best available storage mechanism (localStorage, globalStorage, userData, etc.) for maximum browser compatibility, while offering a modular plugin architecture for extended functionality.
3

4
## Package Information
5

6
- **Package Name**: store
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install store`
10

11
## Core Imports
12

13
```javascript
14
// Main import (legacy build with maximum compatibility)
15
var store = require('store')
16
```
17

18
ES6 modules:
19
```javascript
20
import store from 'store'
21
```
22

23
Alternative builds:
24
```javascript
25
// Modern browsers only (smaller bundle)
26
var store = require('store/dist/store.modern')
27

28
// All features included  
29
var store = require('store/dist/store.everything')
30

31
// Version 1.x API compatibility
32
var store = require('store/dist/store.v1-backcompat')
33
```
34

35
## Basic Usage
36

37
```javascript
38
var store = require('store')
39

40
// Store current user
41
store.set('user', { name: 'Marcus', preferences: { theme: 'dark' } })
42

43
// Get current user
44
var user = store.get('user')
45
console.log(user.name) // 'Marcus'
46

47
// Get with default value
48
var theme = store.get('theme', 'light')
49

50
// Remove current user
51
store.remove('user')
52

53
// Clear all stored values
54
store.clearAll()
55

56
// Loop over all stored values
57
store.each(function(value, key) {
58
    console.log(key, '==', value)
59
})
60
```
61

62
## Architecture
63

64
Store.js is built around several key components:
65

66
- **Storage Backends**: Multiple storage mechanisms with automatic fallback (localStorage, sessionStorage, cookies, memory, legacy IE/Firefox)
67
- **Plugin System**: Modular extensions providing additional functionality like expiration, events, compression, and array operations
68
- **Store Engine**: Core factory system that creates store instances with selected storage backends and plugins
69
- **Build Configurations**: Pre-configured bundles optimized for different browser support levels
70
- **Namespace Support**: Isolated storage contexts for avoiding key collisions
71

72
## Capabilities
73

74
### Core Storage API
75

76
Basic storage operations that work consistently across all browsers.
77

78
```javascript { .api }
79
// Core storage methods
80
store.set(key, value)              // Returns value, undefined removes key
81
store.get(key, defaultValue?)      // Returns stored value or default
82
store.remove(key)                  // Removes key-value pair
83
store.clearAll()                   // Removes all stored values
84
store.each(callback)               // Iterates over all key-value pairs
85

86
// Store properties
87
store.version                      // Library version string
88
store.enabled                      // Boolean indicating if storage works
89

90
// Store management
91
store.createStore(storages, plugins, namespace?)  // Creates new store instance
92
store.addPlugin(plugin)                          // Adds plugin to current store
93
store.namespace(namespace)                       // Creates namespaced store
94
store.hasNamespace(namespace)                    // Checks if store has namespace
95
```
96

97
[Core API](./core-api.md)
98

99
### Plugin Extensions
100

101
Extended functionality through the plugin system including data expiration, event handling, array operations, and more.
102

103
```javascript { .api }
104
// Event handling (events plugin)
105
store.watch(key, listener)         // Watch for changes, returns subscription ID
106
store.unwatch(subscriptionId)      // Remove event subscription  
107
store.once(key, listener)          // Listen for single change event
108

109
// Expiration support (expire plugin)
110
store.set(key, value, expiration)  // Set with expiration timestamp
111
store.getExpiration(key)           // Get expiration timestamp
112
store.removeExpiredKeys()          // Clean up expired keys
113

114
// Array operations (operations plugin)  
115
store.push(key, ...values)         // Array push operation
116
store.pop(key)                     // Array pop operation
117
store.shift(key)                   // Array shift operation
118
store.unshift(key, ...values)      // Array unshift operation
119

120
// Object operations (operations plugin)
121
store.assign(key, ...objects)      // Object.assign operation
122

123
// Value updates (update plugin)
124
store.update(key, updateFn)        // Update value using function
125
store.update(key, defaultVal, updateFn)  // Update with default
126

127
// Default values (defaults plugin)
128
store.defaults(defaultValues)      // Set default values object
129
```
130

131
[Plugin Extensions](./plugins.md)
132

133
### Storage Configuration
134

135
Different build configurations and storage backend management for various browser support requirements.
136

137
```javascript { .api }
138
// Build imports
139
require('store')                          // Legacy build (maximum compatibility)
140
require('store/dist/store.modern')        // Modern build (smaller size)
141
require('store/dist/store.everything')    // All features build
142

143
// Custom store creation
144
var engine = require('store/src/store-engine')
145
var storages = require('store/storages/all')  // All storage backends
146
var plugins = require('store/plugins/all')    // All plugins
147

148
var customStore = engine.createStore(storages, plugins, 'myNamespace')
149
```
150

151
[Storage & Configuration](./storage-config.md)
152

153
## Types
154

155
```javascript { .api }
156
// Callback function types
157
type EachCallback = (value: any, key: string) => void
158
type WatchCallback = (newValue: any, oldValue: any) => void  
159
type UpdateCallback = (currentValue: any) => any
160

161
// Plugin function type
162
type Plugin = () => { [methodName: string]: Function }
163

164
// Storage backend interface
165
interface Storage {
166
    name: string
167
    read(key: string): string | null
168
    write(key: string, data: string): void
169
    each(callback: (value: string, key: string) => void): void
170
    remove(key: string): void
171
    clearAll(): void
172
}
173
```