@ttt-productions/query-core 0.14.4 → 0.14.6

package/dist/cache-helpers.d.ts

@@ -8,4 +8,21 @@ export declare function removeByPrefix(client: QueryClient, prefix: QueryKey): v
  * Useful for optimistic updates without baking in business logic.
  */
 export declare function updateQueryData<T>(client: QueryClient, key: QueryKey, updater: (prev: T | undefined) => T): void;
+/** The cache key of page `page` of a `useFirestorePaginated` list keyed `queryKey`. */
+export declare function paginatedPageKey(queryKey: QueryKey, page: number): QueryKey;
+/**
+ * Patch rows in place across every cached page of a `useFirestorePaginated` list
+ * (`queryKey` is the base key the hook was given). Return the same row to leave it
+ * unchanged; a page with no changed row keeps its identity. Cursors and has-more are
+ * untouched, so paging stays aligned with the server.
+ */
+export declare function mapPaginatedItems<T>(client: QueryClient, queryKey: QueryKey, mapItem: (item: T) => T): void;
+/**
+ * Put a just-created row at the top of page 1 of a `useFirestorePaginated` list, only
+ * when page 1 is cached. Use it only for a list ordered newest-first. Page 1 keeps its
+ * cursor, so it shows one extra row and page 2 keeps its place until page 1 is next read;
+ * that read moves page 1's cursor, and the hook then re-reads page 2 from the new cursor
+ * before showing it.
+ */
+export declare function prependToFirstPaginatedPage<T>(client: QueryClient, queryKey: QueryKey, item: T): void;
 //# sourceMappingURL=cache-helpers.d.ts.map

package/dist/cache-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-helpers.d.ts","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE,uDAAuD;AACvD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,iBAE7E;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,QAEnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,QAGpC"}
+{"version":3,"file":"cache-helpers.d.ts","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGnE,uDAAuD;AACvD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,iBAE7E;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,QAEnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,QAGpC;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE3E;AAeD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GACtB,IAAI,CAWN;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAC3C,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,CAAC,GACN,IAAI,CAKN"}

package/dist/cache-helpers.js

@@ -13,4 +13,52 @@ export function removeByPrefix(client, prefix) {
 export function updateQueryData(client, key, updater) {
     client.setQueryData(key, (prev) => updater(prev));
 }
+/** The cache key of page `page` of a `useFirestorePaginated` list keyed `queryKey`. */
+export function paginatedPageKey(queryKey, page) {
+    return [...queryKey, 'page', page];
+}
+function isPaginatedPage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        Array.isArray(value.items) &&
+        typeof value.hasMore === 'boolean');
+}
+function isPageKey(baseKey, key) {
+    return key.length === baseKey.length + 2 && key[baseKey.length] === 'page';
+}
+/**
+ * Patch rows in place across every cached page of a `useFirestorePaginated` list
+ * (`queryKey` is the base key the hook was given). Return the same row to leave it
+ * unchanged; a page with no changed row keeps its identity. Cursors and has-more are
+ * untouched, so paging stays aligned with the server.
+ */
+export function mapPaginatedItems(client, queryKey, mapItem) {
+    for (const [key, value] of client.getQueriesData({ queryKey })) {
+        if (!isPageKey(queryKey, key) || !isPaginatedPage(value))
+            continue;
+        let changed = false;
+        const items = value.items.map((item) => {
+            const next = mapItem(item);
+            if (next !== item)
+                changed = true;
+            return next;
+        });
+        if (changed)
+            client.setQueryData(key, { ...value, items });
+    }
+}
+/**
+ * Put a just-created row at the top of page 1 of a `useFirestorePaginated` list, only
+ * when page 1 is cached. Use it only for a list ordered newest-first. Page 1 keeps its
+ * cursor, so it shows one extra row and page 2 keeps its place until page 1 is next read;
+ * that read moves page 1's cursor, and the hook then re-reads page 2 from the new cursor
+ * before showing it.
+ */
+export function prependToFirstPaginatedPage(client, queryKey, item) {
+    const key = paginatedPageKey(queryKey, 1);
+    const value = client.getQueryData(key);
+    if (!isPaginatedPage(value))
+        return;
+    client.setQueryData(key, { ...value, items: [item, ...value.items] });
+}
 //# sourceMappingURL=cache-helpers.js.map

package/dist/cache-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-helpers.js","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAmB,EAAE,MAAgB;IAC5E,OAAO,MAAM,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,MAAgB;IAClE,OAAO,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,GAAa,EACb,OAAmC;IAEnC,MAAM,CAAC,YAAY,CAAI,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC","sourcesContent":["import type { QueryClient, QueryKey } from '@tanstack/react-query';\n\n/** Invalidate everything that matches a key prefix. */\nexport async function invalidateByPrefix(client: QueryClient, prefix: QueryKey) {\n  return client.invalidateQueries({ queryKey: prefix, exact: false });\n}\n\n/** Remove everything that matches a key prefix (drops cached data). */\nexport function removeByPrefix(client: QueryClient, prefix: QueryKey) {\n  return client.removeQueries({ queryKey: prefix, exact: false });\n}\n\n/**\n * Generic cache update helper.\n * Useful for optimistic updates without baking in business logic.\n */\nexport function updateQueryData<T>(\n  client: QueryClient,\n  key: QueryKey,\n  updater: (prev: T | undefined) => T\n) {\n  client.setQueryData<T>(key, (prev) => updater(prev));\n}\n"]}
+{"version":3,"file":"cache-helpers.js","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"AAGA,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAmB,EAAE,MAAgB;IAC5E,OAAO,MAAM,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,MAAgB;IAClE,OAAO,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,GAAa,EACb,OAAmC;IAEnC,MAAM,CAAC,YAAY,CAAI,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,QAAkB,EAAE,IAAY;IAC/D,OAAO,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,KAAK,CAAC,OAAO,CAAE,KAA6B,CAAC,KAAK,CAAC;QACnD,OAAQ,KAA+B,CAAC,OAAO,KAAK,SAAS,CAC9D,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,OAAiB,EAAE,GAAa;IACjD,OAAO,GAAG,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,QAAkB,EAClB,OAAuB;IAEvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,cAAc,CAAmB,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACjF,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC;YAAE,SAAS;QACnE,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACrC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAS,CAAC,CAAC;YAChC,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QACH,IAAI,OAAO;YAAE,MAAM,CAAC,YAAY,CAAmB,GAAG,EAAE,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAAmB,EACnB,QAAkB,EAClB,IAAO;IAEP,MAAM,GAAG,GAAG,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAmB,GAAG,CAAC,CAAC;IACzD,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC;QAAE,OAAO;IACpC,MAAM,CAAC,YAAY,CAAmB,GAAG,EAAE,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC1F,CAAC","sourcesContent":["import type { QueryClient, QueryKey } from '@tanstack/react-query';\nimport type { PaginatedPage } from './firestore/types.js';\n\n/** Invalidate everything that matches a key prefix. */\nexport async function invalidateByPrefix(client: QueryClient, prefix: QueryKey) {\n  return client.invalidateQueries({ queryKey: prefix, exact: false });\n}\n\n/** Remove everything that matches a key prefix (drops cached data). */\nexport function removeByPrefix(client: QueryClient, prefix: QueryKey) {\n  return client.removeQueries({ queryKey: prefix, exact: false });\n}\n\n/**\n * Generic cache update helper.\n * Useful for optimistic updates without baking in business logic.\n */\nexport function updateQueryData<T>(\n  client: QueryClient,\n  key: QueryKey,\n  updater: (prev: T | undefined) => T\n) {\n  client.setQueryData<T>(key, (prev) => updater(prev));\n}\n\n/** The cache key of page `page` of a `useFirestorePaginated` list keyed `queryKey`. */\nexport function paginatedPageKey(queryKey: QueryKey, page: number): QueryKey {\n  return [...queryKey, 'page', page];\n}\n\nfunction isPaginatedPage(value: unknown): value is PaginatedPage<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    Array.isArray((value as { items?: unknown }).items) &&\n    typeof (value as { hasMore?: unknown }).hasMore === 'boolean'\n  );\n}\n\nfunction isPageKey(baseKey: QueryKey, key: QueryKey): boolean {\n  return key.length === baseKey.length + 2 && key[baseKey.length] === 'page';\n}\n\n/**\n * Patch rows in place across every cached page of a `useFirestorePaginated` list\n * (`queryKey` is the base key the hook was given). Return the same row to leave it\n * unchanged; a page with no changed row keeps its identity. Cursors and has-more are\n * untouched, so paging stays aligned with the server.\n */\nexport function mapPaginatedItems<T>(\n  client: QueryClient,\n  queryKey: QueryKey,\n  mapItem: (item: T) => T,\n): void {\n  for (const [key, value] of client.getQueriesData<PaginatedPage<T>>({ queryKey })) {\n    if (!isPageKey(queryKey, key) || !isPaginatedPage(value)) continue;\n    let changed = false;\n    const items = value.items.map((item) => {\n      const next = mapItem(item as T);\n      if (next !== item) changed = true;\n      return next;\n    });\n    if (changed) client.setQueryData<PaginatedPage<T>>(key, { ...value, items });\n  }\n}\n\n/**\n * Put a just-created row at the top of page 1 of a `useFirestorePaginated` list, only\n * when page 1 is cached. Use it only for a list ordered newest-first. Page 1 keeps its\n * cursor, so it shows one extra row and page 2 keeps its place until page 1 is next read;\n * that read moves page 1's cursor, and the hook then re-reads page 2 from the new cursor\n * before showing it.\n */\nexport function prependToFirstPaginatedPage<T>(\n  client: QueryClient,\n  queryKey: QueryKey,\n  item: T,\n): void {\n  const key = paginatedPageKey(queryKey, 1);\n  const value = client.getQueryData<PaginatedPage<T>>(key);\n  if (!isPaginatedPage(value)) return;\n  client.setQueryData<PaginatedPage<T>>(key, { ...value, items: [item, ...value.items] });\n}\n"]}

