@uniflowed/query 0.0.0-alpha.2

package/index.js

@@ -0,0 +1,25 @@
+// @flow
+//
+// `@uniflowed/query`: asking for the same thing twice should cost once.
+//
+// Three behaviours an application writes by hand around `fetch` and gets
+// wrong, and which are the reason a query library exists at all:
+//
+//   * **De-duplication.** A header and a sidebar both showing the current user
+//     make one request, not two, and cannot disagree about the answer.
+//   * **Stale-while-revalidate.** A cached value is shown at once and
+//     refreshed behind it, so navigating back does not flash a spinner over
+//     data that is already there.
+//   * **Invalidation by prefix.** After creating a user, `["users"]`
+//     invalidates `["users", 1]` and `["users", 2]` without listing them.
+//
+// The cache is a plain object graph with no React in it, and `useQuery` is a
+// `useSyncExternalStore` over it — so a value is correct during a prerender,
+// two components reading one key cannot render different versions of it, and
+// the cache is testable without rendering anything.
+
+export type { Entry, QueryKey } from "./internal/cache.js";
+export type { MutationResult, QueryOptions, QueryResult } from "./internal/react.js";
+
+export { QueryCache, hash } from "./internal/cache.js";
+export { QueryProvider, useMutation, useQuery, useQueryCache } from "./internal/react.js";

package/internal/cache.js

