Reusable queries: standalone descriptor resolution and nested alias composition limits

Fechada
  • Algo errado?
#2,072 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

@KyleAMathews já está trabalhando nisso.

Desde 7/10/2026.

  • #2079 de @KyleAMathews — aberto

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
25/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
react, typescript
Domínio
backend-api-design, developer-experience

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
TypeScript
Estrelas
4k
Forks
277
Merge médio
1d 11h
PRs com merge (30d)
148

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de TanStack/db

Todas as issues de TanStack/db

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.