Skip to content
Source
Sign inSign up
TanStack/db

fix(db): use Ref<T, Nullable> for left join select refs instead of Ref<T> | undefined #1262

Mergedkevin-dp(GitHub profile, opens in a new tab)merged 5 commits intomain fromrefs/pull/1262/headmerged by kevin-dp(GitHub profile, opens in a new tab)

Improves types of LEFT, RIGHT, and FULL joined data. Closes https://github.com/TanStack/db/issues/1251.

Summary

  • Adds failing type tests that assert the desired behavior for left join refs in declarative .select() callbacks
  • Currently, left-joined table refs are typed as Ref<T> | undefined, which forces optional chaining (dept?.name). Since these refs are always truthy proxy objects at build time, the | undefined is misleading and encourages runtime conditional patterns (profile ? profile.bio : null) that silently fail — the truthy branch is always taken
  • The fix (in a follow-up) will introduce Ref<T, Nullable> where nullability is encoded as a type parameter rather than a union, so that:
    • Direct property access works without ?. (honest — the proxy is always present)
    • Result types still correctly produce T | undefined for fields from left-joined tables
    • Users are guided toward coalesce() / isNull() for null handling in declarative queries

Test plan

  • Type test for left, right, and full join select with direct property access (currently fails — expected)
  • Type test for inner join select with direct property access (passes — baseline)

