local-lite 0.0.1 → 0.0.3

package/README.md

@@ -6,6 +6,18 @@ Built around the **Transactional Outbox Pattern**, `local-lite` ensures instant,
 
 ---
 
+## 📖 Documentation
+
+* **[Quickstart & Setup](docs/getting-started.md)** - 5-minute setup with Expo, React Native, or Node.js
+* **[Architecture](docs/architecture.md)** - Transactional outbox pattern, SyncWorker loops, and event pipeline
+* **[Configuration Reference](docs/configuration.md)** - Options for `defineSyncConfig()`, retries, and loggers
+* **[Local SQLite Adapters](docs/adapters-local.md)** - Expo SQLite, OP-SQLite, better-sqlite3, node:sqlite, and LibSQL
+* **[Remote Cloud Adapters](docs/adapters-remote.md)** - Supabase, Convex, Cloud Firestore, and custom adapters
+* **[React & Expo Hooks](docs/react-hooks.md)** - `useLiveQuery()` and `useSyncStatus()`
+* **[Conflict Resolution](docs/conflict-resolution.md)** - LWW, Client-Wins, Server-Wins, and custom resolvers
+
+---
+
 ## Features
 
 * **⚡ 0ms Optimistic Writes:** Write to local SQLite immediately via atomic dual-write (`client.mutate()`).
