Add preloaded hybrid database with parallel startup

[quolpr]

Summary

• add PreloadedHybridDB with ID-only preloaded B-tree and uniqhash indexes plus on-demand row hydration
• support transactional hash indexes, external-storage merges, and safe IndexedDB bulk scans
• preload tables with configurable concurrency, defaulting to "whole"
• document the API and startup memory tradeoffs

Validation

• pnpm --filter @will-be-done/hyperdb test (866 passed, 16 skipped)
• HyperDB lint, cycle check, build, docs, and format checks
• web integration unit/type/lint checks and Playwright e2e (24 passed)

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by CodeRabbit

• New Features
  • Tables now preload concurrently by default, improving startup performance.
  • Added preloadConcurrency settings to limit parallel loading, use sequential loading, or load all tables concurrently.
  • Successful table preloads are retained even if another table fails.
• Documentation
  • Updated setup guides and reference documentation with concurrency options, driver behavior, and temporary memory considerations.
• Tests
  • Added coverage for concurrent, bounded, sequential, asynchronous, and failure scenarios.

[codesandbox]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview

[netlify]

✅ Deploy Preview for hyperdb ready!

Name	Link
🔨 Latest commit	6049b27
🔍 Latest deploy log	https://app.netlify.com/projects/hyperdb/deploys/6a8f1b210e2abe000863ca51
😎 Deploy Preview	https://deploy-preview-27--hyperdb.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[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: 1de722eb-0206-4e3d-a78e-b1e82deb6767

📥 Commits

Reviewing files that changed from the base of the PR and between 0ef1d58 and 6049b27.

📒 Files selected for processing (8)

• .changeset/green-indexes-rest.md
• README.md
• packages/hyperdb-doc/src/content/docs/runtime/db.md
• packages/hyperdb-doc/src/content/docs/start/llm-cheat-sheet.md
• packages/hyperdb/README.md
• packages/hyperdb/src/hyperdb/drivers/idb/idb-driver.scan-all.test.ts
• packages/hyperdb/src/hyperdb/runtime/preloaded-hybrid-db.test.ts
• packages/hyperdb/src/hyperdb/runtime/preloaded-hybrid-db.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

PreloadedHybridDB now preloads tables concurrently by default. It accepts positive integer limits or "whole", supports sequential loading with 1, preserves successful preloads after failures, and handles synchronous and asynchronous drivers.

Changes

Preload concurrency

Layer / File(s)	Summary
Runtime preload scheduling packages/hyperdb/src/hyperdb/runtime/preloaded-hybrid-db.ts	Adds concurrency validation and scheduling. loadTables selects sequential or concurrent loading and retains successful table states.
Concurrency and driver validation packages/hyperdb/src/hyperdb/runtime/preloaded-hybrid-db.test.ts, packages/hyperdb/src/hyperdb/drivers/idb/idb-driver.scan-all.test.ts	Tests default, bounded, sequential, failed, synchronous, asynchronous, and IndexedDB preload behavior.
Preload concurrency documentation .changeset/green-indexes-rest.md, README.md, packages/hyperdb/README.md, packages/hyperdb-doc/src/content/docs/runtime/db.md, packages/hyperdb-doc/src/content/docs/start/llm-cheat-sheet.md	Documents concurrency settings, driver scheduling, and temporary startup memory effects.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Merge Risk: ⚪ Minimal · up to 6049b

The PR adds preloaded hybrid database startup behavior and related documentation, with the reported validation checks passing. No actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant PreloadedHybridDB
  participant PrimaryDriver
  Caller->>PreloadedHybridDB: call loadTables
  PreloadedHybridDB->>PrimaryDriver: scan supplied tables by concurrency limit
  PrimaryDriver-->>PreloadedHybridDB: return rows or preload error
  PreloadedHybridDB-->>Caller: install table states or throw preload error

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 7 functions across 3 files. (5 skipped: 5 …	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 clearly summarizes the main change: adding PreloadedHybridDB with parallel startup through concurrent table preloading.
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.

Full details: Docstring Coverage

Explanation

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 7 functions across 3 files. (5 skipped: 5 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch feat/preloaded-hybrid-parallel-preload

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/preloaded-hybrid-parallel-preload

---

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