strata-storage 2.4.3 → 2.5.0

package/AI-INTEGRATION-GUIDE.md

@@ -1,354 +1,208 @@
 # AI Integration Guide - strata-storage
 
-Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate strata-storage into web and mobile projects.
+Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.5.0**.
 
 ## Installation
 
 ```bash
 yarn add strata-storage
-# or
-npm install strata-storage
 ```
 
+Zero runtime dependencies. React, Vue, Angular, and `@capacitor/core` are optional peer dependencies — install only what the project uses.
+
 ## Core Concepts
 
-strata-storage provides:
-- **Zero Dependencies** - Pure TypeScript, no runtime deps
-- **9 Storage Adapters** - Memory, LocalStorage, SessionStorage, IndexedDB, Cookies, Cache, Preferences, SQLite, Secure, Filesystem
-- **Advanced Features** - Encryption, compression, TTL, queries, cross-tab sync
+- **Zero dependencies** — pure TypeScript core.
+- **Provider-free** — `defineStorage()` returns a ready-to-use instance; no React context / Vue plugin / Angular module required.
+- **Lazy init** — importing the package does no I/O; instances initialize on first operation. You rarely call `initialize()`.
+- **One API, many backends** — `storage` types: `memory`, `localStorage`, `sessionStorage`, `indexedDB`, `cookies`, `cache`, `url`, plus native `preferences`, `secure`, `sqlite`, `filesystem` (Capacitor).
+- **Opt-in features** — encryption, compression, TTL, queries, cross-tab sync, integrity, durable writes, mirroring, snapshots. All off by default.
 
 ## Quick Start
 
-### Basic Usage
+### Default instance (simplest)
 
 ```typescript
-import { Strata } from 'strata-storage';
-
-const storage = new Strata();
-await storage.initialize();
+import { storage } from 'strata-storage';
 
-// Set data
-await storage.set('username', 'john_doe');
 await storage.set('user', { id: 1, name: 'John' });
-
-// Get data
-const username = await storage.get('username');
 const user = await storage.get<{ id: number; name: string }>('user');
-
-// Remove data
-await storage.remove('username');
-
-// Clear all
+await storage.remove('user');
 await storage.clear();
 ```
 
-### With Encryption
+### Your own configured instance
 
 ```typescript
-const storage = new Strata({
-  encryption: {
-    enabled: true,
-    password: 'your-secure-password',
-  },
-});
-await storage.initialize();
-
-// Data is automatically encrypted
-await storage.set('secret', { token: 'abc123' });
-```
-
-### With TTL (Time-To-Live)
+import { defineStorage } from 'strata-storage';
 
-```typescript
-const storage = new Strata({
-  ttl: {
-    enabled: true,
-    defaultTTL: 3600000, // 1 hour in ms
-  },
+export const storage = defineStorage({
+  defaultStorages: ['indexedDB', 'localStorage'],
 });
-await storage.initialize();
-
-// Expires after 1 hour (default)
-await storage.set('session', { token: '...' });
-
-// Custom TTL: expires in 5 minutes
-await storage.set('cache', data, { ttl: 300000 });
 ```
 
-### With Compression
+`defineStorage()` pre-registers memory, localStorage, sessionStorage, IndexedDB, cookies, and the Cache API. Use `new Strata(config)` + `registerWebAdapters(instance)` only when you need full control.
+
+## Storage Options (per operation)
 
 ```typescript
-const storage = new Strata({
-  compression: {
-    enabled: true,
-    threshold: 1024, // Compress data > 1KB
-  },
+await storage.set('key', value, {
+  storage: 'indexedDB', // pick a specific backend (NOTE: option name is `storage`, not `adapter`)
+  ttl: 3_600_000,       // expire in 1 hour (ms)
+  encrypt: true,        // async only — requires encryption config + password
+  compress: true,       // async only
+  tags: ['user-data'],  // for queries
+  metadata: { version: 1 },
+  verify: true,         // store + check an integrity checksum (2.5.0)
+  durable: true,        // read back and verify the write (2.5.0)
 });
-```
-
-## Storage Adapters
 