@@ -0,0 +1,280 @@
+// @flow
+//
+// The cache a query reads from, and who else is reading it.
+//
+// This is the part that makes a query library worth having rather than a
+// `useEffect` and a `useState`:
+//
+//   * **Two components asking for the same thing make one request.** Without
+//     that, a page with a header and a sidebar both showing the current user
+//     fetches the user twice, and they can disagree.
+//   * **A cached answer is shown immediately and refreshed behind it.** The
+//     alternative is a spinner every time a reader navigates back, which is
+//     the single most common way an application feels slow while being fast.
+//   * **An answer that is old enough is refetched; one that is merely used is
+//     not.** Those are different questions, and conflating them either
+//     hammers the server or shows stale data forever.
+//
+// The store is deliberately not React-aware: it is a map, a set of listeners
+// per key, and a promise per in-flight request. `useQuery` is a
+// `useSyncExternalStore` over it, which is what makes a cached value correct
+// during a prerender and free of tearing on the client.
+
+/** A key, as a caller writes it. */
+export type QueryKey = $ReadOnlyArray<mixed>;
+
+/** What the cache holds for one key. */
+export type Entry<T> = {|
+  readonly value: T | void,
+  readonly error: Error | null,
+  /** When the value arrived, so staleness is a question the reader can ask. */
+  readonly updatedAt: number,
+  readonly pending: boolean,
+  /** Bumped on every change, so a snapshot can be compared by identity. */
+  readonly version: number,
+|};
+
+type Slot = {
+  entry: Entry<mixed>,
+  listeners: Set<() => void>,
+  inFlight: Promise<mixed> | null,
+  /** Cleared when the last listener goes and the entry has outlived its use. */
+  collect: TimeoutID | null,
+  /**
+   * How to fetch this key again, recorded by `watch`.
+   *
+   * Without it, invalidation can only mark an entry stale — and a component
+   * already watching would re-render, see that it is stale, and do nothing,
+   * because nothing was asked to fetch. Keeping the query here is what lets
+   * the store refresh what somebody is looking at.
+   */
+  query: (() => Promise<mixed>) | null,
+};
+
+/** How long an unused entry is kept, so a quick navigation back is free. */
+const DEFAULT_GARBAGE_MILLIS = 5 * 60_000;
+
+const EMPTY: Entry<mixed> = {
+  value: undefined,
+  error: null,
+  updatedAt: 0,
+  pending: false,
+  version: 0,
+};
+
+/**
+ * A cache. An application usually has one, and a test has one per test.
+ *
+ * Explicit rather than a module-level singleton, because a singleton is shared
+ * with every other test in the process and one test's cached answer then
+ * decides another's result.
+ */
+export class QueryCache {
+  readonly slots: Map<string, Slot> = new Map();
+  readonly garbageMillis: number;
+
+  constructor(options?: {| readonly garbageMillis?: number |}) {
+    this.garbageMillis = options?.garbageMillis ?? DEFAULT_GARBAGE_MILLIS;
+  }
+
+  /** What is known about `key` right now. */
+  read(key: QueryKey): Entry<mixed> {
+    return this.slots.get(hash(key))?.entry ?? EMPTY;
+  }
+
+  /** Watch `key`. Returns the unsubscribe. */
+  subscribe(key: QueryKey, listener: () => void): () => void {
+    const id = hash(key);
+    const slot = this.slot(id);
+    slot.listeners.add(listener);
+    if (slot.collect != null) {
+      clearTimeout(slot.collect);
+      slot.collect = null;
+    }
+    return () => {
+      slot.listeners.delete(listener);
+      this.maybeCollect(id);
+    };
+  }
+
+  /**
+   * Watch `key`, and keep it fresh while anybody is watching.
+   *
+   * Subscribing *is* the signal that a value is wanted, so the fetch belongs
+   * here rather than in an effect beside it. That is what lets `useQuery` be a
+   * plain `useSyncExternalStore` over this store — no effect to trigger the
+   * request, no ref to hold the latest query function, and no dependency array
+   * to argue with. The store owns its own freshness, which is what an external
+   * store is for.
+   *
+   * The query function is captured per subscription, which is per key: a
+   * component re-rendering with a new closure does not re-subscribe, and the
+   * request for a given key does not change meaning between renders.
+   */
+  watch<T>(
+    key: QueryKey,
+    query: () => Promise<T>,
+    options: {| readonly listener: () => void, readonly staleTime: number |},
+  ): () => void {
+    const id = hash(key);
+    const slot = this.slot(id);
+    slot.query = query as $FlowFixMe;
+
+    const unsubscribe = this.subscribe(key, options.listener);
+    if (this.isStale(key, options.staleTime)) {
+      // The rejection is recorded on the entry, and every watcher is told.
+      // Letting it reach the console as well would report it twice.
+      this.fetch(key, query).catch(() => {});
+    }
+    return unsubscribe;
+  }
+
+  /**
+   * Run `query` for `key`, or join the request already in flight.
+   *
+   * The de-duplication is the whole point: two components mounting in the same
+   * tick both call this, and one request is made.
+   */
+  fetch<T>(key: QueryKey, query: () => Promise<T>): Promise<T> {
+    const id = hash(key);
+    const slot = this.slot(id);
+    if (slot.inFlight != null) {
+      return slot.inFlight as $FlowFixMe;
+    }
+
+    this.write(id, { pending: true });
+    const promise = query().then(
+      (value) => {
+        slot.inFlight = null;
+        this.write(id, { value, error: null, updatedAt: now(), pending: false });
+        return value;
+      },
+      (thrown) => {
+        slot.inFlight = null;
+        const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+        // The previous value is kept beside the error. A failed refresh should
+        // not blank a page that was showing something.
+        this.write(id, { error, pending: false });
+        throw error;
+      },
+    );
+    slot.inFlight = promise;
+    return promise;
+  }
+
+  /** Whether `key`'s value is older than `millis`. */
+  isStale(key: QueryKey, millis: number): boolean {
+    const entry = this.read(key);
+    if (entry.updatedAt === 0) {
+      return true;
+    }
+    return now() - entry.updatedAt >= millis;
+  }
+
+  /** Put a value in without running a query, for an optimistic update. */
+  set<T>(key: QueryKey, value: T): void {
+    this.write(hash(key), { value, error: null, updatedAt: now(), pending: false });
+  }
+
+  /**
+   * Mark matching keys stale so their watchers refetch.
+   *
+   * A key *prefix* matches, because that is how invalidation is actually
+   * expressed: after a mutation, `["users"]` should refresh `["users", 1]` and
+   * `["users", 2]` without the caller listing them.
+   */
+  invalidate(prefix: QueryKey): void {
+    const wanted = hash(prefix);
+    for (const [id, slot] of Array.from(this.slots)) {
+      if (id !== wanted && !id.startsWith(`${wanted.slice(0, -1)},`)) {
+        continue;
+      }
+      // `updatedAt: 0` is "never fetched", which is what makes every reader
+      // treat it as stale without inventing a separate flag.
+      this.write(id, { updatedAt: 0 });
+
+      // And refetch what somebody is looking at. Marking it stale alone would
+      // leave a mounted component re-rendering, seeing that it is stale, and
+      // doing nothing — the freshness is this store's job, not the
+      // component's.
+      const query = slot.query;
+      if (query != null && slot.listeners.size > 0) {
+        this.fetch(JSON.parse(id), query).catch(() => {});
+      }
+    }
+  }
+
+  /** Forget everything. */
+  clear(): void {
+    for (const slot of this.slots.values()) {
+      if (slot.collect != null) {
+        clearTimeout(slot.collect);
+      }
+    }
+    this.slots.clear();
+  }
+
+  slot(id: string): Slot {
+    let slot = this.slots.get(id);
+    if (slot == null) {
+      slot = {
+        entry: EMPTY,
+        listeners: new Set(),
+        inFlight: null,
+        collect: null,
+        query: null,
+      };
+      this.slots.set(id, slot);
+    }
+    return slot;
+  }
+
+  write(id: string, patch: { readonly [string]: mixed }): void {
+    const slot = this.slot(id);
+    slot.entry = {
+      ...slot.entry,
+      ...patch,
+      version: slot.entry.version + 1,
+    } as $FlowFixMe;
+    for (const listener of Array.from(slot.listeners)) {
+      if (slot.listeners.has(listener)) {
+        listener();
+      }
+    }
+  }
+
+  maybeCollect(id: string): void {
+    const slot = this.slots.get(id);
+    if (slot == null || slot.listeners.size > 0 || slot.collect != null) {
+      return;
+    }
+    // Kept for a while after the last watcher goes: navigating away and back
+    // is the common case, and it should not cost a request.
+    slot.collect = setTimeout(() => {
+      const current = this.slots.get(id);
+      if (current != null && current.listeners.size === 0) {
+        this.slots.delete(id);
+      }
+    }, this.garbageMillis);
+    // A timer must not hold the process open — a test that finishes before the
+    // collection is due should still exit.
+    if (typeof (slot.collect as $FlowFixMe)?.unref === "function") {
+      (slot.collect as $FlowFixMe).unref();
+    }
+  }
+}
+
+/**
+ * A key as a string.
+ *
+ * `JSON.stringify` of the array, so `["users", 1]` and `["users", "1"]` are
+ * different keys — they are different requests, and treating them as one is a
+ * bug that shows up as the wrong data rather than as an error.
+ */
+export function hash(key: QueryKey): string {
+  return JSON.stringify(key);
+}
+
+function now(): number {
+  return Date.now();
+}

