@tanstack/react-db 0.5.12 → 1.0.0-rc.1.1

package/skills/react-db/SKILL.md

@@ -9,8 +9,8 @@ description: >
   useLiveInfiniteQuery for cursor-based pagination (pageSize, fetchNextPage,
   hasNextPage, isFetchingNextPage). usePacedMutations for debounced React
   state updates. Return shape: data, state, collection, status, isLoading,
-  isReady, isError. Import from @tanstack/react-db (re-exports all of
-  @tanstack/db).
+  isReady, isLoadingError, isCrashed, isSyncError, health. Import from
+  @tanstack/react-db (re-exports all of @tanstack/db).
 type: framework
 library: db
 framework: react
@@ -69,9 +69,12 @@ const {
   status,
   isLoading,
   isReady,
-  isError,
+  isLoadingError, // the first load failed: nothing to show
+  isCrashed, // status 'crashed': local storage broke
   isIdle,
   isCleanedUp,
+  isSyncError, // data is shown, but a sync problem is in health
+  health, // health tree: one node for the query and one per source
 } = useLiveQuery({
   query: (q) =>
     q
@@ -86,7 +89,7 @@ const { data } = useLiveQuery({
 })
 
 // Pre-created collection (from route loader)
-const { data } = useLiveQuery(preloadedCollection)
+const { data } = useLiveQuery(preloadedTodos)
 
 // Conditional query — derived identity handles enabled/disabled transitions
 const { data, status } = useLiveQuery({
@@ -100,6 +103,10 @@ const { data, status } = useLiveQuery({
 // When disabled: status='disabled', data=undefined
 ```
 
+`isLoadingError` means the first load failed and there is nothing to show; offer `collection.reload()`. `isCrashed` means local storage broke; only `cleanup({ dependents: true })` and a fresh start recover. After the query is ready, sync problems never change `status`: read `isSyncError` or the `health` tree to show stale-data warnings. `isError` and node `phase` were removed.
+
+Many queries of one shape, such as one per list row, can share one partition. Pass `pool: pooledLiveQueries` (from `@tanstack/db`) in the config form: `useLiveQuery({ query, pool: pooledLiveQueries })`. Pooling applies to queries that filter one eager source with `eq(field, literal)`. It is off by default, and Suspense and `DbClient` queries never pool.
+
 ### useLiveSuspenseQuery
 
 ```tsx
@@ -171,7 +178,7 @@ const mutate = usePacedMutations({
 
 ## Includes (Hierarchical Data)
 
-When a query uses includes (subqueries in `select`), each child field is a live `Collection` by default. Subscribe to it with `useLiveQuery` in a subcomponent:
+When a query uses `include()` for a subquery in `select`, each child field is a live `Collection`. Subscribe to it with `useLiveQuery` in a subcomponent:
 
 ```tsx
 function ProjectList() {
@@ -180,10 +187,12 @@ function ProjectList() {
       q.from({ p: projectsCollection }).select(({ p }) => ({
         id: p.id,
         name: p.name,
-        issues: q
-          .from({ i: issuesCollection })
-          .where(({ i }) => eq(i.projectId, p.id))
-          .select(({ i }) => ({ id: i.id, title: i.title })),
+        issues: include(
+          q
+            .from({ i: issuesCollection })
+            .where(({ i }) => eq(i.projectId, p.id))
+            .select(({ i }) => ({ id: i.id, title: i.title })),
+        ),
       })),
   })
 
@@ -241,8 +250,8 @@ See db-core/live-queries/SKILL.md for full includes rules (correlation condition
 
 Live query results include computed, read-only virtual properties on every row:
 
-- `$synced`: `true` when no pending local optimistic write affects the row;
-  `false` while one does. It does not prove backend confirmation.
+- `$hasPendingWrites`: `true` while a pending local optimistic write affects
+  the row; `false` otherwise. It does not prove backend confirmation.
 - `$origin`: `"local"` if the last confirmed change came from this client, otherwise `"remote"`.
 - `$key`: the row key for the result.
 - `$collectionId`: the source collection ID.
@@ -254,7 +263,7 @@ const { data } = useLiveQuery({
   query: (q) =>
     q
       .from({ todo: todoCollection })
-      .where(({ todo }) => eq(todo.$synced, false)),
+      .where(({ todo }) => eq(todo.$hasPendingWrites, true)),
 })
 // Shows rows with pending local optimistic writes
 ```
@@ -294,9 +303,9 @@ const { data } = useLiveQuery({
 })
 ```
 
-Before 1.0, opaque IR warns and keeps legacy mount-stable identity. Slow or
-repeated derived identity work also warns once. Both point to the same
-`queryKey` escape hatch; unhashable IR without a key will throw in 1.0.
+Unhashable IR without `queryKey` throws `UnhashableQueryIRError`, even with a
+dependency array. Slow or repeated derived identity work warns once and points
+to the same `queryKey` escape hatch.
 
 ### Suspense + Error Boundary
 

package/src/live-query-internals.ts

@@ -1,5 +1,6 @@
 import type {
   DbClient,
+  DeferredLiveQueryCollections,
   LiveQueryObserver,
   UnhashableQueryIRError,
 } from '@tanstack/db'
@@ -11,6 +12,8 @@ export type LiveQueryResultInfo = {
   queryHash: string | undefined
   identityError: UnhashableQueryIRError | undefined
   observer: LiveQueryObserver<object, string | number>
+  /** Sync starts this render deferred, released if the render throws. */
+  deferredCollections: DeferredLiveQueryCollections
 }
 
 type ResultWithInfo = {

package/src/source-id-bindings.ts

@@ -1,75 +1,29 @@
 import { getPreparedLiveQuerySources } from '@tanstack/db'
 import type { DbClient } from '@tanstack/db'
 
-export { resumeDeferredLiveQueryCollections as resumeSyncStarts } from '@tanstack/db'
-
-const sourceObjectTokens = new WeakMap<object, number>()
-let nextSourceObjectToken = 0
-
-export function getSourceObjectToken(source: object): number {
-  let id = sourceObjectTokens.get(source)
-  if (id === undefined) {
-    id = ++nextSourceObjectToken
-    sourceObjectTokens.set(source, id)
+/**
+ * Reports a descriptor source that no DbClient bound, naming the provider a
+ * React tree needs. Returns `undefined` when a client can bind descriptors.
+ */
+export function getUnboundDescriptorReporter(
+  client: DbClient | undefined,
+  hookName: string,
+): ((alias: string) => never) | undefined {
+  if (client) return undefined
+  return (alias) => {
+    throw new Error(
+      `[${hookName}] Collection descriptor "${alias}" requires a DbClient when the query is consumed. Wrap this component in <DbProvider client={client}> or use a concrete Collection.`,
+    )
   }
-  return id
 }
 
 export function getPreparedSources(
   preparedValue: unknown,
-  client?: DbClient,
-  hookName?: string,
+  client: DbClient | undefined,
+  hookName: string,
 ): Array<{ id: string }> {
   return getPreparedLiveQuerySources(
     preparedValue,
-    !client && hookName
-      ? (alias) => {
-          throw new Error(
-            `[${hookName}] Collection descriptor "${alias}" requires a DbClient when the query is consumed. Wrap this component in <DbProvider client={client}> or use a concrete Collection.`,
-          )
-        }
-      : undefined,
+    getUnboundDescriptorReporter(client, hookName),
   )
 }
-
-/** The source object each Collection ID named while one hook is mounted. */
-export type SourceIdBindings = {
-  unscoped: Map<string, number>
-  byClient: WeakMap<DbClient, Map<string, number>>
-}
-
-export function createSourceIdBindings(): SourceIdBindings {
-  return { unscoped: new Map(), byClient: new WeakMap() }
-}
-
-/**
- * Derived query identity names each source by its Collection ID. While a hook
- * is mounted, an ID must keep naming one source object in each client scope,
- * or the hook could reuse a live query that reads the old source. Claims the
- * prepared value's sources, or calls `release` and throws on a collision so a
- * rejected render keeps no sync-start deferral.
- */
-export function claimSourceIds(
-  bindings: SourceIdBindings,
-  preparedValue: unknown,
-  client: DbClient | undefined,
-  hookName: string,
-  release: () => void,
-): void {
-  const prior = client ? bindings.byClient.get(client) : bindings.unscoped
-  const seen = new Map<string, number>()
-  for (const source of getPreparedSources(preparedValue, client, hookName)) {
-    const token = getSourceObjectToken(source)
-    const previous = seen.get(source.id) ?? prior?.get(source.id)
-    if (previous !== undefined && previous !== token) {
-      release()
-      throw new Error(
-        `[${hookName}] Source Collection "${source.id}" was replaced by a different Collection with the same ID while this hook is mounted. Unmount the hook and clean up its previous source and client scope before reusing the ID.`,
-      )
-    }
-    seen.set(source.id, token)
-  }
-  const claimed = prior ?? new Map<string, number>()
-  for (const [id, token] of seen) claimed.set(id, token)
-  if (client) bindings.byClient.set(client, claimed)
-}