local-lite 0.0.6 → 0.0.7

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

@@ -16,6 +16,7 @@ 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 txQueue;
     private statementCache;

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

@@ -5,6 +5,7 @@ exports.BetterSQLite3Adapter = void 0;
  * Adapter for better-sqlite3 in Node.js, Electron, Next.js, and server environments.
  */
 class BetterSQLite3Adapter {
+    supportsSqlPushdown = true;
     db;
     txQueue = Promise.resolve();
     statementCache = new Map();

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

@@ -8,6 +8,7 @@ export interface ExpoDatabase {
     closeSync?(): void;
 }
 export declare class ExpoSQLiteAdapter implements LocalDBAdapter {
+    readonly supportsSqlPushdown = true;
     private db;
     private writeQueue;
     constructor(expoDbInstance: any);

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

@@ -4,6 +4,7 @@ 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;
     writeQueue = Promise.resolve();
     constructor(expoDbInstance) {

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,6 +17,7 @@ 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 txQueue;
     private statementCache;

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

@@ -6,6 +6,7 @@ exports.NodeSQLiteAdapter = void 0;
  * Provides zero-dependency, native SQLite on modern Node.js runtimes.
  */
 class NodeSQLiteAdapter {
+    supportsSqlPushdown = true;
     db;
     txQueue = Promise.resolve();
     statementCache = new Map();

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/core/client.d.ts

@@ -81,7 +81,7 @@ export declare class LocalFirstClient {
      * Writes a mutation to the outbox table, optionally coalescing with existing PENDING records for the same row.
      * Returns the affected outboxId, or undefined if an offline INSERT was deleted offline before pushing.
      */
-    recordOutboxMutation(tx: LocalTransaction, tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, timestamp: number): Promise<string | undefined>;
+    recordOutboxMutation(tx: LocalTransaction, tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, timestamp: number, pendingOutboxMap?: Map<string, OutboxRecord>): Promise<string | undefined>;
     /**
      * Initializes the client: creates sync_outbox schema, ensures autoSchema tables if enabled,
      * applies migrations, and optionally starts automatic sync. Concurrent/repeated calls

package/dist/core/client.js

@@ -11,6 +11,18 @@ const uuid_js_1 = require("../utils/uuid.js");
 const sql_js_1 = require("../utils/sql.js");
 const query_js_1 = require("./query.js");
 const query_builder_js_1 = require("./query-builder.js");
+function hasFunctionFilter(value) {
+    if (typeof value === 'function')
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasFunctionFilter);
+    if (value && typeof value === 'object')
+        return Object.values(value).some(hasFunctionFilter);
+    return false;
+}
+function shouldUseClientSideQuery(options) {
+    return hasFunctionFilter(options?.where);
+}
 async function executeFindById(db, tableName, id, primaryKey, hydrateRow, includeDeleted) {
     const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
     const safePk = (0, sql_js_1.escapeIdentifier)(primaryKey);
@@ -117,8 +129,11 @@ class TransactionalClient {
         return executeFindByIds(this.tx, tableName, ids, this.parent.getPrimaryKey(), (t, r) => this.parent.hydrateRow(t, r), options?.includeDeleted);
     }
     async findMany(tableName, options) {
-        const rows = await this.from(tableName).applyOptions(options).execute();
-        return (0, query_js_1.applyQueryOptions)(rows, options);
+        if (!this.parent.db.supportsSqlPushdown || shouldUseClientSideQuery(options)) {
+            const rows = await this.from(tableName).execute();
+            return (0, query_js_1.applyQueryOptions)(rows, options);
+        }
+        return this.from(tableName).applyOptions(options).execute();
     }
     async query(sql, params = []) {
         return (await this.tx.execute(sql, params));
@@ -228,40 +243,52 @@ class LocalFirstClient {
      * Writes a mutation to the outbox table, optionally coalescing with existing PENDING records for the same row.
      * Returns the affected outboxId, or undefined if an offline INSERT was deleted offline before pushing.
      */
-    async recordOutboxMutation(tx, tableName, rowId, operation, payload, timestamp) {
+    async recordOutboxMutation(tx, tableName, rowId, operation, payload, timestamp, pendingOutboxMap) {
+        const pendingKey = tableName + ':' + rowId;
         if (this.coalesceOutbox) {
-            const existing = await outbox_store_js_1.OutboxStore.findPendingByRow(tx, tableName, rowId);
+            const existing = pendingOutboxMap
+                ? pendingOutboxMap.get(pendingKey)
+                : await outbox_store_js_1.OutboxStore.findPendingByRow(tx, tableName, rowId);
             if (existing && existing.status === 'PENDING') {
                 if (operation === 'DELETE') {
                     if (existing.operation === 'INSERT') {
-                        // Created offline and deleted offline before ever being pushed to server: clean up outbox completely
                         await outbox_store_js_1.OutboxStore.deleteRecord(tx, existing.id);
+                        pendingOutboxMap?.delete(pendingKey);
                         return undefined;
                     }
-                    else {
-                        await outbox_store_js_1.OutboxStore.updateOperation(tx, existing.id, 'DELETE', null, timestamp);
-                        return existing.id;
+                    await outbox_store_js_1.OutboxStore.updateOperation(tx, existing.id, 'DELETE', null, timestamp);
+                    if (pendingOutboxMap) {
+                        existing.operation = 'DELETE';
+                        existing.payload = null;
+                        existing.timestamp = timestamp;
                     }
+                    return existing.id;
                 }
-                else if (operation === 'UPDATE') {
+                if (operation === 'UPDATE') {
                     const merged = { ...(existing.payload || {}), ...(payload || {}) };
                     await outbox_store_js_1.OutboxStore.updatePayload(tx, existing.id, merged, timestamp);
+                    if (pendingOutboxMap) {
+                        existing.payload = merged;
+                        existing.timestamp = timestamp;
+                    }
                     return existing.id;
                 }
-                else if (operation === 'INSERT') {
+                if (operation === 'INSERT') {
                     await outbox_store_js_1.OutboxStore.updateOperation(tx, existing.id, 'INSERT', payload, timestamp);
+                    if (pendingOutboxMap) {
+                        existing.operation = 'INSERT';
+                        existing.payload = payload;
+                        existing.timestamp = timestamp;
+                    }
                     return existing.id;
                 }
             }
         }
         const outboxId = (0, uuid_js_1.generateUUID)();
-        await outbox_store_js_1.OutboxStore.insertRecord(tx, {
-            id: outboxId,
-            tableName,
-            rowId,
-            operation,
-            payload,
-            timestamp,
+        await outbox_store_js_1.OutboxStore.insertRecord(tx, { id: outboxId, tableName, rowId, operation, payload, timestamp });
+        pendingOutboxMap?.set(pendingKey, {
+            id: outboxId, tableName, rowId, operation, payload, timestamp,
+            status: 'PENDING', retryCount: 0, lastError: null,
         });
         return outboxId;
     }
@@ -360,7 +387,11 @@ class LocalFirstClient {
         const queuedEvents = [];
         const queuedOutboxIds = [];
         const pendingOutboxOps = [];
+        let pendingOutboxMap;
         const executeInTx = async (tx) => {
+            if (this.coalesceOutbox && mutations.length > 1) {
+                pendingOutboxMap = await outbox_store_js_1.OutboxStore.getActivePendingMap(tx);
+            }
             for (const m of mutations) {
                 const pk = m.primaryKey ?? options.primaryKey ?? this.primaryKey;
                 const payload = m.payload ?? null;
@@ -377,7 +408,7 @@ class LocalFirstClient {
                 if (!skipOutbox) {
                     const timestamp = m.customTimestamp ?? options.customTimestamp ?? Date.now();
                     if (this.coalesceOutbox && m.operation !== 'INSERT') {
-                        const outboxId = await this.recordOutboxMutation(tx, m.tableName, rowId, m.operation, payload, timestamp);
+                        const outboxId = await this.recordOutboxMutation(tx, m.tableName, rowId, m.operation, payload, timestamp, pendingOutboxMap);
                         if (outboxId) {
                             queuedOutboxIds.push(outboxId);
                         }
@@ -662,8 +693,11 @@ class LocalFirstClient {
         return result;
     }
     async findMany(tableName, options) {
-        const rows = await this.from(tableName).applyOptions(options).execute();
-        return (0, query_js_1.applyQueryOptions)(rows, options);
+        if (!this.db.supportsSqlPushdown || shouldUseClientSideQuery(options)) {
+            const rows = await this.from(tableName).execute();
+            return (0, query_js_1.applyQueryOptions)(rows, options);
+        }
+        return this.from(tableName).applyOptions(options).execute();
     }
     /**
      * Finds a single record by primary key.

package/dist/react/index.js

@@ -116,6 +116,39 @@ class LRUQueryCache {
 // In-memory query result cache capped with LRU eviction to prevent memory leaks
 const queryCache = new LRUQueryCache();
 const inFlightQueries = new Map();
+const tableVersions = new WeakMap();
+const clientIds = new WeakMap();
+let nextClientId = 1;
+function getClientScope(client) {
+    if (!client)
+        return 'no-client';
+    let id = clientIds.get(client);
+    if (!id) {
+        id = nextClientId++;
+        clientIds.set(client, id);
+    }
+    return 'client-' + id;
+}
+function getScopedCacheKey(client, key) {
+    return getClientScope(client) + ':' + key;
+}
+function getTableVersion(client, tableName) {
+    if (!client)
+        return 0;
+    return tableVersions.get(client)?.get(tableName) || 0;
+}
+function advanceTableVersion(client, tableName) {
+    if (!client)
+        return 0;
+    let versions = tableVersions.get(client);
+    if (!versions) {
+        versions = new Map();
+        tableVersions.set(client, versions);
+    }
+    const nextVersion = getTableVersion(client, tableName) + 1;
+    versions.set(tableName, nextVersion);
+    return nextVersion;
+}
 async function fetchDeduped(key, fn) {
     let inFlight = inFlightQueries.get(key);
     if (!inFlight) {
@@ -155,7 +188,7 @@ function useLiveQuery(client, tableName, queryOrOptions) {
         : typeof queryOrOptions === 'function'
             ? 'custom'
             : 'all';
-    const cacheKey = `${tableName}:${queryKey}`;
+    const cacheKey = getScopedCacheKey(client, `${tableName}:${queryKey}`);
     // Read-through cache: return instant cached rows on mount (0ms latency, zero flicker)
     const [data, setData] = (0, react_1.useState)(() => queryCache.get(cacheKey) || []);
     const [loading, setLoading] = (0, react_1.useState)(() => !queryCache.has(cacheKey));
@@ -164,8 +197,9 @@ function useLiveQuery(client, tableName, queryOrOptions) {
     const refetch = (0, react_1.useCallback)(async () => {
         if (!client || !client.db)
             return;
+        const versionAtStart = getTableVersion(client, tableName);
         try {
-            const res = await fetchDeduped(cacheKey, async () => {
+            const res = await fetchDeduped(cacheKey + ':v' + versionAtStart, async () => {
                 const param = queryParamRef.current;
                 if (typeof param === 'function')
                     return (await param(client)) || [];
@@ -173,6 +207,8 @@ function useLiveQuery(client, tableName, queryOrOptions) {
                     return await client.findMany(tableName, param);
                 return await client.findMany(tableName);
             });
+            if (versionAtStart !== getTableVersion(client, tableName))
+                return;
             queryCache.set(cacheKey, res);
             setData((prev) => (areRowArraysEqual(prev, res) ? prev : res));
         }
@@ -196,6 +232,7 @@ function useLiveQuery(client, tableName, queryOrOptions) {
             return;
         refetch();
         const unsubscribe = client.events.on(tableName, () => {
+            advanceTableVersion(client, tableName);
             scheduleRefetch();
         });
         return () => {
@@ -297,10 +334,11 @@ function useLiveQueries(client, queries) {
         return JSON.stringify(queries, (_, val) => (typeof val === 'function' ? 'fn' : val));
     }, [queries]);
     const items = (0, react_1.useMemo)(() => normalizeMultiQueries(queries), [signature]);
+    const clientScope = getClientScope(client);
     const [data, setData] = (0, react_1.useState)(() => {
         const initial = {};
         for (const item of items) {
-            const cached = queryCache.get(item.cacheKey);
+            const cached = queryCache.get(clientScope + ':' + item.cacheKey);
             initial[item.key] = cached ? cached : [];
         }
         return initial;
@@ -309,7 +347,7 @@ function useLiveQueries(client, queries) {
         if (items.length === 0)
             return false;
         for (const item of items) {
-            if (!queryCache.has(item.cacheKey))
+            if (!queryCache.has(clientScope + ':' + item.cacheKey))
                 return true;
         }
         return false;
@@ -320,14 +358,18 @@ function useLiveQueries(client, queries) {
         try {
             const results = await Promise.all(items.map(async (item) => {
                 try {
-                    const rows = await fetchDeduped(item.cacheKey, async () => {
+                    const versionAtStart = getTableVersion(client, item.table);
+                    const scopedCacheKey = clientScope + ':' + item.cacheKey;
+                    const rows = await fetchDeduped(scopedCacheKey + ':v' + versionAtStart, async () => {
                         if (item.fn)
                             return (await item.fn(client)) || [];
                         if (item.options)
                             return await client.findMany(item.table, item.options);
                         return await client.findMany(item.table);
                     });
-                    queryCache.set(item.cacheKey, rows);
+                    if (versionAtStart !== getTableVersion(client, item.table))
+                        return null;
+                    queryCache.set(scopedCacheKey, rows);
                     return { key: item.key, rows };
                 }
                 catch (err) {
@@ -343,6 +385,8 @@ function useLiveQueries(client, queries) {
                 let changed = false;
                 const next = { ...prev };
                 for (const res of results) {
+                    if (!res)
+                        continue;
                     if (!areRowArraysEqual(prev[res.key], res.rows)) {
                         next[res.key] = res.rows;
                         changed = true;
@@ -362,6 +406,7 @@ function useLiveQueries(client, queries) {
         refetch();
         const tables = Array.from(new Set(items.map((i) => i.table).filter(Boolean)));
         const unsubs = tables.map((tbl) => client.events.on(tbl, () => {
+            advanceTableVersion(client, tbl);
             scheduleRefetch();
         }));
         return () => {
@@ -377,7 +422,7 @@ function useLiveQueries(client, queries) {
  * Automatically re-renders only when this specific row or table changes.
  */
 function useLiveRow(client, tableName, rowId, options) {
-    const cacheKey = `${tableName}:row:${rowId || 'null'}:${Boolean(options?.includeDeleted)}`;
+    const cacheKey = getScopedCacheKey(client, `${tableName}:row:${rowId || 'null'}:${Boolean(options?.includeDeleted)}`);
     const [data, setData] = (0, react_1.useState)(() => {
         if (!rowId)
             return null;
@@ -392,10 +437,13 @@ function useLiveRow(client, tableName, rowId, options) {
             return;
         }
         try {
-            const res = await fetchDeduped(cacheKey, async () => {
+            const versionAtStart = getTableVersion(client, tableName);
+            const res = await fetchDeduped(cacheKey + ':v' + versionAtStart, async () => {
                 const r = await client.findById(tableName, rowId, options);
                 return r ? [r] : [];
             });
+            if (versionAtStart !== getTableVersion(client, tableName))
+                return;
             const row = res.length > 0 ? res[0] : null;
             if (row) {
                 queryCache.set(cacheKey, [row]);
@@ -424,6 +472,7 @@ function useLiveRow(client, tableName, rowId, options) {
             return;
         refetch();
         const unsubscribe = client.events.on(tableName, (event) => {
+            advanceTableVersion(client, tableName);
             // Precise row-level invalidation: only refetch if event affects this rowId or is a bulk event
             if (!event || !event.rowId || event.rowId === rowId || event.rowId === 'batch') {
                 scheduleRefetch();
@@ -455,6 +504,7 @@ function useLiveInfiniteQuery(client, tableName, options = {}) {
             return;
         if (isNextPage)
             setIsFetchingNextPage(true);
+        const versionAtStart = getTableVersion(client, tableName);
         try {
             const currentOpts = optionsRef.current;
             const fetchLimit = pages * pageSize + 1; // +1 to check for hasNextPage
@@ -463,6 +513,8 @@ function useLiveInfiniteQuery(client, tableName, options = {}) {
                 limit: fetchLimit,
                 offset: currentOpts.offset || 0,
             });
+            if (versionAtStart !== getTableVersion(client, tableName))
+                return;
             if (rows.length > pages * pageSize) {
                 setHasNextPage(true);
                 setData(rows.slice(0, pages * pageSize));
@@ -504,6 +556,7 @@ function useLiveInfiniteQuery(client, tableName, options = {}) {
             return;
         loadData(1, false);
         const unsubscribe = client.events.on(tableName, () => {
+            advanceTableVersion(client, tableName);
             scheduleRefetch();
         });
         return () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -129,8 +129,9 @@
     }
   },
   "devDependencies": {
-    "@supabase/supabase-js": "^2.118.0",
-    "@types/react": "^19.3.0",
+    "@supabase/supabase-js": "^2.118.0",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
     "@types/uuid": "^11.0.0",
     "expo-sqlite": "^58.0.13",
     "react": "^19.3.1",
@@ -140,4 +141,4 @@
   "dependencies": {
     "uuid": "^14.0.3"
   }
-}
+}