fix(db): lazily initialize runtime reference identities

[TimFL]

🎯 Changes

Lazily initializes runtime reference identities when they are first needed instead of during module evaluation.

The previous eager initialization called crypto.getRandomValues() at global scope, causing @tanstack/db imports to fail in Cloudflare Workers before the request handler could run.

The initialized factory remains cached for the lifetime of the runtime, preserving the existing namespace, WeakMap, and reference identity semantics.

This PR also adds:

• A regression test proving module evaluation does not call getRandomValues.
• Verification that the first identity request initializes the factory exactly once.
• A patch changeset for @tanstack/db.

The fix was additionally verified in a production Cloudflare Worker.

✅ Checklist

• I have tested this code locally with pnpm test.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

---

This fixes #1781

Summary by CodeRabbit

• Bug Fixes

  • Prevented unnecessary random value generation when database modules are loaded in Cloudflare Workers.
  • Runtime reference identities are now initialized only when first needed, improving module startup behavior.

• Tests

  • Added coverage confirming identities are initialized lazily and reused consistently.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3471cacf-ffa5-4117-b536-778052e8bfd1

📥 Commits

Reviewing files that changed from the base of the PR and between e441140 and cc607e7.

📒 Files selected for processing (2)

• packages/db/src/query/runtime-reference-identity.ts
• packages/db/tests/query/ir-stable-identity.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/db/tests/query/ir-stable-identity.test.ts
• packages/db/src/query/runtime-reference-identity.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The runtime reference identity factory now initializes on first use instead of during module evaluation. A test verifies that import does not access random values and that repeated calls initialize the identity source once. A patch changeset documents the update.

Changes

Runtime reference identity lifecycle

Layer / File(s)	Summary
Lazy factory initialization packages/db/src/query/runtime-reference-identity.ts	getRuntimeReferenceIdentity now lazily creates and caches the runtime reference identity factory when first called.
Lazy initialization validation packages/db/tests/query/ir-stable-identity.test.ts, .changeset/lazy-runtime-reference-identities.md	The test verifies that import does not generate random values and that two calls initialize the identity source once. The changeset documents the patch.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to cc607

The change defers runtime identity initialization until first use while preserving cached identity behavior; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant ModuleEvaluation
  participant getRuntimeReferenceIdentity
  participant crypto
  ModuleEvaluation->>getRuntimeReferenceIdentity: Import module without invoking function
  getRuntimeReferenceIdentity->>crypto: Call getRandomValues on first invocation
  getRuntimeReferenceIdentity->>getRuntimeReferenceIdentity: Cache identity factory

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: lazy initialization of runtime reference identities.
Description check	✅ Passed	The description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, testing, production verification, and changeset, with the required checklist items ma…
Linked Issues check	✅ Passed	The implementation addresses issue #1781 by deferring runtime reference identity initialization until first use, preventing crypto.getRandomValues() during module evaluation. The regression test verif…
Out of Scope Changes check	✅ Passed	All changes are within scope for issue #1781: the lazy initialization fix, regression test, and patch changeset directly support the reported Cloudflare Workers import failure.

Full details: Description check

Explanation

The description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, testing, production verification, and changeset, with the required checklist items marked.

Full details: Linked Issues check

Explanation

The implementation addresses issue #1781 by deferring runtime reference identity initialization until first use, preventing crypto.getRandomValues() during module evaluation. The regression test verifies deferred initialization and exactly-once factory creation, while preserving cached identity semantics.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}