@web-engine-dev/storage

Unified storage abstraction with 6 provider backends. Provides a consistent API for persisting game data across localStorage, IndexedDB, sessionStorage, in-memory, filesystem (Node.js), and cloud storage.

Layer 8 · Content

Features

• 6 Storage Providers: localStorage, IndexedDB, sessionStorage, in-memory, filesystem (Node.js), cloud
• Unified API: Same get/set/delete/list interface regardless of backend
• Namespacing: Key prefixes prevent collisions between subsystems
• Quota Management: Track usage and handle QuotaExceededError gracefully
• Transactions: Atomic multi-key operations (IndexedDB and cloud backends)
• Serialization: Automatic JSON serialization with type-safe generics
• Migration: Schema version tracking with upgrade functions
• Compression: Optional LZ4 compression for large values via @web-engine-dev/binary-compression
• TTL: Time-to-live expiration for cache-style entries
• Encryption: Optional AES-GCM encryption for sensitive data (cloud backend)

Installation

npm install @web-engine-dev/storage
# or
pnpm add @web-engine-dev/storage

Quick Start

import { StorageManager, IndexedDBProvider } from '@web-engine-dev/storage';

// Create storage with IndexedDB backend
const storage = new StorageManager(new IndexedDBProvider('my-game'));

// Type-safe get/set
await storage.set('player.score', 1500);
const score = await storage.get<number>('player.score'); // 1500

// Namespaced access
const settings = storage.namespace('settings');
await settings.set('volume', 0.8); // Stored as 'settings.volume'
await settings.set('language', 'en');

// List keys
const keys = await settings.list(); // ['volume', 'language']

// Delete
await storage.delete('player.score');

Provider Comparison

Provider	Async	Capacity	Persistence	Use Case
localStorage	No	~5 MB	Permanent	Small settings, preferences
IndexedDB	Yes	~50 MB+	Permanent	Save data, asset cache
sessionStorage	No	~5 MB	Session only	Temporary state
In-Memory	No	RAM	None	Testing, volatile cache
Filesystem	Yes	Disk	Permanent	Node.js server, tools
Cloud	Yes	Unlimited	Permanent	Cross-device saves

Dependencies

• @web-engine-dev/serialization — Value serialization
• @web-engine-dev/binary-compression — Optional compression (optional)