@uniflowed/query 0.0.0-alpha.10

package/react.js

@@ -0,0 +1,251 @@
+// @flow
+//
+// `@uniflowed/query/react`: the binding, and why it is this thin.
+//
+// Every hook here is a `useSyncExternalStore` over a store that already knows
+// how to keep itself correct, and almost nothing else. There is no effect that
+// starts a request, no ref holding the latest query function, and no
+// dependency array deciding when to refetch. Subscribing *is* the statement
+// that a value is wanted, so the store starts the request; the component only
+// reads.
+//
+// That is not a stylistic preference. Reading an external store through the
+// API React provides for it is what makes the value React committed with the
+// value the component rendered — which is what stops two components sharing a
+// key from painting different versions of it during a concurrent render — and
+// it is what lets a prerender state the server's answer rather than fall
+// through to it.
+//
+// # What runs during render, and what does not
+//
+// During render: reading the cache, applying `select`, and comparing the
+// result with the previous one. All of it is pure with respect to anything
+// outside this hook — the entry is not created, no request is started, no
+// listener is registered, and running it twice produces the same object. The
+// observer's memo slots are written, and that is a cache in the `useMemo`
+// sense; the module docs in `observer.js` set out why that is the only way
+// `getSnapshot` can meet its contract.
+//
+// Outside render, in the effect React calls `subscribe` from: building the
+// entry, registering the listener, starting the fetch, and setting the stale
+// and interval timers. Every one is undone by the function `subscribe`
+// returns, so a component that mounts and unmounts leaves nothing behind.
+//
+// # Why the query function is not a dependency
+//
+// Callers write `queryFn` inline, so its identity changes on every render, and
+// a subscription keyed on it would be torn down and rebuilt on every
+// keystroke. But it is something to *call*, not something to react to: it is
+// read through a callback whose identity never changes and whose body is
+// always the latest, so a fresh closure changes nothing and the request that
+// is eventually made is the current one.
+//
+// What the subscription *is* keyed on is the plan: the key's hash, whether it
+// is enabled, and the times and intervals. Those are the values that change
+// what is being watched, and there are few enough of them to write down —
+// which is better than an exhaustive dependency array that resubscribes for
+// reasons nobody can name.
+//
+// # Why there is no `Suspense` integration here
+//
+// `useQuery` returning a result rather than suspending is a decision, not an
+// omission. Suspending on read makes waterfalls the default — each component
+// suspends in turn, and each one's request starts only after the one above it
+// resolves — and the fix is to hoist fetching to the route, which is
+// `client.prefetchQuery` and `@uniflowed/router`'s loaders. A `useSuspenseQuery`
+// belongs with that work, where the prefetch can be arranged, not here where
+// it would quietly make every list slower.
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "@uniflowed/react";
+
+import { useStableCallback } from "@uniflowed/hooks";
+
+import type { QueryClient } from "./client.js";
+import { InfiniteQueryObserver } from "./infinite.js";
+import type { InfiniteData, InfiniteQueryOptions, InfiniteQueryResult } from "./infinite.js";
+import { hashKey } from "./key.js";
+import { Mutation } from "./mutation.js";
+import type {
+  MutationCallbacks,
+  MutationOptions,
+  MutationResult,
+  MutationState,
+} from "./mutation.js";
+import { QueryObserver } from "./observer.js";
+import type { QueryOptions, QueryResult, ResolvedQueryOptions } from "./observer.js";
+
+const ClientContext: React.Context<QueryClient | null> = createContext(null);
+
+/**
+ * Make a client available to the tree.
+ *
+ * Required rather than falling back to a module-level default. A default is
+ * shared with every other tree in the process, which on a server means one
+ * reader's data is in the cache the next request renders from, and in a test
+ * means the previous test's answer decides this one's result.
+ */
+export component QueryClientProvider(client: QueryClient, children: React.Node) {
+  return <ClientContext.Provider value={client}>{children}</ClientContext.Provider>;
+}
+
+/** The client this subtree uses. */
+export function useQueryClient(): QueryClient {
+  const client = useContext(ClientContext);
+  if (client == null) {
+    throw new Error(
+      "useQuery needs a QueryClientProvider above it; render <QueryClientProvider client={new QueryClient()}>",
+    );
+  }
+  return client;
+}
+
+/**
+ * Read a key, fetching it when it is missing or stale.
+ *
+ * A cached answer is returned immediately and refreshed behind it, so
+ * navigating back to a page shows it at once. `isFetching` says a request is
+ * in flight; `isPending` says there is nothing to show yet — conflating those
+ * is why applications flash a spinner over data they already have.
+ */
+export function useQuery<TData, TSelected = TData>(
+  options: QueryOptions<TData, TSelected>,
+): QueryResult<TSelected> {
+  const client = useQueryClient();
+  const getOptions = useStableCallback(() => options);
+
+  // Created once and never during a commit: the constructor touches nothing
+  // outside the object, so React discarding one of a double-invoked render's
+  // two observers costs an allocation and changes no behaviour.
+  const [observer] = useState(() => new QueryObserver<TData, TSelected>(client, getOptions));
+
+  // Once per render, and used for both what is watched and what is read, so
+  // the two cannot disagree about a default.
+  const resolved = client.resolveQuery(options);
+  const plan = subscriptionPlan(resolved);
+  const subscribe = useCallback(
+    (listener: () => void) => observer.subscribe(client, listener),
+    [observer, client, plan],
+  );
+
+  // Deliberately a fresh closure: it must narrow with *this* render's `select`
+  // and read *this* render's client. Its identity is free to change — React
+  // calls the latest one — while the value it returns must not, which is the
+  // observer's job.
+  const read = () => observer.readResult(client, resolved);
+  return useSyncExternalStore(subscribe, read, read);
+}
+
+/**
+ * Read a key that arrives a page at a time.
+ *
+ * One cache entry holding every page, so the list is invalidated, refetched
+ * and collected as the single thing the reader sees. See `infinite.js` for why
+ * the alternative — a query per page — cannot stay coherent.
+ */
+export function useInfiniteQuery<TPage, TParam, TSelected = InfiniteData<TPage, TParam>>(
+  options: InfiniteQueryOptions<TPage, TParam, TSelected>,
+): InfiniteQueryResult<TSelected> {
+  const client = useQueryClient();
+  const getOptions = useStableCallback(() => options);
+  const [observer] = useState(
+    () => new InfiniteQueryObserver<TPage, TParam, TSelected>(client, getOptions),
+  );
+
+  const resolved = client.resolveQuery(options as $FlowFixMe);
+  const plan = subscriptionPlan(resolved);
+  const subscribe = useCallback(
+    (listener: () => void) => observer.subscribe(client, listener),
+    [observer, client, plan],
+  );
+
+  // The paged observer's snapshot is the ordinary one with the page controls
+  // added; `readResult` is inherited, so the widening is stated here.
+  const read = () => observer.readResult(client, resolved) as InfiniteQueryResult<TSelected>;
+  return useSyncExternalStore(subscribe, read, read);
+}
+
+/**
+ * Run something that changes state, with the callbacks a rollback needs.
+ *
+ * `mutate` is called from an event, so the closure it captures is the one from
+ * the render the reader was looking at, and there is nothing to go stale.
+ * `mutateAsync` is the same call for a caller who needs to await it — the
+ * difference is only whether a failure arrives as a rejected promise or as
+ * `error` on the next render.
+ */
+export function useMutation<TVariables, TData, TContext = mixed>(
+  options: MutationOptions<TVariables, TData, TContext>,
+): MutationResult<TVariables, TData, TContext> {
+  const client = useQueryClient();
+  const getOptions = useStableCallback(() => options);
+  const [mutation] = useState(() => new Mutation<TVariables, TData, TContext>());
+
+  const subscribe = useCallback((listener: () => void) => mutation.subscribe(listener), [mutation]);
+  const read = () => mutation.state;
+  const state: MutationState<TVariables, TData> = useSyncExternalStore(subscribe, read, read);
+
+  const mutateAsync = useStableCallback(
+    (variables: TVariables, callbacks?: MutationCallbacks<TVariables, TData, TContext>) =>
+      mutation.execute(variables, client.resolveMutation(getOptions()), callbacks),
+  );
+  const mutate = useStableCallback(
+    (variables: TVariables, callbacks?: MutationCallbacks<TVariables, TData, TContext>) => {
+      // Swallowed on purpose: the failure is on the next render as `error`,
+      // and an uncaught rejection for a state the UI is already showing is
+      // noise in the console and nothing else.
+      void mutateAsync(variables, callbacks).catch(ignore);
+    },
+  );
+  const reset = useStableCallback(() => mutation.reset());
+
+  return useMemo(
+    () => ({
+      data: state.data,
+      error: state.error,
+      status: state.status,
+      variables: state.variables,
+      failureCount: state.failureCount,
+      isIdle: state.status === "idle",
+      isPending: state.status === "pending",
+      isSuccess: state.status === "success",
+      isError: state.status === "error",
+      mutate,
+      mutateAsync,
+      reset,
+    }),
+    [state, mutate, mutateAsync, reset],
+  );
+}
+
+/**
+ * What makes one subscription different from another.
+ *
+ * A string rather than a dependency array so the reason is readable at the
+ * point of failure: these are the values that change *what is being watched*.
+ * `queryFn`, `select` and `placeholderData` are deliberately absent — they
+ * change what happens when a value arrives, not whether to watch for one, and
+ * including them would resubscribe on every render for no effect.
+ */
+function subscriptionPlan<TData, TSelected>(
+  options: ResolvedQueryOptions<TData, TSelected>,
+): string {
+  return [
+    hashKey(options.queryKey),
+    String(options.enabled),
+    String(options.staleTime),
+    String(options.gcTime),
+    String(options.refetchInterval),
+    String(options.refetchOnWindowFocus),
+    String(options.refetchOnReconnect),
+  ].join("|");
+}
+
+function ignore(): void {}

