local-lite 0.0.0-stage → 0.0.1

package/dist/react/index.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLiveQuery = useLiveQuery;
+exports.useOutboxStatus = useOutboxStatus;
+const react_1 = require("react");
+/**
+ * Hook to execute a live reactive table query that automatically re-runs
+ * whenever the table is mutated locally or via incoming remote delta.
+ *
+ * Supports 3 flexible usage patterns:
+ * 1. Zero-SQL (all rows):
+ *    const { data: todos } = useLiveQuery<Todo>(client, 'todos');
+ *
+ * 2. Declarative options (filtering & sorting without SQL):
+ *    const { data: active } = useLiveQuery<Todo>(client, 'todos', {
+ *      where: { completed: 0 },
+ *      orderBy: 'created_at',
+ *      order: 'desc'
+ *    });
+ *
+ * 3. Custom query callback (advanced raw SQL / joins):
+ *    const { data } = useLiveQuery(client, 'todos', (c) => c.db.execute('SELECT ...'));
+ */
+function useLiveQuery(client, tableName, queryOrOptions) {
+    const [data, setData] = (0, react_1.useState)([]);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const queryParamRef = (0, react_1.useRef)(queryOrOptions);
+    queryParamRef.current = queryOrOptions;
+    const refetch = (0, react_1.useCallback)(async () => {
+        if (!client || !client.db)
+            return;
+        try {
+            const param = queryParamRef.current;
+            let res;
+            if (typeof param === 'function') {
+                res = (await param(client)) || [];
+            }
+            else if (typeof param === 'object' && param !== null) {
+                res = await client.findMany(tableName, param);
+            }
+            else {
+                res = await client.findMany(tableName);
+            }
+            setData(res || []);
+        }
+        catch (err) {
+            const msg = String(err?.message || err || '');
+            if (msg.includes('no such column') || msg.includes('no such table')) {
+                // Table or columns have not been populated yet on fresh database; default to empty list
+                setData([]);
+            }
+            else {
+                console.error(`Error in useLiveQuery("${tableName}"):`, err);
+            }
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, tableName]);
+    (0, react_1.useEffect)(() => {
+        if (!client || !client.db)
+            return;
+        refetch();
+        const unsubscribe = client.events.on(tableName, () => {
+            refetch();
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client, tableName, refetch]);
+    return { data, refetch, loading };
+}
+/**
+ * Hook that tracks the status and pending items in sync_outbox in real time.
+ */
+function useOutboxStatus(client) {
+    const [pendingCount, setPendingCount] = (0, react_1.useState)(0);
+    const [pendingRecords, setPendingRecords] = (0, react_1.useState)([]);
+    const refresh = (0, react_1.useCallback)(async () => {
+        if (!client || !client.db)
+            return;
+        try {
+            const records = await client.db.execute('SELECT * FROM sync_outbox ORDER BY timestamp DESC');
+            setPendingRecords(records || []);
+            setPendingCount((records || []).length);
+        }
+        catch {
+            // Ignored if table doesn't exist yet
+        }
+    }, [client]);
+    (0, react_1.useEffect)(() => {
+        if (!client || !client.db)
+            return;
+        refresh();
+        const unsubscribe = client.events.on('sync_outbox', () => {
+            refresh();
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client, refresh]);
+    return { pendingCount, pendingRecords, refresh };
+}

package/dist/reactive/event-emitter.d.ts

@@ -0,0 +1,7 @@
+type EventCallback = (data: any) => void;
+export declare class EventEmitter {
+    private listeners;
+    on(event: string, callback: EventCallback): () => void;
+    emit(event: string, data: any): void;
+}
+export {};

package/dist/reactive/event-emitter.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventEmitter = void 0;
+class EventEmitter {
+    listeners = new Map();
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => {
+            const eventSet = this.listeners.get(event);
+            if (eventSet) {
+                eventSet.delete(callback);
+                if (eventSet.size === 0)
+                    this.listeners.delete(event);
+            }
+        };
+    }
+    emit(event, data) {
+        const eventSet = this.listeners.get(event);
+        if (eventSet) {
+            eventSet.forEach(callback => {
+                try {
+                    callback(data);
+                }
+                catch (err) {
+                    console.error("Emitter error:", err);
+                }
+            });
+        }
+    }
+}
+exports.EventEmitter = EventEmitter;

package/dist/utils/logger.d.ts

@@ -0,0 +1,51 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export interface CustomLogger {
+    debug?(message: string, ...args: any[]): void;
+    info?(message: string, ...args: any[]): void;
+    warn?(message: string, ...args: any[]): void;
+    error?(message: string, ...args: any[]): void;
+}
+export interface LoggerConfig {
+    level?: LogLevel;
+    customLogger?: CustomLogger;
+    enabled?: boolean;
+}
+export declare class SyncLogger {
+    private level;
+    private customLogger?;
+    private enabled;
+    constructor(config?: LoggerConfig | boolean);
+    setLevel(level: LogLevel): void;
+    setEnabled(enabled: boolean): void;
+    setCustomLogger(logger?: CustomLogger): void;
+    private shouldLog;
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * Global default logger instance.
+ */
+export declare const defaultLogger: SyncLogger;
+/**
+ * Translates PostgreSQL / Supabase PostgREST error codes into actionable, human-readable explanations.
+ */
+export declare function formatSupabaseError(error: any, context?: {
+    table?: string;
+    operation?: string;
+}): string;
+/**
+ * Translates Firestore error codes into human-readable explanations.
+ */
+export declare function formatFirestoreError(error: any, context?: {
+    collection?: string;
+    operation?: string;
+}): string;
+/**
+ * Translates Convex error codes into human-readable explanations.
+ */
+export declare function formatConvexError(error: any, context?: {
+    table?: string;
+    operation?: string;
+}): string;

package/dist/utils/logger.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultLogger = exports.SyncLogger = void 0;
+exports.formatSupabaseError = formatSupabaseError;
+exports.formatFirestoreError = formatFirestoreError;
+exports.formatConvexError = formatConvexError;
+const LOG_LEVEL_WEIGHTS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+class SyncLogger {
+    level = 'info';
+    customLogger;
+    enabled = true;
+    constructor(config) {
+        if (typeof config === 'boolean') {
+            this.enabled = config;
+        }
+        else if (config) {
+            if (config.enabled !== undefined)
+                this.enabled = config.enabled;
+            if (config.level)
+                this.level = config.level;
+            if (config.customLogger)
+                this.customLogger = config.customLogger;
+        }
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    setCustomLogger(logger) {
+        this.customLogger = logger;
+    }
+    shouldLog(level) {
+        if (!this.enabled || this.level === 'silent')
+            return false;
+        return LOG_LEVEL_WEIGHTS[level] >= LOG_LEVEL_WEIGHTS[this.level];
+    }
+    debug(message, ...args) {
+        if (!this.shouldLog('debug'))
+            return;
+        if (this.customLogger?.debug) {
+            this.customLogger.debug(message, ...args);
+        }
+        else {
+            console.debug(`[local-lite] ${message}`, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (!this.shouldLog('info'))
+            return;
+        if (this.customLogger?.info) {
+            this.customLogger.info(message, ...args);
+        }
+        else {
+            console.info(`[local-lite] ${message}`, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (!this.shouldLog('warn'))
+            return;
+        if (this.customLogger?.warn) {
+            this.customLogger.warn(message, ...args);
+        }
+        else {
+            console.warn(`[local-lite] ${message}`, ...args);
+        }
+    }
+    error(message, ...args) {
+        if (!this.shouldLog('error'))
+            return;
+        if (this.customLogger?.error) {
+            this.customLogger.error(message, ...args);
+        }
+        else {
+            console.error(`[local-lite] ${message}`, ...args);
+        }
+    }
+}
+exports.SyncLogger = SyncLogger;
+/**
+ * Global default logger instance.
+ */
+exports.defaultLogger = new SyncLogger();
+/**
+ * Translates PostgreSQL / Supabase PostgREST error codes into actionable, human-readable explanations.
+ */
+function formatSupabaseError(error, context = {}) {
+    if (!error)
+        return 'Unknown Supabase error';
+    const table = context.table ? `"${context.table}"` : 'table';
+    const op = context.operation ? ` (${context.operation})` : '';
+    const code = String(error.code || error.status || '').trim();
+    const rawMsg = error.message || error.details || String(error);
+    // PostgreSQL RLS 42501 (insufficient_privilege)
+    if (code === '42501' || rawMsg.toLowerCase().includes('row-level security')) {
+        return `🔒 RLS Permission Denied on ${table}${op}: Row-Level Security blocked this mutation. Check that the user is authenticated and matching RLS policies exist on Postgres.`;
+    }
+    // PostgreSQL 23502 (not_null_violation)
+    if (code === '23502') {
+        const hint = error.details || rawMsg;
+        return `⚠️ Missing Required Column on ${table}${op}: NOT NULL constraint violated. (${hint})`;
+    }
+    // PostgreSQL 23505 (unique_violation)
+    if (code === '23505') {
+        const hint = error.details || rawMsg;
+        return `⚠️ Duplicate Key on ${table}${op}: Unique constraint violated. (${hint})`;
+    }
+    // PostgreSQL 23503 (foreign_key_violation)
+    if (code === '23503') {
+        const hint = error.details || rawMsg;
+        return `⚠️ Foreign Key Missing on ${table}${op}: Referenced relation does not exist. (${hint})`;
+    }
+    // Supabase Auth / JWT expired (PGRST301, JWT expired)
+    if (code === 'PGRST301' || rawMsg.toLowerCase().includes('jwt')) {
+        return `🔑 Session Expired on ${table}${op}: Supabase auth token is invalid or expired.`;
+    }
+    // Network / Offline errors
+    if (rawMsg.toLowerCase().includes('fetch failed') ||
+        rawMsg.toLowerCase().includes('enotfound') ||
+        rawMsg.toLowerCase().includes('network')) {
+        return `📡 Network Offline: Failed to reach Supabase backend. Mutations safely preserved in local SQLite outbox.`;
+    }
+    return `❌ Supabase error on ${table}${op} [code: ${code || 'N/A'}]: ${rawMsg}`;
+}
+/**
+ * Translates Firestore error codes into human-readable explanations.
+ */
+function formatFirestoreError(error, context = {}) {
+    if (!error)
+        return 'Unknown Firestore error';
+    const collection = context.collection ? `"${context.collection}"` : 'collection';
+    const op = context.operation ? ` (${context.operation})` : '';
+    const code = String(error.code || '').toLowerCase();
+    const rawMsg = error.message || String(error);
+    if (code.includes('permission-denied') || rawMsg.toLowerCase().includes('insufficient permissions')) {
+        return `🔒 Permission Denied on collection ${collection}${op}: Check your Firestore Security Rules.`;
+    }
+    if (code.includes('unauthenticated')) {
+        return `🔑 Unauthenticated on collection ${collection}${op}: User must be signed into Firebase Auth.`;
+    }
+    if (code.includes('unavailable') || rawMsg.toLowerCase().includes('network')) {
+        return `📡 Firestore Offline: Backend unreachable. Mutations preserved in local SQLite outbox.`;
+    }
+    return `❌ Firestore error on ${collection}${op}: ${rawMsg}`;
+}
+/**
+ * Translates Convex error codes into human-readable explanations.
+ */
+function formatConvexError(error, context = {}) {
+    if (!error)
+        return 'Unknown Convex error';
+    const table = context.table ? `"${context.table}"` : 'table';
+    const op = context.operation ? ` (${context.operation})` : '';
+    const rawMsg = error.message || String(error);
+    if (rawMsg.toLowerCase().includes('unauthorized') || rawMsg.toLowerCase().includes('unauthenticated')) {
+        return `🔒 Convex Permission Denied on ${table}${op}: Request unauthorized.`;
+    }
+    if (rawMsg.toLowerCase().includes('network') || rawMsg.toLowerCase().includes('failed to fetch')) {
+        return `📡 Convex Offline: Server unreachable. Mutations preserved in local SQLite outbox.`;
+    }
+    return `❌ Convex error on ${table}${op}: ${rawMsg}`;
+}

package/dist/utils/sql.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Safely escape a SQL identifier (table name or column name) with double quotes.
+ */
+export declare function escapeIdentifier(identifier: string): string;

package/dist/utils/sql.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeIdentifier = escapeIdentifier;
+/**
+ * Safely escape a SQL identifier (table name or column name) with double quotes.
+ */
+function escapeIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}

package/dist/utils/uuid.d.ts

@@ -0,0 +1,7 @@
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Generates an RFC4122 v4 compliant UUID.
+ * Uses native crypto.randomUUID() when supported, with uuid.v4 fallback.
+ */
+export declare function generateUUID(): string;
+export { uuidv4 };

package/dist/utils/uuid.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuidv4 = void 0;
+exports.generateUUID = generateUUID;
+const uuid_1 = require("uuid");
+Object.defineProperty(exports, "uuidv4", { enumerable: true, get: function () { return uuid_1.v4; } });
+/**
+ * Generates an RFC4122 v4 compliant UUID.
+ * Uses native crypto.randomUUID() when supported, with uuid.v4 fallback.
+ */
+function generateUUID() {
+    try {
+        if (typeof globalThis !== 'undefined' &&
+            globalThis.crypto &&
+            typeof globalThis.crypto.randomUUID === 'function') {
+            return globalThis.crypto.randomUUID();
+        }
+        return (0, uuid_1.v4)();
+    }
+    catch {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+}

package/package.json

@@ -1,6 +1,133 @@
 {
   "name": "local-lite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Vendor-agnostic local-first sync engine with outbox pattern, Supabase, Convex, and Firebase support",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "default": "./dist/config/index.js"
+    },
+    "./supabase": {
+      "types": "./dist/adapters/remote/supabase.d.ts",
+      "import": "./dist/adapters/remote/supabase.js",
+      "default": "./dist/adapters/remote/supabase.js"
+    },
+    "./convex": {
+      "types": "./dist/adapters/remote/convex.d.ts",
+      "import": "./dist/adapters/remote/convex.js",
+      "default": "./dist/adapters/remote/convex.js"
+    },
+    "./firebase": {
+      "types": "./dist/adapters/remote/firestore.d.ts",
+      "import": "./dist/adapters/remote/firestore.js",
+      "default": "./dist/adapters/remote/firestore.js"
+    },
+    "./expo-sqlite": {
+      "types": "./dist/adapters/local/expo-sqlite.d.ts",
+      "import": "./dist/adapters/local/expo-sqlite.js",
+      "default": "./dist/adapters/local/expo-sqlite.js"
+    },
+    "./op-sqlite": {
+      "types": "./dist/adapters/local/op-sqlite.d.ts",
+      "import": "./dist/adapters/local/op-sqlite.js",
+      "default": "./dist/adapters/local/op-sqlite.js"
+    },
+    "./better-sqlite3": {
+      "types": "./dist/adapters/local/better-sqlite3.d.ts",
+      "import": "./dist/adapters/local/better-sqlite3.js",
+      "default": "./dist/adapters/local/better-sqlite3.js"
+    },
+    "./libsql": {
+      "types": "./dist/adapters/local/libsql.d.ts",
+      "import": "./dist/adapters/local/libsql.js",
+      "default": "./dist/adapters/local/libsql.js"
+    },
+    "./sql-js": {
+      "types": "./dist/adapters/local/sql-js.d.ts",
+      "import": "./dist/adapters/local/sql-js.js",
+      "default": "./dist/adapters/local/sql-js.js"
+    },
+    "./node-sqlite": {
+      "types": "./dist/adapters/local/node-sqlite.d.ts",
+      "import": "./dist/adapters/local/node-sqlite.js",
+      "default": "./dist/adapters/local/node-sqlite.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@libsql/client": "^0.6.0",
+    "@op-engineering/op-sqlite": "^0.1.0",
+    "@supabase/supabase-js": "^2.0.0",
+    "better-sqlite3": "^8.0.0",
+    "convex": ">=1.0.0",
+    "expo-sqlite": "^57.0.0",
+    "firebase": ">=9.0.0",
+    "react": ">=18.0.0",
+    "sql.js": "^1.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "convex": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    },
+    "expo-sqlite": {
+      "optional": true
+    },
+    "@op-engineering/op-sqlite": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    },
+    "sql.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.117.3",
+    "@types/react": "^19.3.0",
+    "@types/uuid": "^11.0.0",
+    "expo-sqlite": "^57.0.4",
+    "react": "^19.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.4"
+  },
+  "dependencies": {
+    "uuid": "^14.0.3"
+  }
 }