local-lite 0.0.0-stage → 0.0.2

package/dist/core/client.js

@@ -0,0 +1,445 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalFirstClient = exports.TransactionalClient = void 0;
+const event_emitter_js_1 = require("../reactive/event-emitter.js");
+const sync_worker_js_1 = require("./sync-worker.js");
+const table_manager_js_1 = require("./table-manager.js");
+const outbox_store_js_1 = require("./outbox-store.js");
+const meta_store_js_1 = require("./meta-store.js");
+const schema_manager_js_1 = require("./schema-manager.js");
+const uuid_js_1 = require("../utils/uuid.js");
+const sql_js_1 = require("../utils/sql.js");
+const query_js_1 = require("./query.js");
+class TransactionalClient {
+    parent;
+    tx;
+    queuedTableEvents;
+    queuedOutboxIds;
+    constructor(parent, tx, queuedTableEvents, queuedOutboxIds) {
+        this.parent = parent;
+        this.tx = tx;
+        this.queuedTableEvents = queuedTableEvents;
+        this.queuedOutboxIds = queuedOutboxIds;
+    }
+    async mutate(tableName, rowId, operation, payload, options = {}) {
+        const pk = options.primaryKey ?? this.parent.getPrimaryKey();
+        const outboxId = (0, uuid_js_1.generateUUID)();
+        const timestamp = options.customTimestamp ?? Date.now();
+        await table_manager_js_1.TableManager.applyMutation(this.tx, tableName, rowId, operation, payload, pk, {
+            autoSchema: this.parent.autoSchema,
+            schemaManager: this.parent.schemaManager,
+        });
+        if (!options.skipOutbox) {
+            await outbox_store_js_1.OutboxStore.insertRecord(this.tx, {
+                id: outboxId,
+                tableName,
+                rowId,
+                operation,
+                payload,
+                timestamp,
+            });
+            this.queuedOutboxIds.push(outboxId);
+        }
+        this.queuedTableEvents.push({
+            tableName,
+            event: {
+                operation,
+                rowId,
+                payload,
+                source: 'local',
+            },
+        });
+    }
+    async insert(tableName, rowIdOrPayload, payloadOrOptions, options) {
+        let rowId;
+        let payload;
+        let opts = {};
+        if (typeof rowIdOrPayload === 'string') {
+            rowId = rowIdOrPayload;
+            payload = payloadOrOptions || {};
+            opts = options || {};
+        }
+        else {
+            payload = rowIdOrPayload || {};
+            rowId = payload[this.parent.getPrimaryKey()] || (0, uuid_js_1.generateUUID)();
+            opts = payloadOrOptions || {};
+        }
+        await this.mutate(tableName, rowId, 'INSERT', payload, opts);
+        return rowId;
+    }
+    async update(tableName, rowId, payload, options = {}) {
+        await this.mutate(tableName, rowId, 'UPDATE', payload, options);
+    }
+    async delete(tableName, rowId, options = {}) {
+        await this.mutate(tableName, rowId, 'DELETE', null, options);
+    }
+    get rawTx() {
+        return this.tx;
+    }
+}
+exports.TransactionalClient = TransactionalClient;
+class LocalFirstClient {
+    db;
+    remote;
+    events;
+    syncWorker;
+    schemaManager;
+    autoSchema;
+    tables;
+    primaryKey;
+    constructor(config) {
+        this.db = config.local;
+        this.remote = config.remote;
+        this.events = new event_emitter_js_1.EventEmitter();
+        this.primaryKey = config.primaryKey ?? 'id';
+        this.autoSchema = config.autoSchema ?? false;
+        this.tables = config.tables ?? [];
+        this.schemaManager = new schema_manager_js_1.SchemaManager();
+        const workerOptions = {
+            network: config.network,
+            conflictResolver: config.conflictResolver,
+            primaryKey: this.primaryKey,
+            pushIntervalMs: config.pushIntervalMs,
+            pullIntervalMs: config.pullIntervalMs,
+            maxRetries: config.maxRetries,
+            retry: config.retry,
+            logger: config.logger,
+            logLevel: config.logLevel,
+            autoSchema: this.autoSchema,
+            schemaManager: this.schemaManager,
+        };
+        this.syncWorker = new sync_worker_js_1.SyncWorker(this.db, this.remote, this.events, workerOptions);
+    }
+    getPrimaryKey() {
+        return this.primaryKey;
+    }
+    /**
+     * Initializes the client: creates sync_outbox schema, ensures autoSchema tables if enabled,
+     * and starts the background sync worker.
+     */
+    async initialize() {
+        await outbox_store_js_1.OutboxStore.ensureSchema(this.db);
+        await meta_store_js_1.MetaStore.ensureSchema(this.db);
+        await outbox_store_js_1.OutboxStore.resetStaleProcessing(this.db);
+        if (this.autoSchema && this.tables.length > 0) {
+            for (const table of this.tables) {
+                await this.schemaManager.ensureTable(this.db, table, this.primaryKey);
+            }
+        }
+        this.syncWorker.start();
+    }
+    /**
+     * Performs an atomic dual-write: mutates the local data table AND writes
+     * to sync_outbox within the same database transaction.
+     */
+    async mutate(tableName, rowId, operation, payload, options = {}) {
+        const pk = options.primaryKey ?? this.primaryKey;
+        const outboxId = (0, uuid_js_1.generateUUID)();
+        const timestamp = options.customTimestamp ?? Date.now();
+        const executeInTransaction = async (tx) => {
+            // 1. Mutate local table
+            await table_manager_js_1.TableManager.applyMutation(tx, tableName, rowId, operation, payload, pk, {
+                autoSchema: this.autoSchema,
+                schemaManager: this.schemaManager,
+            });
+            // 2. Insert into sync_outbox (if not skipped)
+            if (!options.skipOutbox) {
+                await outbox_store_js_1.OutboxStore.insertRecord(tx, {
+                    id: outboxId,
+                    tableName,
+                    rowId,
+                    operation,
+                    payload,
+                    timestamp,
+                });
+            }
+        };
+        if (options.tx) {
+            await executeInTransaction(options.tx);
+        }
+        else {
+            await this.db.transaction(executeInTransaction);
+        }
+        // 3. Emit reactive change events
+        this.events.emit(tableName, {
+            operation,
+            rowId,
+            payload,
+            source: 'local',
+        });
+        if (!options.skipOutbox) {
+            this.events.emit('sync_outbox', { operation: 'INSERT', rowId: outboxId });
+            // 4. Trigger immediate debounced push
+            this.syncWorker.schedulePush(20);
+        }
+    }
+    /**
+     * Executes multiple mutations in a single atomic database transaction.
+     * Inserts all corresponding outbox entries together and schedules a single push.
+     */
+    async batch(mutations, options = {}) {
+        if (!mutations || mutations.length === 0)
+            return [];
+        const generatedIds = [];
+        const queuedEvents = [];
+        const queuedOutboxIds = [];
+        const executeInTx = async (tx) => {
+            for (const m of mutations) {
+                const pk = m.primaryKey ?? options.primaryKey ?? this.primaryKey;
+                const payload = m.payload ?? null;
+                const rowId = m.rowId ||
+                    (payload && payload[pk] !== undefined && payload[pk] !== null
+                        ? String(payload[pk])
+                        : (0, uuid_js_1.generateUUID)());
+                generatedIds.push(rowId);
+                await table_manager_js_1.TableManager.applyMutation(tx, m.tableName, rowId, m.operation, payload, pk, {
+                    autoSchema: this.autoSchema,
+                    schemaManager: this.schemaManager,
+                });
+                const skipOutbox = m.skipOutbox ?? options.skipOutbox ?? false;
+                if (!skipOutbox) {
+                    const outboxId = (0, uuid_js_1.generateUUID)();
+                    const timestamp = m.customTimestamp ?? options.customTimestamp ?? Date.now();
+                    await outbox_store_js_1.OutboxStore.insertRecord(tx, {
+                        id: outboxId,
+                        tableName: m.tableName,
+                        rowId,
+                        operation: m.operation,
+                        payload,
+                        timestamp,
+                    });
+                    queuedOutboxIds.push(outboxId);
+                }
+                queuedEvents.push({
+                    tableName: m.tableName,
+                    event: {
+                        operation: m.operation,
+                        rowId,
+                        payload,
+                        source: 'local',
+                    },
+                });
+            }
+        };
+        if (options.tx) {
+            await executeInTx(options.tx);
+        }
+        else {
+            await this.db.transaction(executeInTx);
+        }
+        // Emit all buffered events after transaction commits
+        for (const item of queuedEvents) {
+            this.events.emit(item.tableName, item.event);
+        }
+        if (queuedOutboxIds.length > 0) {
+            this.events.emit('sync_outbox', { operation: 'INSERT', rowId: 'batch' });
+            this.syncWorker.schedulePush(20);
+        }
+        return generatedIds;
+    }
+    /**
+     * Convenience helper to insert an array of records into a table atomically.
+     */
+    async insertMany(tableName, records, options = {}) {
+        const pk = options.primaryKey ?? this.primaryKey;
+        const mutations = records.map((record) => {
+            const rowId = record[pk] || (0, uuid_js_1.generateUUID)();
+            return {
+                tableName,
+                rowId,
+                operation: 'INSERT',
+                payload: record,
+                primaryKey: pk,
+            };
+        });
+        return await this.batch(mutations, options);
+    }
+    /**
+     * Runs an arbitrary callback inside an atomic transaction with a scoped TransactionalClient.
+     * If the callback resolves, all changes and outbox records commit and events are emitted.
+     * If the callback throws, SQLite rolls back and no change events are emitted.
+     */
+    async transaction(action) {
+        const queuedEvents = [];
+        const queuedOutboxIds = [];
+        const result = await this.db.transaction(async (tx) => {
+            const txClient = new TransactionalClient(this, tx, queuedEvents, queuedOutboxIds);
+            return await action(txClient);
+        });
+        for (const item of queuedEvents) {
+            this.events.emit(item.tableName, item.event);
+        }
+        if (queuedOutboxIds.length > 0) {
+            this.events.emit('sync_outbox', { operation: 'INSERT', rowId: 'batch' });
+            this.syncWorker.schedulePush(20);
+        }
+        return result;
+    }
+    /**
+     * Convenience helper to insert a record into a table.
+     * Auto-generates a UUID if rowId is omitted or passed inside payload.
+     *
+     * Example:
+     * await client.insert('todos', { title: 'Buy milk' });
+     * await client.insert('todos', 'custom-id', { title: 'Buy milk' });
+     */
+    async insert(tableName, rowIdOrPayload, payloadOrOptions, options) {
+        let rowId;
+        let payload;
+        let opts = {};
+        if (typeof rowIdOrPayload === 'string') {
+            rowId = rowIdOrPayload;
+            payload = payloadOrOptions || {};
+            opts = options || {};
+        }
+        else {
+            payload = rowIdOrPayload || {};
+            rowId = payload[this.primaryKey] || (0, uuid_js_1.generateUUID)();
+            opts = payloadOrOptions || {};
+        }
+        await this.mutate(tableName, rowId, 'INSERT', payload, opts);
+        return rowId;
+    }
+    /**
+     * Convenience helper to update an existing record by ID.
+     *
+     * Example:
+     * await client.update('todos', 'todo-1', { completed: 1 });
+     */
+    async update(tableName, rowId, payload, options = {}) {
+        await this.mutate(tableName, rowId, 'UPDATE', payload, options);
+    }
+    /**
+     * Convenience helper to delete a record by ID.
+     *
+     * Example:
+     * await client.delete('todos', 'todo-1');
+     */
+    async delete(tableName, rowId, options = {}) {
+        await this.mutate(tableName, rowId, 'DELETE', null, options);
+    }
+    /**
+     * Reads records from a local SQLite table without requiring manual SQL.
+     * Supports where filtering with rich operators ($in, $gt, $contains, $or, etc.), order, limit, and offset.
+     * Gracefully returns [] if table or columns have not been populated yet on empty schemas.
+     *
+     * Example:
+     * const tenants = await client.findMany('tenants', { where: { status: 'ACTIVE' }, orderBy: 'name' });
+     * const expensive = await client.findMany('properties', { where: { rent: { $gte: 2000 } } });
+     */
+    async findMany(tableName, options) {
+        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+        let rows;
+        try {
+            rows = await this.db.execute(`SELECT * FROM ${safeTable}`);
+        }
+        catch (err) {
+            const msg = String(err?.message || err || '');
+            if (msg.includes('no such table') || msg.includes('no such column')) {
+                return [];
+            }
+            throw err;
+        }
+        return (0, query_js_1.applyQueryOptions)(rows, options);
+    }
+    /**
+     * Finds a single record by primary key.
+     *
+     * Example:
+     * const tenant = await client.findById('tenants', 'ten-1');
+     */
+    async findById(tableName, id) {
+        const results = await this.findMany(tableName, {
+            where: { [this.primaryKey]: id },
+            limit: 1,
+        });
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Tracks an existing mutation into sync_outbox without modifying the table.
+     * Can accept an external transaction `options.tx` for custom atomic SQL workflows.
+     */
+    async trackMutation(tableName, rowId, operation, payload, options = {}) {
+        const outboxId = (0, uuid_js_1.generateUUID)();
+        const timestamp = options.customTimestamp ?? Date.now();
+        const executeInsert = async (tx) => {
+            await outbox_store_js_1.OutboxStore.insertRecord(tx, {
+                id: outboxId,
+                tableName,
+                rowId,
+                operation,
+                payload,
+                timestamp,
+            });
+        };
+        if (options.tx) {
+            await executeInsert(options.tx);
+        }
+        else {
+            await this.db.transaction(executeInsert);
+        }
+        this.events.emit(tableName, {
+            operation,
+            rowId,
+            payload,
+            source: 'local',
+        });
+        this.events.emit('sync_outbox', { operation: 'INSERT', rowId: outboxId });
+        this.syncWorker.schedulePush(20);
+        return outboxId;
+    }
+    /**
+     * Returns real-time telemetry metrics captured by the sync engine.
+     */
+    async getMetrics() {
+        return await this.syncWorker.getMetrics();
+    }
+    /**
+     * Fetches outbox records with optional status filtering and pagination.
+     */
+    async getOutboxRecords(options) {
+        return await outbox_store_js_1.OutboxStore.getAllRecords(this.db, options);
+    }
+    /**
+     * Re-queues failed outbox mutations for retry by resetting their status to PENDING.
+     * Triggers an immediate sync push.
+     */
+    async retryFailedMutations(ids) {
+        const count = await outbox_store_js_1.OutboxStore.retryFailed(this.db, ids);
+        if (count > 0) {
+            this.events.emit('sync_outbox', { operation: 'UPDATE', rowId: 'retry' });
+            this.syncWorker.schedulePush(0);
+        }
+        return count;
+    }
+    /**
+     * Permanently clears failed mutations (removes poison-pill outbox records).
+     */
+    async clearFailedMutations(ids) {
+        const count = await outbox_store_js_1.OutboxStore.clearFailed(this.db, ids);
+        if (count > 0) {
+            this.events.emit('sync_outbox', { operation: 'DELETE', rowId: 'clear' });
+        }
+        return count;
+    }
+    /**
+     * Retrieves the persisted last_synced_at timestamp cursor (in ms).
+     */
+    async getLastSyncedAt() {
+        return await this.syncWorker.getLastPulledTimestamp();
+    }
+    /**
+     * Resets the persistent sync cursor back to 0, forcing the next pull
+     * to query all remote records.
+     */
+    async resetSyncCursor() {
+        await this.syncWorker.resetSyncCursor();
+    }
+    /**
+     * Stops all active intervals, background sync loops, and network listeners.
+     */
+    stop() {
+        this.syncWorker.stop();
+    }
+}
+exports.LocalFirstClient = LocalFirstClient;

package/dist/core/conflict.d.ts

@@ -0,0 +1,5 @@
+import { ConflictResolver, ConflictStrategy } from './types.js';
+export declare const lastWriteWinsResolver: ConflictResolver;
+export declare const serverWinsResolver: ConflictResolver;
+export declare const clientWinsResolver: ConflictResolver;
+export declare function getConflictResolver(strategyOrResolver?: ConflictStrategy | ConflictResolver): ConflictResolver;

package/dist/core/conflict.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientWinsResolver = exports.serverWinsResolver = exports.lastWriteWinsResolver = void 0;
+exports.getConflictResolver = getConflictResolver;
+const lastWriteWinsResolver = (context) => {
+    const remoteTime = context.remoteChange.timestamp ?? 0;
+    const localTime = context.localOutboxRecord?.timestamp ?? 0;
+    if (remoteTime >= localTime) {
+        return 'apply-remote';
+    }
+    return 'keep-local';
+};
+exports.lastWriteWinsResolver = lastWriteWinsResolver;
+const serverWinsResolver = () => {
+    return 'apply-remote';
+};
+exports.serverWinsResolver = serverWinsResolver;
+const clientWinsResolver = (context) => {
+    if (context.localOutboxRecord) {
+        return 'keep-local';
+    }
+    return 'apply-remote';
+};
+exports.clientWinsResolver = clientWinsResolver;
+function getConflictResolver(strategyOrResolver) {
+    if (typeof strategyOrResolver === 'function') {
+        return strategyOrResolver;
+    }
+    switch (strategyOrResolver) {
+        case 'server-wins':
+            return exports.serverWinsResolver;
+        case 'client-wins':
+            return exports.clientWinsResolver;
+        case 'last-write-wins':
+        default:
+            return exports.lastWriteWinsResolver;
+    }
+}

package/dist/core/meta-store.d.ts

@@ -0,0 +1,28 @@
+import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
+export declare class MetaStore {
+    /**
+     * Initializes the sync_meta schema if it does not already exist.
+     * This table is strictly local to the device and is never synced to the remote server.
+     */
+    static ensureSchema(db: LocalDBAdapter): Promise<void>;
+    /**
+     * Gets a metadata string value by key.
+     */
+    static get(db: LocalDBAdapter, key: string): Promise<string | null>;
+    /**
+     * Sets a metadata value by key (atomic upsert).
+     */
+    static set(db: LocalDBAdapter | LocalTransaction, key: string, value: string): Promise<void>;
+    /**
+     * Retrieves the persisted last_synced_at cursor timestamp (in ms). Returns 0 if never synced.
+     */
+    static getLastSyncedAt(db: LocalDBAdapter): Promise<number>;
+    /**
+     * Persists the last_synced_at cursor timestamp.
+     */
+    static setLastSyncedAt(db: LocalDBAdapter | LocalTransaction, timestamp: number): Promise<void>;
+    /**
+     * Clears the persisted cursor (forces next pull to re-query active remote records).
+     */
+    static clearLastSyncedAt(db: LocalDBAdapter | LocalTransaction): Promise<void>;
+}

package/dist/core/meta-store.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaStore = void 0;
+class MetaStore {
+    /**
+     * Initializes the sync_meta schema if it does not already exist.
+     * This table is strictly local to the device and is never synced to the remote server.
+     */
+    static async ensureSchema(db) {
+        await db.execute(`CREATE TABLE IF NOT EXISTS sync_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );`);
+    }
+    /**
+     * Gets a metadata string value by key.
+     */
+    static async get(db, key) {
+        try {
+            const rows = await db.execute(`SELECT value FROM sync_meta WHERE key = ? LIMIT 1`, [key]);
+            if (rows && rows.length > 0) {
+                return rows[0].value ?? null;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Sets a metadata value by key (atomic upsert).
+     */
+    static async set(db, key, value) {
+        await db.execute(`INSERT OR REPLACE INTO sync_meta (key, value) VALUES (?, ?)`, [key, String(value)]);
+    }
+    /**
+     * Retrieves the persisted last_synced_at cursor timestamp (in ms). Returns 0 if never synced.
+     */
+    static async getLastSyncedAt(db) {
+        const val = await this.get(db, 'last_synced_at');
+        if (!val)
+            return 0;
+        const parsed = parseInt(val, 10);
+        return isNaN(parsed) ? 0 : parsed;
+    }
+    /**
+     * Persists the last_synced_at cursor timestamp.
+     */
+    static async setLastSyncedAt(db, timestamp) {
+        await this.set(db, 'last_synced_at', String(timestamp));
+    }
+    /**
+     * Clears the persisted cursor (forces next pull to re-query active remote records).
+     */
+    static async clearLastSyncedAt(db) {
+        try {
+            await db.execute(`DELETE FROM sync_meta WHERE key = 'last_synced_at'`);
+        }
+        catch {
+            // Ignored if table doesn't exist yet
+        }
+    }
+}
+exports.MetaStore = MetaStore;

package/dist/core/outbox-store.d.ts

@@ -0,0 +1,76 @@
+import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
+import { OutboxRecord, OutboxStatus, SyncOperation } from './types.js';
+export declare class OutboxStore {
+    /**
+     * Initializes the sync_outbox schema if it does not already exist.
+     */
+    static ensureSchema(db: LocalDBAdapter): Promise<void>;
+    /**
+     * Inserts a new outbox entry within an existing database transaction.
+     */
+    static insertRecord(tx: LocalTransaction, op: SyncOperation): Promise<void>;
+    /**
+     * Inserts multiple outbox entries within an existing database transaction.
+     */
+    static insertRecords(tx: LocalTransaction, ops: SyncOperation[]): Promise<void>;
+    /**
+     * Fetches pending and eligible failed outbox records for synchronization.
+     */
+    static getPending(db: LocalDBAdapter, maxRetries?: number, limit?: number): Promise<OutboxRecord[]>;
+    /**
+     * Finds the latest pending outbox record for a given table and row.
+     */
+    static findPendingByRow(tx: LocalTransaction, tableName: string, rowId: string): Promise<OutboxRecord | undefined>;
+    /**
+     * Marks a batch of outbox IDs as 'PROCESSING'.
+     */
+    static markProcessing(db: LocalDBAdapter, ids: string[]): Promise<void>;
+    /**
+     * Resets any orphaned 'PROCESSING' records back to 'PENDING' on startup.
+     * Protects against app kills or crashes that happened mid-push.
+     */
+    static resetStaleProcessing(db: LocalDBAdapter): Promise<void>;
+    /**
+     * Deletes a batch of successfully pushed outbox entries.
+     */
+    static deleteCompleted(db: LocalDBAdapter, ids: string[]): Promise<void>;
+    /**
+     * Deletes a single outbox record within an active transaction.
+     */
+    static deleteRecord(tx: LocalTransaction, id: string): Promise<void>;
+    /**
+     * Updates an outbox record's payload (used during conflict merge).
+     */
+    static updatePayload(tx: LocalTransaction, id: string, payload: Record<string, any>): Promise<void>;
+    /**
+     * Marks a batch of outbox IDs as 'FAILED' and increments retry counters.
+     */
+    static markFailed(db: LocalDBAdapter, ids: string[], errorMessage: string): Promise<void>;
+    /**
+     * Retrieves accurate counts of outbox records categorized by status.
+     */
+    static getCounts(db: LocalDBAdapter): Promise<{
+        pending: number;
+        failed: number;
+        processing: number;
+        total: number;
+    }>;
+    /**
+     * Re-queues failed outbox records for retry by resetting their status to PENDING and resetting retry_count.
+     * If ids are specified, only those records are reset. Otherwise, all FAILED records are reset.
+     * Returns the count of affected records.
+     */
+    static retryFailed(db: LocalDBAdapter, ids?: string[]): Promise<number>;
+    /**
+     * Permanently clears failed outbox records (removes poison-pill mutations).
+     */
+    static clearFailed(db: LocalDBAdapter, ids?: string[]): Promise<number>;
+    /**
+     * Retrieves all outbox records, optionally filtered by status, ordered by timestamp.
+     */
+    static getAllRecords(db: LocalDBAdapter, options?: {
+        status?: OutboxStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<OutboxRecord[]>;
+}