dexie-cloud-addon 4.3.9 → 4.4.1

package/dist/modern/sync/BlobDownloadTracker.d.ts

@@ -0,0 +1,33 @@
+import type { DexieCloudDB } from "../db/DexieCloudDB";
+import { BlobRef } from "./blobResolve";
+/**
+ * Deduplicates in-flight blob downloads.
+ *
+ * Both the blob-resolve middleware and the eager blob downloader may
+ * try to fetch the same blob concurrently. This tracker ensures each
+ * unique blob ref is only downloaded once — subsequent requests for
+ * the same ref piggyback on the existing promise.
+ *
+ * Instantiate once per DexieCloudDB.
+ */
+export declare class BlobDownloadTracker {
+    private inFlight;
+    private db;
+    constructor(db: DexieCloudDB);
+    /**
+     * Download a blob, deduplicating concurrent requests for the same ref.
+     *
+     * @param blobRef - The BlobRef to download
+     * @param dbUrl - Base URL for the database (e.g., 'https://mydb.dexie.cloud')
+     */
+    download(blobRef: BlobRef, dbUrl: string): Promise<Uint8Array>;
+}
+/**
+ * Download blob data from server via proxy endpoint.
+ * Uses auth header for authentication (same as sync).
+ *
+ * @param blobRef - The BlobRef to download
+ * @param dbUrl - Base URL for the database (e.g., 'https://mydb.dexie.cloud')
+ * @param accessToken - Access token for authentication
+ */
+export declare function downloadBlob(blobRef: BlobRef, dbUrl: string, accessToken: string): Promise<Uint8Array>;

package/dist/modern/sync/BlobSavingQueue.d.ts

@@ -0,0 +1,35 @@
+/**
+ * BlobSavingQueue - Queues resolved blobs for saving back to IndexedDB
+ *
+ * Uses setTimeout(fn, 0) instead of queueMicrotask to completely isolate
+ * from Dexie's Promise.PSD context. This prevents the save operation
+ * from inheriting any ongoing transaction.
+ *
+ * Each blob is saved atomically using downCore transaction with the specific
+ * keyPath to avoid race conditions with other property changes.
+ */
+import { ResolvedBlob } from './blobResolve';
+import { DexieCloudDB } from '../db/DexieCloudDB';
+export declare class BlobSavingQueue {
+    private queue;
+    private isProcessing;
+    private db;
+    constructor(db: DexieCloudDB);
+    /**
+     * Queue a resolved blob for saving.
+     * Only the specific blob property will be updated atomically.
+     */
+    saveBlobs(tableName: string, primaryKey: any, resolvedBlobs: ResolvedBlob[]): void;
+    /**
+     * Start the consumer if not already processing.
+     * Uses setTimeout(fn, 0) to completely break out of any
+     * Dexie transaction context (Promise.PSD).
+     */
+    private startConsumer;
+    /**
+     * Process all queued blobs.
+     * Runs in a completely isolated context (no inherited transaction).
+     * Uses atomic updates to avoid race conditions.
+     */
+    private processQueue;
+}

package/dist/modern/sync/blobOffloading.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Blob Offloading for Dexie Cloud
+ *
+ * Handles uploading large blobs to blob storage before sync,
+ * and resolving BlobRefs when reading from the database.
+ */
+import { DBOperationsSet } from 'dexie-cloud-common';
+import { BlobRef, BlobRefOrigType, isBlobRef as isBlobRefFromResolve } from './blobResolve';
+export declare const DEFAULT_MAX_STRING_LENGTH = 32768;
+export type { BlobRef, BlobRefOrigType };
+export declare const isBlobRef: typeof isBlobRefFromResolve;
+/**
+ * Check if a value should be offloaded to blob storage
+ * Performance-optimized for hot path traversal.
+ */
+export declare function shouldOffloadBlob(value: unknown): value is Blob | ArrayBuffer | ArrayBufferView;
+/**
+ * Upload a blob to the blob storage endpoint
+ */
+export declare function uploadBlob(databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, blob: Blob | ArrayBuffer | ArrayBufferView): Promise<BlobRef | null>;
+export declare function offloadBlobsAndMarkDirty(obj: unknown, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, maxStringLength?: number): Promise<unknown>;
+/**
+ * Recursively scan an object for large blobs and upload them
+ * Returns a new object with blobs replaced by BlobRefs
+ */
+export declare function offloadBlobs(obj: unknown, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, maxStringLength?: number, dirtyFlag?: {
+    dirty: boolean;
+}, visited?: WeakSet<object>): Promise<unknown>;
+/**
+ * Process a DBOperationsSet and offload any large blobs
+ * Returns a new DBOperationsSet with blobs replaced by BlobRefs
+ */
+export declare function offloadBlobsInOperations(operations: DBOperationsSet, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, maxStringLength?: number): Promise<DBOperationsSet>;
+/**
+ * Check if there are any large blobs in the operations that need offloading
+ * This is a quick check to avoid unnecessary processing
+ */
+export declare function hasLargeBlobsInOperations(operations: DBOperationsSet, maxStringLength?: number): boolean;