@@ -135,7 +147,7 @@ export const client = await createSyncClient(syncConfig);
 ### 2. Use in React Native / Expo UI
 
 ```tsx
-import { useLiveQuery, useOutboxStatus } from 'local-lite';
+import { useLiveQuery, useSyncStatus } from 'local-lite/react';
 import { client } from './sync.config';
 
 export function TodoScreen() {
@@ -145,7 +157,7 @@ export function TodoScreen() {
     order: 'desc',
   });
 
-  const { pendingCount } = useOutboxStatus(client);
+  const { pendingCount, isOnline, isSyncing } = useSyncStatus(client);
 
   const addTodo = async (title: string) => {
     await client.insert('todos', {

package/dist/core/client.d.ts

@@ -1,9 +1,9 @@
-import { LocalDBAdapter } from '../adapters/local/index.js';
+import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
 import { RemoteDBAdapter } from '../adapters/remote/index.js';
 import { EventEmitter } from '../reactive/event-emitter.js';
 import { SyncWorker } from './sync-worker.js';
 import { SchemaManager } from './schema-manager.js';
-import { ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, QueryOptions, RetryConfig, SyncOp } from './types.js';
+import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent } from './types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
@@ -20,6 +20,21 @@ export interface LocalFirstClientConfig {
     autoSchema?: boolean;
     tables?: string[];
 }
+export declare class TransactionalClient {
+    private parent;
+    private tx;
+    private queuedTableEvents;
+    private queuedOutboxIds;
+    constructor(parent: LocalFirstClient, tx: LocalTransaction, queuedTableEvents: Array<{
+        tableName: string;
+        event: TableChangeEvent;
+    }>, queuedOutboxIds: string[]);
+    mutate(tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, options?: MutateOptions): Promise<void>;
+    insert(tableName: string, rowIdOrPayload: string | Record<string, any>, payloadOrOptions?: Record<string, any> | MutateOptions, options?: MutateOptions): Promise<string>;
+    update(tableName: string, rowId: string, payload: Record<string, any>, options?: MutateOptions): Promise<void>;
+    delete(tableName: string, rowId: string, options?: MutateOptions): Promise<void>;
+    get rawTx(): LocalTransaction;
+}
 export declare class LocalFirstClient {
     db: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -30,6 +45,7 @@ export declare class LocalFirstClient {
     tables: string[];
     private primaryKey;
     constructor(config: LocalFirstClientConfig);
+    getPrimaryKey(): string;
     /**
      * Initializes the client: creates sync_outbox schema, ensures autoSchema tables if enabled,
      * and starts the background sync worker.
@@ -40,6 +56,21 @@ export declare class LocalFirstClient {
      * to sync_outbox within the same database transaction.
      */
     mutate(tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, options?: MutateOptions): Promise<void>;
+    /**
+     * Executes multiple mutations in a single atomic database transaction.
+     * Inserts all corresponding outbox entries together and schedules a single push.
+     */
+    batch(mutations: BatchMutation[], options?: MutateOptions): Promise<string[]>;
+    /**
+     * Convenience helper to insert an array of records into a table atomically.
+     */
+    insertMany(tableName: string, records: Record<string, any>[], options?: MutateOptions): Promise<string[]>;
+    /**
+     * 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.
+     */
+    transaction<T>(action: (txClient: TransactionalClient) => Promise<T>): Promise<T>;
     /**
      * Convenience helper to insert a record into a table.
      * Auto-generates a UUID if rowId is omitted or passed inside payload.
@@ -65,11 +96,12 @@ export declare class LocalFirstClient {
     delete(tableName: string, rowId: string, options?: MutateOptions): Promise<void>;
     /**
      * Reads records from a local SQLite table without requiring manual SQL.
-     * Supports where filtering, order, limit, and offset.
+     * 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 } } });
      */
     findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
     /**
@@ -84,6 +116,27 @@ export declare class LocalFirstClient {
      * Can accept an external transaction `options.tx` for custom atomic SQL workflows.
      */
     trackMutation(tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, options?: MutateOptions): Promise<string>;
+    /**
+     * Returns real-time telemetry metrics captured by the sync engine.
+     */
+    getMetrics(): Promise<SyncMetrics>;
+    /**
+     * Fetches outbox records with optional status filtering and pagination.
+     */
+    getOutboxRecords(options?: {
+        status?: OutboxStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<OutboxRecord[]>;
+    /**
+     * Re-queues failed outbox mutations for retry by resetting their status to PENDING.
+     * Triggers an immediate sync push.
+     */
+    retryFailedMutations(ids?: string[]): Promise<number>;
+    /**
+     * Permanently clears failed mutations (removes poison-pill outbox records).
+     */
+    clearFailedMutations(ids?: string[]): Promise<number>;
     /**
      * Retrieves the persisted last_synced_at timestamp cursor (in ms).
      */

package/dist/core/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalFirstClient = void 0;
+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");
@@ -9,6 +9,75 @@ 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;
@@ -41,6 +110,9 @@ class LocalFirstClient {
         };
         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.
@@ -101,6 +173,108 @@ class LocalFirstClient {
             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.
@@ -146,11 +320,12 @@ class LocalFirstClient {
     }
     /**
      * Reads records from a local SQLite table without requiring manual SQL.
-     * Supports where filtering, order, limit, and offset.
+     * 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);
@@ -165,44 +340,7 @@ class LocalFirstClient {
             }
             throw err;
         }
-        if (!rows || rows.length === 0)
-            return [];
-        let result = [...rows];
-        // 1. Where filtering
-        if (options?.where) {
-            const filterKeys = Object.keys(options.where);
-            result = result.filter((row) => filterKeys.every((k) => row[k] === options.where[k]));
-        }
-        // 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;
+        return (0, query_js_1.applyQueryOptions)(rows, options);
     }
     /**
      * Finds a single record by primary key.
@@ -250,6 +388,40 @@ class LocalFirstClient {
         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).
      */

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

@@ -1,5 +1,5 @@
 import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
-import { OutboxRecord, SyncOperation } from './types.js';
+import { OutboxRecord, OutboxStatus, SyncOperation } from './types.js';
 export declare class OutboxStore {
     /**
      * Initializes the sync_outbox schema if it does not already exist.
@@ -9,6 +9,10 @@ export declare class OutboxStore {
      * 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.
      */
@@ -42,4 +46,31 @@ export declare class OutboxStore {
      * 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[]>;
 }

package/dist/core/outbox-store.js

@@ -32,6 +32,14 @@ class OutboxStore {
             op.timestamp,
         ]);
     }
+    /**
+     * Inserts multiple outbox entries within an existing database transaction.
+     */
+    static async insertRecords(tx, ops) {
+        for (const op of ops) {
+            await this.insertRecord(tx, op);
+        }
+    }
     /**
      * Fetches pending and eligible failed outbox records for synchronization.
      */
@@ -53,7 +61,7 @@ class OutboxStore {
             tableName: r.table_name,
             rowId: r.row_id,
             operation: r.operation,
-            payload: r.payload ? JSON.parse(r.payload) : null,
+            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),
@@ -75,7 +83,7 @@ class OutboxStore {
             tableName: r.table_name,
             rowId: r.row_id,
             operation: r.operation,
-            payload: r.payload ? JSON.parse(r.payload) : null,
+            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),
@@ -137,5 +145,121 @@ class OutboxStore {
            last_error = ? 
        WHERE id IN (${placeholders})`, [errorMessage, ...ids]);
     }
