local-lite 0.0.9 → 0.0.11

package/README.md

@@ -19,6 +19,7 @@ Built around the **Transactional Outbox Pattern**, `local-lite` ensures instant,
 * **[Configuration Reference](https://georgechitechi.github.io/local-lite/#/configuration)** - Options for `defineSyncConfig()`, retries, and loggers
 * **[Local SQLite Adapters](https://georgechitechi.github.io/local-lite/#/adapters-local)** - Expo SQLite, OP-SQLite, better-sqlite3, node:sqlite, and LibSQL
 * **[Remote Cloud Adapters](https://georgechitechi.github.io/local-lite/#/adapters-remote)** - Supabase, Convex, Cloud Firestore, and custom adapters
+* **[Database Backups](https://georgechitechi.github.io/local-lite/#/adapters-local?id=database-backups)** - SQLite snapshots with a Google Drive OAuth/PKCE client
 * **[React & Expo Hooks](https://georgechitechi.github.io/local-lite/#/react-hooks)** - `useLiveQuery()` and `useSyncStatus()`
 * **[Conflict Resolution](https://georgechitechi.github.io/local-lite/#/conflict-resolution)** - LWW, Client-Wins, Server-Wins, and custom resolvers
 
@@ -85,6 +86,7 @@ This recovers sync state; it does not repair corrupt SQLite files or cancel hung
 * **🛡️ Conflict Resolution:** Built-in strategies including **Last-Write-Wins (LWW)**, Server-Wins, Client-Wins, or custom resolver functions.
 * **📶 Network-Aware:** Automatically pauses polling when offline and triggers immediate sync flushes the instant connectivity is restored.
 * **🔄 Infinite-Loop Safe:** Incoming remote deltas update local tables and fire reactive UI listeners without echoing back into the outbox.
+* **☁️ Database Backups:** Export and restore SQLite snapshots independently of your live sync backend.
 
 ---
 
@@ -246,46 +248,46 @@ export function TodoScreen() {
 
 ## Supabase Backend Setup & Schema
 
-To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):
-
-```sql
--- Ensure every application table has the soft-delete column expected by local-lite.
-DO $$
-DECLARE
-  table_record RECORD;
-BEGIN
-  FOR table_record IN
-    SELECT table_schema, table_name
-    FROM information_schema.tables
-    WHERE table_schema = 'public'
-      AND table_type = 'BASE TABLE'
-  LOOP
-    EXECUTE format(
-      'ALTER TABLE %I.%I ADD COLUMN IF NOT EXISTS deleted BOOLEAN',
-      table_record.table_schema,
-      table_record.table_name
-    );
-    EXECUTE format(
-      'UPDATE %I.%I SET deleted = FALSE WHERE deleted IS NULL',
-      table_record.table_schema,
-      table_record.table_name
-    );
-    EXECUTE format(
-      'ALTER TABLE %I.%I ALTER COLUMN deleted SET DEFAULT FALSE',
-      table_record.table_schema,
-      table_record.table_name
-    );
-    EXECUTE format(
-      'ALTER TABLE %I.%I ALTER COLUMN deleted SET NOT NULL',
-      table_record.table_schema,
-      table_record.table_name
-    );
-  END LOOP;
-END $$;
-
--- 1. Automatic Timestamp Trigger
-CREATE OR REPLACE FUNCTION public.set_sync_updated_at()
-RETURNS TRIGGER AS $$
+To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):
+
+```sql
+-- Ensure every application table has the soft-delete column expected by local-lite.
+DO $$
+DECLARE
+  table_record RECORD;
+BEGIN
+  FOR table_record IN
+    SELECT table_schema, table_name
+    FROM information_schema.tables
+    WHERE table_schema = 'public'
+      AND table_type = 'BASE TABLE'
+  LOOP
+    EXECUTE format(
+      'ALTER TABLE %I.%I ADD COLUMN IF NOT EXISTS deleted BOOLEAN',
+      table_record.table_schema,
+      table_record.table_name
+    );
+    EXECUTE format(
+      'UPDATE %I.%I SET deleted = FALSE WHERE deleted IS NULL',
+      table_record.table_schema,
+      table_record.table_name
+    );
+    EXECUTE format(
+      'ALTER TABLE %I.%I ALTER COLUMN deleted SET DEFAULT FALSE',
+      table_record.table_schema,
+      table_record.table_name
+    );
+    EXECUTE format(
+      'ALTER TABLE %I.%I ALTER COLUMN deleted SET NOT NULL',
+      table_record.table_schema,
+      table_record.table_name
+    );
+  END LOOP;
+END $$;
+
+-- 1. Automatic Timestamp Trigger
+CREATE OR REPLACE FUNCTION public.set_sync_updated_at()
+RETURNS TRIGGER AS $$
 BEGIN
   NEW.updated_at = timezone('utc'::text, now());
   RETURN NEW;

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

@@ -19,3 +19,13 @@ export declare class MemoryDemoRemoteAdapter implements RemoteDBAdapter {
     emitLiveChanges(changes: DeltaChanges): void;
     clear(): void;
 }
+/**
+ * Built-in No-Op Remote Adapter for local-only / offline operation.
+ * Acknowledges all local outbox pushes with 0 latency, performs no remote pulls,
+ * and maintains zero cloud backend connections.
+ */
+export declare class NoopRemoteAdapter implements RemoteDBAdapter {
+    pushChanges(_operations: SyncOperation[]): Promise<boolean>;
+    fetchChanges(_sinceTimestamp: number): Promise<DeltaChanges>;
+    subscribeToLiveChanges(_callback: (changes: DeltaChanges) => void): () => void;
+}

package/dist/adapters/remote/demo.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryDemoRemoteAdapter = void 0;
+exports.NoopRemoteAdapter = exports.MemoryDemoRemoteAdapter = void 0;
 /**
  * Built-in In-Memory Demo Remote Adapter.
  * Useful for prototyping, offline testing, and previewing without a live backend.
@@ -47,3 +47,23 @@ class MemoryDemoRemoteAdapter {
     }
 }
 exports.MemoryDemoRemoteAdapter = MemoryDemoRemoteAdapter;
+/**
+ * Built-in No-Op Remote Adapter for local-only / offline operation.
+ * Acknowledges all local outbox pushes with 0 latency, performs no remote pulls,
+ * and maintains zero cloud backend connections.
+ */
+class NoopRemoteAdapter {
+    async pushChanges(_operations) {
+        return true;
+    }
+    async fetchChanges(_sinceTimestamp) {
+        return {
+            timestamp: Date.now(),
+            changes: [],
+        };
+    }
+    subscribeToLiveChanges(_callback) {
+        return () => { };
+    }
+}
+exports.NoopRemoteAdapter = NoopRemoteAdapter;

package/dist/backups/cloud-storage.d.ts

@@ -0,0 +1,61 @@
+import type { BackupStorage } from './index.js';
+export interface CloudBackupFile {
+    id: string;
+    name: string;
+    modifiedAt?: string;
+    size?: number;
+}
+export type BackupAccessTokenProvider = () => Promise<string>;
+export interface GoogleDriveTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+}
+export interface GoogleDriveTokenStore {
+    get(): Promise<GoogleDriveTokens | null>;
+    set(tokens: GoogleDriveTokens): Promise<void>;
+    remove(): Promise<void>;
+}
+export interface GoogleDriveKeyValueStorage {
+    getItem(key: string): Promise<unknown>;
+    setItem(key: string, value: unknown): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface GoogleDriveAuthorizationRequest {
+    authorizationUrl: string;
+    redirectUri: string;
+}
+export interface GoogleDriveAuthorizationResponse {
+    code: string;
+    state: string;
+}
+export interface GoogleDriveBackupClientOptions {
+    clientId: string;
+    redirectUri: string;
+    authorize: (request: GoogleDriveAuthorizationRequest) => Promise<GoogleDriveAuthorizationResponse | null>;
+    tokenStore: GoogleDriveTokenStore;
+    randomBytes?: (length: number) => Uint8Array;
+    fetch?: typeof fetch;
+}
+export declare function createGoogleDriveTokenStore(storage: GoogleDriveKeyValueStorage, key?: string): GoogleDriveTokenStore;
+export declare class GoogleDriveBackupStorage implements BackupStorage {
+    private readonly getAccessToken;
+    private readonly fetcher;
+    constructor(getAccessToken: BackupAccessTokenProvider, fetcher?: typeof fetch);
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileId: string): Promise<Uint8Array>;
+    list(): Promise<CloudBackupFile[]>;
+}
+export declare class GoogleDriveBackupClient implements BackupStorage {
+    private readonly options;
+    private readonly storage;
+    private readonly fetcher;
+    constructor(options: GoogleDriveBackupClientOptions);
+    connect(): Promise<boolean>;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+    getValidAccessToken(): Promise<string>;
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileId: string): Promise<Uint8Array>;
+    list(): Promise<CloudBackupFile[]>;
+}

package/dist/backups/cloud-storage.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleDriveBackupClient = exports.GoogleDriveBackupStorage = void 0;
+exports.createGoogleDriveTokenStore = createGoogleDriveTokenStore;
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const GOOGLE_API = 'https://www.googleapis.com/drive/v3';
+const GOOGLE_UPLOAD_API = 'https://www.googleapis.com/upload/drive/v3';
+const GOOGLE_AUTHORIZATION_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+const GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+const GOOGLE_DRIVE_SCOPE = 'https://www.googleapis.com/auth/drive.file';
+const BACKUP_FOLDER = 'backups';
+function secureRandomBytes(length) {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('Secure random number generation is unavailable.');
+    }
+    return crypto.getRandomValues(new Uint8Array(length));
+}
+function base64UrlEncode(bytes) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let result = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index];
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        result += alphabet[first >> 2];
+        result += alphabet[((first & 3) << 4) | (second === undefined ? 0 : second >> 4)];
+        if (second !== undefined) {
+            result += alphabet[((second & 15) << 2) | (third === undefined ? 0 : third >> 6)];
+        }
+        if (third !== undefined)
+            result += alphabet[third & 63];
+    }
+    return result;
+}
+function validateGoogleTokens(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const tokens = value;
+    return (typeof tokens.accessToken === 'string' &&
+        typeof tokens.expiresAt === 'number' &&
+        (tokens.refreshToken === undefined || typeof tokens.refreshToken === 'string'));
+}
+function createGoogleDriveTokenStore(storage, key = 'local-lite-google-drive-backup-tokens') {
+    return {
+        get: async () => {
+            const tokens = await storage.getItem(key);
+            return validateGoogleTokens(tokens) ? tokens : null;
+        },
+        set: tokens => storage.setItem(key, tokens),
+        remove: () => storage.removeItem(key),
+    };
+}
+async function parseTokenResponse(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        throw new Error(`Google OAuth request failed (${response.status}).`);
+    }
+}
+function createStoredTokens(payload, prior) {
+    if (!payload.access_token) {
+        throw new Error('Google OAuth did not return an access token.');
+    }
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token ?? prior?.refreshToken,
+        expiresAt: Date.now() + (payload.expires_in ?? 3600) * 1000,
+    };
+}
+function throwTokenError(payload, status) {
+    throw new Error(payload.error_description ||
+        payload.error ||
+        `Google OAuth request failed (${status}).`);
+}
+async function parseApiError(response) {
+    let detail = '';
+    try {
+        const body = (await response.json());
+        detail =
+            (typeof body.error === 'object' ? body.error?.message : body.error) ??
+                body.error_description ??
+                body.message ??
+                '';
+    }
+    catch {
+        detail = response.statusText;
+    }
+    return new Error(`Google Drive request failed (${response.status})${detail ? `: ${detail}` : ''}`);
+}
+async function getGoogleFolderId(token, fetcher) {
+    const query = encodeURIComponent(`name = '${BACKUP_FOLDER}' and mimeType = 'application/vnd.google-apps.folder' and trashed = false`);
+    const lookup = await fetcher(`${GOOGLE_API}/files?q=${query}&spaces=drive&fields=files(id,name)&pageSize=100`, { headers: { Authorization: `Bearer ${token}` } });
+    if (!lookup.ok)
+        throw await parseApiError(lookup);
+    const result = (await lookup.json());
+    if (result.files?.[0]?.id)
+        return result.files[0].id;
+    const create = await fetcher(`${GOOGLE_API}/files?fields=id`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            name: BACKUP_FOLDER,
+            mimeType: 'application/vnd.google-apps.folder',
+        }),
+    });
+    if (!create.ok)
+        throw await parseApiError(create);
+    const folder = (await create.json());
+    if (!folder.id)
+        throw new Error('Google Drive did not return a backup folder ID.');
+    return folder.id;
+}
+class GoogleDriveBackupStorage {
+    getAccessToken;
+    fetcher;
+    constructor(getAccessToken, fetcher = fetch) {
+        this.getAccessToken = getAccessToken;
+        this.fetcher = fetcher;
+    }
+    async save(fileName, data) {
+        const token = await this.getAccessToken();
+        const folderId = await getGoogleFolderId(token, this.fetcher);
+        const session = await this.fetcher(`${GOOGLE_UPLOAD_API}/files?uploadType=resumable&fields=id`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json; charset=UTF-8',
+                'X-Upload-Content-Type': 'application/octet-stream',
+                'X-Upload-Content-Length': String(data.byteLength),
+            },
+            body: JSON.stringify({
+                name: fileName,
+                mimeType: 'application/octet-stream',
+                parents: [folderId],
+            }),
+        });
+        if (!session.ok)
+            throw await parseApiError(session);
+        const uploadUrl = session.headers.get('Location');
+        if (!uploadUrl) {
+            throw new Error('Google Drive did not return a resumable upload URL.');
+        }
+        const uploaded = await this.fetcher(uploadUrl, {
+            method: 'PUT',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/octet-stream',
+                'Content-Range': `bytes 0-${data.byteLength - 1}/${data.byteLength}`,
+            },
+            body: data.slice().buffer,
+        });
+        if (!uploaded.ok)
+            throw await parseApiError(uploaded);
+    }
+    async read(fileId) {
+        const token = await this.getAccessToken();
+        const response = await this.fetcher(`${GOOGLE_API}/files/${encodeURIComponent(fileId)}?alt=media`, { headers: { Authorization: `Bearer ${token}` } });
+        if (!response.ok)
+            throw await parseApiError(response);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async list() {
+        const token = await this.getAccessToken();
+        const folderId = await getGoogleFolderId(token, this.fetcher);
+        const query = encodeURIComponent(`'${folderId}' in parents and trashed = false`);
+        const response = await this.fetcher(`${GOOGLE_API}/files?q=${query}&fields=files(id,name,size,modifiedTime)&orderBy=modifiedTime%20desc&pageSize=100`, { headers: { Authorization: `Bearer ${token}` } });
+        if (!response.ok)
+            throw await parseApiError(response);
+        const result = (await response.json());
+        return (result.files ?? [])
+            .filter(file => file.name.endsWith('.db'))
+            .map(file => ({
+            id: file.id,
+            name: file.name,
+            modifiedAt: file.modifiedTime,
+            size: file.size ? Number(file.size) : undefined,
+        }));
+    }
+}
+exports.GoogleDriveBackupStorage = GoogleDriveBackupStorage;
+class GoogleDriveBackupClient {
+    options;
+    storage;
+    fetcher;
+    constructor(options) {
+        this.options = options;
+        if (!options.clientId.trim())
+            throw new Error('Google OAuth client ID is required.');
+        if (!options.redirectUri.trim())
+            throw new Error('Google OAuth redirect URI is required.');
+        this.fetcher = options.fetch ?? fetch;
+        this.storage = new GoogleDriveBackupStorage(() => this.getValidAccessToken(), this.fetcher);
+    }
+    async connect() {
+        const randomBytes = this.options.randomBytes ?? secureRandomBytes;
+        const verifierBytes = randomBytes(32);
+        const stateBytes = randomBytes(32);
+        if (verifierBytes.length !== 32 || stateBytes.length !== 32) {
+            throw new Error('The randomBytes provider returned an invalid number of bytes.');
+        }
+        const codeVerifier = base64UrlEncode(verifierBytes);
+        const codeChallenge = base64UrlEncode((0, sha2_js_1.sha256)((0, utils_js_1.utf8ToBytes)(codeVerifier)));
+        const state = base64UrlEncode(stateBytes);
+        const authorizationParams = new URLSearchParams({
+            client_id: this.options.clientId,
+            redirect_uri: this.options.redirectUri,
+            response_type: 'code',
+            scope: GOOGLE_DRIVE_SCOPE,
+            access_type: 'offline',
+            prompt: 'consent',
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            state,
+        });
+        const authorization = await this.options.authorize({
+            authorizationUrl: `${GOOGLE_AUTHORIZATION_ENDPOINT}?${authorizationParams}`,
+            redirectUri: this.options.redirectUri,
+        });
+        if (!authorization)
+            return false;
+        if (authorization.state !== state) {
+            throw new Error('Google OAuth state validation failed. Please try connecting again.');
+        }
+        if (!authorization.code) {
+            throw new Error('Google OAuth did not return an authorization code.');
+        }
+        const response = await this.fetcher(GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                code: authorization.code,
+                code_verifier: codeVerifier,
+                grant_type: 'authorization_code',
+                redirect_uri: this.options.redirectUri,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok)
+            throwTokenError(payload, response.status);
+        const prior = await this.options.tokenStore.get();
+        await this.options.tokenStore.set(createStoredTokens(payload, prior));
+        return true;
+    }
+    async disconnect() {
+        await this.options.tokenStore.remove();
+    }
+    async isConnected() {
+        const tokens = await this.options.tokenStore.get();
+        return validateGoogleTokens(tokens);
+    }
+    async getValidAccessToken() {
+        const tokens = await this.options.tokenStore.get();
+        if (!validateGoogleTokens(tokens)) {
+            throw new Error('Connect Google Drive before using cloud backups.');
+        }
+        if (tokens.expiresAt > Date.now() + 60_000)
+            return tokens.accessToken;
+        if (!tokens.refreshToken) {
+            throw new Error('Your Google Drive sign-in expired. Disconnect and connect the account again.');
+        }
+        const response = await this.fetcher(GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                grant_type: 'refresh_token',
+                refresh_token: tokens.refreshToken,
+                scope: GOOGLE_DRIVE_SCOPE,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok)
+            throwTokenError(payload, response.status);
+        const updatedTokens = createStoredTokens(payload, tokens);
+        await this.options.tokenStore.set(updatedTokens);
+        return updatedTokens.accessToken;
+    }
+    save(fileName, data) {
+        return this.storage.save(fileName, data);
+    }
+    read(fileId) {
+        return this.storage.read(fileId);
+    }
+    list() {
+        return this.storage.list();
+    }
+}
+exports.GoogleDriveBackupClient = GoogleDriveBackupClient;

