@marktiderman/genesis-core 1.5.1 → 1.7.0

package/README.md

@@ -101,6 +101,7 @@ const provider = createSupabaseProvider(supabase, {
 | `toFormValues(row)` | Row → edit-form values, for a form shaped differently from its table. Served as `DataProvider.toFormValues`, which `useResourceForm` applies in edit mode. The reverse is `prepare`. |
 | `invalidates` | Other query keys a write makes stale, as a list or `(event) => keys`. Served as `DataProvider.invalidates`, which `useResource` and `useResourceForm` (and so `ResourcePage` and `ResourceForm`) invalidate after their writes, on top of `[resource]`. |
 | `onWrite(event)` | Called after every committed create, update and delete, including writes made straight through the provider. Awaited; if it throws, the error is logged and the write is still reported saved. |
+| `realtime` / `resources[r].realtime` | Serve `subscribe` through Supabase Realtime, for `live` lists and records. Off by default: `true`, a list of resources, or `(resource) => boolean`; a resource's own `realtime` wins. See [Live updates](#live-updates-realtime). |
 
 Both hooks also take an `invalidates` option for keys one screen cares about:
 `useResource("tasks", { invalidates: [["me"]] })`.
@@ -232,6 +233,117 @@ const tasks = useResource("tasks", {
 await tasks.remove(id); // resolves at once; sent in 5 s unless undone
 ```
 
+## Cursor paging
+
+For long lists that grow with "Load more", page by cursor (keyset) instead of
+offset: pages stay right while rows are added or removed, and a deep page
+costs no more than the first.
+
+```ts
+const tasks = useInfiniteResource("tasks", {
+  perPage: 50,
+  defaultSort: { field: "due_at", order: "asc" },
+});
+tasks.rows;           // every loaded row
+tasks.total;          // from the first page's count
+tasks.hasNextPage && tasks.fetchNextPage();
+```
+
+- **The contract.** `getList` with `pagination: { page, perPage, cursor }`,
+  where `cursor` is `null` for the first page and the previous page's
+  `nextCursor` after that. A provider that serves it
+  (`capabilities().cursorPagination`) returns `nextCursor` (`null` on the
+  last page) and may return `total: -1` after the first page (not counted).
+  A provider that doesn't ignores `cursor` and pages by `page`;
+  `useInfiniteResource` then pages by offset until `total` rows are loaded.
+- **Supabase.**
+  - It orders by the sort column and then the `orderKey` (default `id`) and
+    fetches one row more than the page to tell whether there is a next
+    page. A page is at most `maxPerPage - 1` rows, so that extra row fits
+    under PostgREST's `max-rows`.
+  - The cursor (opaque, base64 JSON) holds the last row's sort and key
+    values and the sort it was made for. A cursor from another sort is
+    refused.
+  - The keyset filter handles ascending and descending sorts, ties (broken
+    by the key) and null sort values, matching Postgres's default null
+    placement (last when ascending, first when descending, pinned in the
+    query).
+  - It refuses, with an `invalid` `DataReadError` whose `cause` says why:
+    `orderKey: false`, a sort on an embedded field (`author.name`), a sort
+    column with non-scalar values, and a `select` that leaves out the sort
+    or key column.
+  - Only the first page is counted.
+- **Writes and pending patches.** Pages live under
+  `[resource, "infinite", params]`, so writes (which invalidate `[resource]`)
+  refetch them. Optimistic and undoable patches are applied to every loaded
+  page and survive refetches, like lists.
+- **A row shows once.** A row that moved into a later page while the user
+  scrolled (its sort value changed, or rows were added before it) is shown
+  where it first appeared, not twice.
+
+## Live updates (realtime)
+
+`useResource(resource, { live: true })`, `useOne(resource, id, { live: true })`
+and genesis-ui's `<ResourcePage live />` keep what is on screen current while
+they are mounted. They subscribe through the provider's optional
+`subscribe(resource, params, callback)` and, when it reports a change,
+refetch the resource's cached reads (`useResource`: every `[resource, …]`
+query; `useOne`: that record, and only for its own id).
+
+- **Events are hints, never data.** The callback gets `{ type: "created" |
+  "updated" | "deleted", id? }`, or `{ type: "changed" }` when changes may have
+  been missed (after a reconnect). Nothing from an event is written to the
+  cache: rows always come from the provider's normal read, under its RLS.
+- **One refetch per burst.** Events within `debounceMs` (default 250) of each
+  other cause one refetch: `live: { debounceMs: 1000 }`. A steady stream
+  still refetches at least every `4 × debounceMs`.
+- **Pending writes stay applied.** A refetch while an optimistic or undoable
+  write is pending gets that write's patch re-applied (see
+  [Mutation modes](#mutation-modes)), so a row deleted with Undo stays hidden
+  and an edit stays shown. Your own committed writes come back as events too;
+  the extra refetch is harmless and is not filtered out.
+- **A hidden tab waits.** While the page is hidden, reads are only marked
+  stale; they refetch when it is shown again (with TanStack Query's default
+  `refetchOnWindowFocus`) or when next used.
+- **Without `subscribe`**, or for a resource the provider doesn't watch,
+  `live` does nothing. `capabilities(resource).realtime` says whether it
+  will work.
+
+### Supabase setup
+
+```ts
+const provider = createSupabaseProvider(supabase, {
+  resources: { tasks: { realtime: true } }, // or realtime: true | ["tasks"] for several
+});
+```
+
+```sql
+-- 1. Publish the table's changes to Realtime.
+alter publication supabase_realtime add table public.tasks;
+-- 2. Keep RLS on: Realtime only sends an insert or update to a subscriber
+--    whose SELECT policies allow the new row.
+alter table public.tasks enable row level security;
+```
+
+- The provider opens one `postgres_changes` channel per subscription and
+  removes it on unsubscribe. `useOne`'s channel is not filtered on the
+  server (Realtime never delivers deletes through a filter); its id is
+  matched on arrival. A
+  resource named `schema.table` listens in that schema; otherwise `public`.
+- **What leaks, and what doesn't.** Insert and update events are checked
+  against RLS by Realtime. **Delete events are not:** every subscriber to the
+  table receives the deleted row's primary key (with RLS on, Supabase sends
+  only the key, even under `REPLICA IDENTITY FULL`). The provider passes on only the id, and the hooks only refetch,
+  so a user never sees a row their read doesn't return. Don't enable
+  realtime on a table whose ids are themselves sensitive.
+- **Cost.** Each mounted live list or record is one Realtime channel, and
+  each change refetches every live list of that table for every subscriber
+  (debounced per client). Realtime checks RLS once per subscriber per
+  change, so busy tables with many viewers multiply database load. Enable it
+  where people watch shared data change, not on every table.
+- `capabilities(resource).realtime` is true only for resources with realtime
+  on and a client with `channel()` (any `@supabase/supabase-js` client).
+
 ## Unsaved changes
 
 `useResourceForm({ warnWhenUnsaved: true })` (default off) warns while the

package/dist/chunk-ADD2RIGA.js

@@ -0,0 +1,108 @@
+import { useLiveInvalidation } from './chunk-KXVHDK3Q.js';
+import { useDataProvider } from './chunk-GGSXSI6Z.js';
+import { useState, useCallback, useMemo } from 'react';
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+function filterKey(filters) {
+  return JSON.stringify(
+    (filters ?? []).map(
+      (f) => Object.fromEntries(Object.entries(f).sort(([a], [b]) => a.localeCompare(b)))
+    )
+  );
+}
+function useInfiniteResource(resource, options = {}) {
+  const {
+    defaultSort,
+    defaultFilters,
+    perPage = 25,
+    defaultSearch = "",
+    select,
+    searchFields,
+    enabled = true,
+    live
+  } = options;
+  const provider = useDataProvider();
+  const [sort, setSort] = useState(defaultSort);
+  const [filters, setFiltersRaw] = useState(defaultFilters ?? []);
+  const [search, setSearch] = useState(defaultSearch);
+  const defaultKey = filterKey(defaultFilters);
+  const [syncedKey, setSyncedKey] = useState(defaultKey);
+  if (defaultKey !== syncedKey) {
+    setSyncedKey(defaultKey);
+    setFiltersRaw(defaultFilters ?? []);
+  }
+  const setFilters = useCallback((next) => setFiltersRaw(next), []);
+  const params = useMemo(() => {
+    const p = {
+      perPage,
+      sort,
+      filters: filters.length > 0 ? filters : void 0,
+      select
+    };
+    if (search && searchFields && searchFields.length > 0) {
+      p.search = { query: search, fields: searchFields };
+    }
+    return p;
+  }, [perPage, sort, filters, select, search, searchFields]);
+  const query = useInfiniteQuery({
+    queryKey: [resource, "infinite", params],
+    initialPageParam: { page: 1, cursor: null },
+    queryFn: ({ pageParam }) => {
+      const { perPage: size, ...rest } = params;
+      return provider.getList(resource, {
+        ...rest,
+        pagination: { page: pageParam.page, perPage: size, cursor: pageParam.cursor }
+      });
+    },
+    getNextPageParam: (last, pages, lastParam) => {
+      if (last.nextCursor !== void 0) {
+        return last.nextCursor ? { page: lastParam.page + 1, cursor: last.nextCursor } : void 0;
+      }
+      const loaded = pages.reduce((n, p) => n + p.data.length, 0);
+      const total2 = pages[0]?.total ?? 0;
+      if (last.data.length < params.perPage || loaded >= total2) return void 0;
+      return { page: lastParam.page + 1, cursor: null };
+    },
+    enabled
+  });
+  useLiveInvalidation(resource, live, enabled, { filters: params.filters }, [resource]);
+  const rows = useMemo(() => {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const page of query.data?.pages ?? []) {
+      for (const row of page.data) {
+        const id = row?.id;
+        if (id != null) {
+          const key = String(id);
+          if (seen.has(key)) continue;
+          seen.add(key);
+        }
+        out.push(row);
+      }
+    }
+    return out;
+  }, [query.data]);
+  const firstTotal = query.data?.pages[0]?.total;
+  const total = firstTotal === void 0 || firstTotal < 0 ? void 0 : firstTotal;
+  const { fetchNextPage: fetchNext, hasNextPage, isFetchingNextPage } = query;
+  const fetchNextPage = useCallback(() => {
+    if (!hasNextPage || isFetchingNextPage) return;
+    void fetchNext();
+  }, [fetchNext, hasNextPage, isFetchingNextPage]);
+  return {
+    query,
+    rows,
+    total,
+    fetchNextPage,
+    hasNextPage: !!hasNextPage,
+    isFetchingNextPage,
+    params,
+    setSort,
+    setFilters,
+    setSearch
+  };
+}
+
+export { useInfiniteResource };
+//# sourceMappingURL=chunk-ADD2RIGA.js.map
+//# sourceMappingURL=chunk-ADD2RIGA.js.map

package/dist/chunk-ADD2RIGA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-infinite-resource.ts"],"names":["total"],"mappings":"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","file":"chunk-ADD2RIGA.js","sourcesContent":["import { useCallback, useMemo, useState } from \"react\";\nimport {\n  useInfiniteQuery,\n  type InfiniteData,\n  type UseInfiniteQueryResult,\n} from \"@tanstack/react-query\";\nimport { useDataProvider } from \"../provider/context\";\nimport type {\n  BaseRecord,\n  FilterParam,\n  ListParams,\n  ListResult,\n  SortParam,\n} from \"../provider/types\";\nimport { useLiveInvalidation, type LiveOptions } from \"./use-live\";\n\n// ---------------------------------------------------------------------------\n// useInfiniteResource — a list that grows with \"Load more\", by cursor.\n//\n// Asks for the first page with `cursor: null`. A provider that serves cursor\n// paging answers with `nextCursor` and is paged by keyset from then on; one\n// that doesn't answers without it and is paged by `page` (offset) until\n// `total` rows are loaded. Pages live under `[resource, \"infinite\", params]`,\n// so writes on the resource (which invalidate `[resource]`) refetch them,\n// and pending optimistic and undoable writes are patched into every page.\n// ---------------------------------------------------------------------------\n\nexport interface UseInfiniteResourceOptions {\n  defaultSort?: SortParam;\n  /** Re-synced when its value changes, like `useResource`'s. */\n  defaultFilters?: FilterParam[];\n  /** Rows per page. Default 25. */\n  perPage?: number;\n  /** The search to start with. Default \"\". */\n  defaultSearch?: string;\n  /** Supabase select/join syntax. Must include the sort and key columns. */\n  select?: string;\n  /** Fields to search across when `setSearch` is called. */\n  searchFields?: string[];\n  /** Disable fetching. */\n  enabled?: boolean;\n  /** Refetch the loaded pages when the provider reports a change. See `UseResourceOptions.live`. */\n  live?: boolean | LiveOptions;\n}\n\n/** Where one page starts: its offset page, and its cursor (`null` for the first). */\nexport interface InfinitePageParam {\n  page: number;\n  cursor: string | null;\n}\n\nexport interface UseInfiniteResourceReturn<T> {\n  /** The TanStack infinite query. */\n  query: UseInfiniteQueryResult<InfiniteData<ListResult<T>, InfinitePageParam>>;\n  /** Every loaded row, in order. */\n  rows: T[];\n  /** Rows matching the filters and search, from the first page's count. */\n  total: number | undefined;\n  /** Loads the next page. Does nothing while one is loading or none is left. */\n  fetchNextPage: () => void;\n  hasNextPage: boolean;\n  isFetchingNextPage: boolean;\n  /** The params every page is asked with (without its page and cursor). */\n  params: Omit<ListParams, \"pagination\"> & { perPage: number };\n  setSort: (sort: SortParam | undefined) => void;\n  setFilters: (filters: FilterParam[]) => void;\n  setSearch: (query: string) => void;\n}\n\nfunction filterKey(filters: FilterParam[] | undefined): string {\n  return JSON.stringify(\n    (filters ?? []).map((f) =>\n      Object.fromEntries(Object.entries(f).sort(([a], [b]) => a.localeCompare(b))),\n    ),\n  );\n}\n\nexport function useInfiniteResource<T extends BaseRecord = BaseRecord>(\n  resource: string,\n  options: UseInfiniteResourceOptions = {},\n): UseInfiniteResourceReturn<T> {\n  const {\n    defaultSort,\n    defaultFilters,\n    perPage = 25,\n    defaultSearch = \"\",\n    select,\n    searchFields,\n    enabled = true,\n    live,\n  } = options;\n  const provider = useDataProvider();\n\n  const [sort, setSort] = useState<SortParam | undefined>(defaultSort);\n  const [filters, setFiltersRaw] = useState<FilterParam[]>(defaultFilters ?? []);\n  const [search, setSearch] = useState(defaultSearch);\n\n  // Follow `defaultFilters` by value, during render (see useResource).\n  const defaultKey = filterKey(defaultFilters);\n  const [syncedKey, setSyncedKey] = useState(defaultKey);\n  if (defaultKey !== syncedKey) {\n    setSyncedKey(defaultKey);\n    setFiltersRaw(defaultFilters ?? []);\n  }\n\n  const setFilters = useCallback((next: FilterParam[]) => setFiltersRaw(next), []);\n\n  const params = useMemo(() => {\n    const p: Omit<ListParams, \"pagination\"> & { perPage: number } = {\n      perPage,\n      sort,\n      filters: filters.length > 0 ? filters : undefined,\n      select,\n    };\n    if (search && searchFields && searchFields.length > 0) {\n      p.search = { query: search, fields: searchFields };\n    }\n    return p;\n  }, [perPage, sort, filters, select, search, searchFields]);\n\n  const query = useInfiniteQuery<\n    ListResult<T>,\n    Error,\n    InfiniteData<ListResult<T>, InfinitePageParam>,\n    readonly unknown[],\n    InfinitePageParam\n  >({\n    queryKey: [resource, \"infinite\", params],\n    initialPageParam: { page: 1, cursor: null },\n    queryFn: ({ pageParam }) => {\n      const { perPage: size, ...rest } = params;\n      return provider.getList<T>(resource, {\n        ...rest,\n        pagination: { page: pageParam.page, perPage: size, cursor: pageParam.cursor },\n      });\n    },\n    getNextPageParam: (last, pages, lastParam) => {\n      if (last.nextCursor !== undefined) {\n        // Cursor mode: the provider says whether there is more.\n        return last.nextCursor ? { page: lastParam.page + 1, cursor: last.nextCursor } : undefined;\n      }\n      // Offset mode: more while fewer than `total` rows are loaded and the\n      // last page was full.\n      const loaded = pages.reduce((n, p) => n + p.data.length, 0);\n      const total = pages[0]?.total ?? 0;\n      if (last.data.length < params.perPage || loaded >= total) return undefined;\n      return { page: lastParam.page + 1, cursor: null };\n    },\n    enabled,\n  });\n\n  useLiveInvalidation(resource, live, enabled, { filters: params.filters }, [resource]);\n\n  // A row can move between pages while the user scrolls (its sort value\n  // changed, or rows before it were added): show it once, where it first appears.\n  const rows = useMemo(() => {\n    const seen = new Set<string>();\n    const out: T[] = [];\n    for (const page of query.data?.pages ?? []) {\n      for (const row of page.data) {\n        const id = row?.id;\n        if (id != null) {\n          const key = String(id);\n          if (seen.has(key)) continue;\n          seen.add(key);\n        }\n        out.push(row);\n      }\n    }\n    return out;\n  }, [query.data]);\n  const firstTotal = query.data?.pages[0]?.total;\n  const total = firstTotal === undefined || firstTotal < 0 ? undefined : firstTotal;\n\n  const { fetchNextPage: fetchNext, hasNextPage, isFetchingNextPage } = query;\n  const fetchNextPage = useCallback(() => {\n    if (!hasNextPage || isFetchingNextPage) return;\n    void fetchNext();\n  }, [fetchNext, hasNextPage, isFetchingNextPage]);\n\n  return {\n    query,\n    rows,\n    total,\n    fetchNextPage,\n    hasNextPage: !!hasNextPage,\n    isFetchingNextPage,\n    params,\n    setSort,\n    setFilters,\n    setSearch,\n  };\n}\n"]}

package/dist/chunk-KXVHDK3Q.js

@@ -0,0 +1,71 @@
+import { useDataProvider } from './chunk-GGSXSI6Z.js';
+import { useRef, useEffect } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+
+var DEFAULT_LIVE_DEBOUNCE_MS = 250;
+var warnedNoSubscribe = /* @__PURE__ */ new WeakSet();
+function useLiveInvalidation(resource, live, enabled, params, queryKey, accept) {
+  const provider = useDataProvider();
+  const queryClient = useQueryClient();
+  const on = !!live && enabled;
+  const debounceMs = Math.max(
+    0,
+    (typeof live === "object" ? live.debounceMs : void 0) ?? DEFAULT_LIVE_DEBOUNCE_MS
+  );
+  const paramsKey = JSON.stringify(params);
+  const keyKey = JSON.stringify(queryKey);
+  const latest = useRef({ queryKey, accept, params });
+  latest.current = { queryKey, accept, params };
+  useEffect(() => {
+    if (!on) return;
+    if (typeof provider.subscribe !== "function") {
+      if (process.env.NODE_ENV !== "production" && !warnedNoSubscribe.has(provider)) {
+        warnedNoSubscribe.add(provider);
+        console.warn(
+          `[genesis] "${resource}" asked for live updates, but the data provider has no subscribe(); the list will only refresh on its own reads.`
+        );
+      }
+      return;
+    }
+    let timer;
+    let burstStart = 0;
+    let active = true;
+    const maxWaitMs = debounceMs * 4;
+    const fire = () => {
+      timer = void 0;
+      if (!active) return;
+      const hidden = typeof document !== "undefined" && document.visibilityState === "hidden";
+      void queryClient.invalidateQueries({
+        queryKey: [...latest.current.queryKey],
+        refetchType: hidden ? "none" : "active"
+      });
+    };
+    let unsubscribe;
+    try {
+      unsubscribe = provider.subscribe(resource, latest.current.params, (event) => {
+        if (!active) return;
+        const test = latest.current.accept;
+        if (test && event.type !== "changed" && !test(event)) return;
+        const now = Date.now();
+        if (timer === void 0) burstStart = now;
+        else clearTimeout(timer);
+        timer = setTimeout(fire, Math.min(debounceMs, Math.max(0, burstStart + maxWaitMs - now)));
+      });
+    } catch (error) {
+      console.error(`[genesis] subscribing to "${resource}" failed:`, error);
+    }
+    return () => {
+      active = false;
+      if (timer !== void 0) clearTimeout(timer);
+      try {
+        unsubscribe?.();
+      } catch (error) {
+        console.error(`[genesis] unsubscribing from "${resource}" failed:`, error);
+      }
+    };
+  }, [on, provider, queryClient, resource, debounceMs, paramsKey, keyKey]);
+}
+
+export { DEFAULT_LIVE_DEBOUNCE_MS, useLiveInvalidation };
+//# sourceMappingURL=chunk-KXVHDK3Q.js.map
+//# sourceMappingURL=chunk-KXVHDK3Q.js.map

package/dist/chunk-KXVHDK3Q.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-live.ts"],"names":[],"mappings":"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","file":"chunk-KXVHDK3Q.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Live reads — refetch a resource's cached reads when the provider reports a\n// change (`DataProvider.subscribe`).\n//\n// Events are invalidation hints only. Nothing from an event's payload is\n// written to the cache: the refetch goes through the provider's normal read,\n// so what a user sees is always what that read (and its RLS) returns.\n//\n// Pending optimistic and undoable writes are safe: their patches are\n// re-applied to whatever a refetch brings (see mutation-mode.ts), so a row\n// deleted with undo stays hidden and an edit stays shown until the write\n// settles. A change caused by this client's own write arrives as an event\n// too; the refetch it causes is idempotent, so it is not filtered out.\n// ---------------------------------------------------------------------------\n\nimport { useEffect, useRef } from \"react\";\nimport { useQueryClient, type QueryKey } from \"@tanstack/react-query\";\nimport { useDataProvider } from \"../provider/context\";\nimport type { ResourceChangeEvent, SubscribeParams } from \"../provider/types\";\n\n/** How long a burst of change events is gathered into one refetch. */\nexport const DEFAULT_LIVE_DEBOUNCE_MS = 250;\n\n/** `live` as an object, to tune it. `live: true` takes the defaults. */\nexport interface LiveOptions {\n  /**\n   * Events arriving within this many milliseconds of each other cause one\n   * refetch, not one each. Default {@link DEFAULT_LIVE_DEBOUNCE_MS}. A\n   * steady stream still refetches at least every `4 × debounceMs`.\n   */\n  debounceMs?: number;\n}\n\nconst warnedNoSubscribe = new WeakSet<object>();\n\n/**\n * Subscribes while mounted and `enabled`, and invalidates `queryKey` (a\n * prefix) once per burst of events that `accept` lets through. While the\n * page is hidden the queries are only marked stale; they refetch when it is\n * shown again (TanStack Query's `refetchOnWindowFocus`) or next used.\n *\n * @internal Used by `useResource` and `useOne`'s `live` option.\n */\nexport function useLiveInvalidation(\n  resource: string,\n  live: boolean | LiveOptions | undefined,\n  enabled: boolean,\n  params: SubscribeParams,\n  queryKey: QueryKey,\n  accept?: (event: ResourceChangeEvent) => boolean,\n): void {\n  const provider = useDataProvider();\n  const queryClient = useQueryClient();\n  const on = !!live && enabled;\n  const debounceMs = Math.max(\n    0,\n    (typeof live === \"object\" ? live.debounceMs : undefined) ?? DEFAULT_LIVE_DEBOUNCE_MS,\n  );\n  const paramsKey = JSON.stringify(params);\n  const keyKey = JSON.stringify(queryKey);\n\n  // The latest values, read when an event arrives, so a new array or\n  // callback each render doesn't resubscribe.\n  const latest = useRef({ queryKey, accept, params });\n  latest.current = { queryKey, accept, params };\n\n  useEffect(() => {\n    if (!on) return;\n    if (typeof provider.subscribe !== \"function\") {\n      if (process.env.NODE_ENV !== \"production\" && !warnedNoSubscribe.has(provider)) {\n        warnedNoSubscribe.add(provider);\n        console.warn(\n          `[genesis] \"${resource}\" asked for live updates, but the data provider has no subscribe(); the list will only refresh on its own reads.`,\n        );\n      }\n      return;\n    }\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let burstStart = 0;\n    let active = true;\n    // A busy table must not postpone the refetch forever.\n    const maxWaitMs = debounceMs * 4;\n    const fire = () => {\n      timer = undefined;\n      if (!active) return;\n      const hidden = typeof document !== \"undefined\" && document.visibilityState === \"hidden\";\n      void queryClient.invalidateQueries({\n        queryKey: [...latest.current.queryKey],\n        refetchType: hidden ? \"none\" : \"active\",\n      });\n    };\n    let unsubscribe: (() => void) | undefined;\n    try {\n      unsubscribe = provider.subscribe(resource, latest.current.params, (event) => {\n        if (!active) return;\n        const test = latest.current.accept;\n        if (test && event.type !== \"changed\" && !test(event)) return;\n        // Coalesce: one refetch per burst, after it goes quiet (or has\n        // lasted `maxWaitMs`).\n        const now = Date.now();\n        if (timer === undefined) burstStart = now;\n        else clearTimeout(timer);\n        timer = setTimeout(fire, Math.min(debounceMs, Math.max(0, burstStart + maxWaitMs - now)));\n      });\n    } catch (error) {\n      console.error(`[genesis] subscribing to \"${resource}\" failed:`, error);\n    }\n    return () => {\n      active = false;\n      if (timer !== undefined) clearTimeout(timer);\n      try {\n        unsubscribe?.();\n      } catch (error) {\n        console.error(`[genesis] unsubscribing from \"${resource}\" failed:`, error);\n      }\n    };\n    // `paramsKey` / `keyKey` stand for `params` / `queryKey` by value.\n  }, [on, provider, queryClient, resource, debounceMs, paramsKey, keyKey]);\n}\n"]}

package/dist/{chunk-F3BE7NGM.js → chunk-OBUBP4BY.js}

@@ -8,6 +8,36 @@ function sameId(a, b) {
 function isListResult(value) {
   return typeof value === "object" && value !== null && Array.isArray(value.data);
 }
+function isInfiniteLists(value) {
+  return typeof value === "object" && value !== null && Array.isArray(value.pages) && Array.isArray(value.pageParams);
+}
+function mapLists(key, hash, value, fn) {
+  if (key[1] === "list") return isListResult(value) ? fn(value, hash) : value;
+  if (key[1] !== "infinite" || !isInfiniteLists(value)) return value;
+  let changed = false;
+  let rowDelta = 0;
+  const pages = value.pages.map((page, i) => {
+    if (!isListResult(page)) return page;
+    const next = fn(page, `${hash}#${i}`);
+    if (next !== page) {
+      changed = true;
+      rowDelta += next.data.length - page.data.length;
+    }
+    return next;
+  });
+  if (!changed) return value;
+  const withTotals = value.pages.map((orig, i) => {
+    const page = pages[i];
+    if (!isListResult(page) || !isListResult(orig) || typeof orig.total !== "number") return page;
+    return { ...page, total: orig.total < 0 ? orig.total : Math.max(0, orig.total + rowDelta) };
+  });
+  return { ...value, pages: withTotals };
+}
+function listsIn(key, value) {
+  if (key[1] === "list") return isListResult(value) ? [value] : [];
+  if (key[1] === "infinite" && isInfiniteLists(value)) return value.pages.filter(isListResult);
+  return [];
+}
 function isDetailKeyFor(key, resource, id) {
   return key[0] === resource && key[1] === "detail" && sameId(key[2], id);
 }
@@ -34,10 +64,11 @@ function cachedRecord(queryClient, resource, id) {
   for (const [key, value] of queryClient.getQueriesData({ queryKey: [resource, "detail"] })) {
     if (isDetailKeyFor(key, resource, id) && value && typeof value === "object") return value;
   }
-  for (const [, value] of queryClient.getQueriesData({ queryKey: [resource, "list"] })) {
-    if (!isListResult(value)) continue;
-    const found = value.data.find((row) => sameId(row.id, id));
-    if (found) return found;
+  for (const [key, value] of queryClient.getQueriesData({ queryKey: [resource] })) {
+    for (const list of listsIn(key, value)) {
+      const found = list.data.find((row) => sameId(row.id, id));
+      if (found) return found;
+    }
   }
   return void 0;
 }
@@ -96,25 +127,27 @@ function revertFields(row, data, before) {
   return out;
 }
 function applyPatches(key, hash, value, patches) {
-  if (key[1] === "list" && isListResult(value)) {
-    let rows = value.data;
-    let total = value.total;
-    let changed = false;
-    for (const p of patches) {
-      const index = rows.findIndex((row) => sameId(row.id, p.id));
-      if (index < 0) continue;
-      p.before.set(hash, { row: rows[index], index });
-      if (p.kind === "update") {
-        rows = rows.slice();
-        rows[index] = applyUpdate(rows[index], p.data ?? {});
-      } else {
-        rows = rows.filter((_, i) => i !== index);
-        if (typeof total === "number") total = Math.max(0, total - 1);
+  if (key[1] === "list" || key[1] === "infinite") {
+    return mapLists(key, hash, value, (list, listHash) => {
+      let rows = list.data;
+      let total = list.total;
+      let changed = false;
+      for (const p of patches) {
+        const index = rows.findIndex((row) => sameId(row.id, p.id));
+        if (index < 0) continue;
+        p.before.set(listHash, { row: rows[index], index });
+        if (p.kind === "update") {
+          rows = rows.slice();
+          rows[index] = applyUpdate(rows[index], p.data ?? {});
+        } else {
+          rows = rows.filter((_, i) => i !== index);
+          if (typeof total === "number" && total >= 0) total = Math.max(0, total - 1);
+        }
+        changed = true;
       }
-      changed = true;
-    }
-    if (!changed) return value;
-    return typeof total === "number" ? { ...value, data: rows, total } : { ...value, data: rows };
+      if (!changed) return list;
+      return typeof total === "number" ? { ...list, data: rows, total } : { ...list, data: rows };
+    });
   }
   if (key[1] === "detail" && value && typeof value === "object") {
     let row = value;
@@ -183,28 +216,29 @@ function retractPatch(reg, queryClient, patch) {
   for (const query of queryClient.getQueryCache().findAll({ queryKey: [patch.resource] })) {
     const key = query.queryKey;
     const value = query.state.data;
-    const b = patch.before.get(query.queryHash);
     let next = value;
-    if (key[1] === "list" && isListResult(value)) {
-      const at = value.data.findIndex((row) => sameId(row.id, patch.id));
-      if (patch.kind === "update") {
-        const src = b ?? firstBefore(patch);
-        if (at < 0 || !src || !patch.data) continue;
-        const rows = value.data.slice();
-        rows[at] = reapply(revertFields(rows[at], patch.data, src.row));
-        next = { ...value, data: rows };
-      } else {
-        if (at >= 0 || !b || remaining.some((p) => p.kind === "delete")) continue;
-        const rows = value.data.slice();
+    if (key[1] === "list" || key[1] === "infinite") {
+      next = mapLists(key, query.queryHash, value, (list, listHash) => {
+        const b = patch.before.get(listHash);
+        const at = list.data.findIndex((row) => sameId(row.id, patch.id));
+        if (patch.kind === "update") {
+          const src = b ?? firstBefore(patch);
+          if (at < 0 || !src || !patch.data) return list;
+          const rows2 = list.data.slice();
+          rows2[at] = reapply(revertFields(rows2[at], patch.data, src.row));
+          return { ...list, data: rows2 };
+        }
+        if (at >= 0 || !b || remaining.some((p) => p.kind === "delete")) return list;
+        const rows = list.data.slice();
         rows.splice(Math.min(b.index, rows.length), 0, reapply(b.row));
-        next = {
-          ...value,
+        return {
+          ...list,
           data: rows,
-          ...typeof value.total === "number" ? { total: value.total + 1 } : {}
+          ...typeof list.total === "number" && list.total >= 0 ? { total: list.total + 1 } : {}
         };
-      }
+      });
     } else if (key[1] === "detail" && patch.kind === "update" && patch.data && sameId(key[2], patch.id) && value && typeof value === "object") {
-      const src = b ?? firstBefore(patch);
+      const src = patch.before.get(query.queryHash) ?? firstBefore(patch);
       if (!src) continue;
       next = reapply(revertFields(value, patch.data, src.row));
     }
@@ -266,12 +300,14 @@ function refreshFields(reg, queryClient, patch, keys) {
     const key = query.queryKey;
     const value = query.state.data;
     let next = value;
-    if (key[1] === "list" && isListResult(value)) {
-      const at = value.data.findIndex((row) => sameId(row.id, patch.id));
-      if (at < 0) continue;
-      const rows = value.data.slice();
-      rows[at] = fix(rows[at], query.queryHash);
-      next = { ...value, data: rows };
+    if (key[1] === "list" || key[1] === "infinite") {
+      next = mapLists(key, query.queryHash, value, (list, listHash) => {
+        const at = list.data.findIndex((row) => sameId(row.id, patch.id));
+        if (at < 0) return list;
+        const rows = list.data.slice();
+        rows[at] = fix(rows[at], listHash);
+        return { ...list, data: rows };
+      });
     } else if (key[1] === "detail" && sameId(key[2], patch.id) && value && typeof value === "object") {
       next = fix(value, query.queryHash);
     }
@@ -516,5 +552,5 @@ async function executeWrite(args) {
 }
 
 export { DEFAULT_UNDO_DELAY_MS, DROPPED_WRITE_MESSAGE, cachedRecord, executeWrite, invalidateResource, pendingWriteCount, providerServesUndo, sameValue };
-//# sourceMappingURL=chunk-F3BE7NGM.js.map
-//# sourceMappingURL=chunk-F3BE7NGM.js.map
+//# sourceMappingURL=chunk-OBUBP4BY.js.map
+//# sourceMappingURL=chunk-OBUBP4BY.js.map