local-lite 0.0.2 → 0.0.4

package/dist/core/outbox-store.js

@@ -1,6 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OutboxStore = void 0;
+/**
+ * Maps a raw sync_outbox row into an OutboxRecord.
+ */
+function mapOutboxRow(r) {
+    return {
+        id: r.id,
+        tableName: r.table_name,
+        rowId: r.row_id,
+        operation: r.operation,
+        payload: r.payload ? (typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload) : null,
+        timestamp: Number(r.timestamp),
+        status: r.status,
+        retryCount: Number(r.retry_count || 0),
+        lastError: r.last_error,
+    };
+}
 class OutboxStore {
     /**
      * Initializes the sync_outbox schema if it does not already exist.
@@ -17,6 +33,10 @@ class OutboxStore {
         retry_count INTEGER NOT NULL DEFAULT 0,
         last_error TEXT
       );`);
+        // Indexes for the hot paths: pending scans (push), per-row conflict lookups (pull),
+        // and status counts (telemetry). Executed separately: many drivers prepare one statement.
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_sync_outbox_status_ts ON sync_outbox (status, timestamp);`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_sync_outbox_row ON sync_outbox (table_name, row_id, timestamp);`);
     }
     /**
      * Inserts a new outbox entry within an existing database transaction.
@@ -33,11 +53,29 @@ class OutboxStore {
         ]);
     }
     /**
-     * Inserts multiple outbox entries within an existing database transaction.
+     * Inserts multiple outbox entries in high-throughput multi-row SQL chunks within an existing transaction.
      */
     static async insertRecords(tx, ops) {
-        for (const op of ops) {
-            await this.insertRecord(tx, op);
+        if (!ops || ops.length === 0)
+            return;
+        const CHUNK_SIZE = 50;
+        for (let i = 0; i < ops.length; i += CHUNK_SIZE) {
+            const chunk = ops.slice(i, i + CHUNK_SIZE);
+            const valueClauses = [];
+            const params = [];
+            for (const op of chunk) {
+                valueClauses.push('(?, ?, ?, ?, ?, ?, "PENDING", 0)');
+                params.push(op.id, op.tableName, op.rowId, op.operation, op.payload ? JSON.stringify(op.payload) : null, op.timestamp);
+            }
+            try {
+                await tx.execute(`INSERT INTO sync_outbox (id, table_name, row_id, operation, payload, timestamp, status, retry_count) VALUES ${valueClauses.join(', ')}`, params);
+            }
+            catch {
+                // Transparent fallback to per-record insert for mock drivers or custom engines
+                for (const op of chunk) {
+                    await this.insertRecord(tx, op);
+                }
+            }
         }
     }
     /**
@@ -56,17 +94,7 @@ class OutboxStore {
         const rows = await db.execute(query, params);
         if (!rows || rows.length === 0)
             return [];
-        return rows.map((r) => ({
-            id: r.id,
-            tableName: r.table_name,
-            rowId: r.row_id,
-            operation: r.operation,
-            payload: r.payload ? (typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload) : null,
-            timestamp: Number(r.timestamp),
-            status: r.status,
-            retryCount: Number(r.retry_count || 0),
-            lastError: r.last_error,
-        }));
+        return rows.map(mapOutboxRow);
     }
     /**
      * Finds the latest pending outbox record for a given table and row.
@@ -77,18 +105,7 @@ class OutboxStore {
        ORDER BY timestamp DESC LIMIT 1`, [tableName, rowId]);
         if (!rows || rows.length === 0)
             return undefined;
-        const r = rows[0];
-        return {
-            id: r.id,
-            tableName: r.table_name,
-            rowId: r.row_id,
-            operation: r.operation,
-            payload: r.payload ? (typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload) : null,
-            timestamp: Number(r.timestamp),
-            status: r.status,
-            retryCount: Number(r.retry_count || 0),
-            lastError: r.last_error,
-        };
+        return mapOutboxRow(rows[0]);
     }
     /**
      * Marks a batch of outbox IDs as 'PROCESSING'.
@@ -127,10 +144,22 @@ class OutboxStore {
         await tx.execute(`DELETE FROM sync_outbox WHERE id = ?`, [id]);
     }
     /**
-     * Updates an outbox record's payload (used during conflict merge).
+     * Updates an outbox record's payload (used during conflict merge or coalescing).
      */
-    static async updatePayload(tx, id, payload) {
-        await tx.execute(`UPDATE sync_outbox SET payload = ? WHERE id = ?`, [JSON.stringify(payload), id]);
+    static async updatePayload(tx, id, payload, timestamp) {
+        if (timestamp) {
+            await tx.execute(`UPDATE sync_outbox SET payload = ?, timestamp = ? WHERE id = ?`, [JSON.stringify(payload), timestamp, id]);
+        }
+        else {
+            await tx.execute(`UPDATE sync_outbox SET payload = ? WHERE id = ?`, [JSON.stringify(payload), id]);
+        }
+    }
+    /**
+     * Updates an outbox record's operation and payload (used during mutation coalescing).
+     */
+    static async updateOperation(tx, id, operation, payload, timestamp) {
+        const ts = timestamp ?? Date.now();
+        await tx.execute(`UPDATE sync_outbox SET operation = ?, payload = ?, timestamp = ? WHERE id = ?`, [operation, payload ? JSON.stringify(payload) : null, ts, id]);
     }
     /**
      * Marks a batch of outbox IDs as 'FAILED' and increments retry counters.
@@ -150,27 +179,23 @@ class OutboxStore {
      */
     static async getCounts(db) {
         try {
-            const rows = await db.execute(`SELECT * FROM sync_outbox`);
-            if (!rows || rows.length === 0) {
-                return { pending: 0, failed: 0, processing: 0, total: 0 };
-            }
+            // Aggregate in SQLite (index-only scan) instead of loading every row and payload into JS.
+            const rows = await db.execute(`SELECT status, COUNT(*) AS count FROM sync_outbox GROUP BY status`);
             let pending = 0;
             let failed = 0;
             let processing = 0;
-            for (const row of rows) {
+            let total = 0;
+            for (const row of rows || []) {
+                const count = Number(row.count ?? 0);
+                total += count;
                 if (row.status === 'PENDING')
-                    pending++;
+                    pending = count;
                 else if (row.status === 'FAILED')
-                    failed++;
+                    failed = count;
                 else if (row.status === 'PROCESSING')
-                    processing++;
+                    processing = count;
             }
-            return {
-                pending,
-                failed,
-                processing,
-                total: rows.length,
-            };
+            return { pending, failed, processing, total };
         }
         catch {
             return { pending: 0, failed: 0, processing: 0, total: 0 };
@@ -231,31 +256,25 @@ class OutboxStore {
      */
     static async getAllRecords(db, options) {
         try {
-            const rows = await db.execute(`SELECT * FROM sync_outbox`);
-            if (!rows || rows.length === 0)
-                return [];
-            let mapped = rows.map((r) => ({
-                id: r.id,
-                tableName: r.table_name,
-                rowId: r.row_id,
-                operation: r.operation,
-                payload: r.payload ? (typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload) : null,
-                timestamp: Number(r.timestamp),
-                status: r.status,
-                retryCount: Number(r.retry_count || 0),
-                lastError: r.last_error,
-            }));
+            // Filter, order and paginate in SQLite so only the requested page is parsed.
+            const params = [];
+            let query = `SELECT * FROM sync_outbox`;
             if (options?.status) {
-                mapped = mapped.filter((r) => r.status === options.status);
-            }
-            mapped.sort((a, b) => b.timestamp - a.timestamp);
-            if (options?.offset && options.offset > 0) {
-                mapped = mapped.slice(options.offset);
+                query += ` WHERE status = ?`;
+                params.push(options.status);
             }
-            if (options?.limit && options.limit > 0) {
-                mapped = mapped.slice(0, options.limit);
+            query += ` ORDER BY timestamp DESC`;
+            const limit = options?.limit && options.limit > 0 ? options.limit : -1;
+            const offset = options?.offset && options.offset > 0 ? options.offset : 0;
+            if (limit > 0 || offset > 0) {
+                // SQLite requires LIMIT when OFFSET is used; -1 means "no limit".
+                query += ` LIMIT ? OFFSET ?`;
+                params.push(limit, offset);
             }
-            return mapped;
+            const rows = await db.execute(query, params);
+            if (!rows || rows.length === 0)
+                return [];
+            return rows.map(mapOutboxRow);
         }
         catch {
             return [];

package/dist/core/query.d.ts

@@ -7,6 +7,14 @@ export declare function matchesField(fieldValue: any, filter: FieldFilter): bool
  * Evaluates whether a given row matches a WhereFilter.
  */
 export declare function matchesWhere(row: Record<string, any>, where?: WhereFilter): boolean;
+/**
+ * Checks whether a row is considered soft-deleted.
+ */
+export declare function isDeletedRecord(row: any): boolean;
+/**
+ * Checks if a where filter explicitly specifies a condition on the 'deleted' column.
+ */
+export declare function hasExplicitDeletedFilter(where?: WhereFilter): boolean;
 /**
  * Applies in-memory filtering, sorting, offset, and limit to an array of rows.
  */

package/dist/core/query.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchesField = matchesField;
 exports.matchesWhere = matchesWhere;
+exports.isDeletedRecord = isDeletedRecord;
+exports.hasExplicitDeletedFilter = hasExplicitDeletedFilter;
 exports.applyQueryOptions = applyQueryOptions;
 /**
  * Checks whether a single field value matches a field filter condition.
@@ -106,6 +108,23 @@ function matchesWhere(row, where) {
     }
     return true;
 }
+/**
+ * Checks whether a row is considered soft-deleted.
+ */
+function isDeletedRecord(row) {
+    if (!row || typeof row !== 'object')
+        return false;
+    const d = row.deleted;
+    return d === 1 || d === true || d === '1' || d === 'true';
+}
+/**
+ * Checks if a where filter explicitly specifies a condition on the 'deleted' column.
+ */
+function hasExplicitDeletedFilter(where) {
+    if (!where || typeof where !== 'object' || Array.isArray(where))
+        return false;
+    return 'deleted' in where;
+}
 /**
  * Applies in-memory filtering, sorting, offset, and limit to an array of rows.
  */
@@ -113,6 +132,11 @@ function applyQueryOptions(rows, options) {
     if (!rows || rows.length === 0)
         return [];
     let result = [...rows];
+    // 0. Automatic soft-delete filtering: omit deleted records unless includeDeleted is true
+    // or the where filter explicitly targets 'deleted'.
+    if (!options?.includeDeleted && !hasExplicitDeletedFilter(options?.where)) {
+        result = result.filter((row) => !isDeletedRecord(row));
+    }
     // 1. Where filtering
     if (options?.where) {
         result = result.filter((row) => matchesWhere(row, options.where));
@@ -146,5 +170,18 @@ function applyQueryOptions(rows, options) {
     if (options?.limit !== undefined && options.limit > 0) {
         result = result.slice(0, options.limit);
     }
+    // 4. Column Projection
+    if (options?.select && Array.isArray(options.select) && options.select.length > 0) {
+        const fields = options.select;
+        result = result.map((row) => {
+            const projected = {};
+            for (const field of fields) {
+                if (field in row) {
+                    projected[field] = row[field];
+                }
+            }
+            return projected;
+        });
+    }
     return result;
 }

package/dist/core/schema-manager.d.ts

@@ -23,10 +23,19 @@ export declare function formatValueForStorage(value: any): any;
 export declare class SchemaManager {
     private knownTables;
     private knownColumns;
+    private knownIndexes;
     /**
      * Resets the schema cache (useful for testing or full database resets).
      */
     clearCache(): void;
+    /**
+     * Checks whether a column is known to exist on the specified table.
+     */
+    hasColumn(tableName: string, column: string): boolean;
+    /**
+     * Introspects table columns via PRAGMA table_info if not previously cached.
+     */
+    ensureTableIntrospected(db: DBExecutable, tableName: string): Promise<void>;
     /**
      * Ensures that the target table exists in SQLite with the specified primary key.
      */

package/dist/core/schema-manager.js

@@ -58,12 +58,43 @@ function formatValueForStorage(value) {
 class SchemaManager {
     knownTables = new Set();
     knownColumns = new Set();
+    knownIndexes = new Set();
     /**
      * Resets the schema cache (useful for testing or full database resets).
      */
     clearCache() {
         this.knownTables.clear();
         this.knownColumns.clear();
+        this.knownIndexes.clear();
+    }
+    /**
+     * Checks whether a column is known to exist on the specified table.
+     */
+    hasColumn(tableName, column) {
+        return this.knownColumns.has(`${tableName}:${column.toLowerCase()}`);
+    }
+    /**
+     * Introspects table columns via PRAGMA table_info if not previously cached.
+     */
+    async ensureTableIntrospected(db, tableName) {
+        const cacheKey = `${tableName}:__introspected__`;
+        if (this.knownColumns.has(cacheKey))
+            return;
+        this.knownColumns.add(cacheKey);
+        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+        try {
+            const tableInfo = await db.execute(`PRAGMA table_info(${safeTable});`);
+            if (Array.isArray(tableInfo)) {
+                for (const col of tableInfo) {
+                    if (col && col.name) {
+                        this.knownColumns.add(`${tableName}:${String(col.name).toLowerCase()}`);
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore
+        }
     }
     /**
      * Ensures that the target table exists in SQLite with the specified primary key.
@@ -137,6 +168,43 @@ class SchemaManager {
                     }
                     this.knownColumns.add(cacheKey);
                 }
+                // Auto-index foreign keys and common query columns
+                const lowerKey = key.toLowerCase();
+                if (lowerKey.endsWith('_id') ||
+                    lowerKey === 'business_id' ||
+                    lowerKey === 'deleted' ||
+                    lowerKey === 'created_at' ||
+                    lowerKey === 'payment_date') {
+                    const indexKey = `${tableName}:${lowerKey}`;
+                    if (!this.knownIndexes.has(indexKey)) {
+                        this.knownIndexes.add(indexKey);
+                        try {
+                            const idxName = (0, sql_js_1.escapeIdentifier)(`idx_${tableName}_${key}`);
+                            const safeCol = (0, sql_js_1.escapeIdentifier)(key);
+                            await db.execute(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${safeTable} (${safeCol});`);
+                        }
+                        catch {
+                            // Ignore if indexes are not supported by adapter or already exist
+                        }
+                    }
+                }
+            }
+        }
+        // Auto-create high performance composite index for multi-tenant soft-deleted queries
+        if (this.knownColumns.has(`${tableName}:business_id`) &&
+            this.knownColumns.has(`${tableName}:deleted`)) {
+            const compositeKey = `${tableName}:business_id_deleted`;
+            if (!this.knownIndexes.has(compositeKey)) {
+                this.knownIndexes.add(compositeKey);
+                try {
+                    const idxName = (0, sql_js_1.escapeIdentifier)(`idx_${tableName}_biz_del`);
+                    const safeBiz = (0, sql_js_1.escapeIdentifier)('business_id');
+                    const safeDel = (0, sql_js_1.escapeIdentifier)('deleted');
+                    await db.execute(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${safeTable} (${safeBiz}, ${safeDel});`);
+                }
+                catch {
+                    // Ignore
+                }
             }
         }
         // Format all values for SQLite storage

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

@@ -16,6 +16,9 @@ export interface SyncWorkerOptions {
     primaryKey?: string;
     autoSchema?: boolean;
     schemaManager?: SchemaManager;
+    autoSync?: boolean;
+    syncScope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
+    autoPauseOnBackground?: boolean;
 }
 export declare class SyncWorker {
     private db;
@@ -26,20 +29,29 @@ export declare class SyncWorker {
     private primaryKey;
     private autoSchema;
     private schemaManager?;
+    private syncScope?;
     logger: SyncLogger;
     retryConfig: RetryConfig;
     private pushIntervalMs;
     private pullIntervalMs;
     private maxRetries;
+    private autoPauseOnBackground;
+    private isPaused;
+    private lifecycleUnsubscribe?;
     private pushIntervalTimer?;
     private pullIntervalTimer?;
     private pushDebounceTimer?;
     private networkUnsubscribe?;
+    private remoteUnsubscribe?;
+    private subscriptionGeneration;
+    private automaticSync;
     private isPushing;
     private isPulling;
     private lastPulledTimestamp;
     private cursorLoaded;
     private deltaQueue;
+    private statusRun?;
+    private statusRerunRequested;
     private totalPushedOperations;
     private totalPulledDeltas;
     private totalPushCycles;
@@ -59,11 +71,34 @@ export declare class SyncWorker {
      * Stops all active intervals, timers, and listeners.
      */
     stop(): void;
+    /**
+     * Pauses recurring interval timers and active sync loops to conserve battery and data.
+     */
+    pause(): void;
+    /**
+     * Resumes recurring interval timers and triggers an immediate catch-up push and pull.
+     */
+    resume(): void;
+    /**
+     * Returns whether the sync worker is currently suspended due to app backgrounding.
+     */
+    get isBackgroundPaused(): boolean;
+    private isAppBackgrounded;
+    private setupLifecycleListener;
     /**
      * Schedules an immediate push with a short debounce.
      */
     schedulePush(delayMs?: number): void;
+    /**
+     * Dynamically sets or updates the active sync scope (e.g. switching active businessId or userId).
+     */
+    setSyncScope(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
     private isOnline;
+    /**
+     * Emits a `sync:status` snapshot. Calls are coalesced: while one snapshot is being
+     * computed, further requests collapse into a single trailing run that reflects the
+     * latest state, so bursts of push/pull transitions cost at most two COUNT queries.
+     */
     private emitStatus;
     /**
      * Pushes pending outbox records to the remote database.
@@ -78,7 +113,9 @@ export declare class SyncWorker {
      * Applies incoming server delta changes to local tables with conflict resolution.
      * Serializes execution in a queue to prevent concurrent SQLite transactions.
      */
-    applyDeltasLocally(deltas: DeltaChanges): Promise<void>;
+    applyDeltasLocally(deltas: DeltaChanges, options?: {
+        advanceCursor?: boolean;
+    }): Promise<void>;
     private processDeltasLocally;
     getLastPulledTimestamp(): Promise<number>;
     resetSyncCursor(): Promise<void>;