@ttt-productions/query-core 0.14.22 → 0.14.24

package/dist/react/callables/create-callables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-callables.js","sourceRoot":"","sources":["../../../src/react/callables/create-callables.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useCallback, useMemo, useRef } from 'react';\nimport type { UseMutationResult } from '@tanstack/react-query';\nimport type { ExpectedCallableAnswerCode } from '@ttt-productions/firebase-helpers';\nimport {\n  callCallable,\n  isRecoveredFallbackReport,\n  type FunctionsProvider,\n} from '@ttt-productions/firebase-helpers/client';\nimport {\n  useMutationSessionCapture,\n  useSessionMutation,\n  type MutationSession,\n  type SessionMutationOptions,\n} from '../session-mutation.js';\n\nexport interface CallableErrorRouting {\n  showErrorToast: boolean;\n  answeredRefusals: readonly ExpectedCallableAnswerCode[];\n  isAnswerSurfacedByCaller?: (error: unknown) => boolean;\n}\n\nexport type CallableCaptureContext = Record<string, unknown>;\n\nexport interface CallablePolicy {\n  getFunctions: FunctionsProvider;\n  timeoutMs: number;\n  resolveLimitedUseAppCheck: (requested: boolean) => boolean;\n  captureFault: (error: unknown, context: CallableCaptureContext) => void;\n  captureRecoveredFallback: (error: unknown, context: CallableCaptureContext) => void;\n  onActionError: (error: unknown, routing: CallableErrorRouting) => void;\n}\n\nexport interface CallableDeclaration {\n  limitedUseAppCheck?: true;\n}\n\ninterface CallableTransportOptions extends Partial<CallableErrorRouting> {\n  captureFaults?: boolean;\n}\n\nexport type CallableMutationOptions<TInput, TResult, TOnMutateResult = unknown> = Omit<\n  SessionMutationOptions<TResult, Error, TInput, TOnMutateResult>,\n  'mutationFn' | 'retry'\n> &\n  Pick<\n    CallableTransportOptions,\n    'showErrorToast' | 'answeredRefusals' | 'isAnswerSurfacedByCaller' | 'captureFaults'\n  >;\n\nexport const MAX_RESUMABLE_CALLS = 12;\n\nexport type ResumableOutcome<TResult> = TResult & { interruption: Error | null };\n\nexport interface Callables {\n  createCallableHook<TInput, TResult>(\n    functionName: string,\n    declaration?: CallableDeclaration,\n  ): <TOnMutateResult = unknown>(\n    options?: CallableMutationOptions<TInput, TResult, TOnMutateResult>,\n  ) => UseMutationResult<TResult, Error, TInput, TOnMutateResult>;\n  createResumableCallableHook<TInput, TResult extends { complete: boolean }>(\n    functionName: string,\n    merge: (earlier: TResult, later: TResult) => TResult,\n    declaration?: CallableDeclaration,\n  ): <TOnMutateResult = unknown>(\n    options?: CallableMutationOptions<TInput, ResumableOutcome<TResult>, TOnMutateResult>,\n  ) => UseMutationResult<ResumableOutcome<TResult>, Error, TInput, TOnMutateResult>;\n  createCallableReader<TInput, TResult>(\n    functionName: string,\n    declaration?: CallableDeclaration,\n  ): () => (input: TInput) => Promise<TResult>;\n  createCallableInvoker<TInput, TResult>(\n    functionName: string,\n    declaration?: CallableDeclaration,\n  ): () => (input: TInput) => Promise<TResult>;\n}\n\ntype CallableTransport = <TInput, TResult>(\n  input: TInput,\n  session: MutationSession,\n) => Promise<TResult>;\n\nexport function createCallables(policy: CallablePolicy): Callables {\n  function useCallableTransport(\n    functionName: string,\n    declaration: CallableDeclaration,\n    options: CallableTransportOptions,\n  ): CallableTransport {\n    const optionsRef = useRef(options);\n    optionsRef.current = options;\n    const limitedUseAppCheck = policy.resolveLimitedUseAppCheck(\n      declaration.limitedUseAppCheck === true,\n    );\n\n    return useCallback(\n      <TInput, TResult>(input: TInput, session: MutationSession) =>\n        callCallable<TInput, TResult>(\n          policy.getFunctions,\n          functionName,\n          input,\n          {\n            captureException: (error, context) => {\n              if (optionsRef.current.captureFaults !== false) policy.captureFault(error, context);\n              else if (isRecoveredFallbackReport(context))\n                policy.captureRecoveredFallback(error, context);\n            },\n            onError: (error) => {\n              if (!session.isCurrent()) return;\n              const {\n                showErrorToast = true,\n                answeredRefusals = [],\n                isAnswerSurfacedByCaller,\n              } = optionsRef.current;\n              policy.onActionError(error, {\n                showErrorToast,\n                answeredRefusals,\n                isAnswerSurfacedByCaller,\n              });\n            },\n          },\n          { timeoutMs: policy.timeoutMs, limitedUseAppCheck },\n        ),\n      [functionName, limitedUseAppCheck],\n    );\n  }\n\n  function useSessionBoundCall<TInput, TResult>(\n    call: CallableTransport,\n  ): (input: TInput) => Promise<TResult> {\n    const captureSession = useMutationSessionCapture();\n    return useMemo(\n      () => (input: TInput) => call<TInput, TResult>(input, captureSession()),\n      [call, captureSession],\n    );\n  }\n\n  return {\n    createCallableHook<TInput, TResult>(\n      functionName: string,\n      declaration: CallableDeclaration = {},\n    ) {\n      return function useNamedCallable<TOnMutateResult = unknown>(\n        options: CallableMutationOptions<TInput, TResult, TOnMutateResult> = {},\n      ): UseMutationResult<TResult, Error, TInput, TOnMutateResult> {\n        const {\n          showErrorToast,\n          answeredRefusals,\n          isAnswerSurfacedByCaller,\n          captureFaults,\n          ...mutationOptions\n        } = options;\n        const call = useCallableTransport(functionName, declaration, {\n          showErrorToast,\n          answeredRefusals,\n          isAnswerSurfacedByCaller,\n          captureFaults,\n        });\n        // `retry: false` comes last so nothing overrides it: a deadline expiry is an unknown outcome,\n        // and a retry after a committed first attempt writes twice.\n        return useSessionMutation<TResult, Error, TInput, TOnMutateResult>({\n          ...mutationOptions,\n          retry: false,\n          mutationFn: (input, { session }) => call<TInput, TResult>(input, session),\n        });\n      };\n    },\n\n    createResumableCallableHook<TInput, TResult extends { complete: boolean }>(\n      functionName: string,\n      merge: (earlier: TResult, later: TResult) => TResult,\n      declaration: CallableDeclaration = {},\n    ) {\n      return function useNamedResumableCallable<TOnMutateResult = unknown>(\n        options: CallableMutationOptions<TInput, ResumableOutcome<TResult>, TOnMutateResult> = {},\n      ): UseMutationResult<ResumableOutcome<TResult>, Error, TInput, TOnMutateResult> {\n        const {\n          showErrorToast,\n          answeredRefusals,\n          isAnswerSurfacedByCaller,\n          captureFaults,\n          ...mutationOptions\n        } = options;\n        const call = useCallableTransport(functionName, declaration, {\n          showErrorToast,\n          answeredRefusals,\n          isAnswerSurfacedByCaller,\n          captureFaults,\n        });\n        return useSessionMutation<ResumableOutcome<TResult>, Error, TInput, TOnMutateResult>({\n          ...mutationOptions,\n          retry: false,\n          mutationFn: async (input, { session }): Promise<ResumableOutcome<TResult>> => {\n            let progress = await call<TInput, TResult>(input, session);\n            for (let calls = 1; !progress.complete && calls < MAX_RESUMABLE_CALLS; calls += 1) {\n              session.assertCurrent();\n              let later: TResult;\n              try {\n                later = await call<TInput, TResult>(input, session);\n              } catch (error) {\n                const interruption = error instanceof Error ? error : new Error(String(error));\n                return { ...progress, complete: false, interruption };\n              }\n              progress = merge(progress, later);\n            }\n            return { ...progress, interruption: null };\n          },\n        });\n      };\n    },\n\n    createCallableReader<TInput, TResult>(\n      functionName: string,\n      declaration: CallableDeclaration = {},\n    ) {\n      return function useNamedCallableReader(): (input: TInput) => Promise<TResult> {\n        const call = useCallableTransport(functionName, declaration, {\n          showErrorToast: false,\n          captureFaults: false,\n        });\n        return useSessionBoundCall<TInput, TResult>(call);\n      };\n    },\n\n    createCallableInvoker<TInput, TResult>(\n      functionName: string,\n      declaration: CallableDeclaration = {},\n    ) {\n      return function useNamedCallableInvoker(): (input: TInput) => Promise<TResult> {\n        const call = useCallableTransport(functionName, declaration, {});\n        return useSessionBoundCall<TInput, TResult>(call);\n      };\n    },\n  };\n}\n"]}

package/dist/react/defaults.d.ts

@@ -1,8 +1,4 @@
 import type { DefaultOptions, QueryClientConfig } from '@tanstack/react-query';
-/**
- * Small, conservative defaults intended to work well across apps.
- * Apps can override via `createQueryClient({ defaultOptions: ... })`.
- */
 export declare const defaultQueryOptions: DefaultOptions;
 export declare const defaultQueryClientConfig: QueryClientConfig;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/react/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/react/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAcjC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,iBAEtC,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/react/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/E,eAAO,MAAM,mBAAmB,EAAE,cAcjC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,iBAEtC,CAAC"}

package/dist/react/defaults.js

@@ -1,14 +1,10 @@
-/**
- * Small, conservative defaults intended to work well across apps.
- * Apps can override via `createQueryClient({ defaultOptions: ... })`.
- */
 export const defaultQueryOptions = {
     queries: {
         refetchOnWindowFocus: false,
         refetchOnReconnect: true,
         refetchOnMount: false,
-        staleTime: 30_000, // 30s
-        gcTime: 5 * 60_000, // 5m
+        staleTime: 30_000,
+        gcTime: 5 * 60_000,
         retry: (failureCount) => failureCount < 2,
     },
     mutations: {

package/dist/react/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/react/defaults.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAmB;IACjD,OAAO,EAAE;QACP,oBAAoB,EAAE,KAAK;QAC3B,kBAAkB,EAAE,IAAI;QACxB,cAAc,EAAE,KAAK;QAErB,SAAS,EAAE,MAAM,EAAE,MAAM;QACzB,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,KAAK;QAEzB,KAAK,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,GAAG,CAAC;KAC1C;IACD,SAAS,EAAE;QACT,KAAK,EAAE,CAAC;KACT;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAsB;IACzD,cAAc,EAAE,mBAAmB;CACpC,CAAC","sourcesContent":["import type { DefaultOptions, QueryClientConfig } from '@tanstack/react-query';\n\n/**\n * Small, conservative defaults intended to work well across apps.\n * Apps can override via `createQueryClient({ defaultOptions: ... })`.\n */\nexport const defaultQueryOptions: DefaultOptions = {\n  queries: {\n    refetchOnWindowFocus: false,\n    refetchOnReconnect: true,\n    refetchOnMount: false,\n\n    staleTime: 30_000, // 30s\n    gcTime: 5 * 60_000, // 5m\n\n    retry: (failureCount) => failureCount < 2,\n  },\n  mutations: {\n    retry: 0,\n  },\n};\n\nexport const defaultQueryClientConfig: QueryClientConfig = {\n  defaultOptions: defaultQueryOptions,\n};\n"]}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/react/defaults.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,mBAAmB,GAAmB;IACjD,OAAO,EAAE;QACP,oBAAoB,EAAE,KAAK;QAC3B,kBAAkB,EAAE,IAAI;QACxB,cAAc,EAAE,KAAK;QAErB,SAAS,EAAE,MAAM;QACjB,MAAM,EAAE,CAAC,GAAG,MAAM;QAElB,KAAK,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,GAAG,CAAC;KAC1C;IACD,SAAS,EAAE;QACT,KAAK,EAAE,CAAC;KACT;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAsB;IACzD,cAAc,EAAE,mBAAmB;CACpC,CAAC","sourcesContent":["import type { DefaultOptions, QueryClientConfig } from '@tanstack/react-query';\n\nexport const defaultQueryOptions: DefaultOptions = {\n  queries: {\n    refetchOnWindowFocus: false,\n    refetchOnReconnect: true,\n    refetchOnMount: false,\n\n    staleTime: 30_000,\n    gcTime: 5 * 60_000,\n\n    retry: (failureCount) => failureCount < 2,\n  },\n  mutations: {\n    retry: 0,\n  },\n};\n\nexport const defaultQueryClientConfig: QueryClientConfig = {\n  defaultOptions: defaultQueryOptions,\n};\n"]}

package/dist/react/domain-events/cache-invalidation.d.ts

@@ -1,12 +1,5 @@
 import type { Query, QueryClient, QueryKey } from '@tanstack/react-query';
 export type RefetchType = 'active' | 'all' | 'none';
-/**
- * What an entry does to the queries it matches:
- * - `"refresh"` (the default) marks them stale and refetches per `refetchType`;
- * - `"remove"` cancels them and drops them from the cache — for data that no longer exists, or a
- *   held answer that must not be served again;
- * - `"reset"` returns them to their initial state and refetches the active ones from scratch.
- */
 export type CacheAction = 'refresh' | 'remove' | 'reset';
 export type CacheInvalidation = {
     kind: 'exact';
@@ -25,7 +18,6 @@ export type CacheInvalidation = {
     refetchType?: RefetchType;
     action?: CacheAction;
 };
-/** `refetchType` belongs to a refresh; a remove or reset takes none. */
 type EntryOptions = {
     refetchType?: RefetchType;
     action?: 'refresh';
@@ -36,35 +28,6 @@ export declare function exact(queryKey: QueryKey, opts?: EntryOptions): CacheInv
 export declare function prefix(queryKey: QueryKey, opts?: EntryOptions): CacheInvalidation;
 export declare function predicate(description: string, match: (query: Query) => boolean, opts?: EntryOptions): CacheInvalidation;
 export declare function serializeInvalidation(inv: CacheInvalidation): string;
-/**
- * Dispatch a deduplicated list of cache invalidations.
- *
- * Returns a promise that resolves once every `invalidateQueries` call it issued
- * has settled — i.e. once the refetches those invalidations triggered have
- * landed. The dispatch itself stays synchronous (every cancellation and
- * invalidation is issued before this function returns), so a fire-and-forget
- * caller can ignore the promise, while a mutation `onSuccess` that
- * RETURNS or awaits the promise stays pending until the refreshed data is in
- * the cache. The promise never rejects: `invalidateQueries` refetches without
- * `throwOnError`, so a failed refetch surfaces on its own query, never as a
- * failure of the committed action that triggered it. The scoped
- * `cancelQueries` calls stay fire-and-forget — cancellation takes effect
- * synchronously and is not part of the refresh being awaited.
- *
- * Before each invalidation, any query it matches that is mid-PENDING-INITIAL-READ
- * is cancelled (see `cancelPendingInitialReads`) so a read that started before
- * the write committed can never land as the query's first — and freshly-marked —
- * value.
- *
- * `refetchType` governs whether that cancellation happens:
- * - `'active'` (the default) and `'all'` cancel-then-invalidate every matched
- *   pending initial read — including one TanStack's refetch pass will not
- *   restart, since a stale first value would otherwise land and mark the query
- *   fresh, while a cancelled one simply refetches for its next observer.
- * - `'none'` invalidates WITHOUT cancelling: the caller has asked for no
- *   refetch at all, so cancelling would abandon the only in-flight read the
- *   consumer has and leave it with no data and no pending request.
- */
 export declare function applyInvalidations(queryClient: QueryClient, invalidations: ReadonlyArray<CacheInvalidation>): Promise<void>;
 export {};
 //# sourceMappingURL=cache-invalidation.d.ts.map

package/dist/react/domain-events/cache-invalidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-invalidation.d.ts","sourceRoot":"","sources":["../../../src/react/domain-events/cache-invalidation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAgB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAExF,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACvF;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACjC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEN,wEAAwE;AACxE,KAAK,YAAY,GACf;IAAE,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,CAAC;AAOrF,wBAAgB,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAEhF;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAEjF;AAED,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,EAChC,IAAI,CAAC,EAAE,YAAY,GAClB,iBAAiB,CAEnB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAIpE;AA4CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAiCf"}
+{"version":3,"file":"cache-invalidation.d.ts","sourceRoot":"","sources":["../../../src/react/domain-events/cache-invalidation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAgB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAExF,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACvF;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACjC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEN,KAAK,YAAY,GACf;IAAE,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,CAAC;AAOrF,wBAAgB,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAEhF;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAEjF;AAED,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,EAChC,IAAI,CAAC,EAAE,YAAY,GAClB,iBAAiB,CAEnB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAIpE;AA0BD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAC9C,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/react/domain-events/cache-invalidation.js

@@ -17,7 +17,6 @@ export function serializeInvalidation(inv) {
         return `${action}predicate:${inv.description}`;
     return `${action}${inv.kind}:${JSON.stringify(inv.queryKey)}`;
 }
-/** The cache filter that selects exactly the queries one invalidation targets. */
 function invalidationFilters(inv) {
     if (inv.kind === 'exact')
         return { queryKey: inv.queryKey, exact: true };
@@ -26,20 +25,8 @@ function invalidationFilters(inv) {
     return { predicate: inv.match };
 }
 /**
- * Cancel every query matched by `filters` that is in a PENDING INITIAL READ —
- * currently fetching with no data yet.
- *
- * TanStack's `Query.fetch` only cancels a running request on refetch when the
- * query already holds data; an initial fetch in flight is REUSED instead, so
- * the invalidation's refetch resolves with the value the server returned BEFORE
- * the mutation committed and then marks the query fresh. Cancelling first makes
- * the invalidation's refetch a genuinely new request: the retryer is rejected
- * synchronously (its `onCancel` reverts state to idle in the same tick), so the
- * `invalidateQueries` call that follows starts a fresh fetch, and the abandoned
- * promise's late, stale resolution is discarded.
- *
- * Cancellation is always scoped to one concrete query key — never a bare
- * `cancelQueries()`.
+ * TanStack's `Query.fetch` reuses an in-flight initial fetch instead of cancelling it, so without
+ * this cancel the invalidation would resolve with the value read before the mutation committed.
  */
 function cancelPendingInitialReads(queryClient, filters) {
     for (const query of queryClient.getQueryCache().findAll(filters)) {
@@ -50,45 +37,11 @@ function cancelPendingInitialReads(queryClient, filters) {
         void queryClient.cancelQueries({ queryKey: query.queryKey, exact: true });
     }
 }
-/**
- * Exactly the queries `filters` matches now. A remove or reset acts in two steps — cancel then
- * remove, reset then refetch — and the first step changes the state a predicate may read (a reset
- * clears the failure, a cancel idles the fetch), so the second step re-applying the filter would
- * miss the queries the entry matched.
- */
+/** A cancel or reset changes the state a predicate reads, so the second step must not re-apply the filter. */
 function matchedNow(queryClient, filters) {
     const matched = new Set(queryClient.getQueryCache().findAll(filters));
     return { predicate: (query) => matched.has(query) };
 }
-/**
- * Dispatch a deduplicated list of cache invalidations.
- *
- * Returns a promise that resolves once every `invalidateQueries` call it issued
- * has settled — i.e. once the refetches those invalidations triggered have
- * landed. The dispatch itself stays synchronous (every cancellation and
- * invalidation is issued before this function returns), so a fire-and-forget
- * caller can ignore the promise, while a mutation `onSuccess` that
- * RETURNS or awaits the promise stays pending until the refreshed data is in
- * the cache. The promise never rejects: `invalidateQueries` refetches without
- * `throwOnError`, so a failed refetch surfaces on its own query, never as a
- * failure of the committed action that triggered it. The scoped
- * `cancelQueries` calls stay fire-and-forget — cancellation takes effect
- * synchronously and is not part of the refresh being awaited.
- *
- * Before each invalidation, any query it matches that is mid-PENDING-INITIAL-READ
- * is cancelled (see `cancelPendingInitialReads`) so a read that started before
- * the write committed can never land as the query's first — and freshly-marked —
- * value.
- *
- * `refetchType` governs whether that cancellation happens:
- * - `'active'` (the default) and `'all'` cancel-then-invalidate every matched
- *   pending initial read — including one TanStack's refetch pass will not
- *   restart, since a stale first value would otherwise land and mark the query
- *   fresh, while a cancelled one simply refetches for its next observer.
- * - `'none'` invalidates WITHOUT cancelling: the caller has asked for no
- *   refetch at all, so cancelling would abandon the only in-flight read the
- *   consumer has and leave it with no data and no pending request.
- */
 export function applyInvalidations(queryClient, invalidations) {
     const seen = new Set();
     const refreshes = [];
@@ -101,9 +54,7 @@ export function applyInvalidations(queryClient, invalidations) {
         const action = inv.action ?? 'refresh';
         if (action === 'remove') {
             const matched = matchedNow(queryClient, filters);
-            // Removing a query abandons its read in flight silently, so that read never puts the dropped
-            // answer back, but a screen still watching it would go on showing it as fetching. Cancelled
-            // first, the read ends visibly and the watcher reads idle.
+            // Removing a query abandons its in-flight read silently, leaving a watching screen on fetching; cancelling first ends it visibly.
             void queryClient.cancelQueries(matched);
             queryClient.removeQueries(matched);
             continue;

package/dist/react/domain-events/cache-invalidation.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-invalidation.js","sourceRoot":"","sources":["../../../src/react/domain-events/cache-invalidation.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Query, QueryClient, QueryFilters, QueryKey } from '@tanstack/react-query';\n\nexport type RefetchType = 'active' | 'all' | 'none';\n\n/**\n * What an entry does to the queries it matches:\n * - `\"refresh\"` (the default) marks them stale and refetches per `refetchType`;\n * - `\"remove\"` cancels them and drops them from the cache — for data that no longer exists, or a\n *   held answer that must not be served again;\n * - `\"reset\"` returns them to their initial state and refetches the active ones from scratch.\n */\nexport type CacheAction = 'refresh' | 'remove' | 'reset';\n\nexport type CacheInvalidation =\n  | { kind: 'exact'; queryKey: QueryKey; refetchType?: RefetchType; action?: CacheAction }\n  | { kind: 'prefix'; queryKey: QueryKey; refetchType?: RefetchType; action?: CacheAction }\n  | {\n      kind: 'predicate';\n      description: string;\n      match: (query: Query) => boolean;\n      refetchType?: RefetchType;\n      action?: CacheAction;\n    };\n\n/** `refetchType` belongs to a refresh; a remove or reset takes none. */\ntype EntryOptions =\n  { refetchType?: RefetchType; action?: 'refresh' } | { action: 'remove' | 'reset' };\n\nconst entryFields = (opts?: EntryOptions) => ({\n  refetchType: opts && 'refetchType' in opts ? opts.refetchType : undefined,\n  action: opts?.action,\n});\n\nexport function exact(queryKey: QueryKey, opts?: EntryOptions): CacheInvalidation {\n  return { kind: 'exact', queryKey, ...entryFields(opts) };\n}\n\nexport function prefix(queryKey: QueryKey, opts?: EntryOptions): CacheInvalidation {\n  return { kind: 'prefix', queryKey, ...entryFields(opts) };\n}\n\nexport function predicate(\n  description: string,\n  match: (query: Query) => boolean,\n  opts?: EntryOptions,\n): CacheInvalidation {\n  return { kind: 'predicate', description, match, ...entryFields(opts) };\n}\n\nexport function serializeInvalidation(inv: CacheInvalidation): string {\n  const action = inv.action && inv.action !== 'refresh' ? `${inv.action}:` : '';\n  if (inv.kind === 'predicate') return `${action}predicate:${inv.description}`;\n  return `${action}${inv.kind}:${JSON.stringify(inv.queryKey)}`;\n}\n\n/** The cache filter that selects exactly the queries one invalidation targets. */\nfunction invalidationFilters(inv: CacheInvalidation): QueryFilters {\n  if (inv.kind === 'exact') return { queryKey: inv.queryKey, exact: true };\n  if (inv.kind === 'prefix') return { queryKey: inv.queryKey, exact: false };\n  return { predicate: inv.match };\n}\n\n/**\n * Cancel every query matched by `filters` that is in a PENDING INITIAL READ —\n * currently fetching with no data yet.\n *\n * TanStack's `Query.fetch` only cancels a running request on refetch when the\n * query already holds data; an initial fetch in flight is REUSED instead, so\n * the invalidation's refetch resolves with the value the server returned BEFORE\n * the mutation committed and then marks the query fresh. Cancelling first makes\n * the invalidation's refetch a genuinely new request: the retryer is rejected\n * synchronously (its `onCancel` reverts state to idle in the same tick), so the\n * `invalidateQueries` call that follows starts a fresh fetch, and the abandoned\n * promise's late, stale resolution is discarded.\n *\n * Cancellation is always scoped to one concrete query key — never a bare\n * `cancelQueries()`.\n */\nfunction cancelPendingInitialReads(queryClient: QueryClient, filters: QueryFilters): void {\n  for (const query of queryClient.getQueryCache().findAll(filters)) {\n    if (query.state.fetchStatus !== 'fetching') continue;\n    if (query.state.data !== undefined) continue;\n    void queryClient.cancelQueries({ queryKey: query.queryKey, exact: true });\n  }\n}\n\n/**\n * Exactly the queries `filters` matches now. A remove or reset acts in two steps — cancel then\n * remove, reset then refetch — and the first step changes the state a predicate may read (a reset\n * clears the failure, a cancel idles the fetch), so the second step re-applying the filter would\n * miss the queries the entry matched.\n */\nfunction matchedNow(queryClient: QueryClient, filters: QueryFilters): QueryFilters {\n  const matched = new Set(queryClient.getQueryCache().findAll(filters));\n  return { predicate: (query) => matched.has(query) };\n}\n\n/**\n * Dispatch a deduplicated list of cache invalidations.\n *\n * Returns a promise that resolves once every `invalidateQueries` call it issued\n * has settled — i.e. once the refetches those invalidations triggered have\n * landed. The dispatch itself stays synchronous (every cancellation and\n * invalidation is issued before this function returns), so a fire-and-forget\n * caller can ignore the promise, while a mutation `onSuccess` that\n * RETURNS or awaits the promise stays pending until the refreshed data is in\n * the cache. The promise never rejects: `invalidateQueries` refetches without\n * `throwOnError`, so a failed refetch surfaces on its own query, never as a\n * failure of the committed action that triggered it. The scoped\n * `cancelQueries` calls stay fire-and-forget — cancellation takes effect\n * synchronously and is not part of the refresh being awaited.\n *\n * Before each invalidation, any query it matches that is mid-PENDING-INITIAL-READ\n * is cancelled (see `cancelPendingInitialReads`) so a read that started before\n * the write committed can never land as the query's first — and freshly-marked —\n * value.\n *\n * `refetchType` governs whether that cancellation happens:\n * - `'active'` (the default) and `'all'` cancel-then-invalidate every matched\n *   pending initial read — including one TanStack's refetch pass will not\n *   restart, since a stale first value would otherwise land and mark the query\n *   fresh, while a cancelled one simply refetches for its next observer.\n * - `'none'` invalidates WITHOUT cancelling: the caller has asked for no\n *   refetch at all, so cancelling would abandon the only in-flight read the\n *   consumer has and leave it with no data and no pending request.\n */\nexport function applyInvalidations(\n  queryClient: QueryClient,\n  invalidations: ReadonlyArray<CacheInvalidation>,\n): Promise<void> {\n  const seen = new Set<string>();\n  const refreshes: Promise<void>[] = [];\n  for (const inv of invalidations) {\n    const sig = serializeInvalidation(inv);\n    if (seen.has(sig)) continue;\n    seen.add(sig);\n\n    const filters = invalidationFilters(inv);\n    const action: CacheAction = inv.action ?? 'refresh';\n\n    if (action === 'remove') {\n      const matched = matchedNow(queryClient, filters);\n      // Removing a query abandons its read in flight silently, so that read never puts the dropped\n      // answer back, but a screen still watching it would go on showing it as fetching. Cancelled\n      // first, the read ends visibly and the watcher reads idle.\n      void queryClient.cancelQueries(matched);\n      queryClient.removeQueries(matched);\n      continue;\n    }\n    if (action === 'reset') {\n      refreshes.push(queryClient.resetQueries(matchedNow(queryClient, filters)));\n      continue;\n    }\n\n    const refetchType: RefetchType = inv.refetchType ?? 'active';\n    if (refetchType !== 'none') {\n      cancelPendingInitialReads(queryClient, filters);\n    }\n\n    refreshes.push(queryClient.invalidateQueries({ ...filters, refetchType }));\n  }\n  return Promise.all(refreshes).then(() => undefined);\n}\n"]}
+{"version":3,"file":"cache-invalidation.js","sourceRoot":"","sources":["../../../src/react/domain-events/cache-invalidation.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Query, QueryClient, QueryFilters, QueryKey } from '@tanstack/react-query';\n\nexport type RefetchType = 'active' | 'all' | 'none';\n\nexport type CacheAction = 'refresh' | 'remove' | 'reset';\n\nexport type CacheInvalidation =\n  | { kind: 'exact'; queryKey: QueryKey; refetchType?: RefetchType; action?: CacheAction }\n  | { kind: 'prefix'; queryKey: QueryKey; refetchType?: RefetchType; action?: CacheAction }\n  | {\n      kind: 'predicate';\n      description: string;\n      match: (query: Query) => boolean;\n      refetchType?: RefetchType;\n      action?: CacheAction;\n    };\n\ntype EntryOptions =\n  { refetchType?: RefetchType; action?: 'refresh' } | { action: 'remove' | 'reset' };\n\nconst entryFields = (opts?: EntryOptions) => ({\n  refetchType: opts && 'refetchType' in opts ? opts.refetchType : undefined,\n  action: opts?.action,\n});\n\nexport function exact(queryKey: QueryKey, opts?: EntryOptions): CacheInvalidation {\n  return { kind: 'exact', queryKey, ...entryFields(opts) };\n}\n\nexport function prefix(queryKey: QueryKey, opts?: EntryOptions): CacheInvalidation {\n  return { kind: 'prefix', queryKey, ...entryFields(opts) };\n}\n\nexport function predicate(\n  description: string,\n  match: (query: Query) => boolean,\n  opts?: EntryOptions,\n): CacheInvalidation {\n  return { kind: 'predicate', description, match, ...entryFields(opts) };\n}\n\nexport function serializeInvalidation(inv: CacheInvalidation): string {\n  const action = inv.action && inv.action !== 'refresh' ? `${inv.action}:` : '';\n  if (inv.kind === 'predicate') return `${action}predicate:${inv.description}`;\n  return `${action}${inv.kind}:${JSON.stringify(inv.queryKey)}`;\n}\n\nfunction invalidationFilters(inv: CacheInvalidation): QueryFilters {\n  if (inv.kind === 'exact') return { queryKey: inv.queryKey, exact: true };\n  if (inv.kind === 'prefix') return { queryKey: inv.queryKey, exact: false };\n  return { predicate: inv.match };\n}\n\n/**\n * TanStack's `Query.fetch` reuses an in-flight initial fetch instead of cancelling it, so without\n * this cancel the invalidation would resolve with the value read before the mutation committed.\n */\nfunction cancelPendingInitialReads(queryClient: QueryClient, filters: QueryFilters): void {\n  for (const query of queryClient.getQueryCache().findAll(filters)) {\n    if (query.state.fetchStatus !== 'fetching') continue;\n    if (query.state.data !== undefined) continue;\n    void queryClient.cancelQueries({ queryKey: query.queryKey, exact: true });\n  }\n}\n\n/** A cancel or reset changes the state a predicate reads, so the second step must not re-apply the filter. */\nfunction matchedNow(queryClient: QueryClient, filters: QueryFilters): QueryFilters {\n  const matched = new Set(queryClient.getQueryCache().findAll(filters));\n  return { predicate: (query) => matched.has(query) };\n}\n\nexport function applyInvalidations(\n  queryClient: QueryClient,\n  invalidations: ReadonlyArray<CacheInvalidation>,\n): Promise<void> {\n  const seen = new Set<string>();\n  const refreshes: Promise<void>[] = [];\n  for (const inv of invalidations) {\n    const sig = serializeInvalidation(inv);\n    if (seen.has(sig)) continue;\n    seen.add(sig);\n\n    const filters = invalidationFilters(inv);\n    const action: CacheAction = inv.action ?? 'refresh';\n\n    if (action === 'remove') {\n      const matched = matchedNow(queryClient, filters);\n      // Removing a query abandons its in-flight read silently, leaving a watching screen on fetching; cancelling first ends it visibly.\n      void queryClient.cancelQueries(matched);\n      queryClient.removeQueries(matched);\n      continue;\n    }\n    if (action === 'reset') {\n      refreshes.push(queryClient.resetQueries(matchedNow(queryClient, filters)));\n      continue;\n    }\n\n    const refetchType: RefetchType = inv.refetchType ?? 'active';\n    if (refetchType !== 'none') {\n      cancelPendingInitialReads(queryClient, filters);\n    }\n\n    refreshes.push(queryClient.invalidateQueries({ ...filters, refetchType }));\n  }\n  return Promise.all(refreshes).then(() => undefined);\n}\n"]}

package/dist/react/domain-events/create-domain-event-invalidator.d.ts

@@ -1,9 +1,5 @@
 import type { QueryClient } from '@tanstack/react-query';
 import { exact, prefix, predicate, type CacheInvalidation } from './cache-invalidation.js';
-/**
- * Registry shape: each event type maps to a function from the event's `ids`
- * payload to the list of cache invalidations that event should trigger.
- */
 export type DomainEventInvalidationRegistry<TEvent extends {
     type: string;
     ids: unknown;
@@ -16,29 +12,15 @@ export interface DomainEventInvalidator<TEvent extends {
     type: string;
     ids: unknown;
 }> {
-    /**
-     * Dispatch the event's invalidations. The returned promise resolves once
-     * every refetch they triggered has settled, and never rejects — return or
-     * await it from a mutation's `onSuccess` to keep the mutation pending until
-     * the refreshed data lands; ignore it for fire-and-forget dispatch.
-     */
     notify(queryClient: QueryClient, event: TEvent): Promise<void>;
-    /** `notify` for several events, deduplicating their invalidations as one batch. */
     notifyAll(queryClient: QueryClient, events: ReadonlyArray<TEvent>): Promise<void>;
-    /** Test/debug helpers. */
     readonly helpers: {
         exact: typeof exact;
         prefix: typeof prefix;
         predicate: typeof predicate;
     };
-    /** Direct access to the registry, mainly for tests. */
     readonly registry: DomainEventInvalidationRegistry<TEvent>;
 }
-/**
- * Build a domain-event → cache-invalidation notifier from a typed registry.
- * The registry's keys are statically tied to `TEvent["type"]`, so missing or
- * extra entries are compile errors.
- */
 export declare function createDomainEventInvalidator<TEvent extends {
     type: string;
     ids: unknown;

package/dist/react/domain-events/create-domain-event-invalidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-domain-event-invalidator.d.ts","sourceRoot":"","sources":["../../../src/react/domain-events/create-domain-event-invalidator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAEL,KAAK,EACL,MAAM,EACN,SAAS,EACT,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,MAAM,MAAM,+BAA+B,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,IAAI;KAC1F,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CACrB,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC,KAAK,CAAC,KACrC,aAAa,CAAC,iBAAiB,CAAC;CACtC,CAAC;AAEF,MAAM,WAAW,sBAAsB,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE;IACnF;;;;;OAKG;IACH,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,mFAAmF;IACnF,SAAS,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE;QAChB,KAAK,EAAE,OAAO,KAAK,CAAC;QACpB,MAAM,EAAE,OAAO,MAAM,CAAC;QACtB,SAAS,EAAE,OAAO,SAAS,CAAC;KAC7B,CAAC;IACF,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,+BAA+B,CAAC,MAAM,CAAC,CAAC;CAC5D;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,EACxF,QAAQ,EAAE,+BAA+B,CAAC,MAAM,CAAC,GAChD,sBAAsB,CAAC,MAAM,CAAC,CA4BhC"}
+{"version":3,"file":"create-domain-event-invalidator.d.ts","sourceRoot":"","sources":["../../../src/react/domain-events/create-domain-event-invalidator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAEL,KAAK,EACL,MAAM,EACN,SAAS,EACT,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,+BAA+B,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,IAAI;KAC1F,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CACrB,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC,KAAK,CAAC,KACrC,aAAa,CAAC,iBAAiB,CAAC;CACtC,CAAC;AAEF,MAAM,WAAW,sBAAsB,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE;IACnF,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,SAAS,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,QAAQ,CAAC,OAAO,EAAE;QAChB,KAAK,EAAE,OAAO,KAAK,CAAC;QACpB,MAAM,EAAE,OAAO,MAAM,CAAC;QACtB,SAAS,EAAE,OAAO,SAAS,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,+BAA+B,CAAC,MAAM,CAAC,CAAC;CAC5D;AAED,wBAAgB,4BAA4B,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,EACxF,QAAQ,EAAE,+BAA+B,CAAC,MAAM,CAAC,GAChD,sBAAsB,CAAC,MAAM,CAAC,CA4BhC"}

package/dist/react/domain-events/create-domain-event-invalidator.js

@@ -1,9 +1,4 @@
 import { applyInvalidations, exact, prefix, predicate, } from './cache-invalidation.js';
-/**
- * Build a domain-event → cache-invalidation notifier from a typed registry.
- * The registry's keys are statically tied to `TEvent["type"]`, so missing or
- * extra entries are compile errors.
- */
 export function createDomainEventInvalidator(registry) {
     function lookup(type) {
         return registry[type];

package/dist/react/domain-events/create-domain-event-invalidator.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-domain-event-invalidator.js","sourceRoot":"","sources":["../../../src/react/domain-events/create-domain-event-invalidator.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,KAAK,EACL,MAAM,EACN,SAAS,GAEV,MAAM,yBAAyB,CAAC;AAgCjC;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAiD;IAEjD,SAAS,MAAM,CAA+B,IAAW;QACvD,OAAO,QAAQ,CAAC,IAAI,CAEiB,CAAC;IACxC,CAAC;IAED,SAAS,MAAM,CAAC,WAAwB,EAAE,KAAa;QACrD,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,IAAsB,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,EAAE,CAAC,KAAK,CAAC,GAAuD,CAAC,CAAC;QACxF,OAAO,kBAAkB,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IACxD,CAAC;IAED,SAAS,SAAS,CAAC,WAAwB,EAAE,MAA6B;QACxE,MAAM,GAAG,GAAwB,EAAE,CAAC;QACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,IAAsB,CAAC,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAuD,CAAC,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,kBAAkB,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO;QACL,MAAM;QACN,SAAS;QACT,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE;QACrC,QAAQ;KACT,CAAC;AACJ,CAAC","sourcesContent":["import type { QueryClient } from '@tanstack/react-query';\nimport {\n  applyInvalidations,\n  exact,\n  prefix,\n  predicate,\n  type CacheInvalidation,\n} from './cache-invalidation.js';\n\n/**\n * Registry shape: each event type maps to a function from the event's `ids`\n * payload to the list of cache invalidations that event should trigger.\n */\nexport type DomainEventInvalidationRegistry<TEvent extends { type: string; ids: unknown }> = {\n  [K in TEvent['type']]: (\n    ids: Extract<TEvent, { type: K }>['ids'],\n  ) => ReadonlyArray<CacheInvalidation>;\n};\n\nexport interface DomainEventInvalidator<TEvent extends { type: string; ids: unknown }> {\n  /**\n   * Dispatch the event's invalidations. The returned promise resolves once\n   * every refetch they triggered has settled, and never rejects — return or\n   * await it from a mutation's `onSuccess` to keep the mutation pending until\n   * the refreshed data lands; ignore it for fire-and-forget dispatch.\n   */\n  notify(queryClient: QueryClient, event: TEvent): Promise<void>;\n  /** `notify` for several events, deduplicating their invalidations as one batch. */\n  notifyAll(queryClient: QueryClient, events: ReadonlyArray<TEvent>): Promise<void>;\n  /** Test/debug helpers. */\n  readonly helpers: {\n    exact: typeof exact;\n    prefix: typeof prefix;\n    predicate: typeof predicate;\n  };\n  /** Direct access to the registry, mainly for tests. */\n  readonly registry: DomainEventInvalidationRegistry<TEvent>;\n}\n\n/**\n * Build a domain-event → cache-invalidation notifier from a typed registry.\n * The registry's keys are statically tied to `TEvent[\"type\"]`, so missing or\n * extra entries are compile errors.\n */\nexport function createDomainEventInvalidator<TEvent extends { type: string; ids: unknown }>(\n  registry: DomainEventInvalidationRegistry<TEvent>,\n): DomainEventInvalidator<TEvent> {\n  function lookup<TType extends TEvent['type']>(type: TType) {\n    return registry[type] as (\n      ids: Extract<TEvent, { type: TType }>['ids'],\n    ) => ReadonlyArray<CacheInvalidation>;\n  }\n\n  function notify(queryClient: QueryClient, event: TEvent): Promise<void> {\n    const fn = lookup(event.type as TEvent['type']);\n    const invalidations = fn(event.ids as Extract<TEvent, { type: TEvent['type'] }>['ids']);\n    return applyInvalidations(queryClient, invalidations);\n  }\n\n  function notifyAll(queryClient: QueryClient, events: ReadonlyArray<TEvent>): Promise<void> {\n    const all: CacheInvalidation[] = [];\n    for (const event of events) {\n      const fn = lookup(event.type as TEvent['type']);\n      all.push(...fn(event.ids as Extract<TEvent, { type: TEvent['type'] }>['ids']));\n    }\n    return applyInvalidations(queryClient, all);\n  }\n\n  return {\n    notify,\n    notifyAll,\n    helpers: { exact, prefix, predicate },\n    registry,\n  };\n}\n"]}
+{"version":3,"file":"create-domain-event-invalidator.js","sourceRoot":"","sources":["../../../src/react/domain-events/create-domain-event-invalidator.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,KAAK,EACL,MAAM,EACN,SAAS,GAEV,MAAM,yBAAyB,CAAC;AAmBjC,MAAM,UAAU,4BAA4B,CAC1C,QAAiD;IAEjD,SAAS,MAAM,CAA+B,IAAW;QACvD,OAAO,QAAQ,CAAC,IAAI,CAEiB,CAAC;IACxC,CAAC;IAED,SAAS,MAAM,CAAC,WAAwB,EAAE,KAAa;QACrD,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,IAAsB,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,EAAE,CAAC,KAAK,CAAC,GAAuD,CAAC,CAAC;QACxF,OAAO,kBAAkB,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IACxD,CAAC;IAED,SAAS,SAAS,CAAC,WAAwB,EAAE,MAA6B;QACxE,MAAM,GAAG,GAAwB,EAAE,CAAC;QACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,IAAsB,CAAC,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAuD,CAAC,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,kBAAkB,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO;QACL,MAAM;QACN,SAAS;QACT,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE;QACrC,QAAQ;KACT,CAAC;AACJ,CAAC","sourcesContent":["import type { QueryClient } from '@tanstack/react-query';\nimport {\n  applyInvalidations,\n  exact,\n  prefix,\n  predicate,\n  type CacheInvalidation,\n} from './cache-invalidation.js';\n\nexport type DomainEventInvalidationRegistry<TEvent extends { type: string; ids: unknown }> = {\n  [K in TEvent['type']]: (\n    ids: Extract<TEvent, { type: K }>['ids'],\n  ) => ReadonlyArray<CacheInvalidation>;\n};\n\nexport interface DomainEventInvalidator<TEvent extends { type: string; ids: unknown }> {\n  notify(queryClient: QueryClient, event: TEvent): Promise<void>;\n  notifyAll(queryClient: QueryClient, events: ReadonlyArray<TEvent>): Promise<void>;\n  readonly helpers: {\n    exact: typeof exact;\n    prefix: typeof prefix;\n    predicate: typeof predicate;\n  };\n  readonly registry: DomainEventInvalidationRegistry<TEvent>;\n}\n\nexport function createDomainEventInvalidator<TEvent extends { type: string; ids: unknown }>(\n  registry: DomainEventInvalidationRegistry<TEvent>,\n): DomainEventInvalidator<TEvent> {\n  function lookup<TType extends TEvent['type']>(type: TType) {\n    return registry[type] as (\n      ids: Extract<TEvent, { type: TType }>['ids'],\n    ) => ReadonlyArray<CacheInvalidation>;\n  }\n\n  function notify(queryClient: QueryClient, event: TEvent): Promise<void> {\n    const fn = lookup(event.type as TEvent['type']);\n    const invalidations = fn(event.ids as Extract<TEvent, { type: TEvent['type'] }>['ids']);\n    return applyInvalidations(queryClient, invalidations);\n  }\n\n  function notifyAll(queryClient: QueryClient, events: ReadonlyArray<TEvent>): Promise<void> {\n    const all: CacheInvalidation[] = [];\n    for (const event of events) {\n      const fn = lookup(event.type as TEvent['type']);\n      all.push(...fn(event.ids as Extract<TEvent, { type: TEvent['type'] }>['ids']));\n    }\n    return applyInvalidations(queryClient, all);\n  }\n\n  return {\n    notify,\n    notifyAll,\n    helpers: { exact, prefix, predicate },\n    registry,\n  };\n}\n"]}

package/dist/react/firestore/absence-scheduler.d.ts

@@ -1,39 +1,11 @@
 import type { QueryClient, QueryKey } from '@tanstack/react-query';
-/**
- * Bounded re-read ladder for a document that resolved ABSENT.
- *
- * A one-shot lookup that lands `null` has no listener to tell it when the doc appears —
- * the row would stay blank until something invalidates it. That is the real failure the
- * realtime path was introduced to fix (a mirror doc that is missing or lagging at fetch
- * time: just after a create-and-redirect, or in a second tab racing the server mirror).
- * This scheduler restores the recovery without a listener: after an absent result it
- * re-reads a few times on a widening ladder, then gives up.
- *
- * Delays (ms) between re-reads within one absence episode. After the last rung the episode
- * is exhausted and never restarts on its own; only a later PRESENT→absent transition opens
- * a new one.
- */
 export declare const ABSENT_RETRY_DELAYS_MS: readonly [5000, 15000, 45000, 120000];
 export interface TrackAbsentDocParams {
     queryClient: QueryClient;
-    /** Exact key of the per-id lookup query. */
     queryKey: QueryKey;
-    /**
-     * Ladder this registrant wants; an empty array means it wants no re-reads. Registrants
-     * on the same key combine by union — the longest ladder among them governs — so one
-     * consumer passing `[]` never disables polling another consumer asked for.
-     */
     delays?: readonly number[];
 }
-/**
- * Register interest in re-reading `queryKey` while it resolves absent. Returns an
- * idempotent release function; releasing the last interested consumer pauses the ladder
- * without spending the episode's remaining budget, and releasing the last registrant that
- * wanted polling shrinks the effective ladder for the episode still in progress.
- */
 export declare function trackAbsentDoc({ queryClient, queryKey, delays, }: TrackAbsentDocParams): () => void;
-/** Test-only: number of absence episodes currently tracked for a QueryClient. */
 export declare function __absenceEpisodeCount(queryClient: QueryClient): number;
-/** Test-only: rungs already spent on a key's current episode, or `null` if there is none. */
 export declare function __absenceAttempt(queryClient: QueryClient, queryKey: QueryKey): number | null;
 //# sourceMappingURL=absence-scheduler.d.ts.map

package/dist/react/firestore/absence-scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"absence-scheduler.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/absence-scheduler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,uCAA4C,CAAC;AAgLhF,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,WAAW,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAC7B,WAAW,EACX,QAAQ,EACR,MAA+B,GAChC,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAmCnC;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAEtE;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAE5F"}
+{"version":3,"file":"absence-scheduler.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/absence-scheduler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE,eAAO,MAAM,sBAAsB,uCAA4C,CAAC;AAwIhF,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,EAC7B,WAAW,EACX,QAAQ,EACR,MAA+B,GAChC,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAiCnC;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAEtE;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAE5F"}

package/dist/react/firestore/absence-scheduler.js

@@ -1,31 +1,11 @@
 'use client';
-/**
- * Bounded re-read ladder for a document that resolved ABSENT.
- *
- * A one-shot lookup that lands `null` has no listener to tell it when the doc appears —
- * the row would stay blank until something invalidates it. That is the real failure the
- * realtime path was introduced to fix (a mirror doc that is missing or lagging at fetch
- * time: just after a create-and-redirect, or in a second tab racing the server mirror).
- * This scheduler restores the recovery without a listener: after an absent result it
- * re-reads a few times on a widening ladder, then gives up.
- *
- * Delays (ms) between re-reads within one absence episode. After the last rung the episode
- * is exhausted and never restarts on its own; only a later PRESENT→absent transition opens
- * a new one.
- */
 export const ABSENT_RETRY_DELAYS_MS = [5_000, 15_000, 45_000, 120_000];
 const NO_DELAYS = [];
-// Per-QueryClient, like the doc-subscription registry: a discarded client is GC'd with its
-// bookkeeping, and each browser tab schedules independently.
 const schedulers = new WeakMap();
-/**
- * Hash a key the way THIS client hashes it, so a consumer with a custom
- * `queryKeyHashFn` still lines up with `QueryCache.get()`.
- */
+/** Hashes with this client's `queryKeyHashFn` so a custom hash still lines up with `QueryCache.get()`. */
 function hashOf(queryClient, queryKey) {
     return queryClient.defaultQueryOptions({ queryKey }).queryHash;
 }
-/** Union of the registrants' ladders: the longest one wins; none means no polling. */
 function effectiveDelays(tracked) {
     if (!tracked)
         return NO_DELAYS;
@@ -61,8 +41,6 @@ function schedule(queryClient, state, hash) {
         if (!current || !isAbsentAndActive(queryClient, hash))
             return;
         void queryClient.refetchQueries({ queryKey: current.queryKey, exact: true, type: 'active' });
-        // Lay the next rung; the ladder stops the moment the doc appears, the budget runs
-        // out, or the last enabled observer goes away.
         evaluate(queryClient, state, hash);
     }, delays[episode.attempt]);
 }
@@ -80,13 +58,10 @@ function evaluate(queryClient, state, hash) {
     }
     const { status, data } = query.state;
     if (status === 'success' && data !== null) {
-        // The doc is present — the episode is over.
         discardEpisode(state, hash);
         return;
     }
     if (status !== 'success') {
-        // Pending or errored: never polled, but the budget survives so an error mid-episode
-        // cannot hand the id a fresh ladder when it returns to absent.
         clearTimer(state.episodes.get(hash));
         return;
     }
@@ -97,7 +72,6 @@ function evaluate(queryClient, state, hash) {
     }
     let episode = state.episodes.get(hash);
     if (!episode) {
-        // No registrant wants polling — do not open an episode that could never spend a rung.
         if (effectiveDelays(tracked).length === 0)
             return;
         episode = { attempt: 0, timer: null };
@@ -116,8 +90,6 @@ function getState(queryClient) {
     state = { episodes: new Map(), tracked: new Map() };
     schedulers.set(queryClient, state);
     const scheduler = state;
-    // Exactly ONE cache listener per QueryClient, created with this state and never detached:
-    // it is WeakMap-scoped, so it is collected together with the client it belongs to.
     queryClient.getQueryCache().subscribe((event) => {
         const hash = event.query.queryHash;
         if (!scheduler.tracked.has(hash) && !scheduler.episodes.has(hash))
@@ -130,12 +102,6 @@ function getState(queryClient) {
     });
     return state;
 }
-/**
- * Register interest in re-reading `queryKey` while it resolves absent. Returns an
- * idempotent release function; releasing the last interested consumer pauses the ladder
- * without spending the episode's remaining budget, and releasing the last registrant that
- * wanted polling shrinks the effective ladder for the episode still in progress.
- */
 export function trackAbsentDoc({ queryClient, queryKey, delays = ABSENT_RETRY_DELAYS_MS, }) {
     const state = getState(queryClient);
     const hash = hashOf(queryClient, queryKey);
@@ -164,18 +130,14 @@ export function trackAbsentDoc({ queryClient, queryKey, delays = ABSENT_RETRY_DE
             return;
         }
         if (effectiveDelays(current).length !== before) {
-            // The effective ladder changed: re-derive under the new one rather than letting a
-            // timer from the departed registrant's ladder fire.
             clearTimer(state.episodes.get(hash));
             evaluate(queryClient, state, hash);
         }
     };
 }
-/** Test-only: number of absence episodes currently tracked for a QueryClient. */
 export function __absenceEpisodeCount(queryClient) {
     return schedulers.get(queryClient)?.episodes.size ?? 0;
 }
-/** Test-only: rungs already spent on a key's current episode, or `null` if there is none. */
 export function __absenceAttempt(queryClient, queryKey) {
     return schedulers.get(queryClient)?.episodes.get(hashOf(queryClient, queryKey))?.attempt ?? null;
 }

package/dist/react/firestore/absence-scheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"absence-scheduler.js","sourceRoot":"","sources":["../../../src/react/firestore/absence-scheduler.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAIb;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AA+ChF,MAAM,SAAS,GAAsB,EAAE,CAAC;AAExC,2FAA2F;AAC3F,6DAA6D;AAC7D,MAAM,UAAU,GAAG,IAAI,OAAO,EAA+B,CAAC;AAE9D;;;GAGG;AACH,SAAS,MAAM,CAAC,WAAwB,EAAE,QAAkB;IAC1D,OAAO,WAAW,CAAC,mBAAmB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED,sFAAsF;AACtF,SAAS,eAAe,CAAC,OAA4B;IACnD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,OAAO,GAAsB,SAAS,CAAC;IAC3C,KAAK,MAAM,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QACjD,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM;YAAE,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC;IACjF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,OAA4B;IAC9C,IAAI,OAAO,EAAE,KAAK,IAAI,IAAI,EAAE,CAAC;QAC3B,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IACvB,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAqB,EAAE,IAAY;IACzD,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,QAAQ,CAAC,WAAwB,EAAE,KAAqB,EAAE,IAAY;IAC7E,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO;IAE3D,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO;IAE7C,OAAO,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC9B,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;QACrB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,IAAI,CAAC;YAAE,OAAO;QAC9D,KAAK,WAAW,CAAC,cAAc,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7F,kFAAkF;QAClF,+CAA+C;QAC/C,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,iBAAiB,CAAC,WAAwB,EAAE,IAAY;IAC/D,MAAM,KAAK,GAAG,WAAW,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;AAC3F,CAAC;AAED,SAAS,QAAQ,CAAC,WAAwB,EAAE,KAAqB,EAAE,IAAY;IAC7E,MAAM,KAAK,GAAG,WAAW,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC;IAErC,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC1C,4CAA4C;QAC5C,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,oFAAoF;QACpF,+DAA+D;QAC/D,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACrC,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACrC,OAAO;IACT,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,sFAAsF;QACtF,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAClD,OAAO,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACtC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;QACtB,UAAU,CAAC,OAAO,CAAC,CAAC;QACpB,OAAO;IACT,CAAC;IAED,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,QAAQ,CAAC,WAAwB;IACxC,IAAI,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IAExB,KAAK,GAAG,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IACpD,UAAU,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAEnC,MAAM,SAAS,GAAG,KAAK,CAAC;IACxB,0FAA0F;IAC1F,mFAAmF;IACnF,WAAW,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO;QAC1E,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAChC,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC;AAcD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,WAAW,EACX,QAAQ,EACR,MAAM,GAAG,sBAAsB,GACV;IACrB,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAiB,EAAE,MAAM,EAAE,CAAC;IAE9C,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,QAAQ;QAAE,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;;QACnD,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAE1E,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAEnC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC1D,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAEvD,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC3B,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YACrC,OAAO;QACT,CAAC;QAED,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC/C,kFAAkF;YAClF,oDAAoD;YACpD,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YACrC,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CAAC,WAAwB;IAC5D,OAAO,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,gBAAgB,CAAC,WAAwB,EAAE,QAAkB;IAC3E,OAAO,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;AACnG,CAAC","sourcesContent":["'use client';\n\nimport type { QueryClient, QueryKey } from '@tanstack/react-query';\n\n/**\n * Bounded re-read ladder for a document that resolved ABSENT.\n *\n * A one-shot lookup that lands `null` has no listener to tell it when the doc appears —\n * the row would stay blank until something invalidates it. That is the real failure the\n * realtime path was introduced to fix (a mirror doc that is missing or lagging at fetch\n * time: just after a create-and-redirect, or in a second tab racing the server mirror).\n * This scheduler restores the recovery without a listener: after an absent result it\n * re-reads a few times on a widening ladder, then gives up.\n *\n * Delays (ms) between re-reads within one absence episode. After the last rung the episode\n * is exhausted and never restarts on its own; only a later PRESENT→absent transition opens\n * a new one.\n */\nexport const ABSENT_RETRY_DELAYS_MS = [5_000, 15_000, 45_000, 120_000] as const;\n\n/**\n * The rules the scheduler holds to:\n *\n * - It polls ONLY a query in `status: 'success'` whose data is `null`. An error state is\n *   never polled (a denial is not an absence), and an error mid-episode pauses the ladder\n *   with its remaining budget intact.\n * - One timer per query key and one budget per absence episode: the first successful\n *   `undefined → null` opens the episode, and neither a repeated `null` nor an additional\n *   consumer resets it. A `present → null` transition opens a NEW episode.\n * - Several consumers may register the same key with DIFFERENT ladders. The effective\n *   ladder is the union: poll if any registrant wants polling, using the LONGEST ladder\n *   among them, recomputed on every register and release. Mount order never decides.\n * - Eligibility is TanStack's `query.isActive()` — at least one observer that is not\n *   disabled. Subscribe-mode and disabled observers therefore never keep an episode\n *   polling, while disabling ONE consumer cannot stop polling another still needs.\n * - Losing the last enabled observer PAUSES the ladder and retains the episode's remaining\n *   rungs; a later enabled observer resumes from there. A new observer on an EXHAUSTED\n *   episode does not restart it.\n * - Cache removal (gc) discards the episode outright, so a later re-fetch that lands absent\n *   starts fresh.\n *\n * Because the timer is per key rather than per observer, N consumers of one absent id cost\n * one re-read per rung, not N.\n */\n\ntype Episode = {\n  /** Rungs consumed so far; `>= effectiveDelays().length` means exhausted. */\n  attempt: number;\n  timer: ReturnType<typeof setTimeout> | null;\n};\n\ntype Registration = {\n  delays: readonly number[];\n};\n\ntype Tracked = {\n  queryKey: QueryKey;\n  registrations: Registration[];\n};\n\ntype SchedulerState = {\n  episodes: Map<string, Episode>;\n  tracked: Map<string, Tracked>;\n};\n\nconst NO_DELAYS: readonly number[] = [];\n\n// Per-QueryClient, like the doc-subscription registry: a discarded client is GC'd with its\n// bookkeeping, and each browser tab schedules independently.\nconst schedulers = new WeakMap<QueryClient, SchedulerState>();\n\n/**\n * Hash a key the way THIS client hashes it, so a consumer with a custom\n * `queryKeyHashFn` still lines up with `QueryCache.get()`.\n */\nfunction hashOf(queryClient: QueryClient, queryKey: QueryKey): string {\n  return queryClient.defaultQueryOptions({ queryKey }).queryHash;\n}\n\n/** Union of the registrants' ladders: the longest one wins; none means no polling. */\nfunction effectiveDelays(tracked: Tracked | undefined): readonly number[] {\n  if (!tracked) return NO_DELAYS;\n  let longest: readonly number[] = NO_DELAYS;\n  for (const registration of tracked.registrations) {\n    if (registration.delays.length > longest.length) longest = registration.delays;\n  }\n  return longest;\n}\n\nfunction clearTimer(episode: Episode | undefined): void {\n  if (episode?.timer != null) {\n    clearTimeout(episode.timer);\n    episode.timer = null;\n  }\n}\n\nfunction discardEpisode(state: SchedulerState, hash: string): void {\n  clearTimer(state.episodes.get(hash));\n  state.episodes.delete(hash);\n}\n\nfunction schedule(queryClient: QueryClient, state: SchedulerState, hash: string): void {\n  const tracked = state.tracked.get(hash);\n  const episode = state.episodes.get(hash);\n  if (!tracked || !episode || episode.timer !== null) return;\n\n  const delays = effectiveDelays(tracked);\n  if (episode.attempt >= delays.length) return;\n\n  episode.timer = setTimeout(() => {\n    episode.timer = null;\n    episode.attempt += 1;\n    const current = state.tracked.get(hash);\n    if (!current || !isAbsentAndActive(queryClient, hash)) return;\n    void queryClient.refetchQueries({ queryKey: current.queryKey, exact: true, type: 'active' });\n    // Lay the next rung; the ladder stops the moment the doc appears, the budget runs\n    // out, or the last enabled observer goes away.\n    evaluate(queryClient, state, hash);\n  }, delays[episode.attempt]);\n}\n\nfunction isAbsentAndActive(queryClient: QueryClient, hash: string): boolean {\n  const query = queryClient.getQueryCache().get(hash);\n  if (!query) return false;\n  return query.state.status === 'success' && query.state.data === null && query.isActive();\n}\n\nfunction evaluate(queryClient: QueryClient, state: SchedulerState, hash: string): void {\n  const query = queryClient.getQueryCache().get(hash);\n  if (!query) {\n    discardEpisode(state, hash);\n    return;\n  }\n\n  const { status, data } = query.state;\n\n  if (status === 'success' && data !== null) {\n    // The doc is present — the episode is over.\n    discardEpisode(state, hash);\n    return;\n  }\n\n  if (status !== 'success') {\n    // Pending or errored: never polled, but the budget survives so an error mid-episode\n    // cannot hand the id a fresh ladder when it returns to absent.\n    clearTimer(state.episodes.get(hash));\n    return;\n  }\n\n  const tracked = state.tracked.get(hash);\n  if (!tracked) {\n    clearTimer(state.episodes.get(hash));\n    return;\n  }\n\n  let episode = state.episodes.get(hash);\n  if (!episode) {\n    // No registrant wants polling — do not open an episode that could never spend a rung.\n    if (effectiveDelays(tracked).length === 0) return;\n    episode = { attempt: 0, timer: null };\n    state.episodes.set(hash, episode);\n  }\n\n  if (!query.isActive()) {\n    clearTimer(episode);\n    return;\n  }\n\n  schedule(queryClient, state, hash);\n}\n\nfunction getState(queryClient: QueryClient): SchedulerState {\n  let state = schedulers.get(queryClient);\n  if (state) return state;\n\n  state = { episodes: new Map(), tracked: new Map() };\n  schedulers.set(queryClient, state);\n\n  const scheduler = state;\n  // Exactly ONE cache listener per QueryClient, created with this state and never detached:\n  // it is WeakMap-scoped, so it is collected together with the client it belongs to.\n  queryClient.getQueryCache().subscribe((event) => {\n    const hash = event.query.queryHash;\n    if (!scheduler.tracked.has(hash) && !scheduler.episodes.has(hash)) return;\n    if (event.type === 'removed') {\n      discardEpisode(scheduler, hash);\n      return;\n    }\n    evaluate(queryClient, scheduler, hash);\n  });\n\n  return state;\n}\n\nexport interface TrackAbsentDocParams {\n  queryClient: QueryClient;\n  /** Exact key of the per-id lookup query. */\n  queryKey: QueryKey;\n  /**\n   * Ladder this registrant wants; an empty array means it wants no re-reads. Registrants\n   * on the same key combine by union — the longest ladder among them governs — so one\n   * consumer passing `[]` never disables polling another consumer asked for.\n   */\n  delays?: readonly number[];\n}\n\n/**\n * Register interest in re-reading `queryKey` while it resolves absent. Returns an\n * idempotent release function; releasing the last interested consumer pauses the ladder\n * without spending the episode's remaining budget, and releasing the last registrant that\n * wanted polling shrinks the effective ladder for the episode still in progress.\n */\nexport function trackAbsentDoc({\n  queryClient,\n  queryKey,\n  delays = ABSENT_RETRY_DELAYS_MS,\n}: TrackAbsentDocParams): () => void {\n  const state = getState(queryClient);\n  const hash = hashOf(queryClient, queryKey);\n  const registration: Registration = { delays };\n\n  const existing = state.tracked.get(hash);\n  if (existing) existing.registrations.push(registration);\n  else state.tracked.set(hash, { queryKey, registrations: [registration] });\n\n  evaluate(queryClient, state, hash);\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n    const current = state.tracked.get(hash);\n    if (!current) return;\n\n    const before = effectiveDelays(current).length;\n    const index = current.registrations.indexOf(registration);\n    if (index >= 0) current.registrations.splice(index, 1);\n\n    if (current.registrations.length === 0) {\n      state.tracked.delete(hash);\n      clearTimer(state.episodes.get(hash));\n      return;\n    }\n\n    if (effectiveDelays(current).length !== before) {\n      // The effective ladder changed: re-derive under the new one rather than letting a\n      // timer from the departed registrant's ladder fire.\n      clearTimer(state.episodes.get(hash));\n      evaluate(queryClient, state, hash);\n    }\n  };\n}\n\n/** Test-only: number of absence episodes currently tracked for a QueryClient. */\nexport function __absenceEpisodeCount(queryClient: QueryClient): number {\n  return schedulers.get(queryClient)?.episodes.size ?? 0;\n}\n\n/** Test-only: rungs already spent on a key's current episode, or `null` if there is none. */\nexport function __absenceAttempt(queryClient: QueryClient, queryKey: QueryKey): number | null {\n  return schedulers.get(queryClient)?.episodes.get(hashOf(queryClient, queryKey))?.attempt ?? null;\n}\n"]}
+{"version":3,"file":"absence-scheduler.js","sourceRoot":"","sources":["../../../src/react/firestore/absence-scheduler.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport type { QueryClient, QueryKey } from '@tanstack/react-query';\n\nexport const ABSENT_RETRY_DELAYS_MS = [5_000, 15_000, 45_000, 120_000] as const;\n\ntype Episode = {\n  attempt: number;\n  timer: ReturnType<typeof setTimeout> | null;\n};\n\ntype Registration = {\n  delays: readonly number[];\n};\n\ntype Tracked = {\n  queryKey: QueryKey;\n  registrations: Registration[];\n};\n\ntype SchedulerState = {\n  episodes: Map<string, Episode>;\n  tracked: Map<string, Tracked>;\n};\n\nconst NO_DELAYS: readonly number[] = [];\n\nconst schedulers = new WeakMap<QueryClient, SchedulerState>();\n\n/** Hashes with this client's `queryKeyHashFn` so a custom hash still lines up with `QueryCache.get()`. */\nfunction hashOf(queryClient: QueryClient, queryKey: QueryKey): string {\n  return queryClient.defaultQueryOptions({ queryKey }).queryHash;\n}\n\nfunction effectiveDelays(tracked: Tracked | undefined): readonly number[] {\n  if (!tracked) return NO_DELAYS;\n  let longest: readonly number[] = NO_DELAYS;\n  for (const registration of tracked.registrations) {\n    if (registration.delays.length > longest.length) longest = registration.delays;\n  }\n  return longest;\n}\n\nfunction clearTimer(episode: Episode | undefined): void {\n  if (episode?.timer != null) {\n    clearTimeout(episode.timer);\n    episode.timer = null;\n  }\n}\n\nfunction discardEpisode(state: SchedulerState, hash: string): void {\n  clearTimer(state.episodes.get(hash));\n  state.episodes.delete(hash);\n}\n\nfunction schedule(queryClient: QueryClient, state: SchedulerState, hash: string): void {\n  const tracked = state.tracked.get(hash);\n  const episode = state.episodes.get(hash);\n  if (!tracked || !episode || episode.timer !== null) return;\n\n  const delays = effectiveDelays(tracked);\n  if (episode.attempt >= delays.length) return;\n\n  episode.timer = setTimeout(() => {\n    episode.timer = null;\n    episode.attempt += 1;\n    const current = state.tracked.get(hash);\n    if (!current || !isAbsentAndActive(queryClient, hash)) return;\n    void queryClient.refetchQueries({ queryKey: current.queryKey, exact: true, type: 'active' });\n    evaluate(queryClient, state, hash);\n  }, delays[episode.attempt]);\n}\n\nfunction isAbsentAndActive(queryClient: QueryClient, hash: string): boolean {\n  const query = queryClient.getQueryCache().get(hash);\n  if (!query) return false;\n  return query.state.status === 'success' && query.state.data === null && query.isActive();\n}\n\nfunction evaluate(queryClient: QueryClient, state: SchedulerState, hash: string): void {\n  const query = queryClient.getQueryCache().get(hash);\n  if (!query) {\n    discardEpisode(state, hash);\n    return;\n  }\n\n  const { status, data } = query.state;\n\n  if (status === 'success' && data !== null) {\n    discardEpisode(state, hash);\n    return;\n  }\n\n  if (status !== 'success') {\n    clearTimer(state.episodes.get(hash));\n    return;\n  }\n\n  const tracked = state.tracked.get(hash);\n  if (!tracked) {\n    clearTimer(state.episodes.get(hash));\n    return;\n  }\n\n  let episode = state.episodes.get(hash);\n  if (!episode) {\n    if (effectiveDelays(tracked).length === 0) return;\n    episode = { attempt: 0, timer: null };\n    state.episodes.set(hash, episode);\n  }\n\n  if (!query.isActive()) {\n    clearTimer(episode);\n    return;\n  }\n\n  schedule(queryClient, state, hash);\n}\n\nfunction getState(queryClient: QueryClient): SchedulerState {\n  let state = schedulers.get(queryClient);\n  if (state) return state;\n\n  state = { episodes: new Map(), tracked: new Map() };\n  schedulers.set(queryClient, state);\n\n  const scheduler = state;\n  queryClient.getQueryCache().subscribe((event) => {\n    const hash = event.query.queryHash;\n    if (!scheduler.tracked.has(hash) && !scheduler.episodes.has(hash)) return;\n    if (event.type === 'removed') {\n      discardEpisode(scheduler, hash);\n      return;\n    }\n    evaluate(queryClient, scheduler, hash);\n  });\n\n  return state;\n}\n\nexport interface TrackAbsentDocParams {\n  queryClient: QueryClient;\n  queryKey: QueryKey;\n  delays?: readonly number[];\n}\n\nexport function trackAbsentDoc({\n  queryClient,\n  queryKey,\n  delays = ABSENT_RETRY_DELAYS_MS,\n}: TrackAbsentDocParams): () => void {\n  const state = getState(queryClient);\n  const hash = hashOf(queryClient, queryKey);\n  const registration: Registration = { delays };\n\n  const existing = state.tracked.get(hash);\n  if (existing) existing.registrations.push(registration);\n  else state.tracked.set(hash, { queryKey, registrations: [registration] });\n\n  evaluate(queryClient, state, hash);\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n    const current = state.tracked.get(hash);\n    if (!current) return;\n\n    const before = effectiveDelays(current).length;\n    const index = current.registrations.indexOf(registration);\n    if (index >= 0) current.registrations.splice(index, 1);\n\n    if (current.registrations.length === 0) {\n      state.tracked.delete(hash);\n      clearTimer(state.episodes.get(hash));\n      return;\n    }\n\n    if (effectiveDelays(current).length !== before) {\n      clearTimer(state.episodes.get(hash));\n      evaluate(queryClient, state, hash);\n    }\n  };\n}\n\nexport function __absenceEpisodeCount(queryClient: QueryClient): number {\n  return schedulers.get(queryClient)?.episodes.size ?? 0;\n}\n\nexport function __absenceAttempt(queryClient: QueryClient, queryKey: QueryKey): number | null {\n  return schedulers.get(queryClient)?.episodes.get(hashOf(queryClient, queryKey))?.attempt ?? null;\n}\n"]}

package/dist/react/firestore/batch-doc-loader.d.ts

@@ -1,42 +1,12 @@
 import { type Firestore } from 'firebase/firestore';
 import type { QueryClient } from '@tanstack/react-query';
-/**
- * Coalescing document loader behind {@link useBatchFirestoreDocs}'s one-shot mode.
- *
- * Every id is its own observed React Query query, so without coalescing N ids would issue
- * N Firestore round-trips. The loader collects the ids enqueued in a single microtask and
- * dispatches them as `where(documentId(), 'in', chunk)` queries of at most `FIRESTORE_IN_FILTER_LIMIT` ids each
- * (`'batch'` transport), or as concurrent per-document gets (`'get'` transport — required
- * for collections whose rules gate reads on `resource.data`, where an unconstrained list
- * query is denied wholesale but per-document gets are evaluated per doc).
- *
- * Two properties are load-bearing:
- *
- * - **The loader resolves promises only — it NEVER writes the query cache.** TanStack's
- *   per-query fetch identity is therefore the sole guard against a late batch response
- *   overwriting a newer per-id result.
- * - **A dispatched batch is closed.** A later enqueue of the same id (a refetch after a
- *   cancellation, say) always joins a NEW batch, never the in-flight one — so a cancelled
- *   read can never be served by the request it was cancelled out of.
- *
- * Cancelling one per-id query detaches only that waiter; the shared request still completes
- * for its batch-mates.
- *
- * Loaders are scoped per `(QueryClient, Firestore instance, collectionPath)`. The Firestore
- * instance is part of the scope on purpose: two `db` instances sharing a collection path
- * must never share a request.
- */
-/** Maximum `in`-query requests in flight at once, per loader scope. */
 export declare const MAX_CONCURRENT_BATCH_REQUESTS = 4;
-/** Maximum per-document gets in flight at once, per loader scope. */
 export declare const MAX_CONCURRENT_DOC_GETS = 12;
 export type LoadedDoc = Record<string, unknown> & {
     id: string;
 };
 export type DocLoader = {
-    /** Resolve one id through the coalescing `in`-query batcher. */
     loadBatched(id: string, signal?: AbortSignal): Promise<LoadedDoc | null>;
-    /** Resolve one id through its own `getDoc`, bounded by the get concurrency limit. */
     loadOne(id: string, signal?: AbortSignal): Promise<LoadedDoc | null>;
 };
 export declare function getDocLoader(queryClient: QueryClient, db: Firestore, collectionPath: string): DocLoader;