@anfenn/dync 1.0.28 → 1.0.31

package/dist/wa-sqlite.d.ts

@@ -1,4 +1,4 @@
-import { S as SQLiteDatabaseDriver, a as SQLiteRunResult, b as SQLiteQueryResult } from './types-CSbIAfu2.js';
+import { S as SQLiteDatabaseDriver, a as SQLiteRunResult, b as SQLiteQueryResult } from './types-DeiRXWKl.js';
 
 /**
  * Virtual File System (VFS) options for wa-sqlite.
@@ -6,7 +6,7 @@ import { S as SQLiteDatabaseDriver, a as SQLiteRunResult, b as SQLiteQueryResult
  *
  * @see https://github.com/rhashimoto/wa-sqlite/tree/master/src/examples#vfs-comparison
  */
-type WaSqliteVfsType = 
+type WaSQLiteVfsType = 
 /**
  * IDBBatchAtomicVFS - IndexedDB-backed storage
  * - Works on ALL contexts (Window, Worker, SharedWorker, service worker)
@@ -44,14 +44,14 @@ type WaSqliteVfsType =
  */
  | 'AccessHandlePoolVFS';
 /**
- * Options for configuring the WaSqliteDriver.
+ * Options for configuring the WaSQLiteDriver.
  */
-interface WaSqliteDriverOptions {
+interface WaSQLiteDriverOptions {
     /**
      * Virtual File System to use for storage.
      * @default 'IDBBatchAtomicVFS'
      */
-    vfs?: WaSqliteVfsType;
+    vfs?: WaSQLiteVfsType;
     /**
      * Directory path for the database in OPFS VFS modes.
      * Only used with OPFS-based VFS types.
@@ -113,20 +113,20 @@ interface WaSqliteDriverOptions {
  *
  * @example
  * ```ts
- * import { WaSqliteDriver } from '@anfenn/dync/wa-sqlite';
+ * import { WaSQLiteDriver } from '@anfenn/dync/wa-sqlite';
  * import { SQLiteAdapter } from '@anfenn/dync';
  *
  * // Default: IDBBatchAtomicVFS (works in main thread, multi-tab safe)
- * const driver = new WaSqliteDriver('myapp.db');
+ * const driver = new WaSQLiteDriver('myapp.db');
  *
  * // For OPFS (faster, requires Worker, filesystem transparent)
- * const opfsDriver = new WaSqliteDriver('myapp.db', { vfs: 'OPFSCoopSyncVFS' });
+ * const opfsDriver = new WaSQLiteDriver('myapp.db', { vfs: 'OPFSCoopSyncVFS' });
  *
  * const adapter = new SQLiteAdapter('myapp', driver);
  * ```
  */
-declare class WaSqliteDriver implements SQLiteDatabaseDriver {
-    readonly type = "WaSqliteDriver";
+declare class WaSQLiteDriver implements SQLiteDatabaseDriver {
+    readonly type = "WaSQLiteDriver";
     private db;
     private sqlite3;
     private readonly options;
@@ -134,7 +134,7 @@ declare class WaSqliteDriver implements SQLiteDatabaseDriver {
     private openPromise;
     private executionLock;
     readonly name: string;
-    constructor(databaseName: string, options?: WaSqliteDriverOptions);
+    constructor(databaseName: string, options?: WaSQLiteDriverOptions);
     /**
      * Execute a callback with exclusive database access.
      * This prevents concurrent operations which can corrupt the database.
@@ -162,7 +162,7 @@ declare class WaSqliteDriver implements SQLiteDatabaseDriver {
     /**
      * Get the VFS type being used by this driver.
      */
-    getVfsType(): WaSqliteVfsType;
+    getVfsType(): WaSQLiteVfsType;
     /**
      * Delete the database.
      * This will close the database if open and remove all persisted data.
@@ -172,4 +172,4 @@ declare class WaSqliteDriver implements SQLiteDatabaseDriver {
     delete(): Promise<void>;
 }
 
-export { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult, WaSqliteDriver, type WaSqliteDriverOptions, type WaSqliteVfsType };
+export { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult, WaSQLiteDriver, type WaSQLiteDriverOptions, type WaSQLiteVfsType };

package/dist/wa-sqlite.js

@@ -1,10 +1,10 @@
-// src/storage/sqlite/drivers/WaSqliteDriver.ts
+// src/storage/sqlite/drivers/WaSQLiteDriver.ts
 var cachedModuleFactory = null;
 var cachedModule = null;
-var cachedSqlite3 = null;
+var cachedSQLite3 = null;
 var registeredVFS = /* @__PURE__ */ new Map();
-var WaSqliteDriver = class {
-  type = "WaSqliteDriver";
+var WaSQLiteDriver = class {
+  type = "WaSQLiteDriver";
   db = null;
   sqlite3 = null;
   options;
@@ -54,11 +54,11 @@ var WaSqliteDriver = class {
   }
   async _open() {
     const module = await this.loadWasmModule();
-    if (!cachedSqlite3) {
+    if (!cachedSQLite3) {
       const { Factory } = await import("@journeyapps/wa-sqlite");
-      cachedSqlite3 = Factory(module);
+      cachedSQLite3 = Factory(module);
     }
-    this.sqlite3 = cachedSqlite3;
+    this.sqlite3 = cachedSQLite3;
     const vfsName = `dync_${this.options.vfs}_${this.name}`.replace(/[^a-zA-Z0-9_-]/g, "_");
     let existingVfs = registeredVFS.get(vfsName);
     if (!existingVfs) {
@@ -276,6 +276,6 @@ var WaSqliteDriver = class {
   }
 };
 export {
-  WaSqliteDriver
+  WaSQLiteDriver
 };
 //# sourceMappingURL=wa-sqlite.js.map

package/dist/wa-sqlite.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/storage/sqlite/drivers/WaSqliteDriver.ts"],"sourcesContent":["import type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from '../types';\n\n/**\n * Virtual File System (VFS) options for wa-sqlite.\n * Each VFS has different trade-offs for performance, durability, and compatibility.\n *\n * @see https://github.com/rhashimoto/wa-sqlite/tree/master/src/examples#vfs-comparison\n */\nexport type WaSqliteVfsType =\n    /**\n     * IDBBatchAtomicVFS - IndexedDB-backed storage\n     * - Works on ALL contexts (Window, Worker, SharedWorker, service worker)\n     * - Supports multiple connections\n     * - Full durability with batch atomic writes\n     * - Good general-purpose choice for maximum compatibility\n     * @recommended For apps that need to work in main thread and don't need OPFS\n     */\n    | 'IDBBatchAtomicVFS'\n    /**\n     * IDBMirrorVFS - IndexedDB with in-memory mirror\n     * - Works on ALL contexts\n     * - Supports multiple connections\n     * - Much faster than IDBBatchAtomicVFS\n     * - Database must fit in available memory\n     * @recommended For small databases where performance is critical\n     */\n    | 'IDBMirrorVFS'\n    /**\n     * OPFSCoopSyncVFS - OPFS with cooperative synchronous access\n     * - Requires Worker context\n     * - Supports multiple connections\n     * - Filesystem transparent (can import/export files)\n     * - Good balance of performance and compatibility\n     * @recommended For apps needing OPFS with multi-connection support\n     */\n    | 'OPFSCoopSyncVFS'\n    /**\n     * AccessHandlePoolVFS - OPFS-backed storage (fastest single connection)\n     * - Requires Worker context\n     * - Single connection only (no multi-tab support)\n     * - Best performance, supports WAL mode\n     * - NOT filesystem transparent\n     * @recommended For single-tab apps where performance is critical\n     */\n    | 'AccessHandlePoolVFS';\n\n/**\n * Options for configuring the WaSqliteDriver.\n */\nexport interface WaSqliteDriverOptions {\n    /**\n     * Virtual File System to use for storage.\n     * @default 'IDBBatchAtomicVFS'\n     */\n    vfs?: WaSqliteVfsType;\n\n    /**\n     * Directory path for the database in OPFS VFS modes.\n     * Only used with OPFS-based VFS types.\n     * @default '/'\n     */\n    directory?: string;\n\n    /**\n     * SQLite page size in bytes.\n     * Larger pages can improve read performance for large BLOBs.\n     * Cannot be changed after database creation for IDBBatchAtomicVFS/IDBMirrorVFS.\n     * @default 4096\n     */\n    pageSize?: number;\n\n    /**\n     * SQLite cache size in pages (negative = KB, positive = pages).\n     * Larger cache improves performance but uses more memory.\n     * For IDBBatchAtomicVFS, must be large enough to hold journal for batch atomic mode.\n     * @default -2000 (2MB)\n     */\n    cacheSize?: number;\n\n    /**\n     * Enable WAL (Write-Ahead Logging) mode.\n     * Only supported with AccessHandlePoolVFS (with locking_mode=exclusive).\n     * For other VFS types, this is ignored.\n     * @default false\n     */\n    wal?: boolean;\n\n    /**\n     * Set synchronous pragma for durability vs performance trade-off.\n     * - 'full': Maximum durability (default)\n     * - 'normal': Relaxed durability, better performance (supported by IDBBatchAtomicVFS, IDBMirrorVFS, OPFSPermutedVFS)\n     * - 'off': No sync, fastest but risks data loss on crash\n     * @default 'full'\n     */\n    synchronous?: 'full' | 'normal' | 'off';\n}\n\n// Internal VFS interface for lifecycle management\ninterface WaSqliteVFS {\n    close(): Promise<void>;\n    name: string;\n}\n\n// VFS class type with static create method\ninterface VFSClass {\n    create(name: string, module: any, options?: any): Promise<WaSqliteVFS>;\n}\n\n// Cached module factory and instance\nlet cachedModuleFactory: (() => Promise<any>) | null = null;\nlet cachedModule: any = null;\nlet cachedSqlite3: any = null;\n// Track VFS instances by name to avoid re-registering\nconst registeredVFS = new Map<string, WaSqliteVFS>();\n\n/**\n * SQLite driver for web browsers using wa-sqlite with IndexedDB or OPFS persistence.\n * Provides robust, persistent SQLite storage in the browser that prevents data loss.\n *\n * ## Data Safety Features\n *\n * - **IDBBatchAtomicVFS** (default): Uses IndexedDB batch atomic writes to ensure transactions\n *   are either fully committed or not at all. Multi-tab safe.\n * - **IDBMirrorVFS**: IndexedDB with in-memory mirror. Much faster, database must fit in RAM.\n * - **OPFSCoopSyncVFS**: OPFS with cooperative sync. Multi-connection, filesystem transparent.\n * - **AccessHandlePoolVFS**: Uses OPFS Access Handles for high performance. Single-tab only.\n * - Full durability by default (`PRAGMA synchronous=full`)\n * - Automatic journal mode configuration for each VFS type\n *\n * ## VFS Selection Guide\n *\n * | VFS | Best For | Multi-Tab | Speed |\n * |-----|----------|-----------|-------|\n * | IDBBatchAtomicVFS | General use, main thread | ✅ | Good |\n * | IDBMirrorVFS | Small DBs, main thread | ✅ | Fast |\n * | OPFSCoopSyncVFS | Web Workers, file export | ✅ | Good |\n * | AccessHandlePoolVFS | Single-tab performance | ❌ | Fastest |\n *\n * @example\n * ```ts\n * import { WaSqliteDriver } from '@anfenn/dync/wa-sqlite';\n * import { SQLiteAdapter } from '@anfenn/dync';\n *\n * // Default: IDBBatchAtomicVFS (works in main thread, multi-tab safe)\n * const driver = new WaSqliteDriver('myapp.db');\n *\n * // For OPFS (faster, requires Worker, filesystem transparent)\n * const opfsDriver = new WaSqliteDriver('myapp.db', { vfs: 'OPFSCoopSyncVFS' });\n *\n * const adapter = new SQLiteAdapter('myapp', driver);\n * ```\n */\nexport class WaSqliteDriver implements SQLiteDatabaseDriver {\n    readonly type = 'WaSqliteDriver';\n    private db: number | null = null;\n    private sqlite3: any = null;\n    private readonly options: Required<WaSqliteDriverOptions>;\n    private opened = false;\n    private openPromise: Promise<void> | null = null;\n    // Mutex to prevent concurrent database operations (critical for wa-sqlite)\n    private executionLock: Promise<void> = Promise.resolve();\n    readonly name: string;\n\n    constructor(databaseName: string, options: WaSqliteDriverOptions = {}) {\n        this.name = databaseName;\n        this.options = {\n            vfs: 'IDBBatchAtomicVFS',\n            directory: '/',\n            pageSize: 4096,\n            cacheSize: -2000,\n            wal: false,\n            synchronous: 'full',\n            ...options,\n        };\n    }\n\n    /**\n     * Execute a callback with exclusive database access.\n     * This prevents concurrent operations which can corrupt the database.\n     */\n    private async withLock<T>(fn: () => Promise<T>): Promise<T> {\n        // Chain onto the existing lock\n        const previousLock = this.executionLock;\n        let releaseLock: () => void;\n        this.executionLock = new Promise<void>((resolve) => {\n            releaseLock = resolve;\n        });\n\n        try {\n            // Wait for previous operation to complete\n            await previousLock;\n            // Execute our operation\n            return await fn();\n        } finally {\n            // Release the lock\n            releaseLock!();\n        }\n    }\n\n    async open(): Promise<void> {\n        if (this.opened) return;\n        if (this.openPromise) return this.openPromise;\n\n        this.openPromise = this._open();\n\n        try {\n            await this.openPromise;\n        } finally {\n            this.openPromise = null;\n        }\n    }\n\n    private async _open(): Promise<void> {\n        // Load wa-sqlite module (asyncify build for async VFS support)\n        const module = await this.loadWasmModule();\n\n        // Create SQLite API from module (cached - must only create once per module)\n        if (!cachedSqlite3) {\n            const { Factory } = await import('@journeyapps/wa-sqlite');\n            cachedSqlite3 = Factory(module);\n        }\n        this.sqlite3 = cachedSqlite3;\n\n        // For IDB-based VFS, the VFS name is also used as the IndexedDB database name\n        // Use a unique name based on database name to avoid conflicts\n        const vfsName = `dync_${this.options.vfs}_${this.name}`.replace(/[^a-zA-Z0-9_-]/g, '_');\n\n        // Reuse existing VFS instance or create and register a new one\n        let existingVfs = registeredVFS.get(vfsName);\n        if (!existingVfs) {\n            existingVfs = await this.createVFS(module, vfsName);\n            // Register VFS with SQLite as default (like PowerSync does)\n            this.sqlite3.vfs_register(existingVfs, true);\n            registeredVFS.set(vfsName, existingVfs);\n        }\n\n        // Build database path - for IDB VFS, this is the \"file\" path within the VFS\n        const dbPath = this.buildDatabasePath();\n\n        // Open database (VFS is registered as default)\n        this.db = await this.sqlite3.open_v2(dbPath);\n\n        // Configure database pragmas for performance and durability\n        await this.configurePragmas();\n\n        this.opened = true;\n    }\n\n    private async loadWasmModule(): Promise<any> {\n        if (!cachedModule) {\n            if (!cachedModuleFactory) {\n                // Dynamically import the asyncify build for async VFS support\n                const wasmModule = await import('@journeyapps/wa-sqlite/dist/wa-sqlite-async.mjs');\n                cachedModuleFactory = wasmModule.default;\n            }\n            // Cache the module instance - all VFS and sqlite3 APIs must share the same module\n            cachedModule = await cachedModuleFactory();\n        }\n        return cachedModule;\n    }\n\n    private async createVFS(module: any, vfsName: string): Promise<WaSqliteVFS> {\n        const vfsType = this.options.vfs;\n        let VFSClass: VFSClass;\n        let vfsOptions: any = undefined;\n\n        // Dynamically import VFS implementation\n        // Note: We cast to unknown first because the package types don't include the static create method\n        switch (vfsType) {\n            case 'IDBBatchAtomicVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/IDBBatchAtomicVFS.js');\n                VFSClass = mod.IDBBatchAtomicVFS as unknown as VFSClass;\n                // Use exclusive lock policy like PowerSync does\n                vfsOptions = { lockPolicy: 'exclusive' };\n                break;\n            }\n            case 'IDBMirrorVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/IDBMirrorVFS.js');\n                VFSClass = mod.IDBMirrorVFS as unknown as VFSClass;\n                break;\n            }\n            case 'OPFSCoopSyncVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/OPFSCoopSyncVFS.js');\n                VFSClass = mod.OPFSCoopSyncVFS as unknown as VFSClass;\n                break;\n            }\n            case 'AccessHandlePoolVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/AccessHandlePoolVFS.js');\n                VFSClass = mod.AccessHandlePoolVFS as unknown as VFSClass;\n                break;\n            }\n            default:\n                throw new Error(`Unsupported VFS type: ${vfsType}`);\n        }\n\n        return VFSClass.create(vfsName, module, vfsOptions);\n    }\n\n    private buildDatabasePath(): string {\n        const vfsType = this.options.vfs;\n\n        // For IDB-based VFS, use database name directly\n        if (vfsType === 'IDBBatchAtomicVFS' || vfsType === 'IDBMirrorVFS') {\n            return this.name;\n        }\n\n        // For OPFS-based VFS, build full path\n        const directory = this.options.directory.replace(/\\/$/, '');\n        return `${directory}/${this.name}`;\n    }\n\n    private async configurePragmas(): Promise<void> {\n        if (!this.db || !this.sqlite3) return;\n\n        // Page size can only be set on new/empty databases\n        // For IDBBatchAtomicVFS, it cannot be changed after creation\n        // Try to set it, but ignore errors if the database already exists\n        try {\n            await this.sqlite3.exec(this.db, `PRAGMA page_size = ${this.options.pageSize}`);\n        } catch {\n            // Page size already set, ignore\n        }\n\n        // Cache size for performance\n        await this.sqlite3.exec(this.db, `PRAGMA cache_size = ${this.options.cacheSize}`);\n\n        // WAL mode only for AccessHandlePoolVFS with exclusive locking\n        if (this.options.wal && this.options.vfs === 'AccessHandlePoolVFS') {\n            await this.sqlite3.exec(this.db, 'PRAGMA locking_mode = exclusive');\n            await this.sqlite3.exec(this.db, 'PRAGMA journal_mode = WAL');\n        }\n        // Note: For IDB-based VFS, we don't set journal_mode - let the VFS handle it\n    }\n\n    async close(): Promise<void> {\n        if (!this.opened || !this.db || !this.sqlite3) return;\n\n        // Wait for any pending operations to complete by acquiring the lock\n        await this.withLock(async () => {\n            // Ensure all data is flushed before closing\n            // This is critical for IDB-based VFS which batch writes\n            try {\n                await this.sqlite3!.exec(this.db!, 'PRAGMA wal_checkpoint(TRUNCATE)');\n            } catch {\n                // Ignore if WAL mode not enabled\n            }\n\n            await this.sqlite3!.close(this.db!);\n\n            // Don't close the shared VFS - it may be used by other connections\n            // The VFS will be cleaned up when all references are gone\n            this.db = null;\n            this.opened = false;\n        });\n    }\n\n    async execute(statement: string): Promise<void> {\n        await this.open();\n\n        if (!this.db || !this.sqlite3) {\n            throw new Error('Database not initialized');\n        }\n\n        await this.withLock(async () => {\n            await this.sqlite3.exec(this.db, statement);\n        });\n    }\n\n    async run(statement: string, values: unknown[] = []): Promise<SQLiteRunResult> {\n        await this.open();\n\n        if (!this.db || !this.sqlite3) {\n            throw new Error('Database not initialized');\n        }\n\n        return this.withLock(async () => {\n            // Convert values for SQLite (booleans -> integers)\n            const convertedValues = this.convertValues(values);\n\n            // Use statements() generator with proper binding\n            for await (const stmt of this.sqlite3.statements(this.db, statement)) {\n                if (stmt === null) {\n                    break;\n                }\n\n                // Reset statement before binding (critical for wa-sqlite)\n                this.sqlite3.reset(stmt);\n\n                // Bind parameters if any\n                if (convertedValues.length > 0) {\n                    this.sqlite3.bind_collection(stmt, convertedValues);\n                }\n\n                // Execute the statement\n                await this.sqlite3.step(stmt);\n            }\n\n            return {\n                changes: this.sqlite3.changes(this.db),\n                lastId: Number(this.sqlite3.last_insert_id(this.db)),\n            };\n        });\n    }\n\n    /**\n     * Convert values for SQLite compatibility.\n     * - Booleans must be converted to integers (SQLite has no boolean type)\n     */\n    private convertValues(values: unknown[]): unknown[] {\n        return values.map((value) => {\n            if (typeof value === 'boolean') {\n                return value ? 1 : 0;\n            }\n            return value;\n        });\n    }\n\n    async query(statement: string, values: unknown[] = []): Promise<SQLiteQueryResult> {\n        await this.open();\n\n        if (!this.db || !this.sqlite3) {\n            throw new Error('Database not initialized');\n        }\n\n        return this.withLock(async () => {\n            const { SQLITE_ROW } = await import('@journeyapps/wa-sqlite');\n            const allRows: unknown[][] = [];\n            let columns: string[] = [];\n\n            // Convert values for SQLite (booleans -> integers)\n            const convertedValues = this.convertValues(values);\n\n            // Use statements() generator with proper binding\n            for await (const stmt of this.sqlite3.statements(this.db, statement)) {\n                if (stmt === null) {\n                    break;\n                }\n\n                // Reset statement before binding (critical for wa-sqlite)\n                this.sqlite3.reset(stmt);\n\n                // Bind parameters if any\n                if (convertedValues.length > 0) {\n                    this.sqlite3.bind_collection(stmt, convertedValues);\n                }\n\n                // Get column names\n                if (columns.length === 0) {\n                    columns = this.sqlite3.column_names(stmt);\n                }\n\n                // Fetch all rows\n                while ((await this.sqlite3.step(stmt)) === SQLITE_ROW) {\n                    const row = this.sqlite3.row(stmt);\n                    allRows.push(row);\n                }\n            }\n\n            return { columns, values: allRows };\n        });\n    }\n\n    /**\n     * Check if the database is currently open.\n     */\n    isOpen(): boolean {\n        return this.opened;\n    }\n\n    /**\n     * Get the VFS type being used by this driver.\n     */\n    getVfsType(): WaSqliteVfsType {\n        return this.options.vfs;\n    }\n\n    /**\n     * Delete the database.\n     * This will close the database if open and remove all persisted data.\n     * For IndexedDB-based VFS, this deletes the IndexedDB database.\n     * For OPFS-based VFS, this removes the files from OPFS.\n     */\n    async delete(): Promise<void> {\n        // Close if open\n        if (this.opened) {\n            await this.close();\n        }\n\n        const vfsType = this.options.vfs;\n\n        if (vfsType === 'IDBBatchAtomicVFS' || vfsType === 'IDBMirrorVFS') {\n            // Delete IndexedDB database\n            await new Promise<void>((resolve, reject) => {\n                const request = indexedDB.deleteDatabase(this.name);\n                request.onsuccess = () => resolve();\n                request.onerror = () => reject(request.error);\n                request.onblocked = () => {\n                    console.warn(`Database deletion blocked for ${this.name}. Close all connections and try again.`);\n                };\n            });\n        } else {\n            // For OPFS-based VFS, remove the directory\n            const dbPath = this.buildDatabasePath();\n            const root = await navigator.storage.getDirectory();\n\n            try {\n                // Try to remove the file/directory\n                const pathParts = dbPath.split('/').filter(Boolean);\n                let current = root;\n\n                // Navigate to parent directory\n                for (let i = 0; i < pathParts.length - 1; i++) {\n                    current = await current.getDirectoryHandle(pathParts[i]!);\n                }\n\n                // Remove the database file\n                const filename = pathParts[pathParts.length - 1]!;\n                await current.removeEntry(filename, { recursive: true });\n\n                // Also try to remove associated journal/wal files\n                const associatedFiles = [`${filename}-journal`, `${filename}-wal`, `${filename}-shm`];\n                for (const file of associatedFiles) {\n                    try {\n                        await current.removeEntry(file, { recursive: false });\n                    } catch {\n                        // Ignore if file doesn't exist\n                    }\n                }\n            } catch (error) {\n                // Ignore if directory doesn't exist\n                if ((error as Error).name !== 'NotFoundError') {\n                    throw error;\n                }\n            }\n        }\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/storage/sqlite/drivers/WaSQLiteDriver.ts"],"sourcesContent":["import type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from '../types';\n\n/**\n * Virtual File System (VFS) options for wa-sqlite.\n * Each VFS has different trade-offs for performance, durability, and compatibility.\n *\n * @see https://github.com/rhashimoto/wa-sqlite/tree/master/src/examples#vfs-comparison\n */\nexport type WaSQLiteVfsType =\n    /**\n     * IDBBatchAtomicVFS - IndexedDB-backed storage\n     * - Works on ALL contexts (Window, Worker, SharedWorker, service worker)\n     * - Supports multiple connections\n     * - Full durability with batch atomic writes\n     * - Good general-purpose choice for maximum compatibility\n     * @recommended For apps that need to work in main thread and don't need OPFS\n     */\n    | 'IDBBatchAtomicVFS'\n    /**\n     * IDBMirrorVFS - IndexedDB with in-memory mirror\n     * - Works on ALL contexts\n     * - Supports multiple connections\n     * - Much faster than IDBBatchAtomicVFS\n     * - Database must fit in available memory\n     * @recommended For small databases where performance is critical\n     */\n    | 'IDBMirrorVFS'\n    /**\n     * OPFSCoopSyncVFS - OPFS with cooperative synchronous access\n     * - Requires Worker context\n     * - Supports multiple connections\n     * - Filesystem transparent (can import/export files)\n     * - Good balance of performance and compatibility\n     * @recommended For apps needing OPFS with multi-connection support\n     */\n    | 'OPFSCoopSyncVFS'\n    /**\n     * AccessHandlePoolVFS - OPFS-backed storage (fastest single connection)\n     * - Requires Worker context\n     * - Single connection only (no multi-tab support)\n     * - Best performance, supports WAL mode\n     * - NOT filesystem transparent\n     * @recommended For single-tab apps where performance is critical\n     */\n    | 'AccessHandlePoolVFS';\n\n/**\n * Options for configuring the WaSQLiteDriver.\n */\nexport interface WaSQLiteDriverOptions {\n    /**\n     * Virtual File System to use for storage.\n     * @default 'IDBBatchAtomicVFS'\n     */\n    vfs?: WaSQLiteVfsType;\n\n    /**\n     * Directory path for the database in OPFS VFS modes.\n     * Only used with OPFS-based VFS types.\n     * @default '/'\n     */\n    directory?: string;\n\n    /**\n     * SQLite page size in bytes.\n     * Larger pages can improve read performance for large BLOBs.\n     * Cannot be changed after database creation for IDBBatchAtomicVFS/IDBMirrorVFS.\n     * @default 4096\n     */\n    pageSize?: number;\n\n    /**\n     * SQLite cache size in pages (negative = KB, positive = pages).\n     * Larger cache improves performance but uses more memory.\n     * For IDBBatchAtomicVFS, must be large enough to hold journal for batch atomic mode.\n     * @default -2000 (2MB)\n     */\n    cacheSize?: number;\n\n    /**\n     * Enable WAL (Write-Ahead Logging) mode.\n     * Only supported with AccessHandlePoolVFS (with locking_mode=exclusive).\n     * For other VFS types, this is ignored.\n     * @default false\n     */\n    wal?: boolean;\n\n    /**\n     * Set synchronous pragma for durability vs performance trade-off.\n     * - 'full': Maximum durability (default)\n     * - 'normal': Relaxed durability, better performance (supported by IDBBatchAtomicVFS, IDBMirrorVFS, OPFSPermutedVFS)\n     * - 'off': No sync, fastest but risks data loss on crash\n     * @default 'full'\n     */\n    synchronous?: 'full' | 'normal' | 'off';\n}\n\n// Internal VFS interface for lifecycle management\ninterface WaSQLiteVFS {\n    close(): Promise<void>;\n    name: string;\n}\n\n// VFS class type with static create method\ninterface VFSClass {\n    create(name: string, module: any, options?: any): Promise<WaSQLiteVFS>;\n}\n\n// Cached module factory and instance\nlet cachedModuleFactory: (() => Promise<any>) | null = null;\nlet cachedModule: any = null;\nlet cachedSQLite3: any = null;\n// Track VFS instances by name to avoid re-registering\nconst registeredVFS = new Map<string, WaSQLiteVFS>();\n\n/**\n * SQLite driver for web browsers using wa-sqlite with IndexedDB or OPFS persistence.\n * Provides robust, persistent SQLite storage in the browser that prevents data loss.\n *\n * ## Data Safety Features\n *\n * - **IDBBatchAtomicVFS** (default): Uses IndexedDB batch atomic writes to ensure transactions\n *   are either fully committed or not at all. Multi-tab safe.\n * - **IDBMirrorVFS**: IndexedDB with in-memory mirror. Much faster, database must fit in RAM.\n * - **OPFSCoopSyncVFS**: OPFS with cooperative sync. Multi-connection, filesystem transparent.\n * - **AccessHandlePoolVFS**: Uses OPFS Access Handles for high performance. Single-tab only.\n * - Full durability by default (`PRAGMA synchronous=full`)\n * - Automatic journal mode configuration for each VFS type\n *\n * ## VFS Selection Guide\n *\n * | VFS | Best For | Multi-Tab | Speed |\n * |-----|----------|-----------|-------|\n * | IDBBatchAtomicVFS | General use, main thread | ✅ | Good |\n * | IDBMirrorVFS | Small DBs, main thread | ✅ | Fast |\n * | OPFSCoopSyncVFS | Web Workers, file export | ✅ | Good |\n * | AccessHandlePoolVFS | Single-tab performance | ❌ | Fastest |\n *\n * @example\n * ```ts\n * import { WaSQLiteDriver } from '@anfenn/dync/wa-sqlite';\n * import { SQLiteAdapter } from '@anfenn/dync';\n *\n * // Default: IDBBatchAtomicVFS (works in main thread, multi-tab safe)\n * const driver = new WaSQLiteDriver('myapp.db');\n *\n * // For OPFS (faster, requires Worker, filesystem transparent)\n * const opfsDriver = new WaSQLiteDriver('myapp.db', { vfs: 'OPFSCoopSyncVFS' });\n *\n * const adapter = new SQLiteAdapter('myapp', driver);\n * ```\n */\nexport class WaSQLiteDriver implements SQLiteDatabaseDriver {\n    readonly type = 'WaSQLiteDriver';\n    private db: number | null = null;\n    private sqlite3: any = null;\n    private readonly options: Required<WaSQLiteDriverOptions>;\n    private opened = false;\n    private openPromise: Promise<void> | null = null;\n    // Mutex to prevent concurrent database operations (critical for wa-sqlite)\n    private executionLock: Promise<void> = Promise.resolve();\n    readonly name: string;\n\n    constructor(databaseName: string, options: WaSQLiteDriverOptions = {}) {\n        this.name = databaseName;\n        this.options = {\n            vfs: 'IDBBatchAtomicVFS',\n            directory: '/',\n            pageSize: 4096,\n            cacheSize: -2000,\n            wal: false,\n            synchronous: 'full',\n            ...options,\n        };\n    }\n\n    /**\n     * Execute a callback with exclusive database access.\n     * This prevents concurrent operations which can corrupt the database.\n     */\n    private async withLock<T>(fn: () => Promise<T>): Promise<T> {\n        // Chain onto the existing lock\n        const previousLock = this.executionLock;\n        let releaseLock: () => void;\n        this.executionLock = new Promise<void>((resolve) => {\n            releaseLock = resolve;\n        });\n\n        try {\n            // Wait for previous operation to complete\n            await previousLock;\n            // Execute our operation\n            return await fn();\n        } finally {\n            // Release the lock\n            releaseLock!();\n        }\n    }\n\n    async open(): Promise<void> {\n        if (this.opened) return;\n        if (this.openPromise) return this.openPromise;\n\n        this.openPromise = this._open();\n\n        try {\n            await this.openPromise;\n        } finally {\n            this.openPromise = null;\n        }\n    }\n\n    private async _open(): Promise<void> {\n        // Load wa-sqlite module (asyncify build for async VFS support)\n        const module = await this.loadWasmModule();\n\n        // Create SQLite API from module (cached - must only create once per module)\n        if (!cachedSQLite3) {\n            const { Factory } = await import('@journeyapps/wa-sqlite');\n            cachedSQLite3 = Factory(module);\n        }\n        this.sqlite3 = cachedSQLite3;\n\n        // For IDB-based VFS, the VFS name is also used as the IndexedDB database name\n        // Use a unique name based on database name to avoid conflicts\n        const vfsName = `dync_${this.options.vfs}_${this.name}`.replace(/[^a-zA-Z0-9_-]/g, '_');\n\n        // Reuse existing VFS instance or create and register a new one\n        let existingVfs = registeredVFS.get(vfsName);\n        if (!existingVfs) {\n            existingVfs = await this.createVFS(module, vfsName);\n            // Register VFS with SQLite as default (like PowerSync does)\n            this.sqlite3.vfs_register(existingVfs, true);\n            registeredVFS.set(vfsName, existingVfs);\n        }\n\n        // Build database path - for IDB VFS, this is the \"file\" path within the VFS\n        const dbPath = this.buildDatabasePath();\n\n        // Open database (VFS is registered as default)\n        this.db = await this.sqlite3.open_v2(dbPath);\n\n        // Configure database pragmas for performance and durability\n        await this.configurePragmas();\n\n        this.opened = true;\n    }\n\n    private async loadWasmModule(): Promise<any> {\n        if (!cachedModule) {\n            if (!cachedModuleFactory) {\n                // Dynamically import the asyncify build for async VFS support\n                const wasmModule = await import('@journeyapps/wa-sqlite/dist/wa-sqlite-async.mjs');\n                cachedModuleFactory = wasmModule.default;\n            }\n            // Cache the module instance - all VFS and sqlite3 APIs must share the same module\n            cachedModule = await cachedModuleFactory();\n        }\n        return cachedModule;\n    }\n\n    private async createVFS(module: any, vfsName: string): Promise<WaSQLiteVFS> {\n        const vfsType = this.options.vfs;\n        let VFSClass: VFSClass;\n        let vfsOptions: any = undefined;\n\n        // Dynamically import VFS implementation\n        // Note: We cast to unknown first because the package types don't include the static create method\n        switch (vfsType) {\n            case 'IDBBatchAtomicVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/IDBBatchAtomicVFS.js');\n                VFSClass = mod.IDBBatchAtomicVFS as unknown as VFSClass;\n                // Use exclusive lock policy like PowerSync does\n                vfsOptions = { lockPolicy: 'exclusive' };\n                break;\n            }\n            case 'IDBMirrorVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/IDBMirrorVFS.js');\n                VFSClass = mod.IDBMirrorVFS as unknown as VFSClass;\n                break;\n            }\n            case 'OPFSCoopSyncVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/OPFSCoopSyncVFS.js');\n                VFSClass = mod.OPFSCoopSyncVFS as unknown as VFSClass;\n                break;\n            }\n            case 'AccessHandlePoolVFS': {\n                const mod = await import('@journeyapps/wa-sqlite/src/examples/AccessHandlePoolVFS.js');\n                VFSClass = mod.AccessHandlePoolVFS as unknown as VFSClass;\n                break;\n            }\n            default:\n                throw new Error(`Unsupported VFS type: ${vfsType}`);\n        }\n\n        return VFSClass.create(vfsName, module, vfsOptions);\n    }\n\n    private buildDatabasePath(): string {\n        const vfsType = this.options.vfs;\n\n        // For IDB-based VFS, use database name directly\n        if (vfsType === 'IDBBatchAtomicVFS' || vfsType === 'IDBMirrorVFS') {\n            return this.name;\n        }\n\n        // For OPFS-based VFS, build full path\n        const directory = this.options.directory.replace(/\\/$/, '');\n        return `${directory}/${this.name}`;\n    }\n\n    private async configurePragmas(): Promise<void> {\n        if (!this.db || !this.sqlite3) return;\n\n        // Page size can only be set on new/empty databases\n        // For IDBBatchAtomicVFS, it cannot be changed after creation\n        // Try to set it, but ignore errors if the database already exists\n        try {\n            await this.sqlite3.exec(this.db, `PRAGMA page_size = ${this.options.pageSize}`);\n        } catch {\n            // Page size already set, ignore\n        }\n\n        // Cache size for performance\n        await this.sqlite3.exec(this.db, `PRAGMA cache_size = ${this.options.cacheSize}`);\n\n        // WAL mode only for AccessHandlePoolVFS with exclusive locking\n        if (this.options.wal && this.options.vfs === 'AccessHandlePoolVFS') {\n            await this.sqlite3.exec(this.db, 'PRAGMA locking_mode = exclusive');\n            await this.sqlite3.exec(this.db, 'PRAGMA journal_mode = WAL');\n        }\n        // Note: For IDB-based VFS, we don't set journal_mode - let the VFS handle it\n    }\n\n    async close(): Promise<void> {\n        if (!this.opened || !this.db || !this.sqlite3) return;\n\n        // Wait for any pending operations to complete by acquiring the lock\n        await this.withLock(async () => {\n            // Ensure all data is flushed before closing\n            // This is critical for IDB-based VFS which batch writes\n            try {\n                await this.sqlite3!.exec(this.db!, 'PRAGMA wal_checkpoint(TRUNCATE)');\n            } catch {\n                // Ignore if WAL mode not enabled\n            }\n\n            await this.sqlite3!.close(this.db!);\n\n            // Don't close the shared VFS - it may be used by other connections\n            // The VFS will be cleaned up when all references are gone\n            this.db = null;\n            this.opened = false;\n        });\n    }\n\n    async execute(statement: string): Promise<void> {\n        await this.open();\n\n        if (!this.db || !this.sqlite3) {\n            throw new Error('Database not initialized');\n        }\n\n        await this.withLock(async () => {\n            await this.sqlite3.exec(this.db, statement);\n        });\n    }\n\n    async run(statement: string, values: unknown[] = []): Promise<SQLiteRunResult> {\n        await this.open();\n\n        if (!this.db || !this.sqlite3) {\n            throw new Error('Database not initialized');\n        }\n\n        return this.withLock(async () => {\n            // Convert values for SQLite (booleans -> integers)\n            const convertedValues = this.convertValues(values);\n\n            // Use statements() generator with proper binding\n            for await (const stmt of this.sqlite3.statements(this.db, statement)) {\n                if (stmt === null) {\n                    break;\n                }\n\n                // Reset statement before binding (critical for wa-sqlite)\n                this.sqlite3.reset(stmt);\n\n                // Bind parameters if any\n                if (convertedValues.length > 0) {\n                    this.sqlite3.bind_collection(stmt, convertedValues);\n                }\n\n                // Execute the statement\n                await this.sqlite3.step(stmt);\n            }\n\n            return {\n                changes: this.sqlite3.changes(this.db),\n                lastId: Number(this.sqlite3.last_insert_id(this.db)),\n            };\n        });\n    }\n\n    /**\n     * Convert values for SQLite compatibility.\n     * - Booleans must be converted to integers (SQLite has no boolean type)\n     */\n    private convertValues(values: unknown[]): unknown[] {\n        return values.map((value) => {\n            if (typeof value === 'boolean') {\n                return value ? 1 : 0;\n            }\n            return value;\n        });\n    }\n\n    async query(statement: string, values: unknown[] = []): Promise<SQLiteQueryResult> {\n        await this.open();\n\n        if (!this.db || !this.sqlite3) {\n            throw new Error('Database not initialized');\n        }\n\n        return this.withLock(async () => {\n            const { SQLITE_ROW } = await import('@journeyapps/wa-sqlite');\n            const allRows: unknown[][] = [];\n            let columns: string[] = [];\n\n            // Convert values for SQLite (booleans -> integers)\n            const convertedValues = this.convertValues(values);\n\n            // Use statements() generator with proper binding\n            for await (const stmt of this.sqlite3.statements(this.db, statement)) {\n                if (stmt === null) {\n                    break;\n                }\n\n                // Reset statement before binding (critical for wa-sqlite)\n                this.sqlite3.reset(stmt);\n\n                // Bind parameters if any\n                if (convertedValues.length > 0) {\n                    this.sqlite3.bind_collection(stmt, convertedValues);\n                }\n\n                // Get column names\n                if (columns.length === 0) {\n                    columns = this.sqlite3.column_names(stmt);\n                }\n\n                // Fetch all rows\n                while ((await this.sqlite3.step(stmt)) === SQLITE_ROW) {\n                    const row = this.sqlite3.row(stmt);\n                    allRows.push(row);\n                }\n            }\n\n            return { columns, values: allRows };\n        });\n    }\n\n    /**\n     * Check if the database is currently open.\n     */\n    isOpen(): boolean {\n        return this.opened;\n    }\n\n    /**\n     * Get the VFS type being used by this driver.\n     */\n    getVfsType(): WaSQLiteVfsType {\n        return this.options.vfs;\n    }\n\n    /**\n     * Delete the database.\n     * This will close the database if open and remove all persisted data.\n     * For IndexedDB-based VFS, this deletes the IndexedDB database.\n     * For OPFS-based VFS, this removes the files from OPFS.\n     */\n    async delete(): Promise<void> {\n        // Close if open\n        if (this.opened) {\n            await this.close();\n        }\n\n        const vfsType = this.options.vfs;\n\n        if (vfsType === 'IDBBatchAtomicVFS' || vfsType === 'IDBMirrorVFS') {\n            // Delete IndexedDB database\n            await new Promise<void>((resolve, reject) => {\n                const request = indexedDB.deleteDatabase(this.name);\n                request.onsuccess = () => resolve();\n                request.onerror = () => reject(request.error);\n                request.onblocked = () => {\n                    console.warn(`Database deletion blocked for ${this.name}. Close all connections and try again.`);\n                };\n            });\n        } else {\n            // For OPFS-based VFS, remove the directory\n            const dbPath = this.buildDatabasePath();\n            const root = await navigator.storage.getDirectory();\n\n            try {\n                // Try to remove the file/directory\n                const pathParts = dbPath.split('/').filter(Boolean);\n                let current = root;\n\n                // Navigate to parent directory\n                for (let i = 0; i < pathParts.length - 1; i++) {\n                    current = await current.getDirectoryHandle(pathParts[i]!);\n                }\n\n                // Remove the database file\n                const filename = pathParts[pathParts.length - 1]!;\n                await current.removeEntry(filename, { recursive: true });\n\n                // Also try to remove associated journal/wal files\n                const associatedFiles = [`${filename}-journal`, `${filename}-wal`, `${filename}-shm`];\n                for (const file of associatedFiles) {\n                    try {\n                        await current.removeEntry(file, { recursive: false });\n                    } catch {\n                        // Ignore if file doesn't exist\n                    }\n                }\n            } catch (error) {\n                // Ignore if directory doesn't exist\n                if ((error as Error).name !== 'NotFoundError') {\n                    throw error;\n                }\n            }\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anfenn/dync",
-  "version": "1.0.28",
+  "version": "1.0.31",
   "private": false,
   "description": "Write once, run IndexedDB & SQLite with sync anywhere - React, React Native, Expo, Capacitor, Electron & Node.js",
   "keywords": [
@@ -132,8 +132,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "pnpm run format && pnpm run lint && pnpm exec tsc --noEmit && tsup",
-    "build:all": "pnpm run build && pnpm --filter react-capacitor build",
+    "build": "pnpm format && pnpm lint && pnpm exec tsc --noEmit && tsup",
+    "build:all": "pnpm build && pnpm --filter react-capacitor build",
     "dev": "tsup --watch",
     "lint": "eslint . --fix \"src/**/*.{js,jsx,ts,tsx,json}\"",
     "format": "prettier --write \"**/*.{ts,tsx,md}\"",
@@ -142,7 +142,9 @@
     "test:all": "pnpm --filter tests test:all",
     "test:ci": "pnpm --filter tests test:ci",
     "test:browser:full": "pnpm --filter tests test:browser:full",
-    "reinstall": "find . -name node_modules -type d -prune -exec rm -rf {} + && pnpm install"
+    "reinstall": "find . -name node_modules -type d -prune -exec rm -rf {} + && pnpm install",
+    "push": "bash -c '[ -n \"$1\" ] && git add . && git commit -m \"$1\" && git push' --",
+    "release": "bash -c '[ -n \"$1\" ] || { echo \"Usage: pnpm release <commit-message>\"; exit 1; } && pnpm build:all && pnpm test:all && pnpm test:browser:full && git add . && git commit -m \"$1\" && npm version patch && git push && npm login && npm publish' --"
   },
   "devDependencies": {
     "@capacitor-community/sqlite": "7.0.2",

package/src/core/tableEnhancers.ts

@@ -6,7 +6,7 @@ import type { WithTransaction } from './types';
 export type EmitMutation = (event: MutationEvent) => void;
 
 /**
- * Wraps a table with mutation emission for reactive updates.
+ * Wraps a table with mutation emission for reactive updates and auto-generates _localId.
  * This allows useLiveQuery to work with any table.
  */
 export function wrapWithMutationEmitter<T>(table: StorageTable<T>, tableName: string, emitMutation: EmitMutation): void {
@@ -21,13 +21,15 @@ export function wrapWithMutationEmitter<T>(table: StorageTable<T>, tableName: st
     const rawClear = table.raw.clear;
 
     table.add = async (item: AddItem<T>) => {
-        const result = await rawAdd(item as T);
+        const itemWithLocalId = { ...item, _localId: (item as any)._localId || createLocalId() } as T;
+        const result = await rawAdd(itemWithLocalId);
         emitMutation({ type: 'add', tableName, keys: [result] });
         return result;
     };
 
     table.put = async (item: T) => {
-        const result = await rawPut(item);
+        const itemWithLocalId = { ...item, _localId: (item as any)._localId || createLocalId() } as T;
+        const result = await rawPut(itemWithLocalId);
         emitMutation({ type: 'update', tableName, keys: [result] });
         return result;
     };
@@ -46,7 +48,11 @@ export function wrapWithMutationEmitter<T>(table: StorageTable<T>, tableName: st
     };
 
     table.bulkAdd = async (items: AddItem<T>[]) => {
-        const result = await rawBulkAdd(items as T[]);
+        const itemsWithLocalIds = items.map((item) => ({
+            ...item,
+            _localId: (item as any)._localId || createLocalId(),
+        })) as T[];
+        const result = await rawBulkAdd(itemsWithLocalIds);
         if (items.length > 0) {
             emitMutation({ type: 'add', tableName });
         }
@@ -54,7 +60,11 @@ export function wrapWithMutationEmitter<T>(table: StorageTable<T>, tableName: st
     };
 
     table.bulkPut = async (items: T[]) => {
-        const result = await rawBulkPut(items);
+        const itemsWithLocalIds = items.map((item) => ({
+            ...item,
+            _localId: (item as any)._localId || createLocalId(),
+        })) as T[];
+        const result = await rawBulkPut(itemsWithLocalIds);
         if (items.length > 0) {
             emitMutation({ type: 'update', tableName });
         }

package/src/index.native.ts

@@ -2,7 +2,7 @@ export * from './index.shared';
 export { MemoryAdapter } from './storage/memory';
 export { SQLiteAdapter } from './storage/sqlite';
 export { MemoryQueryContext } from './storage/memory';
-export { SqliteQueryContext } from './storage/sqlite';
+export { SQLiteQueryContext } from './storage/sqlite';
 export type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from './storage/sqlite/types';
 export type { StorageAdapter } from './storage/types';
 export { SyncAction } from './types';

package/src/index.shared.ts

@@ -28,7 +28,7 @@ import { startFirstLoad as runFirstLoad, startFirstLoadBatch as runFirstLoadBatc
 import type { FirstLoadProgressCallback, VisibilitySubscription } from './types';
 import { StateManager, DYNC_STATE_TABLE, type StateHelpers } from './core/StateManager';
 import type { MemoryQueryContext } from './storage/memory/MemoryQueryContext';
-import type { SqliteQueryContext } from './storage/sqlite/SqliteQueryContext';
+import type { SQLiteQueryContext } from './storage/sqlite/SQLiteQueryContext';
 import type { DexieQueryContext } from './storage/dexie/DexieQueryContext';
 
 const DEFAULT_SYNC_INTERVAL_MILLIS = 2000;
@@ -85,15 +85,17 @@ class DyncBase<_TStoreMap extends Record<string, any> = Record<string, any>> {
     constructor(config: DyncOptions<_TStoreMap>) {
         const { databaseName, storageAdapter, sync: syncConfig, options } = config;
 
-        // Detect mode based on whether sync config has batch sync shape
-        const isBatchMode = typeof (syncConfig as BatchSync).push === 'function' && typeof (syncConfig as BatchSync).pull === 'function';
+        if (syncConfig) {
+            // Detect mode based on whether sync config has batch sync shape
+            const isBatchMode = typeof syncConfig.push === 'function' && typeof syncConfig.pull === 'function';
 
-        if (isBatchMode) {
-            this.batchSync = syncConfig as BatchSync;
-            this.syncedTables = new Set(this.batchSync.syncTables);
-        } else {
-            this.syncApis = syncConfig as Record<string, ApiFunctions>;
-            this.syncedTables = new Set(Object.keys(this.syncApis));
+            if (isBatchMode) {
+                this.batchSync = syncConfig as BatchSync;
+                this.syncedTables = new Set(this.batchSync.syncTables);
+            } else {
+                this.syncApis = syncConfig as Record<string, ApiFunctions>;
+                this.syncedTables = new Set(Object.keys(this.syncApis));
+            }
         }
 
         this.adapter = storageAdapter;
@@ -158,6 +160,9 @@ class DyncBase<_TStoreMap extends Record<string, any> = Record<string, any>> {
                             // Auto-inject sync fields for sync tables
                             // Note: updated_at is indexed to support user queries like orderBy('updated_at')
                             fullSchema[tableName] = `${LOCAL_PK}, &${SERVER_PK}, ${tableSchema}, ${UPDATED_AT}`;
+                        } else {
+                            // Auto-inject _localId as primary key for non-sync tables
+                            fullSchema[tableName] = `${LOCAL_PK}, ${tableSchema}`;
                         }
 
                         self.logger.debug(
@@ -167,6 +172,9 @@ class DyncBase<_TStoreMap extends Record<string, any> = Record<string, any>> {
                         if (isSyncTable) {
                             // Auto-inject sync columns for structured schemas
                             fullSchema[tableName] = self.injectSyncColumns(tableSchema);
+                        } else {
+                            // Auto-inject _localId column for non-sync structured schemas
+                            fullSchema[tableName] = self.injectLocalIdColumn(tableSchema);
                         }
 
                         const schemaColumns = Object.keys((fullSchema[tableName] as SQLiteTableDefinition).columns ?? {}).join(', ');
@@ -204,11 +212,11 @@ class DyncBase<_TStoreMap extends Record<string, any> = Record<string, any>> {
                 const sqliteOptions = (schemaOptions.sqlite ??= {});
                 const migrations = (sqliteOptions.migrations ??= {});
                 const configurator: SQLiteVersionConfigurator = {
-                    upgrade(handler) {
-                        migrations.upgrade = handler;
+                    up(handler) {
+                        migrations.up = handler;
                     },
-                    downgrade(handler) {
-                        migrations.downgrade = handler;
+                    down(handler) {
+                        migrations.down = handler;
                     },
                 };
                 configure(configurator);
@@ -260,7 +268,7 @@ class DyncBase<_TStoreMap extends Record<string, any> = Record<string, any>> {
         this.syncEnhancedTables.clear();
     }
 
-    async query<R>(callback: (ctx: DexieQueryContext | SqliteQueryContext | MemoryQueryContext) => Promise<R>): Promise<R> {
+    async query<R>(callback: (ctx: DexieQueryContext | SQLiteQueryContext | MemoryQueryContext) => Promise<R>): Promise<R> {
         return this.adapter.query(callback as any);
     }
 
@@ -350,6 +358,26 @@ class DyncBase<_TStoreMap extends Record<string, any> = Record<string, any>> {
         };
     }
 
+    private injectLocalIdColumn(schema: SQLiteTableDefinition): SQLiteTableDefinition {
+        const columns = schema.columns ?? {};
+
+        // Validate user hasn't defined reserved _localId column
+        if (columns[LOCAL_PK]) {
+            throw new Error(`Column '${LOCAL_PK}' is auto-injected and cannot be defined manually.`);
+        }
+
+        // Inject _localId column as primary key
+        const injectedColumns: Record<string, any> = {
+            ...columns,
+            [LOCAL_PK]: { type: 'TEXT' },
+        };
+
+        return {
+            ...schema,
+            columns: injectedColumns,
+        };
+    }
+
     private enhanceSyncTable<T>(table: StorageTable<T & SyncedRecord>, tableName: string): void {
         enhanceSyncTable({
             table,

package/src/index.ts

@@ -2,7 +2,7 @@ export * from './index.shared';
 export { MemoryAdapter } from './storage/memory';
 export { SQLiteAdapter } from './storage/sqlite';
 export { MemoryQueryContext } from './storage/memory';
-export { SqliteQueryContext } from './storage/sqlite';
+export { SQLiteQueryContext } from './storage/sqlite';
 export type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from './storage/sqlite/types';
 export type { StorageAdapter } from './storage/types';
 export { SyncAction } from './types';

package/src/node.ts

@@ -1,4 +1,4 @@
 // Node.js SQLite Driver using better-sqlite3
 // Works in Node.js apps and Electron main process
-export { BetterSqlite3Driver, type BetterSqlite3DriverOptions } from './storage/sqlite/drivers/BetterSqlite3Driver';
+export { BetterSQLite3Driver, type BetterSQLite3DriverOptions } from './storage/sqlite/drivers/BetterSQLite3Driver';
 export type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from './storage/sqlite/types';

package/src/storage/sqlite/SQLiteAdapter.ts

@@ -7,14 +7,14 @@ import type {
     SQLiteDefaultValue,
     SQLiteForeignKeyReference,
 } from './schema';
-import type { StorageSchemaDefinitionOptions, SQLiteMigrationContext, SQLiteMigrationDirection, SQLiteMigrationHandler } from './types';
+import type { StorageSchemaDefinitionOptions, SQLiteMigrationContext, SQLiteMigrationHandler } from './types';
 import type { SQLiteDatabaseDriver, SQLiteRunResult, SQLiteQueryResult } from './types';
 import { LOCAL_PK } from '../../types';
 import type { SQLiteAdapterOptions, SQLiteTableSchemaMetadata, SQLiteColumnSchema } from './types';
 import { DYNC_STATE_TABLE } from '../../core/StateManager';
 import { SQLITE_SCHEMA_VERSION_STATE_KEY, quoteIdentifier } from './helpers';
 import { SQLiteTable } from './SQLiteTable';
-import { SqliteQueryContext } from './SqliteQueryContext';
+import { SQLiteQueryContext } from './SQLiteQueryContext';
 
 export class SQLiteAdapter implements StorageAdapter {
     readonly type = 'SQLiteAdapter';
@@ -199,12 +199,12 @@ export class SQLiteAdapter implements StorageAdapter {
         return driver.run(statement, params);
     }
 
-    async query<R>(callback: (ctx: SqliteQueryContext) => Promise<R>): Promise<R>;
+    async query<R>(callback: (ctx: SQLiteQueryContext) => Promise<R>): Promise<R>;
     async query(statement: string, values?: any[]): Promise<SQLiteQueryResult>;
-    async query<R>(arg1: string | ((ctx: SqliteQueryContext) => Promise<R>), arg2?: any[]): Promise<R | SQLiteQueryResult> {
+    async query<R>(arg1: string | ((ctx: SQLiteQueryContext) => Promise<R>), arg2?: any[]): Promise<R | SQLiteQueryResult> {
         if (typeof arg1 === 'function') {
             const driver = await this.getDriver();
-            return arg1(new SqliteQueryContext(driver, this));
+            return arg1(new SQLiteQueryContext(driver, this));
         }
         const statement = arg1;
         const values = arg2;
@@ -336,27 +336,24 @@ export class SQLiteAdapter implements StorageAdapter {
 
         if (currentVersion < targetVersion) {
             for (let version = currentVersion + 1; version <= targetVersion; version += 1) {
-                await this.runMigrationStep(version, 'upgrade', version - 1, version);
+                await this.runMigrationStep(version, 'up');
                 await this.setStoredSchemaVersion(version);
             }
             return;
         }
 
         for (let version = currentVersion; version > targetVersion; version -= 1) {
-            await this.runMigrationStep(version, 'downgrade', version, version - 1);
+            await this.runMigrationStep(version, 'down');
             await this.setStoredSchemaVersion(version - 1);
         }
     }
 
-    private async runMigrationStep(version: number, direction: SQLiteMigrationDirection, fromVersion: number, toVersion: number): Promise<void> {
+    private async runMigrationStep(version: number, direction: 'up' | 'down'): Promise<void> {
         const handler = this.getMigrationHandler(version, direction);
         if (!handler) {
             return;
         }
         const context: SQLiteMigrationContext = {
-            direction,
-            fromVersion,
-            toVersion,
             execute: (statement: string) => this.internalExecute(statement),
             run: (statement: string, values?: any[]) => this.internalRun(statement, values),
             query: (statement: string, values?: any[]) => this.internalQuery(statement, values),
@@ -364,13 +361,13 @@ export class SQLiteAdapter implements StorageAdapter {
         await handler(context);
     }
 
-    private getMigrationHandler(version: number, direction: SQLiteMigrationDirection): SQLiteMigrationHandler | undefined {
+    private getMigrationHandler(version: number, direction: 'up' | 'down'): SQLiteMigrationHandler | undefined {
         const options = this.versionOptions.get(version);
         const migrations = options?.sqlite?.migrations;
         if (!migrations) {
             return undefined;
         }
-        return direction === 'upgrade' ? migrations.upgrade : migrations.downgrade;
+        return direction === 'up' ? migrations.up : migrations.down;
     }
 
     private async applySchema(): Promise<void> {

package/src/storage/sqlite/{SqliteQueryContext.ts → SQLiteQueryContext.ts}

@@ -2,7 +2,7 @@ import type { StorageTable, StorageTransactionContext, TransactionMode } from '.
 import type { SQLiteDatabaseDriver, SQLiteRunResult } from './types';
 import { SQLiteAdapter } from './SQLiteAdapter';
 
-export class SqliteQueryContext {
+export class SQLiteQueryContext {
     constructor(
         private readonly driver: SQLiteDatabaseDriver,
         private readonly adapter: SQLiteAdapter,

package/src/storage/sqlite/drivers/{BetterSqlite3Driver.ts → BetterSQLite3Driver.ts}

@@ -1,9 +1,9 @@
 import type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from '../types';
 
 /**
- * Options for configuring the BetterSqlite3Driver.
+ * Options for configuring the BetterSQLite3Driver.
  */
-export interface BetterSqlite3DriverOptions {
+export interface BetterSQLite3DriverOptions {
     /**
      * Open the database in readonly mode.
      * @default false
@@ -42,21 +42,21 @@ export interface BetterSqlite3DriverOptions {
  *
  * @example
  * ```ts
- * import { BetterSqlite3Driver } from '@anfenn/dync/node';
+ * import { BetterSQLite3Driver } from '@anfenn/dync/node';
  * import { SQLiteAdapter } from '@anfenn/dync';
  *
- * const driver = new BetterSqlite3Driver('myapp.db', { wal: true });
+ * const driver = new BetterSQLite3Driver('myapp.db', { wal: true });
  * const adapter = new SQLiteAdapter('myapp', driver);
  * ```
  */
-export class BetterSqlite3Driver implements SQLiteDatabaseDriver {
-    readonly type = 'BetterSqlite3Driver';
+export class BetterSQLite3Driver implements SQLiteDatabaseDriver {
+    readonly type = 'BetterSQLite3Driver';
     private db: import('better-sqlite3').Database | null = null;
-    private readonly options: BetterSqlite3DriverOptions;
+    private readonly options: BetterSQLite3DriverOptions;
     private opened = false;
     readonly name: string;
 
-    constructor(databasePath: string, options: BetterSqlite3DriverOptions = {}) {
+    constructor(databasePath: string, options: BetterSQLite3DriverOptions = {}) {
         this.name = databasePath;
         this.options = {
             wal: true,

package/src/storage/sqlite/drivers/CapacitorSQLiteDriver.ts

@@ -4,7 +4,7 @@ import type { SQLiteDatabaseDriver, SQLiteRunResult, SQLiteQueryResult } from '.
 // Lazily loaded module cache to avoid top-level imports that break web bundlers
 let sqliteModuleCache: typeof import('@capacitor-community/sqlite') | null = null;
 
-async function getSqliteModule(): Promise<typeof import('@capacitor-community/sqlite')> {
+async function getSQLiteModule(): Promise<typeof import('@capacitor-community/sqlite')> {
     if (!sqliteModuleCache) {
         sqliteModuleCache = await import('@capacitor-community/sqlite');
     }
@@ -35,7 +35,7 @@ export class CapacitorSQLiteDriver implements SQLiteDatabaseDriver {
 
     private async getConnectionFactory(): Promise<SQLiteConnection> {
         if (!this.connectionFactory) {
-            const { CapacitorSQLite, SQLiteConnection } = await getSqliteModule();
+            const { CapacitorSQLite, SQLiteConnection } = await getSQLiteModule();
             this.connectionFactory = new SQLiteConnection(CapacitorSQLite);
         }
         return this.connectionFactory;