local-lite 0.0.0-stage → 0.0.2

package/dist/adapters/local/node-sqlite.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeSQLiteAdapter = void 0;
+/**
+ * Adapter for Node.js 22+ built-in `node:sqlite` (DatabaseSync).
+ * Provides zero-dependency, native SQLite on modern Node.js runtimes.
+ */
+class NodeSQLiteAdapter {
+    db;
+    constructor(nodeSqliteDb) {
+        this.db = nodeSqliteDb;
+    }
+    async execute(query, params = []) {
+        const trimmed = query.trim();
+        const stmt = this.db.prepare(trimmed);
+        // Queries that return rows (SELECT, PRAGMA)
+        if (/^SELECT|^PRAGMA/i.test(trimmed)) {
+            return stmt.all(...params);
+        }
+        const res = stmt.run(...params);
+        return [res];
+    }
+    async transaction(action) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const txWrapper = {
+                execute: async (q, p = []) => this.execute(q, p),
+            };
+            const result = await action(txWrapper);
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (err) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // ignore rollback errors
+            }
+            throw err;
+        }
+    }
+}
+exports.NodeSQLiteAdapter = NodeSQLiteAdapter;

package/dist/adapters/local/op-sqlite.d.ts

@@ -0,0 +1,26 @@
+import { LocalDBAdapter, LocalTransaction } from './index.js';
+export interface OpSQLiteQueryResult {
+    rows?: {
+        _array?: any[];
+        length?: number;
+        item?: (i: number) => any;
+    } | any[];
+    insertId?: number;
+    rowsAffected?: number;
+}
+export interface OpSQLiteDatabase {
+    executeAsync(query: string, params?: any[]): Promise<OpSQLiteQueryResult>;
+    transactionAsync(action: (tx: any) => Promise<void>): Promise<void>;
+    close?: () => void;
+}
+/**
+ * Adapter for @op-engineering/op-sqlite and react-native-quick-sqlite.
+ * Enables ultra-fast C++ JSI SQLite in bare React Native.
+ */
+export declare class OpSQLiteAdapter implements LocalDBAdapter {
+    private db;
+    private txMutex;
+    constructor(opSqliteInstance: any);
+    execute(query: string, params?: any[]): Promise<any[]>;
+    transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
+}

package/dist/adapters/local/op-sqlite.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpSQLiteAdapter = void 0;
+function extractRows(res) {
+    if (!res)
+        return [];
+    if (Array.isArray(res))
+        return res;
+    if (res.rows) {
+        if (Array.isArray(res.rows))
+            return res.rows;
+        if (res.rows._array && Array.isArray(res.rows._array))
+            return res.rows._array;
+        if (typeof res.rows.length === 'number' && typeof res.rows.item === 'function') {
+            const arr = [];
+            for (let i = 0; i < res.rows.length; i++) {
+                arr.push(res.rows.item(i));
+            }
+            return arr;
+        }
+    }
+    return [];
+}
+/**
+ * Adapter for @op-engineering/op-sqlite and react-native-quick-sqlite.
+ * Enables ultra-fast C++ JSI SQLite in bare React Native.
+ */
+class OpSQLiteAdapter {
+    db;
+    txMutex = Promise.resolve();
+    constructor(opSqliteInstance) {
+        this.db = opSqliteInstance;
+    }
+    async execute(query, params = []) {
+        const res = await this.db.executeAsync(query, params);
+        return extractRows(res);
+    }
+    async transaction(action) {
+        const run = async () => {
+            let result;
+            await this.db.transactionAsync(async (txInstance) => {
+                const txWrapper = {
+                    execute: async (q, p = []) => {
+                        const res = typeof txInstance.executeAsync === 'function'
+                            ? await txInstance.executeAsync(q, p)
+                            : await txInstance.execute(q, p);
+                        return extractRows(res);
+                    },
+                };
+                result = await action(txWrapper);
+            });
+            return result;
+        };
+        const currentTx = this.txMutex.then(run, run);
+        this.txMutex = currentTx.catch(() => { });
+        return await currentTx;
+    }
+}
+exports.OpSQLiteAdapter = OpSQLiteAdapter;

package/dist/adapters/local/sql-js.d.ts