+    /**
+     * Retrieves accurate counts of outbox records categorized by status.
+     */
+    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 };
+            }
+            let pending = 0;
+            let failed = 0;
+            let processing = 0;
+            for (const row of rows) {
+                if (row.status === 'PENDING')
+                    pending++;
+                else if (row.status === 'FAILED')
+                    failed++;
+                else if (row.status === 'PROCESSING')
+                    processing++;
+            }
+            return {
+                pending,
+                failed,
+                processing,
+                total: rows.length,
+            };
+        }
+        catch {
+            return { pending: 0, failed: 0, processing: 0, total: 0 };
+        }
+    }
+    /**
+     * 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 async retryFailed(db, ids) {
+        try {
+            if (ids && ids.length > 0) {
+                const placeholders = ids.map(() => '?').join(',');
+                await db.execute(`UPDATE sync_outbox 
+           SET status = 'PENDING', retry_count = 0, last_error = NULL 
+           WHERE status = 'FAILED' AND id IN (${placeholders})`, ids);
+                return ids.length;
+            }
+            else {
+                const failedRecords = await db.execute(`SELECT id FROM sync_outbox WHERE status = 'FAILED'`);
+                const count = failedRecords?.length || 0;
+                if (count > 0) {
+                    await db.execute(`UPDATE sync_outbox SET status = 'PENDING', retry_count = 0, last_error = NULL WHERE status = 'FAILED'`);
+                }
+                return count;
+            }
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Permanently clears failed outbox records (removes poison-pill mutations).
+     */
+    static async clearFailed(db, ids) {
+        try {
+            if (ids && ids.length > 0) {
+                const placeholders = ids.map(() => '?').join(',');
+                await db.execute(`DELETE FROM sync_outbox WHERE status = 'FAILED' AND id IN (${placeholders})`, ids);
+                return ids.length;
+            }
+            else {
+                const failedRecords = await db.execute(`SELECT id FROM sync_outbox WHERE status = 'FAILED'`);
+                const count = failedRecords?.length || 0;
+                if (count > 0) {
+                    await db.execute(`DELETE FROM sync_outbox WHERE status = 'FAILED'`);
+                }
+                return count;
+            }
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Retrieves all outbox records, optionally filtered by status, ordered by timestamp.
+     */
+    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,
+            }));
+            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);
+            }
+            if (options?.limit && options.limit > 0) {
+                mapped = mapped.slice(0, options.limit);
+            }
+            return mapped;
+        }
+        catch {
+            return [];
+        }
+    }
 }
 exports.OutboxStore = OutboxStore;

package/dist/core/query.d.ts

@@ -0,0 +1,13 @@
+import { FieldFilter, QueryOptions, WhereFilter } from './types.js';
+/**
+ * Checks whether a single field value matches a field filter condition.
+ */
+export declare function matchesField(fieldValue: any, filter: FieldFilter): boolean;
+/**
+ * Evaluates whether a given row matches a WhereFilter.
+ */
+export declare function matchesWhere(row: Record<string, any>, where?: WhereFilter): boolean;
+/**
+ * Applies in-memory filtering, sorting, offset, and limit to an array of rows.
+ */
+export declare function applyQueryOptions<T = any>(rows: T[], options?: QueryOptions): T[];