local-lite 0.0.0-stage → 0.0.1

package/dist/adapters/remote/firestore.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirestoreRemoteAdapter = void 0;
+const logger_js_1 = require("../../utils/logger.js");
+/**
+ * Safely extracts epoch milliseconds from numbers, Firestore Timestamps, or ISO strings.
+ */
+function extractTimestamp(val) {
+    if (!val)
+        return Date.now();
+    if (typeof val === 'number')
+        return val;
+    if (typeof val.toMillis === 'function')
+        return val.toMillis();
+    if (typeof val.toDate === 'function')
+        return val.toDate().getTime();
+    if (typeof val.seconds === 'number') {
+        return val.seconds * 1000 + Math.floor((val.nanoseconds || 0) / 1000000);
+    }
+    if (typeof val.string === 'string') {
+        const parsed = Date.parse(val);
+        if (!isNaN(parsed))
+            return parsed;
+    }
+    return Date.now();
+}
+class FirestoreRemoteAdapter {
+    db;
+    tables;
+    primaryKey;
+    deletedColumn;
+    updatedAtColumn;
+    firestoreModule;
+    unsubscribers = [];
+    logger;
+    constructor(db, options = {}) {
+        if (!db) {
+            throw new Error('FirestoreRemoteAdapter requires a firestore db instance.');
+        }
+        this.db = db;
+        this.tables = options.tables ?? [];
+        this.primaryKey = options.primaryKey ?? 'id';
+        this.deletedColumn = options.deletedColumn ?? 'deleted';
+        this.updatedAtColumn = options.updatedAtColumn ?? 'updatedAt';
+        this.firestoreModule = options.firestoreModule;
+        if (options.logger instanceof logger_js_1.SyncLogger) {
+            this.logger = options.logger;
+        }
+        else if (typeof options.logger === 'boolean') {
+            this.logger = new logger_js_1.SyncLogger({ enabled: options.logger, level: options.logLevel });
+        }
+        else if (options.logger && typeof options.logger === 'object') {
+            this.logger = new logger_js_1.SyncLogger({ customLogger: options.logger, level: options.logLevel });
+        }
+        else {
+            this.logger = options.logLevel ? new logger_js_1.SyncLogger({ level: options.logLevel }) : logger_js_1.defaultLogger;
+        }
+    }
+    setTables(tables) {
+        this.tables = tables;
+    }
+    async getModule() {
+        if (this.firestoreModule) {
+            return this.firestoreModule;
+        }
+        try {
+            const dynamicImport = new Function('moduleName', 'return import(moduleName)');
+            this.firestoreModule = await dynamicImport('firebase/firestore');
+            return this.firestoreModule;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Pushes outbox operations as batch writes to Firestore.
+     * Chunks operations into batches of 450 (below Firestore 500-write limit).
+     */
+    async pushChanges(operations) {
+        if (!operations || operations.length === 0) {
+            return true;
+        }
+        try {
+            const isCompat = typeof this.db.batch === 'function' && typeof this.db.collection === 'function';
+            const mod = isCompat ? null : await this.getModule();
+            const CHUNK_SIZE = 450;
+            for (let i = 0; i < operations.length; i += CHUNK_SIZE) {
+                const chunk = operations.slice(i, i + CHUNK_SIZE);
+                const now = Date.now();
+                if (isCompat) {
+                    // React Native Firebase / Compat SDK
+                    const batch = this.db.batch();
+                    for (const op of chunk) {
+                        const docRef = this.db.collection(op.tableName).doc(op.rowId);
+                        if (op.operation === 'DELETE') {
+                            batch.set(docRef, {
+                                [this.primaryKey]: op.rowId,
+                                [this.deletedColumn]: true,
+                                [this.updatedAtColumn]: now,
+                            }, { merge: true });
+                        }
+                        else {
+                            batch.set(docRef, {
+                                ...(op.payload || {}),
+                                [this.primaryKey]: op.rowId,
+                                [this.deletedColumn]: false,
+                                [this.updatedAtColumn]: now,
+                            }, { merge: true });
+                        }
+                    }
+                    await batch.commit();
+                }
+                else if (mod && typeof mod.writeBatch === 'function') {
+                    // Modular Firebase SDK
+                    const batch = mod.writeBatch(this.db);
+                    for (const op of chunk) {
+                        const docRef = mod.doc(mod.collection(this.db, op.tableName), op.rowId);
+                        if (op.operation === 'DELETE') {
+                            batch.set(docRef, {
+                                [this.primaryKey]: op.rowId,
+                                [this.deletedColumn]: true,
+                                [this.updatedAtColumn]: now,
+                            }, { merge: true });
+                        }
+                        else {
+                            batch.set(docRef, {
+                                ...(op.payload || {}),
+                                [this.primaryKey]: op.rowId,
+                                [this.deletedColumn]: false,
+                                [this.updatedAtColumn]: now,
+                            }, { merge: true });
+                        }
+                    }
+                    await batch.commit();
+                }
+                else {
+                    throw new Error('Firestore client does not have .batch() and modular firebase/firestore writeBatch could not be loaded.');
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            this.logger.error((0, logger_js_1.formatFirestoreError)(error, { operation: 'pushChanges' }));
+            return false;
+        }
+    }
+    /**
+     * Fetches delta changes across tracked collections where updatedAt > sinceTimestamp.
+     */
+    async fetchChanges(sinceTimestamp) {
+        if (!this.tables || this.tables.length === 0) {
+            return { timestamp: sinceTimestamp, changes: [] };
+        }
+        try {
+            const isCompat = typeof this.db.collection === 'function';
+            const mod = isCompat ? null : await this.getModule();
+            let maxServerTimestamp = sinceTimestamp;
+            const changes = [];
+            for (const table of this.tables) {
+                let docs = [];
+                if (isCompat) {
+                    const snapshot = await this.db
+                        .collection(table)
+                        .where(this.updatedAtColumn, '>', sinceTimestamp)
+                        .get();
+                    docs = snapshot.docs || [];
+                }
+                else if (mod && typeof mod.getDocs === 'function') {
+                    const q = mod.query(mod.collection(this.db, table), mod.where(this.updatedAtColumn, '>', sinceTimestamp));
+                    const snapshot = await mod.getDocs(q);
+                    docs = snapshot.docs || [];
+                }
+                for (const doc of docs) {
+                    const data = typeof doc.data === 'function' ? doc.data() : doc;
+                    const isSoftDeleted = Boolean(data[this.deletedColumn] === true ||
+                        data[this.deletedColumn] === 1 ||
+                        (data[this.deletedColumn] &&
+                            !['false', '0', 'null', 'undefined'].includes(String(data[this.deletedColumn]).toLowerCase())));
+                    const rowTime = extractTimestamp(data[this.updatedAtColumn]);
+                    if (rowTime > maxServerTimestamp) {
+                        maxServerTimestamp = rowTime;
+                    }
+                    const rowId = String(data[this.primaryKey] || doc.id || data.id);
+                    const operation = isSoftDeleted ? 'DELETE' : 'UPDATE';
+                    changes.push({
+                        tableName: table,
+                        operation,
+                        rowId,
+                        payload: isSoftDeleted ? null : data,
+                        timestamp: rowTime,
+                    });
+                }
+            }
+            return {
+                timestamp: changes.length > 0 ? maxServerTimestamp : sinceTimestamp,
+                changes,
+            };
+        }
+        catch (error) {
+            this.logger.error((0, logger_js_1.formatFirestoreError)(error, { operation: 'fetchChanges' }));
+            return { timestamp: sinceTimestamp, changes: [] };
+        }
+    }
+    /**
+     * Subscribes to live real-time query updates via onSnapshot.
+     */
+    subscribeToLiveChanges(callback) {
+        this.destroy();
+        if (!this.tables || this.tables.length === 0) {
+            return;
+        }
+        const setupListeners = async () => {
+            const isCompat = typeof this.db.collection === 'function';
+            const mod = isCompat ? null : await this.getModule();
+            const currentCursor = Date.now() - 2000;
+            for (const table of this.tables) {
+                try {
+                    const handleSnapshot = (snapshot) => {
+                        if (!snapshot)
+                            return;
+                        let docList = [];
+                        if (typeof snapshot.docChanges === 'function') {
+                            const docChanges = snapshot.docChanges();
+                            if (docChanges && docChanges.length > 0) {
+                                docList = docChanges.map((dc) => ({
+                                    doc: dc.doc,
+                                    isRemoved: dc.type === 'removed',
+                                }));
+                            }
+                        }
+                        else if (snapshot.docs) {
+                            docList = snapshot.docs.map((doc) => ({ doc, isRemoved: false }));
+                        }
+                        if (docList.length === 0)
+                            return;
+                        const changes = [];
+                        for (const item of docList) {
+                            const doc = item.doc;
+                            const data = typeof doc.data === 'function' ? doc.data() : doc;
+                            const isSoftDeleted = Boolean(item.isRemoved ||
+                                data[this.deletedColumn] === true ||
+                                data[this.deletedColumn] === 1);
+                            const rowTime = extractTimestamp(data[this.updatedAtColumn]);
+                            const rowId = String(data[this.primaryKey] || doc.id || data.id);
+                            changes.push({
+                                tableName: table,
+                                operation: isSoftDeleted ? 'DELETE' : 'UPDATE',
+                                rowId,
+                                payload: isSoftDeleted ? null : data,
+                                timestamp: rowTime,
+                            });
+                        }
+                        if (changes.length > 0) {
+                            const maxTime = Math.max(...changes.map((c) => c.timestamp || 0));
+                            callback({
+                                timestamp: maxTime > 0 ? maxTime : Date.now(),
+                                changes,
+                            });
+                        }
+                    };
+                    if (isCompat) {
+                        const unsub = this.db
+                            .collection(table)
+                            .where(this.updatedAtColumn, '>', currentCursor)
+                            .onSnapshot(handleSnapshot, (err) => {
+                            console.warn(`Firestore onSnapshot error on ${table}:`, err);
+                        });
+                        if (typeof unsub === 'function') {
+                            this.unsubscribers.push(unsub);
+                        }
+                    }
+                    else if (mod && typeof mod.onSnapshot === 'function') {
+                        const q = mod.query(mod.collection(this.db, table), mod.where(this.updatedAtColumn, '>', currentCursor));
+                        const unsub = mod.onSnapshot(q, handleSnapshot, (err) => {
+                            console.warn(`Firestore modular onSnapshot error on ${table}:`, err);
+                        });
+                        if (typeof unsub === 'function') {
+                            this.unsubscribers.push(unsub);
+                        }
+                    }
+                }
+                catch (err) {
+                    console.warn(`Failed to initialize Firestore live listener for table ${table}:`, err);
+                }
+            }
+        };
+        setupListeners();
+    }
+    /**
+     * Cleans up all active real-time listeners.
+     */
+    destroy() {
+        for (const unsub of this.unsubscribers) {
+            try {
+                unsub();
+            }
+            catch { }
+        }
+        this.unsubscribers = [];
+    }
+}
+exports.FirestoreRemoteAdapter = FirestoreRemoteAdapter;

package/dist/adapters/remote/index.d.ts

@@ -0,0 +1,10 @@
+import { SyncOperation, DeltaChanges } from '../../core/types.js';
+export interface RemoteDBAdapter {
+    pushChanges(operations: SyncOperation[]): Promise<boolean>;
+    fetchChanges(sinceTimestamp: number): Promise<DeltaChanges>;
+    subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
+}
+export * from './supabase.js';
+export * from './demo.js';
+export * from './convex.js';
+export * from './firestore.js';

package/dist/adapters/remote/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("./supabase.js"), exports);
+__exportStar(require("./demo.js"), exports);
+__exportStar(require("./convex.js"), exports);
+__exportStar(require("./firestore.js"), exports);

package/dist/adapters/remote/supabase.d.ts

@@ -0,0 +1,97 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { RemoteDBAdapter } from './index.js';
+import { DeltaChanges, SyncOperation } from '../../core/types.js';
+import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+export interface SupabaseAdapterOptions {
+    /**
+     * The list of Postgres tables to sync.
+     * e.g. ['todos', 'notes']
+     */
+    tables?: string[];
+    /**
+     * Timestamp column name on Postgres tables used to track updates.
+     * Default: 'updated_at'
+     */
+    updatedAtColumn?: string;
+    /**
+     * Primary key column name on Postgres tables.
+     * Default: 'id'
+     */
+    primaryKey?: string;
+    /**
+     * Soft-delete column name (e.g. 'deleted', 'is_deleted', or 'deleted_at').
+     * Default: 'deleted'
+     */
+    deletedColumn?: string;
+    /**
+     * Value to write when soft-deleting a row.
+     * Default: true
+     */
+    deletedValue?: any;
+    /**
+     * Legacy alias for deletedColumn.
+     */
+    deletedAtColumn?: string;
+    /**
+     * Optional custom Postgres RPC function name for batch pushing.
+     * If provided, will call `supabase.rpc(pushRpcName, { operations })`.
+     */
+    pushRpcName?: string;
+    /**
+     * Postgres schema name.
+     * Default: 'public'
+     */
+    schema?: string;
+    /**
+     * Name of the Realtime channel.
+     * Default: 'local_first_sync'
+     */
+    channelName?: string;
+    /**
+     * Custom logger or false to silence logs in production.
+     */
+    logger?: SyncLogger | CustomLogger | boolean;
+    /**
+     * Minimum log level. Default: 'info'
+     */
+    logLevel?: LogLevel;
+}
+export declare class SupabaseRemoteAdapter implements RemoteDBAdapter {
+    private client;
+    private tables;
+    private updatedAtColumn;
+    private primaryKey;
+    private deletedColumn;
+    private deletedValue;
+    private pushRpcName?;
+    private schema;
+    private channelName;
+    private activeChannel?;
+    logger: SyncLogger;
+    constructor(client: SupabaseClient, options?: SupabaseAdapterOptions);
+    /**
+     * Set or update tracked tables dynamically.
+     */
+    setTables(tables: string[]): void;
+    /**
+     * Pushes outbox operations to Supabase.
+     */
+    pushChanges(operations: SyncOperation[]): Promise<boolean>;
+    /**
+     * Fetches delta changes from Supabase since a given timestamp.
+     * Reads updated records and checks `deleted: true` to propagate soft deletes.
+     */
+    fetchChanges(sinceTimestamp: number): Promise<DeltaChanges>;
+    /**
+     * Helper to determine if a record represents a soft delete.
+     */
+    private isSoftDeleted;
+    /**
+     * Subscribes to live realtime postgres_changes from Supabase.
+     */
+    subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
+    /**
+     * Clean up active realtime channels.
+     */
+    destroy(): void;
+}