package/dist/backups/index.d.ts

@@ -0,0 +1,14 @@
+export { type BackupAccessTokenProvider, type CloudBackupFile, type GoogleDriveAuthorizationRequest, type GoogleDriveAuthorizationResponse, type GoogleDriveBackupClientOptions, type GoogleDriveKeyValueStorage, type GoogleDriveTokenStore, type GoogleDriveTokens, GoogleDriveBackupClient, GoogleDriveBackupStorage, createGoogleDriveTokenStore, } from './cloud-storage.js';
+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>;
+}
+export interface CreateDatabaseBackupOptions {
+    fileName?: string;
+}
+export declare function createDatabaseBackup(database: BackupDatabase, storage: BackupStorage, options?: CreateDatabaseBackupOptions): Promise<string>;
+export declare function restoreDatabaseBackup(database: BackupDatabase, storage: BackupStorage, fileName: string): Promise<void>;

package/dist/backups/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGoogleDriveTokenStore = exports.GoogleDriveBackupStorage = exports.GoogleDriveBackupClient = void 0;
+exports.createDatabaseBackup = createDatabaseBackup;
+exports.restoreDatabaseBackup = restoreDatabaseBackup;
+var cloud_storage_js_1 = require("./cloud-storage.js");
+Object.defineProperty(exports, "GoogleDriveBackupClient", { enumerable: true, get: function () { return cloud_storage_js_1.GoogleDriveBackupClient; } });
+Object.defineProperty(exports, "GoogleDriveBackupStorage", { enumerable: true, get: function () { return cloud_storage_js_1.GoogleDriveBackupStorage; } });
+Object.defineProperty(exports, "createGoogleDriveTokenStore", { enumerable: true, get: function () { return cloud_storage_js_1.createGoogleDriveTokenStore; } });
+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 fileName = options.fileName ?? `local-lite-${new Date().toISOString().replace(/[:.]/g, '-')}.db`;
+    validateFileName(fileName);
+    const databaseBytes = await database.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 databaseBytes = await storage.read(fileName);
+    if (databaseBytes.length === 0) {
+        throw new Error('Cannot restore an empty database backup.');
+    }
+    await database.importDatabase(databaseBytes);
+}

