@uniflowed/query 0.0.0-alpha.10

package/cache.js

@@ -0,0 +1,136 @@
+// @flow
+//
+// `@uniflowed/query/cache`: every entry, and how to say which ones you mean.
+//
+// The cache is a `Map` from a key's hash to its [`Query`], plus the vocabulary
+// for describing a *set* of entries. Those are two different jobs and this
+// module owns the second: a query knows what happened to one key, and the
+// cache knows how "everything under `["users"]` that somebody is looking at"
+// turns into a list of them.
+//
+// # Why filters are a shape rather than a list of methods
+//
+// Invalidation, cancellation, refetching and removal all need the same
+// question answered — which entries does this describe? — and they need it
+// answered identically, or `invalidateQueries` and `cancelQueries` given the
+// same argument would act on different entries. So there is one
+// [`QueryFilters`] shape and one [`findAll`], and every operation on the
+// client is that plus a verb.
+//
+// `type: "active"` is the one that carries weight. Invalidation has to refetch
+// what is on screen and merely mark the rest, because refetching an entry
+// nobody is watching is a request whose answer will be garbage-collected
+// before it is read. Without the distinction, invalidating `["users"]` in an
+// application with a hundred cached users makes a hundred requests.
+//
+// # Why the cache is explicit rather than a module-level default
+//
+// A singleton is shared with every other test in the process, and one test's
+// cached answer then decides another test's result — a class of flake that
+// costs hours to attribute because the failing test is not the one at fault.
+// It is also wrong in production: a server rendering two requests must not let
+// one reader's data reach the other. One cache per [`QueryClient`], one client
+// per tree, one tree per request.
+
+import { hashKey, matchesKey } from "./key.js";
+import type { QueryKey } from "./key.js";
+import { DEFAULT_GC_TIME, Query } from "./query.js";
+
+/**
+ * Which entries an operation applies to.
+ *
+ * Everything is optional and everything narrows: no filter at all means every
+ * entry, which is what `invalidateQueries()` with no argument means and why
+ * that call is worth writing.
+ */
+export type QueryFilters = {|
+  /** A key prefix, or an exact key with `exact`. */
+  readonly queryKey?: QueryKey,
+  readonly exact?: boolean,
+  /** `active` is "somebody is watching"; see the module docs. */
+  readonly type?: "all" | "active" | "inactive",
+  readonly predicate?: (query: Query<mixed>) => boolean,
+|};
+
+export class QueryCache {
+  readonly queries: Map<string, Query<mixed>> = new Map();
+
+  /** The entry for `hash`, if there is one. Never creates. */
+  get(hash: string): Query<mixed> | void {
+    return this.queries.get(hash);
+  }
+
+  /**
+   * The entry for `key`, creating it if it is not there.
+   *
+   * Creating is a mutation, which is why nothing on the render path calls
+   * this: a component reads with [`get`] and returns "nothing yet" when the
+   * answer is nothing yet. The entry is built in the effect that subscribes,
+   * where a mutation is allowed to happen and where React can undo it.
+   */
+  build(key: QueryKey, gcTime: number = DEFAULT_GC_TIME): Query<mixed> {
+    const hash = hashKey(key);
+    const existing = this.queries.get(hash);
+    if (existing != null) {
+      return existing;
+    }
+    const query = new Query<mixed>(this, key, gcTime);
+    this.queries.set(hash, query);
+    return query;
+  }
+
+  /**
+   * Drop `query`, if it is still the entry under its key.
+   *
+   * The identity check matters: garbage collection is scheduled on a timer,
+   * and by the time it fires the entry may already have been removed and
+   * rebuilt by a remount. Deleting by hash alone would then collect the *new*
+   * entry — with its observers, its data and its request — because an old
+   * timer said so.
+   */
+  remove(query: Query<mixed>): void {
+    if (this.queries.get(query.hash) === query) {
+      this.queries.delete(query.hash);
+    }
+    query.destroy();
+  }
+
+  /** Every entry the filter describes, in insertion order. */
+  findAll(filters?: QueryFilters): Array<Query<mixed>> {
+    const all = Array.from(this.queries.values());
+    if (filters == null) {
+      return all;
+    }
+    return all.filter((query) => matches(query, filters));
+  }
+
+  /** The first entry the filter describes. */
+  find(filters: QueryFilters): Query<mixed> | void {
+    return this.findAll(filters)[0];
+  }
+
+  /** Forget everything, cancelling anything in flight. */
+  clear(): void {
+    for (const query of Array.from(this.queries.values())) {
+      this.remove(query);
+    }
+    this.queries.clear();
+  }
+}
+
+function matches(query: Query<mixed>, filters: QueryFilters): boolean {
+  if (
+    filters.queryKey != null &&
+    !matchesKey(query.key, filters.queryKey, filters.exact === true)
+  ) {
+    return false;
+  }
+  const type = filters.type ?? "all";
+  if (type === "active" && !query.isActive()) {
+    return false;
+  }
+  if (type === "inactive" && query.isActive()) {
+    return false;
+  }
+  return filters.predicate == null || filters.predicate(query);
+}

