@ic-reactor/react 3.12.4 → 3.13.0

package/src/utils.ts

@@ -1,10 +1,94 @@
 /**
- * Shared internal utilities for query and mutation factories.
+ * Shared internal utilities for the query and mutation hooks and factories.
  */
 
-import type { QueryKey } from "@tanstack/react-query"
-import type { ReactorQueryData } from "@ic-reactor/core"
+import { useEffect } from "react"
+import type { QueryClient, QueryKey } from "@tanstack/react-query"
+import type { CallConfig } from "@icp-sdk/core/agent"
+import type {
+  ClientManager,
+  FunctionName,
+  Reactor,
+  ReactorArgs,
+  ReactorQueryData,
+  TransformKey,
+} from "@ic-reactor/core"
 import { generateKey } from "@ic-reactor/core"
+import type {
+  InvalidationTarget,
+  OptimisticRollback,
+  QueryCacheControls,
+  QueryFactoryMethods,
+  QueryKeySource,
+} from "./types.js"
+
+/**
+ * Keep `queryClient` mounted while the calling component is.
+ *
+ * `QueryClient.mount()` is what subscribes a client to TanStack's focus and
+ * online managers. Those subscriptions refetch stale queries on window focus
+ * and on reconnect, resume a fetch that started offline or a retry that paused
+ * while the tab was hidden, and resume mutations sent offline.
+ * `QueryClientProvider` normally calls it, but every hook here binds to its
+ * reactor's own client rather than the context one, and the setup guide calls
+ * the provider optional. Without one, nothing mounted the client: a query that
+ * started offline stayed `paused` after the connection came back, a mutation
+ * sent offline stayed pending, and `refetchOnWindowFocus` and
+ * `refetchOnReconnect` never fired.
+ *
+ * `mount()` and `unmount()` are reference-counted, so this composes with a
+ * provider mounting the same client and with any number of hooks. It runs in
+ * an effect, like the provider's, so a server render never subscribes.
+ *
+ * A reactor stand-in without a `queryClient` (a test double, say) makes the
+ * TanStack hooks fall back to the context client, which its provider mounts,
+ * so there is nothing to do for one.
+ */
+export function useMountQueryClient(
+  queryClient: QueryClient | undefined
+): void {
+  useEffect(() => {
+    if (!queryClient) return
+    queryClient.mount()
+    return () => queryClient.unmount()
+  }, [queryClient])
+}
+
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  typeof (value as { then?: unknown } | null | undefined)?.then === "function"
+
+/**
+ * Keep `queryClient` mounted while a suspense hook waits on the promise it
+ * threw. Call it from a `catch` around the TanStack suspense hook, then
+ * rethrow. The `try` only lets the hook see the promise: it is rethrown
+ * untouched, so React discards the render as before and hook order is kept.
+ *
+ * A suspense hook throws its fetch promise before its component commits, so
+ * the effect in {@link useMountQueryClient} cannot run until that promise
+ * settles. A fetch that started offline, or whose retry is waiting for a hidden
+ * tab to come back, settles only once a mounted client hears the connection or
+ * the focus return. Without a provider nothing had mounted the client, so the
+ * Suspense fallback stayed up after reconnecting.
+ *
+ * The mount taken here is released when the promise settles, whether or not
+ * anything ever commits, so it stays balanced: each suspended render, a
+ * StrictMode double render or a retry included, takes and releases its own
+ * reference. Once the component commits, its effect holds the client like any
+ * other hook's. A tree discarded while suspended lets go once its fetch
+ * finishes, which it does on reconnect, as it would under a mounted provider.
+ * A server render never subscribes.
+ */
+export function mountWhileSuspended(
+  queryClient: QueryClient | undefined,
+  thrown: unknown
+): void {
+  if (!queryClient || typeof window === "undefined" || !isThenable(thrown)) {
+    return
+  }
+  queryClient.mount()
+  const release = () => queryClient.unmount()
+  void thrown.then(release, release)
+}
 
 /**
  * Internal query-key segment used to distinguish per-call factory args
@@ -12,10 +96,119 @@ import { generateKey } from "@ic-reactor/core"
  */
 export const FACTORY_KEY_ARGS_QUERY_KEY = "__ic_reactor_factory_key_args"
 