package/dist/config/index.d.ts

@@ -13,7 +13,7 @@ export { NodeSQLiteAdapter } from '../adapters/local/node-sqlite.js';
 export { SupabaseRemoteAdapter } from '../adapters/remote/supabase.js';
 export { ConvexRemoteAdapter } from '../adapters/remote/convex.js';
 export { FirestoreRemoteAdapter } from '../adapters/remote/firestore.js';
-export { MemoryDemoRemoteAdapter } from '../adapters/remote/demo.js';
+export { MemoryDemoRemoteAdapter, NoopRemoteAdapter } from '../adapters/remote/demo.js';
 /**
  * Type-safe configuration helper function (similar to defineConfig in Vite/Tailwind).
  */

package/dist/config/index.js

@@ -14,7 +14,7 @@ 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 });
-exports.MemoryDemoRemoteAdapter = exports.FirestoreRemoteAdapter = exports.ConvexRemoteAdapter = exports.SupabaseRemoteAdapter = exports.NodeSQLiteAdapter = exports.SqlJsAdapter = exports.LibSQLAdapter = exports.BetterSQLite3Adapter = exports.OpSQLiteAdapter = exports.ExpoSQLiteAdapter = exports.LocalFirstClient = exports.resolveRemoteAdapter = exports.resolveLocalAdapter = void 0;
+exports.NoopRemoteAdapter = exports.MemoryDemoRemoteAdapter = exports.FirestoreRemoteAdapter = exports.ConvexRemoteAdapter = exports.SupabaseRemoteAdapter = exports.NodeSQLiteAdapter = exports.SqlJsAdapter = exports.LibSQLAdapter = exports.BetterSQLite3Adapter = exports.OpSQLiteAdapter = exports.ExpoSQLiteAdapter = exports.LocalFirstClient = exports.resolveRemoteAdapter = exports.resolveLocalAdapter = void 0;
 exports.defineSyncConfig = defineSyncConfig;
 exports.createSyncClient = createSyncClient;
 const client_js_1 = require("../core/client.js");
