@framers/sql-storage-adapter 0.2.0 → 0.3.0

package/dist/adapters/indexedDbAdapter.js

@@ -0,0 +1,367 @@
+/**
+ * @fileoverview IndexedDB Storage Adapter for AgentOS
+ * @description Browser-native SQL storage using IndexedDB with sql.js for full client-side operation.
+ * Supports transactions, persistence to IndexedDB, and offline-first workflows.
+ *
+ * **Use cases:**
+ * - Fully client-side AgentOS (no backend needed)
+ * - Progressive Web Apps (PWAs)
+ * - Offline-capable agents
+ * - Privacy-first applications (data never leaves browser)
+ *
+ * **Architecture:**
+ * - Uses sql.js (SQLite compiled to WebAssembly) for SQL execution
+ * - Persists database to IndexedDB for durability across sessions
+ * - Auto-saves after each transaction
+ * - Supports import/export for data portability
+ *
+ * @example
+ * ```typescript
+ * import { IndexedDbAdapter } from '../adapters/indexedDbAdapter';
+ *
+ * const adapter = new IndexedDbAdapter({
+ *   dbName: 'agentos-client-db',
+ *   autoSave: true,
+ *   saveIntervalMs: 5000,
+ * });
+ *
+ * await adapter.open();
+ * await adapter.run('CREATE TABLE sessions (id TEXT PRIMARY KEY, data TEXT)');
+ * await adapter.run('INSERT INTO sessions VALUES (?, ?)', ['session-1', '{"events": []}']);
+ *
+ * const session = await adapter.get('SELECT * FROM sessions WHERE id = ?', ['session-1']);
+ * console.log(session);
+ * ```
+ */
+import initSqlJs from 'sql.js';
+import { normaliseParameters } from '../shared/parameterUtils';
+const DB_VERSION = 1;
+/**
+ * Storage adapter using IndexedDB + sql.js for client-side SQL persistence.
+ *
+ * **Capabilities:**
+ * - ✅ Transactions
+ * - ✅ Persistence (IndexedDB)
+ * - ✅ Full SQL support (via sql.js)
+ * - ✅ Export/import
+ * - ❌ Concurrent writes (single-threaded)
+ * - ❌ Server-side (browser only)
+ *
+ * **Performance:**
+ * - Fast reads (in-memory SQL)
+ * - Moderate writes (IndexedDB persistence)
+ * - Auto-save batching reduces IDB overhead
+ *
+ * @example Client-side AgentOS
+ * ```typescript
+ * const adapter = new IndexedDbAdapter({ dbName: 'my-app-db' });
+ * const agentos = new AgentOS();
+ * await agentos.initialize({
+ *   storageAdapter: adapter,
+ *   // ... other config
+ * });
+ * ```
+ */
+export class IndexedDbAdapter {
+    constructor(options = {}) {
+        this.kind = 'indexeddb';
+        this.capabilities = new Set(['transactions', 'persistence']);
+        this.SQL = null;
+        this.db = null;
+        this.idb = null;
+        this.saveTimer = null;
+        this.dirty = false;
+        this.dbName = options.dbName || 'agentos-db';
+        this.storeName = options.storeName || 'sqliteDb';
+        this.autoSave = options.autoSave ?? true;
+        this.saveIntervalMs = options.saveIntervalMs || 5000;
+        this.sqlJsConfig = options.sqlJsConfig || {};
+    }
+    /**
+     * Opens IndexedDB and initializes sql.js database.
+     * Loads existing database from IndexedDB if present.
+     */
+    async open(_options) {
+        if (this.db) {
+            return; // Already open
+        }
+        // Initialize sql.js
+        this.SQL = await initSqlJs(this.sqlJsConfig);
+        // Open IndexedDB
+        this.idb = await this.openIndexedDb();
+        // Load existing database from IndexedDB or create new
+        const existingData = await this.loadFromIndexedDb();
+        if (existingData) {
+            this.db = new this.SQL.Database(existingData);
+        }
+        else {
+            this.db = new this.SQL.Database();
+        }
+        // Start auto-save interval
+        if (this.autoSave) {
+            this.startAutoSave();
+        }
+    }
+    /**
+     * Executes a SQL statement that doesn't return rows (INSERT, UPDATE, DELETE, CREATE, etc.).
+     * @param statement SQL statement with ? or :name placeholders
+     * @param parameters Positional array or named object
+     * @returns Result with changes count and last insert row ID
+     */
+    async run(statement, parameters) {
+        this.ensureOpen();
+        const stmt = this.db.prepare(statement);
+        try {
+            const { named, positional } = normaliseParameters(parameters);
+            if (named) {
+                stmt.bind(named);
+            }
+            else if (positional) {
+                stmt.bind(positional);
+            }
+            stmt.step();
+            const rowIdResult = this.db.exec('SELECT last_insert_rowid() AS id');
+            const rawRowId = rowIdResult[0]?.values?.[0]?.[0];
+            const lastInsertRowid = this.normaliseRowId(rawRowId);
+            this.dirty = true;
+            await this.persistIfNeeded();
+            return {
+                changes: this.db.getRowsModified(),
+                lastInsertRowid,
+            };
+        }
+        finally {
+            stmt.free();
+        }
+    }
+    /**
+     * Executes a SQL query and returns the first row.
+     * @param statement SELECT statement
+     * @param parameters Query parameters
+     * @returns First row as object or null if no results
+     */
+    async get(statement, parameters) {
+        const rows = await this.all(statement, parameters);
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /**
+     * Executes a SQL query and returns all matching rows.
+     * @param statement SELECT statement
+     * @param parameters Query parameters
+     * @returns Array of result rows as objects
+     */
+    async all(statement, parameters) {
+        this.ensureOpen();
+        const stmt = this.db.prepare(statement);
+        try {
+            const { named, positional } = normaliseParameters(parameters);
+            if (named) {
+                stmt.bind(named);
+            }
+            else if (positional) {
+                stmt.bind(positional);
+            }
+            const results = [];
+            const columnNames = stmt.getColumnNames();
+            while (stmt.step()) {
+                const row = stmt.get();
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const obj = {};
+                columnNames.forEach((col, idx) => {
+                    obj[col] = row[idx];
+                });
+                results.push(obj);
+            }
+            return results;
+        }
+        finally {
+            stmt.free();
+        }
+    }
+    /**
+     * Executes a script containing multiple SQL statements.
+     */
+    async exec(script) {
+        this.ensureOpen();
+        this.db.exec(script);
+        this.dirty = true;
+        await this.persistIfNeeded();
+    }
+    /**
+     * Executes a callback within a database transaction.
+     */
+    async transaction(fn) {
+        this.ensureOpen();
+        await this.run('BEGIN TRANSACTION');
+        try {
+            const result = await fn(this);
+            await this.run('COMMIT');
+            this.dirty = true;
+            await this.persistIfNeeded();
+            return result;
+        }
+        catch (error) {
+            await this.run('ROLLBACK');
+            throw error;
+        }
+    }
+    /**
+     * Begins a transaction. sql.js executes all statements in implicit transactions,
+     * so this is a no-op for compatibility.
+     */
+    async beginTransaction() {
+        // sql.js uses auto-commit; explicit BEGIN is optional
+        await this.run('BEGIN');
+    }
+    /**
+     * Commits the current transaction.
+     */
+    async commit() {
+        await this.run('COMMIT');
+        this.dirty = true;
+        await this.persistIfNeeded();
+    }
+    /**
+     * Rolls back the current transaction.
+     */
+    async rollback() {
+        await this.run('ROLLBACK');
+    }
+    /**
+     * Closes the database and persists final state to IndexedDB.
+     */
+    async close() {
+        if (this.saveTimer) {
+            clearInterval(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (this.dirty) {
+            await this.saveToIndexedDb();
+        }
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+        if (this.idb) {
+            this.idb.close();
+            this.idb = null;
+        }
+    }
+    /**
+     * Exports the database as a Uint8Array (SQLite file format).
+     * Can be downloaded or stored externally.
+     * @returns SQLite database file as binary
+     */
+    exportDatabase() {
+        this.ensureOpen();
+        return this.db.export();
+    }
+    /**
+     * Imports a database from a Uint8Array (SQLite file).
+     * Replaces the current database.
+     * @param data SQLite database file
+     */
+    async importDatabase(data) {
+        this.ensureOpen();
+        this.db.close();
+        this.db = new this.SQL.Database(data);
+        this.dirty = true;
+        await this.saveToIndexedDb();
+    }
+    /**
+     * Opens or creates the IndexedDB database.
+     */
+    openIndexedDb() {
+        return new Promise((resolve, reject) => {
+            const req = indexedDB.open(this.dbName, DB_VERSION);
+            req.onupgradeneeded = () => {
+                const db = req.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    db.createObjectStore(this.storeName);
+                }
+            };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    /**
+     * Loads the SQLite database from IndexedDB.
+     * @returns Binary database or null if not found
+     */
+    async loadFromIndexedDb() {
+        if (!this.idb)
+            return null;
+        return new Promise((resolve, reject) => {
+            const tx = this.idb.transaction(this.storeName, 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const req = store.get('db');
+            req.onsuccess = () => resolve(req.result || null);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    /**
+     * Saves the SQLite database to IndexedDB.
+     */
+    async saveToIndexedDb() {
+        if (!this.idb || !this.db)
+            return;
+        const data = this.db.export();
+        return new Promise((resolve, reject) => {
+            const tx = this.idb.transaction(this.storeName, 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const req = store.put(data, 'db');
+            req.onsuccess = () => {
+                this.dirty = false;
+                resolve();
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    /**
+     * Persists to IndexedDB if auto-save is enabled.
+     */
+    async persistIfNeeded() {
+        if (this.autoSave && !this.saveTimer) {
+            // Immediate save on first write, then batched
+            await this.saveToIndexedDb();
+        }
+    }
+    /**
+     * Starts auto-save interval.
+     */
+    startAutoSave() {
+        this.saveTimer = setInterval(async () => {
+            if (this.dirty) {
+                await this.saveToIndexedDb();
+            }
+        }, this.saveIntervalMs);
+    }
+    /**
+     * Ensures the database is open.
+     */
+    ensureOpen() {
+        if (!this.db) {
+            throw new Error('IndexedDbAdapter: Database not open. Call open() first.');
+        }
+    }
+    /**
+     * Normalizes last insert row ID to string or number.
+     */
+    normaliseRowId(value) {
+        if (typeof value === 'number' || typeof value === 'string') {
+            return value;
+        }
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        return null;
+    }
+    /**
+     * Prepares a SQL statement for execution.
+     */
+    prepareInternal(statement) {
+        this.ensureOpen();
+        return this.db.prepare(statement);
+    }
+}
+//# sourceMappingURL=indexedDbAdapter.js.map

package/dist/adapters/indexedDbAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexedDbAdapter.js","sourceRoot":"","sources":["../../src/adapters/indexedDbAdapter.ts"],"names":[],"mappings":"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"}

package/dist/agentos/AgentOSStorageAdapter.d.ts

@@ -0,0 +1,320 @@
+/**
+ * @fileoverview AgentOS-First Storage Adapter
+ * @description Opinionated storage layer designed specifically for AgentOS with auto-schema,
+ * typed queries, and cross-platform persistence. This is the recommended way to use
+ * sql-storage-adapter with AgentOS.
+ *
+ * **Features:**
+ * - Auto-detects best adapter for platform (web, electron, capacitor, node, cloud)
+ * - Pre-configured schema for conversations, sessions, personas, telemetry
+ * - Typed query builders for common AgentOS operations
+ * - Optional cloud sync for hybrid local+remote architectures
+ * - Export/import for data portability
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { createAgentOSStorage } from '../agentos';
+ * import { AgentOS } from '@agentos/core';
+ *
+ * const storage = await createAgentOSStorage({
+ *   platform: 'auto',  // Detects: web, electron, capacitor, node, cloud
+ *   persistence: true,
+ * });
+ *
+ * const agentos = new AgentOS();
+ * await agentos.initialize({
+ *   storageAdapter: storage,
+ *   // ... other config
+ * });
+ * ```
+ *
+ * @example Multi-Platform
+ * ```typescript
+ * // Web (browser): Uses IndexedDB
+ * const webStorage = await createAgentOSStorage({ platform: 'web' });
+ *
+ * // Desktop (Electron): Uses better-sqlite3
+ * const desktopStorage = await createAgentOSStorage({ platform: 'electron' });
+ *
+ * // Mobile (Capacitor): Uses native SQLite
+ * const mobileStorage = await createAgentOSStorage({ platform: 'capacitor' });
+ *
+ * // Cloud (Node): Uses PostgreSQL
+ * const cloudStorage = await createAgentOSStorage({
+ *   platform: 'cloud',
+ *   postgres: { connectionString: process.env.DATABASE_URL }
+ * });
+ * ```
+ *
+ * @example Hybrid Sync
+ * ```typescript
+ * const storage = await createAgentOSStorage({
+ *   local: { adapter: 'indexeddb' },
+ *   remote: { adapter: 'postgres', connectionString: CLOUD_URL },
+ *   syncStrategy: 'optimistic',  // Local-first, background sync
+ *   syncIntervalMs: 30000,
+ * });
+ * ```
+ */
+import type { StorageAdapter } from '../core/contracts';
+import type { AdapterKind } from '../core/contracts/context';
+/**
+ * Platform types for AgentOS deployment
+ */
+export type AgentOSPlatform = 'web' | 'electron' | 'capacitor' | 'node' | 'cloud' | 'auto';
+/**
+ * Sync strategy for hybrid local+remote storage
+ */
+export type SyncStrategy = 'local-only' | 'remote-only' | 'optimistic' | 'pessimistic';
+/**
+ * Configuration for AgentOS-optimized storage
+ */
+export interface AgentOSStorageConfig {
+    /**
+     * Target platform. 'auto' detects runtime automatically.
+     * @default 'auto'
+     */
+    platform?: AgentOSPlatform;
+    /**
+     * Enable persistence (vs in-memory only).
+     * @default true
+     */
+    persistence?: boolean;
+    /**
+     * Database name (for IndexedDB, SQLite file, etc.)
+     * @default 'agentos-db'
+     */
+    dbName?: string;
+    /**
+     * File path for SQLite adapters
+     */
+    filePath?: string;
+    /**
+     * PostgreSQL connection config
+     */
+    postgres?: {
+        connectionString?: string;
+    };
+    /**
+     * Capacitor-specific options
+     */
+    capacitor?: {
+        database?: string;
+        encrypted?: boolean;
+    };
+    /**
+     * Features to enable (auto-creates tables)
+     * @default all enabled
+     */
+    features?: {
+        conversations?: boolean;
+        sessions?: boolean;
+        personas?: boolean;
+        telemetry?: boolean;
+        workflows?: boolean;
+    };
+    /**
+     * Optional cloud sync for hybrid architectures
+     */
+    cloudSync?: {
+        enabled?: boolean;
+        provider?: 'supabase' | 'postgres' | 'custom';
+        connectionString?: string;
+        syncStrategy?: SyncStrategy;
+        syncIntervalMs?: number;
+    };
+    /**
+     * Advanced: manual adapter priority override
+     */
+    adapterPriority?: AdapterKind[];
+}
+/**
+ * AgentOS-optimized storage adapter with auto-schema and typed queries.
+ *
+ * This class wraps a generic StorageAdapter and adds AgentOS-specific
+ * functionality like auto-schema creation, typed query builders, and
+ * optional cloud sync.
+ */
+export declare class AgentOSStorageAdapter {
+    private adapter;
+    private config;
+    constructor(adapter: StorageAdapter, config: AgentOSStorageConfig);
+    /**
+     * Initializes the storage adapter and creates AgentOS schema.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Gets the underlying storage adapter for custom queries.
+     */
+    getAdapter(): StorageAdapter;
+    /**
+     * Closes the storage adapter.
+     */
+    close(): Promise<void>;
+    /**
+     * Conversations API with typed query builders.
+     *
+     * @example
+     * ```typescript
+     * await storage.conversations.save('conv-1', 'user-1', 'v_researcher', [
+     *   { type: 'user', content: 'Hello', timestamp: Date.now() },
+     *   { type: 'assistant', content: 'Hi!', timestamp: Date.now() },
+     * ]);
+     *
+     * const conversation = await storage.conversations.get('conv-1');
+     * const allConversations = await storage.conversations.list('user-1', { limit: 50 });
+     * ```
+     */
+    get conversations(): {
+        /**
+         * Saves a conversation with its events.
+         * Creates the conversation if it doesn't exist, updates if it does.
+         */
+        save: (id: string, userId: string, personaId: string, events: any[]) => Promise<void>;
+        /**
+         * Gets a conversation by ID with all its events.
+         * Returns null if not found.
+         */
+        get: (id: string) => Promise<{
+            events: any[];
+            id: string;
+            user_id: string;
+            persona_id: string;
+            created_at: number;
+            updated_at: number;
+            metadata: string;
+        } | null>;
+        /**
+         * Lists conversations for a user, ordered by most recent first.
+         */
+        list: (userId: string, options?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            id: string;
+            user_id: string;
+            persona_id: string;
+            created_at: number;
+            updated_at: number;
+            metadata: string;
+        }[]>;
+        /**
+         * Deletes a conversation and all its events.
+         */
+        delete: (id: string) => Promise<void>;
+    };
+    /**
+     * Sessions API with typed query builders.
+     *
+     * @example
+     * ```typescript
+     * await storage.sessions.save('session-1', 'user-1', 'V Session', 'persona', 'v_researcher');
+     * const session = await storage.sessions.get('session-1');
+     * const allSessions = await storage.sessions.list('user-1', { limit: 25 });
+     * ```
+     */
+    get sessions(): {
+        /**
+         * Saves a session (creates or updates).
+         */
+        save: (id: string, userId: string, displayName: string, targetType: "persona" | "agency", targetId: string, metadata?: Record<string, any>) => Promise<void>;
+        /**
+         * Gets a session by ID.
+         */
+        get: (id: string) => Promise<{
+            id: string;
+            user_id: string;
+            display_name: string;
+            target_type: "persona" | "agency";
+            target_id: string;
+            created_at: number;
+            updated_at: number;
+            metadata: string;
+        } | null>;
+        /**
+         * Lists sessions for a user, ordered by most recent first.
+         */
+        list: (userId: string, options?: {
+            limit?: number;
+            offset?: number;
+            targetType?: "persona" | "agency";
+        }) => Promise<{
+            id: string;
+            user_id: string;
+            display_name: string;
+            target_type: "persona" | "agency";
+            target_id: string;
+            created_at: number;
+            updated_at: number;
+            metadata: string;
+        }[]>;
+        /**
+         * Deletes a session.
+         */
+        delete: (id: string) => Promise<void>;
+    };
+    /**
+     * Personas API with typed query builders.
+     *
+     * @example
+     * ```typescript
+     * await storage.personas.cache('v_researcher', 'V', personaDefinition);
+     * const persona = await storage.personas.get('v_researcher');
+     * const allPersonas = await storage.personas.list();
+     * ```
+     */
+    get personas(): {
+        /**
+         * Caches a persona definition (creates or updates).
+         */
+        cache: (id: string, displayName: string, definition: any) => Promise<void>;
+        /**
+         * Gets a persona by ID.
+         */
+        get: (id: string) => Promise<{
+            definition: any;
+            id: string;
+            display_name: string;
+            description: string;
+            created_at: number;
+            updated_at: number;
+        } | null>;
+        /**
+         * Lists all personas, ordered by display name.
+         */
+        list: () => Promise<{
+            definition: any;
+            id: string;
+            display_name: string;
+            description: string;
+            created_at: number;
+            updated_at: number;
+        }[]>;
+        /**
+         * Deletes a persona.
+         */
+        delete: (id: string) => Promise<void>;
+    };
+}
+/**
+ * Creates an AgentOS-optimized storage adapter with auto-detection and schema setup.
+ *
+ * This is the recommended way to use sql-storage-adapter with AgentOS.
+ * It automatically:
+ * 1. Detects the best storage adapter for the current platform
+ * 2. Creates AgentOS-specific tables (conversations, sessions, personas, etc.)
+ * 3. Provides typed query builders for common operations
+ * 4. Handles graceful degradation (e.g., IndexedDB → sql.js)
+ *
+ * @param config Configuration for platform, persistence, and features
+ * @returns Initialized AgentOSStorageAdapter
+ *
+ * @example
+ * ```typescript
+ * const storage = await createAgentOSStorage({ platform: 'auto' });
+ * const agentos = new AgentOS();
+ * await agentos.initialize({ storageAdapter: storage.getAdapter() });
+ * ```
+ */
+export declare function createAgentOSStorage(config?: AgentOSStorageConfig): Promise<AgentOSStorageAdapter>;
+//# sourceMappingURL=AgentOSStorageAdapter.d.ts.map