package/client.js

@@ -0,0 +1,289 @@
+// @flow
+//
+// `@uniflowed/query/client`: the cache as something you can talk to.
+//
+// A [`QueryClient`] is the cache plus the two things a cache is useless
+// without: the application's defaults, and a vocabulary for acting on entries
+// from outside React. Everything here is callable from an event handler, a
+// route loader, a test, or a server render — nothing on this object needs a
+// component to exist.
+//
+// # Why defaults live here rather than at the call site
+//
+// `staleTime` is an application-wide decision — how long is an answer good for
+// around here — and repeating it at three hundred call sites means the three
+// hundred and first is different and nobody knows why. So the client holds
+// them and every option falls back to them, one level, with no merging of
+// nested objects to reason about.
+//
+// # Why `setQueryData` takes an updater
+//
+// The value being replaced is the one in the cache *now*, which is not
+// necessarily the one the component rendered — a background refresh may have
+// landed in between. Reading it out, changing it, and writing it back would
+// then silently discard that refresh. The updater form reads and writes in the
+// same step, and returning `undefined` from it means "on reflection, do
+// nothing", which is how an optimistic update declines to guess about an entry
+// that has since been dropped.
+//
+// # Why invalidation refetches only what is on screen
+//
+// `invalidateQueries(["users"])` in an application holding a hundred cached
+// users must not make a hundred requests. Every match is *marked* stale, so
+// whichever of them is looked at next refetches on sight; only the ones with a
+// live observer are refetched now. The distinction is what makes invalidation
+// by prefix safe to use freely, which in turn is what makes it the right way
+// to express "something about users changed".
+
+import { QueryCache } from "./cache.js";
+import type { QueryFilters } from "./cache.js";
+import { hashKey } from "./key.js";
+import type { QueryKey } from "./key.js";
+import type { QueryOptions, ResolvedQueryOptions } from "./observer.js";
+import { Presence } from "./presence.js";
+import { DEFAULT_GC_TIME } from "./query.js";
+import type { FetchContext, QueryState } from "./query.js";
+import type { MutationOptions, ResolvedMutationOptions } from "./mutation.js";
+import { backoffDelay } from "./retry.js";
+import type { RetryDelay, RetryPolicy } from "./retry.js";
+
+/** What a whole application decides once. */
+export type QueryDefaults = {|
+  readonly staleTime?: number,
+  readonly gcTime?: number,
+  readonly retry?: RetryPolicy,
+  readonly retryDelay?: RetryDelay,
+  readonly refetchInterval?: number | null,
+  readonly refetchOnWindowFocus?: boolean,
+  readonly refetchOnReconnect?: boolean,
+|};
+
+export type MutationDefaults = {|
+  readonly retry?: RetryPolicy,
+  readonly retryDelay?: RetryDelay,
+|};
+
+export type QueryClientOptions = {|
+  readonly queries?: QueryDefaults,
+  readonly mutations?: MutationDefaults,
+  /** Replaceable so React Native and tests can drive focus themselves. */
+  readonly presence?: Presence,
+|};
+
+/** What `fetchQuery` needs, which is a query without anything React-shaped. */
+export type FetchQueryOptions<TData> = {|
+  readonly queryKey: QueryKey,
+  readonly queryFn: (context: FetchContext<TData>) => Promise<TData>,
+  readonly staleTime?: number,
+  readonly gcTime?: number,
+  readonly retry?: RetryPolicy,
+  readonly retryDelay?: RetryDelay,
+|};
+
+/**
+ * Three retries with doubling backoff, five minutes of grace, fresh for no
+ * time at all.
+ *
+ * `staleTime: 0` is the conservative default and the surprising one: a mount
+ * refetches, showing the cached answer immediately and replacing it when the
+ * new one lands. Applications that know better should say so — `staleTime` is
+ * the single most valuable option on this object.
+ */
+const QUERY_DEFAULTS = {
+  staleTime: 0,
+  gcTime: DEFAULT_GC_TIME,
+  retry: (3: RetryPolicy),
+  retryDelay: (backoffDelay: RetryDelay),
+  refetchInterval: null,
+  refetchOnWindowFocus: true,
+  refetchOnReconnect: true,
+};
+
+/**
+ * Writes are not retried by default.
+ *
+ * A failed read can be repeated because reading twice is free. A failed write
+ * may well have succeeded on the server and lost its answer on the way back,
+ * and repeating it creates the second invoice. Retrying a mutation is a
+ * decision about idempotency that only the caller can make.
+ */
+const MUTATION_DEFAULTS = {
+  retry: (false: RetryPolicy),
+  retryDelay: (backoffDelay: RetryDelay),
+};
+
+export class QueryClient {
+  readonly cache: QueryCache = new QueryCache();
+  readonly presence: Presence;
+  readonly queryDefaults: typeof QUERY_DEFAULTS;
+  readonly mutationDefaults: typeof MUTATION_DEFAULTS;
+
+  constructor(options?: QueryClientOptions) {
+    this.presence = options?.presence ?? new Presence();
+    this.queryDefaults = { ...QUERY_DEFAULTS, ...stripUndefined(options?.queries) };
+    this.mutationDefaults = { ...MUTATION_DEFAULTS, ...stripUndefined(options?.mutations) };
+  }
+
+  /** The options with this client's defaults filled in. A pure function. */
+  resolveQuery<TData, TSelected>(
+    options: QueryOptions<TData, TSelected>,
+  ): ResolvedQueryOptions<TData, TSelected> {
+    const defaults = this.queryDefaults;
+    return {
+      queryKey: options.queryKey,
+      queryFn: options.queryFn,
+      enabled: options.enabled ?? true,
+      staleTime: options.staleTime ?? defaults.staleTime,
+      gcTime: options.gcTime ?? defaults.gcTime,
+      retry: options.retry ?? defaults.retry,
+      retryDelay: options.retryDelay ?? defaults.retryDelay,
+      select: options.select,
+      placeholderData: options.placeholderData,
+      refetchInterval: options.refetchInterval ?? defaults.refetchInterval,
+      refetchOnWindowFocus: options.refetchOnWindowFocus ?? defaults.refetchOnWindowFocus,
+      refetchOnReconnect: options.refetchOnReconnect ?? defaults.refetchOnReconnect,
+    };
+  }
+
+  resolveMutation<TVariables, TData, TContext>(
+    options: MutationOptions<TVariables, TData, TContext>,
+  ): ResolvedMutationOptions<TVariables, TData, TContext> {
+    return {
+      ...options,
+      retry: options.retry ?? this.mutationDefaults.retry,
+      retryDelay: options.retryDelay ?? this.mutationDefaults.retryDelay,
+    };
+  }
+
+  /**
+   * What is cached for `key`, without asking for it.
+   *
+   * `mixed`, not a generic the caller instantiates. A key is an array of
+   * strings and numbers; it carries no type, and a signature that pretended
+   * otherwise would be an unchecked cast wearing a type parameter. Narrow it
+   * where you read it, with the same schema that validated the response.
+   */
+  getQueryData(key: QueryKey): mixed {
+    return this.cache.get(hashKey(key))?.state.data;
+  }
+
+  /** Everything known about `key`, including the timestamps a result omits. */
+  getQueryState(key: QueryKey): QueryState<mixed> | void {
+    return this.cache.get(hashKey(key))?.state;
+  }
+
+  /**
+   * Put a value in, creating the entry if there is none.
+   *
+   * The write goes through structural sharing, so setting data that is deeply
+   * equal to what is there changes no identity and re-renders nothing.
+   */
+  setQueryData(key: QueryKey, updater: mixed | ((previous: mixed) => mixed)): mixed {
+    const query = this.cache.build(key, this.queryDefaults.gcTime);
+    const next =
+      typeof updater === "function" ? (updater as $FlowFixMe)(query.state.data) : updater;
+    if (next === undefined) {
+      return query.state.data;
+    }
+    return query.setData(next);
+  }
+
+  /**
+   * Fetch `key` now unless it is fresh, and hand back the answer.
+   *
+   * This is the imperative half of `useQuery`: the same cache, the same
+   * de-duplication, no component. A route loader that calls this before
+   * navigating hands the component a cache that is already warm, and the
+   * component's own mount finds nothing to do.
+   */
+  fetchQuery<TData>(options: FetchQueryOptions<TData>): Promise<mixed> {
+    const resolved = this.resolveQuery(options as $FlowFixMe);
+    const query = this.cache.build(resolved.queryKey, resolved.gcTime);
+    if (!query.isStale(resolved.staleTime)) {
+      return Promise.resolve(query.state.data);
+    }
+    return query.fetch((context) => resolved.queryFn(context as $FlowFixMe), {
+      retry: resolved.retry,
+      retryDelay: resolved.retryDelay,
+      cancelRefetch: false,
+    });
+  }
+
+  /**
+   * The same thing, for when the answer is not wanted here.
+   *
+   * Never rejects: a prefetch is an optimisation, and an optimisation that can
+   * take down the page that started it is not one. The failure is recorded on
+   * the entry, where the component that eventually reads it will find it.
+   */
+  prefetchQuery<TData>(options: FetchQueryOptions<TData>): Promise<void> {
+    return this.fetchQuery(options).then(ignore, ignore);
+  }
+
+  /**
+   * Mark matching entries stale, and refetch the ones being watched.
+   *
+   * The default filter is "everything", which is the right thing after signing
+   * in or out.
+   */
+  invalidateQueries(filters?: QueryFilters): Promise<void> {
+    for (const query of this.cache.findAll(filters)) {
+      query.invalidate();
+    }
+    return this.refetchQueries({ ...(filters ?? {}), type: "active" });
+  }
+
+  /** Refetch matching entries now. Never rejects. */
+  refetchQueries(filters?: QueryFilters): Promise<void> {
+    const matched = this.cache.findAll(filters);
+    return Promise.all(matched.map((query) => query.refetch())).then(ignore);
+  }
+
+  /**
+   * Abort matching requests and put their entries back as they were.
+   *
+   * The call an optimistic update makes first: a refetch already in flight
+   * would otherwise land after the optimistic write and replace it with the
+   * server's previous answer, which looks exactly like the mutation being
+   * undone at random.
+   */
+  cancelQueries(filters?: QueryFilters): Promise<void> {
+    for (const query of this.cache.findAll(filters)) {
+      query.cancel({ revert: true });
+    }
+    return Promise.resolve();
+  }
+
+  /** Drop matching entries entirely, cancelling anything in flight. */
+  removeQueries(filters?: QueryFilters): void {
+    for (const query of this.cache.findAll(filters)) {
+      this.cache.remove(query);
+    }
+  }
+
+  /** How many matching requests are in flight, for a global progress bar. */
+  isFetching(filters?: QueryFilters): number {
+    return this.cache.findAll(filters).filter((query) => query.state.fetchStatus === "fetching")
+      .length;
+  }
+
+  /** Forget everything. A test's `afterEach`, or a sign-out. */
+  clear(): void {
+    this.cache.clear();
+  }
+}
+
+function stripUndefined<T: { +[string]: mixed }>(source: T | void): { [string]: mixed } {
+  const out: { [string]: mixed } = {};
+  if (source == null) {
+    return out;
+  }
+  for (const name of Object.keys(source)) {
+    if (source[name] !== undefined) {
+      out[name] = source[name];
+    }
+  }
+  return out;
+}
+
+function ignore(): void {}