+/**
+ * Internal query-key segment that ends the key of a query waiting on
+ * `skipToken`. Not part of the public API.
+ */
+export const SKIPPED_QUERY_KEY = "__ic_reactor_skipped"
+
+/**
+ * The key of a query whose args are `skipToken`: `prefix`, the method's key
+ * that every key its args give extends, and then a segment no call's key has.
+ *
+ * It used to be the bare prefix, which is also the key of a query of the same
+ * method made without args, as a method with no parameters is called. The
+ * skipped query then showed that query's data though its own args were not
+ * known. And TanStack Query refetches an entry with the options of whichever
+ * of its observers rendered last, so an invalidation, including the sweep a
+ * sign-in or sign-out runs, could find `skipToken` in place of the query
+ * function: the refetch failed with "Missing queryFn" and the other query
+ * kept the previous caller's answer.
+ *
+ * `kind` keeps a waiting list apart from a waiting query of the same method,
+ * since TanStack Query does not share an entry between `useQuery` and
+ * `useInfiniteQuery`.
+ */
+export function skippedQueryKey(
+  prefix: QueryKey,
+  kind: "query" | "infinite"
+): QueryKey {
+  return [...prefix, { [SKIPPED_QUERY_KEY]: kind }]
+}
+
+/**
+ * The call config an infinite query's function fetches with: the caller's,
+ * aimed at the canister its query key names unless the caller named one.
+ *
+ * The key is built from the reactor's canister when the query is set up, but
+ * the query function reached `callMethod`, which reads `reactor.canisterId`
+ * again whenever it runs. After a `setCanisterId`, a retry or a refetch by an
+ * observer that had not re-rendered then fetched the new canister's pages and
+ * cached them under the old canister's key. `generateQueryKey` always roots a
+ * key at the canister it resolved, so the key says where its pages come from.
+ * `Reactor.getQueryOptions` pins its query function the same way.
+ */
+export function callConfigForKey(
+  queryKey: QueryKey,
+  callConfig: CallConfig | undefined
+): CallConfig | undefined {
+  const keyedCanister = queryKey[0]
+  if (callConfig?.canisterId || typeof keyedCanister !== "string") {
+    return callConfig
+  }
+  return { ...callConfig, canisterId: keyedCanister }
+}
+
 /** Convert a direct reactor result into a value TanStack Query can cache. */
 export const normalizeQueryData = <T>(value: T): ReactorQueryData<T> =>
   (value === undefined ? null : value) as ReactorQueryData<T>
 
