local-lite 0.0.7 → 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/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.
      */

package/dist/core/client.js

@@ -74,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) {
@@ -157,6 +154,8 @@ class LocalFirstClient {
     tables;
     jsonColumns;
     autoHydrateJSON;
+    /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
+    touchColumn;
     primaryKey;
     migrations;
     autoStart;
@@ -173,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,
@@ -195,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.
      */
@@ -345,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);
@@ -400,13 +416,10 @@ 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, pendingOutboxMap);
                         if (outboxId) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.7",
+  "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",
@@ -129,9 +129,9 @@
     }
   },
   "devDependencies": {
-    "@supabase/supabase-js": "^2.118.0",
-    "@types/node": "^26.6.5",
-    "@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",
@@ -141,4 +141,4 @@
   "dependencies": {
     "uuid": "^14.0.3"
   }
-}
+}