@ttt-productions/query-core 0.14.17 → 0.14.18

package/dist/cache-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { QueryClient, QueryKey } from '@tanstack/react-query';
+import type { InfiniteData, QueryClient, QueryKey } from '@tanstack/react-query';
 /** Invalidate everything that matches a key prefix. */
 export declare function invalidateByPrefix(client: QueryClient, prefix: QueryKey): Promise<void>;
 /** Remove everything that matches a key prefix (drops cached data). */
@@ -25,4 +25,24 @@ export declare function mapPaginatedItems<T>(client: QueryClient, queryKey: Quer
  * before showing it.
  */
 export declare function prependToFirstPaginatedPage<T>(client: QueryClient, queryKey: QueryKey, item: T): void;
+/** How `placeRowInPages` reads and writes one infinite list's pages. */
+export interface PagedRows<P, T> {
+    rowsOf: (page: P) => readonly T[];
+    withRows: (page: P, rows: T[]) => P;
+    /** True when `candidate` is the row being placed (its id). */
+    isRow: (candidate: T) => boolean;
+    /** True when `a` comes before `b` in the list's own order. */
+    sortsBefore: (a: T, b: T) => boolean;
+    /** True when this page is not the last one the source holds (a next page exists). */
+    hasMoreAfter: (page: P) => boolean;
+}
+/**
+ * Place, move, or drop ONE row in a cached infinite list's loaded pages, in place: the row leaves
+ * wherever it sits and, when `belongs`, joins at its position in the list's own order. A row that
+ * sorts after every loaded row is added only when no further page exists; otherwise the next page
+ * read returns it, so placing it here would list it twice. Every other row, every page, and every
+ * cursor stays put; a list the row neither left nor joined is returned as it was. Never a reset to the
+ * first page.
+ */
+export declare function placeRowInPages<P, T, TParam = unknown>(data: InfiniteData<P, TParam> | undefined, row: T, belongs: boolean, how: PagedRows<P, T>): InfiniteData<P, TParam> | undefined;
 //# 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;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"}
+{"version":3,"file":"cache-helpers.d.ts","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjF,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;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS,CAAC,CAAC,EAAE,CAAC;IAC7B,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;IAClC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACpC,8DAA8D;IAC9D,KAAK,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO,CAAC;IACjC,8DAA8D;IAC9D,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IACrC,qFAAqF;IACrF,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,EACpD,IAAI,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,SAAS,EACzC,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GACnB,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,SAAS,CA2BrC"}

package/dist/cache-helpers.js

@@ -61,4 +61,43 @@ export function prependToFirstPaginatedPage(client, queryKey, item) {
         return;
     client.setQueryData(key, { ...value, items: [item, ...value.items] });
 }
+/**
+ * Place, move, or drop ONE row in a cached infinite list's loaded pages, in place: the row leaves
+ * wherever it sits and, when `belongs`, joins at its position in the list's own order. A row that
+ * sorts after every loaded row is added only when no further page exists; otherwise the next page
+ * read returns it, so placing it here would list it twice. Every other row, every page, and every
+ * cursor stays put; a list the row neither left nor joined is returned as it was. Never a reset to the
+ * first page.
+ */
+export function placeRowInPages(data, row, belongs, how) {
+    if (!data || data.pages.length === 0)
+        return data;
+    let changed = false;
+    const rows = data.pages.map((page) => {
+        const kept = how.rowsOf(page).filter((candidate) => !how.isRow(candidate));
+        if (kept.length !== how.rowsOf(page).length)
+            changed = true;
+        return kept;
+    });
+    if (belongs) {
+        let placed = false;
+        for (const pageRows of rows) {
+            const index = pageRows.findIndex((candidate) => how.sortsBefore(row, candidate));
+            if (index !== -1) {
+                pageRows.splice(index, 0, row);
+                placed = true;
+                break;
+            }
+        }
+        const lastIndex = data.pages.length - 1;
+        if (!placed && !how.hasMoreAfter(data.pages[lastIndex])) {
+            rows[lastIndex].push(row);
+            placed = true;
+        }
+        changed = changed || placed;
+    }
+    if (!changed)
+        return data;
+    return { ...data, pages: data.pages.map((page, i) => how.withRows(page, rows[i])) };
+}
 //# 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":"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"]}
+{"version":3,"file":"cache-helpers.js","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"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","sourcesContent":["import type { InfiniteData, 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\n/** How `placeRowInPages` reads and writes one infinite list's pages. */\nexport interface PagedRows<P, T> {\n  rowsOf: (page: P) => readonly T[];\n  withRows: (page: P, rows: T[]) => P;\n  /** True when `candidate` is the row being placed (its id). */\n  isRow: (candidate: T) => boolean;\n  /** True when `a` comes before `b` in the list's own order. */\n  sortsBefore: (a: T, b: T) => boolean;\n  /** True when this page is not the last one the source holds (a next page exists). */\n  hasMoreAfter: (page: P) => boolean;\n}\n\n/**\n * Place, move, or drop ONE row in a cached infinite list's loaded pages, in place: the row leaves\n * wherever it sits and, when `belongs`, joins at its position in the list's own order. A row that\n * sorts after every loaded row is added only when no further page exists; otherwise the next page\n * read returns it, so placing it here would list it twice. Every other row, every page, and every\n * cursor stays put; a list the row neither left nor joined is returned as it was. Never a reset to the\n * first page.\n */\nexport function placeRowInPages<P, T, TParam = unknown>(\n  data: InfiniteData<P, TParam> | undefined,\n  row: T,\n  belongs: boolean,\n  how: PagedRows<P, T>,\n): InfiniteData<P, TParam> | undefined {\n  if (!data || data.pages.length === 0) return data;\n  let changed = false;\n  const rows = data.pages.map((page) => {\n    const kept = how.rowsOf(page).filter((candidate) => !how.isRow(candidate));\n    if (kept.length !== how.rowsOf(page).length) changed = true;\n    return kept;\n  });\n  if (belongs) {\n    let placed = false;\n    for (const pageRows of rows) {\n      const index = pageRows.findIndex((candidate) => how.sortsBefore(row, candidate));\n      if (index !== -1) {\n        pageRows.splice(index, 0, row);\n        placed = true;\n        break;\n      }\n    }\n    const lastIndex = data.pages.length - 1;\n    if (!placed && !how.hasMoreAfter(data.pages[lastIndex])) {\n      rows[lastIndex].push(row);\n      placed = true;\n    }\n    changed = changed || placed;\n  }\n  if (!changed) return data;\n  return { ...data, pages: data.pages.map((page, i) => how.withRows(page, rows[i])) };\n}\n"]}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { STALE_TIMES } from './defaults.js';
-export { invalidateByPrefix, removeByPrefix, updateQueryData, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, } from './cache-helpers.js';
+export { invalidateByPrefix, removeByPrefix, updateQueryData, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, placeRowInPages, } from './cache-helpers.js';
+export type { PagedRows } 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';

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,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;AAC3B,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGtG,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,EAC3B,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGpD,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;AAC3B,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGtG,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, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, } from './cache-helpers.js';
+export { invalidateByPrefix, removeByPrefix, updateQueryData, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, placeRowInPages, } from './cache-helpers.js';
 export { docWithId } from './firestore/types.js';
 export { flattenInfiniteData, getInfiniteDataCount, } from './firestore/infinite-helpers.js';
 export { FIRESTORE_SEARCH_MIN_LENGTH, isSearchableText, normalizeSearchText } from './search/rule.js';

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,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;AAQzC,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEtG,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';\nexport { FIRESTORE_SEARCH_MIN_LENGTH, isSearchableText, normalizeSearchText } from './search/rule.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,EAC3B,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAoB5B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AAQzC,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEtG,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  placeRowInPages,\n} from './cache-helpers.js';\nexport type { PagedRows } 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';\nexport { FIRESTORE_SEARCH_MIN_LENGTH, isSearchableText, normalizeSearchText } from './search/rule.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttt-productions/query-core",
-  "version": "0.14.17",
+  "version": "0.14.18",
   "description": "Shared TanStack Query (React Query) client defaults, query key helpers, and Firestore integration hooks for TTT Productions apps",
   "repository": {
     "type": "git",