CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-store

A localStorage wrapper for all browsers without using cookies or flash, providing persistent client-side storage with automatic fallback and plugin architecture

75

0.96x
Overview
Eval results
Files

storage-config.mddocs/

Storage & Configuration

Store.js provides multiple build configurations and storage backends to optimize for different browser support requirements and use cases.

Capabilities

Build Configurations

Legacy Build

Maximum browser compatibility including IE6+ and ancient Firefox versions.

// Main package entry point (package.json "main" field)
var store = require('store')
// Equivalent to:
var store = require('store/dist/store.legacy')

Features:

  • All storage backends for maximum fallback support
  • JSON2 plugin for legacy browser JSON support
  • Works in IE6+, old Firefox, and all modern browsers
  • Larger bundle size (~13KB minified)

Usage Examples:

var store = require('store')

// Works even in IE6
store.set('data', { message: 'Hello IE6!' })
var data = store.get('data')
console.log(data.message) // 'Hello IE6!'

Modern Build

Optimized for modern browsers with smaller bundle size.

// Modern build for current browsers
var store = require('store/dist/store.modern')

Features:

  • Modern storage backends only (localStorage, sessionStorage, cookieStorage, memoryStorage)
  • No legacy browser support code
  • Smaller bundle size (~7KB minified)
  • Works in all browsers from IE8+

Usage Examples:

var store = require('store/dist/store.modern')

// Same API, smaller bundle
store.set('user', { name: 'Alice', preferences: { theme: 'dark' } })
console.log(store.get('user').name) // 'Alice'

Everything Build

All features and plugins included in one bundle.

// Complete build with all plugins
var store = require('store/dist/store.everything')

Features:

  • All storage backends
  • All plugins pre-loaded
  • Largest bundle size (~22KB minified)
  • Maximum functionality out of the box

Usage Examples:

var store = require('store/dist/store.everything')

// All plugin methods available immediately
store.set('temp', 'data', Date.now() + 60000) // expire plugin
store.watch('temp', function(newVal, oldVal) { // events plugin
    console.log('Temp data changed')
})
store.push('items', 'new item') // operations plugin

V1 Backcompat Build

Complete backwards compatibility with store.js version 1.x API.

// V1 compatibility build
var store = require('store/dist/store.v1-backcompat')

Features:

  • All storage backends for maximum compatibility
  • V1 backcompat plugin pre-loaded
  • JSON2 plugin for legacy browser support
  • Dump plugin for getAll() functionality
  • All v1.x methods available (has, transact, clear, forEach, etc.)
  • Medium bundle size (~15KB minified)

Usage Examples:

var store = require('store/dist/store.v1-backcompat')

// V1 API works out of the box
if (store.has('user')) {
    var user = store.get('user')
}

store.transact('visits', 0, function(current) {
    return current + 1
})

store.forEach(function(key, value) {
    console.log(key, value)
})

Custom Store Creation

Store Engine

Core factory for creating custom store instances.

/**
 * Create custom store with specific storages and plugins
 * @param {Array|Object} storages - Storage backend(s) to use
 * @param {Array|Function} plugins - Plugin(s) to apply
 * @param {string} [namespace] - Optional namespace
 * @returns {Object} Custom store instance
 */
var engine = require('store/src/store-engine')
var customStore = engine.createStore(storages, plugins, namespace?)

Usage Examples:

var engine = require('store/src/store-engine')
var localStorage = require('store/storages/localStorage')
var memoryStorage = require('store/storages/memoryStorage')
var expirePlugin = require('store/plugins/expire')

// Custom store with specific backends and plugins
var customStore = engine.createStore(
    [localStorage, memoryStorage], // Try localStorage, fallback to memory
    [expirePlugin],                // Include expiration support
    'myapp'                        // Namespace all keys with 'myapp'
)

customStore.set('config', { theme: 'dark' }, Date.now() + 86400000) // 24 hours

Storage Backends

Individual storage mechanisms that provide the underlying persistence.

localStorage Backend

Browser localStorage API backend.

var localStorage = require('store/storages/localStorage')

// Storage backend interface
interface Storage {
    name: string              // 'localStorage'
    read(key: string): string | null
    write(key: string, data: string): void
    each(callback: (value: string, key: string) => void): void
    remove(key: string): void
    clearAll(): void
}

sessionStorage Backend

Browser sessionStorage API backend (data cleared when tab closes).

var sessionStorage = require('store/storages/sessionStorage')

cookieStorage Backend

Document.cookie-based storage backend.

var cookieStorage = require('store/storages/cookieStorage')

memoryStorage Backend

In-memory storage backend (data lost on page reload).

var memoryStorage = require('store/storages/memoryStorage')

Legacy Storage Backends

For older browsers:

var oldFFGlobalStorage = require('store/storages/oldFF-globalStorage')
var oldIEUserDataStorage = require('store/storages/oldIE-userDataStorage')

