@tanstack/react-db 0.3.2 → 0.3.4

package/dist/cjs/index.d.cts

@@ -1,5 +1,5 @@
 export { useLiveQuery } from './useLiveQuery.cjs';
-export type { LiveQueryKey, UseLiveQueryConfig, UseLiveQueryStatus, } from './useLiveQuery.cjs';
+export type { ConditionalUseLiveQueryConfig, LiveQueryKey, UseLiveQueryConfig, UseLiveQueryStatus, } from './useLiveQuery.cjs';
 export * from './DbProvider.cjs';
 export * from './HydrationBoundary.cjs';
 export * from './useLiveSuspenseQuery.cjs';

package/dist/cjs/useLiveInfiniteQuery.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveInfiniteQuery.cjs","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["'use client'\n\nimport { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  assertLiveQueryWindowManyResult,\n  compareLiveQueryWindowDependencies,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  fetchNextLiveQueryWindowPage,\n  getLiveQueryWindowCollectionWarning,\n  getLiveQueryWindowInputKind,\n  normalizeLiveQueryWindowPageSize,\n  resolveLiveQueryWindowInput,\n  shouldPreserveLiveQueryWindowPageCount,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport {\n  prepareDerivedQuery,\n  prepareQueryValue,\n  warnDeprecatedDepsArray,\n  warnUnhashableDerivedIdentity,\n} from './useLiveQuery'\nimport type {\n  DerivedIdentityProfiler,\n  LiveQueryKey,\n  useLiveQuery,\n} from './useLiveQuery'\nimport type {\n  Collection,\n  CollectionImpl as CollectionImplType,\n  Context,\n  DbClient,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  /**\n   * Explicit identity for queries that contain opaque functional variants or\n   * are hot enough that deriving identity from structured IR is too expensive.\n   * Structured queries should omit this so DB can derive identity directly.\n   */\n  queryKey?: LiveQueryKey\n  /** Override the nearest DbProvider for this query. */\n  client?: DbClient\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => Promise<void>\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\ntype InfiniteQueryRenderState = {\n  inputKind: `collection` | `query`\n  inputCollection: Collection<any, any, any> | null\n  inputQuery: unknown\n  client: DbClient | undefined\n  identityMode: `collection` | `queryKey` | `legacyDeps` | `derived`\n  dependencies: Array<unknown> | null\n  pageSize: number\n  initialPageParam: number\n  collection: Collection<any, any, any>\n  controller: LiveQueryWindowController<any, any>\n  warning: string | null\n  warned: boolean\n  deferredCollections: Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >\n}\n\n/**\n * Create an infinite query using a query function with live updates.\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)\n  const initialPageParam = config.initialPageParam ?? 0\n  const contextDbClient = useOptionalDbClient()\n  const dbClient = config.client ?? contextDbClient\n\n  const inputIsCollection =\n    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`\n\n  const committedRef = useRef<InfiniteQueryRenderState | null>(null)\n  const committed = committedRef.current\n  const inputKind = inputIsCollection ? `collection` : `query`\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n  const deferredCollections = new Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >()\n\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown> = []\n  let identityMode: InfiniteQueryRenderState[`identityMode`] = `collection`\n\n  if (!inputIsCollection) {\n    if (config.queryKey !== undefined) {\n      identityMode = `queryKey`\n      identityDeps = config.queryKey\n    } else if (deps !== undefined) {\n      identityMode = `legacyDeps`\n      identityDeps = deps\n      warnDeprecatedDepsArray(`useLiveInfiniteQuery`)\n    } else if (\n      committed?.identityMode === `derived` &&\n      committed.inputQuery === queryFnOrCollection &&\n      committed.client === dbClient\n    ) {\n      identityMode = `derived`\n      identityDeps = committed.dependencies ?? []\n    } else {\n      identityMode = `derived`\n      const preparation = prepareDerivedQuery(\n        queryFnOrCollection,\n        dbClient,\n        derivedIdentityProfilerRef.current,\n        deferredCollections,\n      )\n      preparedQueryValue = preparation.value\n      if (preparation.status === `hashable`) {\n        identityDeps = preparation.identityDeps\n      } else {\n        warnUnhashableDerivedIdentity(preparation.error)\n        identityDeps = legacyUnhashableIdentityRef.current\n      }\n    }\n  }\n\n  const usesLegacyDeps =\n    !inputIsCollection && config.queryKey === undefined && deps !== undefined\n  const dependencyComparison = compareLiveQueryWindowDependencies(\n    committed?.dependencies,\n    identityDeps,\n  )\n  const sameClient = committed?.client === dbClient\n  const dependenciesChanged =\n    !inputIsCollection &&\n    (!sameClient ||\n      (usesLegacyDeps\n        ? dependencyComparison.changed\n        : !dependencyComparison.structurallyEqual))\n  const dependenciesStructurallyEqual =\n    usesLegacyDeps && sameClient && dependencyComparison.structurallyEqual\n  const needsNewCollection =\n    committed === null ||\n    committed.inputKind !== inputKind ||\n    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    committed === null ||\n    committed.pageSize !== pageSize ||\n    committed.initialPageParam !== initialPageParam\n  const needsNewController =\n    committed === null || needsNewCollection || pageShapeChanged\n\n  let renderState = committed\n  if (needsNewController) {\n    let collection = committed?.collection\n    let warning: string | null = null\n\n    if (needsNewCollection) {\n      let inputValue = queryFnOrCollection\n      if (!inputIsCollection) {\n        if (preparedQueryValue === unpreparedQueryValue) {\n          preparedQueryValue = prepareQueryValue(\n            queryFnOrCollection,\n            dbClient,\n            deferredCollections,\n          )\n        }\n        inputValue = () => preparedQueryValue\n      }\n      const input = resolveLiveQueryWindowInput<TContext>(inputValue)\n      if (input.kind === `collection`) {\n        collection = input.collection\n      } else {\n        // Wrap the query with the first page's peek-ahead window; the controller\n        // grows the limit from here via setWindow.\n        collection = createLiveQueryCollection({\n          query: input.query.limit(pageSize + 1).offset(0),\n          // Construction happens during render. Synchronization starts only when\n          // useSyncExternalStore commits the controller subscription.\n          startSync: false,\n          gcTime: DEFAULT_GC_TIME_MS,\n        })\n      }\n    }\n\n    if (!collection) {\n      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)\n    }\n\n    if (inputIsCollection) {\n      warning =\n        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null\n    } else {\n      assertLiveQueryWindowManyResult(collection)\n    }\n\n    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({\n      hasPreviousController: committed !== null,\n      previousInputKind: committed?.inputKind,\n      inputKind,\n      sameCollection:\n        inputIsCollection && committed?.inputCollection === collection,\n      dependenciesChanged,\n      dependenciesStructurallyEqual,\n      pageShapeChanged,\n    })\n    const previousPageCount = committed\n      ? Math.max(1, committed.controller.getSnapshot().pages.length)\n      : 1\n    const initialPageCount = canPreservePageCount ? previousPageCount : 1\n    renderState = {\n      inputKind,\n      inputCollection: inputIsCollection ? collection : null,\n      inputQuery: inputIsCollection ? null : queryFnOrCollection,\n      client: dbClient,\n      identityMode,\n      dependencies: inputIsCollection ? null : [...identityDeps],\n      pageSize,\n      initialPageParam,\n      collection,\n      controller: createLiveQueryWindowController(collection, {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      }),\n      warning,\n      warned: false,\n      deferredCollections,\n    }\n  }\n  const currentRenderState = renderState!\n  const controller = currentRenderState.controller\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const unsubscribe = controller.subscribe(onStoreChange)\n      committedRef.current = currentRenderState\n      if (currentRenderState.warning && !currentRenderState.warned) {\n        currentRenderState.warned = true\n        console.warn(currentRenderState.warning)\n      }\n      for (const collection of currentRenderState.deferredCollections) {\n        collection._resumeSyncStart()\n      }\n      currentRenderState.deferredCollections.clear()\n      return unsubscribe\n    },\n    [controller, currentRenderState],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n\n  const fetchNextPage = useCallback(\n    () => fetchNextLiveQueryWindowPage(controller),\n    [controller],\n  )\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":["warnDeprecatedDepsArray","prepareDerivedQuery","warnUnhashableDerivedIdentity","compareLiveQueryWindowDependencies","prepareQueryValue","assertLiveQueryWindowManyResult","useCallback"],"mappings":";;;;;;;AAwCA;AACA;AA2FO;AAKL;AACA;AACA;AACA;AAEA;AAGA;AACA;AACA;AACA;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA2D;AACzD;AAEF;AAIA;AAEA;AACA;AAEA;AACE;AACE;AACA;AAAsB;AAEtB;AACA;AACAA;AAA8C;AAM9C;AACA;AAAyC;AAEzC;AACA;AAAoBC;AAClB;AACA;AAC2B;AAC3B;AAEF;AACA;AACE;AAA2B;AAE3BC;AACA;AAA2C;AAC7C;AACF;AAGF;AAEA;AAA6BC;AAChB;AACX;AAEF;AACA;AAMA;AAEA;AAKA;AAIA;AAGA;AACA;AACE;AACA;AAEA;AACE;AACA;AACE;AACE;AAAqBC;AACnB;AACA;AACA;AAAA;AAGJ;AAAmB;AAErB;AACA;AACE;AAAmB;AAInB;AAAuC;AACU;AAAA;AAAA;AAGpC;AACH;AACT;AACH;AAGF;AACE;AAAsE;AAGxE;AACE;AACmE;AAEnEC;AAA0C;AAG5C;AAAoE;AAC7B;AACP;AAC9B;AAEsD;AACtD;AACA;AACA;AAEF;AAGA;AACA;AAAc;AACZ;AACkD;AACX;AAC/B;AACR;AACyD;AACzD;AACA;AACA;AACwD;AACtD;AACA;AACA;AACD;AACD;AACQ;AACR;AAAA;AAGJ;AACA;AAEA;AAAkBC;AAEd;AACA;AACA;AACE;AACA;AAAuC;AAEzC;AACE;AAAW;AAEb;AACA;AAAO;AACT;AAC+B;AAEjC;AACA;AAEA;AAAsBA;AACyB;AAClC;AAGb;AAAO;AACU;AACC;AACC;AACG;AACF;AACD;AACC;AACI;AAEX;AAEA;AACK;AACK;AACrB;AACsB;AACO;AACb;AAEpB;;"}
+{"version":3,"file":"useLiveInfiniteQuery.cjs","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["'use client'\n\nimport { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  assertLiveQueryWindowManyResult,\n  compareLiveQueryWindowDependencies,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  fetchNextLiveQueryWindowPage,\n  getLiveQueryWindowCollectionWarning,\n  getLiveQueryWindowInputKind,\n  normalizeLiveQueryWindowPageSize,\n  resolveLiveQueryWindowInput,\n  shouldPreserveLiveQueryWindowPageCount,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport {\n  prepareDerivedQuery,\n  prepareQueryValue,\n  warnDeprecatedDepsArray,\n  warnUnhashableDerivedIdentity,\n} from './useLiveQuery'\nimport type {\n  DerivedIdentityProfiler,\n  LiveQueryKey,\n  useLiveQuery,\n} from './useLiveQuery'\nimport type {\n  Collection,\n  CollectionImpl as CollectionImplType,\n  Context,\n  DbClient,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  /**\n   * Explicit identity for queries that contain opaque functional variants or\n   * are hot enough that deriving identity from structured IR is too expensive.\n   * Structured queries should omit this so DB can derive identity directly.\n   */\n  queryKey?: LiveQueryKey\n  /** Override the nearest DbProvider for this query. */\n  client?: DbClient\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => Promise<void>\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\ntype InfiniteQueryRenderState = {\n  inputKind: `collection` | `query`\n  inputCollection: Collection<any, any, any> | null\n  inputQuery: unknown\n  client: DbClient | undefined\n  identityMode: `collection` | `queryKey` | `legacyDeps` | `derived`\n  dependencies: Array<unknown> | null\n  pageSize: number\n  initialPageParam: number\n  collection: Collection<any, any, any>\n  controller: LiveQueryWindowController<any, any>\n  warning: string | null\n  warned: boolean\n  deferredCollections: Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >\n}\n\n/**\n * Create an infinite query using a query function with live updates.\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)\n  const initialPageParam = config.initialPageParam ?? 0\n  const contextDbClient = useOptionalDbClient()\n  const dbClient = config.client ?? contextDbClient\n\n  const inputIsCollection =\n    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`\n\n  const committedRef = useRef<InfiniteQueryRenderState | null>(null)\n  const committed = committedRef.current\n  const inputKind = inputIsCollection ? `collection` : `query`\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n  const deferredCollections = new Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >()\n\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown> = []\n  let identityMode: InfiniteQueryRenderState[`identityMode`] = `collection`\n\n  if (!inputIsCollection) {\n    if (config.queryKey !== undefined) {\n      identityMode = `queryKey`\n      identityDeps = config.queryKey\n    } else if (deps !== undefined) {\n      identityMode = `legacyDeps`\n      identityDeps = deps\n      warnDeprecatedDepsArray(`useLiveInfiniteQuery`)\n    } else if (\n      committed?.identityMode === `derived` &&\n      committed.inputQuery === queryFnOrCollection &&\n      committed.client === dbClient\n    ) {\n      identityMode = `derived`\n      identityDeps = committed.dependencies ?? []\n    } else {\n      identityMode = `derived`\n      const preparation = prepareDerivedQuery(\n        queryFnOrCollection,\n        dbClient,\n        derivedIdentityProfilerRef.current,\n        deferredCollections,\n      )\n      preparedQueryValue = preparation.value\n      if (preparation.status === `hashable`) {\n        identityDeps = preparation.identityDeps\n      } else {\n        warnUnhashableDerivedIdentity(preparation.error)\n        identityDeps = legacyUnhashableIdentityRef.current\n      }\n    }\n  }\n\n  const usesLegacyDeps =\n    !inputIsCollection && config.queryKey === undefined && deps !== undefined\n  const dependencyComparison = compareLiveQueryWindowDependencies(\n    committed?.dependencies,\n    identityDeps,\n  )\n  const sameClient = committed?.client === dbClient\n  const dependenciesChanged =\n    !inputIsCollection &&\n    (!sameClient ||\n      (usesLegacyDeps\n        ? dependencyComparison.changed\n        : !dependencyComparison.structurallyEqual))\n  const dependenciesStructurallyEqual =\n    usesLegacyDeps && sameClient && dependencyComparison.structurallyEqual\n  const needsNewCollection =\n    committed === null ||\n    committed.inputKind !== inputKind ||\n    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    committed === null ||\n    committed.pageSize !== pageSize ||\n    committed.initialPageParam !== initialPageParam\n  const needsNewController =\n    committed === null || needsNewCollection || pageShapeChanged\n\n  let renderState = committed\n  if (needsNewController) {\n    let collection = committed?.collection\n    let warning: string | null = null\n\n    if (needsNewCollection) {\n      let inputValue = queryFnOrCollection\n      if (!inputIsCollection) {\n        if (preparedQueryValue === unpreparedQueryValue) {\n          preparedQueryValue = prepareQueryValue(\n            queryFnOrCollection,\n            dbClient,\n            deferredCollections,\n          )\n        }\n        inputValue = () => preparedQueryValue\n      }\n      const input = resolveLiveQueryWindowInput<TContext>(inputValue)\n      if (input.kind === `collection`) {\n        collection = input.collection\n      } else {\n        // Wrap the query with the first page's peek-ahead window; the controller\n        // grows the limit from here via setWindow.\n        collection = createLiveQueryCollection({\n          query: input.query.limit(pageSize + 1).offset(0),\n          // Construction happens during render. Synchronization starts only when\n          // useSyncExternalStore commits the controller subscription.\n          startSync: false,\n          gcTime: DEFAULT_GC_TIME_MS,\n        })\n      }\n    }\n\n    if (!collection) {\n      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)\n    }\n\n    if (inputIsCollection) {\n      warning =\n        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null\n    } else {\n      assertLiveQueryWindowManyResult(collection)\n    }\n\n    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({\n      hasPreviousController: committed !== null,\n      previousInputKind: committed?.inputKind,\n      inputKind,\n      sameCollection:\n        inputIsCollection && committed?.inputCollection === collection,\n      dependenciesChanged,\n      dependenciesStructurallyEqual,\n      pageShapeChanged,\n    })\n    const previousPageCount = committed\n      ? Math.max(1, committed.controller.getSnapshot().pages.length)\n      : 1\n    const initialPageCount = canPreservePageCount ? previousPageCount : 1\n    renderState = {\n      inputKind,\n      inputCollection: inputIsCollection ? collection : null,\n      inputQuery: inputIsCollection ? null : queryFnOrCollection,\n      client: dbClient,\n      identityMode,\n      dependencies: inputIsCollection ? null : [...identityDeps],\n      pageSize,\n      initialPageParam,\n      collection,\n      controller: createLiveQueryWindowController(collection, {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      }),\n      warning,\n      warned: false,\n      deferredCollections,\n    }\n  }\n  const currentRenderState = renderState!\n  const controller = currentRenderState.controller\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const unsubscribe = controller.subscribe(onStoreChange)\n      committedRef.current = currentRenderState\n      if (currentRenderState.warning && !currentRenderState.warned) {\n        currentRenderState.warned = true\n        console.warn(currentRenderState.warning)\n      }\n      for (const collection of currentRenderState.deferredCollections) {\n        collection._resumeSyncStart()\n      }\n      currentRenderState.deferredCollections.clear()\n      return unsubscribe\n    },\n    [controller, currentRenderState],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n\n  const fetchNextPage = useCallback(\n    () => fetchNextLiveQueryWindowPage(controller),\n    [controller],\n  )\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled,\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":["warnDeprecatedDepsArray","prepareDerivedQuery","warnUnhashableDerivedIdentity","compareLiveQueryWindowDependencies","prepareQueryValue","assertLiveQueryWindowManyResult","useCallback"],"mappings":";;;;;;;AAwCA;AACA;AA2FO;AAKL;AACA;AACA;AACA;AAEA;AAGA;AACA;AACA;AACA;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA2D;AACzD;AAEF;AAIA;AAEA;AACA;AAEA;AACE;AACE;AACA;AAAsB;AAEtB;AACA;AACAA;AAA8C;AAM9C;AACA;AAAyC;AAEzC;AACA;AAAoBC;AAClB;AACA;AAC2B;AAC3B;AAEF;AACA;AACE;AAA2B;AAE3BC;AACA;AAA2C;AAC7C;AACF;AAGF;AAEA;AAA6BC;AAChB;AACX;AAEF;AACA;AAMA;AAEA;AAKA;AAIA;AAGA;AACA;AACE;AACA;AAEA;AACE;AACA;AACE;AACE;AAAqBC;AACnB;AACA;AACA;AAAA;AAGJ;AAAmB;AAErB;AACA;AACE;AAAmB;AAInB;AAAuC;AACU;AAAA;AAAA;AAGpC;AACH;AACT;AACH;AAGF;AACE;AAAsE;AAGxE;AACE;AACmE;AAEnEC;AAA0C;AAG5C;AAAoE;AAC7B;AACP;AAC9B;AAEsD;AACtD;AACA;AACA;AAEF;AAGA;AACA;AAAc;AACZ;AACkD;AACX;AAC/B;AACR;AACyD;AACzD;AACA;AACA;AACwD;AACtD;AACA;AACA;AACD;AACD;AACQ;AACR;AAAA;AAGJ;AACA;AAEA;AAAkBC;AAEd;AACA;AACA;AACE;AACA;AAAuC;AAEzC;AACE;AAAW;AAEb;AACA;AAAO;AACT;AAC+B;AAEjC;AACA;AAEA;AAAsBA;AACyB;AAClC;AAGb;AAAO;AACU;AACC;AACC;AACG;AACF;AACD;AACC;AACI;AAEX;AAEA;AACK;AACK;AACrB;AACsB;AACO;AACb;AAEpB;;"}

package/dist/cjs/useLiveQuery.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveQuery.cjs","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["'use client'\n\nimport { useRef, useSyncExternalStore } from 'react'\nimport {\n  BaseQueryBuilder,\n  UnhashableQueryIRError,\n  createLiveQueryCollection,\n  createLiveQueryObserver,\n  deepEquals,\n  getPreparedLiveQueryIdentity,\n  getStableValueHash,\n  isCollection,\n  prepareLiveQueryValue,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport { setLiveQueryResultInfo } from './live-query-internals'\nimport type {\n  Collection,\n  CollectionImpl,\n  CollectionStatus,\n  Context,\n  DbClient,\n  GetResult,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  LiveQueryObserver,\n  NonSingleResult,\n  QueryBuilder,\n  SingleResult,\n} from '@tanstack/db'\n\nconst DEFAULT_GC_TIME_MS = 1 // Live queries created by useLiveQuery are cleaned up immediately (0 disables GC)\nconst DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS = 16\nconst DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD = 10\nconst DERIVED_IDENTITY_TOTAL_WARN_MS = 50\nconst warnedDepsCallsites = new Set<string>()\nconst warnedDerivedIdentityCallsites = new Set<string>()\nconst warnedUnhashableIdentityCallsites = new Set<string>()\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type DerivedIdentityProfiler = {\n  renderCount: number\n  totalMs: number\n  maxMs: number\n  warned: boolean\n}\n\nexport type UseLiveQueryStatus = CollectionStatus | `disabled`\nexport type LiveQueryKey = ReadonlyArray<unknown>\nexport type UseLiveQueryConfig<TContext extends Context> =\n  LiveQueryCollectionConfig<TContext> & {\n    /**\n     * Explicit identity for queries that contain opaque functional variants or\n     * are hot enough that deriving identity from structured IR is too expensive.\n     * Structured queries should omit this so DB can derive identity directly.\n     */\n    queryKey?: LiveQueryKey\n    /** Override the nearest DbProvider for this query. */\n    client?: DbClient\n  }\n\nexport function warnDeprecatedDepsArray(\n  hookName: `useLiveQuery` | `useLiveInfiniteQuery` = `useLiveQuery`,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_DEPRECATION_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedDepsCallsites.has(callsite)) {\n    return\n  }\n  warnedDepsCallsites.add(callsite)\n  const replacement =\n    hookName === `useLiveQuery`\n      ? `useLiveQuery({ query })`\n      : `useLiveInfiniteQuery(query, { queryKey })`\n  console.warn(\n    `[${hookName}] The dependency-array form is deprecated and will be removed in 1.0. Use ${replacement} instead. Provide queryKey only for functional/opaque queries or to avoid deriving identity from structured query IR on render.`,\n  )\n}\n\nfunction shouldWarnInDevelopment(disableEnvVar: string): boolean {\n  if (typeof process === `undefined`) {\n    return false\n  }\n\n  return (\n    process.env.NODE_ENV !== `production` && process.env[disableEnvVar] !== `1`\n  )\n}\n\nfunction getCurrentTime(): number {\n  return typeof performance !== `undefined` &&\n    typeof performance.now === `function`\n    ? performance.now()\n    : Date.now()\n}\n\nfunction getWarningCallsite(stackIndex: number): string {\n  const stack = new Error().stack ?? `unknown`\n  return stack.split(`\\n`)[stackIndex]?.trim() ?? stack\n}\n\nfunction warnDerivedIdentityHotPath(\n  profiler: DerivedIdentityProfiler,\n  durationMs: number,\n): void {\n  if (\n    profiler.warned ||\n    !shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n  ) {\n    return\n  }\n\n  const isSlowSingleRender =\n    durationMs >= DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS\n  const isHotRenderPath =\n    profiler.renderCount >= DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD &&\n    profiler.totalMs >= DERIVED_IDENTITY_TOTAL_WARN_MS\n\n  if (!isSlowSingleRender && !isHotRenderPath) {\n    return\n  }\n\n  const callsite = getWarningCallsite(5)\n  if (warnedDerivedIdentityCallsites.has(callsite)) {\n    profiler.warned = true\n    return\n  }\n\n  warnedDerivedIdentityCallsites.add(callsite)\n  profiler.warned = true\n\n  const reason = isSlowSingleRender\n    ? `one render took ${durationMs.toFixed(1)}ms`\n    : `${profiler.renderCount} renders took ${profiler.totalMs.toFixed(1)}ms`\n\n  console.warn(\n    `[useLiveQuery] Deriving live query identity from structured query IR is running on a hot render path (${reason}, max ${profiler.maxMs.toFixed(1)}ms). ` +\n      `Provide an explicit queryKey to skip rebuilding and hashing the IR on every render: useLiveQuery({ queryKey: [...], query }).`,\n  )\n}\n\nfunction getExplicitQueryKey(value: unknown): LiveQueryKey | undefined {\n  return value &&\n    typeof value === `object` &&\n    Array.isArray((value as { queryKey?: unknown }).queryKey)\n    ? (value as { queryKey: LiveQueryKey }).queryKey\n    : undefined\n}\n\nfunction getExplicitDbClient(value: unknown): DbClient | undefined {\n  return value &&\n    typeof value === `object` &&\n    `client` in value &&\n    (value as { client?: unknown }).client !== undefined\n    ? (value as { client: DbClient }).client\n    : undefined\n}\n\nexport function prepareQueryValue(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): unknown {\n  return prepareLiveQueryValue(value, dbClient, deferredCollections)\n}\n\ntype DerivedQueryPreparation =\n  | {\n      status: `hashable`\n      value: unknown\n      identityDeps: Array<unknown>\n    }\n  | {\n      status: `unhashable`\n      value: unknown\n      error: UnhashableQueryIRError\n    }\n\nexport function prepareDerivedQuery(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  profiler: DerivedIdentityProfiler,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): DerivedQueryPreparation {\n  const shouldProfile = shouldWarnInDevelopment(\n    `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`,\n  )\n  const start = shouldProfile ? getCurrentTime() : 0\n  const preparedValue = prepareQueryValue(value, dbClient, deferredCollections)\n\n  try {\n    const identity = getPreparedLiveQueryIdentity(preparedValue)\n    return {\n      status: `hashable`,\n      value: preparedValue,\n      identityDeps: [`derived`, identity],\n    }\n  } catch (error) {\n    if (error instanceof UnhashableQueryIRError) {\n      return { status: `unhashable`, value: preparedValue, error }\n    }\n\n    throw error\n  } finally {\n    if (shouldProfile) {\n      const durationMs = getCurrentTime() - start\n      profiler.renderCount += 1\n      profiler.totalMs += durationMs\n      profiler.maxMs = Math.max(profiler.maxMs, durationMs)\n      warnDerivedIdentityHotPath(profiler, durationMs)\n    }\n  }\n}\n\nexport function warnUnhashableDerivedIdentity(\n  error: UnhashableQueryIRError,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedUnhashableIdentityCallsites.has(callsite)) {\n    return\n  }\n  warnedUnhashableIdentityCallsites.add(callsite)\n\n  console.warn(\n    `[useLiveQuery] This query cannot derive a stable identity because ${error.reason} at ${error.path}. ` +\n      `It will keep the legacy mount-stable behavior for now. Add queryKey: [...] to make captured values reactive. ` +\n      `Unhashable queries without queryKey will throw in 1.0.`,\n  )\n}\n\nfunction createCollectionFromPreparedQuery(value: unknown) {\n  if (value === undefined || value === null) {\n    return null\n  }\n\n  if (isCollection(value)) {\n    value.startSyncImmediate()\n    return value\n  }\n\n  if (value instanceof BaseQueryBuilder) {\n    return createLiveQueryCollection({\n      query: value,\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n    })\n  }\n\n  if (typeof value === `object`) {\n    return createLiveQueryCollection({\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n      ...(value as LiveQueryCollectionConfig<any>),\n    })\n  }\n\n  throw new Error(\n    `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof value}`,\n  )\n}\n\n/**\n * Create a live query using a query function.\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Prefer config object syntax\n * const { data, isLoading } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ todos: todosCollection })\n *      .where(({ todos }) => eq(todos.completed, false))\n *      .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * })\n *\n *  @example\n * // Single result query\n * const { data } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => eq(todos.id, 1))\n *          .findOne()\n * })\n *\n * @example\n * // Structured captured values are included in derived query identity\n * const { data, state } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n * })\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ issues: issueCollection })\n *      .join({ persons: personCollection }, ({ issues, persons }) =>\n *        eq(issues.userId, persons.id)\n *      )\n *      .select(({ issues, persons }) => ({\n *        id: issues.id,\n *        title: issues.title,\n *        userName: persons.name\n *      }))\n * })\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todoCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept query function that always returns QueryBuilder\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled if always returns QueryBuilder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true if always returns QueryBuilder\n}\n\n// Overload 2: Accept query function that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => QueryBuilder<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 3: Accept query function that can return LiveQueryCollectionConfig\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => LiveQueryCollectionConfig<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 4: Accept query function that can return Collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => Collection<TResult, TKey, TUtils> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<TKey, TResult> | undefined\n  data: Array<TResult> | undefined\n  collection: Collection<TResult, TKey, TUtils> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 5: Accept query function that can return all types\nexport function useLiveQuery<\n  TContext extends Context,\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) =>\n    | QueryBuilder<TContext>\n    | LiveQueryCollectionConfig<TContext>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n    | null,\n  deps?: Array<unknown>,\n): {\n  state:\n    | Map<string | number, GetResult<TContext>>\n    | Map<TKey, TResult>\n    | undefined\n  data: InferResultType<TContext> | Array<TResult> | undefined\n  collection:\n    | Collection<GetResult<TContext>, string | number, {}>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({\n *   query: queryBuilder,\n * })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 6: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: UseLiveQueryConfig<TContext>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled for config objects\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for config objects\n}\n\n// Overload 7: Accept config object with legacy deps\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled for config objects\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for config objects\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 8: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Overload 9: Accept pre-created live query collection with singleResult: true\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: TResult | undefined\n  collection: Collection<TResult, TKey, TUtils> & SingleResult\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps?: Array<unknown>,\n) {\n  const contextDbClient = useOptionalDbClient()\n  // Check if it's already a collection\n  const inputIsCollection = isCollection(configOrQueryOrCollection)\n  const dbClient = inputIsCollection\n    ? contextDbClient\n    : (getExplicitDbClient(configOrQueryOrCollection) ?? contextDbClient)\n  const resolvedDeps = deps ?? []\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<Collection<object, string | number, {}> | null>(\n    null,\n  )\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<unknown>(null)\n  const clientRef = useRef(dbClient)\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const deferredCollectionsRef = useRef(\n    new Set<CollectionImpl<any, string | number, any, any, any>>(),\n  )\n  const observerRef = useRef<LiveQueryObserver<object, string | number> | null>(\n    null,\n  )\n  const queryHashRef = useRef<string | undefined>(undefined)\n  const identityErrorRef = useRef<UnhashableQueryIRError | undefined>(undefined)\n\n  const queryKey = !inputIsCollection\n    ? getExplicitQueryKey(configOrQueryOrCollection)\n    : undefined\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown>\n  let streamIdentity: unknown = undefined\n  let identityError: UnhashableQueryIRError | undefined\n\n  if (queryKey) {\n    identityDeps = queryKey\n    streamIdentity = [`queryKey`, queryKey]\n  } else if (deps !== undefined) {\n    identityDeps = resolvedDeps\n    try {\n      preparedQueryValue = prepareQueryValue(\n        configOrQueryOrCollection,\n        dbClient,\n        deferredCollectionsRef.current,\n      )\n      streamIdentity = [\n        `deps`,\n        resolvedDeps,\n        getPreparedLiveQueryIdentity(preparedQueryValue),\n      ]\n    } catch (error) {\n      if (!(error instanceof UnhashableQueryIRError)) throw error\n      warnUnhashableDerivedIdentity(error)\n      identityError = error\n    }\n  } else if (inputIsCollection) {\n    identityDeps = []\n    streamIdentity = [`collection`, configOrQueryOrCollection.id]\n  } else {\n    const preparation = prepareDerivedQuery(\n      configOrQueryOrCollection,\n      dbClient,\n      derivedIdentityProfilerRef.current,\n      deferredCollectionsRef.current,\n    )\n    preparedQueryValue = preparation.value\n    if (preparation.status === `hashable`) {\n      identityDeps = preparation.identityDeps\n      streamIdentity = preparation.identityDeps\n    } else {\n      warnUnhashableDerivedIdentity(preparation.error)\n      identityDeps = legacyUnhashableIdentityRef.current\n      identityError = preparation.error\n    }\n  }\n\n  let queryHash: string | undefined\n  if (streamIdentity !== undefined) {\n    try {\n      queryHash = getStableValueHash(streamIdentity, `queryKey`)\n    } catch (error) {\n      if (error instanceof UnhashableQueryIRError) {\n        if (queryKey !== undefined) throw error\n        identityError = error\n      } else {\n        throw error\n      }\n    }\n  }\n\n  if (deps !== undefined) {\n    warnDeprecatedDepsArray()\n  }\n\n  const identityChanged =\n    depsRef.current === null ||\n    (deps !== undefined\n      ? depsRef.current.length !== identityDeps.length ||\n        depsRef.current.some((dep, index) => dep !== identityDeps[index])\n      : !deepEquals(depsRef.current, identityDeps))\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (inputIsCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!inputIsCollection && (clientRef.current !== dbClient || identityChanged))\n\n  const resumeDeferredCollections = () => {\n    for (const collection of deferredCollectionsRef.current) {\n      collection._resumeSyncStart()\n    }\n    deferredCollectionsRef.current.clear()\n  }\n\n  if (needsNewCollection) {\n    if (inputIsCollection) {\n      // Warn when passing a collection directly with on-demand sync mode\n      // In on-demand mode, data is only loaded when queries with predicates request it\n      // Passing the collection directly doesn't provide any predicates, so no data loads\n      const syncMode = (\n        configOrQueryOrCollection as { config?: { syncMode?: string } }\n      ).config?.syncMode\n      if (\n        syncMode === `on-demand` &&\n        shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n      ) {\n        console.warn(\n          `[useLiveQuery] Warning: Passing a collection with syncMode \"on-demand\" directly to useLiveQuery ` +\n            `will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.\\n\\n` +\n            `Instead, use a query builder function:\\n` +\n            `  const { data } = useLiveQuery({ query: (q) => q.from({ c: myCollection }).select(({ c }) => c) })\\n\\n` +\n            `Or switch to syncMode \"eager\" if you want all data to sync automatically.`,\n        )\n      }\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      if (preparedQueryValue === unpreparedQueryValue) {\n        preparedQueryValue = prepareQueryValue(\n          configOrQueryOrCollection,\n          dbClient,\n          deferredCollectionsRef.current,\n        )\n      }\n      collectionRef.current = createCollectionFromPreparedQuery(\n        preparedQueryValue,\n      ) as Collection<object, string | number, {}>\n      configRef.current = configOrQueryOrCollection\n      depsRef.current = [...identityDeps]\n    }\n    clientRef.current = dbClient\n    queryHashRef.current = queryHash\n    identityErrorRef.current = identityError\n  }\n\n  // Recreate the observer when the underlying collection changes. The observer\n  // is not disposed explicitly here or on unmount: `useSyncExternalStore`\n  // unsubscribes it when the subscribe changes or the component unmounts, which\n  // detaches the collection subscription; the observer is then GC'd. (An unmount\n  // effect that disposed it would misfire under StrictMode/offscreen effect\n  // replay, leaving a disposed observer in the ref.)\n  if (needsNewCollection) {\n    // Defer the initial notify: useSyncExternalStore must not be notified\n    // synchronously during subscribe.\n    // Wholesale mode: React re-reads getSnapshot() on notify, keeps the\n    // hook's pre-observer loading policy, and — because wholesale delivers\n    // nothing synchronously during subscribe — never notifies\n    // useSyncExternalStore inside its own subscribe call.\n    observerRef.current = createLiveQueryObserver(collectionRef.current, {\n      mode: `wholesale`,\n      client: dbClient,\n      queryHash: queryHashRef.current,\n      onPreload: resumeDeferredCollections,\n    })\n  }\n  const observer = observerRef.current!\n\n  // Stable subscribe bound to the current observer; the observer owns the\n  // subscription, ready-race, and disposal.\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = observer.subscribe(() => onStoreChange())\n      resumeDeferredCollections()\n      return unsubscribe\n    }\n  }\n\n  const returned = useSyncExternalStore(\n    subscribeRef.current,\n    () => observer.getSnapshot(),\n    () => observer.getServerSnapshot(),\n  )\n  setLiveQueryResultInfo(returned, {\n    client: dbClient,\n    queryHash: queryHashRef.current,\n    identityError: identityErrorRef.current,\n    observer,\n  })\n  return returned as any\n}\n"],"names":["useRef","useSyncExternalStore","setLiveQueryResultInfo"],"mappings":";;;;;;;AAgCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAuBO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AACA;AAIA;AAAQ;AAC8F;AAExG;AAEA;AACE;AACE;AAAO;AAGT;AAGF;AAEA;AACE;AAIF;AAEA;AACE;AACA;AAAmB;AACrB;AAEA;AAIE;AAIE;AAAA;AAGF;AAEA;AAIA;AACE;AAAA;AAGF;AACA;AACE;AACA;AAAA;AAGF;AACA;AAEA;AAIA;AAAQ;AAC2I;AAGrJ;AAEA;AACE;AAKF;AAEA;AACE;AAMF;AAEO;AAKL;AACF;AAcO;AAML;AAAsB;AACpB;AAEF;AACA;AAEA;AACE;AACA;AAAO;AACG;AACD;AAC2B;AAAA;AAGpC;AACE;AAAqD;AAGvD;AAAM;AAEN;AACE;AACA;AACA;AACA;AACA;AAA+C;AACjD;AAEJ;AAEO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AAEA;AAAQ;AAC4F;AAItG;AAEA;AACE;AACE;AAAO;AAGT;AACE;AACA;AAAO;AAGT;AACE;AAAiC;AACxB;AACI;AACH;AACT;AAGH;AACE;AAAiC;AACpB;AACH;AACJ;AACL;AAGH;AAAU;AACyH;AAErI;AAwTO;AAIL;AAEA;AACA;AAGA;AAGA;AAAsBA;AACpB;AAEF;AACA;AACA;AACA;AAA2D;AACzD;AAGF;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA+BA;AACzB;AAEN;AAAoBA;AAClB;AAEF;AACA;AAEA;AAGA;AAEA;AACA;AACA;AAEA;AACE;AACA;AAAsC;AAEtC;AACA;AACE;AAAqB;AACnB;AACA;AACuB;AAEzB;AAAiB;AACf;AACA;AAC+C;AAAA;AAGjD;AACA;AACA;AAAgB;AAClB;AAEA;AACA;AAA4D;AAE5D;AAAoB;AAClB;AACA;AAC2B;AACJ;AAEzB;AACA;AACE;AACA;AAA6B;AAE7B;AACA;AACA;AAA4B;AAC9B;AAGF;AACA;AACE;AACE;AAAyD;AAEzD;AACE;AACA;AAAgB;AAEhB;AAAM;AACR;AACF;AAGF;AACE;AAAA;AAGF;AAQA;AAKA;AACE;AACE;AAAW;AAEb;AAA+B;AAGjC;AACE;AAIE;AAGA;AAIE;AAAQ;;AACN;AAAA;;AAAA;AAAA;AAAA;AAQJ;AACA;AACA;AAAoB;AAEpB;AACE;AAAqB;AACnB;AACA;AACuB;AAAA;AAG3B;AAAwB;AACtB;AAEF;AACA;AAAkC;AAEpC;AACA;AACA;AAA2B;AAS7B;AAOE;AAAqE;AAC7D;AACE;AACgB;AACb;AACZ;AAEH;AAIA;AAGA;AACE;AACE;AACA;AACA;AAAO;AACT;AAGF;AAAiBC;AACF;AACE;AACA;AAEjBC;AAAiC;AACvB;AACgB;AACQ;AAChC;AAEF;AACF;;;;;;"}
+{"version":3,"file":"useLiveQuery.cjs","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["'use client'\n\nimport { useRef, useSyncExternalStore } from 'react'\nimport {\n  BaseQueryBuilder,\n  UnhashableQueryIRError,\n  createLiveQueryCollection,\n  createLiveQueryObserver,\n  deepEquals,\n  getPreparedLiveQueryIdentity,\n  getStableValueHash,\n  isCollection,\n  prepareLiveQueryValue,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport { setLiveQueryResultInfo } from './live-query-internals'\nimport type {\n  Collection,\n  CollectionImpl,\n  CollectionStatus,\n  Context,\n  DbClient,\n  GetResult,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  LiveQueryObserver,\n  NonSingleResult,\n  QueryBuilder,\n  SingleResult,\n} from '@tanstack/db'\n\nconst DEFAULT_GC_TIME_MS = 1 // Live queries created by useLiveQuery are cleaned up immediately (0 disables GC)\nconst DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS = 16\nconst DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD = 10\nconst DERIVED_IDENTITY_TOTAL_WARN_MS = 50\nconst warnedDepsCallsites = new Set<string>()\nconst warnedDerivedIdentityCallsites = new Set<string>()\nconst warnedUnhashableIdentityCallsites = new Set<string>()\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type DerivedIdentityProfiler = {\n  renderCount: number\n  totalMs: number\n  maxMs: number\n  warned: boolean\n}\n\nexport type UseLiveQueryStatus = CollectionStatus | `disabled`\nexport type LiveQueryKey = ReadonlyArray<unknown>\ntype UseLiveQueryConfigOptions<TContext extends Context> = Omit<\n  LiveQueryCollectionConfig<TContext>,\n  `query`\n> & {\n  /**\n   * Explicit identity for queries that contain opaque functional variants or\n   * are hot enough that deriving identity from structured IR is too expensive.\n   * Structured queries should omit this so DB can derive identity directly.\n   */\n  queryKey?: LiveQueryKey\n  /** Override the nearest DbProvider for this query. */\n  client?: DbClient\n}\n\ntype ConfiguredQueryBuilder<TContext extends Context> = Extract<\n  LiveQueryCollectionConfig<TContext>[`query`],\n  QueryBuilder<TContext>\n>\n\nexport type UseLiveQueryConfig<TContext extends Context> =\n  UseLiveQueryConfigOptions<TContext> &\n    Pick<LiveQueryCollectionConfig<TContext>, `query`>\n\nexport type ConditionalUseLiveQueryConfig<TContext extends Context> =\n  UseLiveQueryConfigOptions<TContext> & {\n    query:\n      | ConfiguredQueryBuilder<TContext>\n      | ((\n          q: InitialQueryBuilder,\n        ) => ConfiguredQueryBuilder<TContext> | undefined | null)\n  }\n\nexport function warnDeprecatedDepsArray(\n  hookName: `useLiveQuery` | `useLiveInfiniteQuery` = `useLiveQuery`,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_DEPRECATION_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedDepsCallsites.has(callsite)) {\n    return\n  }\n  warnedDepsCallsites.add(callsite)\n  const replacement =\n    hookName === `useLiveQuery`\n      ? `useLiveQuery({ query })`\n      : `useLiveInfiniteQuery(query, { queryKey })`\n  console.warn(\n    `[${hookName}] The dependency-array form is deprecated and will be removed in 1.0. Use ${replacement} instead. Provide queryKey only for functional/opaque queries or to avoid deriving identity from structured query IR on render.`,\n  )\n}\n\nfunction shouldWarnInDevelopment(disableEnvVar: string): boolean {\n  if (typeof process === `undefined`) {\n    return false\n  }\n\n  return (\n    process.env.NODE_ENV !== `production` && process.env[disableEnvVar] !== `1`\n  )\n}\n\nfunction getCurrentTime(): number {\n  return typeof performance !== `undefined` &&\n    typeof performance.now === `function`\n    ? performance.now()\n    : Date.now()\n}\n\nfunction getWarningCallsite(stackIndex: number): string {\n  const stack = new Error().stack ?? `unknown`\n  return stack.split(`\\n`)[stackIndex]?.trim() ?? stack\n}\n\nfunction warnDerivedIdentityHotPath(\n  profiler: DerivedIdentityProfiler,\n  durationMs: number,\n): void {\n  if (\n    profiler.warned ||\n    !shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n  ) {\n    return\n  }\n\n  const isSlowSingleRender =\n    durationMs >= DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS\n  const isHotRenderPath =\n    profiler.renderCount >= DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD &&\n    profiler.totalMs >= DERIVED_IDENTITY_TOTAL_WARN_MS\n\n  if (!isSlowSingleRender && !isHotRenderPath) {\n    return\n  }\n\n  const callsite = getWarningCallsite(5)\n  if (warnedDerivedIdentityCallsites.has(callsite)) {\n    profiler.warned = true\n    return\n  }\n\n  warnedDerivedIdentityCallsites.add(callsite)\n  profiler.warned = true\n\n  const reason = isSlowSingleRender\n    ? `one render took ${durationMs.toFixed(1)}ms`\n    : `${profiler.renderCount} renders took ${profiler.totalMs.toFixed(1)}ms`\n\n  console.warn(\n    `[useLiveQuery] Deriving live query identity from structured query IR is running on a hot render path (${reason}, max ${profiler.maxMs.toFixed(1)}ms). ` +\n      `Provide an explicit queryKey to skip rebuilding and hashing the IR on every render: useLiveQuery({ queryKey: [...], query }).`,\n  )\n}\n\nfunction getExplicitQueryKey(value: unknown): LiveQueryKey | undefined {\n  return value &&\n    typeof value === `object` &&\n    Array.isArray((value as { queryKey?: unknown }).queryKey)\n    ? (value as { queryKey: LiveQueryKey }).queryKey\n    : undefined\n}\n\nfunction getExplicitDbClient(value: unknown): DbClient | undefined {\n  return value &&\n    typeof value === `object` &&\n    `client` in value &&\n    (value as { client?: unknown }).client !== undefined\n    ? (value as { client: DbClient }).client\n    : undefined\n}\n\nexport function prepareQueryValue(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): unknown {\n  return prepareLiveQueryValue(value, dbClient, deferredCollections)\n}\n\ntype DerivedQueryPreparation =\n  | {\n      status: `hashable`\n      value: unknown\n      identityDeps: Array<unknown>\n    }\n  | {\n      status: `unhashable`\n      value: unknown\n      error: UnhashableQueryIRError\n    }\n\nexport function prepareDerivedQuery(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  profiler: DerivedIdentityProfiler,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): DerivedQueryPreparation {\n  const shouldProfile = shouldWarnInDevelopment(\n    `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`,\n  )\n  const start = shouldProfile ? getCurrentTime() : 0\n  const preparedValue = prepareQueryValue(value, dbClient, deferredCollections)\n\n  try {\n    const identity = getPreparedLiveQueryIdentity(preparedValue)\n    return {\n      status: `hashable`,\n      value: preparedValue,\n      identityDeps: [`derived`, identity],\n    }\n  } catch (error) {\n    if (error instanceof UnhashableQueryIRError) {\n      return { status: `unhashable`, value: preparedValue, error }\n    }\n\n    throw error\n  } finally {\n    if (shouldProfile) {\n      const durationMs = getCurrentTime() - start\n      profiler.renderCount += 1\n      profiler.totalMs += durationMs\n      profiler.maxMs = Math.max(profiler.maxMs, durationMs)\n      warnDerivedIdentityHotPath(profiler, durationMs)\n    }\n  }\n}\n\nexport function warnUnhashableDerivedIdentity(\n  error: UnhashableQueryIRError,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedUnhashableIdentityCallsites.has(callsite)) {\n    return\n  }\n  warnedUnhashableIdentityCallsites.add(callsite)\n\n  console.warn(\n    `[useLiveQuery] This query cannot derive a stable identity because ${error.reason} at ${error.path}. ` +\n      `It will keep the legacy mount-stable behavior for now. Add queryKey: [...] to make captured values reactive. ` +\n      `Unhashable queries without queryKey will throw in 1.0.`,\n  )\n}\n\nfunction createCollectionFromPreparedQuery(value: unknown) {\n  if (value === undefined || value === null) {\n    return null\n  }\n\n  if (isCollection(value)) {\n    value.startSyncImmediate()\n    return value\n  }\n\n  if (value instanceof BaseQueryBuilder) {\n    return createLiveQueryCollection({\n      query: value,\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n    })\n  }\n\n  if (typeof value === `object`) {\n    return createLiveQueryCollection({\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n      ...(value as LiveQueryCollectionConfig<any>),\n    })\n  }\n\n  throw new Error(\n    `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof value}`,\n  )\n}\n\n/**\n * Create a live query using a query function.\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Prefer config object syntax\n * const { data, isLoading } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ todos: todosCollection })\n *      .where(({ todos }) => eq(todos.completed, false))\n *      .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * })\n *\n *  @example\n * // Single result query\n * const { data } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => eq(todos.id, 1))\n *          .findOne()\n * })\n *\n * @example\n * // Structured captured values are included in derived query identity\n * const { data, state } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n * })\n *\n * @example\n * // Return undefined or null to disable a query\n * const { data, isEnabled } = useLiveQuery({\n *   query: (q) => {\n *     if (!userId) return undefined\n *     return q.from({ todos: todosCollection })\n *             .where(({ todos }) => eq(todos.userId, userId))\n *   },\n * })\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ issues: issueCollection })\n *      .join({ persons: personCollection }, ({ issues, persons }) =>\n *        eq(issues.userId, persons.id)\n *      )\n *      .select(({ issues, persons }) => ({\n *        id: issues.id,\n *        title: issues.title,\n *        userName: persons.name\n *      }))\n * })\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todoCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept query function that always returns QueryBuilder\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled if always returns QueryBuilder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true if always returns QueryBuilder\n}\n\n// Overload 2: Accept query function that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => QueryBuilder<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 3: Accept query function that can return LiveQueryCollectionConfig\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => LiveQueryCollectionConfig<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 4: Accept query function that can return Collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => Collection<TResult, TKey, TUtils> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<TKey, TResult> | undefined\n  data: Array<TResult> | undefined\n  collection: Collection<TResult, TKey, TUtils> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 5: Accept query function that can return all types\nexport function useLiveQuery<\n  TContext extends Context,\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) =>\n    | QueryBuilder<TContext>\n    | LiveQueryCollectionConfig<TContext>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n    | null,\n  deps?: Array<unknown>,\n): {\n  state:\n    | Map<string | number, GetResult<TContext>>\n    | Map<TKey, TResult>\n    | undefined\n  data: InferResultType<TContext> | Array<TResult> | undefined\n  collection:\n    | Collection<GetResult<TContext>, string | number, {}>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({\n *   query: queryBuilder,\n * })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 6: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: UseLiveQueryConfig<TContext>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled when query always returns a builder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true when query always returns a builder\n}\n\n// Overload 7: Accept config object with a query that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  config: ConditionalUseLiveQueryConfig<TContext>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 8: Accept config object with legacy deps\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled when query always returns a builder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true when query always returns a builder\n}\n\n// Overload 9: Accept config object with legacy deps and a query that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  config: ConditionalUseLiveQueryConfig<TContext>,\n  deps: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 10: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Overload 10: Accept pre-created live query collection with singleResult: true\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: TResult | undefined\n  collection: Collection<TResult, TKey, TUtils> & SingleResult\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps?: Array<unknown>,\n) {\n  const contextDbClient = useOptionalDbClient()\n  // Check if it's already a collection\n  const inputIsCollection = isCollection(configOrQueryOrCollection)\n  const dbClient = inputIsCollection\n    ? contextDbClient\n    : (getExplicitDbClient(configOrQueryOrCollection) ?? contextDbClient)\n  const resolvedDeps = deps ?? []\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<Collection<object, string | number, {}> | null>(\n    null,\n  )\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<unknown>(null)\n  const clientRef = useRef(dbClient)\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const deferredCollectionsRef = useRef(\n    new Set<CollectionImpl<any, string | number, any, any, any>>(),\n  )\n  const observerRef = useRef<LiveQueryObserver<object, string | number> | null>(\n    null,\n  )\n  const queryHashRef = useRef<string | undefined>(undefined)\n  const identityErrorRef = useRef<UnhashableQueryIRError | undefined>(undefined)\n\n  const queryKey = !inputIsCollection\n    ? getExplicitQueryKey(configOrQueryOrCollection)\n    : undefined\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown>\n  let streamIdentity: unknown = undefined\n  let identityError: UnhashableQueryIRError | undefined\n\n  if (queryKey) {\n    identityDeps = queryKey\n    streamIdentity = [`queryKey`, queryKey]\n  } else if (deps !== undefined) {\n    identityDeps = resolvedDeps\n    try {\n      preparedQueryValue = prepareQueryValue(\n        configOrQueryOrCollection,\n        dbClient,\n        deferredCollectionsRef.current,\n      )\n      streamIdentity = [\n        `deps`,\n        resolvedDeps,\n        getPreparedLiveQueryIdentity(preparedQueryValue),\n      ]\n    } catch (error) {\n      if (!(error instanceof UnhashableQueryIRError)) throw error\n      warnUnhashableDerivedIdentity(error)\n      identityError = error\n    }\n  } else if (inputIsCollection) {\n    identityDeps = []\n    streamIdentity = [`collection`, configOrQueryOrCollection.id]\n  } else {\n    const preparation = prepareDerivedQuery(\n      configOrQueryOrCollection,\n      dbClient,\n      derivedIdentityProfilerRef.current,\n      deferredCollectionsRef.current,\n    )\n    preparedQueryValue = preparation.value\n    if (preparation.status === `hashable`) {\n      identityDeps = preparation.identityDeps\n      streamIdentity = preparation.identityDeps\n    } else {\n      warnUnhashableDerivedIdentity(preparation.error)\n      identityDeps = legacyUnhashableIdentityRef.current\n      identityError = preparation.error\n    }\n  }\n\n  let queryHash: string | undefined\n  if (streamIdentity !== undefined) {\n    try {\n      queryHash = getStableValueHash(streamIdentity, `queryKey`)\n    } catch (error) {\n      if (error instanceof UnhashableQueryIRError) {\n        if (queryKey !== undefined) throw error\n        identityError = error\n      } else {\n        throw error\n      }\n    }\n  }\n\n  if (deps !== undefined) {\n    warnDeprecatedDepsArray()\n  }\n\n  const identityChanged =\n    depsRef.current === null ||\n    (deps !== undefined\n      ? depsRef.current.length !== identityDeps.length ||\n        depsRef.current.some((dep, index) => dep !== identityDeps[index])\n      : !deepEquals(depsRef.current, identityDeps))\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (inputIsCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!inputIsCollection && (clientRef.current !== dbClient || identityChanged))\n\n  const resumeDeferredCollections = () => {\n    for (const collection of deferredCollectionsRef.current) {\n      collection._resumeSyncStart()\n    }\n    deferredCollectionsRef.current.clear()\n  }\n\n  if (needsNewCollection) {\n    if (inputIsCollection) {\n      // Warn when passing a collection directly with on-demand sync mode\n      // In on-demand mode, data is only loaded when queries with predicates request it\n      // Passing the collection directly doesn't provide any predicates, so no data loads\n      const syncMode = (\n        configOrQueryOrCollection as { config?: { syncMode?: string } }\n      ).config?.syncMode\n      if (\n        syncMode === `on-demand` &&\n        shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n      ) {\n        console.warn(\n          `[useLiveQuery] Warning: Passing a collection with syncMode \"on-demand\" directly to useLiveQuery ` +\n            `will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.\\n\\n` +\n            `Instead, use a query builder function:\\n` +\n            `  const { data } = useLiveQuery({ query: (q) => q.from({ c: myCollection }).select(({ c }) => c) })\\n\\n` +\n            `Or switch to syncMode \"eager\" if you want all data to sync automatically.`,\n        )\n      }\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      if (preparedQueryValue === unpreparedQueryValue) {\n        preparedQueryValue = prepareQueryValue(\n          configOrQueryOrCollection,\n          dbClient,\n          deferredCollectionsRef.current,\n        )\n      }\n      collectionRef.current = createCollectionFromPreparedQuery(\n        preparedQueryValue,\n      ) as Collection<object, string | number, {}>\n      configRef.current = configOrQueryOrCollection\n      depsRef.current = [...identityDeps]\n    }\n    clientRef.current = dbClient\n    queryHashRef.current = queryHash\n    identityErrorRef.current = identityError\n  }\n\n  // Recreate the observer when the underlying collection changes. The observer\n  // is not disposed explicitly here or on unmount: `useSyncExternalStore`\n  // unsubscribes it when the subscribe changes or the component unmounts, which\n  // detaches the collection subscription; the observer is then GC'd. (An unmount\n  // effect that disposed it would misfire under StrictMode/offscreen effect\n  // replay, leaving a disposed observer in the ref.)\n  if (needsNewCollection) {\n    // Defer the initial notify: useSyncExternalStore must not be notified\n    // synchronously during subscribe.\n    // Wholesale mode: React re-reads getSnapshot() on notify, keeps the\n    // hook's pre-observer loading policy, and — because wholesale delivers\n    // nothing synchronously during subscribe — never notifies\n    // useSyncExternalStore inside its own subscribe call.\n    observerRef.current = createLiveQueryObserver(collectionRef.current, {\n      mode: `wholesale`,\n      client: dbClient,\n      queryHash: queryHashRef.current,\n      onPreload: resumeDeferredCollections,\n    })\n  }\n  const observer = observerRef.current!\n\n  // Stable subscribe bound to the current observer; the observer owns the\n  // subscription, ready-race, and disposal.\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = observer.subscribe(() => onStoreChange())\n      resumeDeferredCollections()\n      return unsubscribe\n    }\n  }\n\n  const returned = useSyncExternalStore(\n    subscribeRef.current,\n    () => observer.getSnapshot(),\n    () => observer.getServerSnapshot(),\n  )\n  setLiveQueryResultInfo(returned, {\n    client: dbClient,\n    queryHash: queryHashRef.current,\n    identityError: identityErrorRef.current,\n    observer,\n  })\n  return returned as any\n}\n"],"names":["useRef","useSyncExternalStore","setLiveQueryResultInfo"],"mappings":";;;;;;;AAgCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AA2CO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AACA;AAIA;AAAQ;AAC8F;AAExG;AAEA;AACE;AACE;AAAO;AAGT;AAGF;AAEA;AACE;AAIF;AAEA;AACE;AACA;AAAmB;AACrB;AAEA;AAIE;AAIE;AAAA;AAGF;AAEA;AAIA;AACE;AAAA;AAGF;AACA;AACE;AACA;AAAA;AAGF;AACA;AAEA;AAIA;AAAQ;AAC2I;AAGrJ;AAEA;AACE;AAKF;AAEA;AACE;AAMF;AAEO;AAKL;AACF;AAcO;AAML;AAAsB;AACpB;AAEF;AACA;AAEA;AACE;AACA;AAAO;AACG;AACD;AAC2B;AAAA;AAGpC;AACE;AAAqD;AAGvD;AAAM;AAEN;AACE;AACA;AACA;AACA;AACA;AAA+C;AACjD;AAEJ;AAEO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AAEA;AAAQ;AAC4F;AAItG;AAEA;AACE;AACE;AAAO;AAGT;AACE;AACA;AAAO;AAGT;AACE;AAAiC;AACxB;AACI;AACH;AACT;AAGH;AACE;AAAiC;AACpB;AACH;AACJ;AACL;AAGH;AAAU;AACyH;AAErI;AAmWO;AAIL;AAEA;AACA;AAGA;AAGA;AAAsBA;AACpB;AAEF;AACA;AACA;AACA;AAA2D;AACzD;AAGF;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA+BA;AACzB;AAEN;AAAoBA;AAClB;AAEF;AACA;AAEA;AAGA;AAEA;AACA;AACA;AAEA;AACE;AACA;AAAsC;AAEtC;AACA;AACE;AAAqB;AACnB;AACA;AACuB;AAEzB;AAAiB;AACf;AACA;AAC+C;AAAA;AAGjD;AACA;AACA;AAAgB;AAClB;AAEA;AACA;AAA4D;AAE5D;AAAoB;AAClB;AACA;AAC2B;AACJ;AAEzB;AACA;AACE;AACA;AAA6B;AAE7B;AACA;AACA;AAA4B;AAC9B;AAGF;AACA;AACE;AACE;AAAyD;AAEzD;AACE;AACA;AAAgB;AAEhB;AAAM;AACR;AACF;AAGF;AACE;AAAA;AAGF;AAQA;AAKA;AACE;AACE;AAAW;AAEb;AAA+B;AAGjC;AACE;AAIE;AAGA;AAIE;AAAQ;;AACN;AAAA;;AAAA;AAAA;AAAA;AAQJ;AACA;AACA;AAAoB;AAEpB;AACE;AAAqB;AACnB;AACA;AACuB;AAAA;AAG3B;AAAwB;AACtB;AAEF;AACA;AAAkC;AAEpC;AACA;AACA;AAA2B;AAS7B;AAOE;AAAqE;AAC7D;AACE;AACgB;AACb;AACZ;AAEH;AAIA;AAGA;AACE;AACE;AACA;AACA;AAAO;AACT;AAGF;AAAiBC;AACF;AACE;AACA;AAEjBC;AAAiC;AACvB;AACgB;AACQ;AAChC;AAEF;AACF;;;;;;"}

package/dist/cjs/useLiveQuery.d.cts

@@ -7,7 +7,7 @@ export type DerivedIdentityProfiler = {
 };
 export type UseLiveQueryStatus = CollectionStatus | `disabled`;
 export type LiveQueryKey = ReadonlyArray<unknown>;
-export type UseLiveQueryConfig<TContext extends Context> = LiveQueryCollectionConfig<TContext> & {
+type UseLiveQueryConfigOptions<TContext extends Context> = Omit<LiveQueryCollectionConfig<TContext>, `query`> & {
     /**
      * Explicit identity for queries that contain opaque functional variants or
      * are hot enough that deriving identity from structured IR is too expensive.
@@ -17,6 +17,11 @@ export type UseLiveQueryConfig<TContext extends Context> = LiveQueryCollectionCo
     /** Override the nearest DbProvider for this query. */
     client?: DbClient;
 };
