local-lite 0.0.5 → 0.0.7

package/dist/adapters/local/better-sqlite3.d.ts

@@ -16,9 +16,13 @@ export interface BetterSqliteDatabase {
  * Adapter for better-sqlite3 in Node.js, Electron, Next.js, and server environments.
  */
 export declare class BetterSQLite3Adapter implements LocalDBAdapter {
+    readonly supportsSqlPushdown = true;
     private db;
-    private queue;
+    private txQueue;
+    private statementCache;
+    private readonly maxCacheSize;
     constructor(betterSqliteInstance: any);
+    private getStatement;
     execute(query: string, params?: any[]): Promise<any[]>;
     transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
     close(): void;

package/dist/adapters/local/better-sqlite3.js

@@ -5,35 +5,56 @@ exports.BetterSQLite3Adapter = void 0;
  * Adapter for better-sqlite3 in Node.js, Electron, Next.js, and server environments.
  */
 class BetterSQLite3Adapter {
+    supportsSqlPushdown = true;
     db;
-    queue = Promise.resolve();
+    txQueue = Promise.resolve();
+    statementCache = new Map();
+    maxCacheSize = 100;
     constructor(betterSqliteInstance) {
         this.db = betterSqliteInstance;
     }
+    getStatement(sql) {
+        let stmt = this.statementCache.get(sql);
+        if (!stmt) {
+            if (this.statementCache.size >= this.maxCacheSize) {
+                const oldestKey = this.statementCache.keys().next().value;
+                if (oldestKey)
+                    this.statementCache.delete(oldestKey);
+            }
+            stmt = this.db.prepare(sql);
+            this.statementCache.set(sql, stmt);
+        }
+        return stmt;
+    }
     async execute(query, params = []) {
+        const trimmed = query.trim();
+        const isReader = /^SELECT|^PRAGMA/i.test(trimmed);
+        // Fast-path: Readers execute directly and synchronously without artificial promise queue delay
+        if (isReader) {
+            const stmt = this.getStatement(trimmed);
+            return stmt.all(...params);
+        }
         const run = async () => {
-            const trimmed = query.trim();
-            const stmt = this.db.prepare(trimmed);
-            // If query returns rows (SELECT, PRAGMA) or is marked as reader
-            if (stmt.reader || /^SELECT|^PRAGMA/i.test(trimmed)) {
+            const stmt = this.getStatement(trimmed);
+            if (stmt.reader) {
                 return stmt.all(...params);
             }
             const info = stmt.run(...params);
             return [info];
         };
-        const next = this.queue.then(run, run);
-        this.queue = next.catch(() => { });
+        const next = this.txQueue.then(run, run);
+        this.txQueue = next.catch(() => { });
         return await next;
     }
     async transaction(action) {
         const run = async () => {
-            // Explicit transaction control compatible with async actions
-            this.db.prepare('BEGIN IMMEDIATE').run();
+            // Explicit transaction control reusing prepared statements
+            this.getStatement('BEGIN IMMEDIATE').run();
             try {
                 const txWrapper = {
                     execute: async (q, p = []) => {
                         const trimmed = q.trim();
-                        const stmt = this.db.prepare(trimmed);
+                        const stmt = this.getStatement(trimmed);
                         if (stmt.reader || /^SELECT|^PRAGMA/i.test(trimmed)) {
                             return stmt.all(...p);
                         }
@@ -41,12 +62,12 @@ class BetterSQLite3Adapter {
                     },
                 };
                 const result = await action(txWrapper);
-                this.db.prepare('COMMIT').run();
+                this.getStatement('COMMIT').run();
                 return result;
             }
             catch (err) {
                 try {
-                    this.db.prepare('ROLLBACK').run();
+                    this.getStatement('ROLLBACK').run();
                 }
                 catch {
                     // Ignore secondary rollback error if connection closed
@@ -54,8 +75,8 @@ class BetterSQLite3Adapter {
                 throw err;
             }
         };
-        const next = this.queue.then(run, run);
-        this.queue = next.catch(() => { });
+        const next = this.txQueue.then(run, run);
+        this.txQueue = next.catch(() => { });
         return await next;
     }
     close() {

package/dist/adapters/local/expo-sqlite.d.ts

@@ -1,12 +1,21 @@
 import { LocalDBAdapter, LocalTransaction } from './index.js';
+export interface ExpoDatabase {
+    getAllAsync(query: string, params: any[]): Promise<any[]>;
+    runAsync?(query: string, params: any[]): Promise<any>;
+    execAsync?(query: string): Promise<void>;
+    withTransactionAsync(action: () => Promise<void>): Promise<void>;
+    closeAsync?(): Promise<void>;
+    closeSync?(): void;
+}
 export declare class ExpoSQLiteAdapter implements LocalDBAdapter {
+    readonly supportsSqlPushdown = true;
     private db;
-    private queue;
+    private writeQueue;
     constructor(expoDbInstance: any);
     execute(query: string, params?: any[]): Promise<any[]>;
     transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
     /**
-     * Waits for pending queries/transactions to finish and closes the underlying SQLite database connection.
+     * Waits for pending writes/transactions to finish and closes the underlying SQLite connection.
      */
     close(): Promise<void>;
 }

package/dist/adapters/local/expo-sqlite.js

@@ -1,26 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExpoSQLiteAdapter = void 0;
+// Pre-compiled RegExp hoisted to module scope — 0 regex allocations per query
+const READ_QUERY_REGEX = /^(?:SELECT|PRAGMA)\b/i;
 class ExpoSQLiteAdapter {
+    supportsSqlPushdown = true;
     db;
-    queue = Promise.resolve();
+    writeQueue = Promise.resolve();
     constructor(expoDbInstance) {
         this.db = expoDbInstance;
     }
     async execute(query, params = []) {
+        const trimmed = query.trim();
+        const isRead = READ_QUERY_REGEX.test(trimmed);
+        // Fast-path: reads bypass the write queue entirely for zero-latency reactive queries
+        if (isRead) {
+            return this.db.getAllAsync(trimmed, params);
+        }
         const run = async () => {
-            const trimmed = query.trim();
-            const isSelect = /^SELECT\b/i.test(trimmed) || /^PRAGMA\b/i.test(trimmed);
-            // Parameterless DDL/write statements can bypass statement preparation
-            // to avoid NativeStatement SharedObject allocation race conditions on Android
-            if (!isSelect && (!params || params.length === 0) && typeof this.db.execAsync === 'function') {
-                await this.db.execAsync(query);
+            // Parameterless DDL statements bypass statement preparation
+            if ((!params || params.length === 0) && typeof this.db.execAsync === 'function') {
+                await this.db.execAsync(trimmed);
                 return [];
             }
-            return await this.db.getAllAsync(query, params);
+            // Modern Expo SQLite (SDK 51+): runAsync is optimized for writes without dummy row allocation
+            if (typeof this.db.runAsync === 'function') {
+                const res = await this.db.runAsync(trimmed, params);
+                return [res];
+            }
+            return this.db.getAllAsync(trimmed, params);
         };
-        const next = this.queue.then(run, run);
-        this.queue = next.catch(() => { });
+        const next = this.writeQueue.then(run, run);
+        this.writeQueue = next.catch(() => { });
         return await next;
     }
     async transaction(action) {
@@ -30,28 +41,34 @@ class ExpoSQLiteAdapter {
                 const txWrapper = {
                     execute: async (q, p = []) => {
                         const trimmed = q.trim();
-                        const isSelect = /^SELECT\b/i.test(trimmed) || /^PRAGMA\b/i.test(trimmed);
-                        if (!isSelect && (!p || p.length === 0) && typeof this.db.execAsync === 'function') {
-                            await this.db.execAsync(q);
+                        if (READ_QUERY_REGEX.test(trimmed)) {
+                            return this.db.getAllAsync(trimmed, p);
+                        }
+                        if ((!p || p.length === 0) && typeof this.db.execAsync === 'function') {
+                            await this.db.execAsync(trimmed);
                             return [];
                         }
-                        return await this.db.getAllAsync(q, p);
-                    }
+                        if (typeof this.db.runAsync === 'function') {
+                            const res = await this.db.runAsync(trimmed, p);
+                            return [res];
+                        }
+                        return this.db.getAllAsync(trimmed, p);
+                    },
                 };
                 result = await action(txWrapper);
             });
             return result;
         };
-        // Serialize transactions and queries to prevent SQLite concurrency crashes
-        const next = this.queue.then(run, run);
-        this.queue = next.catch(() => { });
+        // Serialize transactions to prevent SQLite concurrency crashes
+        const next = this.writeQueue.then(run, run);
+        this.writeQueue = next.catch(() => { });
         return await next;
     }
     /**
-     * Waits for pending queries/transactions to finish and closes the underlying SQLite database connection.
+     * Waits for pending writes/transactions to finish and closes the underlying SQLite connection.
      */
     async close() {
-        await this.queue;
+        await this.writeQueue;
         if (typeof this.db.closeAsync === 'function') {
             await this.db.closeAsync();
         }

package/dist/adapters/local/index.d.ts

@@ -3,6 +3,8 @@ export interface LocalTransaction {
 }
 export interface LocalDBAdapter {
     execute(query: string, params?: any[]): Promise<any[]>;
+    /** True when execute runs real SQL with filtering, ordering, paging, and projection. */
+    readonly supportsSqlPushdown?: boolean;
     transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
     close?(): Promise<void> | void;
 }

package/dist/adapters/local/libsql.d.ts

@@ -17,6 +17,7 @@ export interface LibSQLClient {
  * Supports local SQLite files, embedded replicas, in-memory databases, and server/edge deployments.
  */
 export declare class LibSQLAdapter implements LocalDBAdapter {
+    readonly supportsSqlPushdown = true;
     private client;
     constructor(libsqlClient: any);
     execute(query: string, params?: any[]): Promise<any[]>;

package/dist/adapters/local/libsql.js

@@ -28,6 +28,7 @@ function normalizeRows(res) {
  * Supports local SQLite files, embedded replicas, in-memory databases, and server/edge deployments.
  */
 class LibSQLAdapter {
+    supportsSqlPushdown = true;
     client;
     constructor(libsqlClient) {
         this.client = libsqlClient;

package/dist/adapters/local/node-sqlite.d.ts

@@ -17,9 +17,13 @@ export interface NodeSqliteDatabaseSync {
  * Provides zero-dependency, native SQLite on modern Node.js runtimes.
  */
 export declare class NodeSQLiteAdapter implements LocalDBAdapter {
+    readonly supportsSqlPushdown = true;
     private db;
-    private queue;
+    private txQueue;
+    private statementCache;
+    private readonly maxCacheSize;
     constructor(nodeSqliteDb: any);
+    private getStatement;
     execute(query: string, params?: any[]): Promise<any[]>;
     transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
     close(): void;

package/dist/adapters/local/node-sqlite.js

@@ -6,24 +6,42 @@ exports.NodeSQLiteAdapter = void 0;
  * Provides zero-dependency, native SQLite on modern Node.js runtimes.
  */
 class NodeSQLiteAdapter {
+    supportsSqlPushdown = true;
     db;
-    queue = Promise.resolve();
+    txQueue = Promise.resolve();
+    statementCache = new Map();
+    maxCacheSize = 100;
     constructor(nodeSqliteDb) {
         this.db = nodeSqliteDb;
     }
+    getStatement(sql) {
+        let stmt = this.statementCache.get(sql);
+        if (!stmt) {
+            if (this.statementCache.size >= this.maxCacheSize) {
+                const oldestKey = this.statementCache.keys().next().value;
+                if (oldestKey)
+                    this.statementCache.delete(oldestKey);
+            }
+            stmt = this.db.prepare(sql);
+            this.statementCache.set(sql, stmt);
+        }
+        return stmt;
+    }
     async execute(query, params = []) {
+        const trimmed = query.trim();
+        const isReader = /^SELECT|^PRAGMA/i.test(trimmed);
+        // Fast-path: Readers execute directly and synchronously without queuing delay
+        if (isReader) {
+            const stmt = this.getStatement(trimmed);
+            return stmt.all(...params);
+        }
         const run = async () => {
-            const trimmed = query.trim();
-            const stmt = this.db.prepare(trimmed);
-            // Queries that return rows (SELECT, PRAGMA)
-            if (/^SELECT|^PRAGMA/i.test(trimmed)) {
-                return stmt.all(...params);
-            }
+            const stmt = this.getStatement(trimmed);
             const res = stmt.run(...params);
             return [res];
         };
-        const next = this.queue.then(run, run);
-        this.queue = next.catch(() => { });
+        const next = this.txQueue.then(run, run);
+        this.txQueue = next.catch(() => { });
         return await next;
     }
     async transaction(action) {
@@ -33,7 +51,7 @@ class NodeSQLiteAdapter {
                 const txWrapper = {
                     execute: async (q, p = []) => {
                         const trimmed = q.trim();
-                        const stmt = this.db.prepare(trimmed);
+                        const stmt = this.getStatement(trimmed);
                         if (/^SELECT|^PRAGMA/i.test(trimmed)) {
                             return stmt.all(...p);
                         }
@@ -54,8 +72,8 @@ class NodeSQLiteAdapter {
                 throw err;
             }
         };
-        const next = this.queue.then(run, run);
-        this.queue = next.catch(() => { });
+        const next = this.txQueue.then(run, run);
+        this.txQueue = next.catch(() => { });
         return await next;
     }
     close() {

package/dist/adapters/local/op-sqlite.d.ts

@@ -18,6 +18,7 @@ export interface OpSQLiteDatabase {
  * Enables ultra-fast C++ JSI SQLite in bare React Native.
  */
 export declare class OpSQLiteAdapter implements LocalDBAdapter {
+    readonly supportsSqlPushdown = true;
     private db;
     private txMutex;
     constructor(opSqliteInstance: any);

package/dist/adapters/local/op-sqlite.js

@@ -26,6 +26,7 @@ function extractRows(res) {
  * Enables ultra-fast C++ JSI SQLite in bare React Native.
  */
 class OpSQLiteAdapter {
+    supportsSqlPushdown = true;
     db;
     txMutex = Promise.resolve();
     constructor(opSqliteInstance) {

package/dist/adapters/local/sql-js.d.ts

@@ -19,6 +19,7 @@ export interface SqlJsDatabase {
  * Adapter for sql.js (WebAssembly SQLite in Web Browsers, PWAs, and Expo Web).
  */
 export declare class SqlJsAdapter implements LocalDBAdapter {
+    readonly supportsSqlPushdown = true;
     private db;
     constructor(sqlJsDatabase: any);
     execute(query: string, params?: any[]): Promise<any[]>;

package/dist/adapters/local/sql-js.js

@@ -5,6 +5,7 @@ exports.SqlJsAdapter = void 0;
  * Adapter for sql.js (WebAssembly SQLite in Web Browsers, PWAs, and Expo Web).
  */
 class SqlJsAdapter {
+    supportsSqlPushdown = true;
     db;
     constructor(sqlJsDatabase) {
         this.db = sqlJsDatabase;

package/dist/adapters/remote/firestore.js

@@ -179,39 +179,46 @@ class FirestoreRemoteAdapter {
             const mod = isCompat ? null : await this.getModule();
             let maxServerTimestamp = sinceTimestamp;
             const changes = [];
-            for (const table of this.tables) {
-                let docs = [];
-                if (isCompat) {
-                    const snapshot = await this.db
-                        .collection(table)
-                        .where(this.updatedAtColumn, '>', sinceTimestamp)
-                        .get();
-                    docs = snapshot.docs || [];
-                }
-                else if (mod && typeof mod.getDocs === 'function') {
-                    const q = mod.query(mod.collection(this.db, table), mod.where(this.updatedAtColumn, '>', sinceTimestamp));
-                    const snapshot = await mod.getDocs(q);
-                    docs = snapshot.docs || [];
-                }
-                for (const doc of docs) {
-                    const data = typeof doc.data === 'function' ? doc.data() : doc;
-                    const isSoftDeleted = Boolean(data[this.deletedColumn] === true ||
-                        data[this.deletedColumn] === 1 ||
-                        (data[this.deletedColumn] &&
-                            !['false', '0', 'null', 'undefined'].includes(String(data[this.deletedColumn]).toLowerCase())));
-                    const rowTime = extractTimestamp(data[this.updatedAtColumn]);
-                    if (rowTime > maxServerTimestamp) {
-                        maxServerTimestamp = rowTime;
+            const CHUNK_SIZE = 5;
+            for (let i = 0; i < this.tables.length; i += CHUNK_SIZE) {
+                const chunk = this.tables.slice(i, i + CHUNK_SIZE);
+                const results = await Promise.all(chunk.map(async (table) => {
+                    let docs = [];
+                    if (isCompat) {
+                        const snapshot = await this.db
+                            .collection(table)
+                            .where(this.updatedAtColumn, '>', sinceTimestamp)
+                            .get();
+                        docs = snapshot.docs || [];
+                    }
+                    else if (mod && typeof mod.getDocs === 'function') {
+                        const q = mod.query(mod.collection(this.db, table), mod.where(this.updatedAtColumn, '>', sinceTimestamp));
+                        const snapshot = await mod.getDocs(q);
+                        docs = snapshot.docs || [];
+                    }
+                    return { table, docs };
+                }));
+                for (const { table, docs } of results) {
+                    for (const doc of docs) {
+                        const data = typeof doc.data === 'function' ? doc.data() : doc;
+                        const isSoftDeleted = Boolean(data[this.deletedColumn] === true ||
+                            data[this.deletedColumn] === 1 ||
+                            (data[this.deletedColumn] &&
+                                !['false', '0', 'null', 'undefined'].includes(String(data[this.deletedColumn]).toLowerCase())));
+                        const rowTime = extractTimestamp(data[this.updatedAtColumn]);
+                        if (rowTime > maxServerTimestamp) {
+                            maxServerTimestamp = rowTime;
+                        }
+                        const rowId = String(data[this.primaryKey] || doc.id || data.id);
+                        const operation = isSoftDeleted ? 'DELETE' : 'UPDATE';
+                        changes.push({
+                            tableName: table,
+                            operation,
+                            rowId,
+                            payload: isSoftDeleted ? null : data,
+                            timestamp: rowTime,
+                        });
                     }
-                    const rowId = String(data[this.primaryKey] || doc.id || data.id);
-                    const operation = isSoftDeleted ? 'DELETE' : 'UPDATE';
-                    changes.push({
-                        tableName: table,
-                        operation,
-                        rowId,
-                        payload: isSoftDeleted ? null : data,
-                        timestamp: rowTime,
-                    });
                 }
             }
             return {

package/dist/adapters/remote/supabase.d.ts

@@ -110,12 +110,17 @@ export declare class SupabaseRemoteAdapter implements RemoteDBAdapter {
      * Reads updated records and checks `deleted: true` to propagate soft deletes.
      */
     fetchChanges(sinceTimestamp: number, scope?: Record<string, any>): Promise<DeltaChanges>;
+    /**
+     * Formats a row payload for remote Supabase storage (adds primaryKey, deleted: false, updated_at).
+     */
+    private buildRowData;
     /**
      * Helper to determine if a record represents a soft delete.
      */
     private isSoftDeleted;
     /**
      * Subscribes to live realtime postgres_changes from Supabase.
+     * Batches rapid burst events in the same microtask turn into a single SQLite sync transaction.
      */
     subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): (() => void) | void;
     /**