-### Web Adapters
-
-```typescript
-import {
-  MemoryAdapter,
-  LocalStorageAdapter,
-  SessionStorageAdapter,
-  IndexedDBAdapter,
-  CookieAdapter,
-  CacheAdapter,
-} from 'strata-storage';
-
-const storage = new Strata();
-storage.registerAdapter(new LocalStorageAdapter());
-storage.registerAdapter(new IndexedDBAdapter());
-await storage.initialize();
+const value = await storage.get('key', { storage: 'indexedDB' });
 ```
 
-### Capacitor/Mobile Adapters
+## Synchronous API (2.5.0)
 
-```typescript
-import { Strata } from 'strata-storage';
-import {
-  PreferencesAdapter,
-  SQLiteAdapter,
-  SecureStorageAdapter,
-  FilesystemAdapter,
-} from 'strata-storage/capacitor';
-
-const storage = new Strata();
-storage.registerAdapter(new PreferencesAdapter());
-storage.registerAdapter(new SecureStorageAdapter()); // For sensitive data
-await storage.initialize();
-```
-
-### Adapter Selection
+No `await`. Works only on sync-capable adapters: `memory`, `localStorage`, `sessionStorage`, `cookies`, `url`.
 
 ```typescript
-// Use specific adapter
-await storage.set('key', 'value', { adapter: 'localStorage' });
-await storage.set('secure', 'secret', { adapter: 'secure' });
-
-// Get from specific adapter
-const value = await storage.get('key', { adapter: 'indexedDB' });
+storage.setSync('lastTab', 'inbox');
+const tab = storage.getSync<string>('lastTab');
+storage.hasSync('lastTab');
+storage.keysSync();   // aggregates across sync-capable adapters
+storage.removeSync('lastTab');
+storage.clearSync();
 ```
 
-## Framework Integrations
-
-### React
-
-```typescript
-import { useStorage } from 'strata-storage/react';
-
-function MyComponent() {
-  const { value, setValue, remove, loading, error } = useStorage<string>('username');
+Constraints: targeting an async-only adapter (indexedDB, cache, sqlite, filesystem, secure, preferences) throws; `setSync` with `encrypt`/`compress` throws; `getSync` on an encrypted/compressed value throws. Use the async API in those cases.
 
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <div>
-      <p>Username: {value}</p>
-      <button onClick={() => setValue('new_user')}>Update</button>
-      <button onClick={remove}>Remove</button>
-    </div>
-  );
-}
-```
+## URL Adapter (2.5.0)
 
-### Vue
+Persist small UI state (tab, filters, pagination) in the URL — survives reload, shareable.
 
 ```typescript
-import { useStorage } from 'strata-storage/vue';
+import { defineStorage, URLAdapter } from 'strata-storage';
 
-const { value, setValue, remove, loading, error } = useStorage<string>('username');
-```
+const storage = defineStorage();
+storage.registerAdapter(new URLAdapter()); // config: { mode: 'query'|'hash', prefix, history, maxLength }
 
-### Angular
+storage.setSync('tab', 'pending', { storage: 'url' });
+const tab = storage.getSync<string>('tab', { storage: 'url' });
 
-```typescript
-import { StorageService } from 'strata-storage/angular';
-
-@Component({ ... })
-export class MyComponent {
-  constructor(private storage: StorageService) {}
-
-  async ngOnInit() {
-    const value = await this.storage.get('key');
-  }
-}
+storage.subscribe((c) => { if (c.key === 'tab') applyTab(c.newValue); }, { storage: 'url' });
 ```
 
-## API Reference
-
-### Strata Class
-
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `initialize()` | Initialize storage and adapters | `Promise<void>` |
-| `set(key, value, options?)` | Store a value | `Promise<void>` |
-| `get<T>(key, options?)` | Retrieve a value | `Promise<T \| null>` |
-| `remove(key, options?)` | Remove a value | `Promise<void>` |
-| `clear(options?)` | Clear all values | `Promise<void>` |
-| `has(key, options?)` | Check if key exists | `Promise<boolean>` |
-| `keys(options?)` | Get all keys | `Promise<string[]>` |
-| `registerAdapter(adapter)` | Register storage adapter | `void` |
-| `subscribe(callback)` | Subscribe to changes | `UnsubscribeFunction` |
+Limits: ~2 KB practical URL length; query mode is sent to the server (use `hash` for client-only); browser-only; not durable. Never put secrets in the URL.
 