+/** Config options that decide how a query's function runs. */
+const FETCH_OPTION_KEYS = [
+  "networkMode",
+  "retry",
+  "retryDelay",
+  "meta",
+] as const
+
+type FetchOptionKey = (typeof FETCH_OPTION_KEYS)[number]
+
+/**
+ * The part of a factory config that `fetch()` and `prefetch()` pass on.
+ *
+ * A factory's hook hands its whole config to TanStack Query, but the
+ * imperative path used to pass only the key and query function. So a config's
+ * `networkMode: "always"` let the hook fetch while `fetch()` stayed paused
+ * offline, its `retry` retried in the hook and not in a loader, and its `meta`
+ * never reached the QueryCache callbacks for a `fetch()` failure. These four
+ * say how the query function runs, so they now apply to both paths.
+ *
+ * Options that decide what the cache keeps (`gcTime`, `initialData`) or how an
+ * observer renders (`select`, `placeholderData`, `enabled`, …) stay with the
+ * hook. Unset options are left out rather than passed as `undefined`, which
+ * would override the QueryClient's own defaults.
+ */
+export function pickFetchOptions<Config extends object>(
+  config: Config
+): Partial<Pick<Config, Extract<keyof Config, FetchOptionKey>>> {
+  const picked: Partial<Record<FetchOptionKey, unknown>> = {}
+  for (const key of FETCH_OPTION_KEYS) {
+    const value = (config as Partial<Record<FetchOptionKey, unknown>>)[key]
+    if (value !== undefined) picked[key] = value
+  }
+  return picked as Partial<Pick<Config, Extract<keyof Config, FetchOptionKey>>>
+}
+
+/**
+ * The `retry` entry of a query's options: the query's own `retry` when it sets
+ * one, otherwise the reactor's default for its method, and no entry when
+ * neither is set, so the QueryClient's defaults apply.
+ *
+ * The default is `Reactor.getQueryRetry`'s: `undefined` for a query method,
+ * and for an update method a retry of only the failures that prove the
+ * canister never ran the call, since each attempt runs the update again.
+ * Spread this after the caller's options. An update method's default then also
+ * replaces a `retry: undefined` spread in from them, which would otherwise
+ * select TanStack Query's own three retries.
+ */
+export function retryOption<TRetry, TDefault>(
+  ownRetry: TRetry | undefined,
+  defaultRetry: TDefault | undefined
+): { retry?: TRetry | TDefault } {
+  const retry = ownRetry ?? defaultRetry
+  return retry === undefined ? {} : { retry }
+}
+
 /**
  * Merge a base query key, optional per-call query key, and optional key-args
  * into a single query key array.
@@ -119,3 +312,194 @@ export function createBoundedCache<V>(limit: number = FACTORY_CACHE_LIMIT) {
     },
   }
 }
+
+const isQueryKeySource = (value: object): value is QueryKeySource =>
+  typeof (value as Partial<QueryKeySource>).getQueryKey === "function"
+
+/**
+ * Invalidate one `invalidateQueries` entry; see {@link invalidateTargets}.
+ */
+function invalidateTarget<Service, Transform extends TransformKey>(
+  reactor: Reactor<Service, Transform>,
+  target: InvalidationTarget<Service, Transform> | null,
+  canisterId: CallConfig["canisterId"]
+): Promise<void> {
+  // React Query reads `{ queryKey: undefined }` as "match everything", so an
+  // absent entry would invalidate every query in the client, the app's
+  // unrelated non-canister ones included. `null` only comes from untyped code
+  // and would do the same.
+  if (target == null) return Promise.resolve()
+  if (Array.isArray(target)) {
+    return reactor.queryClient.invalidateQueries({ queryKey: target })
+  }
+  if (isQueryKeySource(target)) {
+    // A query object or factory invalidates on its own reactor's client, which
+    // is not this reactor's when each reactor has a QueryClient of its own.
+    return target.invalidate
+      ? target.invalidate()
+      : reactor.queryClient.invalidateQueries({
+          queryKey: target.getQueryKey(),
+        })
+  }
+  // A `{ functionName, args? }` descriptor. Its key is built now rather than
+  // when the mutation was set up, so it follows a `setCanisterId`.
+  const { functionName, args } = target as {
+    functionName: FunctionName<Service>
+    args?: ReactorArgs<Service, FunctionName<Service>, Transform>
+  }
+  // `args: []`, all that a method without parameters takes, names the same
+  // queries as no args. Keyed as given, it adds an args segment that a query
+  // made without args lacks, and would match none of those.
+  const hasArgs = (args as readonly unknown[] | undefined)?.length
+  return reactor.queryClient.invalidateQueries({
+    // At the canister the mutation was sent to, whose queries it changed.
+    // Only the canister is taken from its `callConfig`: an agent or effective
+    // target segment would narrow the prefix to the queries sent the same
+    // way, while the canister's state changed for every caller.
+    queryKey: reactor.generateQueryKey(
+      { functionName, args: hasArgs ? args : undefined },
+      canisterId ? { canisterId } : undefined
+    ),
+  })
+}
+
+/**
+ * Invalidate every entry of a mutation's `invalidateQueries` in parallel, on
+ * behalf of `reactor`, the mutation's own. It resolves once every active
+ * query they matched has refetched; a refetch that fails does not reject it,
+ * so it cannot turn an update that already ran into a failure.
+ *
+ * An entry is a query key, a query object or query factory (anything with a
+ * `getQueryKey()`), or a `{ functionName, args? }` descriptor, which is keyed
+ * by `reactor.generateQueryKey` at the canister the mutation was sent to:
+ * the one its `callConfig.canisterId` names, else the reactor's. `undefined`
+ * entries are skipped.
+ */
+export async function invalidateTargets<
+  Service,
+  Transform extends TransformKey,
+>(
+  reactor: Reactor<Service, Transform>,
+  targets: readonly InvalidationTarget<Service, Transform>[] | undefined,
+  callConfig?: CallConfig
+): Promise<void> {
+  if (!targets || targets.length === 0) return
+  await Promise.all(
+    targets.map((target) =>
+      invalidateTarget(reactor, target, callConfig?.canisterId)
+    )
+  )
+}
+
+/**
+ * Give an args-late query factory function its {@link QueryFactoryMethods}.
+ *
+ * `getQueryKey` builds the prefix every query of the factory shares, and is
+ * called each time so that it follows a `setCanisterId`.
+ */
+export function withQueryFactoryMethods<Factory extends object>(
+  factory: Factory,
+  reactor: { readonly queryClient: QueryClient },
+  getQueryKey: () => QueryKey
+): Factory & QueryFactoryMethods {
+  const methods: QueryFactoryMethods = {
+    getQueryKey,
+    invalidate: () =>
+      reactor.queryClient.invalidateQueries({ queryKey: getQueryKey() }),
+  }
+  return Object.assign(factory, methods)
+}
+
+/** The rollback of an optimistic update that wrote nothing. */
+const NOTHING_TO_ROLL_BACK: OptimisticRollback = { rollback: () => {} }
+
+/** What {@link queryCacheControls} reads from a reactor. */
+interface CacheOwner {
+  readonly queryClient: QueryClient
+  readonly clientManager: Pick<ClientManager, "identity">
+}
+
+/**
+ * The principal whose answers the reactor's cache holds: the one installed on
+ * the manager's agent, `undefined` before one is.
+ *
+ * Query keys carry no principal. `ClientManager.updateAgent` sweeps the cache
+ * instead when another principal signs in, removing inactive entries and
+ * refetching active ones, so a value read from the cache is this principal's
+ * only while it stays installed.
+ */
+const cachedPrincipal = (reactor: CacheOwner): string | undefined =>
+  reactor.clientManager.identity?.getPrincipal().toText()
+
+/**
+ * The {@link QueryCacheControls} of a query object: `cancel`, `reset` and
+ * `optimisticUpdate` on its own entry of the reactor's QueryClient.
+ *
+ * They match the key exactly. A query object's key is also the prefix of
+ * other entries (a query without args prefixes every args instance of its
+ * method), and cancelling or resetting those would reach queries this object
+ * does not own. `getQueryKey` is called each time, so the controls follow a
+ * `setCanisterId`.
+ */
+export function queryCacheControls<TQueryFnData>(
+  reactor: CacheOwner,
+  getQueryKey: () => QueryKey
+): QueryCacheControls<TQueryFnData> {
+  return {
+    cancel: () =>
+      reactor.queryClient.cancelQueries({
+        queryKey: getQueryKey(),
+        exact: true,
+      }),
+
+    reset: () =>
+      reactor.queryClient.resetQueries({
+        queryKey: getQueryKey(),
+        exact: true,
+      }),
+
+    optimisticUpdate: async (updater) => {
+      const { queryClient } = reactor
+      const queryKey = getQueryKey()
+      // Nothing cached means nothing on screen to update. Cancelling the
+      // entry's first fetch would also leave it pending with no data.
+      if (queryClient.getQueryData(queryKey) === undefined) {
+        return NOTHING_TO_ROLL_BACK
+      }
+      const principal = cachedPrincipal(reactor)
+      // A fetch in flight would otherwise land after the write below with the
+      // canister's answer from before the mutation. Cancelling reverts the
+      // entry to what it held before that fetch, so it is read afterwards.
+      await queryClient.cancelQueries({ queryKey, exact: true })
+      // A sign-in or sign-out while that ran left the previous principal's
+      // value in the entry until the sweep's refetch lands. An update built
+      // on it would show that value to the principal signed in now.
+      if (cachedPrincipal(reactor) !== principal) return NOTHING_TO_ROLL_BACK
+      const snapshot = queryClient.getQueryState<TQueryFnData>(queryKey)
+      if (snapshot?.data === undefined) return NOTHING_TO_ROLL_BACK
+      const { data: previous, dataUpdatedAt, isInvalidated } = snapshot
+      queryClient.setQueryData<TQueryFnData>(queryKey, updater(previous))
+      return {
+        rollback: () => {
+          // After a switch to another principal, `previous` is the previous
+          // principal's value, which the sweep has removed or is refetching.
+          // Written back, it would be served to the one signed in now.
+          if (cachedPrincipal(reactor) !== principal) return
+          // With its own timestamp: written back as new, a value from before
+          // the mutation would look freshly fetched and skip the refetches
+          // its age calls for.
+          queryClient.setQueryData<TQueryFnData>(queryKey, previous, {
+            updatedAt: dataUpdatedAt,
+          })
+          // The write clears the invalidated mark too, and the fetch the
+          // update cancelled was often the refetch an invalidation started.
+          // Marked again, the value reads as outdated as it was, and a
+          // mounted query refetches it.
+          if (isInvalidated) {
+            void queryClient.invalidateQueries({ queryKey, exact: true })
+          }
+        },
+      }
+    },
+  }
+}