@@ -51,6 +51,7 @@ var firestore_js_1 = require("../adapters/remote/firestore.js");
 Object.defineProperty(exports, "FirestoreRemoteAdapter", { enumerable: true, get: function () { return firestore_js_1.FirestoreRemoteAdapter; } });
 var demo_js_1 = require("../adapters/remote/demo.js");
 Object.defineProperty(exports, "MemoryDemoRemoteAdapter", { enumerable: true, get: function () { return demo_js_1.MemoryDemoRemoteAdapter; } });
+Object.defineProperty(exports, "NoopRemoteAdapter", { enumerable: true, get: function () { return demo_js_1.NoopRemoteAdapter; } });
 /**
  * Type-safe configuration helper function (similar to defineConfig in Vite/Tailwind).
  */

package/dist/config/resolve-local.js

@@ -7,6 +7,8 @@ const better_sqlite3_js_1 = require("../adapters/local/better-sqlite3.js");
 const libsql_js_1 = require("../adapters/local/libsql.js");
 const sql_js_js_1 = require("../adapters/local/sql-js.js");
 const node_sqlite_js_1 = require("../adapters/local/node-sqlite.js");
+const dynamic_js_1 = require("../utils/dynamic.js");
+const EXPO_SQLITE_PKG = ['expo', 'sqlite'].join('-');
 /**
  * Resolves or instantiates the appropriate LocalDBAdapter based on the provided configuration.
  * Auto-detects Expo SQLite, OP-SQLite, better-sqlite3, LibSQL, sql.js, and Node.js built-in sqlite.
@@ -51,19 +53,11 @@ async function resolveLocalAdapter(config) {
     // 9. Auto-open by name using expo-sqlite if available
     if (typeof rawDb === 'string' || config.databaseName) {
         const dbName = typeof rawDb === 'string' ? rawDb : (config.databaseName ?? 'local_lite.db');
-        let expoSqlite;
-        try {
-            if (typeof require === 'function') {
-                expoSqlite = require('expo-sqlite');
-            }
-        }
-        catch {
-            // ignore
+        let expoSqlite = (0, dynamic_js_1.safeDynamicRequire)(EXPO_SQLITE_PKG);
+        if (!expoSqlite) {
+            expoSqlite = await (0, dynamic_js_1.safeDynamicImport)(EXPO_SQLITE_PKG);
         }
         try {
-            if (!expoSqlite) {
-                expoSqlite = await import('expo-sqlite');
-            }
             if (expoSqlite && typeof expoSqlite.openDatabaseAsync === 'function') {
                 const expoDb = await expoSqlite.openDatabaseAsync(dbName);
                 return new expo_sqlite_js_1.ExpoSQLiteAdapter(expoDb);

package/dist/config/resolve-remote.d.ts

@@ -2,6 +2,6 @@ import { RemoteDBAdapter } from '../adapters/remote/index.js';
 import { LocalLiteConfig } from './types.js';
 /**
  * Resolves or instantiates the appropriate RemoteDBAdapter based on the provided configuration.
- * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, or custom adapters.
+ * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, local-only mode, or custom adapters.
  */
 export declare function resolveRemoteAdapter(config: LocalLiteConfig): Promise<RemoteDBAdapter>;

