fix(db): use Ref<T, Nullable> for left join select refs instead of Ref<T> | undefined #1262
main fromrefs/pull/1262/head·merged 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| undefinedis 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 | undefinedfor fields from left-joined tables - Users are guided toward
coalesce()/isNull()for null handling in declarative queries
- Direct property access works without
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
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@1262commit:
7c94a5fSize Change: 0 B
Total Size: 92.1 kB
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.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 Size Change: 0 B
Total Size: 3.7 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size ./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 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, neverundefined. But nullable join sides (left/right/full) were typed asRef<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 ofRef<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) — noNullableBrand, result extracts asTRef<T, true>(nullable join side) — hasNullableBrand, result extracts asT | undefined- Direct property access works —
dept.namecompiles without?.since the proxy is neverundefined - Result types are correct —
dept.nameproducesstring | undefinedin the query result viaIsNullableRefdetection
Why not
Ref<T | undefined>orRef<T> | undefined?#Ref<T | undefined>breaks becauseRefLeaf<T>uses intersection branding (T & { [RefBrand]?: T }), and(T | undefined) & { brand }collapses toT & { brand }— theundefinedgets erased. It also breaks mapped type keys sincekeyof (T | undefined)=never.Ref<T> | undefinedis 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>extendsRefLeaf<T, true>(an absent optional property satisfiestrue | undefined). This preserves theQueryBuilder<SpecificContext>→QueryBuilder<Context>assignability needed for subqueries.❤️ yes this looks great!
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!
kevin-dp(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
🦋 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
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