Skip to content
Source
Sign inSign up
TanStack/db

feat: add materialize() helper for includes subqueries #1504

Mergedkevin-dp(GitHub profile, opens in a new tab)merged 2 commits intomain fromrefs/pull/1504/headmerged 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 to Array<T> when the wrapped subquery returns multiple rows, and to T | undefined when the subquery is findOne(). 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 produces Array<T>. materialize() is purely additive.
  • Implementation: extends the existing IncludesMaterialization enum with 'singleton', threads it through the IR / compiler / runtime, and updates the materializeIncludedValue helper to return the first child row (or undefined) 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()) infers T | undefined, materialize(q.from(...)) infers Array<T>. Detected at the type level via a phantom IsSingle flag on MaterializeWrapper that's set from TContext extends SingleResult.
  • materialize() is also rejected inside expressions (coalesce(), eq(), …) with the same kind of error message that toArray() 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.ts cover singleton attach, missing-match → undefined, insert / update / delete reactivity, two parents sharing a correlation key, multi-row fallback, scalar singleton, and nested materialize (array of singletons).
  • New type tests in tests/query/includes.test-d.ts cover array, singleton (with select / without select / scalar), and a nested array-of-singleton case.
  • Full packages/db test 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 | undefined for single-row queries and Array<T> for multi-row queries.
    • Supports nested materialization for complex query structures.
  • Tests

    • Added comprehensive test coverage for materialize functionality.
    1. More templates

      @tanstack/angular-db

      npm i https://pkg.pr.new/@tanstack/angular-db@1504

      @tanstack/browser-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1504

      @tanstack/capacitor-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1504

      @tanstack/cloudflare-durable-objects-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1504

      @tanstack/db

      npm i https://pkg.pr.new/@tanstack/db@1504

      @tanstack/db-ivm

      npm i https://pkg.pr.new/@tanstack/db-ivm@1504

      @tanstack/db-sqlite-persistence-core

      npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1504

      @tanstack/electric-db-collection

      npm i https://pkg.pr.new/@tanstack/electric-db-collection@1504

      @tanstack/electron-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1504

      @tanstack/expo-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1504

      @tanstack/node-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1504

      @tanstack/offline-transactions

      npm i https://pkg.pr.new/@tanstack/offline-transactions@1504

      @tanstack/powersync-db-collection

      npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1504

      @tanstack/query-db-collection

      npm i https://pkg.pr.new/@tanstack/query-db-collection@1504

      @tanstack/react-db

      npm i https://pkg.pr.new/@tanstack/react-db@1504

      @tanstack/react-native-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1504

      @tanstack/rxdb-db-collection

      npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1504

      @tanstack/solid-db

      npm i https://pkg.pr.new/@tanstack/solid-db@1504

      @tanstack/svelte-db

      npm i https://pkg.pr.new/@tanstack/svelte-db@1504

      @tanstack/tauri-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1504

      @tanstack/trailbase-db-collection

      npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1504

      @tanstack/vue-db

      npm i https://pkg.pr.new/@tanstack/vue-db@1504

      commit: 28acd3c

    2. Size Change: +128 B (+0.11%)

      Total Size: 122 kB

      📦 View Changed
      FilenameSizeChange
      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%)
      ℹ️ View Unchanged
      FilenameSize
      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
      compressed-size-action::db-package-size
    3. Size Change: 0 B

      Total Size: 4.24 kB

      ℹ️ View Unchanged
      FilenameSize
      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
      compressed-size-action::react-db-package-size
    4. This is much needed as doing toArray and then data.[0] everywhere really clutters everything

    5. Review Change Stack

      Caution

      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 for findOne() 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.ts
      MaterializeWrapper class wraps subqueries with result type and single-row flag. materialize() function returns appropriately-typed wrappers based on whether the query context extends SingleResult.
      Type inference for materialize projections
      packages/db/src/query/builder/types.ts
      SelectValue union and ResultTypeFromSelectValue/ResultTypeFromSelect conditional types updated to map MaterializeWrapper<T, true> to T | undefined and MaterializeWrapper<T, false> to Array<T>.
      Select compilation and materialization type tracking
      packages/db/src/query/builder/index.ts, packages/db/src/query/ir.ts
      buildNestedSelect compiles MaterializeWrapper instances into IncludesSubquery IR nodes, determining materialization mode as singleton or array from the child query's singleResult flag. IncludesMaterialization IR type extended with singleton variant.
      Runtime materialization and expression validation
      packages/db/src/query/live/collection-config-builder.ts, packages/db/src/query/builder/ref-proxy.ts
      materializeIncludedValue extracts first value for singleton materialization mode. toExpression() rejects MaterializeWrapper as 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.ts
      Type 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 nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring 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.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe 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✅ PassedThe 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✅ PassedThe 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✅ PassedAll changes are directly scoped to implementing the materialize() helper: type definitions, implementation, IR updates, runtime logic, and comprehensive tests. No unrelated modifications detected.
      ✏️ 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 `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.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    6. samwillis(GitHub profile, opens in a new tab) approved these changes

    7. The tanstack db docs are currently missing the new materialize function, right? 😅

Sign in to join this conversation.