strata-storage 2.4.2 → 2.5.0

package/AI-INTEGRATION-GUIDE.md

@@ -0,0 +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. Current version: **2.5.0**.
+
+## Installation
+
+```bash
+yarn add strata-storage
+```
+
+Zero runtime dependencies. React, Vue, Angular, and `@capacitor/core` are optional peer dependencies — install only what the project uses.
+
+## Core Concepts
+
+- **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
+
+### Default instance (simplest)
+
+```typescript
+import { storage } from 'strata-storage';
+
+await storage.set('user', { id: 1, name: 'John' });
+const user = await storage.get<{ id: number; name: string }>('user');
+await storage.remove('user');
+await storage.clear();
+```
+
+### Your own configured instance
+
+```typescript
+import { defineStorage } from 'strata-storage';
+
+export const storage = defineStorage({
+  defaultStorages: ['indexedDB', 'localStorage'],
+});
+```
+
+`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
+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)
+});
+
+const value = await storage.get('key', { storage: 'indexedDB' });
+```
+
+## Synchronous API (2.5.0)
+
+No `await`. Works only on sync-capable adapters: `memory`, `localStorage`, `sessionStorage`, `cookies`, `url`.
+
+```typescript
+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();
+```
+
+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.
+
+## URL Adapter (2.5.0)
+
+Persist small UI state (tab, filters, pagination) in the URL — survives reload, shareable.
+
+```typescript
+import { defineStorage, URLAdapter } from 'strata-storage';
+
+const storage = defineStorage();
+storage.registerAdapter(new URLAdapter()); // config: { mode: 'query'|'hash', prefix, history, maxLength }
+
+storage.setSync('tab', 'pending', { storage: 'url' });
+const tab = storage.getSync<string>('tab', { storage: 'url' });
+
+storage.subscribe((c) => { if (c.key === 'tab') applyTab(c.newValue); }, { storage: 'url' });
+```
+
+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.
+
+## Disaster Recovery (2.5.0, opt-in)
+
+```typescript
+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
+});
+
+const backup = await storage.snapshot();  // checksum-verified backup string
+await storage.restore(backup);            // throws IntegrityError if corrupted
+```
+
+```typescript
+import { computeChecksum, verifyChecksum, IntegrityError } from 'strata-storage';
+```
+
+Honest note: checksums are **non-cryptographic (FNV-1a)** — they detect accidental corruption, not tampering. Use encryption for tamper resistance.
+
+## Framework Integrations (provider-free, 2.5.0)
+
+### React
+
+```tsx
+import { defineStorage } from 'strata-storage';
+import { createStrataHooks } from 'strata-storage/react';
+
+export const storage = defineStorage();
+export const { useStorage, useStorageQuery, useStorageTTL } = createStrataHooks(storage);
+
+// in a component: const [value, setValue, loading] = useStorage<string>('key', 'default');
+```
+
+`<StrataProvider instance={storage}>` (or `config={...}`) + the same hooks via context is still supported.
+
+### Vue
+
+```typescript
+import { defineStorage } from 'strata-storage';
+import { createStrataComposables } from 'strata-storage/vue';
+
+export const storage = defineStorage();
+export const { useStorage } = createStrataComposables(storage);
+
+// in setup(): const { value, update, loading } = useStorage<string>('key', 'default');
+```
+
+`StrataPlugin` (via `app.use`) is still supported; composables accept an optional instance argument.
+
+### Angular
+
+```typescript
+import { defineStorage } from 'strata-storage';
+import { provideStrata } from 'strata-storage/angular';
+
+const storage = defineStorage();
+// bootstrapApplication(App, { providers: [provideStrata(storage)] });
+// inject StrataService — methods return RxJS Observables: this.storage.get('key').subscribe(...)
+```
+
+`StrataModule.forRoot(config)` + `StrataService` is still supported. `STRATA_INSTANCE` token holds the instance.
+
+### Capacitor (native)
+
+```typescript
+import { defineStorage } from 'strata-storage';
+import { PreferencesAdapter, SecureStorageAdapter } from 'strata-storage/capacitor';
+
+const storage = defineStorage();
+storage.registerAdapter(new PreferencesAdapter());
+storage.registerAdapter(new SecureStorageAdapter());
+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 |
+|-------|----------|
+| 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
+
+- [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)