fix(dexie-cloud): route all blob writebacks through BlobSavingQueue to avoid PSD context loss

[liz709]

Problem

When using Dexie hooks (e.g. Table.hook('creating')) together with lazy blob mode, reads would crash with:

[dexie-cloud:blobResolve] Failed to resolve BlobRefs on <table>

Caused by:

Cannot read properties of undefined (reading 'table')

Root cause: After an async native fetch (blob download), Dexie's PSD zone is no longer active — PSD.trans becomes undefined. The previous code called table.mutate() directly for rw transactions, which flowed through HooksMiddleware.mutate(). That reads PSD.trans to get the current transaction and crashes.

Fix

Remove the direct table.mutate() path entirely. All blob writebacks now go through BlobSavingQueue.saveBlobs(), which:

1. Uses setTimeout(fn, 0) to run in a fresh JS task, completely outside any PSD context
2. Opens a proper Dexie rw transaction — always safe regardless of calling context

The BlobSavingQueue path already existed for readonly transactions and was already correctly armored with disableChangeTracking, disableAccessControl, and disableBlobResolve flags.

Verified

• Build passes (pnpm build clean)
• Unit tests pass (114/114)
• Repro script confirms the underlying PSD bug is real; fix avoids the broken path entirely

Fixes lazy blob mode crash reported by @sarink in Discord.

Summary by CodeRabbit

• Refactor
  • Unified blob download and persistence flow to improve reliability, avoid duplicate downloads, and ensure resolved blobs are persisted in a single, managed queue.
  • Downloader now bounds concurrency and processes work in controlled chunks for steadier performance.
• Bug Fixes
  • Prevents in-flight reference/cache leaks and ensures pending blob saves can be awaited before completion signals.

[coderabbitai]

📝 Walkthrough

Walkthrough

Centralizes blob download lifecycle: middleware now delegates resolved-blob persistence to BlobDownloadTracker.enqueueSave; BlobDownloadTracker adds concurrency slots, owns BlobSavingQueue persistence, and exposes enqueueSave/drainPendingSaves/releaseRefs; eager downloader uses chunked bulkGet to trigger middleware-driven resolve/save.

Changes

Blob download & persistence rework

Layer / File(s)	Summary
Middleware: remove BlobSavingQueue wiring and hand off to tracker addons/dexie-cloud/src/middlewares/blobResolveMiddleware.ts	Middleware drops BlobSavingQueue import/creation, removes queue parameters from cursor/call sites, and always delegates persistence to db.blobDownloadTracker.enqueueSave(...) or calls releaseRefs(...) when no key is present.
BlobDownloadTracker: concurrency, enqueue/release, download internals addons/dexie-cloud/src/sync/BlobDownloadTracker.ts	Tracker gains MAX_CONCURRENT, slot acquisition/release, retains inFlight until persistence, adds enqueueSave, drainPendingSaves, releaseRefs, and moves network download logic into a private method handling cached token and non-OK responses.
BlobSavingQueue: onPersisted callback and drain semantics addons/dexie-cloud/src/sync/BlobSavingQueue.ts	Queue constructor accepts onPersisted(refs); drain() waits for queue empty + idle consumer; consumer calls onPersisted(...) after processing items.
Eager downloader: snapshot keys → chunked bulkGet flow addons/dexie-cloud/src/sync/eagerBlobDownloader.ts	Replaces per-row resolution/updates with snapshot of _hasBlobRefs keys and sequential bulkGet chunks (size derived from MAX_CONCURRENT) to trigger middleware resolve and queued persistence; drains pending saves before completion.
Types & live-query tweak addons/dexie-cloud/src/types/TXExpandos.ts, src/live-query/live-query.ts	Adds optional mutatedParts?: ObservabilitySet to TXExpandos; switches mutation event registration to globalEvents.storagemutated.subscribe(...).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• dexie/Dexie.js#2260: Related refactor of the blob download pipeline and previous tracker/dedup changes.
• Fix blob resolve issues (change level to be above cache-middleware) + make sure to resume blob downloader through syncComplete event #2268: Also modifies blobResolve middleware execution ordering and interacts with middleware changes here.
• feat(dexie-cloud): Client-side blob offloading and lazy resolution #2255: Related client-side blob offloading and lazy BlobRef resolution changes in the same modules.

Suggested reviewers

• dfahlander

Poem

🐰 I hopped from key to bulk-get land,
Enqueued each blob with careful hand,
Slots kept busy, saves in queue,
Refs cleared tidy, downloads too,
A hop, a munch — persistence grand.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: routing blob writebacks through BlobSavingQueue to fix PSD context loss, which is the core issue addressed across all modified files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch liz/fix-blobsave-hooks-psd-context

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

addons/dexie-cloud/src/sync/eagerBlobDownloader.ts (1)

58-58: ⚡ Quick win

The infinite loop concern is not applicable with the current MAX_CONCURRENT value.

MAX_CONCURRENT is hardcoded to 10 in BlobDownloadTracker.ts, making CHUNK_SIZE equal to 9. The loop at line 104 will advance normally with no risk of infinite loop.

However, if MAX_CONCURRENT becomes configurable in the future (as the comment suggests), consider adding a defensive floor to prevent CHUNK_SIZE from becoming 0:

-const CHUNK_SIZE = MAX_CONCURRENT - 1;
+const CHUNK_SIZE = Math.max(1, MAX_CONCURRENT - 1);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@addons/dexie-cloud/src/sync/eagerBlobDownloader.ts` at line 58, CHUNK_SIZE
currently sets to MAX_CONCURRENT - 1 which can become zero if MAX_CONCURRENT is
ever configured to 1; change the CHUNK_SIZE declaration to enforce a defensive
minimum (e.g. at least 1) so the loop in eagerBlobDownloader (the loop around
line 104) can always advance; update the CHUNK_SIZE computation to use a floor
such as taking the max between 1 and MAX_CONCURRENT - 1, and add a brief comment
referencing MAX_CONCURRENT from BlobDownloadTracker to explain the defensive
guard.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@addons/dexie-cloud/src/sync/eagerBlobDownloader.ts`:
- Line 58: CHUNK_SIZE currently sets to MAX_CONCURRENT - 1 which can become zero
if MAX_CONCURRENT is ever configured to 1; change the CHUNK_SIZE declaration to
enforce a defensive minimum (e.g. at least 1) so the loop in eagerBlobDownloader
(the loop around line 104) can always advance; update the CHUNK_SIZE computation
to use a floor such as taking the max between 1 and MAX_CONCURRENT - 1, and add
a brief comment referencing MAX_CONCURRENT from BlobDownloadTracker to explain
the defensive guard.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 29729273-cf01-48d3-a54a-4c8fc4792f85

📥 Commits

Reviewing files that changed from the base of the PR and between 65f54fb and ed59f5c.

📒 Files selected for processing (6)

• addons/dexie-cloud/src/middlewares/blobResolveMiddleware.ts
• addons/dexie-cloud/src/sync/BlobDownloadTracker.ts
• addons/dexie-cloud/src/sync/BlobSavingQueue.ts
• addons/dexie-cloud/src/sync/eagerBlobDownloader.ts
• addons/dexie-cloud/src/types/TXExpandos.ts
• src/live-query/live-query.ts