local-lite 0.0.21 → 0.0.22

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

@@ -1,6 +1,7 @@
 import { RemoteDBAdapter } from './index.js';
 import { DeltaChanges, SyncOperation, PushResult } from '../../core/types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+import { createConvexStorageUploader, ConvexStorageUploaderOptions, ConvexStorageUploaderInstance } from '../../storage/convex.js';
 export interface ConvexRemoteAdapterOptions {
     /**
      * Tables synchronized with Convex.
@@ -68,4 +69,10 @@ export declare class ConvexRemoteAdapter implements RemoteDBAdapter {
      * Cleans up live subscriptions.
      */
     destroy(): void;
+    /**
+     * Helper to create a remote storage uploader targeting Convex File Storage.
+     * Connects local-lite offline blob/file storage directly to Convex File Storage.
+     */
+    createStorageUploader(options?: ConvexStorageUploaderOptions): ConvexStorageUploaderInstance;
 }
+export { createConvexStorageUploader, type ConvexStorageUploaderOptions, type ConvexStorageUploaderInstance, };

package/dist/adapters/remote/convex.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConvexRemoteAdapter = void 0;
+exports.createConvexStorageUploader = exports.ConvexRemoteAdapter = void 0;
 const logger_js_1 = require("../../utils/logger.js");
+const convex_js_1 = require("../../storage/convex.js");
+Object.defineProperty(exports, "createConvexStorageUploader", { enumerable: true, get: function () { return convex_js_1.createConvexStorageUploader; } });
 class ConvexRemoteAdapter {
     client;
     tables;
@@ -177,5 +179,12 @@ class ConvexRemoteAdapter {
             this.unsubscribeLive = undefined;
         }
     }
+    /**
+     * Helper to create a remote storage uploader targeting Convex File Storage.
+     * Connects local-lite offline blob/file storage directly to Convex File Storage.
+     */
+    createStorageUploader(options = {}) {
+        return (0, convex_js_1.createConvexStorageUploader)(this.client, options);
+    }
 }
 exports.ConvexRemoteAdapter = ConvexRemoteAdapter;

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

@@ -1,6 +1,7 @@
 import { RemoteDBAdapter } from './index.js';
 import { DeltaChanges, SyncOperation, PushResult } from '../../core/types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+import { createFirebaseStorageUploader, FirebaseStorageUploaderOptions, FirebaseStorageUploaderInstance } from '../../storage/firebase.js';
 export interface FirestoreAdapterOptions {
     /**
      * Collections (tables) synchronized with Firestore.
@@ -62,4 +63,10 @@ export declare class FirestoreRemoteAdapter implements RemoteDBAdapter {
      * Cleans up all active real-time listeners.
      */
     destroy(): void;
+    /**
+     * Helper to create a remote storage uploader targeting Firebase Cloud Storage.
+     * Connects local-lite offline blob/file storage directly to Firebase Storage.
+     */
+    createStorageUploader(storageOrApp?: any, options?: FirebaseStorageUploaderOptions): FirebaseStorageUploaderInstance;
 }
+export { FirestoreRemoteAdapter as FirestoreAdapter, createFirebaseStorageUploader, type FirebaseStorageUploaderOptions, type FirebaseStorageUploaderInstance, };

package/dist/adapters/remote/firestore.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FirestoreRemoteAdapter = void 0;
+exports.createFirebaseStorageUploader = exports.FirestoreAdapter = exports.FirestoreRemoteAdapter = void 0;
 const logger_js_1 = require("../../utils/logger.js");
+const firebase_js_1 = require("../../storage/firebase.js");
+Object.defineProperty(exports, "createFirebaseStorageUploader", { enumerable: true, get: function () { return firebase_js_1.createFirebaseStorageUploader; } });
 /**
  * Safely extracts epoch milliseconds from numbers, Firestore Timestamps, or ISO strings.
  */
@@ -328,5 +330,25 @@ class FirestoreRemoteAdapter {
         }
         this.unsubscribers = [];
     }
+    /**
+     * Helper to create a remote storage uploader targeting Firebase Cloud Storage.
+     * Connects local-lite offline blob/file storage directly to Firebase Storage.
+     */
+    createStorageUploader(storageOrApp, options = {}) {
+        let client = storageOrApp;
+        let opts = options;
+        if (storageOrApp &&
+            !storageOrApp.ref &&
+            !storageOrApp.storage &&
+            !storageOrApp.app &&
+            typeof storageOrApp === 'object' &&
+            ('bucket' in storageOrApp || 'storageModule' in storageOrApp || 'basePath' in storageOrApp)) {
+            opts = storageOrApp;
+            client = this.db.app || this.db;
+        }
+        const resolvedClient = client || this.db.app || this.db;
+        return (0, firebase_js_1.createFirebaseStorageUploader)(resolvedClient, opts);
+    }
 }
 exports.FirestoreRemoteAdapter = FirestoreRemoteAdapter;