package/dist/firestore/types.d.ts

@@ -23,6 +23,27 @@ export type FirestoreSourceState = 'connecting' | 'live' | 'offline' | 'error';
 export type WithSourceState<R> = R & {
     sourceState: FirestoreSourceState;
 };
+/**
+ * One requested id's answer from `useBatchFirestoreDocs`:
+ * - `loading` — no answer yet (nothing cached for the id, or the hook is disabled).
+ * - `present` — the document exists and is readable; `data` is it.
+ * - `absent` — the read succeeded and the document does not exist.
+ * - `failed` — the read (or, in subscribe mode, the listener) errored; `error` is the cause.
+ *   A failure is never reported as `absent`, and a document cached before the failure is
+ *   not reported as `present`. What a failure means for a given collection (a rules denial
+ *   that stands for "not there for this reader", say) is the consumer's to decide from `error`.
+ */
+export type BatchFirestoreDocOutcome<T> = {
+    status: 'loading';
+} | {
+    status: 'present';
+    data: T;
+} | {
+    status: 'absent';
+} | {
+    status: 'failed';
+    error: Error;
+};
 /**
  * Extract document data with ID from a QueryDocumentSnapshot.
  */
@@ -95,6 +116,8 @@ export interface FirestorePaginatedOptions<T> extends FirestoreBaseOptions {
     pageSize?: number;
     /** Initial page number (default: 1) */
     initialPage?: number;
+    /** Re-read the displayed page every `refetchInterval` ms while it is mounted (omit for none). */
+    refetchInterval?: number;
     /** Transform function applied to each document. Receives data WITH id included. */
     select?: (data: DocumentData & {
         id: string;
@@ -152,12 +175,16 @@ export interface InfinitePage<T> {
     size: number;
 }
 /**
- * Result for paginated queries.
+ * One page's cache entry for `useFirestorePaginated`, stored at `[...queryKey, 'page', n]`:
+ * the page's rows, its last row (the next page's cursor; `null` for an empty page), and
+ * whether a further page exists (read with a one-row look-ahead), and the id of the row it
+ * was read after (`null` for page 1), checked against the previous page's cursor.
  */
-export interface PaginatedResult<T> {
-    items: WithId<T>[];
-    cursors: DocumentSnapshot[];
+export interface PaginatedPage<T> {
+    items: T[];
+    cursor: DocumentSnapshot | null;
     hasMore: boolean;
+    after: string | null;
 }
 /**
  * Mutation operation types for batch mutations.

package/dist/firestore/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"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"}

package/dist/firestore/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"AA8BA;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,IAA8B;IAE9B,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;AACzC,CAAC","sourcesContent":["import type {\n  DocumentData,\n  DocumentSnapshot,\n  QueryDocumentSnapshot,\n  QueryConstraint,\n} from 'firebase/firestore';\n\n/**\n * Document with ID included in the data object.\n */\nexport type WithId<T> = T & { id: string };\n\n/**\n * Metadata-derived liveness of a realtime subscription. Firestore serves cached\n * snapshots offline WITHOUT firing the error callback, so error-only detection\n * renders a stale cached empty result as \"live\". This four-state is derived from\n * `snapshot.metadata.fromCache` (server-confirmed vs cache) plus the listener\n * error callback:\n * - `connecting` — no server-confirmed snapshot yet (initial, or only cache-first data).\n * - `live` — at least one server-confirmed snapshot (`fromCache === false`).\n * - `offline` — only cached data after having been live (connectivity loss).\n * - `error` — the listener error callback fired (e.g. permission loss).\n *\n * Meaningful only for `subscribe: true`; a non-subscribed hook stays `connecting`.\n */\nexport type FirestoreSourceState = 'connecting' | 'live' | 'offline' | 'error';\n\n/** A query-hook result augmented with the metadata-derived subscription source state. */\nexport type WithSourceState<R> = R & { sourceState: FirestoreSourceState };\n\n/**\n * Extract document data with ID from a QueryDocumentSnapshot.\n */\nexport function docWithId<T extends DocumentData>(\n  snap: QueryDocumentSnapshot<T>\n): WithId<T> {\n  return { id: snap.id, ...snap.data() };\n}\n\n/**\n * Base options shared across all Firestore hooks.\n */\nexport interface FirestoreBaseOptions {\n  /** React Query cache key */\n  queryKey: readonly unknown[];\n  /** Enable/disable the query */\n  enabled?: boolean;\n  /** Stale time override (ms) */\n  staleTime?: number;\n  /** Garbage collection time override (ms) */\n  gcTime?: number;\n}\n\n/**\n * Options for single document queries.\n */\nexport interface FirestoreDocOptions<T> extends FirestoreBaseOptions {\n  /** Full document path (e.g., 'users/abc123') */\n  docPath: string;\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to document data. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for collection queries.\n */\nexport interface FirestoreCollectionOptions<T> extends FirestoreBaseOptions {\n  /** Collection path (e.g., 'users' or 'entities/abc/members') */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy, etc.) */\n  constraints?: QueryConstraint[];\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for infinite scroll queries.\n */\nexport interface FirestoreInfiniteOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy - required for pagination) */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 20) */\n  pageSize?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for paginated queries with page numbers.\n */\nexport interface FirestorePaginatedOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 10) */\n  pageSize?: number;\n  /** Initial page number (default: 1) */\n  initialPage?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for count() aggregation queries.\n */\nexport interface FirestoreCountOptions extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, etc.) applied before counting */\n  constraints?: QueryConstraint[];\n  /** Polling interval in ms (omit for no polling) */\n  refetchInterval?: number;\n}\n\n/**\n * Options for a live newest-window + cursor-bridged older-pages list\n * (e.g. chat messages, live comment threads, live activity feeds). The newest\n * page is a realtime onSnapshot window; older pages load on demand via getDocs,\n * seeded from the window's oldest document so there is no gap or re-read.\n */\nexport interface FirestoreLiveInfiniteOptions<T = DocumentData & { id: string }> {\n  /** Collection path (slash-joined for nested paths, e.g. 'chats/t1/messages'). */\n  collectionPath: string;\n  /** React Query cache key. The older-pages query is keyed under `[...queryKey, 'older']`. */\n  queryKey: readonly unknown[];\n  /** Field both the live window and older pages order by (descending under the hood). */\n  orderByField: string;\n  /** Equality/filter constraints. Do NOT pass orderBy/limit/startAfter — the hook adds those. */\n  constraints?: QueryConstraint[];\n  /** Items per page / live-window size (default 20, capped at 100). */\n  pageSize?: number;\n  /** When false, no listener is opened and no pages are fetched. */\n  enabled?: boolean;\n  /** Map each raw doc (id included) to the item shape. Default: identity (WithId). */\n  select?: (data: DocumentData & { id: string }) => T;\n  /** Numeric sort key from a raw doc (id included). Default: reads `orderByField` as a number. */\n  getSortValue?: (data: DocumentData & { id: string }) => number;\n  /** Output ordering of the merged list. Default 'asc' (oldest → newest). */\n  sort?: 'asc' | 'desc';\n}\n\n/**\n * Result page for infinite queries.\n */\nexport interface InfinitePage<T> {\n  items: WithId<T>[];\n  lastDoc: DocumentSnapshot | null;\n  size: number;\n}\n\n/**\n * Result for paginated queries.\n */\nexport interface PaginatedResult<T> {\n  items: WithId<T>[];\n  cursors: DocumentSnapshot[];\n  hasMore: boolean;\n}\n\n/**\n * Mutation operation types for batch mutations.\n */\nexport type MutationOperation =\n  | { type: 'set'; docPath: string; data: DocumentData; merge?: boolean }\n  | { type: 'update'; docPath: string; data: DocumentData }\n  | { type: 'delete'; docPath: string };\n\n/**\n * Options for document mutations.\n */\nexport interface FirestoreMutationOptions<T> {\n  /** Document path for single-doc mutations */\n  docPath?: string;\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Enable optimistic updates */\n  optimistic?: {\n    /** Query key of the cache to update */\n    queryKey: readonly unknown[];\n    /** How to update the cached data */\n    updater: (oldData: T | undefined, newData: Partial<T>) => T;\n  };\n}\n\n/**\n * Options for batch mutations.\n */\nexport interface FirestoreBatchOptions {\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Max operations per batch (default: 450) */\n  batchSize?: number;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"AA8CA;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,IAA8B;IAE9B,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;AACzC,CAAC","sourcesContent":["import type {\n  DocumentData,\n  DocumentSnapshot,\n  QueryDocumentSnapshot,\n  QueryConstraint,\n} from 'firebase/firestore';\n\n/**\n * Document with ID included in the data object.\n */\nexport type WithId<T> = T & { id: string };\n\n/**\n * Metadata-derived liveness of a realtime subscription. Firestore serves cached\n * snapshots offline WITHOUT firing the error callback, so error-only detection\n * renders a stale cached empty result as \"live\". This four-state is derived from\n * `snapshot.metadata.fromCache` (server-confirmed vs cache) plus the listener\n * error callback:\n * - `connecting` — no server-confirmed snapshot yet (initial, or only cache-first data).\n * - `live` — at least one server-confirmed snapshot (`fromCache === false`).\n * - `offline` — only cached data after having been live (connectivity loss).\n * - `error` — the listener error callback fired (e.g. permission loss).\n *\n * Meaningful only for `subscribe: true`; a non-subscribed hook stays `connecting`.\n */\nexport type FirestoreSourceState = 'connecting' | 'live' | 'offline' | 'error';\n\n/** A query-hook result augmented with the metadata-derived subscription source state. */\nexport type WithSourceState<R> = R & { sourceState: FirestoreSourceState };\n\n/**\n * One requested id's answer from `useBatchFirestoreDocs`:\n * - `loading` — no answer yet (nothing cached for the id, or the hook is disabled).\n * - `present` — the document exists and is readable; `data` is it.\n * - `absent` — the read succeeded and the document does not exist.\n * - `failed` — the read (or, in subscribe mode, the listener) errored; `error` is the cause.\n *   A failure is never reported as `absent`, and a document cached before the failure is\n *   not reported as `present`. What a failure means for a given collection (a rules denial\n *   that stands for \"not there for this reader\", say) is the consumer's to decide from `error`.\n */\nexport type BatchFirestoreDocOutcome<T> =\n  | { status: 'loading' }\n  | { status: 'present'; data: T }\n  | { status: 'absent' }\n  | { status: 'failed'; error: Error };\n\n/**\n * Extract document data with ID from a QueryDocumentSnapshot.\n */\nexport function docWithId<T extends DocumentData>(\n  snap: QueryDocumentSnapshot<T>\n): WithId<T> {\n  return { id: snap.id, ...snap.data() };\n}\n\n/**\n * Base options shared across all Firestore hooks.\n */\nexport interface FirestoreBaseOptions {\n  /** React Query cache key */\n  queryKey: readonly unknown[];\n  /** Enable/disable the query */\n  enabled?: boolean;\n  /** Stale time override (ms) */\n  staleTime?: number;\n  /** Garbage collection time override (ms) */\n  gcTime?: number;\n}\n\n/**\n * Options for single document queries.\n */\nexport interface FirestoreDocOptions<T> extends FirestoreBaseOptions {\n  /** Full document path (e.g., 'users/abc123') */\n  docPath: string;\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to document data. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for collection queries.\n */\nexport interface FirestoreCollectionOptions<T> extends FirestoreBaseOptions {\n  /** Collection path (e.g., 'users' or 'entities/abc/members') */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy, etc.) */\n  constraints?: QueryConstraint[];\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for infinite scroll queries.\n */\nexport interface FirestoreInfiniteOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy - required for pagination) */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 20) */\n  pageSize?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for paginated queries with page numbers.\n */\nexport interface FirestorePaginatedOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 10) */\n  pageSize?: number;\n  /** Initial page number (default: 1) */\n  initialPage?: number;\n  /** Re-read the displayed page every `refetchInterval` ms while it is mounted (omit for none). */\n  refetchInterval?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for count() aggregation queries.\n */\nexport interface FirestoreCountOptions extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, etc.) applied before counting */\n  constraints?: QueryConstraint[];\n  /** Polling interval in ms (omit for no polling) */\n  refetchInterval?: number;\n}\n\n/**\n * Options for a live newest-window + cursor-bridged older-pages list\n * (e.g. chat messages, live comment threads, live activity feeds). The newest\n * page is a realtime onSnapshot window; older pages load on demand via getDocs,\n * seeded from the window's oldest document so there is no gap or re-read.\n */\nexport interface FirestoreLiveInfiniteOptions<T = DocumentData & { id: string }> {\n  /** Collection path (slash-joined for nested paths, e.g. 'chats/t1/messages'). */\n  collectionPath: string;\n  /** React Query cache key. The older-pages query is keyed under `[...queryKey, 'older']`. */\n  queryKey: readonly unknown[];\n  /** Field both the live window and older pages order by (descending under the hood). */\n  orderByField: string;\n  /** Equality/filter constraints. Do NOT pass orderBy/limit/startAfter — the hook adds those. */\n  constraints?: QueryConstraint[];\n  /** Items per page / live-window size (default 20, capped at 100). */\n  pageSize?: number;\n  /** When false, no listener is opened and no pages are fetched. */\n  enabled?: boolean;\n  /** Map each raw doc (id included) to the item shape. Default: identity (WithId). */\n  select?: (data: DocumentData & { id: string }) => T;\n  /** Numeric sort key from a raw doc (id included). Default: reads `orderByField` as a number. */\n  getSortValue?: (data: DocumentData & { id: string }) => number;\n  /** Output ordering of the merged list. Default 'asc' (oldest → newest). */\n  sort?: 'asc' | 'desc';\n}\n\n/**\n * Result page for infinite queries.\n */\nexport interface InfinitePage<T> {\n  items: WithId<T>[];\n  lastDoc: DocumentSnapshot | null;\n  size: number;\n}\n\n/**\n * One page's cache entry for `useFirestorePaginated`, stored at `[...queryKey, 'page', n]`:\n * the page's rows, its last row (the next page's cursor; `null` for an empty page), and\n * whether a further page exists (read with a one-row look-ahead), and the id of the row it\n * was read after (`null` for page 1), checked against the previous page's cursor.\n */\nexport interface PaginatedPage<T> {\n  items: T[];\n  cursor: DocumentSnapshot | null;\n  hasMore: boolean;\n  after: string | null;\n}\n\n/**\n * Mutation operation types for batch mutations.\n */\nexport type MutationOperation =\n  | { type: 'set'; docPath: string; data: DocumentData; merge?: boolean }\n  | { type: 'update'; docPath: string; data: DocumentData }\n  | { type: 'delete'; docPath: string };\n\n/**\n * Options for document mutations.\n */\nexport interface FirestoreMutationOptions<T> {\n  /** Document path for single-doc mutations */\n  docPath?: string;\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Enable optimistic updates */\n  optimistic?: {\n    /** Query key of the cache to update */\n    queryKey: readonly unknown[];\n    /** How to update the cached data */\n    updater: (oldData: T | undefined, newData: Partial<T>) => T;\n  };\n}\n\n/**\n * Options for batch mutations.\n */\nexport interface FirestoreBatchOptions {\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Max operations per batch (default: 450) */\n  batchSize?: number;\n}\n"]}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { STALE_TIMES } from './defaults.js';
-export { invalidateByPrefix, removeByPrefix, updateQueryData } from './cache-helpers.js';
-export type { WithId, FirestoreSourceState, WithSourceState, FirestoreBaseOptions, FirestoreDocOptions, FirestoreCollectionOptions, FirestoreInfiniteOptions, FirestorePaginatedOptions, InfinitePage, PaginatedResult, MutationOperation, FirestoreMutationOptions, FirestoreBatchOptions, } from './firestore/types.js';
+export { invalidateByPrefix, removeByPrefix, updateQueryData, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, } from './cache-helpers.js';
+export type { WithId, FirestoreSourceState, WithSourceState, BatchFirestoreDocOutcome, FirestoreBaseOptions, FirestoreDocOptions, FirestoreCollectionOptions, FirestoreInfiniteOptions, FirestorePaginatedOptions, InfinitePage, PaginatedPage, MutationOperation, FirestoreMutationOptions, FirestoreBatchOptions, } from './firestore/types.js';
 export { docWithId } from './firestore/types.js';
 export { flattenInfiniteData, getInfiniteDataCount, } from './firestore/infinite-helpers.js';
 export type { FirestoreSearchConfig, FirestoreSearchOptions, SearchEqualityFilter, } from './search/types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGzF,YAAY,EACV,MAAM,EACN,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AAGzC,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,4BAA4B,EAC5B,KAAK,EACL,MAAM,EACN,SAAS,EACT,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,sBAAsB,EACtB,+BAA+B,EAC/B,iBAAiB,EACjB,WAAW,GACZ,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,MAAM,EACN,oBAAoB,EACpB,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AAGzC,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,4BAA4B,EAC5B,KAAK,EACL,MAAM,EACN,SAAS,EACT,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,sBAAsB,EACtB,+BAA+B,EAC/B,iBAAiB,EACjB,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 // Query defaults & staleTime presets (server-safe — plain constants, no React runtime)
 export { STALE_TIMES } from './defaults.js';
 // Cache Helpers