package/dist/modern/sync/blobProgress.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Blob Progress Tracking
+ *
+ * Uses liveQuery to reactively track unresolved blob refs.
+ * Any change to _hasBlobRefs in any syncable table automatically
+ * triggers a re-scan — no manual updateBlobProgress() needed.
+ */
+import { BehaviorSubject, Observable } from 'rxjs';
+import { BlobProgress } from '../DexieCloudAPI';
+import { DexieCloudDB } from '../db/DexieCloudDB';
+/**
+ * BehaviorSubject for the isDownloading flag, controlled by eagerBlobDownloader.
+ */
+export declare function createDownloadingState(): BehaviorSubject<boolean>;
+/**
+ * Set downloading state.
+ */
+export declare function setDownloadingState(downloading$: BehaviorSubject<boolean>, isDownloading: boolean): void;
+/**
+ * Create a liveQuery-based Observable<BlobProgress>.
+ *
+ * Combines a liveQuery (blobsRemaining, bytesRemaining) with an external
+ * isDownloading flag controlled by the eager downloader.
+ */
+export declare function observeBlobProgress(db: DexieCloudDB, downloading$: BehaviorSubject<boolean>): Observable<BlobProgress>;

package/dist/modern/sync/blobResolve.d.ts

@@ -0,0 +1,85 @@
+import { BlobDownloadTracker } from './BlobDownloadTracker';
+/**
+ * BlobRef Resolution for Dexie Cloud
+ *
+ * Handles lazy resolution of BlobRefs when reading from the database.
+ * BlobRefs are symbolic references to blobs stored in blob storage.
+ * They get resolved on-demand when the object is read.
+ *
+ * The server sends offloaded binary data in the format:
+ * { _bt: 'Uint8Array', ref: '1:blobId', size: 1234 }
+ * { _bt: 'Blob', ref: '1:blobId', size: 1234, ct: 'image/png' }
+ *
+ * The _bt field preserves the original JavaScript type.
+ * The ref format is '{version}:{blobId}' where version identifies
+ * the storage backend configuration.
+ */
+/**
+ * Original type that was offloaded to blob storage.
+ * Matches the TSON type names.
+ */
+export type BlobRefOrigType = 'Blob' | 'ArrayBuffer' | 'Uint8Array' | 'Int8Array' | 'Uint8ClampedArray' | 'Int16Array' | 'Uint16Array' | 'Int32Array' | 'Uint32Array' | 'Float32Array' | 'Float64Array' | 'BigInt64Array' | 'BigUint64Array' | 'DataView' | 'string';
+/**
+ * BlobRef represents a reference to binary data stored in blob storage.
+ * The _bt field contains the original JavaScript type (Uint8Array, Blob, etc.)
+ * The presence of 'ref' instead of 'v' indicates this is an offloaded blob.
+ */
+export interface BlobRef {
+    _bt: BlobRefOrigType;
+    ref: string;
+    size: number;
+    ct?: string;
+}
+/**
+ * Resolved blob with its keyPath for queueing
+ */
+export interface ResolvedBlob {
+    keyPath: string;
+    data: Blob | ArrayBuffer | ArrayBufferView | string;
+    ref: string;
+}
+/**
+ * Check if a value is a BlobRef (offloaded binary data)
+ * A BlobRef has _bt (type), ref (blob ID), but no v (inline data)
+ */
+export declare function isBlobRef(value: unknown): value is BlobRef;
+/**
+ * Serialized TSONRef shape (after IndexedDB structured clone).
+ * The Symbol is lost but properties remain.
+ */
+export interface SerializedTSONRef {
+    type: string;
+    ref: string;
+    size: number;
+    contentType?: string;
+}
+/**
+ * Check if a value is a serialized TSONRef (after IndexedDB storage)
+ * Has 'type' instead of '$t', and no Symbol marker
+ */
+export declare function isSerializedTSONRef(value: unknown): value is SerializedTSONRef;
+/**
+ * Recursively check if an object contains any BlobRefs
+ */
+export declare function hasBlobRefs(obj: unknown, visited?: WeakSet<object>): boolean;
+/**
+ * Convert downloaded Uint8Array to the original type specified in BlobRef
+ */
+export declare function convertToOriginalType(data: Uint8Array, ref: BlobRef): Blob | ArrayBuffer | ArrayBufferView | string;
+/**
+ * Recursively resolve all BlobRefs in an object and collect them for queueing.
+ * Returns a new object with BlobRefs replaced by their original type data,
+ * and populates the resolvedBlobs array with keyPath info for each blob.
+ *
+ * @param obj - Object to resolve
+ * @param dbUrl - Base URL for the database
+ * @param accessToken - Access token for blob downloads
+ * @param resolvedBlobs - Array to collect resolved blob info
+ * @param currentPath - Current property path (for tracking)
+ * @param visited - WeakMap for circular reference detection
+ */
+export declare function resolveAllBlobRefs(obj: unknown, dbUrl: string, resolvedBlobs: ResolvedBlob[] | undefined, currentPath: string | undefined, visited: WeakMap<object, any> | undefined, tracker: BlobDownloadTracker): Promise<unknown>;
+/**
+ * Check if an object has unresolved BlobRefs
+ */
+export declare function hasUnresolvedBlobRefs(obj: unknown): boolean;

