@sitharaj08/react-unified-storage-core

Framework-agnostic core storage library - One unified, secure, and modern storage solution.

✨ Features

• 🚀 TypeScript-first with strict typing and generics
• 🔒 End-to-end encryption with AES-GCM and PBKDF2
• 📦 Automatic compression with gzip
• 🔄 Cross-tab synchronization via BroadcastChannel API
• 💾 Multiple storage drivers (IndexedDB, localStorage, sessionStorage, memory)
• 🛡️ SSR-safe with automatic fallback to in-memory storage
• 📋 Schema validation with Zod integration
• ⏰ TTL support for automatic data expiration
• 🔄 Versioning & migrations for data evolution
• 📊 Metadata tracking (timestamps, driver info, versions)
• 🎯 Tiny bundle (<6KB gzipped)
• 🧪 Comprehensive testing with Vitest

📦 Installation

# Core package only (framework-agnostic)
npm install @sitharaj08/react-unified-storage-core

# Peer dependencies
npm install zod

🚀 Quick Start

import { setup, read, write } from '@sitharaj08/react-unified-storage-core';

// Initialize storage
setup({
  driver: 'auto',
  encryption: { key: 'your-secret-key' },
  compression: true
});

// Store and retrieve data
await write('settings', { theme: 'dark', language: 'en' });
const settings = await read('settings');

🏗️ Storage Drivers

| Driver | Description | SSR Safe | Persistence | Size Limit | Best For | |--------|-------------|----------|-------------|------------|----------| | auto | Auto-selects best available | ✅ | ✅ | Varies | General use | | idb | IndexedDB | ❌ | ✅ | ~50MB+ | Large datasets | | local | localStorage | ❌ | ✅ | ~5-10MB | Small data | | session | sessionStorage | ❌ | Tab-only | ~5-10MB | Temporary data | | memory | In-memory | ✅ | Tab-only | Unlimited | SSR/Caching |

📚 API Reference

Setup & Configuration

setup(config: StorageConfig): Promise<void>

Configuration Options:

interface StorageConfig {
  driver?: StorageDriver;
  namespace?: string;
  broadcast?: boolean;
  encryption?: {
    key: string;
    salt?: string;
  };
  compression?: boolean;
  errorHandler?: (error: Error) => void;
}

Data Operations

// Basic operations
read<T>(key: string): Promise<T | null>
write<T>(key: string, value: T, options?: WriteOptions): Promise<void>
remove(key: string): Promise<void>

// Bulk operations
keys(prefix?: string): Promise<string[]>
clearAll(): Promise<void>

// Collections
createCollection<T>(name: string): Collection<T>

// Utilities
driverId(): string
getCurrentDriver(): StorageDriver
subscribe(callback: BroadcastCallback): () => void

Collections API

interface Collection<T extends { id: string | number }> {
  add(item: Omit<T, 'id'>): Promise<T>;
  get(id: string | number): Promise<T | null>;
  update(id: string | number, updates: Partial<T>): Promise<T>;
  remove(id: string | number): Promise<void>;
  list(filter?: (item: T) => boolean): Promise<T[]>;
  clear(): Promise<void>;
}

🔧 Advanced Usage

Encryption Setup

setup({
  encryption: {
    key: 'your-32-character-secret-key-here!',
    salt: 'optional-salt-for-key-derivation'
  }
});

Security Notes:

• Uses PBKDF2 for key derivation (100,000 iterations)
• AES-GCM for encryption with random IVs
• Keys are derived per storage operation for security

Schema Validation & Migrations

import { z } from 'zod';

const userSchemaV1 = z.object({
  name: z.string(),
  email: z.string()
});

setup({
  schema: userSchemaV1,
  version: 1,
  // Migration function (if needed)
  migrate: (oldData, oldVersion) => {
    if (oldVersion === 1) {
      return { ...oldData, avatar: undefined };
    }
    return oldData;
  }
});

Cross-Tab Synchronization

// Enable broadcasting
setup({ broadcast: true });

// Manual subscription
import { subscribe } from '@sitharaj08/react-unified-storage-core';

const unsubscribe = subscribe((key, envelope) => {
  console.log(`Key ${key} changed:`, envelope?.data);
});

TTL (Time To Live)

// Expires in 1 hour
await write('temp-token', token, { ttlMs: 60 * 60 * 1000 });

// Check expiration
const [data, meta] = await readWithMeta('temp-token');
if (meta?.expiresAt && Date.now() > meta.expiresAt) {
  console.log('Token expired');
}

🧪 Testing

import { setup, read, write } from '@sitharaj08/react-unified-storage-core';

// Use memory driver for testing
setup({ driver: 'memory' });

// Your tests here
test('should store and retrieve data', async () => {
  await write('test', { value: 42 });
  const result = await read('test');
  expect(result).toEqual({ value: 42 });
});

📊 Performance

• Bundle Size: <6KB gzipped
• Operations: ~1-2ms for localStorage, ~5-10ms for IndexedDB
• Memory Usage: Minimal overhead, efficient data structures
• Compression: Up to 70% size reduction for text data

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

Apache License 2.0 © Sitharaj Seenivasan