local-lite 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,45 @@
+import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
+import { OutboxRecord, 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>;
+    /**
+     * 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>;
+}

package/dist/core/outbox-store.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxStore = void 0;
+class OutboxStore {
+    /**
+     * Initializes the sync_outbox schema if it does not already exist.
+     */
+    static async ensureSchema(db) {
+        await db.execute(`CREATE TABLE IF NOT EXISTS sync_outbox (
+        id TEXT PRIMARY KEY,
+        table_name TEXT NOT NULL,
+        row_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        payload TEXT,
+        timestamp INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'PENDING',
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        last_error TEXT
+      );`);
+    }
+    /**
+     * Inserts a new outbox entry within an existing database transaction.
+     */
+    static async insertRecord(tx, op) {
+        await tx.execute(`INSERT INTO sync_outbox (id, table_name, row_id, operation, payload, timestamp, status, retry_count)
+       VALUES (?, ?, ?, ?, ?, ?, 'PENDING', 0)`, [
+            op.id,
+            op.tableName,
+            op.rowId,
+            op.operation,
+            op.payload ? JSON.stringify(op.payload) : null,
+            op.timestamp,
+        ]);
+    }
+    /**
+     * Fetches pending and eligible failed outbox records for synchronization.
+     */
+    static async getPending(db, maxRetries = 5, limit = 50) {
+        const isInfinite = !Number.isFinite(maxRetries) || maxRetries === -1;
+        const query = isInfinite
+            ? `SELECT * FROM sync_outbox 
+         WHERE status = 'PENDING' OR status = 'FAILED' 
+         ORDER BY timestamp ASC LIMIT ?`
+            : `SELECT * FROM sync_outbox 
+         WHERE status = 'PENDING' OR (status = 'FAILED' AND retry_count < ?) 
+         ORDER BY timestamp ASC LIMIT ?`;
+        const params = isInfinite ? [limit] : [maxRetries, limit];
+        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 ? JSON.parse(r.payload) : null,
+            timestamp: Number(r.timestamp),
+            status: r.status,
+            retryCount: Number(r.retry_count || 0),
+            lastError: r.last_error,
+        }));
+    }
+    /**
+     * Finds the latest pending outbox record for a given table and row.
+     */
+    static async findPendingByRow(tx, tableName, rowId) {
+        const rows = await tx.execute(`SELECT * FROM sync_outbox 
+       WHERE table_name = ? AND row_id = ? AND status != 'FAILED' 
+       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 ? JSON.parse(r.payload) : null,
+            timestamp: Number(r.timestamp),
+            status: r.status,
+            retryCount: Number(r.retry_count || 0),
+            lastError: r.last_error,
+        };
+    }
+    /**
+     * Marks a batch of outbox IDs as 'PROCESSING'.
+     */
+    static async markProcessing(db, ids) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => '?').join(',');
+        await db.execute(`UPDATE sync_outbox SET status = 'PROCESSING' WHERE id IN (${placeholders})`, ids);
+    }
+    /**
+     * Resets any orphaned 'PROCESSING' records back to 'PENDING' on startup.
+     * Protects against app kills or crashes that happened mid-push.
+     */
+    static async resetStaleProcessing(db) {
+        try {
+            await db.execute(`UPDATE sync_outbox SET status = 'PENDING' WHERE status = 'PROCESSING'`);
+        }
+        catch {
+            // Table may not exist yet
+        }
+    }
+    /**
+     * Deletes a batch of successfully pushed outbox entries.
+     */
+    static async deleteCompleted(db, ids) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => '?').join(',');
+        await db.execute(`DELETE FROM sync_outbox WHERE id IN (${placeholders})`, ids);
+    }
+    /**
+     * Deletes a single outbox record within an active transaction.
+     */
+    static async deleteRecord(tx, id) {
+        await tx.execute(`DELETE FROM sync_outbox WHERE id = ?`, [id]);
+    }
+    /**
+     * Updates an outbox record's payload (used during conflict merge).
+     */
+    static async updatePayload(tx, id, payload) {
+        await tx.execute(`UPDATE sync_outbox SET payload = ? WHERE id = ?`, [JSON.stringify(payload), id]);
+    }
+    /**
+     * Marks a batch of outbox IDs as 'FAILED' and increments retry counters.
+     */
+    static async markFailed(db, ids, errorMessage) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => '?').join(',');
+        await db.execute(`UPDATE sync_outbox 
+       SET status = 'FAILED', 
+           retry_count = retry_count + 1, 
+           last_error = ? 
+       WHERE id IN (${placeholders})`, [errorMessage, ...ids]);
+    }
+}
+exports.OutboxStore = OutboxStore;

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

@@ -0,0 +1,39 @@
+export interface DBExecutable {
+    execute(query: string, params?: any[]): Promise<any[]>;
+}
+/**
+ * Detects the appropriate SQLite column type affinity from a JavaScript runtime value.
+ *
+ * Mapping:
+ * - boolean -> INTEGER (0 or 1)
+ * - integer -> INTEGER
+ * - float/double -> REAL
+ * - string -> TEXT
+ * - object/array -> TEXT (JSON formatted)
+ * - Uint8Array -> BLOB
+ * - null/undefined -> TEXT (flexible SQLite type affinity)
+ */
+export declare function detectSQLiteType(value: any): 'INTEGER' | 'REAL' | 'TEXT' | 'BLOB';
+/**
+ * Normalizes values for SQLite storage:
+ * - Booleans are converted to 1 / 0
+ * - Plain objects and arrays are JSON serialized
+ */
+export declare function formatValueForStorage(value: any): any;
+export declare class SchemaManager {
+    private knownTables;
+    private knownColumns;
+    /**
+     * Resets the schema cache (useful for testing or full database resets).
+     */
+    clearCache(): void;
+    /**
+     * Ensures that the target table exists in SQLite with the specified primary key.
+     */
+    ensureTable(db: DBExecutable, tableName: string, primaryKey?: string): Promise<void>;
+    /**
+     * Automatically introspects and adds missing columns to the table via ALTER TABLE.
+     * Also normalizes payload values for SQLite compatibility.
+     */
+    ensureColumns(db: DBExecutable, tableName: string, payload: Record<string, any> | null, primaryKey?: string): Promise<Record<string, any>>;
+}

package/dist/core/schema-manager.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaManager = void 0;
+exports.detectSQLiteType = detectSQLiteType;
+exports.formatValueForStorage = formatValueForStorage;
+const sql_js_1 = require("../utils/sql.js");
+/**
+ * Detects the appropriate SQLite column type affinity from a JavaScript runtime value.
+ *
+ * Mapping:
+ * - boolean -> INTEGER (0 or 1)
+ * - integer -> INTEGER
+ * - float/double -> REAL
+ * - string -> TEXT
+ * - object/array -> TEXT (JSON formatted)
+ * - Uint8Array -> BLOB
+ * - null/undefined -> TEXT (flexible SQLite type affinity)
+ */
+function detectSQLiteType(value) {
+    if (value === null || value === undefined) {
+        return 'TEXT';
+    }
+    const type = typeof value;
+    if (type === 'boolean') {
+        return 'INTEGER';
+    }
+    if (type === 'number') {
+        return Number.isInteger(value) ? 'INTEGER' : 'REAL';
+    }
+    if (type === 'string') {
+        return 'TEXT';
+    }
+    if (value instanceof Uint8Array) {
+        return 'BLOB';
+    }
+    if (type === 'object') {
+        return 'TEXT';
+    }
+    return 'TEXT';
+}
+/**
+ * Normalizes values for SQLite storage:
+ * - Booleans are converted to 1 / 0
+ * - Plain objects and arrays are JSON serialized
+ */
+function formatValueForStorage(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'boolean') {
+        return value ? 1 : 0;
+    }
+    if (typeof value === 'object' && !(value instanceof Uint8Array)) {
+        return JSON.stringify(value);
+    }
+    return value;
+}
+class SchemaManager {
+    knownTables = new Set();
+    knownColumns = new Set();
+    /**
+     * Resets the schema cache (useful for testing or full database resets).
+     */
+    clearCache() {
+        this.knownTables.clear();
+        this.knownColumns.clear();
+    }
+    /**
+     * Ensures that the target table exists in SQLite with the specified primary key.
+     */
+    async ensureTable(db, tableName, primaryKey = 'id') {
+        if (this.knownTables.has(tableName)) {
+            return;
+        }
+        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+        const safePk = (0, sql_js_1.escapeIdentifier)(primaryKey);
+        await db.execute(`CREATE TABLE IF NOT EXISTS ${safeTable} (${safePk} TEXT PRIMARY KEY);`);
+        this.knownTables.add(tableName);
+        this.knownColumns.add(`${tableName}:${primaryKey.toLowerCase()}`);
+    }
+    /**
+     * Automatically introspects and adds missing columns to the table via ALTER TABLE.
+     * Also normalizes payload values for SQLite compatibility.
+     */
+    async ensureColumns(db, tableName, payload, primaryKey = 'id') {
+        await this.ensureTable(db, tableName, primaryKey);
+        if (!payload || typeof payload !== 'object') {
+            return {};
+        }
+        const keys = Object.keys(payload);
+        if (keys.length === 0) {
+            return {};
+        }
+        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+        let cacheMiss = false;
+        for (const key of keys) {
+            if (key === primaryKey)
+                continue;
+            const cacheKey = `${tableName}:${key.toLowerCase()}`;
+            if (!this.knownColumns.has(cacheKey)) {
+                cacheMiss = true;
+                break;
+            }
+        }
+        if (cacheMiss) {
+            // Query PRAGMA table_info to discover existing columns from SQLite
+            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 (err) {
+                // Fallback for mocks or custom drivers where PRAGMA table_info might not be supported
+            }
+            // Check for columns that still do not exist, and alter table
+            for (const key of keys) {
+                if (key === primaryKey)
+                    continue;
+                const cacheKey = `${tableName}:${key.toLowerCase()}`;
+                if (!this.knownColumns.has(cacheKey)) {
+                    const detectedType = detectSQLiteType(payload[key]);
+                    const safeCol = (0, sql_js_1.escapeIdentifier)(key);
+                    try {
+                        await db.execute(`ALTER TABLE ${safeTable} ADD COLUMN ${safeCol} ${detectedType};`);
+                    }
+                    catch (err) {
+                        // Ignore if column already exists (e.g. concurrent race)
+                        const msg = String(err?.message || err || '');
+                        if (!msg.toLowerCase().includes('duplicate column')) {
+                            // Ignore or rethrow
+                        }
+                    }
+                    this.knownColumns.add(cacheKey);
+                }
+            }
+        }
+        // Format all values for SQLite storage
+        const formatted = {};
+        for (const key of keys) {
+            formatted[key] = formatValueForStorage(payload[key]);
+        }
+        return formatted;
+    }
+}
+exports.SchemaManager = SchemaManager;

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

@@ -0,0 +1,74 @@
+import { LocalDBAdapter } from '../adapters/local/index.js';
+import { RemoteDBAdapter } from '../adapters/remote/index.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+import { ConflictResolver, ConflictStrategy, DeltaChanges, NetworkStatusProvider, RetryConfig } from './types.js';
+import { SchemaManager } from './schema-manager.js';
+import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
+export interface SyncWorkerOptions {
+    pushIntervalMs?: number;
+    pullIntervalMs?: number;
+    maxRetries?: number;
+    retry?: number | RetryConfig;
+    logger?: SyncLogger | CustomLogger | boolean;
+    logLevel?: LogLevel;
+    conflictResolver?: ConflictStrategy | ConflictResolver;
+    network?: NetworkStatusProvider;
+    primaryKey?: string;
+    autoSchema?: boolean;
+    schemaManager?: SchemaManager;
+}
+export declare class SyncWorker {
+    private db;
+    private remote;
+    private events;
+    private network;
+    private conflictResolver;
+    private primaryKey;
+    private autoSchema;
+    private schemaManager?;
+    logger: SyncLogger;
+    retryConfig: RetryConfig;
+    private pushIntervalMs;
+    private pullIntervalMs;
+    private maxRetries;
+    private pushIntervalTimer?;
+    private pullIntervalTimer?;
+    private pushDebounceTimer?;
+    private networkUnsubscribe?;
+    private isPushing;
+    private isPulling;
+    private lastPulledTimestamp;
+    private cursorLoaded;
+    private deltaQueue;
+    constructor(db: LocalDBAdapter, remote: RemoteDBAdapter, events: EventEmitter, options?: SyncWorkerOptions);
+    /**
+     * Starts background interval push/pull loops and listens for network & realtime updates.
+     */
+    start(): void;
+    /**
+     * Stops all active intervals, timers, and listeners.
+     */
+    stop(): void;
+    /**
+     * Schedules an immediate push with a short debounce.
+     */
+    schedulePush(delayMs?: number): void;
+    private isOnline;
+    /**
+     * Pushes pending outbox records to the remote database.
+     */
+    pushLocalChanges(): Promise<void>;
+    private handlePushFailure;
+    /**
+     * Pulls delta changes from the remote backend since lastPulledTimestamp.
+     */
+    pullRemoteChanges(): Promise<void>;
+    /**
+     * 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>;
+    private processDeltasLocally;
+    getLastPulledTimestamp(): Promise<number>;
+    resetSyncCursor(): Promise<void>;
+}