local-lite 0.0.0-stage → 0.0.2

package/dist/core/types.d.ts

@@ -0,0 +1,156 @@
+export type SyncOp = 'INSERT' | 'UPDATE' | 'DELETE';
+export type OutboxStatus = 'PENDING' | 'PROCESSING' | 'FAILED';
+export interface SyncOperation {
+    id: string;
+    tableName: string;
+    rowId: string;
+    operation: SyncOp;
+    payload: Record<string, any> | null;
+    timestamp: number;
+}
+export interface OutboxRecord extends SyncOperation {
+    status: OutboxStatus;
+    retryCount: number;
+    lastError?: string | null;
+}
+export interface DeltaChange {
+    tableName: string;
+    operation: SyncOp;
+    rowId: string;
+    payload: Record<string, any> | null;
+    timestamp?: number;
+}
+export interface DeltaChanges {
+    timestamp: number;
+    changes: DeltaChange[];
+}
+export type ConflictResolution = 'apply-remote' | 'keep-local' | {
+    mergePayload: Record<string, any>;
+};
+export interface ConflictContext {
+    tableName: string;
+    rowId: string;
+    remoteChange: DeltaChange;
+    localOutboxRecord?: OutboxRecord;
+    localRow?: Record<string, any> | null;
+}
+export type ConflictResolver = (context: ConflictContext) => ConflictResolution | Promise<ConflictResolution>;
+export type ConflictStrategy = 'last-write-wins' | 'server-wins' | 'client-wins';
+export interface NetworkStatusProvider {
+    isOnline(): boolean | Promise<boolean>;
+    subscribe(callback: (isOnline: boolean) => void): () => void;
+}
+export interface RetryConfig {
+    /** Maximum retry attempts before marking outbox record as permanently FAILED. Set to `Infinity` or `-1` for infinite retries. Default: 5 */
+    maxRetries?: number;
+    /** Initial delay before retrying failed operations in milliseconds. Default: 1000 */
+    initialDelayMs?: number;
+    /** Backoff multiplier applied on consecutive failures (e.g. 2 for exponential). Default: 1.5 */
+    backoffMultiplier?: number;
+    /** Maximum capped delay between retries in milliseconds. Default: 30000 */
+    maxDelayMs?: number;
+    /** Whether to apply randomized jitter (±20%) to backoff delays to prevent thundering herd. Default: true */
+    jitter?: boolean;
+    /** Custom predicate deciding whether an error is retryable. Return false for non-retryable errors like permanent RLS violations. */
+    shouldRetry?: (error: any, operation: SyncOperation) => boolean;
+}
+export interface MutateOptions {
+    primaryKey?: string;
+    tx?: any;
+    customTimestamp?: number;
+    skipOutbox?: boolean;
+}
+export interface TableChangeEvent {
+    operation: SyncOp;
+    rowId: string;
+    payload?: Record<string, any> | null;
+    source: 'local' | 'remote';
+}
+/**
+ * Filter operator comparison options for query predicates.
+ */
+export interface ComparisonOperator<T = any> {
+    $eq?: T;
+    $ne?: T;
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $in?: T[];
+    $nin?: T[];
+    $contains?: string;
+    $startsWith?: string;
+    $endsWith?: string;
+    $null?: boolean;
+}
+export type FieldFilter<T = any> = T | ComparisonOperator<T> | ((value: T) => boolean);
+export type WhereFilter = Record<string, FieldFilter> | ((row: Record<string, any>) => boolean) | {
+    $or?: (Record<string, FieldFilter> | ((row: Record<string, any>) => boolean))[];
+    $and?: (Record<string, FieldFilter> | ((row: Record<string, any>) => boolean))[];
+    [key: string]: any;
+};
+export interface QueryOptions {
+    where?: WhereFilter;
+    orderBy?: string;
+    order?: 'asc' | 'desc' | 'ASC' | 'DESC';
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Individual mutation descriptor for atomic batch execution.
+ */
+export interface BatchMutation {
+    tableName: string;
+    rowId?: string;
+    operation: SyncOp;
+    payload?: Record<string, any> | null;
+    primaryKey?: string;
+    skipOutbox?: boolean;
+    customTimestamp?: number;
+}
+/**
+ * Real-time operational telemetry metrics captured by the sync engine.
+ */
+export interface SyncMetrics {
+    outboxPendingCount: number;
+    outboxFailedCount: number;
+    outboxProcessingCount: number;
+    totalPushedOperations: number;
+    totalPulledDeltas: number;
+    totalPushCycles: number;
+    totalPullCycles: number;
+    lastPushDurationMs: number;
+    lastPullDurationMs: number;
+    lastPushTimestamp: number;
+    lastPullTimestamp: number;
+    lastPushError?: string | null;
+    lastPullError?: string | null;
+    isOnline: boolean;
+    isPushing: boolean;
+    isPulling: boolean;
+}
+export interface SyncStatusEvent {
+    isOnline: boolean;
+    isPushing: boolean;
+    isPulling: boolean;
+    pendingCount: number;
+}
+export interface PushEvent {
+    success: boolean;
+    count: number;
+    durationMs: number;
+    error?: string | null;
+}
+export interface PullEvent {
+    success: boolean;
+    changesCount: number;
+    durationMs: number;
+    timestamp: number;
+    error?: string | null;
+}
+export interface ConflictEvent {
+    tableName: string;
+    rowId: string;
+    resolution: string;
+    timestamp: number;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * from './core/client.js';
+export * from './core/types.js';
+export * from './core/query.js';
+export * from './core/sync-worker.js';
+export * from './core/conflict.js';
+export * from './core/outbox-store.js';
+export * from './core/meta-store.js';
+export * from './core/table-manager.js';
+export * from './core/schema-manager.js';
+export * from './reactive/event-emitter.js';
+export * from './adapters/local/index.js';
+export * from './adapters/remote/index.js';
+export * from './adapters/network/index.js';
+export * from './config/index.js';
+export * from './react/index.js';
+export * from './utils/uuid.js';
+export * from './utils/sql.js';
+export * from './utils/logger.js';

package/dist/index.js

@@ -0,0 +1,34 @@
+"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 });
+__exportStar(require("./core/client.js"), exports);
+__exportStar(require("./core/types.js"), exports);
+__exportStar(require("./core/query.js"), exports);
+__exportStar(require("./core/sync-worker.js"), exports);
+__exportStar(require("./core/conflict.js"), exports);
+__exportStar(require("./core/outbox-store.js"), exports);
+__exportStar(require("./core/meta-store.js"), exports);
+__exportStar(require("./core/table-manager.js"), exports);
+__exportStar(require("./core/schema-manager.js"), exports);
+__exportStar(require("./reactive/event-emitter.js"), exports);
+__exportStar(require("./adapters/local/index.js"), exports);
+__exportStar(require("./adapters/remote/index.js"), exports);
+__exportStar(require("./adapters/network/index.js"), exports);
+__exportStar(require("./config/index.js"), exports);
+__exportStar(require("./react/index.js"), exports);
+__exportStar(require("./utils/uuid.js"), exports);
+__exportStar(require("./utils/sql.js"), exports);
+__exportStar(require("./utils/logger.js"), exports);

package/dist/react/index.d.ts

@@ -0,0 +1,50 @@
+import { LocalFirstClient } from '../core/client.js';
+import { QueryOptions, SyncMetrics } from '../core/types.js';
+export type LiveQueryFn<T> = (client: LocalFirstClient) => Promise<T[]> | T[];
+/**
+ * Hook to execute a live reactive table query that automatically re-runs
+ * whenever the table is mutated locally or via incoming remote delta.
+ *
+ * Supports 3 flexible usage patterns:
+ * 1. Zero-SQL (all rows):
+ *    const { data: todos } = useLiveQuery<Todo>(client, 'todos');
+ *
+ * 2. Declarative options (filtering with rich operators & sorting without SQL):
+ *    const { data: active } = useLiveQuery<Todo>(client, 'todos', {
+ *      where: { completed: 0, priority: { $gte: 2 } },
+ *      orderBy: 'created_at',
+ *      order: 'desc'
+ *    });
+ *
+ * 3. Custom query callback (advanced raw SQL / joins):
+ *    const { data } = useLiveQuery(client, 'todos', (c) => c.db.execute('SELECT ...'));
+ */
+export declare function useLiveQuery<T = any>(client: LocalFirstClient | null | undefined, tableName: string, queryOrOptions?: LiveQueryFn<T> | QueryOptions): {
+    data: T[];
+    refetch: () => Promise<void>;
+    loading: boolean;
+};
+/**
+ * Hook that tracks the status and pending items in sync_outbox in real time.
+ */
+export declare function useOutboxStatus(client: LocalFirstClient | null | undefined): {
+    pendingCount: number;
+    pendingRecords: any[];
+    refresh: () => Promise<void>;
+};
+/**
+ * Hook that tracks real-time sync connectivity and sync worker activity (pushing/pulling).
+ */
+export declare function useSyncStatus(client: LocalFirstClient | null | undefined): {
+    isOnline: boolean;
+    isPushing: boolean;
+    isPulling: boolean;
+    pendingCount: number;
+};
+/**
+ * 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>;
+};

package/dist/react/index.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLiveQuery = useLiveQuery;
+exports.useOutboxStatus = useOutboxStatus;
+exports.useSyncStatus = useSyncStatus;
+exports.useSyncMetrics = useSyncMetrics;
+const react_1 = require("react");
+/**
+ * Hook to execute a live reactive table query that automatically re-runs
+ * whenever the table is mutated locally or via incoming remote delta.
+ *
+ * Supports 3 flexible usage patterns:
+ * 1. Zero-SQL (all rows):
+ *    const { data: todos } = useLiveQuery<Todo>(client, 'todos');
+ *
+ * 2. Declarative options (filtering with rich operators & sorting without SQL):
+ *    const { data: active } = useLiveQuery<Todo>(client, 'todos', {
+ *      where: { completed: 0, priority: { $gte: 2 } },
+ *      orderBy: 'created_at',
+ *      order: 'desc'
+ *    });
+ *
+ * 3. Custom query callback (advanced raw SQL / joins):
+ *    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 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)) || [];
+            }
+            else if (typeof param === 'object' && param !== null) {
+                res = await client.findMany(tableName, param);
+            }
+            else {
+                res = await client.findMany(tableName);
+            }
+            setData(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([]);
+            }
+            else {
+                console.error(`Error in useLiveQuery("${tableName}"):`, err);
+            }
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, tableName]);
+    (0, react_1.useEffect)(() => {
+        if (!client || !client.db)
+            return;
+        refetch();
+        const unsubscribe = client.events.on(tableName, () => {
+            refetch();
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client, tableName, refetch]);
+    return { data, refetch, loading };
+}
+/**
+ * Hook that tracks the status and pending items in sync_outbox in real time.
+ */
+function useOutboxStatus(client) {
+    const [pendingCount, setPendingCount] = (0, react_1.useState)(0);
+    const [pendingRecords, setPendingRecords] = (0, react_1.useState)([]);
+    const refresh = (0, react_1.useCallback)(async () => {
+        if (!client || !client.db)
+            return;
+        try {
+            const records = await client.getOutboxRecords();
+            setPendingRecords(records || []);
+            setPendingCount(records.filter((r) => r.status === 'PENDING').length);
+        }
+        catch {
+            // Ignored if table doesn't exist yet
+        }
+    }, [client]);
+    (0, react_1.useEffect)(() => {
+        if (!client || !client.db)
+            return;
+        refresh();
+        const unsubscribe = client.events.on('sync_outbox', () => {
+            refresh();
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client, refresh]);
+    return { pendingCount, pendingRecords, refresh };
+}
+/**
+ * Hook that tracks real-time sync connectivity and sync worker activity (pushing/pulling).
+ */
+function useSyncStatus(client) {
+    const [status, setStatus] = (0, react_1.useState)({
+        isOnline: true,
+        isPushing: false,
+        isPulling: false,
+        pendingCount: 0,
+    });
+    (0, react_1.useEffect)(() => {
+        if (!client)
+            return;
+        // Fetch initial metrics
+        client.getMetrics().then((m) => {
+            setStatus({
+                isOnline: m.isOnline,
+                isPushing: m.isPushing,
+                isPulling: m.isPulling,
+                pendingCount: m.outboxPendingCount,
+            });
+        }).catch(() => { });
+        const unsubscribe = client.events.on('sync:status', (e) => {
+            setStatus(e);
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client]);
+    return status;
+}
+/**
+ * Hook that provides real-time sync telemetry and engine performance metrics.
+ */
+function useSyncMetrics(client, pollIntervalMs = 3000) {
+    const [metrics, setMetrics] = (0, react_1.useState)(null);
+    const refresh = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        try {
+            const data = await client.getMetrics();
+            setMetrics(data);
+        }
+        catch {
+            // Ignored
+        }
+    }, [client]);
+    (0, react_1.useEffect)(() => {
+        if (!client)
+            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);
+        }
+        return () => {
+            unsubs.forEach((u) => u());
+            if (timer)
+                clearInterval(timer);
+        };
+    }, [client, refresh, pollIntervalMs]);
+    return { metrics, refresh };
+}

package/dist/reactive/event-emitter.d.ts

@@ -0,0 +1,7 @@
+type EventCallback = (data: any) => void;
+export declare class EventEmitter {
+    private listeners;
+    on(event: string, callback: EventCallback): () => void;
+    emit(event: string, data: any): void;
+}
+export {};

package/dist/reactive/event-emitter.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventEmitter = void 0;
+class EventEmitter {
+    listeners = new Map();
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => {
+            const eventSet = this.listeners.get(event);
+            if (eventSet) {
+                eventSet.delete(callback);
+                if (eventSet.size === 0)
+                    this.listeners.delete(event);
+            }
+        };
+    }
+    emit(event, data) {
+        const eventSet = this.listeners.get(event);
+        if (eventSet) {
+            eventSet.forEach(callback => {
+                try {
+                    callback(data);
+                }
+                catch (err) {
+                    console.error("Emitter error:", err);
+                }
+            });
+        }
+    }
+}
+exports.EventEmitter = EventEmitter;

package/dist/utils/logger.d.ts

@@ -0,0 +1,51 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export interface CustomLogger {
+    debug?(message: string, ...args: any[]): void;
+    info?(message: string, ...args: any[]): void;
+    warn?(message: string, ...args: any[]): void;
+    error?(message: string, ...args: any[]): void;
+}
+export interface LoggerConfig {
+    level?: LogLevel;
+    customLogger?: CustomLogger;
+    enabled?: boolean;
+}
+export declare class SyncLogger {
+    private level;
+    private customLogger?;
+    private enabled;
+    constructor(config?: LoggerConfig | boolean);
+    setLevel(level: LogLevel): void;
+    setEnabled(enabled: boolean): void;
+    setCustomLogger(logger?: CustomLogger): void;
+    private shouldLog;
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * Global default logger instance.
+ */
+export declare const defaultLogger: SyncLogger;
+/**
+ * Translates PostgreSQL / Supabase PostgREST error codes into actionable, human-readable explanations.
+ */
+export declare function formatSupabaseError(error: any, context?: {
+    table?: string;
+    operation?: string;
+}): string;
+/**
+ * Translates Firestore error codes into human-readable explanations.
+ */
+export declare function formatFirestoreError(error: any, context?: {
+    collection?: string;
+    operation?: string;
+}): string;
+/**
+ * Translates Convex error codes into human-readable explanations.
+ */
+export declare function formatConvexError(error: any, context?: {
+    table?: string;
+    operation?: string;
+}): string;