@students-dev/local-storage-api

Local Storage API v1.0.0

Created by Ramkrishna Bhatt V, Milagres PU College, Kallianpur, Udupi

A comprehensive, production-ready client-side storage API with advanced features, automatic fallbacks, and developer tooling. Store any data type including Objects, Arrays, Blobs, Files, Buffers, TypedArrays, JSON, numbers, strings, booleans, Maps, and Sets.

Installation

npm install @students-dev/local-storage-api

Quick Start

const { LocalStorageAPI, useStore } = require('@students-dev/local-storage-api');

const storage = new LocalStorageAPI();

// Simple API
await storage.save('user', { name: 'Alice', age: 25 });
const user = await storage.load('user');
await storage.delete('user');

// Namespaced storage
const appStorage = useStore('myapp');
await appStorage.save('config', { theme: 'dark' });

// Batch operations
await storage.saveMany([
  ['setting1', 'value1'],
  ['setting2', 'value2']
]);
const values = await storage.loadMany(['setting1', 'setting2']);

// Export/Import
const data = await storage.exportJSON();
await storage.importJSON(data);

Features

Core Features

• Automatic Fallbacks: IndexedDB → LocalStorage → In-memory
• Any Data Type: Supports all JavaScript data types with auto-serialization
• TTL Support: Time-to-live for automatic expiration
• Batch Operations: Efficient bulk operations
• Namespacing: Isolated storage scopes
• Event System: Real-time change notifications
• TypeScript Support: Full type definitions included

Advanced Features

• Compression: lz-string and MessagePack serialization
• Storage Profiles: ultra-fast, max-compression, low-memory, safe-mode
• Snapshots: Save/load/compare storage states
• Query Engine: SQL-like querying with filter, sort, limit
• Metrics & Monitoring: Read/write counts, latency tracking
• Audit Logging: Complete operation history
• Cross-tab Sync: BroadcastChannel real-time synchronization
• Encryption Hooks: User-provided crypto integration
• Migration System: Versioned schema migrations
• Benchmark API: Performance testing utilities

API Reference

Simple API

// Core operations
await storage.save(key, value, options?)
await storage.load(key) // -> value or null
await storage.delete(key)
await storage.reset() // Clear all

// Utility
await storage.exists(key) // -> boolean
await storage.count() // -> number
await storage.all() // -> { key: value, ... }

// Batch
await storage.saveMany([[key1, value1], [key2, value2]])
await storage.loadMany([key1, key2]) // -> { key1: value1, ... }
await storage.deleteMany([key1, key2])

// Import/Export
await storage.exportJSON() // -> JSON string
await storage.importJSON(jsonString)
await storage.exportFile() // Browser download

Advanced API

// Direct access
await storage.set(key, value, { ttl: 3600 })
await storage.get(key)
await storage.remove(key)
await storage.clear()

// Querying
const results = await storage.query()
  .filter(value => value.price > 100)
  .sort((a, b) => a.price - b.price)
  .limit(10)
  .execute()

// Snapshots
await storage.saveSnapshot('backup')
await storage.loadSnapshot('backup')
const diff = storage.compareSnapshots('snap1', 'snap2')

// Metrics
const metrics = storage.getMetrics()
// { reads: 10, writes: 5, avgReadLatency: 2.3, ... }

// Events
storage.on('change', (event) => {
  console.log('Storage changed:', event);
});

Configuration

const storage = new LocalStorageAPI({
  namespace: 'myapp',
  profile: 'max-compression', // ultra-fast, max-compression, low-memory, safe-mode
  debug: true,
  safeMode: false,
  hooks: {
    beforeSet: (key, value) => {
      // Validate or transform
      return value;
    }
  },
  encryption: {
    preWriteEncrypt: (data) => encrypt(data),
    postReadDecrypt: (data) => decrypt(data)
  },
  sync: {
    channel: new BroadcastChannel('my-app-sync')
  }
});

Browser Support

• Chrome 24+
• Firefox 16+
• Safari 10+
• Edge 12+

CLI Tool

# Install globally
npm install -g @students-dev/local-storage-api

# Commands
local-storage-api inspect          # Show storage stats
local-storage-api export data.json # Export to file
local-storage-api import data.json # Import from file
local-storage-api visualize        # Data type charts
local-storage-api benchmark        # Performance test

VS Code Extension

Install the "Local Storage API" extension for advanced debugging:

• Storage Explorer: Tree view of all storage
• Inspector Panel: Real-time storage inspection
• Metrics Dashboard: Performance monitoring
• Snapshot Management: Save/compare/restore states
• Diff Viewer: Side-by-side snapshot comparison

Examples

See the examples/ directory:

• examples/plain-js.js - Vanilla JavaScript
• examples/react.js - React hooks
• examples/vue.js - Vue composables
• examples/svelte.js - Svelte stores

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Lint
npm run lint

# Format code
npm run format

Architecture

The API implements a layered storage architecture:

• IndexedDB Layer: Primary async storage with high capacity
• LocalStorage Layer: Sync fallback with browser persistence
• Memory Layer: In-memory fallback for basic functionality

Automatic fallback ensures reliability across all environments.

Migration Guide

From v0.x to v1.0.0

The v1.0.0 introduces breaking changes:

• store() renamed to save()
• retrieve() renamed to load()
• New advanced features available
• Improved error handling

// Old v0.x
await store('key', 'value');
const value = await retrieve('key');

// New v1.0.0
await storage.save('key', 'value');
const value = await storage.load('key');

Contributing

• Fork the repository
• Create a feature branch
• Add tests for new features
• Ensure all tests pass
• Submit a pull request

License

MIT License - see LICENSE file for details.

Copyright

© 2024 Ramkrishna Bhatt V (Milagres PU College, Kallianpur, Udupi). All rights reserved.