local-lite 0.0.19 → 0.0.21

package/dist/scheduler/types.d.ts

@@ -0,0 +1,44 @@
+export type ScheduleType = string | {
+    intervalMs: number;
+};
+export interface JobDefinition {
+    id: string;
+    name?: string;
+    /**
+     * Schedule expression:
+     * - Human string (e.g., 'every 10 minutes', 'every 1 hour', 'daily', 'hourly')
+     * - Standard 5-field cron (e.g., '* / 15 * * * *', '0 9 * * *')
+     * - Object with explicit millisecond interval: { intervalMs: 60000 }
+     */
+    schedule: ScheduleType;
+    /**
+     * Function to execute when the job triggers.
+     */
+    handler?: (job: JobRecord) => Promise<void> | void;
+    payload?: any;
+    enabled?: boolean;
+}
+export interface JobRecord {
+    id: string;
+    name: string;
+    schedule: string;
+    intervalMs: number;
+    lastRunAt: number | null;
+    nextRunAt: number;
+    enabled: boolean;
+    payload?: any;
+    createdAt: number;
+}
+export interface JobRunRecord {
+    id: string;
+    jobId: string;
+    status: 'SUCCESS' | 'FAILED' | 'RUNNING';
+    startedAt: number;
+    finishedAt: number | null;
+    durationMs: number | null;
+    error?: string | null;
+}
+export interface JobSchedulerOptions {
+    checkIntervalMs?: number;
+    autoStart?: boolean;
+}

package/dist/scheduler/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/search/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './store.js';
+export * from './manager.js';

package/dist/search/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./store.js"), exports);
+__exportStar(require("./manager.js"), exports);

package/dist/search/manager.d.ts

@@ -0,0 +1,42 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+import { SearchIndexConfig, SearchQueryOptions, SearchResult } from './types.js';
+export declare class SearchManager {
+    private db;
+    private events?;
+    private getRowById?;
+    private indices;
+    private eventListeners;
+    constructor(db: DBExecutable, events?: EventEmitter | undefined, getRowById?: ((table: string, id: string) => Promise<any | null>) | undefined);
+    /**
+     * Registers and creates an FTS5 index for the specified table and columns.
+     * If an EventEmitter is available, hooks automatically update the index on mutations.
+     */
+    createIndex(config: SearchIndexConfig): Promise<void>;
+    /**
+     * Indexes or updates a single record in the FTS index.
+     */
+    indexRecord(table: string, rowId: string, values: Record<string, any>): Promise<void>;
+    /**
+     * Removes a record from the FTS index.
+     */
+    removeRecord(table: string, rowId: string): Promise<void>;
+    /**
+     * Rebuilds the search index for a table from an array of existing records.
+     */
+    rebuildIndex(table: string, records: Array<{
+        id: string;
+    } & Record<string, any>>): Promise<void>;
+    /**
+     * Executes a full-text search query, returning ranked matches with optional snippets and hydrated rows.
+     */
+    query<T = any>(table: string, queryText: string, options?: SearchQueryOptions): Promise<SearchResult<T>[]>;
+    /**
+     * Drops an index and cleans up auto-sync listeners.
+     */
+    dropIndex(table: string): Promise<void>;
+    /**
+     * Returns list of currently indexed table names.
+     */
+    getIndexedTables(): string[];
+}

