local-lite 0.0.6 → 0.0.9

package/README.md

@@ -246,12 +246,46 @@ export function TodoScreen() {
 
 ## Supabase Backend Setup & Schema
 
-To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):
-
-```sql
--- 1. Automatic Timestamp Trigger
-CREATE OR REPLACE FUNCTION public.set_sync_updated_at()
-RETURNS TRIGGER AS $$
+To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):
+
+```sql
+-- Ensure every application table has the soft-delete column expected by local-lite.
+DO $$
+DECLARE
+  table_record RECORD;
+BEGIN
+  FOR table_record IN
+    SELECT table_schema, table_name
+    FROM information_schema.tables
+    WHERE table_schema = 'public'
+      AND table_type = 'BASE TABLE'
+  LOOP
+    EXECUTE format(
+      'ALTER TABLE %I.%I ADD COLUMN IF NOT EXISTS deleted BOOLEAN',
+      table_record.table_schema,
+      table_record.table_name
+    );
+    EXECUTE format(
+      'UPDATE %I.%I SET deleted = FALSE WHERE deleted IS NULL',
+      table_record.table_schema,
+      table_record.table_name
+    );
+    EXECUTE format(
+      'ALTER TABLE %I.%I ALTER COLUMN deleted SET DEFAULT FALSE',
+      table_record.table_schema,
+      table_record.table_name
+    );
+    EXECUTE format(
+      'ALTER TABLE %I.%I ALTER COLUMN deleted SET NOT NULL',
+      table_record.table_schema,
+      table_record.table_name
+    );
+  END LOOP;
+END $$;
+
+-- 1. Automatic Timestamp Trigger
+CREATE OR REPLACE FUNCTION public.set_sync_updated_at()
+RETURNS TRIGGER AS $$
 BEGIN
   NEW.updated_at = timezone('utc'::text, now());
   RETURN NEW;

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/config/index.js

