Reusable queries: standalone descriptor resolution and nested alias composition limits

Start with packages/db/src/query/builder/index.ts and packages/db/src/live-query-options.ts to trace when descriptor resolution occurs, then review the composable queries and SSR guides. Existing provider tests and alias tests cover the supplied-builder path and rejected collisions; add focused coverage for standalone reusable builders with descriptors under a provider. The issue also calls for a decision on standalone resolution and alias identity, with broader scope, correlation, sibling-reuse, and output-shape tests before any alias-contract change.

Reusable queries with collection descriptors hit an undocumented resolver limit, and nested alias restrictions make helper composition harder. This tracks the Discord report from Xandor Schiefer and separates the reproducible behavior from a proposed change to the alias contract.

Investigated on main at c65799410 (@tanstack/db 0.12.2, @tanstack/react-db 0.5.6). The reporter's installed versions and full application are unknown.

1. new Query() cannot resolve descriptors, even under DbProvider

import {
  DbClient, Query, collectionOptions, localOnlyCollectionOptions,
} from '@tanstack/db'
import { DbProvider, useLiveQuery } from '@tanstack/react-db'

const items = collectionOptions(localOnlyCollectionOptions({
  id: 'items',
  getKey: (row: { id: number }) => row.id,
  initialData: [{ id: 1 }],
}))

function reusableItems() {
  return new Query().from({ item: items })
    .select(({ item }) => ({ id: item.id }))
}

function View() {
  const { data } = useLiveQuery(() => reusableItems())
  return <pre>{JSON.stringify(data)}</pre>
}

const client = new DbClient()
// Render:
// <DbProvider client={client}><View /></DbProvider>

Construction throws:

Cannot use collection descriptor "item" as a query source without a DbClient resolver. In React, wrap your tree in <DbProvider>.

The suggested provider fix is misleading here: the provider is already present. Descriptor resolution happens eagerly in BaseQueryBuilder._createRefsForSource. The hook supplies a resolver only to its callback argument through createInitialQueryBuilder; a separately constructed builder does not inherit it. Query exposes a zero-argument constructor.

Confirmed alternatives:

• Accept q: InitialQueryBuilder in the helper and call it with the hook's supplied q.
• Use client.collection(items) as the source of new Query(). That binds the query to that client, so it is not a client-independent reusable descriptor query.

The Composable Queries documentation recommends standalone builders with concrete Collections. The SSR guide recommends reusable descriptors resolved against the current client. The limitation when combining these patterns needs an explicit supported example and a useful error.

2. Parent/subquery alias collisions still reject composition

Using the supplied builder solves resolution but not alias collisions:

useLiveQuery((q) => {
  const reusable = q.from({ item: items })
    .select(({ item }) => ({ id: item.id }))
  return q.from({ item: items })
    .innerJoin({ child: reusable }, ({ item, child }) => eq(item.id, child.id))
    .select(({ item }) => ({ id: item.id }))
})
// Import eq from @tanstack/db.
// Throws DuplicateAliasInSubqueryError: Subquery uses alias "item" ...

PR #719 added this rejection to prevent incorrect results. The current architecture contract still forbids ancestor alias shadowing. Supporting it would revise that contract; simply removing validation is not a safe fix.

The report's claim that a reusable query cannot be used twice needs qualification: two sibling derived sources with distinct outer aliases (left and right) can both use the same helper whose internal alias is item. That case returned the expected row in the probe. Parent/child collisions remain rejected. The reporter uses builder threading and a stateful alias generator to work around these limits in deeply nested scheduler queries.

Follow-up

• Document descriptor-compatible reusable helpers and correct the standalone-builder error.
• Decide whether client-independent standalone descriptor queries should be supported, and when resolution would occur.
• Decide whether scoped alias identity should allow safe helper composition without caller-managed unique names. Preserve correlation binding and implicit namespaced output keys if changing this contract.

Validation and test gap

Four temporary React probes passed on current source: descriptor rejection inside a provider callback; supplied-builder resolution with two sibling placements; standalone construction with a concrete client Collection; and parent/subquery alias rejection. These are narrow examples, not proof of the reporter's full scheduler query or all nesting shapes.

Existing provider tests cover the supplied-builder path; alias tests deliberately assert parent collisions throw. The missing check is the interaction between standalone reusable builders and descriptors under a provider. Any alias redesign needs broader scope/correlation coverage, including nested helpers, sibling reuse, and public output shape, rather than changing only the rejection assertion.