@@ -0,0 +1,26 @@
+import { LocalDBAdapter, LocalTransaction } from './index.js';
+export interface SqlJsStatement {
+    bind(values?: any[]): boolean;
+    step(): boolean;
+    getAsObject(params?: any[]): Record<string, any>;
+    free(): boolean;
+}
+export interface SqlJsDatabase {
+    prepare(sql: string, params?: any[]): SqlJsStatement;
+    exec(sql: string, params?: any[]): Array<{
+        columns: string[];
+        values: any[][];
+    }>;
+    run(sql: string, params?: any[]): void;
+    export?(): Uint8Array;
+    close?(): void;
+}
+/**
+ * Adapter for sql.js (WebAssembly SQLite in Web Browsers, PWAs, and Expo Web).
+ */
+export declare class SqlJsAdapter implements LocalDBAdapter {
+    private db;
+    constructor(sqlJsDatabase: any);
+    execute(query: string, params?: any[]): Promise<any[]>;
+    transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
+}

package/dist/adapters/local/sql-js.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlJsAdapter = void 0;
+/**
+ * Adapter for sql.js (WebAssembly SQLite in Web Browsers, PWAs, and Expo Web).
+ */
+class SqlJsAdapter {
+    db;
+    constructor(sqlJsDatabase) {
+        this.db = sqlJsDatabase;
+    }
+    async execute(query, params = []) {
+        const trimmed = query.trim();
+        // If there are no parameters, db.exec is fastest
+        if (!params || params.length === 0) {
+            const results = this.db.exec(trimmed);
+            if (!results || results.length === 0)
+                return [];
+            const { columns, values } = results[0];
+            return values.map((row) => {
+                const obj = {};
+                columns.forEach((col, idx) => {
+                    obj[col] = row[idx];
+                });
+                return obj;
+            });
+        }
+        // For parameterized queries, use Statement with bind & getAsObject
+        const stmt = this.db.prepare(trimmed);
+        try {
+            stmt.bind(params);
+            const rows = [];
+            while (stmt.step()) {
+                rows.push(stmt.getAsObject());
+            }
+            return rows;
+        }
+        finally {
+            stmt.free();
+        }
+    }
+    async transaction(action) {
+        this.db.run('BEGIN TRANSACTION;');
+        try {
+            const txWrapper = {
+                execute: async (q, p = []) => this.execute(q, p),
+            };
+            const result = await action(txWrapper);
+            this.db.run('COMMIT;');
+            return result;
+        }
+        catch (err) {
+            try {
+                this.db.run('ROLLBACK;');
+            }
+            catch {
+                // ignore rollback errors
+            }
+            throw err;
+        }
+    }
+}
+exports.SqlJsAdapter = SqlJsAdapter;

package/dist/adapters/network/index.d.ts

@@ -0,0 +1,11 @@
+import { NetworkStatusProvider } from '../../core/types.js';
+export declare class DefaultNetworkStatusProvider implements NetworkStatusProvider {
+    private _isOnline;
+    private listeners;
+    private cleanupBrowserListeners?;
+    constructor(initialOnline?: boolean);
+    isOnline(): boolean;
+    setOnline(status: boolean): void;
+    subscribe(callback: (isOnline: boolean) => void): () => void;
+    destroy(): void;
+}

package/dist/adapters/network/index.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultNetworkStatusProvider = void 0;
+class DefaultNetworkStatusProvider {
+    _isOnline = true;
+    listeners = new Set();
+    cleanupBrowserListeners;
+    constructor(initialOnline = true) {
+        this._isOnline = initialOnline;
+        if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+            if (typeof navigator !== 'undefined' && typeof navigator.onLine === 'boolean') {
+                this._isOnline = navigator.onLine;
+            }
+            const onOnline = () => this.setOnline(true);
+            const onOffline = () => this.setOnline(false);
+            window.addEventListener('online', onOnline);
+            window.addEventListener('offline', onOffline);
+            this.cleanupBrowserListeners = () => {
+                window.removeEventListener('online', onOnline);
+                window.removeEventListener('offline', onOffline);
+            };
+        }
+    }
+    isOnline() {
+        return this._isOnline;
+    }
+    setOnline(status) {
+        if (this._isOnline !== status) {
+            this._isOnline = status;
+            for (const listener of this.listeners) {
+                try {
+                    listener(status);
+                }
+                catch (err) {
+                    console.error('Error in network listener:', err);
+                }
+            }
+        }
+    }
+    subscribe(callback) {
+        this.listeners.add(callback);
+        return () => {
+            this.listeners.delete(callback);
+        };
+    }
+    destroy() {
+        if (this.cleanupBrowserListeners) {
+            this.cleanupBrowserListeners();
+        }
+        this.listeners.clear();
+    }
+}
+exports.DefaultNetworkStatusProvider = DefaultNetworkStatusProvider;

package/dist/adapters/remote/convex.d.ts

