feat: add materialize() helper for includes subqueries #1504
main fromrefs/pull/1504/head·merged by kevin-dp(GitHub profile, opens in a new tab) Closes #1481.
Summary#
- Adds
materialize()— a single helper for materializing includes subqueries onto parent rows. It resolves toArray<T>when the wrapped subquery returns multiple rows, and toT | undefinedwhen the subquery isfindOne(). The intent is to spare callers from unwrapping a singleton array whenever they know the child query yields at most one row. toArray()is unchanged — it still always producesArray<T>.materialize()is purely additive.- Implementation: extends the existing
IncludesMaterializationenum with'singleton', threads it through the IR / compiler / runtime, and updates thematerializeIncludedValuehelper to return the first child row (orundefined) for the singleton case. The reactive re-emit machinery routes through that helper, so insert/update/delete/no-match transitions all flow naturally. - Type inference:
materialize(q.from(...).findOne())infersT | undefined,materialize(q.from(...))infersArray<T>. Detected at the type level via a phantomIsSingleflag onMaterializeWrapperthat's set fromTContext extends SingleResult. materialize()is also rejected inside expressions (coalesce(),eq(), …) with the same kind of error message thattoArray()produces.
Example#
// Multi-row → Array<Issue>
select(({ p }) => ({
...p,
issues: materialize(
q.from({ i: issues }).where(({ i }) => eq(i.projectId, p.id))
),
}))
// Singleton → Project | undefined
select(({ i }) => ({
...i,
project: materialize(
q.from({ p: projects }).where(({ p }) => eq(p.id, i.projectId)).findOne()
),
}))
A changeset will follow in a separate commit.
Test plan#
- New runtime tests in
tests/query/includes.test.tscover singleton attach, missing-match →undefined, insert / update / delete reactivity, two parents sharing a correlation key, multi-row fallback, scalar singleton, and nestedmaterialize(array of singletons). - New type tests in
tests/query/includes.test-d.tscover array, singleton (with select / without select / scalar), and a nested array-of-singleton case. - Full
packages/dbtest suite passes (1502 tests, 0 type errors). - Package builds cleanly.
🤖 Generated with Claude Code
Summary by CodeRabbit#
New Features
- Introduced
materialize()helper function for wrapping subqueries in SELECT statements, providing clean snapshot materialization. - Automatically returns
T | undefinedfor single-row queries andArray<T>for multi-row queries. - Supports nested materialization for complex query structures.
- Introduced
Tests
- Added comprehensive test coverage for materialize functionality.
- 1
Size Change: +128 B (+0.11%)
Total Size: 122 kB
📦 View Changed
Filename Size Change packages/db/dist/esm/index.js3.02 kB +15 B (+0.5%) packages/db/dist/esm/query/builder/functions.js1.4 kB +33 B (+2.41%) packages/db/dist/esm/query/builder/index.js5.84 kB +48 B (+0.83%) packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB +18 B (+1.47%) packages/db/dist/esm/query/live/collection-config-builder.js8.36 kB +14 B (+0.17%) compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/collection/change-events.js1.39 kB packages/db/dist/esm/collection/changes.js1.38 kB packages/db/dist/esm/collection/cleanup-queue.js810 B packages/db/dist/esm/collection/events.js434 B packages/db/dist/esm/collection/index.js3.61 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js1.69 kB packages/db/dist/esm/collection/mutations.js2.46 kB packages/db/dist/esm/collection/state.js5.33 kB packages/db/dist/esm/collection/subscription.js3.74 kB packages/db/dist/esm/collection/sync.js2.88 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.01 kB packages/db/dist/esm/event-emitter.js748 B packages/db/dist/esm/indexes/auto-index.js829 B packages/db/dist/esm/indexes/base-index.js729 B packages/db/dist/esm/indexes/basic-index.js2.05 kB packages/db/dist/esm/indexes/btree-index.js2.17 kB packages/db/dist/esm/indexes/index-registry.js820 B packages/db/dist/esm/indexes/reverse-index.js538 B packages/db/dist/esm/local-only.js890 B packages/db/dist/esm/local-storage.js2.1 kB packages/db/dist/esm/optimistic-action.js359 B packages/db/dist/esm/paced-mutations.js496 B packages/db/dist/esm/proxy.js3.75 kB packages/db/dist/esm/query/compiler/evaluators.js1.83 kB packages/db/dist/esm/query/compiler/expressions.js430 B packages/db/dist/esm/query/compiler/group-by.js3.56 kB packages/db/dist/esm/query/compiler/index.js6.67 kB packages/db/dist/esm/query/compiler/joins.js2.5 kB packages/db/dist/esm/query/compiler/lazy-targets.js918 B packages/db/dist/esm/query/compiler/order-by.js1.74 kB packages/db/dist/esm/query/compiler/select.js1.4 kB packages/db/dist/esm/query/effect.js4.77 kB packages/db/dist/esm/query/expression-helpers.js1.43 kB packages/db/dist/esm/query/ir.js1.25 kB packages/db/dist/esm/query/live-query-collection.js360 B packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js1.93 kB packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/utils.js1.81 kB packages/db/dist/esm/query/optimizer.js2.92 kB packages/db/dist/esm/query/predicate-utils.js2.97 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/subset-dedupe.js960 B packages/db/dist/esm/scheduler.js1.3 kB packages/db/dist/esm/SortedMap.js1.3 kB packages/db/dist/esm/strategies/debounceStrategy.js247 B packages/db/dist/esm/strategies/queueStrategy.js428 B packages/db/dist/esm/strategies/throttleStrategy.js246 B packages/db/dist/esm/transactions.js3.02 kB packages/db/dist/esm/utils.js927 B packages/db/dist/esm/utils/array-utils.js273 B packages/db/dist/esm/utils/browser-polyfills.js304 B packages/db/dist/esm/utils/btree.js5.61 kB packages/db/dist/esm/utils/comparison.js1.05 kB packages/db/dist/esm/utils/cursor.js457 B packages/db/dist/esm/utils/index-optimization.js1.54 kB packages/db/dist/esm/utils/type-guards.js157 B packages/db/dist/esm/virtual-props.js360 B Size Change: 0 B
Total Size: 4.24 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/index.js249 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.32 kB packages/react-db/dist/esm/useLiveQuery.js1.34 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B packages/react-db/dist/esm/usePacedMutations.js401 B This is much needed as doing
toArrayand then data.[0] everywhere really clutters everythingCaution
Review failed#
Pull request was closed or merged during review
📝 Walkthrough
Walkthrough#
This PR introduces a new
materialize()function that wraps included subqueries to return single values forfindOne()queries or arrays for multi-row queries. The feature updates the query builder's type inference, compilation, IR, runtime materialization logic, validation, and includes comprehensive tests for both type safety and runtime behavior.Changes#
Materialize subquery materialization
Layer / File(s) Summary Materialize wrapper and public API
packages/db/src/query/builder/functions.ts,packages/db/src/query/index.tsMaterializeWrapperclass wraps subqueries with result type and single-row flag.materialize()function returns appropriately-typed wrappers based on whether the query context extendsSingleResult.Type inference for materialize projections
packages/db/src/query/builder/types.tsSelectValueunion andResultTypeFromSelectValue/ResultTypeFromSelectconditional types updated to mapMaterializeWrapper<T, true>toT | undefinedandMaterializeWrapper<T, false>toArray<T>.Select compilation and materialization type tracking
packages/db/src/query/builder/index.ts,packages/db/src/query/ir.tsbuildNestedSelectcompilesMaterializeWrapperinstances intoIncludesSubqueryIR nodes, determining materialization mode assingletonorarrayfrom the child query'ssingleResultflag.IncludesMaterializationIR type extended withsingletonvariant.Runtime materialization and expression validation
packages/db/src/query/live/collection-config-builder.ts,packages/db/src/query/builder/ref-proxy.tsmaterializeIncludedValueextracts first value forsingletonmaterialization mode.toExpression()rejectsMaterializeWrapperas non-direct-select usage to prevent misuse inside expressions.Type inference and runtime behavior tests
packages/db/tests/query/includes.test-d.ts,packages/db/tests/query/includes.test.tsType tests verify inference across multi-row arrays, single-result nullability, scalar results, and nested scenarios. Runtime tests validate singleton/array materialization, child-to-parent reactivity, shared-correlation behavior, and nested materialization with per-row singleton lookups. 🎯 3 (Moderate) | ⏱️ ~25 minutes
A function bundled with care, Unwraps subqueries fair, Single or array with grace, Materialized in its place! 🐰✨
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
Check name Status Explanation Resolution Docstring Coverage ⚠️ Warning Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold. ✏️ Tip: You can configure your own custom pre-merge checks in the settings.✅ Passed checks (4 passed)
Check name Status Explanation Title check ✅ Passed The title clearly and concisely describes the main addition: a new materialize() helper for includes subqueries, which is the primary change across the PR. Description check ✅ Passed The description includes the required sections with comprehensive detail: summary of changes, implementation approach, type inference behavior, examples, and test plan. All required checklist items are addressed. Linked Issues check ✅ Passed The PR fully implements the objectives from #1481: provides materialize() helper for findOne subqueries, returns Array for multi-row and T | undefined for singular queries, implements proper materialization semantics, and includes comprehensive tests.Out of Scope Changes check ✅ Passed All changes are directly scoped to implementing the materialize() helper: type definitions, implementation, IR updates, runtime logic, and comprehensive tests. No unrelated modifications detected. ✨ 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 `kevin/includes-materialize`
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.
Comment `@coderabbitai help` to get the list of available commands and usage tips.samwillis(GitHub profile, opens in a new tab) approved these changes
kevin-dp(GitHub profile, opens in a new tab) closed this
The tanstack db docs are currently missing the new
materializefunction, right? 😅
Sign in to join this conversation.
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@tanstack/db
@tanstack/db-ivm
@tanstack/db-sqlite-persistence-core
@tanstack/electric-db-collection
@tanstack/electron-db-sqlite-persistence
@tanstack/expo-db-sqlite-persistence
@tanstack/node-db-sqlite-persistence
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit:
28acd3c