package/index.js

@@ -0,0 +1,158 @@
+// @flow
+//
+// `@uniflowed/query`: asking for the same thing twice should cost once.
+//
+// Server state is not application state. It is owned somewhere else, it goes
+// out of date without anybody touching it, several components want the same
+// piece of it at the same moment, and every read can fail. A `useState` beside
+// a `useEffect` models none of that, which is why every application that
+// starts with one ends up rebuilding this package badly.
+//
+// ```js
+// const client = new QueryClient({ queries: { staleTime: 30_000 } });
+//
+// component Profile(id: string) {
+//   const { data, isPending, error } = useQuery({
+//     queryKey: ["user", id],
+//     queryFn: ({ signal }) => fetch(`/users/${id}`, { signal }).then((r) => r.json()),
+//   });
+//   if (isPending) return <Spinner />;
+//   if (error != null) return <Failure error={error} />;
+//   return <Card user={data} />;
+// }
+// ```
+//
+// A header and a sidebar rendering that make one request. Navigating away and
+// back shows the profile immediately and refreshes it behind. A response that
+// is byte-identical to the cached one re-renders nothing at all.
+//
+// # The five decisions everything else follows from
+//
+// **A key is a value, not a reference.** `["user", id]` written in two files
+// is one entry, because keys are compared by their contents. `key.js`.
+//
+// **An unchanged answer is the same object.** A response is merged into the
+// cached one so that every deeply-equal subtree keeps its identity. That is
+// what makes "did anything change" an `Object.is`, which is what makes a poll
+// over unchanging data free. `structural.js`.
+//
+// **One entry, one request in flight.** Two components mounting in the same
+// tick join one request — not only for the saving, but because two requests
+// can answer in either order and the two components would then disagree.
+// `query.js`.
+//
+// **Stale is not the same as absent.** A cached answer is shown while it is
+// refreshed, so navigating back does not flash a spinner over data that is
+// already on screen. `staleTime` is the whole of the policy. `query.js`.
+//
+// **The snapshot is stable when nothing changed.** A component reads through
+// `useSyncExternalStore`, which re-renders only when the snapshot's identity
+// changes; the observer returns the *same* result object whenever every field
+// in it is unchanged. `observer.js`.
+//
+// # How the package is laid out
+//
+// Eleven modules beside this one, each named after the thing it decides. Nothing
+// is under an `internal/`: every one of them is a reasonable thing to import
+// on purpose, and hiding them would have cost a reader a directory hop to
+// reach the first line of code without making anything safer.
+//
+// The value-level leaves, which have no state and no React in them:
+//
+// - `key.js` — when two requests are the same request, and what a prefix
+//   filter matches.
+// - `structural.js` — when two answers are the same answer, and how to keep
+//   the old references for the parts that are.
+// - `retry.js` — whether to try again, how long to wait, and how to stop.
+//
+// The cache, which is a plain object graph that works with nothing rendering:
+//
+// - `query.js` — one key: its state machine, its one in-flight request, its
+//   abort signal and its collection timer.
+// - `cache.js` — every entry, and the filter vocabulary that says which ones
+//   an operation means.
+// - `mutation.js` — the write side: optimistic context, rollback, and why a
+//   write is never cancelled.
+// - `presence.js` — the tab came back; the network came back.
+// - `client.js` — the cache with the application's defaults on it, and the
+//   imperative surface: `setQueryData`, `invalidateQueries`, `prefetchQuery`,
+//   `cancelQueries`.
+//
+// The React edge:
+//
+// - `observer.js` — one component's options over one entry: the narrowing, the
+//   placeholder, and the reference-stable snapshot that decides whether a
+//   render happens at all.
+// - `infinite.js` — what a paged query changes about an ordinary one, which is
+//   only how the entry is filled.
+// - `react.js` — the provider and the four hooks, each a
+//   `useSyncExternalStore` and almost nothing else.
+//
+// `observer.js` is the one to read first if something re-renders when it
+// should not, and `query.js` if something fetches when it should not.
+//
+// # What is not here, and where it went instead
+//
+// `initialData` is absent: `client.setQueryData` before rendering is the same
+// thing with fewer rules, and the difference between initial data and
+// placeholder data is a distinction this package would rather not make people
+// learn. `placeholderData` is here, because "show the previous page while the
+// next one loads" has no other spelling.
+//
+// Suspense, offline request queues, and `client.fetchInfiniteQuery` are named
+// as out of scope in the modules that would own them, with the reason in each
+// case. A single request in flight for `useAsync` — one call, no cache — is
+// `@uniflowed/hooks`.
+
+export type { QueryFilters } from "./cache.js";
+export type {
+  FetchQueryOptions,
+  MutationDefaults,
+  QueryClientOptions,
+  QueryDefaults,
+} from "./client.js";
+export type {
+  InfiniteData,
+  InfinitePageContext,
+  InfiniteQueryOptions,
+  InfiniteQueryResult,
+  PageParamFn,
+} from "./infinite.js";
+export type { QueryKey } from "./key.js";
+export type {
+  MutationCallbacks,
+  MutationOptions,
+  MutationResult,
+  MutationState,
+  MutationStatus,
+} from "./mutation.js";
+export type { QueryOptions, QueryResult, ResolvedQueryOptions } from "./observer.js";
+export type { PresenceEvent } from "./presence.js";
+export type {
+  FetchContext,
+  FetchDirection,
+  FetchStatus,
+  Fetcher,
+  QueryState,
+  QueryStatus,
+  QueryWatcher,
+} from "./query.js";
+export type { RetryDelay, RetryPolicy } from "./retry.js";
+
+export { QueryCache } from "./cache.js";
+export { QueryClient } from "./client.js";
+export { InfiniteQueryObserver, infinitePages } from "./infinite.js";
+export { hashKey, matchesKey } from "./key.js";
+export { Mutation } from "./mutation.js";
+export { QueryObserver } from "./observer.js";
+export { Presence } from "./presence.js";
+export { DEFAULT_GC_TIME, Query } from "./query.js";
+export {
+  QueryClientProvider,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from "./react.js";
+export { CancelledError, backoffDelay } from "./retry.js";
+export { structuralShare } from "./structural.js";