package/retry.js

@@ -0,0 +1,192 @@
+// @flow
+//
+// `@uniflowed/query/retry`: trying again without making the outage worse.
+//
+// A request fails for two unrelated reasons and the difference decides
+// everything: the network dropped a packet, in which case trying again in a
+// moment works; or the server said 404, in which case trying again works
+// exactly as well as the first time and costs the same. So the policy is a
+// function of the failure, not a constant, and [`RetryPolicy`] accepts a
+// predicate for the case where only the caller can tell the two apart.
+//
+// # Why the delay grows
+//
+// The failure mode a fixed delay produces is a thundering herd: a server comes
+// back up, every client that was retrying every second hits it in the same
+// second, and it goes down again. Doubling the wait spreads the recovery out,
+// and the cap keeps a tab left open overnight from drifting into hour-long
+// silences. The default is `1s, 2s, 4s, 8s…` to thirty seconds.
+//
+// Jitter is deliberately absent. It is the right answer for a fleet of servers
+// retrying each other, and close to irrelevant for browser tabs, which are
+// already spread out by the reader's own timing; adding it here would make
+// every test of this module probabilistic in exchange for nothing measurable.
+//
+// # Why this module owns the sleeping too
+//
+// A retry loop that cannot be interrupted is a leak with a delay on it: the
+// reader has navigated away, the query is unobserved, and the loop still wakes
+// up in eight seconds to make a request nobody will read. So [`runWithRetry`]
+// takes the same `AbortSignal` the request does, and the sleep between
+// attempts rejects the moment it fires. Splitting "how long to wait" from
+// "waiting" would put the half that matters in whichever module happened to
+// call this one.
+
+/**
+ * Whether a failed attempt should be tried again.
+ *
+ * `false` never retries, `true` retries forever, a number is a count of
+ * *retries* — `2` means three attempts in total — and a predicate is given the
+ * number of failures so far and the last error, which is the only form that
+ * can tell a 500 from a 404.
+ */
+export type RetryPolicy = boolean | number | ((failureCount: number, error: Error) => boolean);
+
+/** How long to wait before the next attempt, in milliseconds. */
+export type RetryDelay = number | ((failureCount: number, error: Error) => number);
+
+/**
+ * What a cancelled request rejects with.
+ *
+ * A real class rather than a string, because the code that swallows a
+ * cancellation must not also swallow a genuine failure — telling them apart by
+ * message would break the first time someone's API said "aborted".
+ */
+export class CancelledError extends Error {
+  constructor(message: string = "the request was cancelled") {
+    super(message);
+    this.name = "CancelledError";
+  }
+}
+
+/** Doubling backoff from one second, capped at thirty. */
+export function backoffDelay(failureCount: number): number {
+  return Math.min(1000 * 2 ** (failureCount - 1), 30_000);
+}
+
+/**
+ * Run `attempt` until it succeeds, the policy gives up, or the signal fires.
+ *
+ * `onFailure` is called after every failed attempt with the running count, so
+ * the caller can put "retrying, attempt 2" on screen. It is not called for a
+ * cancellation: nobody is waiting for that answer, so there is nothing to
+ * report.
+ *
+ * The error a caller finally sees is the *last* one. An early failure that was
+ * retried past is not the reason the request failed; the one that exhausted
+ * the policy is.
+ */
+export async function runWithRetry<T>(options: {|
+  readonly attempt: (failureCount: number) => Promise<T>,
+  readonly retry: RetryPolicy,
+  readonly retryDelay: RetryDelay,
+  readonly signal: AbortSignal,
+  readonly onFailure?: (failureCount: number, error: Error) => void,
+|}): Promise<T> {
+  let failureCount = 0;
+  for (;;) {
+    if (options.signal.aborted) {
+      throw cancellation(options.signal);
+    }
+    try {
+      return await race(options.attempt, failureCount, options.signal);
+    } catch (thrown) {
+      // A request that failed *because* it was cancelled is not a failure this
+      // policy has an opinion about. Retrying it would restart work the caller
+      // just asked to stop.
+      if (options.signal.aborted) {
+        throw cancellation(options.signal);
+      }
+
+      const error = asError(thrown);
+      failureCount += 1;
+      options.onFailure?.(failureCount, error);
+      if (!shouldRetry(options.retry, failureCount, error)) {
+        throw error;
+      }
+      await sleep(delayFor(options.retryDelay, failureCount, error), options.signal);
+    }
+  }
+}
+
+/** Whatever was thrown, as an `Error`, because state has to hold one shape. */
+export function asError(thrown: mixed): Error {
+  return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+
+function shouldRetry(policy: RetryPolicy, failureCount: number, error: Error): boolean {
+  if (typeof policy === "function") {
+    return policy(failureCount, error);
+  }
+  if (typeof policy === "number") {
+    return failureCount <= policy;
+  }
+  return policy;
+}
+
+function delayFor(delay: RetryDelay, failureCount: number, error: Error): number {
+  return typeof delay === "function" ? delay(failureCount, error) : delay;
+}
+
+/**
+ * One attempt, but no longer than the caller wants to wait for it.
+ *
+ * Aborting a signal does not, on its own, settle anything: `AbortController`
+ * is a request, and a function that ignores it goes on running. So the
+ * cancellation has to be a promise of its own, raced against the attempt —
+ * otherwise cancelling a query whose function does not take a signal hangs
+ * forever, and the reader is left watching a spinner for a request nobody is
+ * waiting for.
+ *
+ * The attempt is not stopped by this; nothing can stop it. It is abandoned,
+ * and the entry's fetch id makes sure a late answer cannot write.
+ */
+async function race<T>(
+  attempt: (failureCount: number) => Promise<T>,
+  failureCount: number,
+  signal: AbortSignal,
+): Promise<T> {
+  let onAbort = () => {};
+  const cancelled: Promise<empty> = new Promise((_resolve, reject) => {
+    onAbort = () => reject(cancellation(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([attempt(failureCount), cancelled]);
+  } finally {
+    // So a signal aborted after this attempt succeeded cannot reject a promise
+    // nothing is listening to any more.
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+
+function cancellation(signal: AbortSignal): Error {
+  const reason = signal.reason;
+  return reason instanceof Error ? reason : new CancelledError();
+}
+
+/**
+ * Wait, unless the signal fires first.
+ *
+ * The timer is unreferenced where the host supports it: a process whose only
+ * remaining work is a backoff nobody is waiting for should exit, and a test
+ * that finishes while a retry is pending should not hang for eight seconds.
+ */
+function sleep(millis: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(cancellation(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(cancellation(signal));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, millis);
+    (timer as $FlowFixMe)?.unref?.();
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/structural.js

@@ -0,0 +1,131 @@
+// @flow
+//
+// `@uniflowed/query/structural`: deciding that nothing changed.
+//
+// A server that is polled every five seconds answers with the same rows and a
+// brand new object graph each time. `JSON.parse` cannot know that, so every
+// response is a fresh identity, every observer re-renders, and every memoised
+// child below it re-renders — twelve times a minute, forever, over data that
+// has not moved. That is the cost this module removes.
+//
+// [`structuralShare`] takes the value the cache holds and the value that just
+// arrived and returns a graph in which every subtree that is deeply equal is
+// the *old* reference. A response with one changed row shares every other row,
+// so a list re-renders one item instead of a thousand, and a response with no
+// changes at all returns the previous object itself — `Object.is` says so,
+// `useSyncExternalStore` bails out of the render, and `React.memo` below it
+// never runs.
+//
+// # What the obvious version gets wrong
+//
+// The comparison people reach for first is `JSON.stringify(a) === JSON.stringify(b)`.
+// It is wrong three ways, and each is a bug someone has shipped:
+//
+//   * It answers a different question. It tells you the values are equal, and
+//     then you still hand React `next` — a new identity — because you have
+//     nothing else to hand it. Equality was never the goal; *sharing* was.
+//   * It cannot share subtrees. One changed field makes the whole tree
+//     unequal, so the other nine hundred rows get new identities too.
+//   * It depends on key order, so two objects that are equal in every way that
+//     matters compare unequal because a server reordered its fields.
+//
+// The walk below is `O(size of the response)` once, with no serialisation and
+// no allocation for the parts it shares.
+//
+// # What it deliberately does not do
+//
+// Only arrays and plain objects are walked. A `Date`, a `Map`, a class
+// instance, or anything with a prototype is compared by identity and replaced
+// wholesale — because "deeply equal" for those is a question with no single
+// right answer, and guessing at it silently keeps a stale object alive. A
+// cache that holds such values still works; it just does not get sharing for
+// free inside them.
+//
+// Nothing here freezes. Freezing the graph would make the sharing enforceable,
+// and it would also freeze objects the application owns and did not consent to
+// hand over. `@uniflowed/immer` is where a value becomes structurally
+// immutable; this module only decides which references may be reused.
+
+/**
+ * Whether `value` is an object literal rather than a class instance.
+ *
+ * `Object.prototype` or a null prototype, and nothing else: the walk may only
+ * rebuild things it can rebuild faithfully, and a class instance rebuilt as an
+ * object literal has silently lost its methods.
+ */
+export function isPlainObject(value: mixed): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * `next`, with every deeply-equal subtree replaced by `previous`'s reference.
+ *
+ * Returns `previous` itself when the two are deeply equal, which is the whole
+ * point: an unchanged response must not produce a new identity, or nothing
+ * downstream can tell that it was unchanged.
+ *
+ * The shape of the *result* is always `next`'s shape. Sharing never resurrects
+ * a key that `next` dropped or a row it removed; it only reuses references for
+ * the parts that are still there and still equal.
+ */
+export function structuralShare<T>(previous: mixed, next: T): T {
+  if (previous === next) {
+    return next;
+  }
+
+  const bothArrays = Array.isArray(previous) && Array.isArray(next);
+  if (!bothArrays && !(isPlainObject(previous) && isPlainObject(next))) {
+    return next;
+  }
+
+  const before = previous as $FlowFixMe;
+  const after = next as $FlowFixMe;
+  const keys = bothArrays ? null : Object.keys(after);
+  const size = bothArrays ? after.length : (keys as $FlowFixMe).length;
+  const beforeSize = bothArrays ? before.length : Object.keys(before).length;
+  const copy = bothArrays ? new Array(size) : ({}: $FlowFixMe);
+
+  // Counted rather than tracked with a flag, because "every child was shared"
+  // is only half the answer: a child can be shared while the parent has gained
+  // or lost a sibling, and then the parent is not the same object.
+  let shared = 0;
+  for (let index = 0; index < size; index += 1) {
+    const key = bothArrays ? index : (keys as $FlowFixMe)[index];
+    const child = structuralShare(before[key], after[key]);
+    if (child === before[key] && (bothArrays || Object.hasOwn(before, key))) {
+      shared += 1;
+    }
+    copy[key] = child;
+  }
+
+  return beforeSize === size && shared === size ? (before as T) : (copy as T);
+}
+
+/**
+ * Whether two records have the same keys and `Object.is`-identical values.
+ *
+ * This is how an observer decides whether the snapshot it just built is the
+ * one it already returned. It is a *shallow* comparison on purpose: every
+ * field it compares is either a primitive or a value that already went through
+ * [`structuralShare`], so identity is the correct question and a deep walk
+ * here would be paying twice for an answer we already have.
+ */
+export function shallowEqual(left: { +[string]: mixed }, right: { +[string]: mixed }): boolean {
+  if (left === right) {
+    return true;
+  }
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) {
+    return false;
+  }
+  for (const key of keys) {
+    if (!Object.is(left[key], right[key])) {
+      return false;
+    }
+  }
+  return true;
+}