local-lite 0.0.0-stage → 0.0.2

package/dist/core/outbox-store.js

@@ -0,0 +1,265 @@
+"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,
+        ]);
+    }
+    /**
+     * 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.
+     */
+    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 ? (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,
+        }));
+    }
+    /**
+     * 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 ? (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,
+        };
+    }
+    /**
+     * 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]);
+    }
+    /**
+     * 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[];

package/dist/core/query.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesField = matchesField;
+exports.matchesWhere = matchesWhere;
+exports.applyQueryOptions = applyQueryOptions;
+/**
+ * Checks whether a single field value matches a field filter condition.
+ */
+function matchesField(fieldValue, filter) {
+    if (filter === undefined)
+        return true;
+    if (typeof filter === 'function') {
+        return filter(fieldValue);
+    }
+    // Direct primitive / reference equality
+    if (filter === null || typeof filter !== 'object') {
+        return fieldValue === filter;
+    }
+    // Operator object: $eq, $ne, $in, $nin, $gt, $gte, $lt, $lte, $contains, etc.
+    const ops = filter;
+    if (ops.$eq !== undefined && fieldValue !== ops.$eq) {
+        return false;
+    }
+    if (ops.$ne !== undefined && fieldValue === ops.$ne) {
+        return false;
+    }
+    if (ops.$in !== undefined) {
+        if (!Array.isArray(ops.$in) || !ops.$in.includes(fieldValue)) {
+            return false;
+        }
+    }
+    if (ops.$nin !== undefined) {
+        if (Array.isArray(ops.$nin) && ops.$nin.includes(fieldValue)) {
+            return false;
+        }
+    }
+    if (ops.$gt !== undefined && !(fieldValue > ops.$gt)) {
+        return false;
+    }
+    if (ops.$gte !== undefined && !(fieldValue >= ops.$gte)) {
+        return false;
+    }
+    if (ops.$lt !== undefined && !(fieldValue < ops.$lt)) {
+        return false;
+    }
+    if (ops.$lte !== undefined && !(fieldValue <= ops.$lte)) {
+        return false;
+    }
+    if (ops.$contains !== undefined) {
+        const str = fieldValue === null || fieldValue === undefined ? '' : String(fieldValue).toLowerCase();
+        const search = String(ops.$contains).toLowerCase();
+        if (!str.includes(search)) {
+            return false;
+        }
+    }
+    if (ops.$startsWith !== undefined) {
+        const str = fieldValue === null || fieldValue === undefined ? '' : String(fieldValue).toLowerCase();
+        const prefix = String(ops.$startsWith).toLowerCase();
+        if (!str.startsWith(prefix)) {
+            return false;
+        }
+    }
+    if (ops.$endsWith !== undefined) {
+        const str = fieldValue === null || fieldValue === undefined ? '' : String(fieldValue).toLowerCase();
+        const suffix = String(ops.$endsWith).toLowerCase();
+        if (!str.endsWith(suffix)) {
+            return false;
+        }
+    }
+    if (ops.$null !== undefined) {
+        const isNull = fieldValue === null || fieldValue === undefined;
+        if (ops.$null !== isNull) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Evaluates whether a given row matches a WhereFilter.
+ */
+function matchesWhere(row, where) {
+    if (!where)
+        return true;
+    if (typeof where === 'function') {
+        return where(row);
+    }
+    // Handle $or combinator
+    if ('$or' in where && Array.isArray(where.$or)) {
+        const orMatches = where.$or.some((subWhere) => matchesWhere(row, subWhere));
+        if (!orMatches)
+            return false;
+    }
+    // Handle $and combinator
+    if ('$and' in where && Array.isArray(where.$and)) {
+        const andMatches = where.$and.every((subWhere) => matchesWhere(row, subWhere));
+        if (!andMatches)
+            return false;
+    }
+    // Field-level conditions
+    for (const [key, filter] of Object.entries(where)) {
+        if (key === '$or' || key === '$and')
+            continue;
+        if (!matchesField(row[key], filter)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Applies in-memory filtering, sorting, offset, and limit to an array of rows.
+ */
+function applyQueryOptions(rows, options) {
+    if (!rows || rows.length === 0)
+        return [];
+    let result = [...rows];
+    // 1. Where filtering
+    if (options?.where) {
+        result = result.filter((row) => matchesWhere(row, options.where));
+    }
+    // 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;
+}

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;