local-lite 0.0.14 → 0.0.16

package/dist/backups/operations.d.ts

@@ -0,0 +1,39 @@
+import { type EncryptedBackupOptions, type RestoreEncryptedBackupOptions } from './encryption.js';
+import type { CloudBackupFile } from './cloud-storage.js';
+export type BackupAccessTokenProvider = () => Promise<string>;
+export interface BackupDatabase {
+    exportDatabase(): Promise<Uint8Array>;
+    importDatabase(data: Uint8Array): Promise<void>;
+}
+export interface BackupStorage {
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileName: string): Promise<Uint8Array>;
+    list?(): Promise<CloudBackupFile[]>;
+    delete?(fileName: string): Promise<void>;
+}
+export interface CloudBackupClient extends BackupStorage {
+    connect(): Promise<boolean>;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+    list(): Promise<CloudBackupFile[]>;
+    deleteBackup?(fileIdOrName: string): Promise<void>;
+    onStatusChange?(listener: (connected: boolean) => void): () => void;
+    backup?(database: ResolvableBackupDatabase, options?: CreateDatabaseBackupOptions & Partial<EncryptedBackupOptions>): Promise<string>;
+    restore?(database: ResolvableBackupDatabase, fileNameOrId: string, options?: Partial<RestoreEncryptedBackupOptions>): Promise<void>;
+}
+export interface CreateDatabaseBackupOptions {
+    fileName?: string;
+}
+export type ResolvableBackupDatabase = BackupDatabase | {
+    exportDatabase(): Promise<Uint8Array>;
+    importDatabase(data: Uint8Array): Promise<void>;
+} | {
+    db: any;
+    exportDatabase?(): Promise<Uint8Array>;
+    importDatabase?(data: Uint8Array): Promise<void>;
+};
+export declare function resolveBackupDatabase(target: any): BackupDatabase;
+export declare function createDatabaseBackup(database: ResolvableBackupDatabase, storage: BackupStorage, options?: CreateDatabaseBackupOptions): Promise<string>;
+export declare function restoreDatabaseBackup(database: ResolvableBackupDatabase, storage: BackupStorage, fileName: string): Promise<void>;
+export declare function performBackup(database: ResolvableBackupDatabase, storage: BackupStorage, options?: CreateDatabaseBackupOptions & Partial<EncryptedBackupOptions>): Promise<string>;
+export declare function performRestore(database: ResolvableBackupDatabase, storage: BackupStorage, fileNameOrId: string, options?: Partial<RestoreEncryptedBackupOptions>): Promise<void>;

package/dist/backups/operations.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBackupDatabase = resolveBackupDatabase;
+exports.createDatabaseBackup = createDatabaseBackup;
+exports.restoreDatabaseBackup = restoreDatabaseBackup;
+exports.performBackup = performBackup;
+exports.performRestore = performRestore;
+const encryption_js_1 = require("./encryption.js");
+function resolveBackupDatabase(target) {
+    if (!target) {
+        throw new Error('A valid database or LocalFirstClient is required for backup.');
+    }
+    if (typeof target.exportDatabase === 'function' && typeof target.importDatabase === 'function') {
+        return target;
+    }
+    if (target.db &&
+        typeof target.db.exportDatabase === 'function' &&
+        typeof target.db.importDatabase === 'function') {
+        return target.db;
+    }
+    throw new Error('Provided target does not implement BackupDatabase. It must provide exportDatabase() and importDatabase().');
+}
+function validateFileName(fileName) {
+    if (!fileName || /[\\/]/.test(fileName)) {
+        throw new Error('Backup file name must be a single file name.');
+    }
+}
+async function createDatabaseBackup(database, storage, options = {}) {
+    const resolved = resolveBackupDatabase(database);
+    const fileName = options.fileName ?? `local-lite-${new Date().toISOString().replace(/[:.]/g, '-')}.db`;
+    validateFileName(fileName);
+    const databaseBytes = await resolved.exportDatabase();
+    if (databaseBytes.length === 0) {
+        throw new Error('Cannot create a backup from an empty database.');
+    }
+    await storage.save(fileName, databaseBytes);
+    return fileName;
+}
+async function restoreDatabaseBackup(database, storage, fileName) {
+    validateFileName(fileName);
+    const resolved = resolveBackupDatabase(database);
+    const databaseBytes = await storage.read(fileName);
+    if (databaseBytes.length === 0) {
+        throw new Error('Cannot restore an empty database backup.');
+    }
+    await resolved.importDatabase(databaseBytes);
+}
+async function performBackup(database, storage, options = {}) {
+    const resolved = resolveBackupDatabase(database);
+    if (options.passphrase && options.passphrase.trim()) {
+        return (0, encryption_js_1.createEncryptedDatabaseBackup)(resolved, storage, {
+            passphrase: options.passphrase,
+            fileName: options.fileName,
+            iterations: options.iterations,
+        });
+    }
+    return createDatabaseBackup(resolved, storage, options);
+}
+async function performRestore(database, storage, fileNameOrId, options = {}) {
+    const resolved = resolveBackupDatabase(database);
+    if (options.passphrase && options.passphrase.trim()) {
+        return (0, encryption_js_1.restoreEncryptedDatabaseBackup)(resolved, storage, fileNameOrId, {
+            passphrase: options.passphrase,
+        });
+    }
+    const rawBytes = await storage.read(fileNameOrId);
+    if ((0, encryption_js_1.isEncryptedBackup)(rawBytes)) {
+        throw new Error('This backup is encrypted. A passphrase is required to restore it.');
+    }
+    if (rawBytes.length === 0) {
+        throw new Error('Cannot restore an empty database backup.');
+    }
+    await resolved.importDatabase(rawBytes);
+}

