local-lite 0.0.7 → 0.0.10

package/README.md

@@ -19,6 +19,7 @@ Built around the **Transactional Outbox Pattern**, `local-lite` ensures instant,
 * **[Configuration Reference](https://georgechitechi.github.io/local-lite/#/configuration)** - Options for `defineSyncConfig()`, retries, and loggers
 * **[Local SQLite Adapters](https://georgechitechi.github.io/local-lite/#/adapters-local)** - Expo SQLite, OP-SQLite, better-sqlite3, node:sqlite, and LibSQL
 * **[Remote Cloud Adapters](https://georgechitechi.github.io/local-lite/#/adapters-remote)** - Supabase, Convex, Cloud Firestore, and custom adapters
+* **[Database Backups](https://georgechitechi.github.io/local-lite/#/adapters-local?id=database-backups)** - SQLite snapshots with a Google Drive OAuth/PKCE client
 * **[React & Expo Hooks](https://georgechitechi.github.io/local-lite/#/react-hooks)** - `useLiveQuery()` and `useSyncStatus()`
 * **[Conflict Resolution](https://georgechitechi.github.io/local-lite/#/conflict-resolution)** - LWW, Client-Wins, Server-Wins, and custom resolvers
 
@@ -85,6 +86,7 @@ This recovers sync state; it does not repair corrupt SQLite files or cancel hung
 * **🛡️ Conflict Resolution:** Built-in strategies including **Last-Write-Wins (LWW)**, Server-Wins, Client-Wins, or custom resolver functions.
 * **📶 Network-Aware:** Automatically pauses polling when offline and triggers immediate sync flushes the instant connectivity is restored.
 * **🔄 Infinite-Loop Safe:** Incoming remote deltas update local tables and fire reactive UI listeners without echoing back into the outbox.
+* **☁️ Database Backups:** Export and restore SQLite snapshots independently of your live sync backend.
 
 ---
 
@@ -249,6 +251,40 @@ export function TodoScreen() {
 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 $$

package/dist/backups/cloud-storage.d.ts

@@ -0,0 +1,61 @@
+import type { BackupStorage } from './index.js';
+export interface CloudBackupFile {
+    id: string;
+    name: string;
+    modifiedAt?: string;
+    size?: number;
+}
+export type BackupAccessTokenProvider = () => Promise<string>;
+export interface GoogleDriveTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+}
+export interface GoogleDriveTokenStore {
+    get(): Promise<GoogleDriveTokens | null>;
+    set(tokens: GoogleDriveTokens): Promise<void>;
+    remove(): Promise<void>;
+}
+export interface GoogleDriveKeyValueStorage {
+    getItem(key: string): Promise<unknown>;
+    setItem(key: string, value: unknown): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface GoogleDriveAuthorizationRequest {
+    authorizationUrl: string;
+    redirectUri: string;
+}
+export interface GoogleDriveAuthorizationResponse {
+    code: string;
+    state: string;
+}
+export interface GoogleDriveBackupClientOptions {
+    clientId: string;
+    redirectUri: string;
+    authorize: (request: GoogleDriveAuthorizationRequest) => Promise<GoogleDriveAuthorizationResponse | null>;
+    tokenStore: GoogleDriveTokenStore;
+    randomBytes?: (length: number) => Uint8Array;
+    fetch?: typeof fetch;
+}
+export declare function createGoogleDriveTokenStore(storage: GoogleDriveKeyValueStorage, key?: string): GoogleDriveTokenStore;
+export declare class GoogleDriveBackupStorage implements BackupStorage {
+    private readonly getAccessToken;
+    private readonly fetcher;
+    constructor(getAccessToken: BackupAccessTokenProvider, fetcher?: typeof fetch);
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileId: string): Promise<Uint8Array>;
+    list(): Promise<CloudBackupFile[]>;
+}
+export declare class GoogleDriveBackupClient implements BackupStorage {
+    private readonly options;
+    private readonly storage;
+    private readonly fetcher;
+    constructor(options: GoogleDriveBackupClientOptions);
+    connect(): Promise<boolean>;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+    getValidAccessToken(): Promise<string>;
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileId: string): Promise<Uint8Array>;
+    list(): Promise<CloudBackupFile[]>;
+}

package/dist/backups/cloud-storage.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleDriveBackupClient = exports.GoogleDriveBackupStorage = void 0;
+exports.createGoogleDriveTokenStore = createGoogleDriveTokenStore;
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const GOOGLE_API = 'https://www.googleapis.com/drive/v3';
+const GOOGLE_UPLOAD_API = 'https://www.googleapis.com/upload/drive/v3';
+const GOOGLE_AUTHORIZATION_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+const GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+const GOOGLE_DRIVE_SCOPE = 'https://www.googleapis.com/auth/drive.file';
+const BACKUP_FOLDER = 'backups';
+function secureRandomBytes(length) {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('Secure random number generation is unavailable.');
+    }
+    return crypto.getRandomValues(new Uint8Array(length));
+}
+function base64UrlEncode(bytes) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let result = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index];
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        result += alphabet[first >> 2];
+        result += alphabet[((first & 3) << 4) | (second === undefined ? 0 : second >> 4)];
+        if (second !== undefined) {
+            result += alphabet[((second & 15) << 2) | (third === undefined ? 0 : third >> 6)];
+        }
+        if (third !== undefined)
+            result += alphabet[third & 63];
+    }
+    return result;
+}
+function validateGoogleTokens(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const tokens = value;
+    return (typeof tokens.accessToken === 'string' &&
+        typeof tokens.expiresAt === 'number' &&
+        (tokens.refreshToken === undefined || typeof tokens.refreshToken === 'string'));
+}
+function createGoogleDriveTokenStore(storage, key = 'local-lite-google-drive-backup-tokens') {
+    return {
+        get: async () => {
+            const tokens = await storage.getItem(key);
+            return validateGoogleTokens(tokens) ? tokens : null;
+        },
+        set: tokens => storage.setItem(key, tokens),
+        remove: () => storage.removeItem(key),
+    };
+}
+async function parseTokenResponse(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        throw new Error(`Google OAuth request failed (${response.status}).`);
+    }
+}
+function createStoredTokens(payload, prior) {
+    if (!payload.access_token) {
+        throw new Error('Google OAuth did not return an access token.');
+    }
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token ?? prior?.refreshToken,
+        expiresAt: Date.now() + (payload.expires_in ?? 3600) * 1000,
+    };
+}
+function throwTokenError(payload, status) {
+    throw new Error(payload.error_description ||
+        payload.error ||
+        `Google OAuth request failed (${status}).`);
+}
+async function parseApiError(response) {
+    let detail = '';
+    try {
+        const body = (await response.json());
+        detail =
+            (typeof body.error === 'object' ? body.error?.message : body.error) ??
+                body.error_description ??
+                body.message ??
+                '';
+    }
+    catch {
+        detail = response.statusText;
+    }
+    return new Error(`Google Drive request failed (${response.status})${detail ? `: ${detail}` : ''}`);
+}
+async function getGoogleFolderId(token, fetcher) {
+    const query = encodeURIComponent(`name = '${BACKUP_FOLDER}' and mimeType = 'application/vnd.google-apps.folder' and trashed = false`);
+    const lookup = await fetcher(`${GOOGLE_API}/files?q=${query}&spaces=drive&fields=files(id,name)&pageSize=100`, { headers: { Authorization: `Bearer ${token}` } });
+    if (!lookup.ok)
+        throw await parseApiError(lookup);
+    const result = (await lookup.json());
+    if (result.files?.[0]?.id)
+        return result.files[0].id;
+    const create = await fetcher(`${GOOGLE_API}/files?fields=id`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            name: BACKUP_FOLDER,
+            mimeType: 'application/vnd.google-apps.folder',
+        }),
+    });
+    if (!create.ok)
+        throw await parseApiError(create);
+    const folder = (await create.json());
+    if (!folder.id)
+        throw new Error('Google Drive did not return a backup folder ID.');
+    return folder.id;
+}
+class GoogleDriveBackupStorage {
+    getAccessToken;
+    fetcher;
+    constructor(getAccessToken, fetcher = fetch) {
+        this.getAccessToken = getAccessToken;
+        this.fetcher = fetcher;
+    }
+    async save(fileName, data) {
+        const token = await this.getAccessToken();
+        const folderId = await getGoogleFolderId(token, this.fetcher);
+        const session = await this.fetcher(`${GOOGLE_UPLOAD_API}/files?uploadType=resumable&fields=id`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json; charset=UTF-8',
+                'X-Upload-Content-Type': 'application/octet-stream',
+                'X-Upload-Content-Length': String(data.byteLength),
+            },
+            body: JSON.stringify({
+                name: fileName,
+                mimeType: 'application/octet-stream',
+                parents: [folderId],
+            }),
+        });
+        if (!session.ok)
+            throw await parseApiError(session);
+        const uploadUrl = session.headers.get('Location');
+        if (!uploadUrl) {
+            throw new Error('Google Drive did not return a resumable upload URL.');
+        }
+        const uploaded = await this.fetcher(uploadUrl, {
+            method: 'PUT',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/octet-stream',
+                'Content-Range': `bytes 0-${data.byteLength - 1}/${data.byteLength}`,
+            },
+            body: data.slice().buffer,
+        });
+        if (!uploaded.ok)
+            throw await parseApiError(uploaded);
+    }
+    async read(fileId) {
+        const token = await this.getAccessToken();
+        const response = await this.fetcher(`${GOOGLE_API}/files/${encodeURIComponent(fileId)}?alt=media`, { headers: { Authorization: `Bearer ${token}` } });
+        if (!response.ok)
+            throw await parseApiError(response);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async list() {
+        const token = await this.getAccessToken();
+        const folderId = await getGoogleFolderId(token, this.fetcher);
+        const query = encodeURIComponent(`'${folderId}' in parents and trashed = false`);
+        const response = await this.fetcher(`${GOOGLE_API}/files?q=${query}&fields=files(id,name,size,modifiedTime)&orderBy=modifiedTime%20desc&pageSize=100`, { headers: { Authorization: `Bearer ${token}` } });
+        if (!response.ok)
+            throw await parseApiError(response);
+        const result = (await response.json());
+        return (result.files ?? [])
+            .filter(file => file.name.endsWith('.db'))
+            .map(file => ({
+            id: file.id,
+            name: file.name,
+            modifiedAt: file.modifiedTime,
+            size: file.size ? Number(file.size) : undefined,
+        }));
+    }
+}
+exports.GoogleDriveBackupStorage = GoogleDriveBackupStorage;
+class GoogleDriveBackupClient {
+    options;
+    storage;
+    fetcher;
+    constructor(options) {
+        this.options = options;
+        if (!options.clientId.trim())
+            throw new Error('Google OAuth client ID is required.');
+        if (!options.redirectUri.trim())
+            throw new Error('Google OAuth redirect URI is required.');
+        this.fetcher = options.fetch ?? fetch;
+        this.storage = new GoogleDriveBackupStorage(() => this.getValidAccessToken(), this.fetcher);
+    }
+    async connect() {
+        const randomBytes = this.options.randomBytes ?? secureRandomBytes;
+        const verifierBytes = randomBytes(32);
+        const stateBytes = randomBytes(32);
+        if (verifierBytes.length !== 32 || stateBytes.length !== 32) {
+            throw new Error('The randomBytes provider returned an invalid number of bytes.');
+        }
+        const codeVerifier = base64UrlEncode(verifierBytes);
+        const codeChallenge = base64UrlEncode((0, sha2_js_1.sha256)((0, utils_js_1.utf8ToBytes)(codeVerifier)));
+        const state = base64UrlEncode(stateBytes);
+        const authorizationParams = new URLSearchParams({
+            client_id: this.options.clientId,
+            redirect_uri: this.options.redirectUri,
+            response_type: 'code',
+            scope: GOOGLE_DRIVE_SCOPE,
+            access_type: 'offline',
+            prompt: 'consent',
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            state,
+        });
+        const authorization = await this.options.authorize({
+            authorizationUrl: `${GOOGLE_AUTHORIZATION_ENDPOINT}?${authorizationParams}`,
+            redirectUri: this.options.redirectUri,
+        });
+        if (!authorization)
+            return false;
+        if (authorization.state !== state) {
+            throw new Error('Google OAuth state validation failed. Please try connecting again.');
+        }
+        if (!authorization.code) {
+            throw new Error('Google OAuth did not return an authorization code.');
+        }
+        const response = await this.fetcher(GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                code: authorization.code,
+                code_verifier: codeVerifier,
+                grant_type: 'authorization_code',
+                redirect_uri: this.options.redirectUri,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok)
+            throwTokenError(payload, response.status);
+        const prior = await this.options.tokenStore.get();
+        await this.options.tokenStore.set(createStoredTokens(payload, prior));
+        return true;
+    }
+    async disconnect() {
+        await this.options.tokenStore.remove();
+    }
+    async isConnected() {
+        const tokens = await this.options.tokenStore.get();
+        return validateGoogleTokens(tokens);
+    }
+    async getValidAccessToken() {
+        const tokens = await this.options.tokenStore.get();
+        if (!validateGoogleTokens(tokens)) {
+            throw new Error('Connect Google Drive before using cloud backups.');
+        }
+        if (tokens.expiresAt > Date.now() + 60_000)
+            return tokens.accessToken;
+        if (!tokens.refreshToken) {
+            throw new Error('Your Google Drive sign-in expired. Disconnect and connect the account again.');
+        }
+        const response = await this.fetcher(GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                grant_type: 'refresh_token',
+                refresh_token: tokens.refreshToken,
+                scope: GOOGLE_DRIVE_SCOPE,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok)
+            throwTokenError(payload, response.status);
+        const updatedTokens = createStoredTokens(payload, tokens);
+        await this.options.tokenStore.set(updatedTokens);
+        return updatedTokens.accessToken;
+    }
+    save(fileName, data) {
+        return this.storage.save(fileName, data);
+    }
+    read(fileId) {
+        return this.storage.read(fileId);
+    }
+    list() {
+        return this.storage.list();
+    }
+}
+exports.GoogleDriveBackupClient = GoogleDriveBackupClient;

