local-lite 0.0.12 → 0.0.14

package/dist/core/maintenance.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseMaintenance = void 0;
+const sql_js_1 = require("../utils/sql.js");
+class DatabaseMaintenance {
+    db;
+    getKnownTables;
+    constructor(db, getKnownTables = () => []) {
+        this.db = db;
+        this.getKnownTables = getKnownTables;
+    }
+    /**
+     * Reclaims unused space, defragments the database file, and optimizes internal B-trees.
+     */
+    async vacuum() {
+        await this.db.execute('VACUUM');
+    }
+    /**
+     * Checkpoints WAL (Write-Ahead Log) pages into the main database file.
+     * 'TRUNCATE' (default) copies all WAL frames to the database file and resets WAL size to zero.
+     */
+    async checkpoint(mode = 'TRUNCATE') {
+        await this.db.execute(`PRAGMA wal_checkpoint(${mode})`);
+    }
+    /**
+     * Prunes old or completed mutations from the sync_outbox table to keep database footprint small.
+     * Returns the count of deleted outbox records.
+     */
+    async pruneOutbox(options = {}) {
+        const statuses = options.statuses ?? ['COMPLETED', 'FAILED'];
+        if (statuses.length === 0)
+            return 0;
+        let cutoffTimestamp = options.beforeTimestamp;
+        if (options.retentionDays !== undefined && options.retentionDays >= 0) {
+            const daysMs = options.retentionDays * 24 * 60 * 60 * 1000;
+            const calculatedCutoff = Date.now() - daysMs;
+            cutoffTimestamp = cutoffTimestamp !== undefined
+                ? Math.min(cutoffTimestamp, calculatedCutoff)
+                : calculatedCutoff;
+        }
+        const conditions = [];
+        const params = [];
+        const statusPlaceholders = statuses.map(() => '?').join(', ');
+        conditions.push(`status IN (${statusPlaceholders})`);
+        params.push(...statuses);
+        if (cutoffTimestamp !== undefined) {
+            conditions.push('timestamp < ?');
+            params.push(cutoffTimestamp);
+        }
+        const whereClause = `WHERE ${conditions.join(' AND ')}`;
+        // If maxEntries is set, only prune if total matching exceeds maxEntries
+        if (options.maxEntries !== undefined && options.maxEntries >= 0) {
+            const countRes = await this.db.execute(`SELECT COUNT(*) as total FROM sync_outbox ${whereClause}`, params);
+            const totalMatching = Number(countRes[0]?.total ?? 0);
+            const excess = totalMatching - options.maxEntries;
+            if (excess <= 0) {
+                return 0;
+            }
+            // Delete the oldest `excess` records
+            const selectOldest = await this.db.execute(`SELECT id FROM sync_outbox ${whereClause} ORDER BY timestamp ASC LIMIT ?`, [...params, excess]);
+            if (selectOldest.length === 0)
+                return 0;
+            const ids = selectOldest.map((r) => r.id);
+            const idPlaceholders = ids.map(() => '?').join(', ');
+            await this.db.execute(`DELETE FROM sync_outbox WHERE id IN (${idPlaceholders})`, ids);
+            return ids.length;
+        }
+        // Standard cutoff delete
+        const beforeCountRes = await this.db.execute(`SELECT COUNT(*) as total FROM sync_outbox ${whereClause}`, params);
+        const toDeleteCount = Number(beforeCountRes[0]?.total ?? 0);
+        if (toDeleteCount === 0)
+            return 0;
+        await this.db.execute(`DELETE FROM sync_outbox ${whereClause}`, params);
+        return toDeleteCount;
+    }
+    /**
+     * Gathers storage metrics: table row counts, outbox status distribution, and database size.
+     */
+    async getStorageStats() {
+        // 1. Table row counts
+        const tableCounts = {};
+        let tableNames = [];
+        try {
+            const masterRows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`);
+            tableNames = masterRows.map((r) => r.name);
+        }
+        catch {
+            tableNames = this.getKnownTables();
+        }
+        for (const tableName of tableNames) {
+            try {
+                const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+                const rows = await this.db.execute(`SELECT COUNT(*) as count FROM ${safeTable}`);
+                tableCounts[tableName] = Number(rows[0]?.count ?? 0);
+            }
+            catch {
+                // Table might not exist or be accessible
+            }
+        }
+        // 2. Outbox breakdown
+        const outboxStats = {
+            total: 0,
+            pending: 0,
+            processing: 0,
+            completed: 0,
+            failed: 0,
+        };
+        try {
+            const outboxRows = await this.db.execute(`SELECT status, COUNT(*) as count FROM sync_outbox GROUP BY status`);
+            for (const row of outboxRows) {
+                const st = String(row.status).toUpperCase();
+                const cnt = Number(row.count ?? 0);
+                outboxStats.total += cnt;
+                if (st === 'PENDING')
+                    outboxStats.pending = cnt;
+                else if (st === 'PROCESSING')
+                    outboxStats.processing = cnt;
+                else if (st === 'COMPLETED')
+                    outboxStats.completed = cnt;
+                else if (st === 'FAILED')
+                    outboxStats.failed = cnt;
+            }
+        }
+        catch {
+            // sync_outbox table may not exist yet
+        }
+        // 3. SQLite database sizing via PRAGMAs
+        let pageSize = 4096;
+        let pageCount = 0;
+        try {
+            const pageSizeRes = await this.db.execute('PRAGMA page_size');
+            if (pageSizeRes[0]) {
+                pageSize = Number(Object.values(pageSizeRes[0])[0] ?? 4096);
+            }
+        }
+        catch {
+            // fallback
+        }
+        try {
+            const pageCountRes = await this.db.execute('PRAGMA page_count');
+            if (pageCountRes[0]) {
+                pageCount = Number(Object.values(pageCountRes[0])[0] ?? 0);
+            }
+        }
+        catch {
+            // fallback
+        }
+        return {
+            tables: tableCounts,
+            outbox: outboxStats,
+            pageSize,
+            pageCount,
+            databaseSizeBytes: pageSize * pageCount,
+        };
+    }
+}
+exports.DatabaseMaintenance = DatabaseMaintenance;

package/dist/core/sync-worker.js

@@ -654,7 +654,7 @@ class SyncWorker {
                         }
                     }
                     // 3. Apply remote change to local database
-                    await table_manager_js_1.TableManager.applyMutation(tx, change.tableName, change.rowId, change.operation, change.payload, this.primaryKey, { autoSchema: this.autoSchema, schemaManager: this.schemaManager });
+                    await table_manager_js_1.TableManager.applyMutation(tx, change.tableName, change.rowId, change.operation, change.payload ?? null, this.primaryKey, { autoSchema: this.autoSchema, schemaManager: this.schemaManager });
                     // 4. Queue table change event to notify reactive listeners after commit
                     queuedEvents.push({
                         event: change.tableName,

package/dist/core/types.d.ts

@@ -5,7 +5,7 @@ export interface SyncOperation {
     tableName: string;
     rowId: string;
     operation: SyncOp;
-    payload: Record<string, any> | null;
+    payload?: Record<string, any> | null;
     timestamp: number;
 }
 export interface PushResult {
@@ -16,14 +16,14 @@ export interface PushResult {
 }
 export interface OutboxRecord extends SyncOperation {
     status: OutboxStatus;
-    retryCount: number;
+    retryCount?: number;
     lastError?: string | null;
 }
 export interface DeltaChange {
     tableName: string;
     operation: SyncOp;
     rowId: string;
-    payload: Record<string, any> | null;
+    payload?: Record<string, any> | null;
     timestamp?: number;
 }
 export interface DeltaChanges {
@@ -41,7 +41,37 @@ export interface ConflictContext {
     localRow?: Record<string, any> | null;
 }
 export type ConflictResolver = (context: ConflictContext) => ConflictResolution | Promise<ConflictResolution>;
-export type ConflictStrategy = 'last-write-wins' | 'server-wins' | 'client-wins';
+export type ConflictStrategy = 'last-write-wins' | 'server-wins' | 'client-wins' | 'field-merge';
+export type FieldMergeWinner = 'remote' | 'local' | 'newer' | 'max' | 'min';
+export type FieldMergeCustomResolver = (localVal: any, remoteVal: any, context: ConflictContext) => any;
+export type FieldMergeRule = FieldMergeWinner | FieldMergeCustomResolver;
+export interface FieldMergeResolverOptions {
+    /**
+     * Default resolution strategy when both local and remote updated the exact same field.
+     * 'newer' (default) uses timestamp to pick the newer field; 'remote' or 'local' picks fixed side.
+     */
+    defaultWinner?: 'remote' | 'local' | 'newer';
+    /**
+     * Field-level merge rules by table and column.
+     * e.g.
+     * {
+     *   notes: {
+     *     tags: (local, remote) => Array.from(new Set([...(local ?? []), ...(remote ?? [])])),
+     *     view_count: 'max',
+     *   },
+     *   '*': {
+     *     updated_at: 'newer'
+     *   }
+     * }
+     */
+    fieldRules?: Record<string, Record<string, FieldMergeRule>>;
+    /**
+     * Strategy when one side deleted the row while the other side updated fields.
+     * 'delete-wins' (default) preserves the deletion.
+     * 'update-wins' resurrects the row with the updated fields.
+     */
+    deleteHandling?: 'delete-wins' | 'update-wins';
+}
 export interface NetworkStatusProvider {
     isOnline(): boolean | Promise<boolean>;
     subscribe(callback: (isOnline: boolean) => void): () => void;

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './core/meta-store.js';
 export * from './core/table-manager.js';
 export * from './core/schema-manager.js';
 export * from './core/query-builder.js';
+export * from './core/maintenance.js';
 export * from './reactive/event-emitter.js';
 export * from './adapters/local/index.js';
 export * from './adapters/remote/index.js';
@@ -17,6 +18,7 @@ export type * from './react/index.js';
 export * from './utils/uuid.js';
 export * from './utils/sql.js';
 export * from './utils/logger.js';
+export * from './utils/portability.js';
 export * from './schema/index.js';
 export * from './auth/index.js';
 export * from './backups/index.js';

package/dist/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./core/meta-store.js"), exports);
 __exportStar(require("./core/table-manager.js"), exports);
 __exportStar(require("./core/schema-manager.js"), exports);
 __exportStar(require("./core/query-builder.js"), exports);
+__exportStar(require("./core/maintenance.js"), exports);
 __exportStar(require("./reactive/event-emitter.js"), exports);
 __exportStar(require("./adapters/local/index.js"), exports);
 __exportStar(require("./adapters/remote/index.js"), exports);
@@ -32,6 +33,7 @@ __exportStar(require("./config/index.js"), exports);
 __exportStar(require("./utils/uuid.js"), exports);
 __exportStar(require("./utils/sql.js"), exports);
 __exportStar(require("./utils/logger.js"), exports);
+__exportStar(require("./utils/portability.js"), exports);
 __exportStar(require("./schema/index.js"), exports);
 __exportStar(require("./auth/index.js"), exports);
 __exportStar(require("./backups/index.js"), exports);

package/dist/react/auth.d.ts

@@ -1,4 +1,7 @@
 import type { GoogleAuthClient, GoogleUser } from '../auth/google.js';
+import type { MicrosoftAuthClient, MicrosoftUser } from '../auth/microsoft.js';
+import type { GitHubAuthClient, GitHubUser } from '../auth/github.js';
+import type { AppleAuthClient, AppleUser, AppleNativeCredential } from '../auth/apple.js';
 export interface UseGoogleAuthResult {
     user: GoogleUser | null;
     isSignedIn: boolean;
@@ -9,3 +12,35 @@ export interface UseGoogleAuthResult {
     refetchUser: () => Promise<GoogleUser | null>;
 }
 export declare function useGoogleAuth(client: GoogleAuthClient | null | undefined): UseGoogleAuthResult;
+export interface UseMicrosoftAuthResult {
+    user: MicrosoftUser | null;
+    isSignedIn: boolean;
+    loading: boolean;
+    error: Error | null;
+    signIn: () => Promise<MicrosoftUser | null>;
+    signOut: () => Promise<void>;
+    refetchUser: () => Promise<MicrosoftUser | null>;
+}
+export type UseOneDriveAuthResult = UseMicrosoftAuthResult;
+export declare function useMicrosoftAuth(client: MicrosoftAuthClient | null | undefined): UseMicrosoftAuthResult;
+export declare const useOneDriveAuth: typeof useMicrosoftAuth;
+export interface UseGitHubAuthResult {
+    user: GitHubUser | null;
+    isSignedIn: boolean;
+    loading: boolean;
+    error: Error | null;
+    signIn: () => Promise<GitHubUser | null>;
+    signOut: () => Promise<void>;
+    refetchUser: () => Promise<GitHubUser | null>;
+}
+export declare function useGitHubAuth(client: GitHubAuthClient | null | undefined): UseGitHubAuthResult;
+export interface UseAppleAuthResult {
+    user: AppleUser | null;
+    isSignedIn: boolean;
+    loading: boolean;
+    error: Error | null;
+    signIn: (nativeCredential?: AppleNativeCredential) => Promise<AppleUser | null>;
+    signOut: () => Promise<void>;
+    refetchUser: () => Promise<AppleUser | null>;
+}
+export declare function useAppleAuth(client: AppleAuthClient | null | undefined): UseAppleAuthResult;

package/dist/react/auth.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOneDriveAuth = void 0;
 exports.useGoogleAuth = useGoogleAuth;
+exports.useMicrosoftAuth = useMicrosoftAuth;
+exports.useGitHubAuth = useGitHubAuth;
+exports.useAppleAuth = useAppleAuth;
 const react_1 = require("react");
 function useGoogleAuth(client) {
     const [user, setUser] = (0, react_1.useState)(null);
@@ -91,3 +95,271 @@ function useGoogleAuth(client) {
         refetchUser,
     };
 }
+function useMicrosoftAuth(client) {
+    const [user, setUser] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!client) {
+            setUser(null);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        client
+            .getUser()
+            .then(currentUser => {
+            if (isMounted) {
+                setUser(currentUser);
+                setLoading(false);
+            }
+        })
+            .catch(err => {
+            if (isMounted) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        });
+        const unsubscribe = client.onAuthStateChange(updatedUser => {
+            if (isMounted) {
+                setUser(updatedUser);
+            }
+        });
+        return () => {
+            isMounted = false;
+            unsubscribe();
+        };
+    }, [client]);
+    const signIn = (0, react_1.useCallback)(async () => {
+        if (!client)
+            throw new Error('MicrosoftAuthClient is not initialized.');
+        setError(null);
+        setLoading(true);
+        try {
+            const res = await client.signIn();
+            setUser(res);
+            return res;
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const signOut = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        setError(null);
+        setLoading(true);
+        try {
+            await client.signOut();
+            setUser(null);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const refetchUser = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return null;
+        const res = await client.getUser();
+        setUser(res);
+        return res;
+    }, [client]);
+    return {
+        user,
+        isSignedIn: Boolean(user),
+        loading,
+        error,
+        signIn,
+        signOut,
+        refetchUser,
+    };
+}
+exports.useOneDriveAuth = useMicrosoftAuth;
+function useGitHubAuth(client) {
+    const [user, setUser] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!client) {
+            setUser(null);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        client
+            .getUser()
+            .then(currentUser => {
+            if (isMounted) {
+                setUser(currentUser);
+                setLoading(false);
+            }
+        })
+            .catch(err => {
+            if (isMounted) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        });
+        const unsubscribe = client.onAuthStateChange(updatedUser => {
+            if (isMounted) {
+                setUser(updatedUser);
+            }
+        });
+        return () => {
+            isMounted = false;
+            unsubscribe();
+        };
+    }, [client]);
+    const signIn = (0, react_1.useCallback)(async () => {
+        if (!client)
+            throw new Error('GitHubAuthClient is not initialized.');
+        setError(null);
+        setLoading(true);
+        try {
+            const res = await client.signIn();
+            setUser(res);
+            return res;
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const signOut = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        setError(null);
+        setLoading(true);
+        try {
+            await client.signOut();
+            setUser(null);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const refetchUser = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return null;
+        const res = await client.getUser();
+        setUser(res);
+        return res;
+    }, [client]);
+    return {
+        user,
+        isSignedIn: Boolean(user),
+        loading,
+        error,
+        signIn,
+        signOut,
+        refetchUser,
+    };
+}
+function useAppleAuth(client) {
+    const [user, setUser] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!client) {
+            setUser(null);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        client
+            .getUser()
+            .then(currentUser => {
+            if (isMounted) {
+                setUser(currentUser);
+                setLoading(false);
+            }
+        })
+            .catch(err => {
+            if (isMounted) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        });
+        const unsubscribe = client.onAuthStateChange(updatedUser => {
+            if (isMounted) {
+                setUser(updatedUser);
+            }
+        });
+        return () => {
+            isMounted = false;
+            unsubscribe();
+        };
+    }, [client]);
+    const signIn = (0, react_1.useCallback)(async (nativeCredential) => {
+        if (!client)
+            throw new Error('AppleAuthClient is not initialized.');
+        setError(null);
+        setLoading(true);
+        try {
+            const res = await client.signIn(nativeCredential);
+            setUser(res);
+            return res;
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const signOut = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        setError(null);
+        setLoading(true);
+        try {
+            await client.signOut();
+            setUser(null);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const refetchUser = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return null;
+        const res = await client.getUser();
+        setUser(res);
+        return res;
+    }, [client]);
+    return {
+        user,
+        isSignedIn: Boolean(user),
+        loading,
+        error,
+        signIn,
+        signOut,
+        refetchUser,
+    };
+}

package/dist/utils/portability.d.ts

@@ -0,0 +1,73 @@
+import type { LocalFirstClient } from '../core/client.js';
+export interface ExportJsonOptions {
+    /** Pretty-print JSON with 2-space indentation. Default: false */
+    pretty?: boolean;
+    /** Explicit list of tables to export. If not specified, exports all registered tables. */
+    tables?: string[];
+}
+export interface JsonExportData {
+    version: number;
+    exportedAt: string;
+    tables: Record<string, Array<Record<string, any>>>;
+}
+export interface ImportJsonOptions {
+    /**
+     * 'merge' (default): updates existing rows and inserts new rows using primary key.
+     * 'replace': deletes all rows in the table before inserting the imported data.
+     */
+    mode?: 'merge' | 'replace';
+    /**
+     * Whether to skip queueing outbox mutations for remote sync.
+     * When true, imported data is only stored in local SQLite without triggering sync pushes.
+     * Default: false.
+     */
+    skipOutbox?: boolean;
+    /** Whitelist of tables to import. If specified, any tables in JSON not in this list are ignored. */
+    tables?: string[];
+}
+export interface ExportCsvOptions {
+    /** Columns to export in order. If omitted, uses all columns from the table. */
+    columns?: string[];
+    /** Field delimiter. Default: ',' */
+    delimiter?: string;
+    /** Whether to output the first row as column headers. Default: true */
+    includeHeader?: boolean;
+}
+export interface ImportCsvOptions {
+    /** 'merge' (default) or 'replace' */
+    mode?: 'merge' | 'replace';
+    /** Whether to skip queueing outbox records. Default: false */
+    skipOutbox?: boolean;
+    /** Field delimiter. Default: ',' */
+    delimiter?: string;
+    /** Whether the first line contains header columns. Default: true */
+    hasHeader?: boolean;
+    /** Explicit column names if CSV has no header. */
+    columns?: string[];
+}
+export interface ImportSummary {
+    tables: string[];
+    rowCounts: Record<string, number>;
+}
+/**
+ * Robust RFC-4180 CSV parser supporting multiline fields and escaped quotes.
+ */
+export declare function parseCsv(text: string, delimiter?: string): string[][];
+/**
+ * Exports SQLite tables to a structured JSON string.
+ */
+export declare function exportTablesToJson(client: LocalFirstClient, tables?: string[], options?: ExportJsonOptions): Promise<string>;
+/**
+ * Imports tables from a JSON export string into the database.
+ */
+export declare function importTablesFromJson(client: LocalFirstClient, jsonString: string, options?: ImportJsonOptions): Promise<ImportSummary>;
+/**
+ * Exports a single SQLite table to an RFC-4180 CSV string.
+ */
+export declare function exportTableToCsv(client: LocalFirstClient, tableName: string, options?: ExportCsvOptions): Promise<string>;
+/**
+ * Imports an RFC-4180 CSV string into a SQLite table.
+ */
+export declare function importTableFromCsv(client: LocalFirstClient, tableName: string, csvString: string, options?: ImportCsvOptions): Promise<{
+    rowCount: number;
+}>;