@@ -0,0 +1,71 @@
+import { RemoteDBAdapter } from './index.js';
+import { DeltaChanges, SyncOperation } from '../../core/types.js';
+import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+export interface ConvexRemoteAdapterOptions {
+    /**
+     * Tables synchronized with Convex.
+     */
+    tables?: string[];
+    /**
+     * Primary key field name. Default: 'id' (or falls back to '_id').
+     */
+    primaryKey?: string;
+    /**
+     * Name or function reference for Convex push mutation.
+     * Default: 'sync:pushBatch'
+     */
+    pushMutation?: any;
+    /**
+     * Name or function reference for Convex delta pull query.
+     * Default: 'sync:pullDeltas'
+     */
+    pullQuery?: any;
+    /**
+     * Column used for soft deletes. Default: 'deleted'
+     */
+    deletedColumn?: string;
+    /**
+     * Column used for updated timestamps. Default: 'updatedAt'
+     */
+    updatedAtColumn?: string;
+    /**
+     * Custom logger or false to silence logs in production.
+     */
+    logger?: SyncLogger | CustomLogger | boolean;
+    /**
+     * Minimum log level. Default: 'info'
+     */
+    logLevel?: LogLevel;
+}
+export declare class ConvexRemoteAdapter implements RemoteDBAdapter {
+    private client;
+    private tables;
+    private primaryKey;
+    private pushMutation;
+    private pullQuery;
+    private deletedColumn;
+    private updatedAtColumn;
+    private unsubscribeLive?;
+    logger: SyncLogger;
+    constructor(client: any, options?: ConvexRemoteAdapterOptions);
+    /**
+     * Dynamically update tracked tables.
+     */
+    setTables(tables: string[]): void;
+    /**
+     * Pushes outbox operations as a batch mutation to Convex.
+     */
+    pushChanges(operations: SyncOperation[]): Promise<boolean>;
+    /**
+     * Fetches delta changes from Convex since a given timestamp.
+     */
+    fetchChanges(sinceTimestamp: number): Promise<DeltaChanges>;
+    /**
+     * Subscribes to live reactive query updates from Convex.
+     */
+    subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
+    /**
+     * Cleans up live subscriptions.
+     */
+    destroy(): void;
+}

