local-lite 0.0.12 → 0.0.15

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,8 @@ 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';
+export * from './access/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,8 @@ __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);
+__exportStar(require("./access/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/react/index.d.ts

@@ -111,6 +111,18 @@ export interface UseMutationsResult<TTable extends string = string> {
  * Universal mutations hook providing memoized, null-safe helpers for database operations.
  */
 export declare function useMutations<TTable extends string = string>(client: LocalFirstClient | null | undefined): UseMutationsResult<TTable>;
+export interface UseDatabaseMaintenanceResult {
+    stats: import('../core/maintenance.js').StorageStats | null;
+    loading: boolean;
+    refreshStats: () => Promise<import('../core/maintenance.js').StorageStats | null>;
+    pruneOutbox: (options?: import('../core/maintenance.js').PruneOutboxOptions) => Promise<number>;
+    vacuum: () => Promise<void>;
+    checkpoint: (mode?: import('../core/maintenance.js').CheckpointMode) => Promise<void>;
+}
+/**
+ * Reactive hook for database maintenance (vacuum, WAL checkpoint, outbox pruning, and storage metrics).
+ */
+export declare function useDatabaseMaintenance(client: LocalFirstClient | null | undefined): UseDatabaseMaintenanceResult;
 export * from './runner.js';
 export * from './status.js';
 export * from './theme.js';

package/dist/react/index.js

@@ -21,6 +21,7 @@ exports.useLiveQueries = useLiveQueries;
 exports.useLiveRow = useLiveRow;
 exports.useLiveInfiniteQuery = useLiveInfiniteQuery;
 exports.useMutations = useMutations;
+exports.useDatabaseMaintenance = useDatabaseMaintenance;
 const react_1 = require("react");
 const runner_js_1 = require("./runner.js");
 function areRowsEqual(a, b) {
@@ -587,6 +588,56 @@ function useMutations(client) {
         transaction: (action) => client ? client.transaction(action) : Promise.resolve(undefined),
     }), [client]);
 }
+/**
+ * Reactive hook for database maintenance (vacuum, WAL checkpoint, outbox pruning, and storage metrics).
+ */
+function useDatabaseMaintenance(client) {
+    const [stats, setStats] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const refreshStats = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return null;
+        setLoading(true);
+        try {
+            const res = await client.maintenance.getStorageStats();
+            setStats(res);
+            return res;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const pruneOutbox = (0, react_1.useCallback)(async (options) => {
+        if (!client)
+            return 0;
+        const count = await client.maintenance.pruneOutbox(options);
+        await refreshStats();
+        return count;
+    }, [client, refreshStats]);
+    const vacuum = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        await client.maintenance.vacuum();
+        await refreshStats();
+    }, [client, refreshStats]);
+    const checkpoint = (0, react_1.useCallback)(async (mode) => {
+        if (!client)
+            return;
+        await client.maintenance.checkpoint(mode);
+        await refreshStats();
+    }, [client, refreshStats]);
+    return {
+        stats,
+        loading,
+        refreshStats,
+        pruneOutbox,
+        vacuum,
+        checkpoint,
+    };
+}
 __exportStar(require("./runner.js"), exports);
 __exportStar(require("./status.js"), exports);
 __exportStar(require("./theme.js"), exports);

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;
+}>;