-### Configuration Options
+## Disaster Recovery (2.5.0, opt-in)
 
 ```typescript
-interface StrataConfig {
-  defaultStorages?: StorageType[];  // Preferred adapter order
-  autoInitialize?: boolean;         // Auto-init on first operation
-  encryption?: {
-    enabled: boolean;
-    password: string;
-    algorithm?: 'AES-GCM';
-  };
-  compression?: {
-    enabled: boolean;
-    threshold?: number;  // Min bytes to compress
-  };
-  ttl?: {
-    enabled: boolean;
-    defaultTTL?: number; // Default expiration in ms
-    cleanupInterval?: number;
-  };
-  sync?: {
-    enabled: boolean;
-    channel?: string;    // BroadcastChannel name
-  };
-}
-```
-
-### Storage Options
+const storage = defineStorage({
+  integrity: true,        // FNV-1a checksum per value, verified on read
+  durableWrites: true,    // read back + retry each write
+  mirror: ['indexedDB'],  // copy writes to backups; read-repair on corruption
+  autoBackup: { interval: 300_000, storage: 'indexedDB' }, // scheduled snapshots
+});
 
-```typescript
-interface StorageOptions {
-  adapter?: string;     // Specific adapter to use
-  ttl?: number;         // Custom TTL for this operation
-  tags?: string[];      // Tags for querying
-  encrypt?: boolean;    // Override encryption setting
-  compress?: boolean;   // Override compression setting
-}
+const backup = await storage.snapshot();  // checksum-verified backup string
+await storage.restore(backup);            // throws IntegrityError if corrupted
 ```
 
-## Advanced Features
-
-### Tag-Based Queries
-
 ```typescript
-// Store with tags
-await storage.set('user:1', userData, { tags: ['users', 'active'] });
-await storage.set('user:2', userData, { tags: ['users', 'inactive'] });
-
-// Query by tag
-const activeUsers = await storage.query({ tags: ['active'] });
-
-// Query with operators
-const results = await storage.query({
-  where: {
-    age: { $gte: 18 },
-    status: 'active',
-  },
-});
+import { computeChecksum, verifyChecksum, IntegrityError } from 'strata-storage';
 ```
 
-### Cross-Tab Sync
-
-```typescript
-const storage = new Strata({
-  sync: {
-    enabled: true,
-    channel: 'my-app-storage',
-  },
-});
-
-// Subscribe to changes (including from other tabs)
-storage.subscribe((event) => {
-  console.log('Storage changed:', event.key, event.newValue);
-});
-```
+Honest note: checksums are **non-cryptographic (FNV-1a)** — they detect accidental corruption, not tampering. Use encryption for tamper resistance.
 
-### Observer Pattern
+## Framework Integrations (provider-free, 2.5.0)
 
-```typescript
-import { StorageObserver } from 'strata-storage';
+### React
 
-const observer = new StorageObserver(storage);
+```tsx
+import { defineStorage } from 'strata-storage';
+import { createStrataHooks } from 'strata-storage/react';
 
-// Watch specific key
-observer.watch('user', (newValue, oldValue) => {
-  console.log('User changed:', newValue);
-});
+export const storage = defineStorage();
+export const { useStorage, useStorageQuery, useStorageTTL } = createStrataHooks(storage);
 
-// Watch pattern
-observer.watchPattern(/^cache:/, (key, newValue) => {
-  console.log(`Cache key ${key} changed:`, newValue);
-});
+// in a component: const [value, setValue, loading] = useStorage<string>('key', 'default');
 ```
 
-## Common Patterns
+`<StrataProvider instance={storage}>` (or `config={...}`) + the same hooks via context is still supported.
 
-### Initialize Once in App Entry
+### Vue
 
 ```typescript
-// src/storage.ts
-import { Strata } from 'strata-storage';
-
-export const storage = new Strata({
-  encryption: { enabled: true, password: import.meta.env.VITE_STORAGE_KEY },
-  ttl: { enabled: true, defaultTTL: 86400000 }, // 24 hours
-});
+import { defineStorage } from 'strata-storage';
+import { createStrataComposables } from 'strata-storage/vue';
 