package/dist/config/resolve-remote.js

@@ -46,7 +46,6 @@ async function resolveRemoteAdapter(config) {
         updatedAtColumn: config.supabase?.updatedAtColumn,
         deletedColumn: config.supabase?.deletedColumn,
         deletedValue: config.supabase?.deletedValue,
-        deletedAtColumn: config.supabase?.deletedAtColumn,
         pushRpcName: config.supabase?.pushRpcName,
         channelName: config.supabase?.channelName,
         scopedTables: config.supabase?.scopedTables,

package/dist/core/client.d.ts

@@ -7,6 +7,8 @@ import { SchemaManager } from './schema-manager.js';
 import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 import { QueryBuilder, AggregateSpec, AggregateResult } from './query-builder.js';
+import { type ExportJsonOptions, type ImportJsonOptions, type ExportCsvOptions, type ImportCsvOptions, type ImportSummary } from '../utils/portability.js';
+import { type BackupStorage, type CreateDatabaseBackupOptions, type EncryptedBackupOptions, type RestoreEncryptedBackupOptions } from '../backups/index.js';
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -62,6 +64,10 @@ export declare class TransactionalClient {
         includeDeleted?: boolean;
     }): Promise<T[]>;
     findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Alias for findMany().
+     */
+    find<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
     query<T = any>(sql: string, params?: any[]): Promise<T[]>;
     from<T = any>(tableName: string): QueryBuilder<T>;
     get rawTx(): LocalTransaction;
@@ -227,6 +233,32 @@ export declare class LocalFirstClient {
      */
     aggregate(tableName: string, spec: AggregateSpec): Promise<AggregateResult>;
     findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Alias for findMany().
+     */
+    find<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Returns true if client storage has successfully initialized.
+     */
+    get isReady(): boolean;
+    /**
+     * Convenience export of tables to JSON.
+     */
+    exportToJson(tables?: string[], options?: ExportJsonOptions): Promise<string>;
+    /**
+     * Convenience import of tables from JSON.
+     */
+    importFromJson(jsonString: string, options?: ImportJsonOptions): Promise<ImportSummary>;
+    /**
+     * Convenience export of a table to RFC-4180 CSV.
+     */
+    exportToCsv(tableName: string, options?: ExportCsvOptions): Promise<string>;
+    /**
+     * Convenience import of RFC-4180 CSV into a table.
+     */
+    importFromCsv(tableName: string, csvString: string, options?: ImportCsvOptions): Promise<{
+        rowCount: number;
+    }>;
     /**
      * Finds a single record by primary key.
      *
@@ -294,4 +326,23 @@ export declare class LocalFirstClient {
     reset(options?: {
         dropTables?: boolean;
     }): Promise<void>;
+    private getAllTableNames;
+    /**
+     * Exports the entire local database state as a portable binary snapshot.
+     * If the local adapter has a native export mechanism (e.g. serialize or export),
+     * it uses that; otherwise, it exports an atomic JSON snapshot of all tables.
+     */
+    exportDatabase(): Promise<Uint8Array>;
+    /**
+     * Imports database state from a backup snapshot.
+     */
+    importDatabase(data: Uint8Array): Promise<void>;
+    /**
+     * Creates a backup directly from this client to the given cloud or local storage.
+     */
+    backup(storage: BackupStorage, options?: CreateDatabaseBackupOptions & Partial<EncryptedBackupOptions>): Promise<string>;
+    /**
+     * Restores this client's database from a backup in cloud or local storage.
+     */
+    restore(storage: BackupStorage, fileNameOrId: string, options?: Partial<RestoreEncryptedBackupOptions>): Promise<void>;
 }