package/dist/adapters/remote/convex.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConvexRemoteAdapter = void 0;
+const logger_js_1 = require("../../utils/logger.js");
+class ConvexRemoteAdapter {
+    client;
+    tables;
+    primaryKey;
+    pushMutation;
+    pullQuery;
+    deletedColumn;
+    updatedAtColumn;
+    unsubscribeLive;
+    logger;
+    constructor(client, options = {}) {
+        if (!client) {
+            throw new Error('ConvexRemoteAdapter requires a ConvexClient instance.');
+        }
+        this.client = client;
+        this.tables = options.tables ?? [];
+        this.primaryKey = options.primaryKey ?? 'id';
+        this.pushMutation = options.pushMutation ?? 'sync:pushBatch';
+        this.pullQuery = options.pullQuery ?? 'sync:pullDeltas';
+        this.deletedColumn = options.deletedColumn ?? 'deleted';
+        this.updatedAtColumn = options.updatedAtColumn ?? 'updatedAt';
+        if (options.logger instanceof logger_js_1.SyncLogger) {
+            this.logger = options.logger;
+        }
+        else if (typeof options.logger === 'boolean') {
+            this.logger = new logger_js_1.SyncLogger({ enabled: options.logger, level: options.logLevel });
+        }
+        else if (options.logger && typeof options.logger === 'object') {
+            this.logger = new logger_js_1.SyncLogger({ customLogger: options.logger, level: options.logLevel });
+        }
+        else {
+            this.logger = options.logLevel ? new logger_js_1.SyncLogger({ level: options.logLevel }) : logger_js_1.defaultLogger;
+        }
+    }
+    /**
+     * Dynamically update tracked tables.
+     */
+    setTables(tables) {
+        this.tables = tables;
+    }
+    /**
+     * Pushes outbox operations as a batch mutation to Convex.
+     */
+    async pushChanges(operations) {
+        if (!operations || operations.length === 0) {
+            return true;
+        }
+        try {
+            const payload = operations.map((op) => ({
+                id: op.id,
+                tableName: op.tableName,
+                rowId: op.rowId,
+                operation: op.operation,
+                payload: op.payload,
+                timestamp: op.timestamp,
+            }));
+            const res = await this.client.mutation(this.pushMutation, {
+                operations: payload,
+            });
+            return res !== false;
+        }
+        catch (error) {
+            this.logger.error((0, logger_js_1.formatConvexError)(error, { operation: 'pushChanges' }));
+            return false;
+        }
+    }
+    /**
+     * Fetches delta changes from Convex since a given timestamp.
+     */
+    async fetchChanges(sinceTimestamp) {
+        try {
+            const res = await this.client.query(this.pullQuery, {
+                sinceTimestamp,
+                tables: this.tables,
+            });
+            if (!res) {
+                return { timestamp: sinceTimestamp, changes: [] };
+            }
+            // 1. If backend returns structured DeltaChanges { timestamp, changes }
+            if (res.changes && Array.isArray(res.changes)) {
+                return {
+                    timestamp: Number(res.timestamp || sinceTimestamp),
+                    changes: res.changes,
+                };
+            }
+            // 2. If backend returns an array of updated documents
+            if (Array.isArray(res)) {
+                let maxServerTimestamp = sinceTimestamp;
+                const changes = [];
+                for (const row of res) {
+                    const isSoftDeleted = Boolean(row[this.deletedColumn] === true ||
+                        row[this.deletedColumn] === 1 ||
+                        (row[this.deletedColumn] &&
+                            !['false', '0', 'null', 'undefined'].includes(String(row[this.deletedColumn]).toLowerCase())));
+                    const operation = isSoftDeleted ? 'DELETE' : 'UPDATE';
+                    const rowTime = Number(row[this.updatedAtColumn] || row._creationTime || Date.now());
+                    if (rowTime > maxServerTimestamp) {
+                        maxServerTimestamp = rowTime;
+                    }
+                    const rowId = String(row[this.primaryKey] || row._id || row.id);
+                    const tableName = row.tableName || row._table || (this.tables.length === 1 ? this.tables[0] : 'default');
+                    changes.push({
+                        tableName,
+                        operation,
+                        rowId,
+                        payload: isSoftDeleted ? null : row,
+                        timestamp: rowTime,
+                    });
+                }
+                return {
+                    timestamp: changes.length > 0 ? maxServerTimestamp : sinceTimestamp,
+                    changes,
+                };
+            }
+            return { timestamp: sinceTimestamp, changes: [] };
+        }
+        catch (error) {
+            this.logger.error((0, logger_js_1.formatConvexError)(error, { operation: 'fetchChanges' }));
+            return { timestamp: sinceTimestamp, changes: [] };
+        }
+    }
+    /**
+     * Subscribes to live reactive query updates from Convex.
+     */
+    subscribeToLiveChanges(callback) {
+        if (typeof this.client.onUpdate !== 'function') {
+            return;
+        }
+        if (this.unsubscribeLive) {
+            this.unsubscribeLive();
+            this.unsubscribeLive = undefined;
+        }
+        try {
+            this.unsubscribeLive = this.client.onUpdate(this.pullQuery, { sinceTimestamp: Date.now() - 2000, tables: this.tables }, (data) => {
+                if (!data)
+                    return;
+                if (data.changes && Array.isArray(data.changes)) {
+                    callback({
+                        timestamp: Number(data.timestamp || Date.now()),
+                        changes: data.changes,
+                    });
+                    return;
+                }
+                if (Array.isArray(data) && data.length > 0) {
+                    const changes = data.map((row) => {
+                        const isSoftDeleted = Boolean(row[this.deletedColumn] === true);
+                        const op = isSoftDeleted ? 'DELETE' : 'UPDATE';
+                        const rowTime = Number(row[this.updatedAtColumn] || row._creationTime || Date.now());
+                        const rowId = String(row[this.primaryKey] || row._id || row.id);
+                        const tableName = row.tableName || row._table || (this.tables[0] ?? 'default');
+                        return {
+                            tableName,
+                            operation: op,
+                            rowId,
+                            payload: isSoftDeleted ? null : row,
+                            timestamp: rowTime,
+                        };
+                    });
+                    const maxTime = Math.max(...changes.map((c) => c.timestamp || 0));
+                    callback({
+                        timestamp: maxTime > 0 ? maxTime : Date.now(),
+                        changes,
+                    });
+                }
+            });
+        }
+        catch (err) {
+            console.warn('ConvexRemoteAdapter live subscription failed to initialize:', err);
+        }
+    }
+    /**
+     * Cleans up live subscriptions.
+     */
+    destroy() {
+        if (this.unsubscribeLive) {
+            this.unsubscribeLive();
+            this.unsubscribeLive = undefined;
+        }
+    }
+}
+exports.ConvexRemoteAdapter = ConvexRemoteAdapter;

package/dist/adapters/remote/demo.d.ts