package/internal/react.js

@@ -0,0 +1,181 @@
+// @flow
+//
+// The React binding: `useQuery`, `useMutation`, and the provider they read.
+//
+// Deliberately thin. The cache is an external store, so `useQuery` is a
+// `useSyncExternalStore` over it and nothing else — no effect to trigger the
+// request, no ref holding the latest query function, no dependency array to
+// argue with. Subscribing is the signal that a value is wanted, so keeping it
+// fresh is the store's job; the component only reads.
+//
+// That is not a stylistic preference. A component that reads an external store
+// through the API React provides for it gets the value React commits with,
+// which is what stops two components sharing a key from rendering different
+// versions of it, and it states the server's value rather than falling through
+// to it.
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "@uniflowed/react";
+
+import { useStableCallback } from "@uniflowed/hooks";
+
+import { QueryCache, hash } from "./cache.js";
+import type { Entry, QueryKey } from "./cache.js";
+
+const CacheContext: React.Context<QueryCache | null> = createContext(null);
+
+/**
+ * Make a cache available to the tree.
+ *
+ * Required rather than falling back to a module-level default: a default is
+ * shared with every test in the process, and one test's cached answer then
+ * decides another's result.
+ */
+export component QueryProvider(cache: QueryCache, children: React.Node) {
+  return <CacheContext.Provider value={cache}>{children}</CacheContext.Provider>;
+}
+
+/** The cache this subtree uses. */
+export function useQueryCache(): QueryCache {
+  const cache = useContext(CacheContext);
+  if (cache == null) {
+    throw new Error(
+      "useQuery needs a QueryProvider above it; render <QueryProvider cache={new QueryCache()}>",
+    );
+  }
+  return cache;
+}
+
+/** What a query looks like to a component. */
+export type QueryResult<T> = {|
+  readonly value: T | void,
+  readonly error: Error | null,
+  /** A request is in flight. True on the first load and on a refresh. */
+  readonly pending: boolean,
+  /** There has never been a value, so there is nothing to show yet. */
+  readonly loading: boolean,
+  /** The value is older than `staleTime`. */
+  readonly stale: boolean,
+  readonly refetch: () => Promise<T>,
+|};
+
+/** How a query behaves. */
+export type QueryOptions = {|
+  /** How long a value is fresh. Defaults to none, so a mount refetches. */
+  readonly staleTime?: number,
+|};
+
+/**
+ * Read `key`, fetching it when it is missing or stale.
+ *
+ * A cached value is returned immediately and refreshed behind it, so
+ * navigating back to a page shows it at once. `pending` says a request is in
+ * flight; `loading` says there is nothing to show yet — conflating those is
+ * why applications flash a spinner over data they already have.
+ */
+export function useQuery<T>(
+  key: QueryKey,
+  query: () => Promise<T>,
+  options?: QueryOptions,
+): QueryResult<T> {
+  const cache = useQueryCache();
+  const staleTime = options?.staleTime ?? 0;
+
+  // The key's identity is its hash. A caller writes the array inline, so
+  // depending on the array itself would resubscribe on every render; two
+  // arrays with the same hash are the same request by definition, so holding
+  // the first one is not a stale closure.
+  const id = hash(key);
+  const stable = useMemo(() => key, [id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // The query is something to *call*, not something to react to. React's own
+  // answer for that is an effect event — a function whose identity never
+  // changes and whose body is always the latest — and without it `subscribe`
+  // would change every render and `useSyncExternalStore` would resubscribe
+  // every render.
+  const fetcher = useStableCallback(query);
+
+  const subscribe = useCallback(
+    (listener: () => void) => cache.watch(stable, fetcher, { listener, staleTime }),
+    [cache, stable, fetcher, staleTime],
+  );
+
+  const snapshot = useCallback(() => cache.read(stable), [cache, stable]);
+  const entry: Entry<mixed> = useSyncExternalStore(subscribe, snapshot, snapshot);
+
+  const refetch = useCallback(() => cache.fetch(stable, fetcher), [cache, stable, fetcher]);
+
+  return useMemo(
+    () => ({
+      value: entry.value as $FlowFixMe,
+      error: entry.error,
+      pending: entry.pending,
+      loading: entry.pending && entry.updatedAt === 0,
+      stale: entry.updatedAt === 0 || Date.now() - entry.updatedAt >= staleTime,
+      refetch: refetch as $FlowFixMe,
+    }),
+    [entry, staleTime, refetch],
+  );
+}
+
+/** What a mutation looks like to a component. */
+export type MutationResult<TInput, TOutput> = {|
+  readonly run: (input: TInput) => Promise<TOutput>,
+  readonly value: TOutput | void,
+  readonly error: Error | null,
+  readonly pending: boolean,
+|};
+
+/**
+ * Run something that changes state, and invalidate what it affected.
+ *
+ * `run` is called from an event, so the closure it captures is the one from
+ * the render the reader was looking at — there is no ref holding a "latest"
+ * anything, and nothing to go stale. Nor is there a guard against settling
+ * after unmount: React has not warned about that since 18, and adding one
+ * would only hide a real leak if there were one.
+ *
+ * `invalidates` takes key prefixes, because that is how invalidation is
+ * expressed: creating a user refreshes `["users"]` and every `["users", id]`
+ * under it without the caller listing them.
+ */
+export function useMutation<TInput, TOutput>(
+  mutation: (input: TInput) => Promise<TOutput>,
+  options?: {| readonly invalidates?: $ReadOnlyArray<QueryKey> |},
+): MutationResult<TInput, TOutput> {
+  const cache = useQueryCache();
+  const [state, setState] = useState<{|
+    value: TOutput | void,
+    error: Error | null,
+    pending: boolean,
+  |}>({ value: undefined, error: null, pending: false });
+
+  const run = async (input: TInput): Promise<TOutput> => {
+    setState((current) => ({ ...current, pending: true, error: null }));
+    try {
+      const value = await mutation(input);
+      setState({ value, error: null, pending: false });
+      // After it settles, so a watcher refetching sees the change rather than
+      // racing it.
+      for (const prefix of options?.invalidates ?? []) {
+        cache.invalidate(prefix);
+      }
+      return value;
+    } catch (thrown) {
+      const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+      setState({ value: undefined, error, pending: false });
+      // Rethrown: a caller awaiting `run` has to be able to tell that it
+      // failed, and the failure state alone would not let it.
+      throw error;
+    }
+  };
+
+  return { run, value: state.value, error: state.error, pending: state.pending };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@uniflowed/query",
+  "version": "0.0.0-alpha.2",
+  "description": "A query cache with de-duplication and stale-while-revalidate, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/query"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "internal"
+  ],
+  "dependencies": {
+    "@uniflowed/hooks": "0.0.0-alpha.2",
+    "@uniflowed/react": "0.0.0-alpha.2"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  }
+}