package/dist/search/manager.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchManager = void 0;
+const store_js_1 = require("./store.js");
+class SearchManager {
+    db;
+    events;
+    getRowById;
+    indices = new Map();
+    eventListeners = new Map();
+    constructor(db, events, getRowById) {
+        this.db = db;
+        this.events = events;
+        this.getRowById = getRowById;
+    }
+    /**
+     * Registers and creates an FTS5 index for the specified table and columns.
+     * If an EventEmitter is available, hooks automatically update the index on mutations.
+     */
+    async createIndex(config) {
+        const table = config.table;
+        this.indices.set(table, config);
+        await store_js_1.SearchStore.ensureFtsTable(this.db, config);
+        // Auto-sync via event emitter if configured
+        if (this.events && !this.eventListeners.has(table)) {
+            const listener = async (e) => {
+                try {
+                    if (e.operation === 'DELETE') {
+                        await this.removeRecord(table, e.rowId);
+                    }
+                    else if (e.payload) {
+                        await this.indexRecord(table, e.rowId, e.payload);
+                    }
+                }
+                catch {
+                    // Background sync errors shouldn't crash the event bus
+                }
+            };
+            this.events.on(table, listener);
+            this.eventListeners.set(table, listener);
+        }
+    }
+    /**
+     * Indexes or updates a single record in the FTS index.
+     */
+    async indexRecord(table, rowId, values) {
+        const config = this.indices.get(table);
+        const columns = config ? config.columns : Object.keys(values).filter((k) => k !== 'id');
+        await store_js_1.SearchStore.indexRow(this.db, table, rowId, columns, values);
+    }
+    /**
+     * Removes a record from the FTS index.
+     */
+    async removeRecord(table, rowId) {
+        await store_js_1.SearchStore.removeRow(this.db, table, rowId);
+    }
+    /**
+     * Rebuilds the search index for a table from an array of existing records.
+     */
+    async rebuildIndex(table, records) {
+        const config = this.indices.get(table);
+        if (!config) {
+            throw new Error(`Search index not configured for table "${table}". Call createIndex first.`);
+        }
+        await store_js_1.SearchStore.clearFts(this.db, table);
+        for (const record of records) {
+            await store_js_1.SearchStore.indexRow(this.db, table, record.id, config.columns, record);
+        }
+    }
+    /**
+     * Executes a full-text search query, returning ranked matches with optional snippets and hydrated rows.
+     */
+    async query(table, queryText, options = {}) {
+        const config = this.indices.get(table);
+        const columns = config ? config.columns : [];
+        const matches = await store_js_1.SearchStore.search(this.db, table, columns, queryText, options);
+        const shouldHydrate = options.hydrateRow !== false;
+        const results = [];
+        for (const match of matches) {
+            let data = null;
+            if (shouldHydrate) {
+                if (this.getRowById) {
+                    data = await this.getRowById(table, match.rowId);
+                }
+                else {
+                    try {
+                        const rows = await this.db.execute(`SELECT * FROM ${table} WHERE id = ? LIMIT 1`, [match.rowId]);
+                        data = rows && rows.length > 0 ? rows[0] : null;
+                    }
+                    catch {
+                        data = null;
+                    }
+                }
+            }
+            results.push({
+                rowId: match.rowId,
+                rank: match.rank,
+                snippet: match.snippet,
+                data,
+            });
+        }
+        return results;
+    }
+    /**
+     * Drops an index and cleans up auto-sync listeners.
+     */
+    async dropIndex(table) {
+        this.indices.delete(table);
+        const listener = this.eventListeners.get(table);
+        if (listener && this.events) {
+            this.events.off(table, listener);
+            this.eventListeners.delete(table);
+        }
+        await store_js_1.SearchStore.dropFtsTable(this.db, table);
+    }
+    /**
+     * Returns list of currently indexed table names.
+     */
+    getIndexedTables() {
+        return Array.from(this.indices.keys());
+    }
+}
+exports.SearchManager = SearchManager;

package/dist/search/store.d.ts

@@ -0,0 +1,33 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { SearchIndexConfig, SearchQueryOptions } from './types.js';
+export declare function getFtsTableName(table: string): string;
+export declare class SearchStore {
+    /**
+     * Ensures the FTS5 virtual table exists for the given table and columns.
+     */
+    static ensureFtsTable(db: DBExecutable, config: SearchIndexConfig): Promise<void>;
+    /**
+     * Drops the FTS5 virtual table.
+     */
+    static dropFtsTable(db: DBExecutable, table: string): Promise<void>;
+    /**
+     * Indexes or updates a single row in the FTS table.
+     */
+    static indexRow(db: DBExecutable, table: string, rowId: string, columns: string[], values: Record<string, any>): Promise<void>;
+    /**
+     * Removes a single row from the FTS table.
+     */
+    static removeRow(db: DBExecutable, table: string, rowId: string): Promise<void>;
+    /**
+     * Clears all rows in the FTS table.
+     */
+    static clearFts(db: DBExecutable, table: string): Promise<void>;
+    /**
+     * Executes a full-text search match query against the FTS5 table.
+     */
+    static search(db: DBExecutable, table: string, columns: string[], queryText: string, options?: SearchQueryOptions): Promise<Array<{
+        rowId: string;
+        rank: number;
+        snippet?: string;
+    }>>;
+}

