local-lite 0.0.3 → 0.0.4

package/dist/react/index.d.ts

@@ -1,6 +1,10 @@
-import { LocalFirstClient } from '../core/client.js';
-import { QueryOptions, SyncMetrics } from '../core/types.js';
+import { LocalFirstClient, TransactionalClient } from '../core/client.js';
+import { BatchMutation, MutateOptions, QueryOptions } from '../core/types.js';
 export type LiveQueryFn<T> = (client: LocalFirstClient) => Promise<T[]> | T[];
+/**
+ * Clears the in-memory live query cache.
+ */
+export declare function clearLiveQueryCache(): void;
 /**
  * Hook to execute a live reactive table query that automatically re-runs
  * whenever the table is mutated locally or via incoming remote delta.
@@ -24,25 +28,53 @@ export declare function useLiveQuery<T = any>(client: LocalFirstClient | null |
     refetch: () => Promise<void>;
     loading: boolean;
 };
-export interface UseSyncStatusResult {
-    isOnline: boolean;
-    isPushing: boolean;
-    isPulling: boolean;
-    isSyncing: boolean;
-    pendingCount: number;
-    pendingRecords: any[];
-    lastSyncedAt: number | null;
-    refresh: () => Promise<void>;
+/**
+ * Reactive hook to query a single record by primary key with 0ms cache read-through.
+ * Automatically re-renders only when this specific row or table changes.
+ */
+export declare function useLiveRow<T = any>(client: LocalFirstClient | null | undefined, tableName: string, rowId: string | null | undefined, options?: {
+    includeDeleted?: boolean;
+}): {
+    data: T | null;
+    refetch: () => Promise<void>;
+    loading: boolean;
+};
+export interface InfiniteQueryOptions extends QueryOptions {
+    pageSize?: number;
+}
+export interface UseLiveInfiniteQueryResult<T> {
+    data: T[];
+    loading: boolean;
+    isFetchingNextPage: boolean;
+    hasNextPage: boolean;
+    fetchNextPage: () => Promise<void>;
+    refetch: () => Promise<void>;
 }
 /**
- * Consolidated hook that tracks real-time sync connectivity, sync worker activity
- * (pushing/pulling/syncing), and pending items in the local SQLite outbox queue.
+ * Reactive infinite query hook that progressively loads pages of records
+ * with live updates when underlying table rows are inserted, updated, or synced.
  */
-export declare function useSyncStatus(client: LocalFirstClient | null | undefined): UseSyncStatusResult;
+export declare function useLiveInfiniteQuery<T = any>(client: LocalFirstClient | null | undefined, tableName: string, options?: InfiniteQueryOptions): UseLiveInfiniteQueryResult<T>;
+export interface UseMutationsResult<TTable extends string = string> {
+    client: LocalFirstClient | null | undefined;
+    insert: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), payload: T, options?: MutateOptions) => Promise<string | undefined>;
+    insertMany: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), records: T[], options?: MutateOptions) => Promise<string[] | undefined>;
+    update: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), rowId: string, payload: Partial<T>, options?: MutateOptions) => Promise<void>;
+    updateMany: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), updates: Array<{
+        id: string;
+        payload: Partial<T>;
+    }>, options?: MutateOptions) => Promise<void>;
+    delete: (tableName: TTable | (string & {}), rowId: string, options?: MutateOptions) => Promise<void>;
+    batch: (mutations: BatchMutation[]) => Promise<string[] | undefined>;
+    transaction: <T>(action: (txClient: TransactionalClient) => Promise<T>) => Promise<T | undefined>;
+}
 /**
- * Hook that provides real-time sync telemetry and engine performance metrics.
+ * Universal mutations hook providing memoized, null-safe helpers for database operations.
  */
-export declare function useSyncMetrics(client: LocalFirstClient | null | undefined, pollIntervalMs?: number): {
-    metrics: SyncMetrics | null;
-    refresh: () => Promise<void>;
-};
+export declare function useMutations<TTable extends string = string>(client: LocalFirstClient | null | undefined): UseMutationsResult<TTable>;
+export * from './runner.js';
+export * from './status.js';
+export * from './theme.js';
+export * from './BenchmarkModal.js';
+export { SyncInspector, SyncIndicator } from './SyncInspector.js';
+export type { SyncInspectorProps, SyncIndicatorProps } from './SyncInspector.js';

package/dist/react/index.js

@@ -1,9 +1,90 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncIndicator = exports.SyncInspector = void 0;
+exports.clearLiveQueryCache = clearLiveQueryCache;
 exports.useLiveQuery = useLiveQuery;