🤖 Generated with Claude Code

    1. 🦋 Changeset detected

      Latest commit: 7c94a5f2069ca19bb060fb10a780bafe6097c3ea

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 12 packages
      NameType
      @tanstack/dbPatch
      @tanstack/angular-dbPatch
      @tanstack/electric-db-collectionPatch
      @tanstack/offline-transactionsPatch
      @tanstack/powersync-db-collectionPatch
      @tanstack/query-db-collectionPatch
      @tanstack/react-dbPatch
      @tanstack/rxdb-db-collectionPatch
      @tanstack/solid-dbPatch
      @tanstack/svelte-dbPatch
      @tanstack/trailbase-db-collectionPatch
      @tanstack/vue-dbPatch

      Not sure what this means? Click here to learn what changesets are.

      Click here if you're a maintainer who wants to add another changeset to this PR

    2. More templates

      @tanstack/angular-db

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

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/electric-db-collection

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

      @tanstack/offline-transactions

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

      @tanstack/powersync-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: 7c94a5f

    3. Size Change: 0 B

      Total Size: 92.1 kB

      ℹ️ View Unchanged
      FilenameSize
      ./packages/db/dist/esm/collection/change-events.js1.39 kB
      ./packages/db/dist/esm/collection/changes.js1.22 kB
      ./packages/db/dist/esm/collection/events.js388 B
      ./packages/db/dist/esm/collection/index.js3.32 kB
      ./packages/db/dist/esm/collection/indexes.js1.1 kB
      ./packages/db/dist/esm/collection/lifecycle.js1.75 kB
      ./packages/db/dist/esm/collection/mutations.js2.34 kB
      ./packages/db/dist/esm/collection/state.js3.49 kB
      ./packages/db/dist/esm/collection/subscription.js3.71 kB
      ./packages/db/dist/esm/collection/sync.js2.41 kB
      ./packages/db/dist/esm/deferred.js207 B
      ./packages/db/dist/esm/errors.js4.7 kB
      ./packages/db/dist/esm/event-emitter.js748 B
      ./packages/db/dist/esm/index.js2.69 kB
      ./packages/db/dist/esm/indexes/auto-index.js742 B
      ./packages/db/dist/esm/indexes/base-index.js766 B
      ./packages/db/dist/esm/indexes/btree-index.js2.17 kB
      ./packages/db/dist/esm/indexes/lazy-index.js1.1 kB
      ./packages/db/dist/esm/indexes/reverse-index.js538 B
      ./packages/db/dist/esm/local-only.js808 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/builder/functions.js733 B
      ./packages/db/dist/esm/query/builder/index.js4.09 kB
      ./packages/db/dist/esm/query/builder/ref-proxy.js1.05 kB
      ./packages/db/dist/esm/query/compiler/evaluators.js1.43 kB
      ./packages/db/dist/esm/query/compiler/expressions.js430 B
      ./packages/db/dist/esm/query/compiler/group-by.js1.81 kB
      ./packages/db/dist/esm/query/compiler/index.js2.02 kB
      ./packages/db/dist/esm/query/compiler/joins.js2.11 kB
      ./packages/db/dist/esm/query/compiler/order-by.js1.45 kB
      ./packages/db/dist/esm/query/compiler/select.js1.06 kB
      ./packages/db/dist/esm/query/expression-helpers.js1.43 kB
      ./packages/db/dist/esm/query/ir.js673 B
      ./packages/db/dist/esm/query/live-query-collection.js360 B
      ./packages/db/dist/esm/query/live/collection-config-builder.js5.44 kB
      ./packages/db/dist/esm/query/live/collection-registry.js264 B
      ./packages/db/dist/esm/query/live/collection-subscriber.js2.42 kB
      ./packages/db/dist/esm/query/live/internal.js145 B
      ./packages/db/dist/esm/query/optimizer.js2.62 kB
      ./packages/db/dist/esm/query/predicate-utils.js2.97 kB
      ./packages/db/dist/esm/query/subset-dedupe.js921 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.js2.9 kB
      ./packages/db/dist/esm/utils.js924 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.js952 B
      ./packages/db/dist/esm/utils/cursor.js457 B
      ./packages/db/dist/esm/utils/index-optimization.js1.51 kB
      ./packages/db/dist/esm/utils/type-guards.js157 B
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 3.7 kB

      ℹ️ View Unchanged
      FilenameSize
      ./packages/react-db/dist/esm/index.js225 B
      ./packages/react-db/dist/esm/useLiveInfiniteQuery.js1.17 kB
      ./packages/react-db/dist/esm/useLiveQuery.js1.34 kB
      ./packages/react-db/dist/esm/useLiveSuspenseQuery.js559 B
      ./packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size
    5. How the new typing works

      Problem

      The declarative select() callback receives proxy objects that record property access paths at build time. These proxies are always truthy — they're JavaScript objects, never undefined. But nullable join sides (left/right/full) were typed as Ref<T> | undefined, which led users into traps like:

      .leftJoin({ dept }, ...)
      .select(({ user, dept }) => ({
        // dept is typed as Ref<Department> | undefined, but it's always a truthy proxy
        deptName: dept?.name,          // ?. has no effect at runtime
        safeName: dept?.name ?? 'N/A', // ?? never triggers at runtime
      }))

      Solution

      Nullable join refs are now typed as Ref<T, true> instead of Ref<T> | undefined. The second type parameter (Nullable) is a brand that propagates through all nested property accesses:

      // RefLeaf uses a conditional brand — only present when Nullable is true
      type RefLeaf<T, Nullable extends boolean = false> = {
        readonly [RefBrand]?: T
      } & ([Nullable] extends [true] ? { readonly [NullableBrand]?: true } : {})

      This means:

      • Ref<T, false> (inner join / from table) — no NullableBrand, result extracts as T
      • Ref<T, true> (nullable join side) — has NullableBrand, result extracts as T | undefined
      • Direct property access works — dept.name compiles without ?. since the proxy is never undefined
      • Result types are correct — dept.name produces string | undefined in the query result via IsNullableRef detection

      Why not Ref<T | undefined> or Ref<T> | undefined?

      • Ref<T | undefined> breaks because RefLeaf<T> uses intersection branding (T & { [RefBrand]?: T }), and (T | undefined) & { brand } collapses to T & { brand } — the undefined gets erased. It also breaks mapped type keys since keyof (T | undefined) = never.
      • Ref<T> | undefined is the current approach and the root cause of the problem — it makes the proxy appear nullable when it's always truthy.

      Assignability

      The conditional brand ensures RefLeaf<T, false> extends RefLeaf<T, true> (an absent optional property satisfies true | undefined). This preserves the QueryBuilder<SpecificContext> → QueryBuilder<Context> assignability needed for subqueries.

    6. ❤️ yes this looks great!

    7. samwillis(GitHub profile, opens in a new tab) approved these changes

      I was hesitant on this as you know, but I think it's the right tradeoff. Let's get it merged.

      packages/db/tests/query/live-query-collection.test.ts lines 2327 to 2328
      @@ -2324,4 +2325,4 @@
      23242325 .join({ users }, ({ comments: c, users: u }) => eq(c.userId, u.id))
      23252326 .select(({ comments: c, users: u }) => ({
      23262327 id: c.id,
      2327- userId: u?.id ?? c.userId,
      2328+ userId: coalesce(u.id, c.userId),

      When our own tests have this bug it makes it VERY clear we should change this!

    8. 🎉 This PR has been released!

      Thank you for your contribution!

Sign in to join this conversation.