package/dist/config/resolve-remote.js

@@ -5,9 +5,13 @@ const supabase_js_1 = require("../adapters/remote/supabase.js");
 const convex_js_1 = require("../adapters/remote/convex.js");
 const firestore_js_1 = require("../adapters/remote/firestore.js");
 const demo_js_1 = require("../adapters/remote/demo.js");
+const dynamic_js_1 = require("../utils/dynamic.js");
+// Construct dynamically to prevent Metro, Webpack, and Rollup from treating
+// optional peer dependencies as unconditional build-time dependencies.
+const SUPABASE_PKG = ['@supabase', 'supabase-js'].join('/');
 /**
  * Resolves or instantiates the appropriate RemoteDBAdapter based on the provided configuration.
- * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, or custom adapters.
+ * Supports Supabase, Convex, Firebase / Firestore, in-memory demo adapter, local-only mode, or custom adapters.
  */
 async function resolveRemoteAdapter(config) {
     // 1. Explicit custom remote adapter
@@ -53,34 +57,27 @@ async function resolveRemoteAdapter(config) {
     }
     // 5. Supabase with URL + anonKey (lazy dynamic import)
     if (config.supabase?.url && config.supabase?.anonKey) {
-        let supabaseModule;
-        // In CommonJS / React Native Metro environments, synchronous require avoids async chunk split failure
-        try {
-            if (typeof require === 'function') {
-                supabaseModule = require('@supabase/supabase-js');
-            }
-        }
-        catch {
-            // ignore
-        }
+        let supabaseModule = (0, dynamic_js_1.safeDynamicRequire)(SUPABASE_PKG);
         if (!supabaseModule && typeof globalThis?.supabase?.createClient === 'function') {
             supabaseModule = globalThis.supabase;
         }
         if (!supabaseModule) {
-            try {
-                supabaseModule = await import('@supabase/supabase-js');
-            }
-            catch {
-                throw new Error('To initialize Supabase from url and anonKey, please install @supabase/supabase-js or provide a pre-configured client to config.supabase.client');
-            }
+            supabaseModule = await (0, dynamic_js_1.safeDynamicImport)(SUPABASE_PKG);
+        }
+        if (!supabaseModule) {
+            throw new Error('To initialize Supabase from url and anonKey, please install @supabase/supabase-js or provide a pre-configured client to config.supabase.client');
         }
         const createClientFn = supabaseModule.createClient || supabaseModule.default?.createClient;
         const supabaseClient = createClientFn(config.supabase.url, config.supabase.anonKey);
         return new supabase_js_1.SupabaseRemoteAdapter(supabaseClient, getSupabaseOptions());
     }
-    // 6. Explicitly selected demo backend only; never acknowledge writes into a temporary backend implicitly.
+    // 6. Local-only standalone mode
+    if (config.localOnly === true) {
+        return new demo_js_1.NoopRemoteAdapter();
+    }
+    // 7. Explicitly selected demo backend only; never acknowledge writes into a temporary backend implicitly.
     if (config.inMemoryRemote === true) {
         return new demo_js_1.MemoryDemoRemoteAdapter(300);
     }
-    throw new Error('No remote adapter configured. Please specify config.supabase, config.convex, config.firebase, or config.remote. For demos only, explicitly set config.inMemoryRemote: true.');
+    throw new Error('No remote adapter configured. Please specify config.supabase, config.convex, config.firebase, or config.remote. For local-only use, set config.localOnly: true. For demos, set config.inMemoryRemote: true.');
 }