package/src/validation.ts

@@ -38,9 +38,20 @@ export interface MapValidationErrorsOptions {
   multiple?: boolean
 }
 
+/**
+ * The field an issue belongs to: the first segment of its path, as a string.
+ * An issue with an empty path is about the whole argument (a zod object-level
+ * `.refine()`, or any issue of a primitive argument) and belongs to `""`.
+ */
+function fieldNameOf(issue: ValidationIssue): string {
+  return String(issue.path[0] ?? "")
+}
+
 /**
  * Maps validation error issues to a simple field -> message object.
- * Returns the first error message for each field path.
+ * Returns the first error message for each field path, or every message with
+ * `{ multiple: true }`. Issues about the whole argument (an empty path) are
+ * filed under `""`.
  *
  * @example
  * ```tsx
@@ -60,44 +71,56 @@ export interface MapValidationErrorsOptions {
  * })
  * ```
  */
-export function mapValidationErrors(error: ValidationError): FieldErrors
+export function mapValidationErrors(
+  error: ValidationError,
+  options?: { multiple?: false }
+): FieldErrors
 export function mapValidationErrors(
   error: ValidationError,
   options: { multiple: true }
 ): FieldErrorsMultiple
 export function mapValidationErrors(
   error: ValidationError,
-  options: { multiple: false }
-): FieldErrors
+  options?: MapValidationErrorsOptions
+): FieldErrors | FieldErrorsMultiple
 export function mapValidationErrors(
   error: ValidationError,
   options?: MapValidationErrorsOptions
 ): FieldErrors | FieldErrorsMultiple {
+  // Collected in a Map, not a plain object: a field named like an
+  // Object.prototype member (`constructor`, `toString`, `__proto__`) read that
+  // member back as if the field were already filled, which dropped its issue,
+  // and threw on `.push` with `multiple`. `Object.fromEntries` then creates
+  // every field as an own property, `__proto__` included.
   if (options?.multiple) {
-    const result: FieldErrorsMultiple = {}
+    const messages = new Map<string, string[]>()
     for (const issue of error.issues) {
-      const fieldName = String(issue.path[0] ?? "")
-      if (!result[fieldName]) {
-        result[fieldName] = []
+      const fieldName = fieldNameOf(issue)
+      const fieldMessages = messages.get(fieldName)
+      if (fieldMessages) {
+        fieldMessages.push(issue.message)
+      } else {
+        messages.set(fieldName, [issue.message])
       }
-      result[fieldName].push(issue.message)
     }
-    return result
+    return Object.fromEntries(messages)
   }
 
-  const result: FieldErrors = {}
+  const messages = new Map<string, string>()
   for (const issue of error.issues) {
-    const fieldName = String(issue.path[0] ?? "")
-    if (!result[fieldName]) {
-      result[fieldName] = issue.message
+    const fieldName = fieldNameOf(issue)
+    if (!messages.get(fieldName)) {
+      messages.set(fieldName, issue.message)
     }
   }
-  return result
+  return Object.fromEntries(messages)
 }
 
 /**
  * Gets error message for a specific field from a ValidationError.
- * Returns undefined if no error exists for that field.
+ * Returns undefined if no error exists for that field. Pass `""` for issues
+ * about the whole argument (an empty path), the key `mapValidationErrors`
+ * files them under.
  *
  * @example
  * ```tsx
@@ -111,13 +134,14 @@ export function getFieldError(
   error: ValidationError,
   fieldName: string
 ): string | undefined {
-  const issue = error.issues.find((i) => String(i.path[0]) === fieldName)
+  const issue = error.issues.find((i) => fieldNameOf(i) === fieldName)
   return issue?.message
 }
 
 /**
  * Gets all error messages for a specific field from a ValidationError.
- * Returns empty array if no errors exist for that field.
+ * Returns empty array if no errors exist for that field. Pass `""` for issues
+ * about the whole argument (an empty path).
  *
  * @example
  * ```tsx
@@ -132,7 +156,7 @@ export function getFieldErrors(
   fieldName: string
 ): string[] {
   return error.issues
-    .filter((i) => String(i.path[0]) === fieldName)
+    .filter((i) => fieldNameOf(i) === fieldName)
     .map((i) => i.message)
 }