dexie-cloud-addon 4.4.11 → 4.4.12

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

@@ -1,36 +1,96 @@
 import type { DexieCloudDB } from '../db/DexieCloudDB';
-import { BlobRef } from './blobResolve';
+import { BlobRef, ResolvedBlob } from './blobResolve';
 /**
- * Deduplicates in-flight blob downloads.
+ * Owns the full lifecycle of downloaded blobs:
+ *   1. Deduplicates concurrent downloads for the same ref.
+ *   2. Bounds the number of concurrent network fetches (MAX_CONCURRENT)
+ *      so that ad-hoc reads can't starve the HTTP connection pool. Calls
+ *      beyond the cap queue in FIFO order as slots free. The slot is held
+ *      only for the duration of the fetch — NOT until persistence — to
+ *      avoid deadlocks when a single object contains more blob refs than
+ *      MAX_CONCURRENT (a sequential resolver would otherwise hold every
+ *      slot itself while waiting for the next).
+ *   3. Keeps the in-flight promise alive after the network fetch completes,
+ *      until the blob has been persisted back to IndexedDB. This way,
+ *      readers that ask for the same ref while it is queued for saving
+ *      can piggyback on the existing promise instead of refetching.
+ *      In-flight membership and slot ownership are independent: a piggyback
+ *      reader consumes neither a slot nor extra memory beyond the existing
+ *      cached Uint8Array.
+ *   4. Persists resolved blobs via an internal BlobSavingQueue, and
+ *      releases the in-flight entry when persistence completes.
  *
- * 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.
+ * Both the blob-resolve middleware and the eager blob downloader use this
+ * tracker. Instantiate once per DexieCloudDB.
+ */
+/**
+ * Maximum number of concurrent blob fetches.
  *
- * Instantiate once per DexieCloudDB.
+ * Historically 6 to match the HTTP/1.1 same-origin connection cap that
+ * browsers enforce. With HTTP/2 (the typical transport for Dexie Cloud
+ * today) many streams multiplex over a single TCP connection, so the
+ * old cap is overly conservative. 10 is a modest bump that still keeps
+ * memory pressure (in-flight Uint8Arrays) and server load bounded.
+ * Can be made configurable via DexieCloudOptions if a real need arises.
  */
+export declare const MAX_CONCURRENT = 10;
 export declare class BlobDownloadTracker {
     private inFlight;
     private db;
+    private savingQueue;
+    private activeFetches;
+    private waiting;
     constructor(db: DexieCloudDB);
     /**
-     * Download a blob, deduplicating concurrent requests for the same ref.
+     * Download a blob, deduplicating concurrent requests for the same ref
+     * and respecting the global fetch concurrency cap.
+     *
+     * Lifecycle:
+     *   - Slot is acquired before the fetch and released as soon as the
+     *     fetch settles (success or failure).
+     *   - The in-flight entry survives a successful fetch and lives on
+     *     until persistence completes (via enqueueSave) or releaseRefs
+     *     is called. On fetch failure, the entry is removed immediately
+     *     so a future call can retry.
      *
      * @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>;
+    /**
+     * Queue resolved blobs for persisting back to IndexedDB.
+     * When the save transaction completes, the corresponding in-flight
+     * entries are released.
+     */
+    enqueueSave(tableName: string, primaryKey: any, resolvedBlobs: ResolvedBlob[]): void;
+    /**
+     * Wait until all previously enqueued saves have been persisted to
+     * IndexedDB. Used by callers that need to make decisions based on
+     * on-disk state — e.g., the eager downloader looping over rows with
+     * `_hasBlobRefs=1` in chunks, where each iteration must see the
+     * previous chunk's writes before re-querying.
+     *
+     * New saves enqueued AFTER drainPendingSaves() is called do NOT extend
+     * the wait.
+     */
+    drainPendingSaves(): Promise<void>;
+    /**
+     * Release in-flight entries without going through the internal saving
+     * queue. Used when the caller persists the blobs itself, or when no
+     * primary key was available and the data won't be persisted at all.
+     */
+    releaseRefs(refs: string[]): void;
+    private acquireSlot;
+    private releaseSlot;
+    /**
+     * Download blob data from server via proxy endpoint.
+     * Uses auth header for authentication (same as sync).
+     * When accessToken is null, the request is made without Authorization header —
+     * this allows downloading blobs from public realms (rlm-public) for
+     * unauthenticated users.
+     *
+     * @param blobRef - The BlobRef to download
+     * @param dbUrl - Base URL for the database (e.g., 'https://mydb.dexie.cloud')
+     */
+    private downloadBlob;
 }
-/**
- * Download blob data from server via proxy endpoint.
- * Uses auth header for authentication (same as sync).
- * When accessToken is null, the request is made without Authorization header —
- * this allows downloading blobs from public realms (rlm-public) for
- * unauthenticated users.
- *
- * @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, or null for anonymous access
- */
-export declare function downloadBlob(blobRef: BlobRef, dbUrl: string, accessToken: string | null): Promise<Uint8Array>;

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