package/dist/search/store.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchStore = void 0;
+exports.getFtsTableName = getFtsTableName;
+function getFtsTableName(table) {
+    return `_fts_${table}`;
+}
+class SearchStore {
+    /**
+     * Ensures the FTS5 virtual table exists for the given table and columns.
+     */
+    static async ensureFtsTable(db, config) {
+        const ftsTable = getFtsTableName(config.table);
+        const cols = config.columns.map((c) => c.trim()).filter(Boolean);
+        const tokenize = config.tokenize || 'unicode61';
+        // row_id is UNINDEXED in FTS5 so it does not pollute search tokens
+        const columnDefs = ['row_id UNINDEXED', ...cols].join(', ');
+        const sql = `CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTable} USING fts5(${columnDefs}, tokenize='${tokenize}');`;
+        try {
+            await db.execute(sql);
+        }
+        catch (err) {
+            // In case tokenize='unicode61' isn't supported by legacy SQLite build, retry without tokenize option
+            if (err?.message?.includes('tokenize') || err?.message?.includes('unknown tokenizer')) {
+                await db.execute(`CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTable} USING fts5(${columnDefs});`);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    /**
+     * Drops the FTS5 virtual table.
+     */
+    static async dropFtsTable(db, table) {
+        const ftsTable = getFtsTableName(table);
+        await db.execute(`DROP TABLE IF EXISTS ${ftsTable};`);
+    }
+    /**
+     * Indexes or updates a single row in the FTS table.
+     */
+    static async indexRow(db, table, rowId, columns, values) {
+        const ftsTable = getFtsTableName(table);
+        // Delete existing entry if any
+        await db.execute(`DELETE FROM ${ftsTable} WHERE row_id = ?;`, [rowId]);
+        const cols = ['row_id', ...columns];
+        const placeholders = cols.map(() => '?').join(', ');
+        const params = [
+            rowId,
+            ...columns.map((c) => {
+                const val = values[c];
+                if (val === null || val === undefined)
+                    return '';
+                if (typeof val === 'object')
+                    return JSON.stringify(val);
+                return String(val);
+            }),
+        ];
+        await db.execute(`INSERT INTO ${ftsTable} (${cols.join(', ')}) VALUES (${placeholders});`, params);
+    }
+    /**
+     * Removes a single row from the FTS table.
+     */
+    static async removeRow(db, table, rowId) {
+        const ftsTable = getFtsTableName(table);
+        await db.execute(`DELETE FROM ${ftsTable} WHERE row_id = ?;`, [rowId]);
+    }
+    /**
+     * Clears all rows in the FTS table.
+     */
+    static async clearFts(db, table) {
+        const ftsTable = getFtsTableName(table);
+        await db.execute(`DELETE FROM ${ftsTable};`);
+    }
+    /**
+     * Executes a full-text search match query against the FTS5 table.
+     */
+    static async search(db, table, columns, queryText, options = {}) {
+        const ftsTable = getFtsTableName(table);
+        const limit = options.limit ?? 20;
+        const offset = options.offset ?? 0;
+        const preTag = options.highlightPreTag ?? '<mark>';
+        const postTag = options.highlightPostTag ?? '</mark>';
+        // Prepare match phrase: escape quotes or sanitize
+        // If query has multiple terms, SQLite FTS5 supports prefix matching (e.g. "term*")
+        const terms = queryText
+            .trim()
+            .split(/\s+/)
+            .map((t) => t.replace(/["*]/g, ''))
+            .filter(Boolean);
+        if (terms.length === 0) {
+            return [];
+        }
+        // Search query syntax: each term as prefix search: "term1"* "term2"*
+        const matchQuery = terms.map((t) => `"${t}"*`).join(' ');
+        // Snippet column index in FTS5: columns are 0-based: col 0 is row_id, col 1 is columns[0], etc.
+        // We pick column index 1 (or the first indexed text column) for snippet extraction
+        const snippetColIndex = 1;
+        let sql = `
+      SELECT 
+        row_id,
+        rank,
+        snippet(${ftsTable}, ${snippetColIndex}, '${preTag}', '${postTag}', '...', 15) as snippet_text
+      FROM ${ftsTable}
+      WHERE ${ftsTable} MATCH ?
+      ORDER BY rank
+      LIMIT ? OFFSET ?;
+    `;
+        try {
+            const rows = await db.execute(sql, [matchQuery, limit, offset]);
+            return (rows || []).map((r) => ({
+                rowId: String(r.row_id),
+                rank: Number(r.rank ?? 0),
+                snippet: r.snippet_text ?? undefined,
+            }));
+        }
+        catch (err) {
+            // In case snippet() function is unavailable in the environment, fallback to rank-only search
+            if (err?.message?.includes('snippet') || err?.message?.includes('no such function')) {
+                const fallbackSql = `
+          SELECT row_id, rank
+          FROM ${ftsTable}
+          WHERE ${ftsTable} MATCH ?
+          ORDER BY rank
+          LIMIT ? OFFSET ?;
+        `;
+                const rows = await db.execute(fallbackSql, [matchQuery, limit, offset]);
+                return (rows || []).map((r) => ({
+                    rowId: String(r.row_id),
+                    rank: Number(r.rank ?? 0),
+                }));
+            }
+            throw err;
+        }
+    }
+}
+exports.SearchStore = SearchStore;

package/dist/search/types.d.ts

@@ -0,0 +1,49 @@
+export interface SearchIndexConfig {
+    /**
+     * The name of the table to index (e.g. 'properties', 'tenants').
+     */
+    table: string;
+    /**
+     * The text columns to include in the full-text search index.
+     */
+    columns: string[];
+    /**
+     * SQLite FTS tokenizer (e.g. 'unicode61', 'porter', 'ascii').
+     * Default: 'unicode61'
+     */
+    tokenize?: string;
+}
+export interface SearchQueryOptions {
+    /**
+     * Maximum search results to return (default: 20).
+     */
+    limit?: number;
+    /**
+     * Pagination offset.
+     */
+    offset?: number;
+    /**
+     * Whether to include a highlighted snippet matching the search query.
+     * Default: true
+     */
+    highlight?: boolean;
+    /**
+     * Tag prefix for highlights (default: '<mark>').
+     */
+    highlightPreTag?: string;
+    /**
+     * Tag suffix for highlights (default: '</mark>').
+     */
+    highlightPostTag?: string;
+    /**
+     * Whether to hydrate the full row record from the base table.
+     * Default: true
+     */
+    hydrateRow?: boolean;
+}
+export interface SearchResult<T = any> {
+    rowId: string;
+    rank: number;
+    snippet?: string;
+    data?: T | null;
+}

package/dist/search/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/storage/driver.d.ts

@@ -0,0 +1,25 @@
+import { FileDriver } from './types.js';
+/**
+ * Universal in-memory driver (ideal for tests, memory caches, and browser storage fallback).
+ */
+export declare class MemoryFileDriver implements FileDriver {
+    private files;
+    write(key: string, data: Uint8Array): Promise<string>;
+    read(key: string): Promise<Uint8Array | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    clear(): void;
+}
+/**
+ * Node.js filesystem driver for writing blobs to disk.
+ */
+export declare class NodeFileDriver implements FileDriver {
+    private baseDir;
+    constructor(baseDir?: string);
+    private getFs;
+    private getResolvedPath;
+    write(key: string, data: Uint8Array): Promise<string>;
+    read(key: string): Promise<Uint8Array | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}

package/dist/storage/driver.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeFileDriver = exports.MemoryFileDriver = void 0;
+/**
+ * Universal in-memory driver (ideal for tests, memory caches, and browser storage fallback).
+ */
+class MemoryFileDriver {
+    files = new Map();
+    async write(key, data) {
+        this.files.set(key, new Uint8Array(data));
+        return `memory://${key}`;
+    }
+    async read(key) {
+        const file = this.files.get(key);
+        return file ? new Uint8Array(file) : null;
+    }
+    async delete(key) {
+        this.files.delete(key);
+    }
+    async exists(key) {
+        return this.files.has(key);
+    }
+    clear() {
+        this.files.clear();
+    }
+}
+exports.MemoryFileDriver = MemoryFileDriver;
+/**
+ * Node.js filesystem driver for writing blobs to disk.
+ */
+class NodeFileDriver {
+    baseDir;
+    constructor(baseDir = './.local-lite-blobs') {
+        this.baseDir = baseDir;
+    }
+    async getFs() {
+        try {
+            const fs = await import('node:fs/promises');
+            const path = await import('node:path');
+            return { fs, path };
+        }
+        catch {
+            throw new Error('NodeFileDriver is only supported in Node.js environments.');
+        }
+    }
+    async getResolvedPath(key) {
+        const { path } = await this.getFs();
+        // sanitize key to prevent directory traversal
+        const safeKey = key.replace(/\.\./g, '_');
+        return path.resolve(this.baseDir, safeKey);
+    }
+    async write(key, data) {
+        const { fs, path } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, data);
+        return filePath;
+    }
+    async read(key) {
+        const { fs } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        try {
+            const buffer = await fs.readFile(filePath);
+            return new Uint8Array(buffer);
+        }
+        catch {
+            return null;
+        }
+    }
+    async delete(key) {
+        const { fs } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        try {
+            await fs.unlink(filePath);
+        }
+        catch {
+            // file might already be removed
+        }
+    }
+    async exists(key) {
+        const { fs } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.NodeFileDriver = NodeFileDriver;

package/dist/storage/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './driver.js';
+export * from './store.js';
+export * from './manager.js';

package/dist/storage/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./driver.js"), exports);
+__exportStar(require("./store.js"), exports);
+__exportStar(require("./manager.js"), exports);

package/dist/storage/manager.d.ts

@@ -0,0 +1,48 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { BlobRecord, BlobStorageManagerOptions, BlobUploadStatus, FileDriver, RemoteStorageUploader, SaveBlobOptions } from './types.js';
+export declare class BlobStorageManager {
+    private db;
+    private driver;
+    private uploader?;
+    private network?;
+    private tableName;
+    constructor(db: DBExecutable, options?: BlobStorageManagerOptions);
+    initialize(): Promise<void>;
+    setDriver(driver: FileDriver): void;
+    setUploader(uploader: RemoteStorageUploader): void;
+    /**
+     * Saves a binary blob or file locally. Records metadata in SQLite and writes binary to driver.
+     * If online and uploader configured, can immediately trigger upload.
+     */
+    save(key: string, data: Uint8Array | string, options?: SaveBlobOptions): Promise<BlobRecord>;
+    /**
+     * Retrieves blob record and raw binary data.
+     */
+    get(key: string): Promise<{
+        record: BlobRecord;
+        data: Uint8Array;
+    } | null>;
+    /**
+     * Reads raw binary data for key.
+     */
+    getData(key: string): Promise<Uint8Array | null>;
+    /**
+     * Retrieves blob metadata record.
+     */
+    getRecord(key: string): Promise<BlobRecord | null>;
+    /**
+     * Lists blob metadata records, optionally filtered by upload status.
+     */
+    list(status?: BlobUploadStatus): Promise<BlobRecord[]>;
+    /**
+     * Deletes the blob binary and metadata record.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Flushes and syncs pending or failed uploads to the remote storage uploader.
+     */
+    syncPending(): Promise<{
+        uploaded: number;
+        failed: number;
+    }>;
+}