@ic-reactor/react 3.12.4 → 3.13.0

package/dist/utils.d.ts

@@ -1,15 +1,132 @@
 /**
- * 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 type { QueryClient, QueryKey } from "@tanstack/react-query";
+import type { CallConfig } from "@icp-sdk/core/agent";
+import type { ClientManager, Reactor, ReactorQueryData, TransformKey } from "@ic-reactor/core";
+import type { InvalidationTarget, QueryCacheControls, QueryFactoryMethods } 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 declare function useMountQueryClient(queryClient: QueryClient | undefined): void;
+/**
+ * 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 declare function mountWhileSuspended(queryClient: QueryClient | undefined, thrown: unknown): void;
 /**
  * Internal query-key segment used to distinguish per-call factory args
  * from the base query key. Not part of the public API.
  */
 export declare 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 declare 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 declare function skippedQueryKey(prefix: QueryKey, kind: "query" | "infinite"): QueryKey;
+/**
+ * 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 declare function callConfigForKey(queryKey: QueryKey, callConfig: CallConfig | undefined): CallConfig | undefined;
 /** Convert a direct reactor result into a value TanStack Query can cache. */
 export declare const normalizeQueryData: <T>(value: T) => ReactorQueryData<T>;
+/** Config options that decide how a query's function runs. */
+declare const FETCH_OPTION_KEYS: readonly ["networkMode", "retry", "retryDelay", "meta"];
+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 declare function pickFetchOptions<Config extends object>(config: Config): 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 declare function retryOption<TRetry, TDefault>(ownRetry: TRetry | undefined, defaultRetry: TDefault | undefined): {
+    retry?: TRetry | TDefault;
+};
 /**
  * Merge a base query key, optional per-call query key, and optional key-args
  * into a single query key array.
@@ -48,4 +165,43 @@ export declare function createBoundedCache<V>(limit?: number): {
     set(key: string, value: V): void;
     readonly size: number;
 };
+/**
+ * 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 declare function invalidateTargets<Service, Transform extends TransformKey>(reactor: Reactor<Service, Transform>, targets: readonly InvalidationTarget<Service, Transform>[] | undefined, callConfig?: CallConfig): Promise<void>;
+/**
+ * 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 declare function withQueryFactoryMethods<Factory extends object>(factory: Factory, reactor: {
+    readonly queryClient: QueryClient;
+}, getQueryKey: () => QueryKey): Factory & QueryFactoryMethods;
+/** What {@link queryCacheControls} reads from a reactor. */
+interface CacheOwner {
+    readonly queryClient: QueryClient;
+    readonly clientManager: Pick<ClientManager, "identity">;
+}
+/**
+ * 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 declare function queryCacheControls<TQueryFnData>(reactor: CacheOwner, getQueryKey: () => QueryKey): QueryCacheControls<TQueryFnData>;
+export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAGxD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,kCAAkC,CAAA;AAEzE,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,gBAAgB,CAAC,CAAC,CACN,CAAA;AAE7D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,CAAC,EAAE,QAAQ,EACvB,YAAY,CAAC,EAAE,QAAQ,EACvB,OAAO,CAAC,EAAE,OAAO,GAChB,QAAQ,GAAG,SAAS,CAgBtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,EACrE,YAAY,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,GAAG,SAAS,EACtD,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,GAAG,SAAS,GACpD,CAAC,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,GAAG,MAAM,CAAC,GAAG,SAAS,CAStD;AAaD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,GAAE,MAA4B;aAI5D,MAAM,GAAG,CAAC,GAAG,SAAS;aAQtB,MAAM,SAAS,CAAC,GAAG,IAAI;mBAQpB,MAAM;EAIrB"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/dist/utils.js

@@ -1,14 +1,166 @@
 /**
- * Shared internal utilities for query and mutation factories.
+ * Shared internal utilities for the query and mutation hooks and factories.
  */
+import { useEffect } from "react";
 import { generateKey } from "@ic-reactor/core";
+/**
+ * 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) {
+    useEffect(() => {
+        if (!queryClient)
+            return;
+        queryClient.mount();
+        return () => queryClient.unmount();
+    }, [queryClient]);
+}
+const isThenable = (value) => typeof value?.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, thrown) {
+    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
  * from the base query key. Not part of the public API.
  */
 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, kind) {
+    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, callConfig) {
+    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 = (value) => (value === undefined ? null : value);
+/** Config options that decide how a query's function runs. */
+const FETCH_OPTION_KEYS = [
+    "networkMode",
+    "retry",
+    "retryDelay",
+    "meta",
+];
+/**
+ * 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) {
+    const picked = {};
+    for (const key of FETCH_OPTION_KEYS) {
+        const value = config[key];
+        if (value !== undefined)
+            picked[key] = value;
+    }
+    return picked;
+}
+/**
+ * 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(ownRetry, defaultRetry) {
+    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.
@@ -102,4 +254,152 @@ export function createBoundedCache(limit = FACTORY_CACHE_LIMIT) {
         },
     };
 }
+const isQueryKeySource = (value) => typeof value.getQueryKey === "function";
+/**
+ * Invalidate one `invalidateQueries` entry; see {@link invalidateTargets}.
+ */
+function invalidateTarget(reactor, target, canisterId) {
+    // 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;
+    // `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?.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(reactor, targets, callConfig) {
+    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, reactor, getQueryKey) {
+    const methods = {
+        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 = { rollback: () => { } };
+/**
+ * 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) => 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(reactor, getQueryKey) {
+    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(queryKey);
+            if (snapshot?.data === undefined)
+                return NOTHING_TO_ROLL_BACK;
+            const { data: previous, dataUpdatedAt, isInvalidated } = snapshot;
+            queryClient.setQueryData(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(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 });
+                    }
+                },
+            };
+        },
+    };
+}
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

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

package/dist/validation.d.ts

@@ -29,7 +29,9 @@ export interface MapValidationErrorsOptions {
 }
 /**
  * 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
@@ -49,16 +51,18 @@ export interface MapValidationErrorsOptions {
  * })
  * ```
  */
-export declare function mapValidationErrors(error: ValidationError): FieldErrors;
+export declare function mapValidationErrors(error: ValidationError, options?: {
+    multiple?: false;
+}): FieldErrors;
 export declare function mapValidationErrors(error: ValidationError, options: {
     multiple: true;
 }): FieldErrorsMultiple;
-export declare function mapValidationErrors(error: ValidationError, options: {
-    multiple: false;
-}): FieldErrors;
+export declare function mapValidationErrors(error: ValidationError, options?: MapValidationErrorsOptions): FieldErrors | FieldErrorsMultiple;
 /**
  * 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
@@ -71,7 +75,8 @@ export declare function mapValidationErrors(error: ValidationError, options: {
 export declare function getFieldError(error: ValidationError, fieldName: string): string | undefined;
 /**
  * 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

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,CAAA;AAC7C,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAEhD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAE1D;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,WAAW,CAAA;AACxE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,mBAAmB,CAAA;AACtB,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,GAC3B,WAAW,CAAA;AA2Bd;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,MAAM,EAAE,CAIV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAK1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,EAC7C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GACpC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CASxB"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,CAAA;AAC7C,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAEhD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAE1D;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAWD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GAC7B,WAAW,CAAA;AACd,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,mBAAmB,CAAA;AACtB,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,0BAA0B,GACnC,WAAW,GAAG,mBAAmB,CAAA;AAkCpC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,MAAM,EAAE,CAIV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAK1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,EAC7C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GACpC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CASxB"}