@uniflowed/query 0.0.0-alpha.10

package/infinite.js

@@ -0,0 +1,311 @@
+// @flow
+//
+// `@uniflowed/query/infinite`: many pages, one entry.
+//
+// "Load more" is not a sequence of queries. If page two were its own cache
+// entry, then the list on screen would be the concatenation of three entries
+// that can be invalidated, refetched and garbage-collected independently — and
+// the first time one of them refreshed on its own the reader would see a list
+// with a hole in it, or the same row twice.
+//
+// So a paged query is *one* entry whose value happens to be a list of pages:
+//
+// ```js
+// { pages: [[…], […]], pageParams: [undefined, "cursor-2"] }
+// ```
+//
+// One key, one staleness clock, one invalidation, one garbage collection, and
+// one thing to render. `pageParams` is kept beside the pages because a refetch
+// has to be able to ask for the same pages again, and a cursor is not
+// recoverable from the rows it returned.
+//
+// # Why this is a fetcher and not a second cache
+//
+// Everything else about a paged query — de-duplication, retries, cancellation,
+// staleness, structural sharing — is identical to an ordinary one. The only
+// difference is what "fetch this entry" means, so that is the only thing this
+// module replaces: [`infinitePages`] builds the function [`Query`] calls, and
+// [`InfiniteQueryObserver`] is the ordinary observer with the page controls
+// added to its snapshot.
+//
+// Structural sharing is why appending a page is cheap: the new value is a new
+// array with the *same* page objects in it, so the pages already rendered keep
+// their identity and a memoised row component does not re-render because its
+// neighbour arrived.
+//
+// # Why a refetch re-asks for every page
+//
+// The alternative is to refetch page one and keep the rest, which produces a
+// list that is coherent nowhere: the first page is from now and the second is
+// from ten minutes ago, and an item that moved between them appears twice or
+// not at all. So a refetch walks the recorded `pageParams` in order and asks
+// again for each. It is more expensive, and it is the only version that is
+// correct.
+//
+// The recorded parameters are reused rather than recomputed from
+// `getNextPageParam`, so a refetch asks for the pages the reader is looking
+// at. A cursor that has since expired is the server's to reject, and the
+// failure is reported rather than hidden behind a silently different list.
+//
+// # What is out of scope
+//
+// `client.fetchInfiniteQuery` — prefetching a paged query from outside React —
+// is not implemented. It needs the same page walk with a different entry
+// point, and until there is a server-rendering path that wants it, it would be
+// an untested API. `useInfiniteQuery` inside a tree covers what applications
+// do today.
+
+import type { QueryKey } from "./key.js";
+import { QueryObserver } from "./observer.js";
+import type { QueryResult, ResolvedQueryOptions } from "./observer.js";
+import type { FetchContext, FetchDirection, Fetcher, Query, QueryState } from "./query.js";
+
+/** The value a paged entry holds. */
+export type InfiniteData<TPage, TParam> = {|
+  readonly pages: $ReadOnlyArray<TPage>,
+  readonly pageParams: $ReadOnlyArray<TParam>,
+|};
+
+/** What the query function is called with, once per page. */
+export type InfinitePageContext<TParam> = {|
+  readonly queryKey: QueryKey,
+  readonly signal: AbortSignal,
+  readonly pageParam: TParam,
+  readonly direction: FetchDirection,
+|};
+
+/**
+ * Where the next page starts, or `null` when there is no next page.
+ *
+ * Returning `null` is how the list ends, and it is why `hasNextPage` can be
+ * answered without an extra request: the server already said so in the answer
+ * it gave for the last page.
+ */
+export type PageParamFn<TPage, TParam> = (
+  lastPage: TPage,
+  allPages: $ReadOnlyArray<TPage>,
+  lastPageParam: TParam,
+  allPageParams: $ReadOnlyArray<TParam>,
+) => TParam | null | void;
+
+export type InfiniteQueryOptions<TPage, TParam, TSelected = InfiniteData<TPage, TParam>> = {|
+  readonly queryKey: QueryKey,
+  readonly queryFn: (context: InfinitePageContext<TParam>) => Promise<TPage>,
+  /** The parameter the first page is asked for with. */
+  readonly initialPageParam: TParam,
+  readonly getNextPageParam: PageParamFn<TPage, TParam>,
+  readonly getPreviousPageParam?: PageParamFn<TPage, TParam>,
+  /** Keep at most this many pages, dropping from the far end. */
+  readonly maxPages?: number,
+  readonly enabled?: boolean,
+  readonly staleTime?: number,
+  readonly gcTime?: number,
+  readonly retry?: mixed,
+  readonly retryDelay?: mixed,
+  readonly select?: (data: InfiniteData<TPage, TParam>) => TSelected,
+  readonly placeholderData?: mixed,
+  readonly refetchInterval?: number | null,
+  readonly refetchOnWindowFocus?: boolean,
+  readonly refetchOnReconnect?: boolean,
+|};
+
+/** An ordinary result, plus the two ends of the list. */
+export type InfiniteQueryResult<TSelected> = {|
+  ...QueryResult<TSelected>,
+  readonly hasNextPage: boolean,
+  readonly hasPreviousPage: boolean,
+  readonly isFetchingNextPage: boolean,
+  readonly isFetchingPreviousPage: boolean,
+  readonly fetchNextPage: () => Promise<void>,
+  readonly fetchPreviousPage: () => Promise<void>,
+|};
+
+/**
+ * The function the cache calls to fill a paged entry.
+ *
+ * `direction` decides which of the three things it means: extend the list
+ * forward, extend it backward, or — when there is no direction — refetch every
+ * page the entry already holds. A first fetch has nothing to extend, so it
+ * asks for `initialPageParam` whatever the direction says.
+ */
+export function infinitePages<TPage, TParam>(
+  options: InfiniteQueryOptions<TPage, TParam, mixed>,
+  direction: FetchDirection | null,
+): Fetcher<InfiniteData<TPage, TParam>> {
+  return async (context: FetchContext<InfiniteData<TPage, TParam>>) => {
+    const previous = context.previousData;
+    const askFor = (pageParam: TParam, towards: FetchDirection): Promise<TPage> =>
+      options.queryFn({
+        queryKey: context.queryKey,
+        pageParam,
+        direction: towards,
+        // Delegated rather than read, so a paged query function that ignores
+        // the signal leaves the entry uncancellable in exactly the same way an
+        // ordinary one does. Reading it here instead would opt every paged
+        // query in on its behalf. See `query.js` for what the getter means.
+        // uf-lint-disable-next-line flow/unsafe-getters-setters
+        get signal(): AbortSignal {
+          return context.signal;
+        },
+      });
+
+    if (previous == null || previous.pages.length === 0) {
+      const page = await askFor(options.initialPageParam, "forward");
+      return { pages: [page], pageParams: [options.initialPageParam] };
+    }
+
+    if (direction === "forward") {
+      const param = nextParam(options, previous);
+      if (param == null) {
+        return previous;
+      }
+      const page = await askFor(param, "forward");
+      return trim(
+        { pages: [...previous.pages, page], pageParams: [...previous.pageParams, param] },
+        options.maxPages,
+        "forward",
+      );
+    }
+
+    if (direction === "backward") {
+      const param = previousParam(options, previous);
+      if (param == null) {
+        return previous;
+      }
+      const page = await askFor(param, "backward");
+      return trim(
+        { pages: [page, ...previous.pages], pageParams: [param, ...previous.pageParams] },
+        options.maxPages,
+        "backward",
+      );
+    }
+
+    // No direction: refresh what is on screen, page by page, in order.
+    const pages: Array<TPage> = [];
+    for (const pageParam of previous.pageParams) {
+      pages.push(await askFor(pageParam, "forward"));
+    }
+    return { pages, pageParams: previous.pageParams.slice() };
+  };
+}
+
+/** Whether the server said there is another page after the ones held. */
+export function hasMore<TPage, TParam>(
+  options: InfiniteQueryOptions<TPage, TParam, mixed>,
+  data: InfiniteData<TPage, TParam> | void,
+  towards: FetchDirection,
+): boolean {
+  if (data == null || data.pages.length === 0) {
+    return false;
+  }
+  return (towards === "forward" ? nextParam(options, data) : previousParam(options, data)) != null;
+}
+
+/**
+ * The observer for a paged query.
+ *
+ * Everything about watching, fetching, retrying and snapshotting is inherited;
+ * the two differences are that the entry is filled a page at a time and that
+ * the snapshot carries the controls for the two ends of the list.
+ */
+export class InfiniteQueryObserver<TPage, TParam, TSelected> extends QueryObserver<
+  InfiniteData<TPage, TParam>,
+  TSelected,
+> {
+  readonly fetchNextPage: () => Promise<void>;
+  readonly fetchPreviousPage: () => Promise<void>;
+
+  constructor(
+    client: $FlowFixMe,
+    getOptions: () => InfiniteQueryOptions<TPage, TParam, TSelected>,
+  ) {
+    super(client, getOptions as $FlowFixMe);
+    // Stable for the observer's life: a snapshot that carried a new function
+    // every render would never compare equal to the one before it, and every
+    // notification would become a re-render.
+    // `cancelRefetch: true`, because a page control is a request for something
+    // the entry does not have yet. Joining whatever is in flight would return
+    // the refetch's answer and add no page at all — the directional fetcher
+    // would never run — so pressing "load more" while a background refetch was
+    // going did nothing, silently.
+    this.fetchNextPage = () => this.fetch({ cancelRefetch: true, direction: "forward" });
+    this.fetchPreviousPage = () => this.fetch({ cancelRefetch: true, direction: "backward" });
+  }
+
+  pageOptions(): InfiniteQueryOptions<TPage, TParam, mixed> {
+    return this.getOptions() as $FlowFixMe;
+  }
+
+  buildFetcher(
+    _options: ResolvedQueryOptions<InfiniteData<TPage, TParam>, TSelected>,
+    direction: FetchDirection | null,
+  ): Fetcher<InfiniteData<TPage, TParam>> {
+    return infinitePages(this.pageOptions(), direction);
+  }
+
+  // $FlowFixMe[incompatible-extend] the paged snapshot is the base snapshot plus
+  // the page controls. Flow has no way to state "the same exact object with
+  // more fields" for an override, and widening the base result to an inexact
+  // type to allow it would stop catching typos in every ordinary query.
+  buildResult(
+    query: Query<InfiniteData<TPage, TParam>> | void,
+    state: QueryState<InfiniteData<TPage, TParam>>,
+    options: ResolvedQueryOptions<InfiniteData<TPage, TParam>, TSelected>,
+  ): InfiniteQueryResult<TSelected> {
+    const base = super.buildResult(query, state, options);
+    const pages = this.pageOptions();
+    // Asked of the raw pages rather than of `base.data`, which may have been
+    // narrowed by `select` into something with no pages in it at all.
+    const data = state.data;
+    const isFetching = state.fetchStatus === "fetching";
+    return {
+      ...base,
+      hasNextPage: hasMore(pages, data, "forward"),
+      hasPreviousPage: hasMore(pages, data, "backward"),
+      isFetchingNextPage: isFetching && state.direction === "forward",
+      isFetchingPreviousPage: isFetching && state.direction === "backward",
+      fetchNextPage: this.fetchNextPage,
+      fetchPreviousPage: this.fetchPreviousPage,
+    };
+  }
+}
+
+function nextParam<TPage, TParam>(
+  options: InfiniteQueryOptions<TPage, TParam, mixed>,
+  data: InfiniteData<TPage, TParam>,
+): TParam | null | void {
+  const index = data.pages.length - 1;
+  return options.getNextPageParam(
+    data.pages[index],
+    data.pages,
+    data.pageParams[index],
+    data.pageParams,
+  );
+}
+
+function previousParam<TPage, TParam>(
+  options: InfiniteQueryOptions<TPage, TParam, mixed>,
+  data: InfiniteData<TPage, TParam>,
+): TParam | null | void {
+  const get = options.getPreviousPageParam;
+  if (get == null) {
+    return null;
+  }
+  return get(data.pages[0], data.pages, data.pageParams[0], data.pageParams);
+}
+
+/** Keep at most `maxPages`, dropping from the end the reader is moving away from. */
+function trim<TPage, TParam>(
+  data: InfiniteData<TPage, TParam>,
+  maxPages: number | void,
+  direction: FetchDirection,
+): InfiniteData<TPage, TParam> {
+  if (maxPages == null || maxPages <= 0 || data.pages.length <= maxPages) {
+    return data;
+  }
+  const from = direction === "forward" ? data.pages.length - maxPages : 0;
+  return {
+    pages: data.pages.slice(from, from + maxPages),
+    pageParams: data.pageParams.slice(from, from + maxPages),
+  };
+}