package/dist/backups/index.d.ts

@@ -0,0 +1,14 @@
+export { type BackupAccessTokenProvider, type CloudBackupFile, type GoogleDriveAuthorizationRequest, type GoogleDriveAuthorizationResponse, type GoogleDriveBackupClientOptions, type GoogleDriveKeyValueStorage, type GoogleDriveTokenStore, type GoogleDriveTokens, GoogleDriveBackupClient, GoogleDriveBackupStorage, createGoogleDriveTokenStore, } from './cloud-storage.js';
+export interface BackupDatabase {
+    exportDatabase(): Promise<Uint8Array>;
+    importDatabase(data: Uint8Array): Promise<void>;
+}
+export interface BackupStorage {
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileName: string): Promise<Uint8Array>;
+}
+export interface CreateDatabaseBackupOptions {
+    fileName?: string;
+}
+export declare function createDatabaseBackup(database: BackupDatabase, storage: BackupStorage, options?: CreateDatabaseBackupOptions): Promise<string>;
+export declare function restoreDatabaseBackup(database: BackupDatabase, storage: BackupStorage, fileName: string): Promise<void>;

package/dist/backups/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGoogleDriveTokenStore = exports.GoogleDriveBackupStorage = exports.GoogleDriveBackupClient = void 0;
+exports.createDatabaseBackup = createDatabaseBackup;
+exports.restoreDatabaseBackup = restoreDatabaseBackup;
+var cloud_storage_js_1 = require("./cloud-storage.js");
+Object.defineProperty(exports, "GoogleDriveBackupClient", { enumerable: true, get: function () { return cloud_storage_js_1.GoogleDriveBackupClient; } });
+Object.defineProperty(exports, "GoogleDriveBackupStorage", { enumerable: true, get: function () { return cloud_storage_js_1.GoogleDriveBackupStorage; } });
+Object.defineProperty(exports, "createGoogleDriveTokenStore", { enumerable: true, get: function () { return cloud_storage_js_1.createGoogleDriveTokenStore; } });
+function validateFileName(fileName) {
+    if (!fileName || /[\\/]/.test(fileName)) {
+        throw new Error('Backup file name must be a single file name.');
+    }
+}
+async function createDatabaseBackup(database, storage, options = {}) {
+    const fileName = options.fileName ?? `local-lite-${new Date().toISOString().replace(/[:.]/g, '-')}.db`;
+    validateFileName(fileName);
+    const databaseBytes = await database.exportDatabase();
+    if (databaseBytes.length === 0) {
+        throw new Error('Cannot create a backup from an empty database.');
+    }
+    await storage.save(fileName, databaseBytes);
+    return fileName;
+}
+async function restoreDatabaseBackup(database, storage, fileName) {
+    validateFileName(fileName);
+    const databaseBytes = await storage.read(fileName);
+    if (databaseBytes.length === 0) {
+        throw new Error('Cannot restore an empty database backup.');
+    }
+    await database.importDatabase(databaseBytes);
+}

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,144 +1,150 @@
-{
-  "name": "local-lite",
-  "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",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js",
-      "default": "./dist/react/index.js"
-    },
-    "./config": {
-      "types": "./dist/config/index.d.ts",
-      "import": "./dist/config/index.js",
-      "default": "./dist/config/index.js"
-    },
-    "./schema": {
-      "types": "./dist/schema/index.d.ts",
-      "import": "./dist/schema/index.js",
-      "default": "./dist/schema/index.js"
-    },
-    "./supabase": {
-      "types": "./dist/adapters/remote/supabase.d.ts",
-      "import": "./dist/adapters/remote/supabase.js",
-      "default": "./dist/adapters/remote/supabase.js"
-    },
-    "./convex": {
-      "types": "./dist/adapters/remote/convex.d.ts",
-      "import": "./dist/adapters/remote/convex.js",
-      "default": "./dist/adapters/remote/convex.js"
-    },
-    "./firebase": {
-      "types": "./dist/adapters/remote/firestore.d.ts",
-      "import": "./dist/adapters/remote/firestore.js",
-      "default": "./dist/adapters/remote/firestore.js"
-    },
-    "./expo-sqlite": {
-      "types": "./dist/adapters/local/expo-sqlite.d.ts",
-      "import": "./dist/adapters/local/expo-sqlite.js",
-      "default": "./dist/adapters/local/expo-sqlite.js"
-    },
-    "./op-sqlite": {
-      "types": "./dist/adapters/local/op-sqlite.d.ts",
-      "import": "./dist/adapters/local/op-sqlite.js",
-      "default": "./dist/adapters/local/op-sqlite.js"
-    },
-    "./better-sqlite3": {
-      "types": "./dist/adapters/local/better-sqlite3.d.ts",
-      "import": "./dist/adapters/local/better-sqlite3.js",
-      "default": "./dist/adapters/local/better-sqlite3.js"
-    },
-    "./libsql": {
-      "types": "./dist/adapters/local/libsql.d.ts",
-      "import": "./dist/adapters/local/libsql.js",
-      "default": "./dist/adapters/local/libsql.js"
-    },
-    "./sql-js": {
-      "types": "./dist/adapters/local/sql-js.d.ts",
-      "import": "./dist/adapters/local/sql-js.js",
-      "default": "./dist/adapters/local/sql-js.js"
-    },
-    "./node-sqlite": {
-      "types": "./dist/adapters/local/node-sqlite.d.ts",
-      "import": "./dist/adapters/local/node-sqlite.js",
-      "default": "./dist/adapters/local/node-sqlite.js"
-    },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "default": "./dist/core/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run test && npm run build"
-  },
-  "peerDependencies": {
-    "@libsql/client": "^0.6.0",
-    "@op-engineering/op-sqlite": "^0.1.0",
-    "@supabase/supabase-js": "^2.0.0",
-    "better-sqlite3": "^8.0.0",
-    "convex": ">=1.0.0",
-    "expo-sqlite": ">=57.0.0",
-    "firebase": ">=9.0.0",
-    "react": ">=18.0.0",
-    "sql.js": "^1.8.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "@supabase/supabase-js": {
-      "optional": true
-    },
-    "convex": {
-      "optional": true
-    },
-    "firebase": {
-      "optional": true
-    },
-    "expo-sqlite": {
-      "optional": true
-    },
-    "@op-engineering/op-sqlite": {
-      "optional": true
-    },
-    "better-sqlite3": {
-      "optional": true
-    },
-    "@libsql/client": {
-      "optional": true
-    },
-    "sql.js": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
+{
+  "name": "local-lite",
+  "version": "0.0.10",
+  "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",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "default": "./dist/config/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js",
+      "default": "./dist/schema/index.js"
+    },
+    "./supabase": {
+      "types": "./dist/adapters/remote/supabase.d.ts",
+      "import": "./dist/adapters/remote/supabase.js",
+      "default": "./dist/adapters/remote/supabase.js"
+    },
+    "./convex": {
+      "types": "./dist/adapters/remote/convex.d.ts",
+      "import": "./dist/adapters/remote/convex.js",
+      "default": "./dist/adapters/remote/convex.js"
+    },
+    "./firebase": {
+      "types": "./dist/adapters/remote/firestore.d.ts",
+      "import": "./dist/adapters/remote/firestore.js",
+      "default": "./dist/adapters/remote/firestore.js"
+    },
+    "./backups": {
+      "types": "./dist/backups/index.d.ts",
+      "import": "./dist/backups/index.js",
+      "default": "./dist/backups/index.js"
+    },
+    "./expo-sqlite": {
+      "types": "./dist/adapters/local/expo-sqlite.d.ts",
+      "import": "./dist/adapters/local/expo-sqlite.js",
+      "default": "./dist/adapters/local/expo-sqlite.js"
+    },
+    "./op-sqlite": {
+      "types": "./dist/adapters/local/op-sqlite.d.ts",
+      "import": "./dist/adapters/local/op-sqlite.js",
+      "default": "./dist/adapters/local/op-sqlite.js"
+    },
+    "./better-sqlite3": {
+      "types": "./dist/adapters/local/better-sqlite3.d.ts",
+      "import": "./dist/adapters/local/better-sqlite3.js",
+      "default": "./dist/adapters/local/better-sqlite3.js"
+    },
+    "./libsql": {
+      "types": "./dist/adapters/local/libsql.d.ts",
+      "import": "./dist/adapters/local/libsql.js",
+      "default": "./dist/adapters/local/libsql.js"
+    },
+    "./sql-js": {
+      "types": "./dist/adapters/local/sql-js.d.ts",
+      "import": "./dist/adapters/local/sql-js.js",
+      "default": "./dist/adapters/local/sql-js.js"
+    },
+    "./node-sqlite": {
+      "types": "./dist/adapters/local/node-sqlite.d.ts",
+      "import": "./dist/adapters/local/node-sqlite.js",
+      "default": "./dist/adapters/local/node-sqlite.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@libsql/client": "^0.6.0",
+    "@op-engineering/op-sqlite": "^0.1.0",
+    "@supabase/supabase-js": "^2.0.0",
+    "better-sqlite3": "^8.0.0",
+    "convex": ">=1.0.0",
+    "expo-sqlite": ">=57.0.0",
+    "firebase": ">=9.0.0",
+    "react": ">=18.0.0",
+    "sql.js": "^1.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "convex": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    },
+    "expo-sqlite": {
+      "optional": true
+    },
+    "@op-engineering/op-sqlite": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    },
+    "sql.js": {
+      "optional": true
+    }
+  },
+  "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",
-    "react": "^19.3.1",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.5"
-  },
-  "dependencies": {
-    "uuid": "^14.0.3"
-  }
+    "@types/uuid": "^11.0.0",
+    "expo-sqlite": "^58.0.13",
+    "react": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.4.0",
+    "uuid": "^14.0.3"
+  }
 }