package/dist/config/types.d.ts

@@ -120,6 +120,13 @@ export interface LocalLiteConfig {
      * Default: false
      */
     inMemoryRemote?: boolean;
+    /**
+     * Run purely local-only without requiring any remote cloud backend.
+     * Disables cloud sync pushes and pulls while preserving all local SQLite features,
+     * schema management, outbox tracking, and transactions.
+     * Default: false
+     */
+    localOnly?: boolean;
     /**
      * Conflict resolution strategy. Default: 'last-write-wins'
      */

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 REACT_NATIVE_PKG = ['react', 'native'].join('-');
 /** Maximum outbox records sent per push cycle. */
 const PUSH_BATCH_SIZE = 50;
 /** Maximum incoming delta changes applied in a single database transaction. */

package/dist/utils/dynamic.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Safely loads an optional dependency at runtime without triggering
+ * ahead-of-time static analysis in bundlers like Metro, Webpack, or Rollup.
+ */
+export declare function safeDynamicRequire(pkgName: string): any;
+export declare function safeDynamicImport(pkgName: string): Promise<any>;

package/dist/utils/dynamic.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeDynamicRequire = safeDynamicRequire;
+exports.safeDynamicImport = safeDynamicImport;
+/**
+ * Safely loads an optional dependency at runtime without triggering
+ * ahead-of-time static analysis in bundlers like Metro, Webpack, or Rollup.
+ */
+function safeDynamicRequire(pkgName) {
+    try {
+        const req = typeof __non_webpack_require__ !== 'undefined'
+            ? __non_webpack_require__
+            : typeof require === 'function'
+                ? require
+                : undefined;
+        return req ? req(pkgName) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function safeDynamicImport(pkgName) {
+    try {
+        // Metro's AST worker rejects `import(dynamicVariable)` with "Invalid call at line ...: import(...)".
+        // Evaluating via new Function bypasses the bundler AST parser entirely while working in Node/browser.
+        const dynamicImport = new Function('specifier', 'return import(specifier);');
+        return await dynamicImport(pkgName);
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,144 +1,150 @@
-{
-  "name": "local-lite",
-  "version": "0.0.9",
-  "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
-  "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"
-    },
-    "./schema": {
-      "types": "./dist/schema/index.d.ts",
-      "import": "./dist/schema/index.js",
-      "default": "./dist/schema/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"
-    },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "default": "./dist/core/index.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.118.0",
-    "@types/node": "^26.6.5",
-    "@types/react": "^19.3.0",
-    "@types/uuid": "^11.0.0",
-    "expo-sqlite": "^58.0.13",
-    "react": "^19.3.1",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.5"
-  },
-  "dependencies": {
-    "uuid": "^14.0.3"
-  }
-}
+{
+  "name": "local-lite",
+  "version": "0.0.11",
+  "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
+  "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"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js",
+      "default": "./dist/schema/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"
+    },
+    "./backups": {
+      "types": "./dist/backups/index.d.ts",
+      "import": "./dist/backups/index.js",
+      "default": "./dist/backups/index.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"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.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.118.0",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/uuid": "^11.0.0",
+    "expo-sqlite": "^58.0.13",
+    "react": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.4.0",
+    "uuid": "^14.0.3"
+  }
+}