package/key.js

@@ -0,0 +1,124 @@
+// @flow
+//
+// `@uniflowed/query/key`: what makes two requests the same request.
+//
+// Everything else in this package is downstream of one decision: when two
+// components ask for `["user", 1]`, is that one entry or two? The answer has
+// to be a *value* comparison — the arrays are written inline in two different
+// files and will never be the same object — so a key is reduced to a string
+// and the string is the identity.
+//
+// # Why the hash is order-stable
+//
+// `JSON.stringify` of the array would be enough if every caller wrote object
+// members in the same order. They do not: `["users", {page: 1, size: 20}]` and
+// `["users", {size: 20, page: 1}]` are the same request written by two people,
+// and hashing them apart means two cache entries, two requests, and two
+// answers that can disagree on screen. So object keys are sorted as the walk
+// serialises them.
+//
+// Arrays are *not* sorted — order is meaning there — and neither is anything
+// else. A `Date` or a class instance in a key serialises through its own
+// `toJSON`, which is a reasonable default and a bad idea to rely on; keys
+// should be built from strings, numbers and plain records.
+//
+// # Why `1` and `"1"` are different keys
+//
+// They come from different code paths — a route parameter is a string, a
+// database id is a number — and treating them as one entry means a component
+// reading `["user", 1]` is shown the answer fetched for `["user", "1"]`. That
+// is a bug that surfaces as *the wrong data*, never as an exception, which is
+// the worst failure mode a cache has. `JSON.stringify` keeps them apart for
+// free, so the cheap behaviour is also the correct one.
+//
+// # Why matching is by prefix
+//
+// Invalidation is written as `["users"]` and has to reach `["users", 1]` and
+// `["users", 2]` without the caller enumerating them, because after creating a
+// user the caller does not know which ids are cached. [`matchesKey`] is that
+// rule, and it is structural rather than a string `startsWith` on the hash:
+// the string form has no idea where one member ends and the next begins, so
+// `["user"]` would match `["users", 1]` for a large enough coincidence of
+// punctuation. Comparing the arrays cannot make that mistake.
+
+import { isPlainObject } from "./structural.js";
+
+/** A key, as a caller writes it: `["user", id]`. */
+export type QueryKey = $ReadOnlyArray<mixed>;
+
+/**
+ * A key as a string, stable across member order inside object members.
+ *
+ * Two keys with the same hash are the same request by definition. That is the
+ * contract every other module in this package relies on, including the one
+ * that decides a component does not need to resubscribe.
+ */
+export function hashKey(key: QueryKey): string {
+  return JSON.stringify(key, (_name, value) =>
+    isPlainObject(value)
+      ? Object.keys(value)
+          .sort()
+          .reduce((sorted: $FlowFixMe, name: string) => {
+            sorted[name] = (value as $FlowFixMe)[name];
+            return sorted;
+          }, {})
+      : value,
+  );
+}
+
+/**
+ * Whether `key` is described by `pattern`.
+ *
+ * By default `pattern` is a prefix: `["users"]` matches `["users", 1]`, and
+ * `["users", {done: true}]` matches `["users", {done: true, page: 2}]` —
+ * object members match partially, so a filter can name the parts of a
+ * parameter record it cares about and ignore the rest.
+ *
+ * With `exact`, the two must hash identically. That is the option for "this
+ * one entry and not the list it belongs to", which is the difference between
+ * refreshing a row and refetching a table.
+ */
+export function matchesKey(key: QueryKey, pattern: QueryKey, exact: boolean = false): boolean {
+  if (exact) {
+    return hashKey(key) === hashKey(pattern);
+  }
+  if (pattern.length > key.length) {
+    return false;
+  }
+  for (let index = 0; index < pattern.length; index += 1) {
+    if (!partiallyMatches(key[index], pattern[index])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Whether `value` satisfies everything `pattern` states about it.
+ *
+ * Object patterns are partial — they constrain the members they name — while
+ * arrays must line up member for member. The asymmetry is deliberate: a record
+ * in a key is a bag of parameters and naming one of them is a useful filter,
+ * whereas a shorter array is a different list, not a laxer description of one.
+ */
+function partiallyMatches(value: mixed, pattern: mixed): boolean {
+  if (Object.is(value, pattern)) {
+    return true;
+  }
+  if (Array.isArray(pattern)) {
+    if (!Array.isArray(value) || value.length !== pattern.length) {
+      return false;
+    }
+    return pattern.every((member, index) => partiallyMatches(value[index], member));
+  }
+  if (isPlainObject(pattern)) {
+    if (!isPlainObject(value)) {
+      return false;
+    }
+    const record = value as $FlowFixMe;
+    return Object.keys(pattern as $FlowFixMe).every((name) =>
+      partiallyMatches(record[name], (pattern as $FlowFixMe)[name]),
+    );
+  }
+  return false;
+}

package/mutation.js

@@ -0,0 +1,249 @@
+// @flow
+//
+// `@uniflowed/query/mutation`: the write, and the lie you tell before it.
+//
+// A mutation is not a query with a different verb. A query can be repeated,
+// abandoned, de-duplicated and garbage-collected because asking twice is free;
+// none of that is true of "create the invoice". So this module shares the
+// retry loop with queries and nothing else: no cache entry, no de-duplication,
+// no staleness, and — deliberately — no cancellation.
+//
+// # Why an unmount does not cancel a mutation
+//
+// A request that has left the building cannot be un-sent. Aborting it would
+// stop the *answer* arriving, not the write happening, and the application
+// would be left unable to say whether the invoice exists. So a mutation runs
+// to completion and its callbacks fire even if the component that started it
+// has gone. The callbacks are where cache updates and invalidations live,
+// which is exactly the work that still needs doing when the reader has moved
+// on.
+//
+// # Why `onMutate` returns a context and `onError` is given it
+//
+// Optimistic updates are the reason this API has a shape at all. The sequence
+// is fixed and each step exists because of a specific failure:
+//
+// ```js
+// onMutate: async (next) => {
+//   // A refetch already in flight would land *after* the optimistic write and
+//   // put the server's old answer back on screen. Stop it first.
+//   await client.cancelQueries({ queryKey: ["todos"] });
+//   const previous = client.getQueryData(["todos"]);
+//   client.setQueryData(["todos"], (todos) => [...todos, next]);
+//   return { previous };            // ← the rollback, captured before the guess
+// },
+// onError: (_error, _next, context) => {
+//   client.setQueryData(["todos"], context.previous);
+// },
+// onSettled: () => client.invalidateQueries({ queryKey: ["todos"] }),
+// ```
+//
+// The context has to be produced by `onMutate` and handed back to `onError`
+// because nothing else can hold it: a `useRef` in the component is gone if the
+// component unmounted, and a variable in the caller's closure belongs to one
+// call and two mutations can be in flight at once. Passing it through the
+// mutation itself is what makes the rollback correct for *this* call.
+//
+// `onError` runs before the state becomes `error`, and `onSettled` before
+// either terminal state, so by the time a component is told the mutation
+// failed, the rollback has already happened — the reader never sees the
+// optimistic value and the failure message at the same time.
+//
+// # Why the state is an external store rather than `useState`
+//
+// So a snapshot is one immutable object with a stable identity, comparable by
+// `Object.is`, which is what `useSyncExternalStore` requires and what keeps a
+// re-render from being scheduled for a mutation that has not moved. It also
+// means the state machine is testable without rendering anything.
+
+import { asError, runWithRetry } from "./retry.js";
+import type { RetryDelay, RetryPolicy } from "./retry.js";
+
+export type MutationStatus = "idle" | "pending" | "success" | "error";
+
+export type MutationState<TVariables, TData> = {|
+  readonly status: MutationStatus,
+  readonly data: TData | void,
+  readonly error: Error | null,
+  /** What the last call was given, so a retry button can repeat it. */
+  readonly variables: TVariables | void,
+  readonly failureCount: number,
+  readonly submittedAt: number,
+|};
+
+/**
+ * The callbacks a single call may add.
+ *
+ * Both sets run — the ones on the hook and the ones on the call — with the
+ * hook's first. The hook's are the ones that keep the cache correct and must
+ * not be skippable by a caller who only wanted a toast.
+ */
+export type MutationCallbacks<TVariables, TData, TContext> = {|
+  readonly onSuccess?: (data: TData, variables: TVariables, context: TContext | void) => mixed,
+  readonly onError?: (error: Error, variables: TVariables, context: TContext | void) => mixed,
+  readonly onSettled?: (
+    data: TData | void,
+    error: Error | null,
+    variables: TVariables,
+    context: TContext | void,
+  ) => mixed,
+|};
+
+export type MutationOptions<TVariables, TData, TContext> = {|
+  readonly mutationFn: (variables: TVariables) => Promise<TData>,
+  /** Runs first; what it returns is handed to the other three. */
+  readonly onMutate?: (variables: TVariables) => Promise<TContext | void> | TContext | void,
+  readonly onSuccess?: (data: TData, variables: TVariables, context: TContext | void) => mixed,
+  readonly onError?: (error: Error, variables: TVariables, context: TContext | void) => mixed,
+  readonly onSettled?: (
+    data: TData | void,
+    error: Error | null,
+    variables: TVariables,
+    context: TContext | void,
+  ) => mixed,
+  readonly retry?: RetryPolicy,
+  readonly retryDelay?: RetryDelay,
+|};
+
+/** The same options with the client's defaults filled in. */
+export type ResolvedMutationOptions<TVariables, TData, TContext> = {|
+  ...MutationOptions<TVariables, TData, TContext>,
+  readonly retry: RetryPolicy,
+  readonly retryDelay: RetryDelay,
+|};
+
+/** What a mutation looks like to a component. */
+export type MutationResult<TVariables, TData, TContext> = {|
+  readonly data: TData | void,
+  readonly error: Error | null,
+  readonly status: MutationStatus,
+  readonly variables: TVariables | void,
+  readonly failureCount: number,
+  readonly isIdle: boolean,
+  readonly isPending: boolean,
+  readonly isSuccess: boolean,
+  readonly isError: boolean,
+  /** Fire and forget. The failure is in `error`, not in a rejected promise. */
+  readonly mutate: (
+    variables: TVariables,
+    callbacks?: MutationCallbacks<TVariables, TData, TContext>,
+  ) => void,
+  /** The same call, awaited. Rejects, so a caller can branch on the failure. */
+  readonly mutateAsync: (
+    variables: TVariables,
+    callbacks?: MutationCallbacks<TVariables, TData, TContext>,
+  ) => Promise<TData>,
+  readonly reset: () => void,
+|};
+
+const IDLE: MutationState<empty, empty> = Object.freeze({
+  status: "idle",
+  data: undefined,
+  error: null,
+  variables: undefined,
+  failureCount: 0,
+  submittedAt: 0,
+});
+
+export class Mutation<TVariables, TData, TContext> {
+  state: MutationState<TVariables, TData> = IDLE;
+  listeners: Set<() => void> = new Set();
+
+  /**
+   * Which call owns the state.
+   *
+   * Two calls can be in flight — a reader who clicked twice — and the state
+   * describes the latest, not whichever settled last. The callbacks of both
+   * still run: each of them was a real write with real consequences, and the
+   * cache updates in them are not the loser's to skip.
+   */
+  runId: number = 0;
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Back to idle, forgetting the last result. */
+  reset(): void {
+    this.runId += 1;
+    this.setState(IDLE as $FlowFixMe);
+  }
+
+  async execute(
+    variables: TVariables,
+    options: ResolvedMutationOptions<TVariables, TData, TContext>,
+    callbacks?: MutationCallbacks<TVariables, TData, TContext>,
+  ): Promise<TData> {
+    const id = this.runId + 1;
+    this.runId = id;
+    this.setState({
+      status: "pending",
+      data: undefined,
+      error: null,
+      variables,
+      failureCount: 0,
+      submittedAt: Date.now(),
+    });
+
+    // Declared outside the `try` so the rollback in `onError` can still be
+    // given whatever `onMutate` managed to record before things went wrong.
+    let context: TContext | void;
+    try {
+      context = await options.onMutate?.(variables);
+      const data = await runWithRetry({
+        attempt: () => options.mutationFn(variables),
+        retry: options.retry,
+        retryDelay: options.retryDelay,
+        // Never aborted: see the module docs on why a write is not cancelled.
+        signal: new AbortController().signal,
+        onFailure: (failureCount) => {
+          if (this.runId === id) {
+            this.setState({ failureCount });
+          }
+        },
+      });
+
+      // Before the state moves to `success`, so a component told the mutation
+      // succeeded is looking at a cache that already knows.
+      await options.onSuccess?.(data, variables, context);
+      await callbacks?.onSuccess?.(data, variables, context);
+      await options.onSettled?.(data, null, variables, context);
+      await callbacks?.onSettled?.(data, null, variables, context);
+
+      if (this.runId === id) {
+        this.setState({ status: "success", data, error: null });
+      }
+      return data;
+    } catch (thrown) {
+      const error = asError(thrown);
+      try {
+        await options.onError?.(error, variables, context);
+        await callbacks?.onError?.(error, variables, context);
+        await options.onSettled?.(undefined, error, variables, context);
+        await callbacks?.onSettled?.(undefined, error, variables, context);
+      } finally {
+        // Committed whatever the callbacks did. A callback that throws is the
+        // caller's bug and still reaches them — it comes out of `execute` in
+        // place of the rethrow below — but a mutation left `pending` for ever
+        // because a listener threw would be this module's bug, and the
+        // component showing a spinner has no way back from it.
+        if (this.runId === id) {
+          this.setState({ status: "error", error, data: undefined });
+        }
+      }
+      // Rethrown so `mutateAsync` can be branched on. `mutate` swallows it,
+      // which is why the two exist.
+      throw error;
+    }
+  }
+
+  setState(patch: { +[string]: mixed }): void {
+    this.state = { ...this.state, ...patch } as $FlowFixMe;
+    for (const listener of Array.from(this.listeners)) {
+      listener();
+    }
+  }
+}