-export { invalidateByPrefix, removeByPrefix, updateQueryData } from './cache-helpers.js';
+export { invalidateByPrefix, removeByPrefix, updateQueryData, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, } from './cache-helpers.js';
 export { docWithId } from './firestore/types.js';
 export { flattenInfiniteData, getInfiniteDataCount, } from './firestore/infinite-helpers.js';
 // Domain-event invalidator (mechanism — consumers register their event registry)

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,gBAAgB;AAChB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAkBzF,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AASzC,iFAAiF;AACjF,OAAO,EACL,4BAA4B,EAC5B,KAAK,EACL,MAAM,EACN,SAAS,EACT,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC","sourcesContent":["// Query defaults & staleTime presets (server-safe — plain constants, no React runtime)\nexport { STALE_TIMES } from './defaults.js';\n\n// Cache Helpers\nexport { invalidateByPrefix, removeByPrefix, updateQueryData } from './cache-helpers.js';\n\n// Firestore Types & Pure Helpers\nexport type {\n  WithId,\n  FirestoreSourceState,\n  WithSourceState,\n  FirestoreBaseOptions,\n  FirestoreDocOptions,\n  FirestoreCollectionOptions,\n  FirestoreInfiniteOptions,\n  FirestorePaginatedOptions,\n  InfinitePage,\n  PaginatedResult,\n  MutationOperation,\n  FirestoreMutationOptions,\n  FirestoreBatchOptions,\n} from './firestore/types.js';\nexport { docWithId } from './firestore/types.js';\nexport {\n  flattenInfiniteData,\n  getInfiniteDataCount,\n} from './firestore/infinite-helpers.js';\n\n// Search Types\nexport type {\n  FirestoreSearchConfig,\n  FirestoreSearchOptions,\n  SearchEqualityFilter,\n} from './search/types.js';\n\n// Domain-event invalidator (mechanism — consumers register their event registry)\nexport {\n  createDomainEventInvalidator,\n  exact,\n  prefix,\n  predicate,\n  serializeInvalidation,\n  applyInvalidations,\n} from \"./domain-events/index.js\";\nexport type {\n  DomainEventInvalidator,\n  DomainEventInvalidationRegistry,\n  CacheInvalidation,\n  RefetchType,\n} from \"./domain-events/index.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,gBAAgB;AAChB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AAmB5B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AASzC,iFAAiF;AACjF,OAAO,EACL,4BAA4B,EAC5B,KAAK,EACL,MAAM,EACN,SAAS,EACT,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC","sourcesContent":["// Query defaults & staleTime presets (server-safe — plain constants, no React runtime)\nexport { STALE_TIMES } from './defaults.js';\n\n// Cache Helpers\nexport {\n  invalidateByPrefix,\n  removeByPrefix,\n  updateQueryData,\n  paginatedPageKey,\n  mapPaginatedItems,\n  prependToFirstPaginatedPage,\n} from './cache-helpers.js';\n\n// Firestore Types & Pure Helpers\nexport type {\n  WithId,\n  FirestoreSourceState,\n  WithSourceState,\n  BatchFirestoreDocOutcome,\n  FirestoreBaseOptions,\n  FirestoreDocOptions,\n  FirestoreCollectionOptions,\n  FirestoreInfiniteOptions,\n  FirestorePaginatedOptions,\n  InfinitePage,\n  PaginatedPage,\n  MutationOperation,\n  FirestoreMutationOptions,\n  FirestoreBatchOptions,\n} from './firestore/types.js';\nexport { docWithId } from './firestore/types.js';\nexport {\n  flattenInfiniteData,\n  getInfiniteDataCount,\n} from './firestore/infinite-helpers.js';\n\n// Search Types\nexport type {\n  FirestoreSearchConfig,\n  FirestoreSearchOptions,\n  SearchEqualityFilter,\n} from './search/types.js';\n\n// Domain-event invalidator (mechanism — consumers register their event registry)\nexport {\n  createDomainEventInvalidator,\n  exact,\n  prefix,\n  predicate,\n  serializeInvalidation,\n  applyInvalidations,\n} from \"./domain-events/index.js\";\nexport type {\n  DomainEventInvalidator,\n  DomainEventInvalidationRegistry,\n  CacheInvalidation,\n  RefetchType,\n} from \"./domain-events/index.js\";\n"]}