@@ -89,6 +89,7 @@ async function createSyncClient(config) {
         autoHydrateJSON: config.autoHydrateJSON,
         syncScope: config.syncScope,
         autoPauseOnBackground: config.autoPauseOnBackground,
+        touchUpdatedAt: config.touchUpdatedAt,
     });
     // 5. Execute Migrations & Auto-initialize
     if (config.autoInitialize !== false) {

package/dist/config/types.d.ts

@@ -181,4 +181,13 @@ export interface LocalLiteConfig {
      * Scoped synchronization filter (e.g. { org_id: '...' } or dynamic resolver callback).
      */
     syncScope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
+    /**
+     * Stamp an "updated at" column on every local INSERT/UPDATE so reactive queries
+     * (which compare rows by `id` + `updated_at`/`updatedAt`) re-render after offline edits.
+     * Only the local SQLite row is stamped; payloads pushed to the remote are unchanged.
+     * - `true` (default): column inferred from the remote adapter's `updatedAtColumn`, else 'updated_at'
+     * - `string`: explicit column name
+     * - `false`: disabled
+     */
+    touchUpdatedAt?: boolean | string;
 }

package/dist/core/client.d.ts

@@ -27,6 +27,15 @@ export interface LocalFirstClientConfig {
     autoHydrateJSON?: boolean;
     syncScope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
     autoPauseOnBackground?: boolean;
+    /**
+     * Stamp an "updated at" column on every local INSERT/UPDATE write so reactive
+     * queries (which compare rows by `id` + `updated_at`/`updatedAt`) detect offline edits.
+     * Only the local SQLite row is stamped; outbox payloads sent to the remote are unchanged.
+     * - `true` (default): column inferred from the remote adapter's `updatedAtColumn`, else 'updated_at'
+     * - `string`: explicit column name
+     * - `false`: disabled
+     */
+    touchUpdatedAt?: boolean | string;
 }
 export declare class TransactionalClient {
     private parent;
@@ -67,12 +76,25 @@ export declare class LocalFirstClient {
     tables: string[];
     jsonColumns: Record<string, string[]>;
     autoHydrateJSON: boolean;
+    /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
+    touchColumn: string | null;
     private primaryKey;
     private migrations;
     private autoStart;
     private initialization?;
     constructor(config: LocalFirstClientConfig);
     getPrimaryKey(): string;
+    /**
+     * Options for TableManager.applyMutation on locally-originated writes.
+     * The touch value uses the mutation timestamp so it matches what remote
+     * adapters (e.g. Supabase) write for the same operation on push.
+     */
+    localMutationOptions(timestamp: number): {
+        autoSchema: boolean;
+        schemaManager: SchemaManager;
+        touchColumn: string | null;
+        touchValue: string;
+    };
     /**
      * Automatically deserializes JSON string columns into JavaScript objects/arrays.
      */
@@ -81,7 +103,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);
@@ -62,10 +74,7 @@ class TransactionalClient {
     async mutate(tableName, rowId, operation, payload, options = {}) {
         const pk = options.primaryKey ?? this.parent.getPrimaryKey();
         const timestamp = options.customTimestamp ?? Date.now();
-        await table_manager_js_1.TableManager.applyMutation(this.tx, tableName, rowId, operation, payload, pk, {
-            autoSchema: this.parent.autoSchema,
-            schemaManager: this.parent.schemaManager,
-        });
+        await table_manager_js_1.TableManager.applyMutation(this.tx, tableName, rowId, operation, payload, pk, this.parent.localMutationOptions(timestamp));
         if (!options.skipOutbox) {
             const outboxId = await this.parent.recordOutboxMutation(this.tx, tableName, rowId, operation, payload, timestamp);
             if (outboxId) {
@@ -117,8 +126,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));
@@ -142,6 +154,8 @@ class LocalFirstClient {
     tables;
     jsonColumns;
     autoHydrateJSON;
+    /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
+    touchColumn;
     primaryKey;
     migrations;
     autoStart;
@@ -158,6 +172,13 @@ class LocalFirstClient {
         this.autoStart = config.autoStart ?? true;
         this.jsonColumns = config.jsonColumns ?? {};
         this.autoHydrateJSON = config.autoHydrateJSON ?? false;
+        const touch = config.touchUpdatedAt ?? true;
+        this.touchColumn =
+            touch === false
+                ? null
+                : typeof touch === 'string'
+                    ? touch
+                    : this.remote?.updatedAtColumn || 'updated_at';
         this.schemaManager = new schema_manager_js_1.SchemaManager();
         const workerOptions = {
             network: config.network,
@@ -180,6 +201,19 @@ class LocalFirstClient {
     getPrimaryKey() {
         return this.primaryKey;
     }
+    /**
+     * Options for TableManager.applyMutation on locally-originated writes.
+     * The touch value uses the mutation timestamp so it matches what remote
+     * adapters (e.g. Supabase) write for the same operation on push.
+     */
+    localMutationOptions(timestamp) {
+        return {
+            autoSchema: this.autoSchema,
+            schemaManager: this.schemaManager,
+            touchColumn: this.touchColumn,
+            touchValue: new Date(timestamp).toISOString(),
+        };
+    }
     /**
      * Automatically deserializes JSON string columns into JavaScript objects/arrays.
      */
@@ -228,40 +262,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;
     }
@@ -318,10 +364,7 @@ class LocalFirstClient {
         let affectedOutboxId;
         const executeInTransaction = async (tx) => {
             // 1. Mutate local table
-            await table_manager_js_1.TableManager.applyMutation(tx, tableName, rowId, operation, payload, pk, {
-                autoSchema: this.autoSchema,
-                schemaManager: this.schemaManager,
-            });
+            await table_manager_js_1.TableManager.applyMutation(tx, tableName, rowId, operation, payload, pk, this.localMutationOptions(timestamp));
             // 2. Insert into sync_outbox (if not skipped)
             if (!options.skipOutbox) {
                 affectedOutboxId = await this.recordOutboxMutation(tx, tableName, rowId, operation, payload, timestamp);
@@ -360,7 +403,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;
@@ -369,15 +416,12 @@ class LocalFirstClient {
                         ? String(payload[pk])
                         : (0, uuid_js_1.generateUUID)());
                 generatedIds.push(rowId);
-                await table_manager_js_1.TableManager.applyMutation(tx, m.tableName, rowId, m.operation, payload, pk, {
-                    autoSchema: this.autoSchema,
-                    schemaManager: this.schemaManager,
-                });
+                const timestamp = m.customTimestamp ?? options.customTimestamp ?? Date.now();
+                await table_manager_js_1.TableManager.applyMutation(tx, m.tableName, rowId, m.operation, payload, pk, this.localMutationOptions(timestamp));
                 const skipOutbox = m.skipOutbox ?? options.skipOutbox ?? false;
                 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 +706,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/core/schema-manager.d.ts

@@ -17,6 +17,12 @@ export declare class SchemaManager {
     private knownIndexes;
     clearCache(): void;
     hasColumn(tableName: string, column: string): boolean;
+    /**
+     * Returns whether `column` exists on `tableName`, introspecting via PRAGMA table_info
+     * at most once per table (cached). Unlike ensureTableIntrospected, this has no
+     * side effects (no auto-indexing), so it is safe on hand-written schemas.
+     */
+    tableHasColumn(db: DBExecutable, tableName: string, column: string): Promise<boolean>;
     /**
      * Introspects table columns via PRAGMA table_info if not previously cached.
      */

package/dist/core/schema-manager.js

@@ -42,6 +42,31 @@ class SchemaManager {
     hasColumn(tableName, column) {
         return this.knownColumns.has(`${tableName}:${column.toLowerCase()}`);
     }
+    /**
+     * Returns whether `column` exists on `tableName`, introspecting via PRAGMA table_info
+     * at most once per table (cached). Unlike ensureTableIntrospected, this has no
+     * side effects (no auto-indexing), so it is safe on hand-written schemas.
+     */
+    async tableHasColumn(db, tableName, column) {
+        if (this.hasColumn(tableName, column))
+            return true;
+        const probeKey = `${tableName}:__probed__`;
+        if (!this.knownColumns.has(probeKey)) {
+            try {
+                const tableInfo = await db.execute(`PRAGMA table_info(${(0, sql_js_1.escapeIdentifier)(tableName)});`);
+                if (Array.isArray(tableInfo) && tableInfo.length > 0) {
+                    // Only cache once the table exists, so tables created later get re-probed.
+                    this.knownColumns.add(probeKey);
+                    for (const col of tableInfo) {
+                        if (col?.name)
+                            this.knownColumns.add(`${tableName}:${String(col.name).toLowerCase()}`);
+                    }
+                }
+            }
+            catch { }
+        }
+        return this.hasColumn(tableName, column);
+    }
     /**
      * Introspects table columns via PRAGMA table_info if not previously cached.
      */

package/dist/core/table-manager.d.ts

@@ -4,6 +4,15 @@ import { SchemaManager } from './schema-manager.js';
 export interface TableMutationOptions {
     autoSchema?: boolean;
     schemaManager?: SchemaManager;
+    /**
+     * Column to stamp with `touchValue` on local writes (e.g. 'updated_at').
+     * - UPDATE: always overwritten (mirrors what remote adapters do on push).
+     * - INSERT: only set when the payload does not already provide a value.
+     * Skipped when the column does not exist and autoSchema is disabled.
+     */
+    touchColumn?: string | null;
+    /** Value written to `touchColumn`. Default: current time as an ISO string. */
+    touchValue?: any;
 }
 export declare class TableManager {
     /**

package/dist/core/table-manager.js

@@ -13,6 +13,16 @@ function formatPayload(payload) {
     }
     return formatted;
 }
+async function withTouchedColumn(tx, sm, tableName, operation, payload, options) {
+    const col = options.touchColumn;
+    if (operation === 'INSERT' && payload && payload[col] !== undefined && payload[col] !== null) {
+        return payload;
+    }
+    if (!options.autoSchema && !(await sm.tableHasColumn(tx, tableName, col))) {
+        return payload;
+    }
+    return { ...(payload || {}), [col]: options.touchValue ?? new Date().toISOString() };
+}
 class TableManager {
     /**
      * Applies an insert, update, or delete mutation on a local data table.
@@ -30,6 +40,9 @@ class TableManager {
             await tx.execute(`DELETE FROM ${safeTable} WHERE ${safePk} = ?`, [rowId]);
             return;
         }
+        if (options?.touchColumn) {
+            payload = await withTouchedColumn(tx, sm, tableName, operation, payload, options);
+        }
         const formatted = options?.autoSchema
             ? await sm.ensureColumns(tx, tableName, payload, primaryKey)
             : formatPayload(payload);

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.9",
   "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",
@@ -130,6 +130,7 @@
   },
   "devDependencies": {
     "@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",