package/dist/modern/sync/eagerBlobDownloader.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Eager Blob Downloader
+ *
+ * Downloads unresolved blobs in the background when blobMode='eager'.
+ * Called after sync completes to prefetch blobs for offline access.
+ *
+ * Progress is tracked automatically via liveQuery in blobProgress.ts —
+ * no manual progress reporting needed here.
+ */
+import { BehaviorSubject } from 'rxjs';
+import { DexieCloudDB } from '../db/DexieCloudDB';
+/**
+ * Download all unresolved blobs in the background.
+ *
+ * This is called when blobMode='eager' (default) after sync completes.
+ * BlobRef URLs are signed (SAS tokens) so no auth header needed.
+ *
+ * Each blob is saved atomically using Table.update() to avoid race conditions.
+ */
+export declare function downloadUnresolvedBlobs(db: DexieCloudDB, downloading$: BehaviorSubject<boolean>, signal?: AbortSignal): Promise<void>;

package/dist/modern/sync/loadCachedAccessToken.d.ts

@@ -0,0 +1,2 @@
+import { DexieCloudDB } from '../db/DexieCloudDB';
+export declare function loadCachedAccessToken(db: DexieCloudDB): Promise<string | null>;

package/dist/modern/types/DXCAlert.d.ts

@@ -6,6 +6,8 @@ export interface DXCErrorAlert {
     messageParams: {
         [paramName: string]: string;
     };
+    /** Optional text that users can copy to clipboard (e.g. a CLI command) */
+    copyText?: string;
 }
 export interface DXCWarningAlert {
     type: 'warning';
@@ -14,6 +16,8 @@ export interface DXCWarningAlert {
     messageParams: {
         [paramName: string]: string;
     };
+    /** Optional text that users can copy to clipboard (e.g. a CLI command) */
+    copyText?: string;
 }
 export interface DXCInfoAlert {
     type: 'info';
@@ -22,4 +26,6 @@ export interface DXCInfoAlert {
     messageParams: {
         [paramName: string]: string;
     };
+    /** Optional text that users can copy to clipboard (e.g. a CLI command) */
+    copyText?: string;
 }

package/dist/modern/types/TXExpandos.d.ts

@@ -6,6 +6,7 @@ export interface TXExpandos {
     schema: DexieCloudSchema;
     disableChangeTracking?: boolean;
     disableAccessControl?: boolean;
+    disableBlobResolve?: boolean;
     mutationsAdded?: boolean;
     opCount: number;
 }