@tanstack/react-db 0.5.1 → 0.5.4

package/skills/react-db/SKILL.md

@@ -324,6 +324,56 @@ See meta-framework/SKILL.md for full preloading patterns.
 
 ## Common Mistakes
 
+### CRITICAL Using === instead of eq() in .where()
+
+Wrong — throws `InvalidWhereExpressionError` at runtime:
+
+```tsx
+const { data } = useLiveQuery({
+  query: (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => todo.completed === true),
+})
+```
+
+Correct — use expression functions from `@tanstack/react-db`:
+
+```tsx
+import { useLiveQuery, eq } from '@tanstack/react-db'
+
+const { data } = useLiveQuery({
+  query: (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.completed, true)),
+})
+```
+
+JavaScript `===`, `!==`, `<`, and `>` evaluate immediately and return a boolean. Use expression functions such as `eq`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, and `not` for structured `.where()` predicates. See db-core/live-queries/SKILL.md for the full operator reference.
+
+### CRITICAL Assigning useLiveQuery result directly instead of destructuring
+
+Wrong — crashes with "map is not a function":
+
+```tsx
+const todos = useLiveQuery({
+  query: (q) => q.from({ todo: todoCollection }),
+})
+return todos.map((t) => <li>{t.text}</li>) // TypeError: todos.map is not a function
+```
+
+Correct — destructure `{ data }`:
+
+```tsx
+const { data: todos } = useLiveQuery({
+  query: (q) => q.from({ todo: todoCollection }),
+})
+return todos.map((t) => <li key={t.id}>{t.text}</li>)
+```
+
+`useLiveQuery` returns an object with `data`, `isLoading`, `status`, and other fields. For queries that can be disabled, use `{ data: todos = [] }` to handle `data` being `undefined`.
+
 ### CRITICAL Using opaque query logic without queryKey
 
 Wrong:

package/src/development.ts

@@ -0,0 +1,15 @@
+// Bundlers inline `process.env.NODE_ENV` even where `process` does not exist,
+// so it is read directly; without either, warnings stay off.
+export function shouldWarnInDevelopment(disableEnvVar: string): boolean {
+  try {
+    if (process.env.NODE_ENV === `production`) return false
+  } catch {
+    return false
+  }
+  // A page may supply a `process` shim without `env`; nothing disabled it.
+  try {
+    return process.env[disableEnvVar] !== `1`
+  } catch {
+    return true
+  }
+}

package/src/useLiveQuery.ts

@@ -5,16 +5,17 @@ import {
   BaseQueryBuilder,
   IR,
   UnhashableQueryIRError,
-  createLiveQueryCollection,
   createLiveQueryObserver,
   deepEquals,
   getPreparedLiveQueryIdentity,
   getStableValueHash,
   isCollection,
   prepareLiveQueryValue,
+  resolveLiveQueryValue,
 } from '@tanstack/db'
 import { useOptionalDbClient } from './DbProvider'
 import { setLiveQueryResultInfo } from './live-query-internals'
