@tanstack/react-db/dist/cjs/useLiveInfiniteQuery.cjs.map

React integration for @tanstack/db

{"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  liveQueryWindowMatches,\n  normalizeLiveQueryWindowPageSize,\n  resolveLiveQueryWindowInput,\n  shouldPreserveLiveQueryWindowPageCount,\n} from '@tanstack/db'\nimport { useOptionalDbClient } from './DbProvider'\nimport {\n  claimSourceIds,\n  createSourceIdBindings,\n  resumeSyncStarts,\n} from './source-id-bindings'\nimport {\n  prepareDerivedQuery,\n  prepareQueryValue,\n  warnDeprecatedDepsArray,\n  warnUnhashableDerivedIdentity,\n} from './useLiveQuery'\nimport type { SourceIdBindings } from './source-id-bindings'\nimport type {\n  DerivedIdentityProfiler,\n  LiveQueryKey,\n  useLiveQuery,\n} from './useLiveQuery'\nimport type {\n  Collection,\n  CollectionImpl as CollectionImplType,\n  CollectionStatus,\n  Context,\n  DbClient,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryPersistedStatus,\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\n// Keep the generic parameter for existing typed config wrappers.\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  /** First result-page label, not a server cursor or remote offset. */\n  initialPageParam?: number\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\nexport type UseLiveInfiniteQueryReturnWithCollection<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n> = {\n  data: Array<TResult>\n  state: Map<TKey, TResult>\n  collection: Collection<TResult, TKey, TUtils> & NonSingleResult\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  persistedStatus: LiveQueryPersistedStatus\n  isPersistedReady: boolean\n  persistedError: unknown | undefined\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true\n  pages: Array<Array<TResult>>\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\ntype RenderedWindowCollection = {\n  client: DbClient | undefined\n  dependencies: Array<unknown>\n  collection: Collection<any, any, any>\n  deferredCollections: Set<\n    CollectionImplType<any, string | number, any, any, any>\n  >\n}\n\n/**\n * Whether a recorded query identity matches the current one. Legacy deps\n * compare by reference. Derived identities and query keys compare by structure.\n */\nfunction queryIdentityMatches(\n  comparison: { changed: boolean; structurallyEqual: boolean },\n  sameClient: boolean,\n  usesLegacyDeps: boolean,\n): boolean {\n  return (\n    sameClient &&\n    (usesLegacyDeps ? !comparison.changed : comparison.structurallyEqual)\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 an optional initial page label\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): UseLiveInfiniteQueryReturnWithCollection<TResult, TKey, TUtils>\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  if (`getNextPageParam` in config) {\n    throw new Error(\n      `getNextPageParam is not supported by useLiveInfiniteQuery. Use an on-demand collection and fulfill meta.loadSubsetOptions in queryFn for server pagination.`,\n    )\n  }\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  // Like useLiveQuery's instance memo, keep the window collection built by the\n  // latest render. A second render before commit, such as a StrictMode double\n  // render, reuses it instead of starting another one. Only the collection is\n  // kept. Each render still builds its own controller and page count from the\n  // committed state, which an uncommitted render never changes.\n  const renderedCollectionRef = useRef<RenderedWindowCollection | null>(null)\n  const sourceIdsRef = useRef<SourceIdBindings | null>(null)\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      claimSourceIds(\n        (sourceIdsRef.current ??= createSourceIdBindings()),\n        preparation.value,\n        dbClient,\n        `useLiveInfiniteQuery`,\n        () => resumeSyncStarts(deferredCollections),\n      )\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    !queryIdentityMatches(dependencyComparison, sameClient, usesLegacyDeps)\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    let startInRender = false\n    let suppliedCollection = false\n    let createdCollection = false\n\n    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({\n      hasPreviousController: committed !== null,\n      previousInputKind: committed?.inputKind,\n      inputKind,\n      sameCollection:\n        inputIsCollection && committed?.inputCollection === queryFnOrCollection,\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    // The peek-ahead window for every retained page.\n    const requiredLimit = initialPageCount * pageSize + 1\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 rendered = renderedCollectionRef.current\n      if (\n        !inputIsCollection &&\n        rendered !== null &&\n        queryIdentityMatches(\n          compareLiveQueryWindowDependencies(\n            rendered.dependencies,\n            identityDeps,\n          ),\n          rendered.client === dbClient,\n          usesLegacyDeps,\n        ) &&\n        rendered.collection.status !== `cleaned-up` &&\n        rendered.collection.status !== `error` &&\n        liveQueryWindowMatches(rendered.collection, requiredLimit)\n      ) {\n        // An earlier render built this collection and nothing has committed\n        // since. Its window is exactly the retained pages, so its first\n        // rows are correct. Sources it deferred still resume at commit. A\n        // collection in terminal error, such as after its source restarted,\n        // cannot serve the query again, so a new one replaces it.\n        collection = rendered.collection\n        for (const deferred of rendered.deferredCollections) {\n          deferredCollections.add(deferred)\n        }\n      } else {\n        const input = resolveLiveQueryWindowInput<TContext>(inputValue)\n        if (input.kind === `collection`) {\n          collection = input.collection\n          suppliedCollection = true\n          // A supplied collection is never reused, so release the last one.\n          renderedCollectionRef.current = null\n        } else {\n          // Wrap the query with the peek-ahead window for every retained page,\n          // so a collection that starts syncing now never publishes fewer rows\n          // than the controller's pages. The controller grows the limit via\n          // setWindow.\n          collection = createLiveQueryCollection({\n            query: input.query.limit(requiredLimit).offset(0),\n            gcTime: DEFAULT_GC_TIME_MS,\n          })\n          startInRender = true\n          createdCollection = true\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    // Like useLiveQuery, start sync during render once the input is valid. A\n    // render reads only rows the sources already hold, such as a preloaded\n    // collection's, and sends no request until the subscription commits. GC\n    // reclaims a render that never commits. A supplied window that the\n    // controller must still adjust waits for the subscription.\n    if (suppliedCollection) {\n      startInRender = liveQueryWindowMatches(collection, requiredLimit)\n    }\n    if (startInRender) collection.startSyncImmediate()\n    // Keep a created collection for the next render only once it validated and\n    // started, so a retry after a startup error builds a new one and throws.\n    if (createdCollection) {\n      renderedCollectionRef.current = {\n        client: dbClient,\n        dependencies: [...identityDeps],\n        collection,\n        deferredCollections,\n      }\n    }\n\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      resumeSyncStarts(currentRenderState.deferredCollections)\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    get state() {\n      return snapshot.state as EnabledLiveQueryReturn<TContext>[`state`]\n    },\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    persistedStatus: snapshot.persistedStatus,\n    isPersistedReady: snapshot.isPersistedReady,\n    persistedError: snapshot.persistedError,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled: 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","claimSourceIds","warnUnhashableDerivedIdentity","compareLiveQueryWindowDependencies","prepareQueryValue","assertLiveQueryWindowManyResult","useCallback","resumeSyncStarts"],"mappings":";;;;;;;;AAiDA;AACA;AA2FA;AAKE;AAIF;AAgCO;AAKL;AACE;AAAU;AACR;AAAA;AAGJ;AACA;AACA;AACA;AAEA;AAGA;AACA;AAMA;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;AACAC;AAAAA;AAC4B;AACd;AACZ;AACA;AAC0C;AAE5C;AACE;AAA2B;AAE3BC;AACA;AAA2C;AAC7C;AACF;AAGF;AAEA;AAA6BC;AAChB;AACX;AAEF;AACA;AAGA;AAEA;AAKA;AAIA;AAGA;AACA;AACE;AACA;AACA;AACA;AACA;AAEA;AAAoE;AAC7B;AACP;AAC9B;AAEsD;AACtD;AACA;AACA;AAEF;AAGA;AAEA;AAEA;AACE;AACA;AACE;AACE;AAAqBC;AACnB;AACA;AACA;AAAA;AAGJ;AAAmB;AAErB;AACA;AAGE;AACED;AACW;AACT;AAAA;AAEkB;AACpB;AAWF;AACA;AACE;AAAgC;AAClC;AAEA;AACA;AACE;AACA;AAEA;AAAgC;AAMhC;AAAuC;AACW;AACxC;AAEV;AACA;AAAoB;AACtB;AACF;AAGF;AACE;AAAsE;AAGxE;AACE;AACmE;AAEnEE;AAA0C;AAO5C;AACE;AAAgE;AAElE;AAGA;AACE;AAAgC;AACtB;AACsB;AAC9B;AACA;AAAA;AAIJ;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;AAEzCC;AACA;AAAO;AACT;AAC+B;AAEjC;AACA;AAEA;AAAsBD;AACyB;AAClC;AAGb;AAAO;AACU;AAEb;AAAgB;AAClB;AACiB;AACG;AACF;AACQ;AACC;AACF;AACR;AACC;AACI;AAEX;AACS;AACJ;AACK;AACrB;AACsB;AACO;AACb;AAEpB;;"}