Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Reusable queries: standalone descriptor resolution and nested alias composition limits

Đang mở
  • Có gì không ổn?
#2,072 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@KyleAMathews đang làm issue này rồi.

Từ ngày 7/10/2026.

  • #2079 của @KyleAMathews — đang mở

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
react, typescript
Lĩnh vực
backend-api-design, developer-experience

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
TypeScript
Star
3.9k
Fork
268
Merge trung bình
1 ngày 2 giờ
Pull request đã merge (30 ngày)
200

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của TanStack/db

Tất cả issue của TanStack/db

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.