@@ -1,5 +1,9 @@
 /**
- * BlobSavingQueue - Queues resolved blobs for saving back to IndexedDB
+ * BlobSavingQueue - Queues resolved blobs for saving back to IndexedDB.
+ *
+ * This is an internal collaborator of BlobDownloadTracker and is not
+ * intended to be used directly by middleware or other code. See
+ * BlobDownloadTracker.enqueueSave().
  *
  * Uses setTimeout(fn, 0) instead of queueMicrotask to completely isolate
  * from Dexie's Promise.PSD context. This prevents the save operation
@@ -14,12 +18,26 @@ export declare class BlobSavingQueue {
     private queue;
     private isProcessing;
     private db;
-    constructor(db: DexieCloudDB);
+    private onPersisted;
+    private drainResolvers;
+    constructor(db: DexieCloudDB, onPersisted: (refs: string[]) => void);
     /**
      * Queue a resolved blob for saving.
      * Only the specific blob property will be updated atomically.
      */
     saveBlobs(tableName: string, primaryKey: any, resolvedBlobs: ResolvedBlob[]): void;
+    /**
+     * Returns a promise that resolves when the queue is empty AND no item
+     * is currently being processed. Used by callers that need to know when
+     * all previously enqueued saves have been persisted to IndexedDB before
+     * making decisions based on the on-disk state (e.g., the eager blob
+     * downloader looping over `_hasBlobRefs=1` rows in chunks).
+     *
+     * Note: New work enqueued AFTER drain() is called does NOT extend the
+     * wait. Callers that race against concurrent producers should treat the
+     * returned promise as "queue was empty at some point after this call".
+     */
+    drain(): Promise<void>;
     /**
      * Start the consumer if not already processing.
      * Uses setTimeout(fn, 0) to completely break out of any

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

@@ -4,8 +4,45 @@
  * Downloads unresolved blobs in the background when blobMode='eager'.
  * Called after sync completes to prefetch blobs for offline access.
  *
+ * Strategy:
+ *   1. Snapshot the primary keys of all rows currently flagged
+ *      `_hasBlobRefs=1` for each syncable table.
+ *   2. Walk that key list in chunks via `bulkGet`. Each `bulkGet`
+ *      triggers the blob-resolve middleware, which does all the actual
+ *      work — downloading blobs (throttled and deduplicated by the
+ *      shared BlobDownloadTracker) and enqueueing them for persistence
+ *      via the internal save queue.
+ *
+ * This keeps a single, symmetric code path with normal application
+ * reads, which is important when other middlewares are present
+ * (e.g., a hypothetical encryption middleware): writes from the save
+ * queue and reads from this loop both pass through the full middleware
+ * stack, so on-disk representation stays consistent.
+ *
+ * Why a snapshot of primary keys (rather than re-querying the index)?
+ *   - Rows that get resolved by parallel application reads simply
+ *     disappear from the table contents we're about to re-fetch; the
+ *     middleware skips them since `_hasBlobRefs` is already cleared.
+ *   - Stuck rows (e.g., blob 404s) are naturally bypassed: we just
+ *     advance to the next chunk in the snapshot. No `seenKeys`
+ *     bookkeeping required.
+ *   - The snapshot is `string[]`-shaped for typical Dexie Cloud rows
+ *     (~36 bytes/UUID), so ~28K keys per MB. Acceptable for any
+ *     realistic dataset.
+ *
  * Progress is tracked automatically via liveQuery in blobProgress.ts —
  * no manual progress reporting needed here.
+ *
+ * --- Throughput note ---
+ * The chunk loop is sequential: bulkGet → wait for all downloads to
+ * settle → next bulkGet. The save queue drains in the background and
+ * does not block iteration (saves no longer need to be persisted before
+ * the next iteration, since we don't re-query the index). For typical
+ * blob sizes (10 KB – 10 MB) the network dominates total time. If
+ * real-world profiling later shows the per-chunk fixed cost matters,
+ * the next bulkGet could be kicked off in parallel with the current
+ * one's middleware work — but we keep it simple until measurements
+ * justify otherwise.
  */
 import { BehaviorSubject } from 'rxjs';
 import { DexieCloudDB } from '../db/DexieCloudDB';
@@ -13,8 +50,5 @@ 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/types/TXExpandos.d.ts

@@ -1,3 +1,4 @@
+import { ObservabilitySet } from 'dexie';
 import { DexieCloudSchema } from 'dexie-cloud-common';
 import { UserLogin } from '../db/entities/UserLogin';
 export interface TXExpandos {
@@ -8,5 +9,6 @@ export interface TXExpandos {
     disableAccessControl?: boolean;
     disableBlobResolve?: boolean;
     mutationsAdded?: boolean;
+    mutatedParts?: ObservabilitySet;
     opCount: number;
 }