package/dist/core/client.js

@@ -12,6 +12,8 @@ const uuid_js_1 = require("../utils/uuid.js");
 const sql_js_1 = require("../utils/sql.js");
 const query_js_1 = require("./query.js");
 const query_builder_js_1 = require("./query-builder.js");
+const portability_js_1 = require("../utils/portability.js");
+const index_js_1 = require("../backups/index.js");
 function hasFunctionFilter(value) {
     if (typeof value === 'function')
         return true;
@@ -133,6 +135,12 @@ class TransactionalClient {
         }
         return this.from(tableName).applyOptions(options).execute();
     }
+    /**
+     * Alias for findMany().
+     */
+    async find(tableName, options) {
+        return this.findMany(tableName, options);
+    }
     async query(sql, params = []) {
         return (await this.tx.execute(sql, params));
     }
@@ -715,6 +723,42 @@ class LocalFirstClient {
         }
         return this.from(tableName).applyOptions(options).execute();
     }
+    /**
+     * Alias for findMany().
+     */
+    async find(tableName, options) {
+        return this.findMany(tableName, options);
+    }
+    /**
+     * Returns true if client storage has successfully initialized.
+     */
+    get isReady() {
+        return Boolean(this.initialization);
+    }
+    /**
+     * Convenience export of tables to JSON.
+     */
+    async exportToJson(tables, options) {
+        return (0, portability_js_1.exportTablesToJson)(this, tables, options);
+    }
+    /**
+     * Convenience import of tables from JSON.
+     */
+    async importFromJson(jsonString, options) {
+        return (0, portability_js_1.importTablesFromJson)(this, jsonString, options);
+    }
+    /**
+     * Convenience export of a table to RFC-4180 CSV.
+     */
+    async exportToCsv(tableName, options) {
+        return (0, portability_js_1.exportTableToCsv)(this, tableName, options);
+    }
+    /**
+     * Convenience import of RFC-4180 CSV into a table.
+     */
+    async importFromCsv(tableName, csvString, options) {
+        return (0, portability_js_1.importTableFromCsv)(this, tableName, csvString, options);
+    }
     /**
      * Finds a single record by primary key.
      *
@@ -860,5 +904,150 @@ class LocalFirstClient {
         await this.resetSyncCursor();
         this.events.emit('reset', { dropTables: options.dropTables ?? false });
     }
+    async getAllTableNames() {
+        const list = new Set(this.tables);
+        list.add('sync_outbox');
+        list.add('sync_meta');
+        try {
+            const rows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`);
+            if (Array.isArray(rows)) {
+                for (const r of rows) {
+                    if (r.name)
+                        list.add(r.name);
+                }
+            }
+        }
+        catch {
+            // Non-SQLite database adapter, fallback to configured tables
+        }
+        return Array.from(list);
+    }
+    /**
+     * Exports the entire local database state as a portable binary snapshot.
+     * If the local adapter has a native export mechanism (e.g. serialize or export),
+     * it uses that; otherwise, it exports an atomic JSON snapshot of all tables.
+     */
+    async exportDatabase() {
+        await this.initialize();
+        if (typeof this.db.exportDatabase === 'function') {
+            return this.db.exportDatabase();
+        }
+        if (typeof this.db.serialize === 'function') {
+            return new Uint8Array(this.db.serialize());
+        }
+        if (typeof this.db.export === 'function') {
+            return new Uint8Array(this.db.export());
+        }
+        const tables = await this.getAllTableNames();
+        const snapshot = {};
+        for (const table of tables) {
+            const safeTable = (0, sql_js_1.escapeIdentifier)(table);
+            try {
+                const rows = await this.db.execute(`SELECT * FROM ${safeTable}`);
+                snapshot[table] = rows || [];
+            }
+            catch {
+                // Table may not exist yet
+            }
+        }
+        const payload = JSON.stringify({
+            format: 'local-lite-backup-v1',
+            timestamp: Date.now(),
+            tables: snapshot,
+        });
+        return new TextEncoder().encode(payload);
+    }
+    /**
+     * Imports database state from a backup snapshot.
+     */
+    async importDatabase(data) {
+        if (!data || data.length === 0) {
+            throw new Error('Cannot restore an empty database snapshot.');
+        }
+        await this.initialize();
+        if (typeof this.db.importDatabase === 'function') {
+            await this.db.importDatabase(data);
+            this.schemaManager.clearCache();
+            this.events.emit('reset', { dropTables: false });
+            return;
+        }
+        // Check if data is SQLite format (magic header: "SQLite format 3\0")
+        const isSqlite = data.length > 16 &&
+            data[0] === 0x53 &&
+            data[1] === 0x51 &&
+            data[2] === 0x4c &&
+            data[3] === 0x69 &&
+            data[4] === 0x74 &&
+            data[5] === 0x65 &&
+            data[6] === 0x20 &&
+            data[7] === 0x66 &&
+            data[8] === 0x6f &&
+            data[9] === 0x72 &&
+            data[10] === 0x6d &&
+            data[11] === 0x61 &&
+            data[12] === 0x74 &&
+            data[13] === 0x20 &&
+            data[14] === 0x33 &&
+            data[15] === 0x00;
+        if (isSqlite) {
+            if (typeof this.db.load === 'function') {
+                await this.db.load(data);
+                this.schemaManager.clearCache();
+                this.events.emit('reset', { dropTables: false });
+                return;
+            }
+            throw new Error('Direct SQLite binary snapshot import requires an adapter with native import/load support (e.g. sql.js).');
+        }
+        // Parse portable JSON backup snapshot
+        try {
+            const text = new TextDecoder().decode(data);
+            const parsed = JSON.parse(text);
+            if (parsed.tables && typeof parsed.tables === 'object') {
+                await this.db.transaction(async (tx) => {
+                    for (const [table, rows] of Object.entries(parsed.tables)) {
+                        const safeTable = (0, sql_js_1.escapeIdentifier)(table);
+                        if (Array.isArray(rows) && rows.length > 0) {
+                            await this.schemaManager.ensureTable(tx, table, rows[0]);
+                            await tx.execute(`DELETE FROM ${safeTable}`);
+                            for (const row of rows) {
+                                const cols = Object.keys(row);
+                                const safeCols = cols.map(sql_js_1.escapeIdentifier).join(', ');
+                                const placeholders = cols.map(() => '?').join(', ');
+                                const values = cols.map(c => {
+                                    const val = row[c];
+                                    return val !== null && typeof val === 'object' ? JSON.stringify(val) : val;
+                                });
+                                await tx.execute(`INSERT INTO ${safeTable} (${safeCols}) VALUES (${placeholders})`, values);
+                            }
+                        }
+                        else {
+                            try {
+                                await tx.execute(`DELETE FROM ${safeTable}`);
+                            }
+                            catch { }
+                        }
+                    }
+                });
+                this.schemaManager.clearCache();
+                this.events.emit('reset', { dropTables: false });
+                return;
+            }
+        }
+        catch (err) {
+            throw new Error(`Failed to import backup snapshot: ${err?.message || err}`);
+        }
+    }
+    /**
+     * Creates a backup directly from this client to the given cloud or local storage.
+     */
+    async backup(storage, options) {
+        return (0, index_js_1.performBackup)(this, storage, options);
+    }
+    /**
+     * Restores this client's database from a backup in cloud or local storage.
+     */
+    async restore(storage, fileNameOrId, options) {
+        return (0, index_js_1.performRestore)(this, storage, fileNameOrId, options);
+    }
 }
 exports.LocalFirstClient = LocalFirstClient;

