strata-storage 2.4.2 → 2.4.3

package/AI-INTEGRATION-GUIDE.md

@@ -0,0 +1,354 @@
+# 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.
+
+## Installation
+
+```bash
+yarn add strata-storage
+# or
+npm install strata-storage
+```
+
+## 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
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { Strata } from 'strata-storage';
+
+const storage = new Strata();
+await storage.initialize();
+
+// 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.clear();
+```
+
+### With Encryption
+
+```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)
+
+```typescript
+const storage = new Strata({
+  ttl: {
+    enabled: true,
+    defaultTTL: 3600000, // 1 hour in ms
+  },
+});
+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
+
+```typescript
+const storage = new Strata({
+  compression: {
+    enabled: true,
+    threshold: 1024, // Compress data > 1KB
+  },
+});
+```
+
+## 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();
+```
+
+### Capacitor/Mobile Adapters
+
+```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
+
+```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' });
+```
+
+## Framework Integrations
+
+### React
+
+```typescript
+import { useStorage } from 'strata-storage/react';
+
+function MyComponent() {
+  const { value, setValue, remove, loading, error } = useStorage<string>('username');
+
+  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>
+  );
+}
+```
+
+### Vue
+
+```typescript
+import { useStorage } from 'strata-storage/vue';
+
+const { value, setValue, remove, loading, error } = useStorage<string>('username');
+```
+
+### Angular
+
+```typescript
+import { StorageService } from 'strata-storage/angular';
+
+@Component({ ... })
+export class MyComponent {
+  constructor(private storage: StorageService) {}
+
+  async ngOnInit() {
+    const value = await this.storage.get('key');
+  }
+}
+```
+
+## 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` |
+
+### Configuration Options
+
+```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
+
+```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
+}
+```
+
+## 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',
+  },
+});
+```
+
+### 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);
+});
+```
+
+### Observer Pattern
+
+```typescript
+import { StorageObserver } from 'strata-storage';
+
+const observer = new StorageObserver(storage);
+
+// Watch specific key
+observer.watch('user', (newValue, oldValue) => {
+  console.log('User changed:', newValue);
+});
+
+// Watch pattern
+observer.watchPattern(/^cache:/, (key, newValue) => {
+  console.log(`Cache key ${key} changed:`, newValue);
+});
+```
+
+## Common Patterns
+
+### Initialize Once in App Entry
+
+```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
+});
+
+// Initialize early in app lifecycle
+storage.initialize();
+
+export default storage;
+```
+
+### Use in Components
+
+```typescript
+import storage from '@/storage';
+
+async function saveSettings(settings: Settings) {
+  await storage.set('settings', settings);
+}
+
+async function loadSettings(): Promise<Settings | null> {
+  return await storage.get<Settings>('settings');
+}
+```
+
+### Capacitor Mobile Setup
+
+```typescript
+// capacitor.config.ts - register plugin
+import { registerPlugin } from '@capacitor/core';
+
+// In your app initialization
+import { Strata } from 'strata-storage';
+import { PreferencesAdapter, SecureStorageAdapter } from 'strata-storage/capacitor';
+
+const storage = new Strata();
+storage.registerAdapter(new PreferencesAdapter());
+storage.registerAdapter(new SecureStorageAdapter());
+await storage.initialize();
+```
+
+## 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 |
+
+## Links
+
+- [Full Documentation](./README.md)
+- [Changelog](./CHANGELOG.md)
+- [GitHub](https://github.com/aoneahsan/strata-storage)

package/README.md

@@ -1,5 +1,7 @@
 # Strata Storage
 
+- **[AI Integration Guide](./AI-INTEGRATION-GUIDE.md)** - Quick reference for AI development agents (Claude, Cursor, Copilot)
+
 > Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms.
 
 [![npm version](https://img.shields.io/npm/v/strata-storage.svg)](https://www.npmjs.com/package/strata-storage)

package/dist/README.md

@@ -1,5 +1,7 @@
 # Strata Storage
 
+- **[AI Integration Guide](./AI-INTEGRATION-GUIDE.md)** - Quick reference for AI development agents (Claude, Cursor, Copilot)
+
 > Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms.
 
 [![npm version](https://img.shields.io/npm/v/strata-storage.svg)](https://www.npmjs.com/package/strata-storage)

package/dist/config/support.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Support configuration for strata-storage package
+ * Help keep this package free and improving
+ */
+export declare const SUPPORT_CONFIG: {
+    readonly url: "https://aoneahsan.com/payment?project-id=strata-storage&project-identifier=strata-storage";
+    readonly label: "Support the Project";
+    readonly description: "Help us keep strata-storage free and improving";
+};
+//# sourceMappingURL=support.d.ts.map

package/dist/config/support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../../src/config/support.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC"}

package/dist/config/support.js

@@ -0,0 +1,9 @@
+/**
+ * Support configuration for strata-storage package
+ * Help keep this package free and improving
+ */
+export const SUPPORT_CONFIG = {
+    url: 'https://aoneahsan.com/payment?project-id=strata-storage&project-identifier=strata-storage',
+    label: 'Support the Project',
+    description: 'Help us keep strata-storage free and improving',
+};

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strata-storage",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms",
   "type": "module",
   "main": "./index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strata-storage",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,8 @@
     "ios/",
     "android/",
     "scripts/",
-    "StrataStorage.podspec"
+    "StrataStorage.podspec",
+    "AI-INTEGRATION-GUIDE.md"
   ],
   "bin": {
     "strata-storage": "./scripts/cli.js"
@@ -48,7 +49,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:coverage": "vitest --coverage",
-    "prepublishOnly": "pnpm build && pnpm lint && pnpm typecheck",
+    "prepublishOnly": "yarn build && yarn lint && yarn typecheck",
     "postinstall": "node scripts/postinstall.js || true"
   },
   "keywords": [
@@ -100,19 +101,19 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.0.3",
-    "@types/react": "^19.2.7",
-    "@typescript-eslint/eslint-plugin": "^8.50.1",
-    "@typescript-eslint/parser": "^8.50.1",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@types/node": "^25.0.9",
+    "@types/react": "^19.2.9",
+    "@typescript-eslint/eslint-plugin": "^8.53.1",
+    "@typescript-eslint/parser": "^8.53.1",
+    "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-prettier": "^5.5.5",
     "jsdom": "^27.4.0",
-    "prettier": "^3.7.4",
+    "prettier": "^3.8.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.50.1",
-    "vitest": "^4.0.16"
+    "typescript-eslint": "^8.53.1",
+    "vitest": "^4.0.17"
   },
   "engines": {
     "node": ">=18.0.0"