+import { shouldWarnInDevelopment } from './development'
 import type {
   Collection,
   CollectionImpl,
@@ -55,22 +56,20 @@ const suspenseCollectionsByClient = new WeakMap<
   DbClient,
   Map<string, SuspenseCollectionEntry>
 >()
-const suspenseSourceIds = new WeakMap<object, number>()
-let nextSuspenseSourceId = 0
+const sourceObjectTokens = new WeakMap<object, number>()
+let nextSourceObjectToken = 0
 
-function getSuspenseSourceId(source: object): number {
-  let id = suspenseSourceIds.get(source)
+function getSourceObjectToken(source: object): number {
+  let id = sourceObjectTokens.get(source)
   if (id === undefined) {
-    id = ++nextSuspenseSourceId
-    suspenseSourceIds.set(source, id)
+    id = ++nextSourceObjectToken
+    sourceObjectTokens.set(source, id)
   }
   return id
 }
 
-function getUnscopedSuspenseKey(
-  preparedValue: unknown,
-  queryHash: string,
-): string {
+function getPreparedSources(preparedValue: unknown): Array<{ id: string }> {
+  if (isCollection(preparedValue)) return [preparedValue]
   const query =
     preparedValue instanceof BaseQueryBuilder
       ? preparedValue
@@ -80,10 +79,19 @@ function getUnscopedSuspenseKey(
           preparedValue.query instanceof BaseQueryBuilder
         ? preparedValue.query
         : undefined
-  if (!query) return queryHash
-  const sourceIds = IR.collectCollectionSources(query._getQuery()).map(
-    ({ collection }) => getSuspenseSourceId(collection),
-  )
+  return query
+    ? IR.collectCollectionSources(query._getQuery()).map(
+        ({ collection }) => collection,
+      )
+    : []
+}
+
+function getSourceQualifiedSuspenseKey(
+  preparedValue: unknown,
+  queryHash: string,
+): string {
+  const sourceIds = getPreparedSources(preparedValue).map(getSourceObjectToken)
+  if (sourceIds.length === 0) return queryHash
   return `${sourceIds.join(`,`)}:${queryHash}`
 }
 
@@ -172,16 +180,6 @@ export function warnDeprecatedDepsArray(
   )
 }
 
-function shouldWarnInDevelopment(disableEnvVar: string): boolean {
-  if (typeof process === `undefined`) {
-    return false
-  }
-
-  return (
-    process.env.NODE_ENV !== `production` && process.env[disableEnvVar] !== `1`
-  )
-}
-
 function getCurrentTime(): number {
   return typeof performance !== `undefined` &&
     typeof performance.now === `function`
@@ -336,40 +334,6 @@ export function warnUnhashableDerivedIdentity(
   )
 }
 
-function createCollectionFromPreparedQuery(
-  value: unknown,
-  defaultGcTime = DEFAULT_GC_TIME_MS,
-) {
-  if (value === undefined || value === null) {
-    return null
-  }
-
-  if (isCollection(value)) {
-    value.startSyncImmediate()
-    return value
-  }
-
-  if (value instanceof BaseQueryBuilder) {
-    return createLiveQueryCollection({
-      query: value,
-      startSync: true,
-      gcTime: defaultGcTime,
-    })
-  }
-
-  if (typeof value === `object`) {
-    return createLiveQueryCollection({
-      startSync: true,
-      gcTime: defaultGcTime,
-      ...(value as LiveQueryCollectionConfig<any>),
-    })
-  }
-
-  throw new Error(
-    `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof value}`,
-  )
-}
-
 /**
  * Create a live query using a query function.
  * @param queryFn - Query function that defines what data to fetch
@@ -547,9 +511,7 @@ export function useLiveQuery<
   deps?: Array<unknown>,
 ): {
   state:
-    | Map<string | number, GetResult<TContext>>
-    | Map<TKey, TResult>
-    | undefined
+    Map<string | number, GetResult<TContext>> | Map<TKey, TResult> | undefined
   data: InferResultType<TContext> | Array<TResult> | undefined
   collection:
     | Collection<GetResult<TContext>, string | number, {}>
@@ -771,6 +733,36 @@ export function useLiveQueryForSuspense(
   return useLiveQueryImpl(configOrQueryOrCollection, deps, true)
 }
 
+// What one hook instance keeps across renders. It lives in a single ref
+// slot, so a render neither looks up nor allocates more.
+function createHookInstance(dbClient: DbClient | undefined) {
+  return {
+    collection: null as Collection<object, string | number, {}> | null,
+    deps: null as Array<unknown> | null,
+    config: null as unknown,
+    client: dbClient,
+    legacyUnhashableIdentity: [`legacy-unhashable`] as Array<unknown>,
+    derivedIdentityProfiler: {
+      renderCount: 0,
+      totalMs: 0,
+      maxMs: 0,
+      warned: false,
+    } as DerivedIdentityProfiler,
+    deferredCollections: new Set<
+      CollectionImpl<any, string | number, any, any, any>
+    >(),
+    sourceIds: {
+      unscoped: new Map<string, number>(),
+      byClient: new WeakMap<DbClient, Map<string, number>>(),
+    },
+    observer: null as LiveQueryObserver<object, string | number> | null,
+    queryHash: undefined as string | undefined,
+    suspenseKey: undefined as string | undefined,
+    identityError: undefined as UnhashableQueryIRError | undefined,
+    subscribe: null as ((onStoreChange: () => void) => () => void) | null,
+  }
+}
+
 function useLiveQueryImpl(
   configOrQueryOrCollection: any,
   deps: Array<unknown> | undefined,
@@ -784,32 +776,21 @@ function useLiveQueryImpl(
     : (getExplicitDbClient(configOrQueryOrCollection) ?? contextDbClient)
   const resolvedDeps = deps ?? []
 
-  // Use refs to cache collection and track dependencies
-  const collectionRef = useRef<Collection<object, string | number, {}> | null>(
-    null,
-  )
-  const depsRef = useRef<Array<unknown> | null>(null)
-  const configRef = useRef<unknown>(null)
-  const clientRef = useRef(dbClient)
-  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([
-    `legacy-unhashable`,
-  ])
-
-  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({
-    renderCount: 0,
-    totalMs: 0,
-    maxMs: 0,
-    warned: false,
-  })
-  const deferredCollectionsRef = useRef(
-    new Set<CollectionImpl<any, string | number, any, any, any>>(),
-  )
-  const observerRef = useRef<LiveQueryObserver<object, string | number> | null>(
-    null,
-  )
-  const queryHashRef = useRef<string | undefined>(undefined)
-  const suspenseKeyRef = useRef<string | undefined>(undefined)
-  const identityErrorRef = useRef<UnhashableQueryIRError | undefined>(undefined)
+  const instanceRef = useRef<ReturnType<typeof createHookInstance> | null>(null)
+  const instance = (instanceRef.current ??= createHookInstance(dbClient))
+  const resumeDeferredCollections = () => {
+    const collections = Array.from(instance.deferredCollections)
+    instance.deferredCollections.clear()
+    const errors: Array<unknown> = []
+    for (const collection of collections) {
+      try {
+        collection._resumeSyncStart()
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+    if (errors.length) throw errors[0]
+  }
 
   const queryKey = !inputIsCollection
     ? getExplicitQueryKey(configOrQueryOrCollection)
@@ -825,22 +806,29 @@ function useLiveQueryImpl(
     streamIdentity = [`queryKey`, queryKey]
   } else if (deps !== undefined) {
     identityDeps = resolvedDeps
-    try {
-      preparedQueryValue = prepareQueryValue(
-        configOrQueryOrCollection,
-        dbClient,
-        deferredCollectionsRef.current,
-      )
-      streamIdentity = [
-        `deps`,
-        resolvedDeps,
-        getPreparedLiveQueryIdentity(preparedQueryValue),
-      ]
-    } catch (error) {
-      if (!(error instanceof UnhashableQueryIRError)) throw error
-      warnUnhashableDerivedIdentity(error)
-      identityError = error
-    }
+    // Deps decide reuse. Only hydration and Suspense read the query hash; the
+    // development warning about unhashable queries still derives it.
+    if (
+      dbClient ||
+      forSuspense ||
+      shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)
+    )
+      try {
+        preparedQueryValue = prepareQueryValue(
+          configOrQueryOrCollection,
+          dbClient,
+          instance.deferredCollections,
+        )
+        streamIdentity = [
+          `deps`,
+          resolvedDeps,
+          getPreparedLiveQueryIdentity(preparedQueryValue),
+        ]
+      } catch (error) {
+        if (!(error instanceof UnhashableQueryIRError)) throw error
+        warnUnhashableDerivedIdentity(error)
+        identityError = error
+      }
   } else if (inputIsCollection) {
     identityDeps = []
     streamIdentity = [`collection`, configOrQueryOrCollection.id]
@@ -848,8 +836,8 @@ function useLiveQueryImpl(
     const preparation = prepareDerivedQuery(
       configOrQueryOrCollection,
       dbClient,
-      derivedIdentityProfilerRef.current,
-      deferredCollectionsRef.current,
+      instance.derivedIdentityProfiler,
+      instance.deferredCollections,
     )
     preparedQueryValue = preparation.value
     if (preparation.status === `hashable`) {
@@ -857,7 +845,7 @@ function useLiveQueryImpl(
       streamIdentity = preparation.identityDeps
     } else {
       warnUnhashableDerivedIdentity(preparation.error)
-      identityDeps = legacyUnhashableIdentityRef.current
+      identityDeps = instance.legacyUnhashableIdentity
       identityError = preparation.error
     }
   }
@@ -880,36 +868,60 @@ function useLiveQueryImpl(
     warnDeprecatedDepsArray()
   }
 
+  if (
+    queryKey === undefined &&
+    deps === undefined &&
+    preparedQueryValue !== unpreparedQueryValue
+  ) {
+    const prior = dbClient
+      ? instance.sourceIds.byClient.get(dbClient)
+      : instance.sourceIds.unscoped
+    const seen = new Map<string, number>()
+    for (const source of getPreparedSources(preparedQueryValue)) {
+      const token = getSourceObjectToken(source)
+      const previous = seen.get(source.id) ?? prior?.get(source.id)
+      if (previous !== undefined && previous !== token) {
+        // The rejected render must not retain a shared Collection's sync deferral.
+        resumeDeferredCollections()
+        throw new Error(
+          `[useLiveQuery] 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 bindings = prior ?? new Map<string, number>()
+    for (const [id, token] of seen) bindings.set(id, token)
+    if (dbClient) instance.sourceIds.byClient.set(dbClient, bindings)
+  }
+
   const canReuseSuspenseKey =
     forSuspense &&
     !inputIsCollection &&
     queryHash !== undefined &&
-    !dbClient &&
-    collectionRef.current !== null &&
-    clientRef.current === dbClient &&
-    queryHashRef.current === queryHash &&
-    suspenseKeyRef.current !== undefined
+    instance.collection !== null &&
+    instance.client === dbClient &&
+    instance.queryHash === queryHash &&
+    instance.suspenseKey !== undefined
 
   if (
     forSuspense &&
     !inputIsCollection &&
     queryHash &&
-    !dbClient &&
     !canReuseSuspenseKey &&
     preparedQueryValue === unpreparedQueryValue
   ) {
     preparedQueryValue = prepareQueryValue(
       configOrQueryOrCollection,
       dbClient,
-      deferredCollectionsRef.current,
+      instance.deferredCollections,
     )
   }
 
   const suspenseKey =
-    queryHash && !dbClient
+    queryHash && forSuspense && !inputIsCollection
       ? canReuseSuspenseKey
-        ? suspenseKeyRef.current
-        : getUnscopedSuspenseKey(preparedQueryValue, queryHash)
+        ? instance.suspenseKey
+        : getSourceQualifiedSuspenseKey(preparedQueryValue, queryHash)
       : queryHash
 
   const suspenseCollections =
@@ -922,24 +934,17 @@ function useLiveQueryImpl(
   const suspenseCollection = suspenseEntry?.collection
 
   const identityChanged =
-    depsRef.current === null ||
+    instance.deps === null ||
     (deps !== undefined
-      ? depsRef.current.length !== identityDeps.length ||
-        depsRef.current.some((dep, index) => dep !== identityDeps[index])
-      : !deepEquals(depsRef.current, identityDeps))
+      ? instance.deps.length !== identityDeps.length ||
+        instance.deps.some((dep, index) => dep !== identityDeps[index])
+      : !deepEquals(instance.deps, identityDeps))
 
   // Check if we need to create/recreate the collection
   const needsNewCollection =
-    !collectionRef.current ||
-    (inputIsCollection && configRef.current !== configOrQueryOrCollection) ||
-    (!inputIsCollection && (clientRef.current !== dbClient || identityChanged))
-
-  const resumeDeferredCollections = () => {
-    for (const collection of deferredCollectionsRef.current) {
-      collection._resumeSyncStart()
-    }
-    deferredCollectionsRef.current.clear()
-  }
+    !instance.collection ||
+    (inputIsCollection && instance.config !== configOrQueryOrCollection) ||
+    (!inputIsCollection && (instance.client !== dbClient || identityChanged))
 
   if (needsNewCollection) {
     if (inputIsCollection) {
@@ -963,25 +968,28 @@ function useLiveQueryImpl(
       }
       // It's already a collection, ensure sync is started for React hooks
       configOrQueryOrCollection.startSyncImmediate()
-      collectionRef.current = configOrQueryOrCollection
-      configRef.current = configOrQueryOrCollection
+      instance.collection = configOrQueryOrCollection
+      instance.config = configOrQueryOrCollection
     } else {
       if (suspenseCollection) {
-        collectionRef.current = suspenseCollection
+        instance.collection = suspenseCollection
       } else {
         if (preparedQueryValue === unpreparedQueryValue) {
           preparedQueryValue = prepareQueryValue(
             configOrQueryOrCollection,
             dbClient,
-            deferredCollectionsRef.current,
+            instance.deferredCollections,
           )
         }
-        collectionRef.current = createCollectionFromPreparedQuery(
-          preparedQueryValue,
-          forSuspense ? DEFAULT_SUSPENSE_GC_TIME_MS : DEFAULT_GC_TIME_MS,
-        ) as SuspenseCollection | null
-        if (suspenseCollections && suspenseKey && collectionRef.current) {
-          const collection = collectionRef.current
+        instance.collection = resolveLiveQueryValue(preparedQueryValue, {
+          gcTime: forSuspense
+            ? DEFAULT_SUSPENSE_GC_TIME_MS
+            : DEFAULT_GC_TIME_MS,
+          // Hydration and Suspense key the live-query Collection by identity.
+          pool: !forSuspense && !dbClient,
+        }) as SuspenseCollection | null
+        if (suspenseCollections && suspenseKey && instance.collection) {
+          const collection = instance.collection
           const removeCleanupListener = collection.on(`status:cleaned-up`, () =>
             releaseSuspenseCollection(
               suspenseCollections,
@@ -1013,13 +1021,13 @@ function useLiveQueryImpl(
           suspenseCollections.set(suspenseKey, entry)
         }
       }
-      configRef.current = configOrQueryOrCollection
-      depsRef.current = [...identityDeps]
+      instance.config = configOrQueryOrCollection
+      instance.deps = [...identityDeps]
     }
-    clientRef.current = dbClient
-    queryHashRef.current = queryHash
-    suspenseKeyRef.current = suspenseKey
-    identityErrorRef.current = identityError
+    instance.client = dbClient
+    instance.queryHash = queryHash
+    instance.suspenseKey = suspenseKey
+    instance.identityError = identityError
   }
 
   // Recreate the observer when the underlying collection changes. The observer
@@ -1035,38 +1043,38 @@ function useLiveQueryImpl(
     // hook's pre-observer loading policy, and — because wholesale delivers
     // nothing synchronously during subscribe — never notifies
     // useSyncExternalStore inside its own subscribe call.
-    observerRef.current = createLiveQueryObserver(collectionRef.current, {
+    instance.observer = createLiveQueryObserver(instance.collection, {
       mode: `wholesale`,
       client: dbClient,
-      queryHash: queryHashRef.current,
+      queryHash: instance.queryHash,
       onPreload: resumeDeferredCollections,
     })
   }
-  const observer = observerRef.current!
+  const observer = instance.observer!
 
   // Stable subscribe bound to the current observer; the observer owns the
   // subscription, ready-race, and disposal.
-  const subscribeRef = useRef<
-    ((onStoreChange: () => void) => () => void) | null
-  >(null)
-  if (!subscribeRef.current || needsNewCollection) {
-    subscribeRef.current = (onStoreChange: () => void) => {
-      const unsubscribe = observer.subscribe(() => onStoreChange())
+  if (!instance.subscribe || needsNewCollection) {
+    instance.subscribe = (onStoreChange: () => void) => {
+      const unsubscribe = observer.subscribe(onStoreChange)
       resumeDeferredCollections()
       return unsubscribe
     }
   }
 
   const returned = useSyncExternalStore(
-    subscribeRef.current,
+    instance.subscribe,
     () => observer.getSnapshot(),
     () => observer.getServerSnapshot(),
   )
-  setLiveQueryResultInfo(returned, {
-    client: dbClient,
-    queryHash: queryHashRef.current,
-    identityError: identityErrorRef.current,
-    observer,
-  })
+  // Only useLiveSuspenseQuery reads this, and it costs a define per render.
+  if (forSuspense) {
+    setLiveQueryResultInfo(returned, {
+      client: dbClient,
+      queryHash: instance.queryHash,
+      identityError: instance.identityError,
+      observer,
+    })
+  }
   return returned as any
 }