+exports.FirestoreAdapter = FirestoreRemoteAdapter;

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

@@ -2,6 +2,7 @@ import type { SupabaseClient } from '@supabase/supabase-js';
 import { RemoteDBAdapter } from './index.js';
 import { DeltaChanges, PushResult, SyncOperation } from '../../core/types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../../utils/logger.js';
+import { createSupabaseStorageUploader, type SupabaseStorageUploaderOptions, type SupabaseStorageUploaderInstance } from '../../storage/supabase.js';
 export interface SupabaseAdapterOptions {
     /**
      * The list of Postgres tables to sync.
@@ -123,4 +124,10 @@ export declare class SupabaseRemoteAdapter implements RemoteDBAdapter {
      * Clean up active realtime channels.
      */
     destroy(): void;
+    /**
+     * Helper to create a remote storage uploader targeting Supabase Storage buckets.
+     * Connects local-lite offline blob/file storage directly to Supabase Storage.
+     */
+    createStorageUploader(options: SupabaseStorageUploaderOptions): SupabaseStorageUploaderInstance;
 }
+export { SupabaseRemoteAdapter as SupabaseAdapter, createSupabaseStorageUploader, type SupabaseStorageUploaderOptions, type SupabaseStorageUploaderInstance, };

package/dist/adapters/remote/supabase.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SupabaseRemoteAdapter = void 0;
+exports.createSupabaseStorageUploader = exports.SupabaseAdapter = exports.SupabaseRemoteAdapter = void 0;
 const logger_js_1 = require("../../utils/logger.js");
+const supabase_js_1 = require("../../storage/supabase.js");
+Object.defineProperty(exports, "createSupabaseStorageUploader", { enumerable: true, get: function () { return supabase_js_1.createSupabaseStorageUploader; } });
 class SupabaseRemoteAdapter {
     clientResolver;
     activeLiveCallback;
@@ -25,7 +27,8 @@ class SupabaseRemoteAdapter {
             typeof clientOrOptions === 'object' &&
             !('channel' in clientOrOptions) &&
             !('from' in clientOrOptions) &&
-            !('auth' in clientOrOptions)) {
+            !('auth' in clientOrOptions) &&
+            !('storage' in clientOrOptions)) {
             client = null;
             options = clientOrOptions;
         }
@@ -640,5 +643,13 @@ class SupabaseRemoteAdapter {
             this.activeChannel = undefined;
         }
     }
+    /**
+     * Helper to create a remote storage uploader targeting Supabase Storage buckets.
+     * Connects local-lite offline blob/file storage directly to Supabase Storage.
+     */
+    createStorageUploader(options) {
+        return (0, supabase_js_1.createSupabaseStorageUploader)(this.getClient(), options);
+    }
 }
 exports.SupabaseRemoteAdapter = SupabaseRemoteAdapter;
+exports.SupabaseAdapter = SupabaseRemoteAdapter;

package/dist/core/client.js

