local-lite 0.0.1 → 0.0.3

package/dist/core/query.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesField = matchesField;
+exports.matchesWhere = matchesWhere;
+exports.applyQueryOptions = applyQueryOptions;
+/**
+ * Checks whether a single field value matches a field filter condition.
+ */
+function matchesField(fieldValue, filter) {
+    if (filter === undefined)
+        return true;
+    if (typeof filter === 'function') {
+        return filter(fieldValue);
+    }
+    // Direct primitive / reference equality
+    if (filter === null || typeof filter !== 'object') {
+        return fieldValue === filter;
+    }
+    // Operator object: $eq, $ne, $in, $nin, $gt, $gte, $lt, $lte, $contains, etc.
+    const ops = filter;
+    if (ops.$eq !== undefined && fieldValue !== ops.$eq) {
+        return false;
+    }
+    if (ops.$ne !== undefined && fieldValue === ops.$ne) {
+        return false;
+    }
+    if (ops.$in !== undefined) {
+        if (!Array.isArray(ops.$in) || !ops.$in.includes(fieldValue)) {
+            return false;
+        }
+    }
+    if (ops.$nin !== undefined) {
+        if (Array.isArray(ops.$nin) && ops.$nin.includes(fieldValue)) {
+            return false;
+        }
+    }
+    if (ops.$gt !== undefined && !(fieldValue > ops.$gt)) {
+        return false;
+    }
+    if (ops.$gte !== undefined && !(fieldValue >= ops.$gte)) {
+        return false;
+    }
+    if (ops.$lt !== undefined && !(fieldValue < ops.$lt)) {
+        return false;
+    }
+    if (ops.$lte !== undefined && !(fieldValue <= ops.$lte)) {
+        return false;
+    }
+    if (ops.$contains !== undefined) {
+        const str = fieldValue === null || fieldValue === undefined ? '' : String(fieldValue).toLowerCase();
+        const search = String(ops.$contains).toLowerCase();
+        if (!str.includes(search)) {
+            return false;
+        }
+    }
+    if (ops.$startsWith !== undefined) {
+        const str = fieldValue === null || fieldValue === undefined ? '' : String(fieldValue).toLowerCase();
+        const prefix = String(ops.$startsWith).toLowerCase();
+        if (!str.startsWith(prefix)) {
+            return false;
+        }
+    }
+    if (ops.$endsWith !== undefined) {
+        const str = fieldValue === null || fieldValue === undefined ? '' : String(fieldValue).toLowerCase();
+        const suffix = String(ops.$endsWith).toLowerCase();
+        if (!str.endsWith(suffix)) {
+            return false;
+        }
+    }
+    if (ops.$null !== undefined) {
+        const isNull = fieldValue === null || fieldValue === undefined;
+        if (ops.$null !== isNull) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Evaluates whether a given row matches a WhereFilter.
+ */
+function matchesWhere(row, where) {
+    if (!where)
+        return true;
+    if (typeof where === 'function') {
+        return where(row);
+    }
+    // Handle $or combinator
+    if ('$or' in where && Array.isArray(where.$or)) {
+        const orMatches = where.$or.some((subWhere) => matchesWhere(row, subWhere));
+        if (!orMatches)
+            return false;
+    }
+    // Handle $and combinator
+    if ('$and' in where && Array.isArray(where.$and)) {
+        const andMatches = where.$and.every((subWhere) => matchesWhere(row, subWhere));
+        if (!andMatches)
+            return false;
+    }
+    // Field-level conditions
+    for (const [key, filter] of Object.entries(where)) {
+        if (key === '$or' || key === '$and')
+            continue;
+        if (!matchesField(row[key], filter)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Applies in-memory filtering, sorting, offset, and limit to an array of rows.
+ */
+function applyQueryOptions(rows, options) {
+    if (!rows || rows.length === 0)
+        return [];
+    let result = [...rows];
+    // 1. Where filtering
+    if (options?.where) {
+        result = result.filter((row) => matchesWhere(row, options.where));
+    }
+    // 2. Order by
+    if (options?.orderBy) {
+        const key = options.orderBy;
+        const isAsc = (options.order || 'asc').toLowerCase() === 'asc';
+        result.sort((a, b) => {
+            const valA = a[key];
+            const valB = b[key];
+            if (valA === valB)
+                return 0;
+            if (valA === null || valA === undefined)
+                return isAsc ? 1 : -1;
+            if (valB === null || valB === undefined)
+                return isAsc ? -1 : 1;
+            if (typeof valA === 'string' && typeof valB === 'string') {
+                return isAsc ? valA.localeCompare(valB) : valB.localeCompare(valA);
+            }
+            if (typeof valA === 'number' && typeof valB === 'number') {
+                return isAsc ? valA - valB : valB - valA;
+            }
+            return isAsc ? (valA > valB ? 1 : -1) : (valA < valB ? 1 : -1);
+        });
+    }
+    // 3. Offset and Limit
+    if (options?.offset !== undefined && options.offset > 0) {
+        result = result.slice(options.offset);
+    }
+    if (options?.limit !== undefined && options.limit > 0) {
+        result = result.slice(0, options.limit);
+    }
+    return result;
+}

package/dist/core/sync-worker.d.ts

@@ -1,7 +1,7 @@
 import { LocalDBAdapter } from '../adapters/local/index.js';
 import { RemoteDBAdapter } from '../adapters/remote/index.js';
 import { EventEmitter } from '../reactive/event-emitter.js';
-import { ConflictResolver, ConflictStrategy, DeltaChanges, NetworkStatusProvider, RetryConfig } from './types.js';
+import { ConflictResolver, ConflictStrategy, DeltaChanges, NetworkStatusProvider, RetryConfig, SyncMetrics } from './types.js';
 import { SchemaManager } from './schema-manager.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 export interface SyncWorkerOptions {
@@ -40,6 +40,16 @@ export declare class SyncWorker {
     private lastPulledTimestamp;
     private cursorLoaded;
     private deltaQueue;
+    private totalPushedOperations;
+    private totalPulledDeltas;
+    private totalPushCycles;
+    private totalPullCycles;
+    private lastPushDurationMs;
+    private lastPullDurationMs;
+    private lastPushTimestamp;
+    private lastPullTimestamp;
+    private lastPushError;
+    private lastPullError;
     constructor(db: LocalDBAdapter, remote: RemoteDBAdapter, events: EventEmitter, options?: SyncWorkerOptions);
     /**
      * Starts background interval push/pull loops and listens for network & realtime updates.
@@ -54,6 +64,7 @@ export declare class SyncWorker {
      */
     schedulePush(delayMs?: number): void;
     private isOnline;
+    private emitStatus;
     /**
      * Pushes pending outbox records to the remote database.
      */
@@ -71,4 +82,8 @@ export declare class SyncWorker {
     private processDeltasLocally;
     getLastPulledTimestamp(): Promise<number>;
     resetSyncCursor(): Promise<void>;
+    /**
+     * Collects real-time engine telemetry snapshot.
+     */
+    getMetrics(): Promise<SyncMetrics>;
 }

package/dist/core/sync-worker.js

@@ -30,6 +30,17 @@ class SyncWorker {
     lastPulledTimestamp = 0;
     cursorLoaded = false;
     deltaQueue = Promise.resolve();
+    // Telemetry metrics
+    totalPushedOperations = 0;
+    totalPulledDeltas = 0;
+    totalPushCycles = 0;
+    totalPullCycles = 0;
+    lastPushDurationMs = 0;
+    lastPullDurationMs = 0;
+    lastPushTimestamp = 0;
+    lastPullTimestamp = 0;
+    lastPushError = null;
+    lastPullError = null;
     constructor(db, remote, events, options = {}) {
         this.db = db;
         this.remote = remote;
@@ -62,6 +73,7 @@ class SyncWorker {
                 initialDelayMs: 1000,
                 backoffMultiplier: 1.5,
                 maxDelayMs: 30000,
+                jitter: true,
             };
         }
         else if (typeof r === 'object' && r !== null) {
@@ -70,6 +82,7 @@ class SyncWorker {
                 initialDelayMs: r.initialDelayMs ?? 1000,
                 backoffMultiplier: r.backoffMultiplier ?? 1.5,
                 maxDelayMs: r.maxDelayMs ?? 30000,
+                jitter: r.jitter ?? true,
                 shouldRetry: r.shouldRetry,
             };
         }
@@ -79,6 +92,7 @@ class SyncWorker {
                 initialDelayMs: 1000,
                 backoffMultiplier: 1.5,
                 maxDelayMs: 30000,
+                jitter: true,
             };
         }
         this.maxRetries = this.retryConfig.maxRetries ?? 5;
@@ -98,6 +112,7 @@ class SyncWorker {
         });
         // Subscribe to network connectivity changes
         this.networkUnsubscribe = this.network.subscribe((online) => {
+            this.emitStatus();
             if (online) {
                 this.schedulePush(0);
                 this.pullRemoteChanges().catch((err) => {
@@ -109,6 +124,7 @@ class SyncWorker {
         this.pullRemoteChanges().catch((err) => {
             this.logger.error('Initial pull failed:', err);
         });
+        this.emitStatus();
     }
     /**
      * Stops all active intervals, timers, and listeners.
@@ -153,6 +169,22 @@ class SyncWorker {
             return true;
         }
     }
+    async emitStatus() {
+        try {
+            const online = await this.isOnline();
+            const counts = await outbox_store_js_1.OutboxStore.getCounts(this.db);
+            const statusEvent = {
+                isOnline: online,
+                isPushing: this.isPushing,
+                isPulling: this.isPulling,
+                pendingCount: counts.pending,
+            };
+            this.events.emit('sync:status', statusEvent);
+        }
+        catch {
+            // Ignored
+        }
+    }
     /**
      * Pushes pending outbox records to the remote database.
      */
@@ -162,8 +194,11 @@ class SyncWorker {
         if (!(await this.isOnline()))
             return;
         this.isPushing = true;
+        this.emitStatus();
+        const startTime = Date.now();
         let pendingRecords = [];
         try {
+            this.totalPushCycles++;
             pendingRecords = await outbox_store_js_1.OutboxStore.getPending(this.db, this.maxRetries);
             if (pendingRecords.length === 0) {
                 return;
@@ -180,23 +215,57 @@ class SyncWorker {
             // Mark records as PROCESSING
             await outbox_store_js_1.OutboxStore.markProcessing(this.db, recordIds);
             const success = await this.remote.pushChanges(operations);
+            const durationMs = Date.now() - startTime;
+            this.lastPushDurationMs = durationMs;
+            this.lastPushTimestamp = Date.now();
             if (success) {
                 // Successful push: delete rows from outbox
                 await outbox_store_js_1.OutboxStore.deleteCompleted(this.db, recordIds);
+                this.totalPushedOperations += operations.length;
+                this.lastPushError = null;
+                const pushEvent = {
+                    success: true,
+                    count: operations.length,
+                    durationMs,
+                    error: null,
+                };
+                this.events.emit('sync:push', pushEvent);
                 this.events.emit('sync_outbox', { operation: 'DELETE', rowId: 'batch' });
             }
             else {
-                await this.handlePushFailure(pendingRecords, 'Remote push returned false');
+                const errMsg = 'Remote push returned false';
+                this.lastPushError = errMsg;
+                const pushEvent = {
+                    success: false,
+                    count: operations.length,
+                    durationMs,
+                    error: errMsg,
+                };
+                this.events.emit('sync:push', pushEvent);
+                await this.handlePushFailure(pendingRecords, errMsg);
             }
         }
         catch (error) {
+            const durationMs = Date.now() - startTime;
+            this.lastPushDurationMs = durationMs;
+            this.lastPushTimestamp = Date.now();
+            const errMsg = error?.message || String(error);
+            this.lastPushError = errMsg;
             this.logger.error('Sync Engine Outbox Push Error:', error);
+            const pushEvent = {
+                success: false,
+                count: pendingRecords.length,
+                durationMs,
+                error: errMsg,
+            };
+            this.events.emit('sync:push', pushEvent);
             if (pendingRecords.length > 0) {
-                await this.handlePushFailure(pendingRecords, error?.message || String(error), error);
+                await this.handlePushFailure(pendingRecords, errMsg, error);
             }
         }
         finally {
             this.isPushing = false;
+            this.emitStatus();
         }
     }
     async handlePushFailure(records, errorMessage, errorObj) {
@@ -212,12 +281,17 @@ class SyncWorker {
                     }
                 }
             }
-            // Schedule next retry with exponential backoff
+            // Schedule next retry with exponential backoff & optional jitter
             const currentRetry = Math.max(...records.map((r) => r.retryCount || 0));
             const isInfinite = !Number.isFinite(this.maxRetries) || this.maxRetries === -1;
             if (isInfinite || currentRetry < this.maxRetries) {
-                const backoffDelay = Math.min((this.retryConfig.initialDelayMs || 1000) *
+                let backoffDelay = Math.min((this.retryConfig.initialDelayMs || 1000) *
                     Math.pow(this.retryConfig.backoffMultiplier || 1.5, currentRetry), this.retryConfig.maxDelayMs || 30000);
+                // Apply ±15% jitter if enabled to avoid synchronized retry stampedes
+                if (this.retryConfig.jitter !== false) {
+                    const jitterFactor = 0.85 + Math.random() * 0.3;
+                    backoffDelay = Math.round(backoffDelay * jitterFactor);
+                }
                 this.schedulePush(backoffDelay);
             }
         }
@@ -234,21 +308,52 @@ class SyncWorker {
         if (!(await this.isOnline()))
             return;
         this.isPulling = true;
+        this.emitStatus();
+        const startTime = Date.now();
         try {
+            this.totalPullCycles++;
             if (!this.cursorLoaded) {
                 this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db);
                 this.cursorLoaded = true;
             }
             const deltas = await this.remote.fetchChanges(this.lastPulledTimestamp);
+            const durationMs = Date.now() - startTime;
+            this.lastPullDurationMs = durationMs;
+            this.lastPullTimestamp = Date.now();
+            this.lastPullError = null;
+            const changesCount = deltas?.changes?.length || 0;
             if (deltas) {
+                this.totalPulledDeltas += changesCount;
                 await this.applyDeltasLocally(deltas);
             }
+            const pullEvent = {
+                success: true,
+                changesCount,
+                durationMs,
+                timestamp: this.lastPulledTimestamp,
+                error: null,
+            };
+            this.events.emit('sync:pull', pullEvent);
         }
         catch (error) {
+            const durationMs = Date.now() - startTime;
+            this.lastPullDurationMs = durationMs;
+            this.lastPullTimestamp = Date.now();
+            const errMsg = error?.message || String(error);
+            this.lastPullError = errMsg;
             this.logger.error('Sync Engine Delta Pull Error:', error);
+            const pullEvent = {
+                success: false,
+                changesCount: 0,
+                durationMs,
+                timestamp: this.lastPulledTimestamp,
+                error: errMsg,
+            };
+            this.events.emit('sync:pull', pullEvent);
         }
         finally {
             this.isPulling = false;
+            this.emitStatus();
         }
     }
     /**
@@ -286,6 +391,14 @@ class SyncWorker {
                         localOutboxRecord: localPendingRecord,
                         localRow,
                     }));
+                    const resolutionStr = typeof resolution === 'string' ? resolution : 'merge';
+                    const conflictEvent = {
+                        tableName: change.tableName,
+                        rowId: change.rowId,
+                        resolution: resolutionStr,
+                        timestamp: Date.now(),
+                    };
+                    this.events.emit('sync:conflict', conflictEvent);
                     if (resolution === 'keep-local') {
                         // Local offline change takes precedence
                         continue;
@@ -331,5 +444,30 @@ class SyncWorker {
         this.lastPulledTimestamp = 0;
         this.cursorLoaded = true;
     }
+    /**
+     * Collects real-time engine telemetry snapshot.
+     */
+    async getMetrics() {
+        const counts = await outbox_store_js_1.OutboxStore.getCounts(this.db);
+        const online = await this.isOnline();
+        return {
+            outboxPendingCount: counts.pending,
+            outboxFailedCount: counts.failed,
+            outboxProcessingCount: counts.processing,
+            totalPushedOperations: this.totalPushedOperations,
+            totalPulledDeltas: this.totalPulledDeltas,
+            totalPushCycles: this.totalPushCycles,
+            totalPullCycles: this.totalPullCycles,
+            lastPushDurationMs: this.lastPushDurationMs,
+            lastPullDurationMs: this.lastPullDurationMs,
+            lastPushTimestamp: this.lastPushTimestamp,
+            lastPullTimestamp: this.lastPullTimestamp,
+            lastPushError: this.lastPushError,
+            lastPullError: this.lastPullError,
+            isOnline: online,
+            isPushing: this.isPushing,
+            isPulling: this.isPulling,
+        };
+    }
 }
 exports.SyncWorker = SyncWorker;

package/dist/core/types.d.ts

@@ -49,6 +49,8 @@ export interface RetryConfig {
     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;
 }
@@ -64,10 +66,91 @@ export interface TableChangeEvent {
     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?: Record<string, any>;
+    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/index.d.ts

@@ -1,5 +1,6 @@
 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';
@@ -11,7 +12,7 @@ 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 type * from './react/index.js';
 export * from './utils/uuid.js';
 export * from './utils/sql.js';
 export * from './utils/logger.js';

package/dist/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 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);
@@ -27,7 +28,6 @@ __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

@@ -1,5 +1,5 @@
 import { LocalFirstClient } from '../core/client.js';
-import { QueryOptions } from '../core/types.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
@@ -9,9 +9,9 @@ export type LiveQueryFn<T> = (client: LocalFirstClient) => Promise<T[]> | T[];
  * 1. Zero-SQL (all rows):
  *    const { data: todos } = useLiveQuery<Todo>(client, 'todos');
  *
- * 2. Declarative options (filtering & sorting without SQL):
+ * 2. Declarative options (filtering with rich operators & sorting without SQL):
  *    const { data: active } = useLiveQuery<Todo>(client, 'todos', {
- *      where: { completed: 0 },
+ *      where: { completed: 0, priority: { $gte: 2 } },
  *      orderBy: 'created_at',
  *      order: 'desc'
  *    });
@@ -24,11 +24,25 @@ export declare function useLiveQuery<T = any>(client: LocalFirstClient | null |
     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): {
+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>;
 };