@@ -0,0 +1,21 @@
+import { RemoteDBAdapter } from './index.js';
+import { DeltaChanges, SyncOperation } from '../../core/types.js';
+/**
+ * Built-in In-Memory Demo Remote Adapter.
+ * Useful for prototyping, offline testing, and previewing without a live backend.
+ */
+export declare class MemoryDemoRemoteAdapter implements RemoteDBAdapter {
+    pushedBatches: SyncOperation[][];
+    allPushedOperations: SyncOperation[];
+    private liveSubscribers;
+    private simulatedLatencyMs;
+    constructor(simulatedLatencyMs?: number);
+    pushChanges(operations: SyncOperation[]): Promise<boolean>;
+    fetchChanges(_sinceTimestamp: number): Promise<DeltaChanges>;
+    subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
+    /**
+     * Manually emit simulated server deltas to subscribers.
+     */
+    emitLiveChanges(changes: DeltaChanges): void;
+    clear(): void;
+}

package/dist/adapters/remote/demo.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryDemoRemoteAdapter = void 0;
+/**
+ * Built-in In-Memory Demo Remote Adapter.
+ * Useful for prototyping, offline testing, and previewing without a live backend.
+ */
+class MemoryDemoRemoteAdapter {
+    pushedBatches = [];
+    allPushedOperations = [];
+    liveSubscribers = [];
+    simulatedLatencyMs;
+    constructor(simulatedLatencyMs = 300) {
+        this.simulatedLatencyMs = simulatedLatencyMs;
+    }
+    async pushChanges(operations) {
+        if (this.simulatedLatencyMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, this.simulatedLatencyMs));
+        }
+        this.pushedBatches.push(operations);
+        this.allPushedOperations.push(...operations);
+        return true;
+    }
+    async fetchChanges(_sinceTimestamp) {
+        return {
+            timestamp: Date.now(),
+            changes: [],
+        };
+    }
+    subscribeToLiveChanges(callback) {
+        this.liveSubscribers.push(callback);
+    }
+    /**
+     * Manually emit simulated server deltas to subscribers.
+     */
+    emitLiveChanges(changes) {
+        for (const sub of this.liveSubscribers) {
+            sub(changes);
+        }
+    }
+    clear() {
+        this.pushedBatches = [];
+        this.allPushedOperations = [];
+    }
+}
+exports.MemoryDemoRemoteAdapter = MemoryDemoRemoteAdapter;

package/dist/adapters/remote/firestore.d.ts

@@ -0,0 +1,64 @@
+import { RemoteDBAdapter } from './index.js';
+import { DeltaChanges, SyncOperation } from '../../core/types.js';
+import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+export interface FirestoreAdapterOptions {
+    /**
+     * Collections (tables) synchronized with Firestore.
+     * e.g. ['properties', 'tenants']
+     */
+    tables?: string[];
+    /**
+     * Primary key field name in documents. Default: 'id'
+     */
+    primaryKey?: string;
+    /**
+     * Field used for soft deletes. Default: 'deleted'
+     */
+    deletedColumn?: string;
+    /**
+     * Field used for updated timestamp tracking. Default: 'updatedAt'
+     */
+    updatedAtColumn?: string;
+    /**
+     * Optional reference to modular firebase/firestore SDK if not globally available.
+     */
+    firestoreModule?: any;
+    /**
+     * Custom logger or false to silence logs in production.
+     */
+    logger?: SyncLogger | CustomLogger | boolean;
+    /**
+     * Minimum log level. Default: 'info'
+     */
+    logLevel?: LogLevel;
+}
+export declare class FirestoreRemoteAdapter implements RemoteDBAdapter {
+    private db;
+    private tables;
+    private primaryKey;
+    private deletedColumn;
+    private updatedAtColumn;
+    private firestoreModule;
+    private unsubscribers;
+    logger: SyncLogger;
+    constructor(db: any, options?: FirestoreAdapterOptions);
+    setTables(tables: string[]): void;
+    private getModule;
+    /**
+     * Pushes outbox operations as batch writes to Firestore.
+     * Chunks operations into batches of 450 (below Firestore 500-write limit).
+     */
+    pushChanges(operations: SyncOperation[]): Promise<boolean>;
+    /**
+     * Fetches delta changes across tracked collections where updatedAt > sinceTimestamp.
+     */
+    fetchChanges(sinceTimestamp: number): Promise<DeltaChanges>;
+    /**
+     * Subscribes to live real-time query updates via onSnapshot.
+     */
+    subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
+    /**
+     * Cleans up all active real-time listeners.
+     */
+    destroy(): void;
+}