+type ConfiguredQueryBuilder<TContext extends Context> = Extract<LiveQueryCollectionConfig<TContext>[`query`], QueryBuilder<TContext>>;
+export type UseLiveQueryConfig<TContext extends Context> = UseLiveQueryConfigOptions<TContext> & Pick<LiveQueryCollectionConfig<TContext>, `query`>;
+export type ConditionalUseLiveQueryConfig<TContext extends Context> = UseLiveQueryConfigOptions<TContext> & {
+    query: ConfiguredQueryBuilder<TContext> | ((q: InitialQueryBuilder) => ConfiguredQueryBuilder<TContext> | undefined | null);
+};
 export declare function warnDeprecatedDepsArray(hookName?: `useLiveQuery` | `useLiveInfiniteQuery`): void;
 export declare function prepareQueryValue(value: unknown, dbClient: DbClient | undefined, deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>): unknown;
 type DerivedQueryPreparation = {
@@ -60,6 +65,16 @@ export declare function warnUnhashableDerivedIdentity(error: UnhashableQueryIREr
  * })
  *
  * @example
+ * // Return undefined or null to disable a query
+ * const { data, isEnabled } = useLiveQuery({
+ *   query: (q) => {
+ *     if (!userId) return undefined
+ *     return q.from({ todos: todosCollection })
+ *             .where(({ todos }) => eq(todos.userId, userId))
+ *   },
+ * })
+ *
+ * @example
  * // Join pattern
  * const { data } = useLiveQuery({
  *   query: (q) =>
@@ -196,6 +211,18 @@ export declare function useLiveQuery<TContext extends Context>(config: UseLiveQu
     isCleanedUp: boolean;
     isEnabled: true;
 };
+export declare function useLiveQuery<TContext extends Context>(config: ConditionalUseLiveQueryConfig<TContext>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: InferResultType<TContext> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
 export declare function useLiveQuery<TContext extends Context>(config: LiveQueryCollectionConfig<TContext>, deps?: Array<unknown>): {
     state: Map<string | number, GetResult<TContext>>;
     data: InferResultType<TContext>;
@@ -208,6 +235,18 @@ export declare function useLiveQuery<TContext extends Context>(config: LiveQuery
     isCleanedUp: boolean;
     isEnabled: true;
 };
+export declare function useLiveQuery<TContext extends Context>(config: ConditionalUseLiveQueryConfig<TContext>, deps: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: InferResultType<TContext> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
 /**
  * Subscribe to an existing live query collection
  * @param liveQueryCollection - Pre-created live query collection to subscribe to

package/dist/esm/index.d.ts

@@ -1,5 +1,5 @@
 export { useLiveQuery } from './useLiveQuery.js';
-export type { LiveQueryKey, UseLiveQueryConfig, UseLiveQueryStatus, } from './useLiveQuery.js';
+export type { ConditionalUseLiveQueryConfig, LiveQueryKey, UseLiveQueryConfig, UseLiveQueryStatus, } from './useLiveQuery.js';
 export * from './DbProvider.js';
 export * from './HydrationBoundary.js';
 export * from './useLiveSuspenseQuery.js';

package/dist/esm/useLiveInfiniteQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveInfiniteQuery.js","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["'use client'\n\nimport { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  assertLiveQueryWindowManyResult,\n  compareLiveQueryWindowDependencies,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  fetchNextLiveQueryWindowPage,\n  getLiveQueryWindowCollectionWarning,\n  getLiveQueryWindowInputKind,\n  normalizeLiveQueryWindowPageSize,\n  resolveLiveQueryWindowInput,\n  shouldPreserveLiveQueryWindowPageCount,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport {\n  prepareDerivedQuery,\n  prepareQueryValue,\n  warnDeprecatedDepsArray,\n  warnUnhashableDerivedIdentity,\n} from './useLiveQuery'\nimport type {\n  DerivedIdentityProfiler,\n  LiveQueryKey,\n  useLiveQuery,\n} from './useLiveQuery'\nimport type {\n  Collection,\n  CollectionImpl as CollectionImplType,\n  Context,\n  DbClient,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  /**\n   * Explicit identity for queries that contain opaque functional variants or\n   * are hot enough that deriving identity from structured IR is too expensive.\n   * Structured queries should omit this so DB can derive identity directly.\n   */\n  queryKey?: LiveQueryKey\n  /** Override the nearest DbProvider for this query. */\n  client?: DbClient\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => Promise<void>\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\ntype InfiniteQueryRenderState = {\n  inputKind: `collection` | `query`\n  inputCollection: Collection<any, any, any> | null\n  inputQuery: unknown\n  client: DbClient | undefined\n  identityMode: `collection` | `queryKey` | `legacyDeps` | `derived`\n  dependencies: Array<unknown> | null\n  pageSize: number\n  initialPageParam: number\n  collection: Collection<any, any, any>\n  controller: LiveQueryWindowController<any, any>\n  warning: string | null\n  warned: boolean\n  deferredCollections: Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >\n}\n\n/**\n * Create an infinite query using a query function with live updates.\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)\n  const initialPageParam = config.initialPageParam ?? 0\n  const contextDbClient = useOptionalDbClient()\n  const dbClient = config.client ?? contextDbClient\n\n  const inputIsCollection =\n    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`\n\n  const committedRef = useRef<InfiniteQueryRenderState | null>(null)\n  const committed = committedRef.current\n  const inputKind = inputIsCollection ? `collection` : `query`\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n  const deferredCollections = new Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >()\n\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown> = []\n  let identityMode: InfiniteQueryRenderState[`identityMode`] = `collection`\n\n  if (!inputIsCollection) {\n    if (config.queryKey !== undefined) {\n      identityMode = `queryKey`\n      identityDeps = config.queryKey\n    } else if (deps !== undefined) {\n      identityMode = `legacyDeps`\n      identityDeps = deps\n      warnDeprecatedDepsArray(`useLiveInfiniteQuery`)\n    } else if (\n      committed?.identityMode === `derived` &&\n      committed.inputQuery === queryFnOrCollection &&\n      committed.client === dbClient\n    ) {\n      identityMode = `derived`\n      identityDeps = committed.dependencies ?? []\n    } else {\n      identityMode = `derived`\n      const preparation = prepareDerivedQuery(\n        queryFnOrCollection,\n        dbClient,\n        derivedIdentityProfilerRef.current,\n        deferredCollections,\n      )\n      preparedQueryValue = preparation.value\n      if (preparation.status === `hashable`) {\n        identityDeps = preparation.identityDeps\n      } else {\n        warnUnhashableDerivedIdentity(preparation.error)\n        identityDeps = legacyUnhashableIdentityRef.current\n      }\n    }\n  }\n\n  const usesLegacyDeps =\n    !inputIsCollection && config.queryKey === undefined && deps !== undefined\n  const dependencyComparison = compareLiveQueryWindowDependencies(\n    committed?.dependencies,\n    identityDeps,\n  )\n  const sameClient = committed?.client === dbClient\n  const dependenciesChanged =\n    !inputIsCollection &&\n    (!sameClient ||\n      (usesLegacyDeps\n        ? dependencyComparison.changed\n        : !dependencyComparison.structurallyEqual))\n  const dependenciesStructurallyEqual =\n    usesLegacyDeps && sameClient && dependencyComparison.structurallyEqual\n  const needsNewCollection =\n    committed === null ||\n    committed.inputKind !== inputKind ||\n    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    committed === null ||\n    committed.pageSize !== pageSize ||\n    committed.initialPageParam !== initialPageParam\n  const needsNewController =\n    committed === null || needsNewCollection || pageShapeChanged\n\n  let renderState = committed\n  if (needsNewController) {\n    let collection = committed?.collection\n    let warning: string | null = null\n\n    if (needsNewCollection) {\n      let inputValue = queryFnOrCollection\n      if (!inputIsCollection) {\n        if (preparedQueryValue === unpreparedQueryValue) {\n          preparedQueryValue = prepareQueryValue(\n            queryFnOrCollection,\n            dbClient,\n            deferredCollections,\n          )\n        }\n        inputValue = () => preparedQueryValue\n      }\n      const input = resolveLiveQueryWindowInput<TContext>(inputValue)\n      if (input.kind === `collection`) {\n        collection = input.collection\n      } else {\n        // Wrap the query with the first page's peek-ahead window; the controller\n        // grows the limit from here via setWindow.\n        collection = createLiveQueryCollection({\n          query: input.query.limit(pageSize + 1).offset(0),\n          // Construction happens during render. Synchronization starts only when\n          // useSyncExternalStore commits the controller subscription.\n          startSync: false,\n          gcTime: DEFAULT_GC_TIME_MS,\n        })\n      }\n    }\n\n    if (!collection) {\n      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)\n    }\n\n    if (inputIsCollection) {\n      warning =\n        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null\n    } else {\n      assertLiveQueryWindowManyResult(collection)\n    }\n\n    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({\n      hasPreviousController: committed !== null,\n      previousInputKind: committed?.inputKind,\n      inputKind,\n      sameCollection:\n        inputIsCollection && committed?.inputCollection === collection,\n      dependenciesChanged,\n      dependenciesStructurallyEqual,\n      pageShapeChanged,\n    })\n    const previousPageCount = committed\n      ? Math.max(1, committed.controller.getSnapshot().pages.length)\n      : 1\n    const initialPageCount = canPreservePageCount ? previousPageCount : 1\n    renderState = {\n      inputKind,\n      inputCollection: inputIsCollection ? collection : null,\n      inputQuery: inputIsCollection ? null : queryFnOrCollection,\n      client: dbClient,\n      identityMode,\n      dependencies: inputIsCollection ? null : [...identityDeps],\n      pageSize,\n      initialPageParam,\n      collection,\n      controller: createLiveQueryWindowController(collection, {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      }),\n      warning,\n      warned: false,\n      deferredCollections,\n    }\n  }\n  const currentRenderState = renderState!\n  const controller = currentRenderState.controller\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const unsubscribe = controller.subscribe(onStoreChange)\n      committedRef.current = currentRenderState\n      if (currentRenderState.warning && !currentRenderState.warned) {\n        currentRenderState.warned = true\n        console.warn(currentRenderState.warning)\n      }\n      for (const collection of currentRenderState.deferredCollections) {\n        collection._resumeSyncStart()\n      }\n      currentRenderState.deferredCollections.clear()\n      return unsubscribe\n    },\n    [controller, currentRenderState],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n\n  const fetchNextPage = useCallback(\n    () => fetchNextLiveQueryWindowPage(controller),\n    [controller],\n  )\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":[],"mappings":";;;;;AAwCA;AACA;AA2FO;AAKL;AACA;AACA;AACA;AAEA;AAGA;AACA;AACA;AACA;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA2D;AACzD;AAEF;AAIA;AAEA;AACA;AAEA;AACE;AACE;AACA;AAAsB;AAEtB;AACA;AACA;AAA8C;AAM9C;AACA;AAAyC;AAEzC;AACA;AAAoB;AAClB;AACA;AAC2B;AAC3B;AAEF;AACA;AACE;AAA2B;AAE3B;AACA;AAA2C;AAC7C;AACF;AAGF;AAEA;AAA6B;AAChB;AACX;AAEF;AACA;AAMA;AAEA;AAKA;AAIA;AAGA;AACA;AACE;AACA;AAEA;AACE;AACA;AACE;AACE;AAAqB;AACnB;AACA;AACA;AAAA;AAGJ;AAAmB;AAErB;AACA;AACE;AAAmB;AAInB;AAAuC;AACU;AAAA;AAAA;AAGpC;AACH;AACT;AACH;AAGF;AACE;AAAsE;AAGxE;AACE;AACmE;AAEnE;AAA0C;AAG5C;AAAoE;AAC7B;AACP;AAC9B;AAEsD;AACtD;AACA;AACA;AAEF;AAGA;AACA;AAAc;AACZ;AACkD;AACX;AAC/B;AACR;AACyD;AACzD;AACA;AACA;AACwD;AACtD;AACA;AACA;AACD;AACD;AACQ;AACR;AAAA;AAGJ;AACA;AAEA;AAAkB;AAEd;AACA;AACA;AACE;AACA;AAAuC;AAEzC;AACE;AAAW;AAEb;AACA;AAAO;AACT;AAC+B;AAEjC;AACA;AAEA;AAAsB;AACyB;AAClC;AAGb;AAAO;AACU;AACC;AACC;AACG;AACF;AACD;AACC;AACI;AAEX;AAEA;AACK;AACK;AACrB;AACsB;AACO;AACb;AAEpB;;;;"}
+{"version":3,"file":"useLiveInfiniteQuery.js","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["'use client'\n\nimport { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  assertLiveQueryWindowManyResult,\n  compareLiveQueryWindowDependencies,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  fetchNextLiveQueryWindowPage,\n  getLiveQueryWindowCollectionWarning,\n  getLiveQueryWindowInputKind,\n  normalizeLiveQueryWindowPageSize,\n  resolveLiveQueryWindowInput,\n  shouldPreserveLiveQueryWindowPageCount,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport {\n  prepareDerivedQuery,\n  prepareQueryValue,\n  warnDeprecatedDepsArray,\n  warnUnhashableDerivedIdentity,\n} from './useLiveQuery'\nimport type {\n  DerivedIdentityProfiler,\n  LiveQueryKey,\n  useLiveQuery,\n} from './useLiveQuery'\nimport type {\n  Collection,\n  CollectionImpl as CollectionImplType,\n  Context,\n  DbClient,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  /**\n   * Explicit identity for queries that contain opaque functional variants or\n   * are hot enough that deriving identity from structured IR is too expensive.\n   * Structured queries should omit this so DB can derive identity directly.\n   */\n  queryKey?: LiveQueryKey\n  /** Override the nearest DbProvider for this query. */\n  client?: DbClient\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => Promise<void>\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\ntype InfiniteQueryRenderState = {\n  inputKind: `collection` | `query`\n  inputCollection: Collection<any, any, any> | null\n  inputQuery: unknown\n  client: DbClient | undefined\n  identityMode: `collection` | `queryKey` | `legacyDeps` | `derived`\n  dependencies: Array<unknown> | null\n  pageSize: number\n  initialPageParam: number\n  collection: Collection<any, any, any>\n  controller: LiveQueryWindowController<any, any>\n  warning: string | null\n  warned: boolean\n  deferredCollections: Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >\n}\n\n/**\n * Create an infinite query using a query function with live updates.\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)\n  const initialPageParam = config.initialPageParam ?? 0\n  const contextDbClient = useOptionalDbClient()\n  const dbClient = config.client ?? contextDbClient\n\n  const inputIsCollection =\n    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`\n\n  const committedRef = useRef<InfiniteQueryRenderState | null>(null)\n  const committed = committedRef.current\n  const inputKind = inputIsCollection ? `collection` : `query`\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n  const deferredCollections = new Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >()\n\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown> = []\n  let identityMode: InfiniteQueryRenderState[`identityMode`] = `collection`\n\n  if (!inputIsCollection) {\n    if (config.queryKey !== undefined) {\n      identityMode = `queryKey`\n      identityDeps = config.queryKey\n    } else if (deps !== undefined) {\n      identityMode = `legacyDeps`\n      identityDeps = deps\n      warnDeprecatedDepsArray(`useLiveInfiniteQuery`)\n    } else if (\n      committed?.identityMode === `derived` &&\n      committed.inputQuery === queryFnOrCollection &&\n      committed.client === dbClient\n    ) {\n      identityMode = `derived`\n      identityDeps = committed.dependencies ?? []\n    } else {\n      identityMode = `derived`\n      const preparation = prepareDerivedQuery(\n        queryFnOrCollection,\n        dbClient,\n        derivedIdentityProfilerRef.current,\n        deferredCollections,\n      )\n      preparedQueryValue = preparation.value\n      if (preparation.status === `hashable`) {\n        identityDeps = preparation.identityDeps\n      } else {\n        warnUnhashableDerivedIdentity(preparation.error)\n        identityDeps = legacyUnhashableIdentityRef.current\n      }\n    }\n  }\n\n  const usesLegacyDeps =\n    !inputIsCollection && config.queryKey === undefined && deps !== undefined\n  const dependencyComparison = compareLiveQueryWindowDependencies(\n    committed?.dependencies,\n    identityDeps,\n  )\n  const sameClient = committed?.client === dbClient\n  const dependenciesChanged =\n    !inputIsCollection &&\n    (!sameClient ||\n      (usesLegacyDeps\n        ? dependencyComparison.changed\n        : !dependencyComparison.structurallyEqual))\n  const dependenciesStructurallyEqual =\n    usesLegacyDeps && sameClient && dependencyComparison.structurallyEqual\n  const needsNewCollection =\n    committed === null ||\n    committed.inputKind !== inputKind ||\n    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    committed === null ||\n    committed.pageSize !== pageSize ||\n    committed.initialPageParam !== initialPageParam\n  const needsNewController =\n    committed === null || needsNewCollection || pageShapeChanged\n\n  let renderState = committed\n  if (needsNewController) {\n    let collection = committed?.collection\n    let warning: string | null = null\n\n    if (needsNewCollection) {\n      let inputValue = queryFnOrCollection\n      if (!inputIsCollection) {\n        if (preparedQueryValue === unpreparedQueryValue) {\n          preparedQueryValue = prepareQueryValue(\n            queryFnOrCollection,\n            dbClient,\n            deferredCollections,\n          )\n        }\n        inputValue = () => preparedQueryValue\n      }\n      const input = resolveLiveQueryWindowInput<TContext>(inputValue)\n      if (input.kind === `collection`) {\n        collection = input.collection\n      } else {\n        // Wrap the query with the first page's peek-ahead window; the controller\n        // grows the limit from here via setWindow.\n        collection = createLiveQueryCollection({\n          query: input.query.limit(pageSize + 1).offset(0),\n          // Construction happens during render. Synchronization starts only when\n          // useSyncExternalStore commits the controller subscription.\n          startSync: false,\n          gcTime: DEFAULT_GC_TIME_MS,\n        })\n      }\n    }\n\n    if (!collection) {\n      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)\n    }\n\n    if (inputIsCollection) {\n      warning =\n        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null\n    } else {\n      assertLiveQueryWindowManyResult(collection)\n    }\n\n    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({\n      hasPreviousController: committed !== null,\n      previousInputKind: committed?.inputKind,\n      inputKind,\n      sameCollection:\n        inputIsCollection && committed?.inputCollection === collection,\n      dependenciesChanged,\n      dependenciesStructurallyEqual,\n      pageShapeChanged,\n    })\n    const previousPageCount = committed\n      ? Math.max(1, committed.controller.getSnapshot().pages.length)\n      : 1\n    const initialPageCount = canPreservePageCount ? previousPageCount : 1\n    renderState = {\n      inputKind,\n      inputCollection: inputIsCollection ? collection : null,\n      inputQuery: inputIsCollection ? null : queryFnOrCollection,\n      client: dbClient,\n      identityMode,\n      dependencies: inputIsCollection ? null : [...identityDeps],\n      pageSize,\n      initialPageParam,\n      collection,\n      controller: createLiveQueryWindowController(collection, {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      }),\n      warning,\n      warned: false,\n      deferredCollections,\n    }\n  }\n  const currentRenderState = renderState!\n  const controller = currentRenderState.controller\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const unsubscribe = controller.subscribe(onStoreChange)\n      committedRef.current = currentRenderState\n      if (currentRenderState.warning && !currentRenderState.warned) {\n        currentRenderState.warned = true\n        console.warn(currentRenderState.warning)\n      }\n      for (const collection of currentRenderState.deferredCollections) {\n        collection._resumeSyncStart()\n      }\n      currentRenderState.deferredCollections.clear()\n      return unsubscribe\n    },\n    [controller, currentRenderState],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n\n  const fetchNextPage = useCallback(\n    () => fetchNextLiveQueryWindowPage(controller),\n    [controller],\n  )\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled,\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":[],"mappings":";;;;;AAwCA;AACA;AA2FO;AAKL;AACA;AACA;AACA;AAEA;AAGA;AACA;AACA;AACA;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA2D;AACzD;AAEF;AAIA;AAEA;AACA;AAEA;AACE;AACE;AACA;AAAsB;AAEtB;AACA;AACA;AAA8C;AAM9C;AACA;AAAyC;AAEzC;AACA;AAAoB;AAClB;AACA;AAC2B;AAC3B;AAEF;AACA;AACE;AAA2B;AAE3B;AACA;AAA2C;AAC7C;AACF;AAGF;AAEA;AAA6B;AAChB;AACX;AAEF;AACA;AAMA;AAEA;AAKA;AAIA;AAGA;AACA;AACE;AACA;AAEA;AACE;AACA;AACE;AACE;AAAqB;AACnB;AACA;AACA;AAAA;AAGJ;AAAmB;AAErB;AACA;AACE;AAAmB;AAInB;AAAuC;AACU;AAAA;AAAA;AAGpC;AACH;AACT;AACH;AAGF;AACE;AAAsE;AAGxE;AACE;AACmE;AAEnE;AAA0C;AAG5C;AAAoE;AAC7B;AACP;AAC9B;AAEsD;AACtD;AACA;AACA;AAEF;AAGA;AACA;AAAc;AACZ;AACkD;AACX;AAC/B;AACR;AACyD;AACzD;AACA;AACA;AACwD;AACtD;AACA;AACA;AACD;AACD;AACQ;AACR;AAAA;AAGJ;AACA;AAEA;AAAkB;AAEd;AACA;AACA;AACE;AACA;AAAuC;AAEzC;AACE;AAAW;AAEb;AACA;AAAO;AACT;AAC+B;AAEjC;AACA;AAEA;AAAsB;AACyB;AAClC;AAGb;AAAO;AACU;AACC;AACC;AACG;AACF;AACD;AACC;AACI;AAEX;AAEA;AACK;AACK;AACrB;AACsB;AACO;AACb;AAEpB;;;;"}

package/dist/esm/useLiveQuery.d.ts

@@ -7,7 +7,7 @@ export type DerivedIdentityProfiler = {
 };
 export type UseLiveQueryStatus = CollectionStatus | `disabled`;
 export type LiveQueryKey = ReadonlyArray<unknown>;
-export type UseLiveQueryConfig<TContext extends Context> = LiveQueryCollectionConfig<TContext> & {
+type UseLiveQueryConfigOptions<TContext extends Context> = Omit<LiveQueryCollectionConfig<TContext>, `query`> & {
     /**
      * Explicit identity for queries that contain opaque functional variants or
      * are hot enough that deriving identity from structured IR is too expensive.
@@ -17,6 +17,11 @@ export type UseLiveQueryConfig<TContext extends Context> = LiveQueryCollectionCo
     /** Override the nearest DbProvider for this query. */
     client?: DbClient;
 };
+type ConfiguredQueryBuilder<TContext extends Context> = Extract<LiveQueryCollectionConfig<TContext>[`query`], QueryBuilder<TContext>>;
+export type UseLiveQueryConfig<TContext extends Context> = UseLiveQueryConfigOptions<TContext> & Pick<LiveQueryCollectionConfig<TContext>, `query`>;
+export type ConditionalUseLiveQueryConfig<TContext extends Context> = UseLiveQueryConfigOptions<TContext> & {
+    query: ConfiguredQueryBuilder<TContext> | ((q: InitialQueryBuilder) => ConfiguredQueryBuilder<TContext> | undefined | null);
+};
 export declare function warnDeprecatedDepsArray(hookName?: `useLiveQuery` | `useLiveInfiniteQuery`): void;
 export declare function prepareQueryValue(value: unknown, dbClient: DbClient | undefined, deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>): unknown;
 type DerivedQueryPreparation = {
@@ -60,6 +65,16 @@ export declare function warnUnhashableDerivedIdentity(error: UnhashableQueryIREr
  * })
  *
  * @example
+ * // Return undefined or null to disable a query
+ * const { data, isEnabled } = useLiveQuery({
+ *   query: (q) => {
+ *     if (!userId) return undefined
+ *     return q.from({ todos: todosCollection })
+ *             .where(({ todos }) => eq(todos.userId, userId))
+ *   },
+ * })
+ *
+ * @example
  * // Join pattern
  * const { data } = useLiveQuery({
  *   query: (q) =>
@@ -196,6 +211,18 @@ export declare function useLiveQuery<TContext extends Context>(config: UseLiveQu
     isCleanedUp: boolean;
     isEnabled: true;
 };
+export declare function useLiveQuery<TContext extends Context>(config: ConditionalUseLiveQueryConfig<TContext>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: InferResultType<TContext> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
 export declare function useLiveQuery<TContext extends Context>(config: LiveQueryCollectionConfig<TContext>, deps?: Array<unknown>): {
     state: Map<string | number, GetResult<TContext>>;
     data: InferResultType<TContext>;
@@ -208,6 +235,18 @@ export declare function useLiveQuery<TContext extends Context>(config: LiveQuery
     isCleanedUp: boolean;
     isEnabled: true;
 };
+export declare function useLiveQuery<TContext extends Context>(config: ConditionalUseLiveQueryConfig<TContext>, deps: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: InferResultType<TContext> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
 /**
  * Subscribe to an existing live query collection
  * @param liveQueryCollection - Pre-created live query collection to subscribe to

package/dist/esm/useLiveQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["'use client'\n\nimport { useRef, useSyncExternalStore } from 'react'\nimport {\n  BaseQueryBuilder,\n  UnhashableQueryIRError,\n  createLiveQueryCollection,\n  createLiveQueryObserver,\n  deepEquals,\n  getPreparedLiveQueryIdentity,\n  getStableValueHash,\n  isCollection,\n  prepareLiveQueryValue,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport { setLiveQueryResultInfo } from './live-query-internals'\nimport type {\n  Collection,\n  CollectionImpl,\n  CollectionStatus,\n  Context,\n  DbClient,\n  GetResult,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  LiveQueryObserver,\n  NonSingleResult,\n  QueryBuilder,\n  SingleResult,\n} from '@tanstack/db'\n\nconst DEFAULT_GC_TIME_MS = 1 // Live queries created by useLiveQuery are cleaned up immediately (0 disables GC)\nconst DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS = 16\nconst DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD = 10\nconst DERIVED_IDENTITY_TOTAL_WARN_MS = 50\nconst warnedDepsCallsites = new Set<string>()\nconst warnedDerivedIdentityCallsites = new Set<string>()\nconst warnedUnhashableIdentityCallsites = new Set<string>()\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type DerivedIdentityProfiler = {\n  renderCount: number\n  totalMs: number\n  maxMs: number\n  warned: boolean\n}\n\nexport type UseLiveQueryStatus = CollectionStatus | `disabled`\nexport type LiveQueryKey = ReadonlyArray<unknown>\nexport type UseLiveQueryConfig<TContext extends Context> =\n  LiveQueryCollectionConfig<TContext> & {\n    /**\n     * Explicit identity for queries that contain opaque functional variants or\n     * are hot enough that deriving identity from structured IR is too expensive.\n     * Structured queries should omit this so DB can derive identity directly.\n     */\n    queryKey?: LiveQueryKey\n    /** Override the nearest DbProvider for this query. */\n    client?: DbClient\n  }\n\nexport function warnDeprecatedDepsArray(\n  hookName: `useLiveQuery` | `useLiveInfiniteQuery` = `useLiveQuery`,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_DEPRECATION_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedDepsCallsites.has(callsite)) {\n    return\n  }\n  warnedDepsCallsites.add(callsite)\n  const replacement =\n    hookName === `useLiveQuery`\n      ? `useLiveQuery({ query })`\n      : `useLiveInfiniteQuery(query, { queryKey })`\n  console.warn(\n    `[${hookName}] The dependency-array form is deprecated and will be removed in 1.0. Use ${replacement} instead. Provide queryKey only for functional/opaque queries or to avoid deriving identity from structured query IR on render.`,\n  )\n}\n\nfunction shouldWarnInDevelopment(disableEnvVar: string): boolean {\n  if (typeof process === `undefined`) {\n    return false\n  }\n\n  return (\n    process.env.NODE_ENV !== `production` && process.env[disableEnvVar] !== `1`\n  )\n}\n\nfunction getCurrentTime(): number {\n  return typeof performance !== `undefined` &&\n    typeof performance.now === `function`\n    ? performance.now()\n    : Date.now()\n}\n\nfunction getWarningCallsite(stackIndex: number): string {\n  const stack = new Error().stack ?? `unknown`\n  return stack.split(`\\n`)[stackIndex]?.trim() ?? stack\n}\n\nfunction warnDerivedIdentityHotPath(\n  profiler: DerivedIdentityProfiler,\n  durationMs: number,\n): void {\n  if (\n    profiler.warned ||\n    !shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n  ) {\n    return\n  }\n\n  const isSlowSingleRender =\n    durationMs >= DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS\n  const isHotRenderPath =\n    profiler.renderCount >= DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD &&\n    profiler.totalMs >= DERIVED_IDENTITY_TOTAL_WARN_MS\n\n  if (!isSlowSingleRender && !isHotRenderPath) {\n    return\n  }\n\n  const callsite = getWarningCallsite(5)\n  if (warnedDerivedIdentityCallsites.has(callsite)) {\n    profiler.warned = true\n    return\n  }\n\n  warnedDerivedIdentityCallsites.add(callsite)\n  profiler.warned = true\n\n  const reason = isSlowSingleRender\n    ? `one render took ${durationMs.toFixed(1)}ms`\n    : `${profiler.renderCount} renders took ${profiler.totalMs.toFixed(1)}ms`\n\n  console.warn(\n    `[useLiveQuery] Deriving live query identity from structured query IR is running on a hot render path (${reason}, max ${profiler.maxMs.toFixed(1)}ms). ` +\n      `Provide an explicit queryKey to skip rebuilding and hashing the IR on every render: useLiveQuery({ queryKey: [...], query }).`,\n  )\n}\n\nfunction getExplicitQueryKey(value: unknown): LiveQueryKey | undefined {\n  return value &&\n    typeof value === `object` &&\n    Array.isArray((value as { queryKey?: unknown }).queryKey)\n    ? (value as { queryKey: LiveQueryKey }).queryKey\n    : undefined\n}\n\nfunction getExplicitDbClient(value: unknown): DbClient | undefined {\n  return value &&\n    typeof value === `object` &&\n    `client` in value &&\n    (value as { client?: unknown }).client !== undefined\n    ? (value as { client: DbClient }).client\n    : undefined\n}\n\nexport function prepareQueryValue(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): unknown {\n  return prepareLiveQueryValue(value, dbClient, deferredCollections)\n}\n\ntype DerivedQueryPreparation =\n  | {\n      status: `hashable`\n      value: unknown\n      identityDeps: Array<unknown>\n    }\n  | {\n      status: `unhashable`\n      value: unknown\n      error: UnhashableQueryIRError\n    }\n\nexport function prepareDerivedQuery(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  profiler: DerivedIdentityProfiler,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): DerivedQueryPreparation {\n  const shouldProfile = shouldWarnInDevelopment(\n    `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`,\n  )\n  const start = shouldProfile ? getCurrentTime() : 0\n  const preparedValue = prepareQueryValue(value, dbClient, deferredCollections)\n\n  try {\n    const identity = getPreparedLiveQueryIdentity(preparedValue)\n    return {\n      status: `hashable`,\n      value: preparedValue,\n      identityDeps: [`derived`, identity],\n    }\n  } catch (error) {\n    if (error instanceof UnhashableQueryIRError) {\n      return { status: `unhashable`, value: preparedValue, error }\n    }\n\n    throw error\n  } finally {\n    if (shouldProfile) {\n      const durationMs = getCurrentTime() - start\n      profiler.renderCount += 1\n      profiler.totalMs += durationMs\n      profiler.maxMs = Math.max(profiler.maxMs, durationMs)\n      warnDerivedIdentityHotPath(profiler, durationMs)\n    }\n  }\n}\n\nexport function warnUnhashableDerivedIdentity(\n  error: UnhashableQueryIRError,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedUnhashableIdentityCallsites.has(callsite)) {\n    return\n  }\n  warnedUnhashableIdentityCallsites.add(callsite)\n\n  console.warn(\n    `[useLiveQuery] This query cannot derive a stable identity because ${error.reason} at ${error.path}. ` +\n      `It will keep the legacy mount-stable behavior for now. Add queryKey: [...] to make captured values reactive. ` +\n      `Unhashable queries without queryKey will throw in 1.0.`,\n  )\n}\n\nfunction createCollectionFromPreparedQuery(value: unknown) {\n  if (value === undefined || value === null) {\n    return null\n  }\n\n  if (isCollection(value)) {\n    value.startSyncImmediate()\n    return value\n  }\n\n  if (value instanceof BaseQueryBuilder) {\n    return createLiveQueryCollection({\n      query: value,\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n    })\n  }\n\n  if (typeof value === `object`) {\n    return createLiveQueryCollection({\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n      ...(value as LiveQueryCollectionConfig<any>),\n    })\n  }\n\n  throw new Error(\n    `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof value}`,\n  )\n}\n\n/**\n * Create a live query using a query function.\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Prefer config object syntax\n * const { data, isLoading } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ todos: todosCollection })\n *      .where(({ todos }) => eq(todos.completed, false))\n *      .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * })\n *\n *  @example\n * // Single result query\n * const { data } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => eq(todos.id, 1))\n *          .findOne()\n * })\n *\n * @example\n * // Structured captured values are included in derived query identity\n * const { data, state } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n * })\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ issues: issueCollection })\n *      .join({ persons: personCollection }, ({ issues, persons }) =>\n *        eq(issues.userId, persons.id)\n *      )\n *      .select(({ issues, persons }) => ({\n *        id: issues.id,\n *        title: issues.title,\n *        userName: persons.name\n *      }))\n * })\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todoCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept query function that always returns QueryBuilder\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled if always returns QueryBuilder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true if always returns QueryBuilder\n}\n\n// Overload 2: Accept query function that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => QueryBuilder<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 3: Accept query function that can return LiveQueryCollectionConfig\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => LiveQueryCollectionConfig<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 4: Accept query function that can return Collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => Collection<TResult, TKey, TUtils> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<TKey, TResult> | undefined\n  data: Array<TResult> | undefined\n  collection: Collection<TResult, TKey, TUtils> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 5: Accept query function that can return all types\nexport function useLiveQuery<\n  TContext extends Context,\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) =>\n    | QueryBuilder<TContext>\n    | LiveQueryCollectionConfig<TContext>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n    | null,\n  deps?: Array<unknown>,\n): {\n  state:\n    | Map<string | number, GetResult<TContext>>\n    | Map<TKey, TResult>\n    | undefined\n  data: InferResultType<TContext> | Array<TResult> | undefined\n  collection:\n    | Collection<GetResult<TContext>, string | number, {}>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({\n *   query: queryBuilder,\n * })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 6: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: UseLiveQueryConfig<TContext>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled for config objects\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for config objects\n}\n\n// Overload 7: Accept config object with legacy deps\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled for config objects\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for config objects\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 8: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Overload 9: Accept pre-created live query collection with singleResult: true\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: TResult | undefined\n  collection: Collection<TResult, TKey, TUtils> & SingleResult\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps?: Array<unknown>,\n) {\n  const contextDbClient = useOptionalDbClient()\n  // Check if it's already a collection\n  const inputIsCollection = isCollection(configOrQueryOrCollection)\n  const dbClient = inputIsCollection\n    ? contextDbClient\n    : (getExplicitDbClient(configOrQueryOrCollection) ?? contextDbClient)\n  const resolvedDeps = deps ?? []\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<Collection<object, string | number, {}> | null>(\n    null,\n  )\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<unknown>(null)\n  const clientRef = useRef(dbClient)\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const deferredCollectionsRef = useRef(\n    new Set<CollectionImpl<any, string | number, any, any, any>>(),\n  )\n  const observerRef = useRef<LiveQueryObserver<object, string | number> | null>(\n    null,\n  )\n  const queryHashRef = useRef<string | undefined>(undefined)\n  const identityErrorRef = useRef<UnhashableQueryIRError | undefined>(undefined)\n\n  const queryKey = !inputIsCollection\n    ? getExplicitQueryKey(configOrQueryOrCollection)\n    : undefined\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown>\n  let streamIdentity: unknown = undefined\n  let identityError: UnhashableQueryIRError | undefined\n\n  if (queryKey) {\n    identityDeps = queryKey\n    streamIdentity = [`queryKey`, queryKey]\n  } else if (deps !== undefined) {\n    identityDeps = resolvedDeps\n    try {\n      preparedQueryValue = prepareQueryValue(\n        configOrQueryOrCollection,\n        dbClient,\n        deferredCollectionsRef.current,\n      )\n      streamIdentity = [\n        `deps`,\n        resolvedDeps,\n        getPreparedLiveQueryIdentity(preparedQueryValue),\n      ]\n    } catch (error) {\n      if (!(error instanceof UnhashableQueryIRError)) throw error\n      warnUnhashableDerivedIdentity(error)\n      identityError = error\n    }\n  } else if (inputIsCollection) {\n    identityDeps = []\n    streamIdentity = [`collection`, configOrQueryOrCollection.id]\n  } else {\n    const preparation = prepareDerivedQuery(\n      configOrQueryOrCollection,\n      dbClient,\n      derivedIdentityProfilerRef.current,\n      deferredCollectionsRef.current,\n    )\n    preparedQueryValue = preparation.value\n    if (preparation.status === `hashable`) {\n      identityDeps = preparation.identityDeps\n      streamIdentity = preparation.identityDeps\n    } else {\n      warnUnhashableDerivedIdentity(preparation.error)\n      identityDeps = legacyUnhashableIdentityRef.current\n      identityError = preparation.error\n    }\n  }\n\n  let queryHash: string | undefined\n  if (streamIdentity !== undefined) {\n    try {\n      queryHash = getStableValueHash(streamIdentity, `queryKey`)\n    } catch (error) {\n      if (error instanceof UnhashableQueryIRError) {\n        if (queryKey !== undefined) throw error\n        identityError = error\n      } else {\n        throw error\n      }\n    }\n  }\n\n  if (deps !== undefined) {\n    warnDeprecatedDepsArray()\n  }\n\n  const identityChanged =\n    depsRef.current === null ||\n    (deps !== undefined\n      ? depsRef.current.length !== identityDeps.length ||\n        depsRef.current.some((dep, index) => dep !== identityDeps[index])\n      : !deepEquals(depsRef.current, identityDeps))\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (inputIsCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!inputIsCollection && (clientRef.current !== dbClient || identityChanged))\n\n  const resumeDeferredCollections = () => {\n    for (const collection of deferredCollectionsRef.current) {\n      collection._resumeSyncStart()\n    }\n    deferredCollectionsRef.current.clear()\n  }\n\n  if (needsNewCollection) {\n    if (inputIsCollection) {\n      // Warn when passing a collection directly with on-demand sync mode\n      // In on-demand mode, data is only loaded when queries with predicates request it\n      // Passing the collection directly doesn't provide any predicates, so no data loads\n      const syncMode = (\n        configOrQueryOrCollection as { config?: { syncMode?: string } }\n      ).config?.syncMode\n      if (\n        syncMode === `on-demand` &&\n        shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n      ) {\n        console.warn(\n          `[useLiveQuery] Warning: Passing a collection with syncMode \"on-demand\" directly to useLiveQuery ` +\n            `will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.\\n\\n` +\n            `Instead, use a query builder function:\\n` +\n            `  const { data } = useLiveQuery({ query: (q) => q.from({ c: myCollection }).select(({ c }) => c) })\\n\\n` +\n            `Or switch to syncMode \"eager\" if you want all data to sync automatically.`,\n        )\n      }\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      if (preparedQueryValue === unpreparedQueryValue) {\n        preparedQueryValue = prepareQueryValue(\n          configOrQueryOrCollection,\n          dbClient,\n          deferredCollectionsRef.current,\n        )\n      }\n      collectionRef.current = createCollectionFromPreparedQuery(\n        preparedQueryValue,\n      ) as Collection<object, string | number, {}>\n      configRef.current = configOrQueryOrCollection\n      depsRef.current = [...identityDeps]\n    }\n    clientRef.current = dbClient\n    queryHashRef.current = queryHash\n    identityErrorRef.current = identityError\n  }\n\n  // Recreate the observer when the underlying collection changes. The observer\n  // is not disposed explicitly here or on unmount: `useSyncExternalStore`\n  // unsubscribes it when the subscribe changes or the component unmounts, which\n  // detaches the collection subscription; the observer is then GC'd. (An unmount\n  // effect that disposed it would misfire under StrictMode/offscreen effect\n  // replay, leaving a disposed observer in the ref.)\n  if (needsNewCollection) {\n    // Defer the initial notify: useSyncExternalStore must not be notified\n    // synchronously during subscribe.\n    // Wholesale mode: React re-reads getSnapshot() on notify, keeps the\n    // hook's pre-observer loading policy, and — because wholesale delivers\n    // nothing synchronously during subscribe — never notifies\n    // useSyncExternalStore inside its own subscribe call.\n    observerRef.current = createLiveQueryObserver(collectionRef.current, {\n      mode: `wholesale`,\n      client: dbClient,\n      queryHash: queryHashRef.current,\n      onPreload: resumeDeferredCollections,\n    })\n  }\n  const observer = observerRef.current!\n\n  // Stable subscribe bound to the current observer; the observer owns the\n  // subscription, ready-race, and disposal.\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = observer.subscribe(() => onStoreChange())\n      resumeDeferredCollections()\n      return unsubscribe\n    }\n  }\n\n  const returned = useSyncExternalStore(\n    subscribeRef.current,\n    () => observer.getSnapshot(),\n    () => observer.getServerSnapshot(),\n  )\n  setLiveQueryResultInfo(returned, {\n    client: dbClient,\n    queryHash: queryHashRef.current,\n    identityError: identityErrorRef.current,\n    observer,\n  })\n  return returned as any\n}\n"],"names":[],"mappings":";;;;;AAgCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAuBO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AACA;AAIA;AAAQ;AAC8F;AAExG;AAEA;AACE;AACE;AAAO;AAGT;AAGF;AAEA;AACE;AAIF;AAEA;AACE;AACA;AAAmB;AACrB;AAEA;AAIE;AAIE;AAAA;AAGF;AAEA;AAIA;AACE;AAAA;AAGF;AACA;AACE;AACA;AAAA;AAGF;AACA;AAEA;AAIA;AAAQ;AAC2I;AAGrJ;AAEA;AACE;AAKF;AAEA;AACE;AAMF;AAEO;AAKL;AACF;AAcO;AAML;AAAsB;AACpB;AAEF;AACA;AAEA;AACE;AACA;AAAO;AACG;AACD;AAC2B;AAAA;AAGpC;AACE;AAAqD;AAGvD;AAAM;AAEN;AACE;AACA;AACA;AACA;AACA;AAA+C;AACjD;AAEJ;AAEO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AAEA;AAAQ;AAC4F;AAItG;AAEA;AACE;AACE;AAAO;AAGT;AACE;AACA;AAAO;AAGT;AACE;AAAiC;AACxB;AACI;AACH;AACT;AAGH;AACE;AAAiC;AACpB;AACH;AACJ;AACL;AAGH;AAAU;AACyH;AAErI;AAwTO;AAIL;AAEA;AACA;AAGA;AAGA;AAAsB;AACpB;AAEF;AACA;AACA;AACA;AAA2D;AACzD;AAGF;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA+B;AACzB;AAEN;AAAoB;AAClB;AAEF;AACA;AAEA;AAGA;AAEA;AACA;AACA;AAEA;AACE;AACA;AAAsC;AAEtC;AACA;AACE;AAAqB;AACnB;AACA;AACuB;AAEzB;AAAiB;AACf;AACA;AAC+C;AAAA;AAGjD;AACA;AACA;AAAgB;AAClB;AAEA;AACA;AAA4D;AAE5D;AAAoB;AAClB;AACA;AAC2B;AACJ;AAEzB;AACA;AACE;AACA;AAA6B;AAE7B;AACA;AACA;AAA4B;AAC9B;AAGF;AACA;AACE;AACE;AAAyD;AAEzD;AACE;AACA;AAAgB;AAEhB;AAAM;AACR;AACF;AAGF;AACE;AAAA;AAGF;AAQA;AAKA;AACE;AACE;AAAW;AAEb;AAA+B;AAGjC;AACE;AAIE;AAGA;AAIE;AAAQ;;AACN;AAAA;;AAAA;AAAA;AAAA;AAQJ;AACA;AACA;AAAoB;AAEpB;AACE;AAAqB;AACnB;AACA;AACuB;AAAA;AAG3B;AAAwB;AACtB;AAEF;AACA;AAAkC;AAEpC;AACA;AACA;AAA2B;AAS7B;AAOE;AAAqE;AAC7D;AACE;AACgB;AACb;AACZ;AAEH;AAIA;AAGA;AACE;AACE;AACA;AACA;AAAO;AACT;AAGF;AAAiB;AACF;AACE;AACA;AAEjB;AAAiC;AACvB;AACgB;AACQ;AAChC;AAEF;AACF;;;;;;;;"}
+{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["'use client'\n\nimport { useRef, useSyncExternalStore } from 'react'\nimport {\n  BaseQueryBuilder,\n  UnhashableQueryIRError,\n  createLiveQueryCollection,\n  createLiveQueryObserver,\n  deepEquals,\n  getPreparedLiveQueryIdentity,\n  getStableValueHash,\n  isCollection,\n  prepareLiveQueryValue,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport { setLiveQueryResultInfo } from './live-query-internals'\nimport type {\n  Collection,\n  CollectionImpl,\n  CollectionStatus,\n  Context,\n  DbClient,\n  GetResult,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  LiveQueryObserver,\n  NonSingleResult,\n  QueryBuilder,\n  SingleResult,\n} from '@tanstack/db'\n\nconst DEFAULT_GC_TIME_MS = 1 // Live queries created by useLiveQuery are cleaned up immediately (0 disables GC)\nconst DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS = 16\nconst DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD = 10\nconst DERIVED_IDENTITY_TOTAL_WARN_MS = 50\nconst warnedDepsCallsites = new Set<string>()\nconst warnedDerivedIdentityCallsites = new Set<string>()\nconst warnedUnhashableIdentityCallsites = new Set<string>()\nconst unpreparedQueryValue = Symbol(`unpreparedQueryValue`)\n\nexport type DerivedIdentityProfiler = {\n  renderCount: number\n  totalMs: number\n  maxMs: number\n  warned: boolean\n}\n\nexport type UseLiveQueryStatus = CollectionStatus | `disabled`\nexport type LiveQueryKey = ReadonlyArray<unknown>\ntype UseLiveQueryConfigOptions<TContext extends Context> = Omit<\n  LiveQueryCollectionConfig<TContext>,\n  `query`\n> & {\n  /**\n   * Explicit identity for queries that contain opaque functional variants or\n   * are hot enough that deriving identity from structured IR is too expensive.\n   * Structured queries should omit this so DB can derive identity directly.\n   */\n  queryKey?: LiveQueryKey\n  /** Override the nearest DbProvider for this query. */\n  client?: DbClient\n}\n\ntype ConfiguredQueryBuilder<TContext extends Context> = Extract<\n  LiveQueryCollectionConfig<TContext>[`query`],\n  QueryBuilder<TContext>\n>\n\nexport type UseLiveQueryConfig<TContext extends Context> =\n  UseLiveQueryConfigOptions<TContext> &\n    Pick<LiveQueryCollectionConfig<TContext>, `query`>\n\nexport type ConditionalUseLiveQueryConfig<TContext extends Context> =\n  UseLiveQueryConfigOptions<TContext> & {\n    query:\n      | ConfiguredQueryBuilder<TContext>\n      | ((\n          q: InitialQueryBuilder,\n        ) => ConfiguredQueryBuilder<TContext> | undefined | null)\n  }\n\nexport function warnDeprecatedDepsArray(\n  hookName: `useLiveQuery` | `useLiveInfiniteQuery` = `useLiveQuery`,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_DEPRECATION_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedDepsCallsites.has(callsite)) {\n    return\n  }\n  warnedDepsCallsites.add(callsite)\n  const replacement =\n    hookName === `useLiveQuery`\n      ? `useLiveQuery({ query })`\n      : `useLiveInfiniteQuery(query, { queryKey })`\n  console.warn(\n    `[${hookName}] The dependency-array form is deprecated and will be removed in 1.0. Use ${replacement} instead. Provide queryKey only for functional/opaque queries or to avoid deriving identity from structured query IR on render.`,\n  )\n}\n\nfunction shouldWarnInDevelopment(disableEnvVar: string): boolean {\n  if (typeof process === `undefined`) {\n    return false\n  }\n\n  return (\n    process.env.NODE_ENV !== `production` && process.env[disableEnvVar] !== `1`\n  )\n}\n\nfunction getCurrentTime(): number {\n  return typeof performance !== `undefined` &&\n    typeof performance.now === `function`\n    ? performance.now()\n    : Date.now()\n}\n\nfunction getWarningCallsite(stackIndex: number): string {\n  const stack = new Error().stack ?? `unknown`\n  return stack.split(`\\n`)[stackIndex]?.trim() ?? stack\n}\n\nfunction warnDerivedIdentityHotPath(\n  profiler: DerivedIdentityProfiler,\n  durationMs: number,\n): void {\n  if (\n    profiler.warned ||\n    !shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n  ) {\n    return\n  }\n\n  const isSlowSingleRender =\n    durationMs >= DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS\n  const isHotRenderPath =\n    profiler.renderCount >= DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD &&\n    profiler.totalMs >= DERIVED_IDENTITY_TOTAL_WARN_MS\n\n  if (!isSlowSingleRender && !isHotRenderPath) {\n    return\n  }\n\n  const callsite = getWarningCallsite(5)\n  if (warnedDerivedIdentityCallsites.has(callsite)) {\n    profiler.warned = true\n    return\n  }\n\n  warnedDerivedIdentityCallsites.add(callsite)\n  profiler.warned = true\n\n  const reason = isSlowSingleRender\n    ? `one render took ${durationMs.toFixed(1)}ms`\n    : `${profiler.renderCount} renders took ${profiler.totalMs.toFixed(1)}ms`\n\n  console.warn(\n    `[useLiveQuery] Deriving live query identity from structured query IR is running on a hot render path (${reason}, max ${profiler.maxMs.toFixed(1)}ms). ` +\n      `Provide an explicit queryKey to skip rebuilding and hashing the IR on every render: useLiveQuery({ queryKey: [...], query }).`,\n  )\n}\n\nfunction getExplicitQueryKey(value: unknown): LiveQueryKey | undefined {\n  return value &&\n    typeof value === `object` &&\n    Array.isArray((value as { queryKey?: unknown }).queryKey)\n    ? (value as { queryKey: LiveQueryKey }).queryKey\n    : undefined\n}\n\nfunction getExplicitDbClient(value: unknown): DbClient | undefined {\n  return value &&\n    typeof value === `object` &&\n    `client` in value &&\n    (value as { client?: unknown }).client !== undefined\n    ? (value as { client: DbClient }).client\n    : undefined\n}\n\nexport function prepareQueryValue(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): unknown {\n  return prepareLiveQueryValue(value, dbClient, deferredCollections)\n}\n\ntype DerivedQueryPreparation =\n  | {\n      status: `hashable`\n      value: unknown\n      identityDeps: Array<unknown>\n    }\n  | {\n      status: `unhashable`\n      value: unknown\n      error: UnhashableQueryIRError\n    }\n\nexport function prepareDerivedQuery(\n  value: unknown,\n  dbClient: DbClient | undefined,\n  profiler: DerivedIdentityProfiler,\n  deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,\n): DerivedQueryPreparation {\n  const shouldProfile = shouldWarnInDevelopment(\n    `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`,\n  )\n  const start = shouldProfile ? getCurrentTime() : 0\n  const preparedValue = prepareQueryValue(value, dbClient, deferredCollections)\n\n  try {\n    const identity = getPreparedLiveQueryIdentity(preparedValue)\n    return {\n      status: `hashable`,\n      value: preparedValue,\n      identityDeps: [`derived`, identity],\n    }\n  } catch (error) {\n    if (error instanceof UnhashableQueryIRError) {\n      return { status: `unhashable`, value: preparedValue, error }\n    }\n\n    throw error\n  } finally {\n    if (shouldProfile) {\n      const durationMs = getCurrentTime() - start\n      profiler.renderCount += 1\n      profiler.totalMs += durationMs\n      profiler.maxMs = Math.max(profiler.maxMs, durationMs)\n      warnDerivedIdentityHotPath(profiler, durationMs)\n    }\n  }\n}\n\nexport function warnUnhashableDerivedIdentity(\n  error: UnhashableQueryIRError,\n): void {\n  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {\n    return\n  }\n\n  const callsite = getWarningCallsite(4)\n  if (warnedUnhashableIdentityCallsites.has(callsite)) {\n    return\n  }\n  warnedUnhashableIdentityCallsites.add(callsite)\n\n  console.warn(\n    `[useLiveQuery] This query cannot derive a stable identity because ${error.reason} at ${error.path}. ` +\n      `It will keep the legacy mount-stable behavior for now. Add queryKey: [...] to make captured values reactive. ` +\n      `Unhashable queries without queryKey will throw in 1.0.`,\n  )\n}\n\nfunction createCollectionFromPreparedQuery(value: unknown) {\n  if (value === undefined || value === null) {\n    return null\n  }\n\n  if (isCollection(value)) {\n    value.startSyncImmediate()\n    return value\n  }\n\n  if (value instanceof BaseQueryBuilder) {\n    return createLiveQueryCollection({\n      query: value,\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n    })\n  }\n\n  if (typeof value === `object`) {\n    return createLiveQueryCollection({\n      startSync: true,\n      gcTime: DEFAULT_GC_TIME_MS,\n      ...(value as LiveQueryCollectionConfig<any>),\n    })\n  }\n\n  throw new Error(\n    `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof value}`,\n  )\n}\n\n/**\n * Create a live query using a query function.\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Prefer config object syntax\n * const { data, isLoading } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ todos: todosCollection })\n *      .where(({ todos }) => eq(todos.completed, false))\n *      .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * })\n *\n *  @example\n * // Single result query\n * const { data } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => eq(todos.id, 1))\n *          .findOne()\n * })\n *\n * @example\n * // Structured captured values are included in derived query identity\n * const { data, state } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n * })\n *\n * @example\n * // Return undefined or null to disable a query\n * const { data, isEnabled } = useLiveQuery({\n *   query: (q) => {\n *     if (!userId) return undefined\n *     return q.from({ todos: todosCollection })\n *             .where(({ todos }) => eq(todos.userId, userId))\n *   },\n * })\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery({\n *   query: (q) =>\n *     q.from({ issues: issueCollection })\n *      .join({ persons: personCollection }, ({ issues, persons }) =>\n *        eq(issues.userId, persons.id)\n *      )\n *      .select(({ issues, persons }) => ({\n *        id: issues.id,\n *        title: issues.title,\n *        userName: persons.name\n *      }))\n * })\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todoCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept query function that always returns QueryBuilder\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled if always returns QueryBuilder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true if always returns QueryBuilder\n}\n\n// Overload 2: Accept query function that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => QueryBuilder<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 3: Accept query function that can return LiveQueryCollectionConfig\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => LiveQueryCollectionConfig<TContext> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 4: Accept query function that can return Collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => Collection<TResult, TKey, TUtils> | undefined | null,\n  deps?: Array<unknown>,\n): {\n  state: Map<TKey, TResult> | undefined\n  data: Array<TResult> | undefined\n  collection: Collection<TResult, TKey, TUtils> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 5: Accept query function that can return all types\nexport function useLiveQuery<\n  TContext extends Context,\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) =>\n    | QueryBuilder<TContext>\n    | LiveQueryCollectionConfig<TContext>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n    | null,\n  deps?: Array<unknown>,\n): {\n  state:\n    | Map<string | number, GetResult<TContext>>\n    | Map<TKey, TResult>\n    | undefined\n  data: InferResultType<TContext> | Array<TResult> | undefined\n  collection:\n    | Collection<GetResult<TContext>, string | number, {}>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({\n *   query: queryBuilder,\n * })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 6: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: UseLiveQueryConfig<TContext>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled when query always returns a builder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true when query always returns a builder\n}\n\n// Overload 7: Accept config object with a query that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  config: ConditionalUseLiveQueryConfig<TContext>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 8: Accept config object with legacy deps\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus // Can't be disabled when query always returns a builder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true when query always returns a builder\n}\n\n// Overload 9: Accept config object with legacy deps and a query that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  config: ConditionalUseLiveQueryConfig<TContext>,\n  deps: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: InferResultType<TContext> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 10: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Overload 10: Accept pre-created live query collection with singleResult: true\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: TResult | undefined\n  collection: Collection<TResult, TKey, TUtils> & SingleResult\n  status: CollectionStatus // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps?: Array<unknown>,\n) {\n  const contextDbClient = useOptionalDbClient()\n  // Check if it's already a collection\n  const inputIsCollection = isCollection(configOrQueryOrCollection)\n  const dbClient = inputIsCollection\n    ? contextDbClient\n    : (getExplicitDbClient(configOrQueryOrCollection) ?? contextDbClient)\n  const resolvedDeps = deps ?? []\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<Collection<object, string | number, {}> | null>(\n    null,\n  )\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<unknown>(null)\n  const clientRef = useRef(dbClient)\n  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([\n    `legacy-unhashable`,\n  ])\n\n  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({\n    renderCount: 0,\n    totalMs: 0,\n    maxMs: 0,\n    warned: false,\n  })\n  const deferredCollectionsRef = useRef(\n    new Set<CollectionImpl<any, string | number, any, any, any>>(),\n  )\n  const observerRef = useRef<LiveQueryObserver<object, string | number> | null>(\n    null,\n  )\n  const queryHashRef = useRef<string | undefined>(undefined)\n  const identityErrorRef = useRef<UnhashableQueryIRError | undefined>(undefined)\n\n  const queryKey = !inputIsCollection\n    ? getExplicitQueryKey(configOrQueryOrCollection)\n    : undefined\n  let preparedQueryValue: unknown | typeof unpreparedQueryValue =\n    unpreparedQueryValue\n  let identityDeps: ReadonlyArray<unknown>\n  let streamIdentity: unknown = undefined\n  let identityError: UnhashableQueryIRError | undefined\n\n  if (queryKey) {\n    identityDeps = queryKey\n    streamIdentity = [`queryKey`, queryKey]\n  } else if (deps !== undefined) {\n    identityDeps = resolvedDeps\n    try {\n      preparedQueryValue = prepareQueryValue(\n        configOrQueryOrCollection,\n        dbClient,\n        deferredCollectionsRef.current,\n      )\n      streamIdentity = [\n        `deps`,\n        resolvedDeps,\n        getPreparedLiveQueryIdentity(preparedQueryValue),\n      ]\n    } catch (error) {\n      if (!(error instanceof UnhashableQueryIRError)) throw error\n      warnUnhashableDerivedIdentity(error)\n      identityError = error\n    }\n  } else if (inputIsCollection) {\n    identityDeps = []\n    streamIdentity = [`collection`, configOrQueryOrCollection.id]\n  } else {\n    const preparation = prepareDerivedQuery(\n      configOrQueryOrCollection,\n      dbClient,\n      derivedIdentityProfilerRef.current,\n      deferredCollectionsRef.current,\n    )\n    preparedQueryValue = preparation.value\n    if (preparation.status === `hashable`) {\n      identityDeps = preparation.identityDeps\n      streamIdentity = preparation.identityDeps\n    } else {\n      warnUnhashableDerivedIdentity(preparation.error)\n      identityDeps = legacyUnhashableIdentityRef.current\n      identityError = preparation.error\n    }\n  }\n\n  let queryHash: string | undefined\n  if (streamIdentity !== undefined) {\n    try {\n      queryHash = getStableValueHash(streamIdentity, `queryKey`)\n    } catch (error) {\n      if (error instanceof UnhashableQueryIRError) {\n        if (queryKey !== undefined) throw error\n        identityError = error\n      } else {\n        throw error\n      }\n    }\n  }\n\n  if (deps !== undefined) {\n    warnDeprecatedDepsArray()\n  }\n\n  const identityChanged =\n    depsRef.current === null ||\n    (deps !== undefined\n      ? depsRef.current.length !== identityDeps.length ||\n        depsRef.current.some((dep, index) => dep !== identityDeps[index])\n      : !deepEquals(depsRef.current, identityDeps))\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (inputIsCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!inputIsCollection && (clientRef.current !== dbClient || identityChanged))\n\n  const resumeDeferredCollections = () => {\n    for (const collection of deferredCollectionsRef.current) {\n      collection._resumeSyncStart()\n    }\n    deferredCollectionsRef.current.clear()\n  }\n\n  if (needsNewCollection) {\n    if (inputIsCollection) {\n      // Warn when passing a collection directly with on-demand sync mode\n      // In on-demand mode, data is only loaded when queries with predicates request it\n      // Passing the collection directly doesn't provide any predicates, so no data loads\n      const syncMode = (\n        configOrQueryOrCollection as { config?: { syncMode?: string } }\n      ).config?.syncMode\n      if (\n        syncMode === `on-demand` &&\n        shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)\n      ) {\n        console.warn(\n          `[useLiveQuery] Warning: Passing a collection with syncMode \"on-demand\" directly to useLiveQuery ` +\n            `will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.\\n\\n` +\n            `Instead, use a query builder function:\\n` +\n            `  const { data } = useLiveQuery({ query: (q) => q.from({ c: myCollection }).select(({ c }) => c) })\\n\\n` +\n            `Or switch to syncMode \"eager\" if you want all data to sync automatically.`,\n        )\n      }\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      if (preparedQueryValue === unpreparedQueryValue) {\n        preparedQueryValue = prepareQueryValue(\n          configOrQueryOrCollection,\n          dbClient,\n          deferredCollectionsRef.current,\n        )\n      }\n      collectionRef.current = createCollectionFromPreparedQuery(\n        preparedQueryValue,\n      ) as Collection<object, string | number, {}>\n      configRef.current = configOrQueryOrCollection\n      depsRef.current = [...identityDeps]\n    }\n    clientRef.current = dbClient\n    queryHashRef.current = queryHash\n    identityErrorRef.current = identityError\n  }\n\n  // Recreate the observer when the underlying collection changes. The observer\n  // is not disposed explicitly here or on unmount: `useSyncExternalStore`\n  // unsubscribes it when the subscribe changes or the component unmounts, which\n  // detaches the collection subscription; the observer is then GC'd. (An unmount\n  // effect that disposed it would misfire under StrictMode/offscreen effect\n  // replay, leaving a disposed observer in the ref.)\n  if (needsNewCollection) {\n    // Defer the initial notify: useSyncExternalStore must not be notified\n    // synchronously during subscribe.\n    // Wholesale mode: React re-reads getSnapshot() on notify, keeps the\n    // hook's pre-observer loading policy, and — because wholesale delivers\n    // nothing synchronously during subscribe — never notifies\n    // useSyncExternalStore inside its own subscribe call.\n    observerRef.current = createLiveQueryObserver(collectionRef.current, {\n      mode: `wholesale`,\n      client: dbClient,\n      queryHash: queryHashRef.current,\n      onPreload: resumeDeferredCollections,\n    })\n  }\n  const observer = observerRef.current!\n\n  // Stable subscribe bound to the current observer; the observer owns the\n  // subscription, ready-race, and disposal.\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = observer.subscribe(() => onStoreChange())\n      resumeDeferredCollections()\n      return unsubscribe\n    }\n  }\n\n  const returned = useSyncExternalStore(\n    subscribeRef.current,\n    () => observer.getSnapshot(),\n    () => observer.getServerSnapshot(),\n  )\n  setLiveQueryResultInfo(returned, {\n    client: dbClient,\n    queryHash: queryHashRef.current,\n    identityError: identityErrorRef.current,\n    observer,\n  })\n  return returned as any\n}\n"],"names":[],"mappings":";;;;;AAgCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AA2CO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AACA;AAIA;AAAQ;AAC8F;AAExG;AAEA;AACE;AACE;AAAO;AAGT;AAGF;AAEA;AACE;AAIF;AAEA;AACE;AACA;AAAmB;AACrB;AAEA;AAIE;AAIE;AAAA;AAGF;AAEA;AAIA;AACE;AAAA;AAGF;AACA;AACE;AACA;AAAA;AAGF;AACA;AAEA;AAIA;AAAQ;AAC2I;AAGrJ;AAEA;AACE;AAKF;AAEA;AACE;AAMF;AAEO;AAKL;AACF;AAcO;AAML;AAAsB;AACpB;AAEF;AACA;AAEA;AACE;AACA;AAAO;AACG;AACD;AAC2B;AAAA;AAGpC;AACE;AAAqD;AAGvD;AAAM;AAEN;AACE;AACA;AACA;AACA;AACA;AAA+C;AACjD;AAEJ;AAEO;AAGL;AACE;AAAA;AAGF;AACA;AACE;AAAA;AAEF;AAEA;AAAQ;AAC4F;AAItG;AAEA;AACE;AACE;AAAO;AAGT;AACE;AACA;AAAO;AAGT;AACE;AAAiC;AACxB;AACI;AACH;AACT;AAGH;AACE;AAAiC;AACpB;AACH;AACJ;AACL;AAGH;AAAU;AACyH;AAErI;AAmWO;AAIL;AAEA;AACA;AAGA;AAGA;AAAsB;AACpB;AAEF;AACA;AACA;AACA;AAA2D;AACzD;AAGF;AAAmE;AACpD;AACJ;AACF;AACC;AAEV;AAA+B;AACzB;AAEN;AAAoB;AAClB;AAEF;AACA;AAEA;AAGA;AAEA;AACA;AACA;AAEA;AACE;AACA;AAAsC;AAEtC;AACA;AACE;AAAqB;AACnB;AACA;AACuB;AAEzB;AAAiB;AACf;AACA;AAC+C;AAAA;AAGjD;AACA;AACA;AAAgB;AAClB;AAEA;AACA;AAA4D;AAE5D;AAAoB;AAClB;AACA;AAC2B;AACJ;AAEzB;AACA;AACE;AACA;AAA6B;AAE7B;AACA;AACA;AAA4B;AAC9B;AAGF;AACA;AACE;AACE;AAAyD;AAEzD;AACE;AACA;AAAgB;AAEhB;AAAM;AACR;AACF;AAGF;AACE;AAAA;AAGF;AAQA;AAKA;AACE;AACE;AAAW;AAEb;AAA+B;AAGjC;AACE;AAIE;AAGA;AAIE;AAAQ;;AACN;AAAA;;AAAA;AAAA;AAAA;AAQJ;AACA;AACA;AAAoB;AAEpB;AACE;AAAqB;AACnB;AACA;AACuB;AAAA;AAG3B;AAAwB;AACtB;AAEF;AACA;AAAkC;AAEpC;AACA;AACA;AAA2B;AAS7B;AAOE;AAAqE;AAC7D;AACE;AACgB;AACb;AACZ;AAEH;AAIA;AAGA;AACE;AACE;AACA;AACA;AAAO;AACT;AAGF;AAAiB;AACF;AACE;AACA;AAEjB;AAAiC;AACvB;AACgB;AACQ;AAChC;AAEF;AACF;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-db",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "React integration for @tanstack/db",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@tanstack/db": "0.8.2"
+    "@tanstack/db": "0.8.4"
   },
   "peerDependencies": {
     "react": ">=16.8.0"

package/skills/react-db/SKILL.md

@@ -89,11 +89,13 @@ const { data } = useLiveQuery({
 const { data } = useLiveQuery(preloadedCollection)
 
 // Conditional query — derived identity handles enabled/disabled transitions
-const { data, status } = useLiveQuery((q) => {
-  if (!userId) return undefined
-  return q
-    .from({ todo: todoCollection })
-    .where(({ todo }) => eq(todo.userId, userId))
+const { data, status } = useLiveQuery({
+  query: (q) => {
+    if (!userId) return undefined
+    return q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.userId, userId))
+  },
 })
 // When disabled: status='disabled', data=undefined
 ```

package/src/index.ts

@@ -1,6 +1,7 @@
 // Re-export all public APIs
 export { useLiveQuery } from './useLiveQuery'
 export type {
+  ConditionalUseLiveQueryConfig,
   LiveQueryKey,
   UseLiveQueryConfig,
   UseLiveQueryStatus,

package/src/useLiveInfiniteQuery.ts

@@ -341,7 +341,7 @@ export function useLiveInfiniteQuery<TContext extends Context>(
     collection:
       snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],
     isEnabled:
-      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],
+      snapshot.isEnabled,
     pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,
     pageParams: snapshot.pageParams as Array<number>,
     fetchNextPage,

package/src/useLiveQuery.ts

@@ -48,16 +48,36 @@ export type DerivedIdentityProfiler = {
 
 export type UseLiveQueryStatus = CollectionStatus | `disabled`
 export type LiveQueryKey = ReadonlyArray<unknown>
+type UseLiveQueryConfigOptions<TContext extends Context> = Omit<
+  LiveQueryCollectionConfig<TContext>,
+  `query`
+> & {
+  /**
+   * Explicit identity for queries that contain opaque functional variants or
+   * are hot enough that deriving identity from structured IR is too expensive.
+   * Structured queries should omit this so DB can derive identity directly.
+   */
+  queryKey?: LiveQueryKey
+  /** Override the nearest DbProvider for this query. */
+  client?: DbClient
+}
+
+type ConfiguredQueryBuilder<TContext extends Context> = Extract<
+  LiveQueryCollectionConfig<TContext>[`query`],
+  QueryBuilder<TContext>
+>
+
 export type UseLiveQueryConfig<TContext extends Context> =
-  LiveQueryCollectionConfig<TContext> & {
-    /**
-     * Explicit identity for queries that contain opaque functional variants or
-     * are hot enough that deriving identity from structured IR is too expensive.
-     * Structured queries should omit this so DB can derive identity directly.
-     */
-    queryKey?: LiveQueryKey
-    /** Override the nearest DbProvider for this query. */
-    client?: DbClient
+  UseLiveQueryConfigOptions<TContext> &
+    Pick<LiveQueryCollectionConfig<TContext>, `query`>
+
+export type ConditionalUseLiveQueryConfig<TContext extends Context> =
+  UseLiveQueryConfigOptions<TContext> & {
+    query:
+      | ConfiguredQueryBuilder<TContext>
+      | ((
+          q: InitialQueryBuilder,
+        ) => ConfiguredQueryBuilder<TContext> | undefined | null)
   }
 
 export function warnDeprecatedDepsArray(
@@ -297,6 +317,16 @@ function createCollectionFromPreparedQuery(value: unknown) {
  * })
  *
  * @example
+ * // Return undefined or null to disable a query
+ * const { data, isEnabled } = useLiveQuery({
+ *   query: (q) => {
+ *     if (!userId) return undefined
+ *     return q.from({ todos: todosCollection })
+ *             .where(({ todos }) => eq(todos.userId, userId))
+ *   },
+ * })
+ *
+ * @example
  * // Join pattern
  * const { data } = useLiveQuery({
  *   query: (q) =>
@@ -481,16 +511,32 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: InferResultType<TContext>
   collection: Collection<GetResult<TContext>, string | number, {}>
-  status: CollectionStatus // Can't be disabled for config objects
+  status: CollectionStatus // Can't be disabled when query always returns a builder
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
+  isEnabled: true // Always true when query always returns a builder
+}
+
+// Overload 7: Accept config object with a query that can return undefined/null
+export function useLiveQuery<TContext extends Context>(
+  config: ConditionalUseLiveQueryConfig<TContext>,
+): {
+  state: Map<string | number, GetResult<TContext>> | undefined
+  data: InferResultType<TContext> | undefined
+  collection: Collection<GetResult<TContext>, string | number, {}> | undefined
+  status: UseLiveQueryStatus
   isLoading: boolean
   isReady: boolean
   isIdle: boolean
   isError: boolean
   isCleanedUp: boolean
-  isEnabled: true // Always true for config objects
+  isEnabled: boolean
 }
 
-// Overload 7: Accept config object with legacy deps
+// Overload 8: Accept config object with legacy deps
 export function useLiveQuery<TContext extends Context>(
   config: LiveQueryCollectionConfig<TContext>,
   deps?: Array<unknown>,
@@ -498,13 +544,30 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: InferResultType<TContext>
   collection: Collection<GetResult<TContext>, string | number, {}>
-  status: CollectionStatus // Can't be disabled for config objects
+  status: CollectionStatus // Can't be disabled when query always returns a builder
   isLoading: boolean
   isReady: boolean
   isIdle: boolean
   isError: boolean
   isCleanedUp: boolean
-  isEnabled: true // Always true for config objects
+  isEnabled: true // Always true when query always returns a builder
+}
+
+// Overload 9: Accept config object with legacy deps and a query that can return undefined/null
+export function useLiveQuery<TContext extends Context>(
+  config: ConditionalUseLiveQueryConfig<TContext>,
+  deps: Array<unknown>,
+): {
+  state: Map<string | number, GetResult<TContext>> | undefined
+  data: InferResultType<TContext> | undefined
+  collection: Collection<GetResult<TContext>, string | number, {}> | undefined
+  status: UseLiveQueryStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
+  isEnabled: boolean
 }
 
 /**
@@ -536,7 +599,7 @@ export function useLiveQuery<TContext extends Context>(
  *
  * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>
  */
-// Overload 8: Accept pre-created live query collection
+// Overload 10: Accept pre-created live query collection
 export function useLiveQuery<
   TResult extends object,
   TKey extends string | number,
@@ -556,7 +619,7 @@ export function useLiveQuery<
   isEnabled: true // Always true for pre-created live query collections
 }
 
-// Overload 9: Accept pre-created live query collection with singleResult: true
+// Overload 10: Accept pre-created live query collection with singleResult: true
 export function useLiveQuery<
   TResult extends object,
   TKey extends string | number,