@@ -219,9 +219,21 @@ class LocalFirstClient {
         this.keys = new index_js_3.ApiKeyManager(this.db, config.keys);
         this.kv = new index_js_4.KVManager(this.db, this.events, config.kv);
         this.search = new index_js_5.SearchManager(this.db, this.events, (table, id) => this.findById(table, id));
+        let storageUploader = config.storage?.uploader;
+        if (!storageUploader && config.storage) {
+            if (typeof this.remote?.createStorageUploader === 'function' &&
+                (config.storage.autoRemote !== false &&
+                    (config.storage.autoRemote || config.storage.bucket || config.storage.uploadMutation))) {
+                try {
+                    storageUploader = this.remote.createStorageUploader(config.storage);
+                }
+                catch { }
+            }
+        }
         this.storage = new index_js_6.BlobStorageManager(this.db, {
             network: config.network,
             ...config.storage,
+            uploader: storageUploader,
         });
         this.scheduler = new index_js_7.JobScheduler(this.db, config.scheduler);
         this.session = new session_js_1.SessionManager(this.db, this.events, {

package/dist/storage/convex.d.ts

@@ -0,0 +1,43 @@
+import { BlobRecord, RemoteStorageUploader } from './types.js';
+export interface ConvexStorageUploaderOptions {
+    /**
+     * Name or function reference for Convex mutation that generates an upload URL.
+     * Default: 'sync:generateUploadUrl' (or can be `api.files.generateUploadUrl`)
+     */
+    uploadMutation?: any;
+    /**
+     * Optional arguments passed to uploadMutation.
+     */
+    uploadMutationArgs?: Record<string, any> | ((blob: BlobRecord) => Record<string, any>);
+    /**
+     * Optional name or function reference for Convex query that gets a serving URL from a storageId.
+     * e.g. `api.files.getUrl`
+     */
+    getUrlQuery?: any;
+    /**
+     * Optional name or function reference for Convex mutation called after file is uploaded,
+     * allowing you to persist metadata or link the storageId to your Convex schema.
+     */
+    saveFileMutation?: any;
+    /**
+     * Optional name or function reference for Convex mutation called when a file is deleted.
+     */
+    deleteMutation?: any;
+    /**
+     * Custom path / metadata transformation.
+     */
+    pathTransform?: (key: string, blob?: BlobRecord) => string;
+    /**
+     * Custom fetch function (defaults to global fetch).
+     */
+    fetchFn?: typeof fetch;
+}
+export interface ConvexStorageUploaderInstance extends RemoteStorageUploader {
+    getUrl(storageId: string): Promise<string | null>;
+    getDownloadUrl(keyOrStorageId: string): Promise<string>;
+    delete(storageIdOrKey: string): Promise<void>;
+}
+/**
+ * Creates a RemoteStorageUploader that syncs binary files to Convex File Storage.
+ */
+export declare function createConvexStorageUploader(convex: any, options?: ConvexStorageUploaderOptions): ConvexStorageUploaderInstance;

package/dist/storage/convex.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConvexStorageUploader = createConvexStorageUploader;
+/**
+ * Creates a RemoteStorageUploader that syncs binary files to Convex File Storage.
+ */
+function createConvexStorageUploader(convex, options = {}) {
+    const uploadMutation = options.uploadMutation ?? 'sync:generateUploadUrl';
+    const fetchFn = options.fetchFn ?? (typeof fetch !== 'undefined' ? fetch : undefined);
+    if (!convex) {
+        throw new Error('Convex client must be provided to createConvexStorageUploader.');
+    }
+    // Cache of key/storageId mapping
+    const storageIdMap = new Map();
+    return {
+        async upload(blob, data) {
+            if (!fetchFn) {
+                throw new Error('Fetch API is not available in the current environment.');
+            }
+            // 1. Generate upload URL via mutation
+            const mutationArgs = typeof options.uploadMutationArgs === 'function'
+                ? options.uploadMutationArgs(blob)
+                : options.uploadMutationArgs || {};
+            let postUrl;
+            if (typeof convex.mutation === 'function') {
+                postUrl = await convex.mutation(uploadMutation, mutationArgs);
+            }
+            else if (typeof convex === 'function') {
+                postUrl = await convex(uploadMutation, mutationArgs);
+            }
+            else {
+                throw new Error('Convex client must support .mutation() method.');
+            }
+            if (!postUrl || typeof postUrl !== 'string') {
+                throw new Error(`Convex generateUploadUrl mutation did not return a valid URL: ${JSON.stringify(postUrl)}`);
+            }
+            // 2. POST binary data to upload URL
+            const response = await fetchFn(postUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': blob.mimeType || 'application/octet-stream',
+                },
+                body: data,
+            });
+            if (!response.ok) {
+                throw new Error(`Convex file upload failed with status ${response.status}: ${response.statusText}`);
+            }
+            const jsonResult = await response.json();
+            const storageId = jsonResult?.storageId || jsonResult?.id || jsonResult;
+            if (!storageId) {
+                throw new Error('Convex upload response did not contain a valid storageId.');
+            }
+            storageIdMap.set(blob.key, storageId);
+            // 3. Optional: save file record in Convex schema
+            if (options.saveFileMutation) {
+                const filePayload = {
+                    storageId,
+                    key: blob.key,
+                    name: blob.name,
+                    mimeType: blob.mimeType,
+                    size: blob.size,
+                    sha256: blob.sha256,
+                    metadata: blob.metadata,
+                };
+                if (typeof convex.mutation === 'function') {
+                    await convex.mutation(options.saveFileMutation, filePayload);
+                }
+            }
+            // 4. Resolve serving URL if query is provided
+            let remoteUrl = storageId;
+            if (options.getUrlQuery) {
+                const resolved = await this.getUrl(storageId);
+                if (resolved) {
+                    remoteUrl = resolved;
+                }
+            }
+            return {
+                remoteUrl,
+                storageId,
+                metadata: { storageId },
+            };
+        },
+        async getUrl(storageId) {
+            if (!options.getUrlQuery) {
+                return null;
+            }
+            try {
+                if (typeof convex.query === 'function') {
+                    return await convex.query(options.getUrlQuery, { storageId });
+                }
+                return null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async getDownloadUrl(keyOrStorageId) {
+            const storageId = storageIdMap.get(keyOrStorageId) || keyOrStorageId;
+            const url = await this.getUrl(storageId);
+            return url || storageId;
+        },
+        async delete(storageIdOrKey) {
+            const storageId = storageIdMap.get(storageIdOrKey) || storageIdOrKey;
+            storageIdMap.delete(storageIdOrKey);
+            if (options.deleteMutation) {
+                if (typeof convex.mutation === 'function') {
+                    await convex.mutation(options.deleteMutation, { storageId });
+                }
+            }
+        },
+    };
+}

package/dist/storage/expo.d.ts

@@ -0,0 +1,132 @@
+import { FileDriver } from './types.js';
+export interface ExpoFileSystemModule {
+    File?: any;
+    Directory?: any;
+    Paths?: any;
+    documentDirectory?: string | null;
+    cacheDirectory?: string | null;
+    EncodingType?: {
+        UTF8: string;
+        Base64: string;
+    };
+    getInfoAsync?(fileUri: string, options?: {
+        md5?: boolean;
+        size?: boolean;
+    }): Promise<{
+        exists: boolean;
+        isDirectory?: boolean;
+        size?: number;
+        uri?: string;
+    }>;
+    writeAsStringAsync?(fileUri: string, contents: string, options?: {
+        encoding?: string;
+    }): Promise<void>;
+    readAsStringAsync?(fileUri: string, options?: {
+        encoding?: string;
+        length?: number;
+        position?: number;
+    }): Promise<string>;
+    makeDirectoryAsync?(fileUri: string, options?: {
+        intermediates?: boolean;
+    }): Promise<void>;
+    deleteAsync?(fileUri: string, options?: {
+        idempotent?: boolean;
+    }): Promise<void>;
+    copyAsync?(options: {
+        from: string;
+        to: string;
+    }): Promise<void>;
+    moveAsync?(options: {
+        from: string;
+        to: string;
+    }): Promise<void>;
+    downloadAsync?(url: string, fileUri: string, options?: {
+        md5?: boolean;
+        headers?: Record<string, string>;
+        sessionType?: any;
+    }): Promise<{
+        uri: string;
+        status: number;
+        headers: Record<string, string>;
+        md5?: string;
+    }>;
+}
+export interface ExpoFileDriverOptions {
+    /**
+     * The modern `File` class from `expo-file-system` (SDK >57/58).
+     * e.g. `import { File } from 'expo-file-system'`
+     */
+    File?: any;
+    /**
+     * The modern `Directory` class from `expo-file-system`.
+     * e.g. `import { Directory } from 'expo-file-system'`
+     */
+    Directory?: any;
+    /**
+     * The modern `Paths` object from `expo-file-system`.
+     * e.g. `import { Paths } from 'expo-file-system'`
+     */
+    Paths?: any;
+    /**
+     * The `expo-file-system` module instance.
+     * e.g. `import * as FileSystem from 'expo-file-system'`
+     */
+    fileSystem?: ExpoFileSystemModule | any;
+    /**
+     * Base directory path or `Directory` instance for storing files.
+     * Defaults to: `new Directory(Paths.document, 'local-lite-blobs')`
+     */
+    baseDir?: any;
+    /**
+     * Whether to store files in `Paths.cache` instead of `Paths.document`.
+     * Files in cache directory may be cleared by the OS if device storage runs low.
+     * Default: false
+     */
+    useCache?: boolean;
+}
+/**
+ * Universal binary <-> base64 utilities compatible with Node, Browser, and React Native (Hermes).
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * FileDriver implementation for Expo / React Native environments.
+ * Uses modern Expo (>57/58) `File`, `Directory`, and `Paths` APIs when available,
+ * with seamless fallback for legacy `expo-file-system` environments.
+ */
+export declare class ExpoFileDriver implements FileDriver {
+    private FileClass?;
+    private DirectoryClass?;
+    private PathsObj?;
+    private legacyFs?;
+    private baseDirOption?;
+    private useCache;
+    private resolvedBaseDir;
+    private resolvedBaseDirPath;
+    private ensuredDirs;
+    constructor(options?: ExpoFileDriverOptions);
+    private resolveClasses;
+    private getBaseDirectory;
+    /**
+     * Resolves a key to a modern Expo `File` instance (if File class is available)
+     * or a string URI path.
+     */
+    private resolveFileOrUri;
+    resolveUri(key: string): Promise<string>;
+    getUri(key: string): Promise<string>;
+    private ensureDirectory;
+    write(key: string, data: Uint8Array): Promise<string>;
+    read(key: string): Promise<Uint8Array | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getSize(key: string): Promise<number>;
+    /**
+     * Fast file copy from an existing local URI (e.g. from expo-image-picker or expo-document-picker)
+     * into local-lite managed storage without reading entire file contents into memory.
+     */
+    copyFrom(sourceUri: string, key: string): Promise<string>;
+    /**
+     * Downloads a remote URL directly to the destination key on disk.
+     */
+    downloadFrom(remoteUrl: string, key: string): Promise<string>;
+}