package/dist/react/firestore/doc-subscription-registry.d.ts

@@ -9,6 +9,12 @@ import type { QueryClient } from '@tanstack/react-query';
  * The one-shot `queryFn` consults this after its read and yields to the listener's value.
  */
 export declare function isListenerOwned(queryClient: QueryClient, queryKeyPrefix: string, id: string): boolean;
+/**
+ * The error of the shared listener that owns `[queryKeyPrefix, id]`, or `null` when no listener
+ * owns the key or it has not errored. The listener writes `null` to the key when it errors, so a
+ * one-shot reader of the same key consults this before taking that `null` as a missing document.
+ */
+export declare function listenerErrorOf(queryClient: QueryClient, queryKeyPrefix: string, id: string): Error | null;
 export interface SubscribeDocParams {
     queryClient: QueryClient;
     db: Firestore;
@@ -19,7 +25,7 @@ export interface SubscribeDocParams {
     id: string;
     /** Called whenever a snapshot (data or missing) lands, so the caller can re-render. */
     onUpdate: () => void;
-    /** Called on listener error. */
+    /** Called on listener error — and at once on joining a listener that has already errored. */
     onError?: (error: Error) => void;
 }
 /**

package/dist/react/firestore/doc-subscription-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc-subscription-registry.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/doc-subscription-registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAwCzD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,GACT,OAAO,CAET;AAWD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,uFAAuF;IACvF,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,IAAI,CA+CnE;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAEtE"}
+{"version":3,"file":"doc-subscription-registry.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/doc-subscription-registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AA8CzD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,GACT,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,GACT,KAAK,GAAG,IAAI,CAEd;AAWD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,uFAAuF;IACvF,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAwDnE;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAEtE"}

package/dist/react/firestore/doc-subscription-registry.js

@@ -16,6 +16,14 @@ function registryKey(queryKeyPrefix, id) {
 export function isListenerOwned(queryClient, queryKeyPrefix, id) {
     return registries.get(queryClient)?.has(registryKey(queryKeyPrefix, id)) ?? false;
 }
+/**
+ * The error of the shared listener that owns `[queryKeyPrefix, id]`, or `null` when no listener
+ * owns the key or it has not errored. The listener writes `null` to the key when it errors, so a
+ * one-shot reader of the same key consults this before taking that `null` as a missing document.
+ */
+export function listenerErrorOf(queryClient, queryKeyPrefix, id) {
+    return registries.get(queryClient)?.get(registryKey(queryKeyPrefix, id))?.error ?? null;
+}
 function getRegistry(queryClient) {
     let registry = registries.get(queryClient);
     if (!registry) {
@@ -35,26 +43,31 @@ export function subscribeDoc(params) {
     const key = registryKey(queryKeyPrefix, id);
     let entry = registry.get(key);
     if (!entry) {
-        const subscribers = new Set();
+        const created = { unsubscribe: () => { }, subscribers: new Set(), error: null };
+        const subscribers = created.subscribers;
         const ref = doc(db, collectionPath, id);
-        const unsubscribe = onSnapshot(ref, (snapshot) => {
+        created.unsubscribe = onSnapshot(ref, (snapshot) => {
+            created.error = null;
             queryClient.setQueryData([queryKeyPrefix, id], snapshot.exists() ? { id: snapshot.id, ...snapshot.data() } : null, { updatedAt: Date.now() });
             // Copy before iterating: an onUpdate could (re-entrantly) unsubscribe.
             for (const sub of [...subscribers])
                 sub.onUpdate();
         }, (error) => {
-            // Negative-cache the id: a denied doc is resolved-absent. Without this,
-            // subscribe-mode loading state ("no cache entry yet") would stay true
-            // forever for ids whose listener can never land a snapshot.
+            // Write `null` so the id resolves — as a failure, through the kept error — instead
+            // of loading forever: subscribe-mode loading ("no cache entry yet") would otherwise
+            // stay true for ids whose listener can never land a snapshot.
+            created.error = error;
             queryClient.setQueryData([queryKeyPrefix, id], null, { updatedAt: Date.now() });
             for (const sub of [...subscribers])
                 sub.onError?.(error);
         });
-        entry = { unsubscribe, subscribers };
+        entry = created;
         registry.set(key, entry);
     }
     const subscriber = { onUpdate, onError };
     entry.subscribers.add(subscriber);
+    if (entry.error)
+        onError?.(entry.error);
     let released = false;
     return () => {
         if (released)
@@ -67,6 +80,11 @@ export function subscribeDoc(params) {
         if (current.subscribers.size === 0) {
             current.unsubscribe();
             registry.delete(key);
+            // A failed listener's `null` is a placeholder, not a read: once nothing owns the key,
+            // mark it stale so a remaining one-shot reader reads the document for itself.
+            if (current.error) {
+                void queryClient.invalidateQueries({ queryKey: [queryKeyPrefix, id], exact: true });
+            }
         }
     };
 }

package/dist/react/firestore/doc-subscription-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"doc-subscription-registry.js","sourceRoot":"","sources":["../../../src/react/firestore/doc-subscription-registry.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { doc, onSnapshot, type Firestore } from 'firebase/firestore';\nimport type { QueryClient } from '@tanstack/react-query';\n\n/**\n * Reference-counted, real-time document subscription registry.\n *\n * Backs the `subscribe` mode of {@link useBatchFirestoreDocs}. The problem it solves:\n * many components on a page resolve the SAME document id (e.g. the same author rendered\n * in a feed card, a comment, and a mention). Without sharing, each would open its own\n * `onSnapshot` listener. This registry keeps exactly ONE Firestore listener per\n * `(queryClient, queryKeyPrefix, id)` and fans its updates out to every subscriber, so N\n * components showing the same id cost one listener.\n *\n * The single listener writes the document straight into the React Query cache at\n * `[queryKeyPrefix, id]` — `{ id, ...data }` when the doc exists, or `null` when it does\n * not (negative caching, so a missing/lagging doc resolves the instant it appears instead\n * of staying blank until staleTime). A listener ERROR also negative-caches the id: a\n * rules-denied doc (hidden, or non-existent when the rule references `resource.data`) is\n * resolved-absent, not forever-loading — consumers see `data: null` plus the error instead\n * of an eternal spinner. The registry is keyed per `QueryClient` (a WeakMap), which in\n * practice means per browser tab, so each tab listens independently and stays consistent\n * without cross-tab plumbing.\n */\n\ntype Subscriber = {\n  onUpdate: () => void;\n  onError?: (error: Error) => void;\n};\n\ntype Entry = {\n  unsubscribe: () => void;\n  subscribers: Set<Subscriber>;\n};\n\n// Per-QueryClient registry. WeakMap so a discarded QueryClient (and its entries) is GC'd.\nconst registries = new WeakMap<QueryClient, Map<string, Entry>>();\n\nfunction registryKey(queryKeyPrefix: string, id: string): string {\n  return `${queryKeyPrefix} ${id}`;\n}\n\n/**\n * True while a shared listener owns `[queryKeyPrefix, id]` for this client.\n *\n * A one-shot read that was already in flight when a consumer entered subscribe mode would\n * otherwise resolve AFTER the listener's first snapshot and overwrite it — and `onSnapshot`\n * does not re-emit until the document actually changes, so the stale value would stick.\n * The one-shot `queryFn` consults this after its read and yields to the listener's value.\n */\nexport function isListenerOwned(\n  queryClient: QueryClient,\n  queryKeyPrefix: string,\n  id: string,\n): boolean {\n  return registries.get(queryClient)?.has(registryKey(queryKeyPrefix, id)) ?? false;\n}\n\nfunction getRegistry(queryClient: QueryClient): Map<string, Entry> {\n  let registry = registries.get(queryClient);\n  if (!registry) {\n    registry = new Map();\n    registries.set(queryClient, registry);\n  }\n  return registry;\n}\n\nexport interface SubscribeDocParams {\n  queryClient: QueryClient;\n  db: Firestore;\n  /** Top-level/full collection path the doc lives in (e.g. 'publicUsers'). */\n  collectionPath: string;\n  /** Cache key prefix; the doc is cached at `[queryKeyPrefix, id]`. */\n  queryKeyPrefix: string;\n  id: string;\n  /** Called whenever a snapshot (data or missing) lands, so the caller can re-render. */\n  onUpdate: () => void;\n  /** Called on listener error. */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Subscribe to a single document via a shared, reference-counted listener.\n * Returns an idempotent unsubscribe function; the underlying Firestore listener is\n * detached only when the last subscriber for that id unsubscribes.\n */\nexport function subscribeDoc(params: SubscribeDocParams): () => void {\n  const { queryClient, db, collectionPath, queryKeyPrefix, id, onUpdate, onError } = params;\n  const registry = getRegistry(queryClient);\n  const key = registryKey(queryKeyPrefix, id);\n\n  let entry = registry.get(key);\n  if (!entry) {\n    const subscribers = new Set<Subscriber>();\n    const ref = doc(db, collectionPath, id);\n    const unsubscribe = onSnapshot(\n      ref,\n      (snapshot) => {\n        queryClient.setQueryData(\n          [queryKeyPrefix, id],\n          snapshot.exists() ? { id: snapshot.id, ...snapshot.data() } : null,\n          { updatedAt: Date.now() },\n        );\n        // Copy before iterating: an onUpdate could (re-entrantly) unsubscribe.\n        for (const sub of [...subscribers]) sub.onUpdate();\n      },\n      (error) => {\n        // Negative-cache the id: a denied doc is resolved-absent. Without this,\n        // subscribe-mode loading state (\"no cache entry yet\") would stay true\n        // forever for ids whose listener can never land a snapshot.\n        queryClient.setQueryData([queryKeyPrefix, id], null, { updatedAt: Date.now() });\n        for (const sub of [...subscribers]) sub.onError?.(error);\n      },\n    );\n    entry = { unsubscribe, subscribers };\n    registry.set(key, entry);\n  }\n\n  const subscriber: Subscriber = { onUpdate, onError };\n  entry.subscribers.add(subscriber);\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n    const current = registry.get(key);\n    if (!current) return;\n    current.subscribers.delete(subscriber);\n    if (current.subscribers.size === 0) {\n      current.unsubscribe();\n      registry.delete(key);\n    }\n  };\n}\n\n/** Test-only: number of active shared listeners for a QueryClient. */\nexport function __activeListenerCount(queryClient: QueryClient): number {\n  return registries.get(queryClient)?.size ?? 0;\n}\n"]}
+{"version":3,"file":"doc-subscription-registry.js","sourceRoot":"","sources":["../../../src/react/firestore/doc-subscription-registry.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { doc, onSnapshot, type Firestore } from 'firebase/firestore';\nimport type { QueryClient } from '@tanstack/react-query';\n\n/**\n * Reference-counted, real-time document subscription registry.\n *\n * Backs the `subscribe` mode of {@link useBatchFirestoreDocs}. The problem it solves:\n * many components on a page resolve the SAME document id (e.g. the same author rendered\n * in a feed card, a comment, and a mention). Without sharing, each would open its own\n * `onSnapshot` listener. This registry keeps exactly ONE Firestore listener per\n * `(queryClient, queryKeyPrefix, id)` and fans its updates out to every subscriber, so N\n * components showing the same id cost one listener.\n *\n * The single listener writes the document straight into the React Query cache at\n * `[queryKeyPrefix, id]` — `{ id, ...data }` when the doc exists, or `null` when it does\n * not (negative caching, so a missing/lagging doc resolves the instant it appears instead\n * of staying blank until staleTime). A listener ERROR also negative-caches the id: a\n * rules-denied doc (hidden, or non-existent when the rule references `resource.data`) is\n * resolved, not forever-loading — consumers see `data: null` plus the error instead\n * of an eternal spinner. Firestore ends a listener that errors, so the entry keeps that error\n * for as long as the entry lives (until its last subscriber leaves; a later snapshot, were one\n * to arrive, clears it): a subscriber that joins an errored listener receives the error too,\n * and a one-shot reader of the same key reads it through `listenerErrorOf`, so neither takes\n * the cached `null` as a missing document. The registry is keyed per `QueryClient` (a WeakMap),\n * which in practice means per browser tab, so each tab listens independently and stays\n * consistent without cross-tab plumbing.\n */\n\ntype Subscriber = {\n  onUpdate: () => void;\n  onError?: (error: Error) => void;\n};\n\ntype Entry = {\n  unsubscribe: () => void;\n  subscribers: Set<Subscriber>;\n  /** The listener's last error, cleared by the next snapshot. */\n  error: Error | null;\n};\n\n// Per-QueryClient registry. WeakMap so a discarded QueryClient (and its entries) is GC'd.\nconst registries = new WeakMap<QueryClient, Map<string, Entry>>();\n\nfunction registryKey(queryKeyPrefix: string, id: string): string {\n  return `${queryKeyPrefix} ${id}`;\n}\n\n/**\n * True while a shared listener owns `[queryKeyPrefix, id]` for this client.\n *\n * A one-shot read that was already in flight when a consumer entered subscribe mode would\n * otherwise resolve AFTER the listener's first snapshot and overwrite it — and `onSnapshot`\n * does not re-emit until the document actually changes, so the stale value would stick.\n * The one-shot `queryFn` consults this after its read and yields to the listener's value.\n */\nexport function isListenerOwned(\n  queryClient: QueryClient,\n  queryKeyPrefix: string,\n  id: string,\n): boolean {\n  return registries.get(queryClient)?.has(registryKey(queryKeyPrefix, id)) ?? false;\n}\n\n/**\n * The error of the shared listener that owns `[queryKeyPrefix, id]`, or `null` when no listener\n * owns the key or it has not errored. The listener writes `null` to the key when it errors, so a\n * one-shot reader of the same key consults this before taking that `null` as a missing document.\n */\nexport function listenerErrorOf(\n  queryClient: QueryClient,\n  queryKeyPrefix: string,\n  id: string,\n): Error | null {\n  return registries.get(queryClient)?.get(registryKey(queryKeyPrefix, id))?.error ?? null;\n}\n\nfunction getRegistry(queryClient: QueryClient): Map<string, Entry> {\n  let registry = registries.get(queryClient);\n  if (!registry) {\n    registry = new Map();\n    registries.set(queryClient, registry);\n  }\n  return registry;\n}\n\nexport interface SubscribeDocParams {\n  queryClient: QueryClient;\n  db: Firestore;\n  /** Top-level/full collection path the doc lives in (e.g. 'publicUsers'). */\n  collectionPath: string;\n  /** Cache key prefix; the doc is cached at `[queryKeyPrefix, id]`. */\n  queryKeyPrefix: string;\n  id: string;\n  /** Called whenever a snapshot (data or missing) lands, so the caller can re-render. */\n  onUpdate: () => void;\n  /** Called on listener error — and at once on joining a listener that has already errored. */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Subscribe to a single document via a shared, reference-counted listener.\n * Returns an idempotent unsubscribe function; the underlying Firestore listener is\n * detached only when the last subscriber for that id unsubscribes.\n */\nexport function subscribeDoc(params: SubscribeDocParams): () => void {\n  const { queryClient, db, collectionPath, queryKeyPrefix, id, onUpdate, onError } = params;\n  const registry = getRegistry(queryClient);\n  const key = registryKey(queryKeyPrefix, id);\n\n  let entry = registry.get(key);\n  if (!entry) {\n    const created: Entry = { unsubscribe: () => {}, subscribers: new Set<Subscriber>(), error: null };\n    const subscribers = created.subscribers;\n    const ref = doc(db, collectionPath, id);\n    created.unsubscribe = onSnapshot(\n      ref,\n      (snapshot) => {\n        created.error = null;\n        queryClient.setQueryData(\n          [queryKeyPrefix, id],\n          snapshot.exists() ? { id: snapshot.id, ...snapshot.data() } : null,\n          { updatedAt: Date.now() },\n        );\n        // Copy before iterating: an onUpdate could (re-entrantly) unsubscribe.\n        for (const sub of [...subscribers]) sub.onUpdate();\n      },\n      (error) => {\n        // Write `null` so the id resolves — as a failure, through the kept error — instead\n        // of loading forever: subscribe-mode loading (\"no cache entry yet\") would otherwise\n        // stay true for ids whose listener can never land a snapshot.\n        created.error = error;\n        queryClient.setQueryData([queryKeyPrefix, id], null, { updatedAt: Date.now() });\n        for (const sub of [...subscribers]) sub.onError?.(error);\n      },\n    );\n    entry = created;\n    registry.set(key, entry);\n  }\n\n  const subscriber: Subscriber = { onUpdate, onError };\n  entry.subscribers.add(subscriber);\n  if (entry.error) onError?.(entry.error);\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n    const current = registry.get(key);\n    if (!current) return;\n    current.subscribers.delete(subscriber);\n    if (current.subscribers.size === 0) {\n      current.unsubscribe();\n      registry.delete(key);\n      // A failed listener's `null` is a placeholder, not a read: once nothing owns the key,\n      // mark it stale so a remaining one-shot reader reads the document for itself.\n      if (current.error) {\n        void queryClient.invalidateQueries({ queryKey: [queryKeyPrefix, id], exact: true });\n      }\n    }\n  };\n}\n\n/** Test-only: number of active shared listeners for a QueryClient. */\nexport function __activeListenerCount(queryClient: QueryClient): number {\n  return registries.get(queryClient)?.size ?? 0;\n}\n"]}

package/dist/react/firestore/subscription-status.d.ts

@@ -0,0 +1,21 @@
+import type { FirestoreSourceState } from '../../firestore/types.js';
+interface SubscriptionStatus {
+    identity: string;
+    error: Error | null;
+    sourceState: FirestoreSourceState;
+}
+type StatusPatch = Partial<Omit<SubscriptionStatus, 'identity'>>;
+/**
+ * A realtime listener's source state and error, tagged to the subscription identity that
+ * produced them. A new identity reads `connecting` with no error from its first render;
+ * writes made for a retired identity are dropped once the new identity's listener has
+ * started (it calls `reset`).
+ */
+export declare function useSubscriptionStatus(identity: string): {
+    error: Error | null;
+    sourceState: FirestoreSourceState;
+    reset: () => void;
+    update: (patch: StatusPatch | ((prev: SubscriptionStatus) => StatusPatch)) => void;
+};
+export {};
+//# sourceMappingURL=subscription-status.d.ts.map

package/dist/react/firestore/subscription-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-status.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/subscription-status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,oBAAoB,CAAC;CACnC;AAED,KAAK,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM;;;;oBAe1C,WAAW,GAAG,CAAC,CAAC,IAAI,EAAE,kBAAkB,KAAK,WAAW,CAAC;EAWpE"}

package/dist/react/firestore/subscription-status.js

@@ -0,0 +1,29 @@
+'use client';
+import { useCallback, useState } from 'react';
+/**
+ * A realtime listener's source state and error, tagged to the subscription identity that
+ * produced them. A new identity reads `connecting` with no error from its first render;
+ * writes made for a retired identity are dropped once the new identity's listener has
+ * started (it calls `reset`).
+ */
+export function useSubscriptionStatus(identity) {
+    const [status, setStatus] = useState(() => ({
+        identity,
+        error: null,
+        sourceState: 'connecting',
+    }));
+    const current = status.identity === identity ? status : { identity, error: null, sourceState: 'connecting' };
+    const reset = useCallback(() => {
+        setStatus({ identity, error: null, sourceState: 'connecting' });
+    }, [identity]);
+    const update = useCallback((patch) => {
+        setStatus((prev) => {
+            if (prev.identity !== identity)
+                return prev;
+            const next = typeof patch === 'function' ? patch(prev) : patch;
+            return { ...prev, ...next };
+        });
+    }, [identity]);
+    return { error: current.error, sourceState: current.sourceState, reset, update };
+}
+//# sourceMappingURL=subscription-status.js.map

package/dist/react/firestore/subscription-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-status.js","sourceRoot":"","sources":["../../../src/react/firestore/subscription-status.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAW9C;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAqB,GAAG,EAAE,CAAC,CAAC;QAC9D,QAAQ;QACR,KAAK,EAAE,IAAI;QACX,WAAW,EAAE,YAAY;KAC1B,CAAC,CAAC,CAAC;IAEJ,MAAM,OAAO,GACX,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;IAE/F,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC,CAAC;IAClE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,KAAgE,EAAE,EAAE;QACnE,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YACjB,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC5C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAC/D,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QAC9B,CAAC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACnF,CAAC","sourcesContent":["'use client';\n\nimport { useCallback, useState } from 'react';\nimport type { FirestoreSourceState } from '../../firestore/types.js';\n\ninterface SubscriptionStatus {\n  identity: string;\n  error: Error | null;\n  sourceState: FirestoreSourceState;\n}\n\ntype StatusPatch = Partial<Omit<SubscriptionStatus, 'identity'>>;\n\n/**\n * A realtime listener's source state and error, tagged to the subscription identity that\n * produced them. A new identity reads `connecting` with no error from its first render;\n * writes made for a retired identity are dropped once the new identity's listener has\n * started (it calls `reset`).\n */\nexport function useSubscriptionStatus(identity: string) {\n  const [status, setStatus] = useState<SubscriptionStatus>(() => ({\n    identity,\n    error: null,\n    sourceState: 'connecting',\n  }));\n\n  const current: SubscriptionStatus =\n    status.identity === identity ? status : { identity, error: null, sourceState: 'connecting' };\n\n  const reset = useCallback(() => {\n    setStatus({ identity, error: null, sourceState: 'connecting' });\n  }, [identity]);\n\n  const update = useCallback(\n    (patch: StatusPatch | ((prev: SubscriptionStatus) => StatusPatch)) => {\n      setStatus((prev) => {\n        if (prev.identity !== identity) return prev;\n        const next = typeof patch === 'function' ? patch(prev) : patch;\n        return { ...prev, ...next };\n      });\n    },\n    [identity],\n  );\n\n  return { error: current.error, sourceState: current.sourceState, reset, update };\n}\n"]}

package/dist/react/firestore/use-firestore-collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-collection.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-collection.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EACV,0BAA0B,EAE1B,MAAM,EACN,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAC5E,cAAc,EACd,QAAQ,EACR,WAAgB,EAChB,OAAc,EACd,SAAiB,EACjB,SAAS,EACT,MAAM,EACN,MAAM,GACP,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CA8HrF"}
+{"version":3,"file":"use-firestore-collection.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-collection.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EACV,0BAA0B,EAC1B,MAAM,EACN,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAC5E,cAAc,EACd,QAAQ,EACR,WAAgB,EAChB,OAAc,EACd,SAAiB,EACjB,SAAS,EACT,MAAM,EACN,MAAM,GACP,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAiIrF"}

package/dist/react/firestore/use-firestore-collection.js

@@ -1,9 +1,10 @@
 'use client';
-import { useEffect, useState } from 'react';
+import { useEffect } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { collection, query, getDocs, onSnapshot, } from 'firebase/firestore';
 import { useFirestoreDb } from './context.js';
 import { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';
+import { useSubscriptionStatus } from './subscription-status.js';
 /**
  * Fetch all documents from a Firestore collection with optional realtime updates.
  * Use this for small collections where you need all documents at once.
@@ -32,15 +33,12 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
     const constraintsMemo = JSON.stringify(constraints);
     const queryKeyMemo = JSON.stringify(queryKey);
     // Listener errors can't surface through useQuery (the queryFn is disabled while
-    // subscribed), so they're tracked here and merged into the returned result.
-    const [subscriptionError, setSubscriptionError] = useState(null);
-    // Metadata-derived source state — reset whenever the subscription identity changes.
-    const [sourceState, setSourceState] = useState('connecting');
+    // subscribed), so they're tracked per subscription identity and merged into the result.
+    const { error: subscriptionError, sourceState, reset: resetStatus, update: updateStatus, } = useSubscriptionStatus(JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe]));
     useEffect(() => {
         if (!subscribe || !enabled)
             return;
-        setSubscriptionError(null);
-        setSourceState('connecting');
+        resetStatus();
         // Bounded resubscribe: a transient `permission-denied` (e.g. a failed mid-session
         // App Check token refresh) is retried on the RESUBSCRIBE_DELAYS_MS ladder before the
         // error is surfaced. `attempt` resets on any healthy snapshot; `disposed`/timers are
@@ -58,7 +56,7 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
                 : collectionRef;
             currentUnsubscribe = onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
                 attempt = 0;
-                setSubscriptionError(null);
+                updateStatus({ error: null });
                 const items = snapshot.docs.map((docSnap) => {
                     const rawData = docSnap.data();
                     const dataWithId = { id: docSnap.id, ...rawData };
@@ -67,7 +65,7 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
                 });
                 queryClient.setQueryData(queryKey, items);
                 const fromCache = snapshot.metadata?.fromCache ?? false;
-                setSourceState((prev) => (fromCache ? (prev === 'connecting' ? 'connecting' : 'offline') : 'live'));
+                updateStatus((prev) => ({ sourceState: fromCache ? (prev.sourceState === 'connecting' ? 'connecting' : 'offline') : 'live' }));
             }, (error) => {
                 // Heal a transient permission-denied by resubscribing on the backoff ladder,
                 // keeping the last-known data visible. Only surface the error once the ladder
@@ -77,13 +75,12 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
                     currentUnsubscribe = null;
                     const delay = RESUBSCRIBE_DELAYS_MS[attempt];
                     attempt += 1;
-                    setSourceState('connecting');
+                    updateStatus({ sourceState: 'connecting' });
                     retryTimer = setTimeout(start, delay);
                     return;
                 }
                 console.error('[useFirestoreCollection] Subscription error:', error);
-                setSubscriptionError(error);
-                setSourceState('error');
+                updateStatus({ error, sourceState: 'error' });
                 queryClient.setQueryData(queryKey, undefined);
             });
         };
@@ -97,7 +94,7 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
         // queryKey & constraints are tracked via their stringified forms above; select is intentionally
         // excluded so an inline caller function doesn't force a re-subscribe on every render.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [db, collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe, queryClient]);
+    }, [db, collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe, queryClient, resetStatus, updateStatus]);
     const queryResult = useQuery({
         queryKey,
         queryFn: async () => {