All Storage Backends

Convenience import for all storage backends in optimal fallback order based on browser support and persistence capabilities.

var allStorages = require('store/storages/all')
// Array containing all storage backends in priority order:
// [localStorage, oldFF-globalStorage, oldIE-userDataStorage, 
//  cookieStorage, sessionStorage, memoryStorage]

Storage Priority Order:

  1. localStorage - Modern browsers, persistent across sessions (~2MB capacity)
  2. oldFF-globalStorage - Firefox 6-7 compatibility, persistent
  3. oldIE-userDataStorage - IE6-7 compatibility, persistent (~64KB capacity)
  4. cookieStorage - Cookie fallback for Safari private mode (~4KB capacity)
  5. sessionStorage - Session-only storage, cleared when tab closes
  6. memoryStorage - In-memory fallback, no persistence (cleared on page reload)

Usage Examples:

var engine = require('store/src/store-engine')
var allStorages = require('store/storages/all')

// Store will automatically choose the first working storage
var store = engine.createStore(allStorages, [])

// Manual storage selection
var localStorage = require('store/storages/localStorage')
var memoryStorage = require('store/storages/memoryStorage')

var store = engine.createStore([localStorage, memoryStorage], [])
// Will use localStorage if available, fallback to memoryStorage

Namespace Support

Create isolated storage contexts to avoid key collisions.

/**
 * Create namespaced store instance
 * @param {string} namespace - Namespace identifier (alphanumeric + underscore/dash)
 * @returns {Object} Namespaced store instance
 */
store.namespace(namespace)

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

Usage Examples:

// Create separate namespaces for different app sections
var userStore = store.namespace('user')
var appStore = store.namespace('app')  
var cacheStore = store.namespace('cache')

// Data is isolated by namespace
userStore.set('preferences', { theme: 'dark' })
appStore.set('preferences', { language: 'en' })
cacheStore.set('data', { timestamp: Date.now() })

console.log(userStore.get('preferences'))  // { theme: 'dark' }
console.log(appStore.get('preferences'))   // { language: 'en' }
console.log(userStore.get('data'))         // undefined

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

// Create stores with namespace from start
var engine = require('store/src/store-engine')
var storages = require('store/storages/all')

var adminStore = engine.createStore(storages, [], 'admin')
var guestStore = engine.createStore(storages, [], 'guest')

adminStore.set('permissions', ['read', 'write', 'delete'])
guestStore.set('permissions', ['read'])

Advanced Configuration

Script Tag Usage

For script tag usage without bundlers:

<!-- Legacy build (maximum compatibility) -->
<script src="path/to/store.legacy.min.js"></script>

<!-- Modern build (smaller size) -->
<script src="path/to/store.modern.min.js"></script>

<!-- Everything build (all features) -->
<script src="path/to/store.everything.min.js"></script>

Usage Examples:

<script src="https://cdn.jsdelivr.net/npm/store@2.0.12/dist/store.legacy.min.js"></script>
<script>
// Store is available globally
store.set('user', { name: 'Alice' })
console.log(store.get('user').name) // 'Alice'
</script>

Node.js Environment

Store.js works in Node.js with a localStorage polyfill:

// Install localStorage polyfill for Node.js
// npm install localStorage

// Store.js will automatically detect and use it
var store = require('store')
store.set('data', 'works in Node.js')

Storage Testing

Test if specific storage backends work in the current environment:

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

// Test storage manually
var testStore = engine.createStore([localStorage], [])
if (testStore.enabled) {
    console.log('localStorage is working')
} else {
    console.log('localStorage is not available')
}

Plugin Development

Create custom plugins to extend functionality:

/**
 * Plugin function that returns method implementations
 * @returns {Object} Object with method names as keys and functions as values
 */
function myPlugin() {
    return {
        // Method implementations that can override or extend store methods
        customMethod: function() {
            // Plugin implementation
        }
    }
}

store.addPlugin(myPlugin)

Usage Examples:

// Custom plugin example
function timestampPlugin() {
    return {
        setWithTimestamp: function(_, key, value) {
            var data = {
                value: value,
                timestamp: Date.now()
            }
            this.set(key, data)
        },
        
        getWithAge: function(_, key) {
            var data = this.get(key)
            if (data && data.timestamp) {
                return {
                    value: data.value,
                    age: Date.now() - data.timestamp
                }
            }
            return data
        }
    }
}

store.addPlugin(timestampPlugin)

// Use custom plugin methods
store.setWithTimestamp('data', 'hello world')
setTimeout(function() {
    var result = store.getWithAge('data')
    console.log(result.value) // 'hello world'
    console.log(result.age)   // ~1000 (milliseconds)
}, 1000)

Install with Tessl CLI

npx tessl i tessl/npm-store

docs

core-api.md

index.md

plugins.md

storage-config.md

tile.json