-// Initialize early in app lifecycle
-storage.initialize();
+export const storage = defineStorage();
+export const { useStorage } = createStrataComposables(storage);
 
-export default storage;
+// in setup(): const { value, update, loading } = useStorage<string>('key', 'default');
 ```
 
-### Use in Components
+`StrataPlugin` (via `app.use`) is still supported; composables accept an optional instance argument.
 
-```typescript
-import storage from '@/storage';
+### Angular
 
-async function saveSettings(settings: Settings) {
-  await storage.set('settings', settings);
-}
+```typescript
+import { defineStorage } from 'strata-storage';
+import { provideStrata } from 'strata-storage/angular';
 
-async function loadSettings(): Promise<Settings | null> {
-  return await storage.get<Settings>('settings');
-}
+const storage = defineStorage();
+// bootstrapApplication(App, { providers: [provideStrata(storage)] });
+// inject StrataService — methods return RxJS Observables: this.storage.get('key').subscribe(...)
 ```
 
-### Capacitor Mobile Setup
+`StrataModule.forRoot(config)` + `StrataService` is still supported. `STRATA_INSTANCE` token holds the instance.
 
-```typescript
-// capacitor.config.ts - register plugin
-import { registerPlugin } from '@capacitor/core';
+### Capacitor (native)
 
-// In your app initialization
-import { Strata } from 'strata-storage';
+```typescript
+import { defineStorage } from 'strata-storage';
 import { PreferencesAdapter, SecureStorageAdapter } from 'strata-storage/capacitor';
 
-const storage = new Strata();
+const storage = defineStorage();
 storage.registerAdapter(new PreferencesAdapter());
 storage.registerAdapter(new SecureStorageAdapter());
-await storage.initialize();
+await storage.set('secret', token, { storage: 'secure' });
 ```
 
+Native adapters depend on the downstream Capacitor project setup; verify behavior on-device.
+
+## Strata API (most-used methods)
+
+| Method | Returns |
+|--------|---------|
+| `get<T>(key, options?)` | `Promise<T \| null>` |
+| `set<T>(key, value, options?)` | `Promise<void>` |
+| `remove(key, options?)` | `Promise<void>` |
+| `has(key, options?)` | `Promise<boolean>` |
+| `keys(pattern?, options?)` | `Promise<string[]>` |
+| `clear(options?)` | `Promise<void>` |
+| `query<T>(condition, options?)` | `Promise<Array<{ key, value }>>` |
+| `subscribe(cb, options?)` | `UnsubscribeFunction` |
+| `getSync`/`setSync`/`removeSync`/`hasSync`/`keysSync`/`clearSync` | sync equivalents (2.5.0) |
+| `snapshot(options?)` / `restore(snapshot, options?)` | `Promise<string>` / `Promise<void>` (2.5.0) |
+| `getTTL`/`extendTTL`/`persist` | TTL management |
+| `registerAdapter(adapter)` | `void` |
+
 ## Troubleshooting
 
 | Issue | Solution |
 |-------|----------|
-| Data not persisting | Ensure `initialize()` is called before operations |
-| Encryption errors | Check password is consistent, use env vars |
-| Mobile storage not working | Register Capacitor adapters explicitly |
-| Cross-tab not syncing | Enable sync in config, use same channel name |
+| Framework import fails | Ensure `strata-storage >= 2.5.0` (earlier versions never shipped the built entry points). |
+| "does not support synchronous operations" | The targeted adapter is async-only; use the async API or a sync-capable adapter. |
+| Sync set throws on encrypt/compress | Encryption/compression are async — use `await storage.set(...)`. |
+| `useStrata must be used within <StrataProvider>` | Use `createStrataHooks(instance)` for provider-free code. |
+| Native storage not working | Register Capacitor adapters explicitly; verify on a real device. |
+| URL too long warning | URL adapter is for small state; move bulk data to indexedDB/localStorage. |
 
 ## Links
 
-- [Full Documentation](./README.md)
+- [README](./README.md)
 - [Changelog](./CHANGELOG.md)
+- [Core API](./docs/api/core/strata.md)
+- [URL Adapter](./docs/api/adapters/web/url.md)
+- [Recovery & Integrity](./docs/api/features/recovery.md)
 - [GitHub](https://github.com/aoneahsan/strata-storage)