local-lite 0.0.3 → 0.0.5

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

@@ -1,5 +1,5 @@
 import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
-import { OutboxRecord, OutboxStatus, SyncOperation } from './types.js';
+import { OutboxRecord, OutboxStatus, SyncOp, SyncOperation } from './types.js';
 export declare class OutboxStore {
     /**
      * Initializes the sync_outbox schema if it does not already exist.
@@ -10,7 +10,7 @@ export declare class OutboxStore {
      */
     static insertRecord(tx: LocalTransaction, op: SyncOperation): Promise<void>;
     /**
-     * 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 insertRecords(tx: LocalTransaction, ops: SyncOperation[]): Promise<void>;
     /**
@@ -39,9 +39,13 @@ export declare class OutboxStore {
      */
     static deleteRecord(tx: LocalTransaction, id: string): Promise<void>;
     /**
-     * Updates an outbox record's payload (used during conflict merge).
+     * Updates an outbox record's payload (used during conflict merge or coalescing).
      */
-    static updatePayload(tx: LocalTransaction, id: string, payload: Record<string, any>): Promise<void>;
+    static updatePayload(tx: LocalTransaction, id: string, payload: Record<string, any>, timestamp?: number): Promise<void>;
+    /**
+     * Updates an outbox record's operation and payload (used during mutation coalescing).
+     */
+    static updateOperation(tx: LocalTransaction, id: string, operation: SyncOp, payload: Record<string, any> | null, timestamp?: number): Promise<void>;
     /**
      * Marks a batch of outbox IDs as 'FAILED' and increments retry counters.
      */

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-builder.d.ts

@@ -0,0 +1,119 @@
+import { LocalFirstClient, TransactionalClient } from './client.js';
+import { QueryOptions, WhereFilter } from './types.js';
+type ClientLike = LocalFirstClient | TransactionalClient;
+/**
+ * Escapes an identifier or compound identifier (e.g. 'table.column' or 'table.col as alias').
+ */
+export declare function formatColumnIdentifier(col: string): string;
+export interface JoinDefinition {
+    type: 'INNER' | 'LEFT' | 'CROSS';
+    table: string;
+    firstCol: string;
+    secondCol: string;
+}
+export interface AggregateSpec {
+    where?: WhereFilter;
+    count?: boolean;
+    sum?: string[];
+    avg?: string[];
+    min?: string[];
+    max?: string[];
+}
+export interface AggregateResult {
+    count?: number;
+    sum?: Record<string, number>;
+    avg?: Record<string, number | null>;
+    min?: Record<string, any>;
+    max?: Record<string, any>;
+}
+/**
+ * Fluent, type-safe SQL Query Builder for local-first SQLite operations.
+ * Allows writing expressive JavaScript code that compiles and executes high-performance SQL under the hood.
+ */
+export declare class QueryBuilder<T = any> {
+    private client;
+    private tableName;
+    private selectCols;
+    private joins;
+    private whereConditions;
+    private orderColumn?;
+    private orderDirection;
+    private limitCount?;
+    private offsetCount?;
+    private groupByCols;
+    private includeDeleted;
+    constructor(client: ClientLike, tableName: string);
+    /**
+     * Specifies which columns to select.
+     * Supports column aliases (e.g. ['id', 'contracts.rent_amount AS rent', 'houses.house_number']).
+     */
+    select(...columns: Array<string | string[]>): this;
+    /**
+     * Inner joins another SQLite table on a matching column expression.
+     */
+    join(table: string, firstCol: string, secondCol: string): this;
+    /**
+     * Left joins another SQLite table on a matching column expression.
+     */
+    leftJoin(table: string, firstCol: string, secondCol: string): this;
+    /**
+     * Adds WHERE criteria to filter results.
+     * Supports:
+     * - where({ status: 'ACTIVE' })
+     * - where('status', 'ACTIVE')
+     * - where('end_date', '>=', today)
+     */
+    where(columnOrFilter: string | WhereFilter, operatorOrValue?: any, value?: any): this;
+    /**
+     * Orders query results by column and direction.
+     */
+    orderBy(column: string, direction?: 'asc' | 'desc' | 'ASC' | 'DESC'): this;
+    /**
+     * Groups rows by one or more columns for aggregation.
+     */
+    groupBy(...columns: Array<string | string[]>): this;
+    /**
+     * Limits the number of returned records.
+     */
+    limit(count: number): this;
+    /**
+     * Offsets the starting record position.
+     */
+    offset(count: number): this;
+    /**
+     * Includes soft-deleted rows in results.
+     */
+    withDeleted(include?: boolean): this;
+    /**
+     * Applies standard QueryOptions (select, where, orderBy, limit, offset, includeDeleted) to this query.
+     */
+    applyOptions(options?: QueryOptions): this;
+    /**
+     * Compiles the current builder state into an executable SQL string and parameter list.
+     */
+    toSQL(): {
+        sql: string;
+        params: any[];
+    };
+    /**
+     * Executes the compiled SQL query against SQLite and returns rows.
+     */
+    execute(): Promise<T[]>;
+    /**
+     * Returns the first matching record or null if not found.
+     */
+    first(): Promise<T | null>;
+    /**
+     * Executes a COUNT(*) in SQLite and returns the numeric count directly.
+     */
+    count(): Promise<number>;
+    /**
+     * Executes a SUM(column) in SQLite and returns the numeric total directly.
+     */
+    sum(column: string): Promise<number>;
+    /**
+     * Executes an AVG(column) in SQLite and returns the average directly.
+     */
+    avg(column: string): Promise<number | null>;
+}
+export {};