-exports.useSyncStatus = useSyncStatus;
-exports.useSyncMetrics = useSyncMetrics;
+exports.useLiveRow = useLiveRow;
+exports.useLiveInfiniteQuery = useLiveInfiniteQuery;
+exports.useMutations = useMutations;
 const react_1 = require("react");
+const runner_js_1 = require("./runner.js");
+function areRowsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b || typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    const aObj = a;
+    const bObj = b;
+    if (aObj.id !== undefined && bObj.id !== undefined && aObj.id !== bObj.id) {
+        return false;
+    }
+    if (aObj.updated_at !== undefined &&
+        bObj.updated_at !== undefined &&
+        aObj.updated_at !== bObj.updated_at) {
+        return false;
+    }
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (let i = 0; i < aKeys.length; i++) {
+        const k = aKeys[i];
+        const aVal = aObj[k];
+        const bVal = bObj[k];
+        if (aVal === bVal)
+            continue;
+        if (aVal &&
+            bVal &&
+            typeof aVal === 'object' &&
+            typeof bVal === 'object') {
+            if (Array.isArray(aVal) !== Array.isArray(bVal))
+                return false;
+            if (JSON.stringify(aVal) !== JSON.stringify(bVal))
+                return false;
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+function areRowArraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!areRowsEqual(a[i], b[i])) {
+            return false;
+        }
+    }
+    return true;
+}
+// In-memory query result cache to eliminate initial render latency and flickering
+const queryCache = new Map();
+const inFlightQueries = new Map();
+/**
+ * Clears the in-memory live query cache.
+ */
+function clearLiveQueryCache() {
+    queryCache.clear();
+    inFlightQueries.clear();
+}
 /**
  * Hook to execute a live reactive table query that automatically re-runs
  * whenever the table is mutated locally or via incoming remote delta.
@@ -23,32 +104,50 @@ const react_1 = require("react");
  *    const { data } = useLiveQuery(client, 'todos', (c) => c.db.execute('SELECT ...'));
  */
 function useLiveQuery(client, tableName, queryOrOptions) {
-    const [data, setData] = (0, react_1.useState)([]);
-    const [loading, setLoading] = (0, react_1.useState)(true);
+    const queryKey = typeof queryOrOptions === 'object' && queryOrOptions !== null
+        ? JSON.stringify(queryOrOptions)
+        : typeof queryOrOptions === 'function'
+            ? 'custom'
+            : 'all';
+    const cacheKey = `${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));
     const queryParamRef = (0, react_1.useRef)(queryOrOptions);
     queryParamRef.current = queryOrOptions;
     const refetch = (0, react_1.useCallback)(async () => {
         if (!client || !client.db)
             return;
         try {
-            const param = queryParamRef.current;
-            let res;
-            if (typeof param === 'function') {
-                res = (await param(client)) || [];
+            // De-duplicate simultaneous identical in-flight queries
+            let inFlight = inFlightQueries.get(cacheKey);
+            if (!inFlight) {
+                inFlight = (async () => {
+                    const param = queryParamRef.current;
+                    if (typeof param === 'function') {
+                        return (await param(client)) || [];
+                    }
+                    else if (typeof param === 'object' && param !== null) {
+                        return await client.findMany(tableName, param);
+                    }
+                    else {
+                        return await client.findMany(tableName);
+                    }
+                })();
+                inFlightQueries.set(cacheKey, inFlight);
+                inFlight.finally(() => {
+                    inFlightQueries.delete(cacheKey);
+                });
             }
-            else if (typeof param === 'object' && param !== null) {
-                res = await client.findMany(tableName, param);
-            }
-            else {
-                res = await client.findMany(tableName);
-            }
-            setData(res || []);
+            const res = (await inFlight) || [];
+            queryCache.set(cacheKey, res);
+            setData((prev) => (areRowArraysEqual(prev, res) ? prev : res));
         }
         catch (err) {
             const msg = String(err?.message || err || '');
             if (msg.includes('no such column') || msg.includes('no such table')) {
                 // Table or columns have not been populated yet on fresh database; default to empty list
-                setData([]);
+                setData((prev) => (prev.length === 0 ? prev : []));
             }
             else {
                 console.error(`Error in useLiveQuery("${tableName}"):`, err);
@@ -57,129 +156,190 @@ function useLiveQuery(client, tableName, queryOrOptions) {
         finally {
             setLoading(false);
         }
-    }, [client, tableName]);
+    }, [client, tableName, cacheKey]);
+    const scheduleRefetch = (0, runner_js_1.useCoalescedRunner)(refetch);
     (0, react_1.useEffect)(() => {
         if (!client || !client.db)
             return;
         refetch();
         const unsubscribe = client.events.on(tableName, () => {
-            refetch();
+            scheduleRefetch();
         });
         return () => {
             unsubscribe();
         };
-    }, [client, tableName, refetch]);
+    }, [client, tableName, queryKey, refetch, scheduleRefetch]);
     return { data, refetch, loading };
 }
 /**
- * Consolidated hook that tracks real-time sync connectivity, sync worker activity
- * (pushing/pulling/syncing), and pending items in the local SQLite outbox queue.
+ * Reactive hook to query a single record by primary key with 0ms cache read-through.
+ * Automatically re-renders only when this specific row or table changes.
  */
-function useSyncStatus(client) {
-    const [isOnline, setIsOnline] = (0, react_1.useState)(true);
-    const [isPushing, setIsPushing] = (0, react_1.useState)(false);
-    const [isPulling, setIsPulling] = (0, react_1.useState)(false);
-    const [pendingCount, setPendingCount] = (0, react_1.useState)(0);
-    const [pendingRecords, setPendingRecords] = (0, react_1.useState)([]);
-    const [lastSyncedAt, setLastSyncedAt] = (0, react_1.useState)(null);
-    const refresh = (0, react_1.useCallback)(async () => {
-        if (!client || !client.db)
+function useLiveRow(client, tableName, rowId, options) {
+    const cacheKey = `${tableName}:row:${rowId || 'null'}:${Boolean(options?.includeDeleted)}`;
+    const [data, setData] = (0, react_1.useState)(() => {
+        if (!rowId)
+            return null;
+        const cached = queryCache.get(cacheKey);
+        return cached && cached.length > 0 ? cached[0] : null;
+    });
+    const [loading, setLoading] = (0, react_1.useState)(() => Boolean(rowId && !queryCache.has(cacheKey)));
+    const refetch = (0, react_1.useCallback)(async () => {
+        if (!client || !client.db || !rowId) {
+            setData(null);
+            setLoading(false);
             return;
+        }
         try {
-            const [metrics, records, lastSynced] = await Promise.all([
-                client.getMetrics().catch(() => null),
-                client.getOutboxRecords().catch(() => []),
-                client.getLastSyncedAt().catch(() => null),
-            ]);
-            if (metrics) {
-                setIsOnline(metrics.isOnline);
-                setIsPushing(metrics.isPushing);
-                setIsPulling(metrics.isPulling);
+            let inFlight = inFlightQueries.get(cacheKey);
+            if (!inFlight) {
+                inFlight = client.findById(tableName, rowId, options).then((r) => (r ? [r] : []));
+                inFlightQueries.set(cacheKey, inFlight);
+                inFlight.finally(() => inFlightQueries.delete(cacheKey));
             }
-            if (records) {
-                setPendingRecords(records);
-                setPendingCount(records.filter((r) => r.status === 'PENDING').length);
+            const res = await inFlight;
+            const row = res.length > 0 ? res[0] : null;
+            if (row) {
+                queryCache.set(cacheKey, [row]);
             }
-            if (lastSynced !== null && lastSynced !== undefined) {
-                setLastSyncedAt(lastSynced > 0 ? lastSynced : null);
+            else {
+                queryCache.delete(cacheKey);
+            }
+            setData((prev) => (areRowsEqual(prev, row) ? prev : row));
+        }
+        catch (err) {
+            const msg = String(err?.message || err || '');
+            if (msg.includes('no such column') || msg.includes('no such table')) {
+                setData(null);
+            }
+            else {
+                console.error(`Error in useLiveRow("${tableName}", "${rowId}"):`, err);
             }
         }
-        catch {
-            // Ignored if client is stopping or tables initializing
+        finally {
+            setLoading(false);
         }
-    }, [client]);
+    }, [client, tableName, rowId, cacheKey]);
+    const scheduleRefetch = (0, runner_js_1.useCoalescedRunner)(refetch);
     (0, react_1.useEffect)(() => {
-        if (!client || !client.db)
+        if (!client || !client.db || !rowId)
             return;
-        refresh();
-        const unsubStatus = client.events.on('sync:status', (e) => {
-            setIsOnline(e.isOnline);
-            setIsPushing(e.isPushing);
-            setIsPulling(e.isPulling);
-            setPendingCount(e.pendingCount);
-        });
-        const unsubOutbox = client.events.on('sync_outbox', () => {
-            refresh();
-        });
-        const unsubPush = client.events.on('sync:push', () => {
-            refresh();
-        });
-        const unsubPull = client.events.on('sync:pull', () => {
-            refresh();
+        refetch();
+        const unsubscribe = client.events.on(tableName, (event) => {
+            // 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();
+            }
         });
         return () => {
-            unsubStatus();
-            unsubOutbox();
-            unsubPush();
-            unsubPull();
+            unsubscribe();
         };
-    }, [client, refresh]);
-    return {
-        isOnline,
-        isPushing,
-        isPulling,
-        isSyncing: isPushing || isPulling,
-        pendingCount,
-        pendingRecords,
-        lastSyncedAt,
-        refresh,
-    };
+    }, [client, tableName, rowId, refetch, scheduleRefetch]);
+    return { data, refetch, loading };
 }
 /**
- * Hook that provides real-time sync telemetry and engine performance metrics.
+ * Reactive infinite query hook that progressively loads pages of records
+ * with live updates when underlying table rows are inserted, updated, or synced.
  */
-function useSyncMetrics(client, pollIntervalMs = 3000) {
-    const [metrics, setMetrics] = (0, react_1.useState)(null);
-    const refresh = (0, react_1.useCallback)(async () => {
-        if (!client)
+function useLiveInfiniteQuery(client, tableName, options = {}) {
+    const pageSize = options.pageSize || options.limit || 25;
+    const [pageCount, setPageCount] = (0, react_1.useState)(1);
+    const [data, setData] = (0, react_1.useState)([]);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [isFetchingNextPage, setIsFetchingNextPage] = (0, react_1.useState)(false);
+    const [hasNextPage, setHasNextPage] = (0, react_1.useState)(true);
+    const optionsRef = (0, react_1.useRef)(options);
+    optionsRef.current = options;
+    const pageCountRef = (0, react_1.useRef)(pageCount);
+    pageCountRef.current = pageCount;
+    const loadData = (0, react_1.useCallback)(async (pages, isNextPage = false) => {
+        if (!client || !client.db)
             return;
+        if (isNextPage)
+            setIsFetchingNextPage(true);
         try {
-            const data = await client.getMetrics();
-            setMetrics(data);
+            const currentOpts = optionsRef.current;
+            const fetchLimit = pages * pageSize + 1; // +1 to check for hasNextPage
+            const rows = await client.findMany(tableName, {
+                ...currentOpts,
+                limit: fetchLimit,
+                offset: currentOpts.offset || 0,
+            });
+            if (rows.length > pages * pageSize) {
+                setHasNextPage(true);
+                setData(rows.slice(0, pages * pageSize));
+            }
+            else {
+                setHasNextPage(false);
+                setData(rows);
+            }
+        }
+        catch (err) {
+            const msg = String(err?.message || err || '');
+            if (msg.includes('no such column') || msg.includes('no such table')) {
+                setData([]);
+                setHasNextPage(false);
+            }
+            else {
+                console.error(`Error in useLiveInfiniteQuery("${tableName}"):`, err);
+            }
         }
-        catch {
-            // Ignored
+        finally {
+            setLoading(false);
+            if (isNextPage)
+                setIsFetchingNextPage(false);
         }
-    }, [client]);
+    }, [client, tableName, pageSize]);
+    const refetch = (0, react_1.useCallback)(async () => {
+        await loadData(pageCountRef.current, false);
+    }, [loadData]);
+    const scheduleRefetch = (0, runner_js_1.useCoalescedRunner)(refetch);
+    const fetchNextPage = (0, react_1.useCallback)(async () => {
+        if (!hasNextPage || isFetchingNextPage)
+            return;
+        const nextPages = pageCountRef.current + 1;
+        setPageCount(nextPages);
+        await loadData(nextPages, true);
+    }, [hasNextPage, isFetchingNextPage, loadData]);
     (0, react_1.useEffect)(() => {
-        if (!client)
+        if (!client || !client.db)
             return;
-        refresh();
-        // Listen to sync events for immediate refresh
-        const unsubs = [
-            client.events.on('sync:push', () => refresh()),
-            client.events.on('sync:pull', () => refresh()),
-            client.events.on('sync:status', () => refresh()),
-        ];
-        let timer;
-        if (pollIntervalMs > 0) {
-            timer = setInterval(refresh, pollIntervalMs);
-        }
+        loadData(1, false);
+        const unsubscribe = client.events.on(tableName, () => {
+            scheduleRefetch();
+        });
         return () => {
-            unsubs.forEach((u) => u());
-            if (timer)
-                clearInterval(timer);
+            unsubscribe();
         };
-    }, [client, refresh, pollIntervalMs]);
-    return { metrics, refresh };
+    }, [client, tableName, loadData, scheduleRefetch]);
+    return {
+        data,
+        loading,
+        isFetchingNextPage,
+        hasNextPage,
+        fetchNextPage,
+        refetch,
+    };
+}
+/**
+ * Universal mutations hook providing memoized, null-safe helpers for database operations.
+ */
+function useMutations(client) {
+    return (0, react_1.useMemo)(() => ({
+        client,
+        insert: (table, payload, opts) => client ? client.insert(table, payload, opts) : Promise.resolve(undefined),
+        insertMany: (table, records, opts) => client ? client.insertMany(table, records, opts) : Promise.resolve(undefined),
+        update: (table, id, payload, opts) => client ? client.update(table, id, payload, opts) : Promise.resolve(),
+        updateMany: (table, updates, opts) => client ? client.updateMany(table, updates, opts) : Promise.resolve(),
+        delete: (table, id, opts) => client ? client.delete(table, id, opts) : Promise.resolve(),
+        batch: (mutations) => client ? client.batch(mutations) : Promise.resolve(undefined),
+        transaction: (action) => client ? client.transaction(action) : Promise.resolve(undefined),
+    }), [client]);
 }
+__exportStar(require("./runner.js"), exports);
+__exportStar(require("./status.js"), exports);
+__exportStar(require("./theme.js"), exports);
+__exportStar(require("./BenchmarkModal.js"), exports);
+var SyncInspector_js_1 = require("./SyncInspector.js");
+Object.defineProperty(exports, "SyncInspector", { enumerable: true, get: function () { return SyncInspector_js_1.SyncInspector; } });
+Object.defineProperty(exports, "SyncIndicator", { enumerable: true, get: function () { return SyncInspector_js_1.SyncIndicator; } });

package/dist/react/runner.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a stable trigger that coalesces bursts of calls into a single run of `fn`.
+ * - Calls in the same tick collapse into one run scheduled on the next macrotask.
+ * - Calls while a run is in flight collapse into exactly one trailing run.
+ * This keeps reactive hooks from re-querying SQLite once per emitted row event.
+ */
+export declare function useCoalescedRunner(fn: () => Promise<void>): () => void;

package/dist/react/runner.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCoalescedRunner = useCoalescedRunner;
+const react_1 = require("react");
+/**
+ * Returns a stable trigger that coalesces bursts of calls into a single run of `fn`.
+ * - Calls in the same tick collapse into one run scheduled on the next macrotask.
+ * - Calls while a run is in flight collapse into exactly one trailing run.
+ * This keeps reactive hooks from re-querying SQLite once per emitted row event.
+ */
+function useCoalescedRunner(fn) {
+    const fnRef = (0, react_1.useRef)(fn);
+    fnRef.current = fn;
+    const state = (0, react_1.useRef)({
+        scheduled: false,
+        running: false,
+        rerun: false
+    });
+    return (0, react_1.useCallback)(() => {
+        const s = state.current;
+        if (s.running) {
+            s.rerun = true;
+            return;
+        }
+        if (s.scheduled)
+            return;
+        s.scheduled = true;
+        setTimeout(async () => {
+            s.scheduled = false;
+            s.running = true;
+            try {
+                do {
+                    s.rerun = false;
+                    await fnRef.current();
+                } while (s.rerun);
+            }
+            finally {
+                s.running = false;
+            }
+        }, 0);
+    }, []);
+}

package/dist/react/status.d.ts

@@ -0,0 +1,24 @@
+import { LocalFirstClient } from '../core/client.js';
+import { SyncMetrics } from '../core/types.js';
+export interface UseSyncStatusResult {
+    isOnline: boolean;
+    isPushing: boolean;
+    isPulling: boolean;
+    isSyncing: boolean;
+    pendingCount: number;
+    pendingRecords: any[];
+    lastSyncedAt: number | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Consolidated hook that tracks real-time sync connectivity, sync worker activity
+ * (pushing/pulling/syncing), and pending items in the local SQLite outbox queue.
+ */
+export declare function useSyncStatus(client: LocalFirstClient | null | undefined): UseSyncStatusResult;
+/**
+ * Hook that provides real-time sync telemetry and engine performance metrics.
+ */
+export declare function useSyncMetrics(client: LocalFirstClient | null | undefined, pollIntervalMs?: number): {
+    metrics: SyncMetrics | null;
+    refresh: () => Promise<void>;
+};