package/dist/core/index.d.ts

@@ -8,6 +8,7 @@ export * from './meta-store.js';
 export * from './table-manager.js';
 export * from './schema-manager.js';
 export * from './query-builder.js';
+export * from './maintenance.js';
 export * from '../reactive/event-emitter.js';
 export * from '../adapters/network/index.js';
 export type { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';

package/dist/core/index.js

@@ -25,6 +25,7 @@ __exportStar(require("./meta-store.js"), exports);
 __exportStar(require("./table-manager.js"), exports);
 __exportStar(require("./schema-manager.js"), exports);
 __exportStar(require("./query-builder.js"), exports);
+__exportStar(require("./maintenance.js"), exports);
 __exportStar(require("../reactive/event-emitter.js"), exports);
 __exportStar(require("../adapters/network/index.js"), exports);
 __exportStar(require("../utils/logger.js"), exports);

package/dist/core/sync-worker.js

@@ -7,6 +7,7 @@ const outbox_store_js_1 = require("./outbox-store.js");
 const meta_store_js_1 = require("./meta-store.js");
 const table_manager_js_1 = require("./table-manager.js");
 const logger_js_1 = require("../utils/logger.js");
+const dynamic_js_1 = require("../utils/dynamic.js");
 const REACT_NATIVE_PKG = ['react', 'native'].join('-');
 /** Maximum outbox records sent per push cycle. */
 const PUSH_BATCH_SIZE = 50;
@@ -236,7 +237,8 @@ class SyncWorker {
             return false;
         // React Native AppState
         try {
-            const { AppState } = require('react-native');
+            const rn = (0, dynamic_js_1.safeDynamicRequire)(REACT_NATIVE_PKG);
+            const AppState = rn?.AppState;
             if (AppState?.currentState && typeof AppState.currentState === 'string') {
                 return Boolean(AppState.currentState.match(/inactive|background/));
             }
@@ -255,7 +257,8 @@ class SyncWorker {
             return;
         // 1. Try React Native AppState
         try {
-            const { AppState } = require('react-native');
+            const rn = (0, dynamic_js_1.safeDynamicRequire)(REACT_NATIVE_PKG);
+            const AppState = rn?.AppState;
             if (AppState && typeof AppState.addEventListener === 'function') {
                 const sub = AppState.addEventListener('change', (state) => {
                     if (state.match(/inactive|background/)) {

package/dist/react/SyncInspector.d.ts

@@ -27,5 +27,3 @@ export interface SyncInspectorProps {
  * Displays real-time outbox telemetry, connection status, metrics, and triggers manual push, pull, reset, and benchmarks.
  */
 export declare function SyncInspector({ client, position, variant, initialOpen, enableBenchmark, onOpenBenchmark, style, theme, alwaysVisible, renderTrigger, }: SyncInspectorProps): React.JSX.Element | null;
-export declare const SyncIndicator: typeof SyncInspector;
-export type SyncIndicatorProps = SyncInspectorProps;

package/dist/react/SyncInspector.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SyncIndicator = void 0;
 exports.SyncInspector = SyncInspector;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
@@ -582,4 +581,3 @@ const rnStyles = RN && RN.StyleSheet
         },
     })
     : {};
-exports.SyncIndicator = SyncInspector;

package/dist/react/auth.d.ts

@@ -21,9 +21,7 @@ export interface UseMicrosoftAuthResult {
     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;

package/dist/react/auth.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useOneDriveAuth = void 0;
 exports.useGoogleAuth = useGoogleAuth;
 exports.useMicrosoftAuth = useMicrosoftAuth;
 exports.useGitHubAuth = useGitHubAuth;
@@ -184,7 +183,6 @@ function useMicrosoftAuth(client) {
         refetchUser,
     };
 }
-exports.useOneDriveAuth = useMicrosoftAuth;
 function useGitHubAuth(client) {
     const [user, setUser] = (0, react_1.useState)(null);
     const [loading, setLoading] = (0, react_1.useState)(true);

package/dist/react/backups.d.ts

@@ -0,0 +1,28 @@
+import type { CloudBackupClient, CloudBackupFile, ResolvableBackupDatabase, GoogleDriveBackupClient, OneDriveBackupClient } from '../backups/index.js';
+export interface UseCloudBackupOptions {
+    passphrase?: string;
+    autoRefresh?: boolean;
+}
+export interface UseCloudBackupResult {
+    isConnected: boolean;
+    isLoading: boolean;
+    isBackingUp: boolean;
+    isRestoring: boolean;
+    backups: CloudBackupFile[];
+    lastBackupAt: string | null;
+    error: Error | null;
+    connect: () => Promise<boolean>;
+    disconnect: () => Promise<void>;
+    refreshBackups: () => Promise<CloudBackupFile[]>;
+    backup: (options?: {
+        fileName?: string;
+        passphrase?: string;
+    }) => Promise<string>;
+    restore: (fileNameOrId: string, options?: {
+        passphrase?: string;
+    }) => Promise<void>;
+    deleteBackup: (fileNameOrId: string) => Promise<void>;
+}
+export declare function useCloudBackup(client: CloudBackupClient | null | undefined, database?: ResolvableBackupDatabase, options?: UseCloudBackupOptions): UseCloudBackupResult;
+export declare function useGoogleDriveBackup(client: GoogleDriveBackupClient | null | undefined, database?: ResolvableBackupDatabase, options?: UseCloudBackupOptions): UseCloudBackupResult;
+export declare function useOneDriveBackup(client: OneDriveBackupClient | null | undefined, database?: ResolvableBackupDatabase, options?: UseCloudBackupOptions): UseCloudBackupResult;