@raf-query/core 0.11.1 → 0.12.0

package/dist/keys/keys.d.mts

@@ -0,0 +1,46 @@
+//#region src/keys/keys.d.ts
+/**
+ * Keys: plain arrays, the same in memory, on the wire and in devtools.
+ * `group()` builds them; a hand-written array works too. Every key is
+ * hashed to one stable string, the entry's identity in the cache.
+ *
+ * Keys and targets (`./targets.ts`) are the seam for grouping: everything
+ * that builds or matches a key lives in this folder, so the shape of
+ * grouping can change without touching the cache.
+ */
+/** A query's key: a plain, serializable array. */
+export type QueryKey = ReadonlyArray<unknown>;
+declare const groupBrand: unique symbol;
+/**
+ * A named set of queries: those whose key starts with its path. Call it
+ * for a key under that path; a subgroup's path extends its parent's, so a
+ * group covers its subgroups and their queries.
+ */
+export interface Group<TPath extends ReadonlyArray<string> = ReadonlyArray<string>> {
+  <const TRest extends QueryKey>(...rest: TRest): readonly [...TPath, ...TRest];
+  readonly [groupBrand]: TPath;
+  /** Its parents' names and its own. */
+  readonly path: TPath;
+}
+/**
+ * A group, or a subgroup inside `parent`. Call it for a query's key: a
+ * flat, plain array that starts with the group's path. Invalidating a group
+ * covers its subgroups and every query below them.
+ *
+ * ```ts
+ * export const posts = group("posts");
+ * export const drafts = group(posts, "drafts");
+ * const draftById = (input: { id: string }) =>
+ *   queryOptions({ queryKey: drafts("byId", input), queryFn }); // ["posts", "drafts", "byId", input]
+ * await invalidateMany(client, posts); // drafts too
+ * ```
+ */
+export declare function group<const TName extends string>(name: TName): Group<readonly [TName]>;
+export declare function group<const TPath extends ReadonlyArray<string>, const TName extends string>(parent: Group<TPath>, name: TName): Group<readonly [...TPath, TName]>;
+/** Stable string form of a key: JSON with sorted fields. Functions drop out. */
+export declare function hashKey(key: QueryKey): string;
+/** Any function that returns a query's options. */
+export type AnyFactory = (input: never) => {
+  readonly queryKey: QueryKey;
+};
+//#endregion

package/dist/keys/keys.mjs

@@ -0,0 +1,53 @@
+import { isString } from "../guards.mjs";
+//#region src/keys/keys.ts
+/**
+* Keys: plain arrays, the same in memory, on the wire and in devtools.
+* `group()` builds them; a hand-written array works too. Every key is
+* hashed to one stable string, the entry's identity in the cache.
+*
+* Keys and targets (`./targets.ts`) are the seam for grouping: everything
+* that builds or matches a key lives in this folder, so the shape of
+* grouping can change without touching the cache.
+*/
+let namesUnder;
+/**
+* A subgroup and a query with one name under one parent would share a key
+* prefix, so invalidating the subgroup would reach the query. Development
+* builds throw at whichever comes second. Only keys `group()` builds are
+* checked.
+*/
+function claim(parent, name, kind) {
+	if (!isString(name)) return;
+	namesUnder ??= /* @__PURE__ */ new WeakMap();
+	const names = namesUnder.get(parent) ?? /* @__PURE__ */ new Map();
+	namesUnder.set(parent, names);
+	if ((names.get(name) ?? kind) !== kind) throw new Error(`raf-query: "${[...parent.path, name].join("/")}" is both a subgroup and a query key. Give one of them another name.`);
+	names.set(name, kind);
+}
+function group(first, name) {
+	const path = isString(first) ? [first] : [...first.path, name];
+	const self = (...rest) => {
+		if (process.env.NODE_ENV !== "production") claim(built, rest[0], "query");
+		return [...path, ...rest];
+	};
+	const built = Object.assign(self, { path: Object.freeze(path) });
+	if (process.env.NODE_ENV !== "production" && !isString(first)) claim(first, name, "group");
+	return built;
+}
+function isPlainRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function sortFields(_name, value) {
+	if (!isPlainRecord(value)) return value;
+	const sorted = {};
+	for (const name of Object.keys(value).toSorted()) sorted[name] = value[name];
+	return sorted;
+}
+/** Stable string form of a key: JSON with sorted fields. Functions drop out. */
+function hashKey(key) {
+	return JSON.stringify(key, sortFields);
+}
+//#endregion
+export { group, hashKey, isPlainRecord };

package/dist/keys/targets.d.mts

@@ -0,0 +1,56 @@
+import { AnyFactory, Group, QueryKey } from "./keys.mjs";
+import { QueryMeta } from "../root.mjs";
+//#region src/keys/targets.d.ts
+/** What a target's `where` sees of a query. */
+export interface QueryInfo<TMeta = QueryMeta> {
+  /** The query's data, before `select`; `undefined` without data. */
+  readonly data: unknown;
+  readonly input: unknown;
+  /** The `meta` its factory gave it. An entry only hydrated has `{}` until it's read. */
+  readonly meta: TMeta;
+  readonly queryKey: QueryKey;
+}
+/**
+ * Picks out queries by what they are: `where` gets each query and the
+ * parameter the verb was called with.
+ *
+ * ```ts
+ * const ownedBy: Target<AppMeta, Team> = { where: (query, team) => query.meta.owner === team };
+ * await invalidateMany(client, ownedBy, "posts-team");
+ * ```
+ */
+export interface Target<TMeta = QueryMeta, TParam = never> {
+  readonly where: (query: QueryInfo<TMeta>, param: TParam) => boolean;
+}
+/** A target of any meta and parameter. */
+export interface AnyTarget {
+  readonly where: (query: never, param: never) => boolean;
+}
+/** The arguments after a target: its parameter, if it takes one. */
+export type ParamArgs<TParam> = [TParam] extends [never] ? [] : unknown extends TParam ? [] : undefined extends TParam ? [param?: TParam] : [param: TParam];
+/** One invalidation, by what it targets. */
+export type Stamp = {
+  readonly at: number;
+  readonly kind: "all";
+} | {
+  readonly at: number;
+  readonly hash: string;
+  readonly kind: "entry";
+} | {
+  readonly at: number;
+  readonly factory: AnyFactory;
+  readonly kind: "factory";
+  readonly partial: unknown;
+} | {
+  readonly at: number;
+  readonly kind: "group";
+  readonly path: ReadonlyArray<string>;
+} | {
+  readonly at: number;
+  readonly kind: "target";
+  readonly param: unknown;
+  readonly target: AnyTarget;
+};
+/** Anything a verb can invalidate by. */
+export type AnyInvalidation = AnyFactory | AnyTarget | Group;
+//#endregion

package/dist/keys/targets.mjs

@@ -0,0 +1,85 @@
+import { isPlainRecord } from "./keys.mjs";
+//#region src/keys/targets.ts
+/**
+* Invalidation targets, and how a stamp matches an entry.
+*
+* Core knows three kinds of target:
+*
+* - A factory, matched by identity, optionally with part of its input.
+*   The partial is matched against the input the factory was called with,
+*   never against the key, so it means the same however the key is built.
+* - A group, made by `group()`: a function that builds flat keys under its
+*   path, `drafts("byId", input)` is `["posts", "drafts", "byId", input]`.
+*   It matches every key that starts with its path, whoever built the key,
+*   so it covers its subgroups and their queries.
+* - Any object with `where(query, param)`, typed by the client's root
+*   `meta`: predicates over a query's key, input, `meta` or data. Tags
+*   are one, written in user code over a `meta.tags` a feature declares.
+*
+* Invalidation records a stamp per target. An entry is invalidated when a
+* matching stamp is newer than the request its data came from. Entries with
+* readers refetch at once; the rest are checked when they are next read,
+* which always goes through their factory, so `where` sees their `meta`.
+*
+* An entry that was only hydrated has no factory or input until it's read.
+* A factory target covers it from that first read: invalidation through its
+* stamp, which outlives the call. `resetMany` and `removeMany` act at once,
+* so a factory target skips such an entry; a group still reaches it by key.
+*/
+/** Whether `actual` matches `expected`: equal, or for objects, every field `expected` has. */
+function partialMatch(actual, expected) {
+	if (Object.is(actual, expected)) return true;
+	if (Array.isArray(actual) && Array.isArray(expected)) return actual.length === expected.length && expected.every((part, index) => partialMatch(actual[index], part));
+	if (isPlainRecord(actual) && isPlainRecord(expected)) return Object.keys(expected).every((name) => partialMatch(actual[name], expected[name]));
+	return false;
+}
+/** A stamp for `target`. `arg` is a factory's partial input or a target's parameter. A `where` target may be callable too, so `where` is checked first. */
+function stampFor(target, arg, at) {
+	if ("where" in target) return {
+		at,
+		kind: "target",
+		param: arg,
+		target
+	};
+	return "path" in target ? {
+		at,
+		kind: "group",
+		path: target.path
+	} : {
+		at,
+		factory: target,
+		kind: "factory",
+		partial: arg
+	};
+}
+/** A stamp for exactly one entry. */
+function entryStamp(hash, at) {
+	return {
+		at,
+		hash,
+		kind: "entry"
+	};
+}
+function infoOf(entry) {
+	return {
+		data: entry.state.data,
+		input: entry.input,
+		meta: entry.options?.meta ?? {},
+		queryKey: entry.key
+	};
+}
+/** Whether a stamp's target covers an entry. */
+function matches(entry, stamp) {
+	switch (stamp.kind) {
+		case "all": return true;
+		case "entry": return entry.hash === stamp.hash;
+		case "factory": return entry.factory === stamp.factory && (stamp.partial === void 0 || partialMatch(entry.input, stamp.partial));
+		case "group": return stamp.path.every((segment, i) => entry.key[i] === segment);
+		case "target": {
+			const where = stamp.target.where;
+			return where(infoOf(entry), stamp.param);
+		}
+	}
+}
+//#endregion
+export { entryStamp, matches, stampFor };

package/dist/links/retry/retry.d.mts

@@ -0,0 +1,26 @@
+import { Link } from "../../client.mjs";
+//#region src/links/retry/retry.d.ts
+export interface RetryOptions {
+  /** Retries after the first attempt. A query's `meta.retry` wins. Default 3. */
+  readonly attempts?: number;
+  /** Wait before retry `n` (0-based), in ms. Default: doubling from 1 s, at most 30 s. */
+  readonly delay?: (attempt: number) => number;
+  /** Whether an error is worth retrying. Default: every error but a thrown `Response`. */
+  readonly when?: (error: unknown) => boolean;
+}
+/** What `retry()` reads from a query's `meta`. */
+export interface RetryMeta {
+  /** Attempts for this query, or `false`. */
+  readonly retry?: number | false;
+}
+/**
+ * Retry failed requests. Thrown `Response`s (router redirects and
+ * not-founds) and cancelled requests aren't retried,
+ * server clients never retry, and a browser that is offline
+ * waits until it's back online before retrying. A query sets its own
+ * attempts with `meta: { retry }`.
+ */
+export declare function retry(options?: RetryOptions): Link<{
+  readonly meta: RetryMeta;
+}>;
+//#endregion

package/dist/links/retry/retry.mjs

@@ -0,0 +1,51 @@
+import { link } from "../../client.mjs";
+import { isResponse } from "../../guards.mjs";
+//#region src/links/retry/retry.ts
+function wait(clock, ms, signal) {
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clock.clearTimeout(handle);
+			reject(signal.reason);
+		};
+		const handle = clock.setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function whenOnline(signal) {
+	if (navigator.onLine !== false) return Promise.resolve();
+	return new Promise((resolve) => {
+		window.addEventListener("online", () => resolve(), {
+			once: true,
+			signal
+		});
+	});
+}
+const defaultDelay = (attempt) => Math.min(1e3 * 2 ** attempt, 3e4);
+/** Routers throw a `Response` for a redirect or a not-found: control flow, not a failure. */
+const notThrownResponse = (error) => !isResponse(error);
+/**
+* Retry failed requests. Thrown `Response`s (router redirects and
+* not-founds) and cancelled requests aren't retried,
+* server clients never retry, and a browser that is offline
+* waits until it's back online before retrying. A query sets its own
+* attempts with `meta: { retry }`.
+*/
+function retry(options = {}) {
+	return link(async (op, next) => {
+		const configured = op.meta.retry;
+		const attempts = configured === false ? 0 : configured ?? options.attempts ?? 3;
+		if (op.client.isServer || attempts === 0) return next(op);
+		for (let attempt = 0;; attempt++) try {
+			return await next(op);
+		} catch (error) {
+			if (attempt >= attempts || op.signal.aborted || !(options.when ?? notThrownResponse)(error)) throw error;
+			await wait(op.client.clock, (options.delay ?? defaultDelay)(attempt), op.signal);
+			await whenOnline(op.signal);
+		}
+	});
+}
+//#endregion
+export { retry };

package/dist/links/timeout/timeout.d.mts

@@ -0,0 +1,9 @@
+import { Link } from "../../client.mjs";
+//#region src/links/timeout/timeout.d.ts
+/** What a request that took too long fails with. */
+export declare class QueryTimeoutError extends Error {
+  readonly name = "QueryTimeoutError";
+}
+/** Fail a request (and abort its `signal`) when it takes longer than `ms`. */
+export declare function timeout(ms: number): Link;
+//#endregion

package/dist/links/timeout/timeout.mjs

@@ -0,0 +1,27 @@
+//#region src/links/timeout/timeout.ts
+/** What a request that took too long fails with. */
+var QueryTimeoutError = class extends Error {
+	name = "QueryTimeoutError";
+};
+/** Fail a request (and abort its `signal`) when it takes longer than `ms`. */
+function timeout(ms) {
+	return (op, next) => {
+		const controller = new AbortController();
+		const signal = AbortSignal.any([op.signal, controller.signal]);
+		return new Promise((resolve, reject) => {
+			const handle = op.client.clock.setTimeout(() => {
+				const error = new QueryTimeoutError(`Query ${op.hash} took longer than ${ms} ms`);
+				controller.abort(error);
+				reject(error);
+			}, ms);
+			next({
+				...op,
+				signal
+			}).then(resolve, reject).finally(() => {
+				op.client.clock.clearTimeout(handle);
+			});
+		});
+	};
+}
+//#endregion
+export { QueryTimeoutError, timeout };

package/dist/load.d.mts

@@ -0,0 +1,124 @@
+import { DataOf, InputArgs, InputOf, KeyOf, QueryFactory } from "./options.mjs";
+import { Entry } from "./entry.mjs";
+import { QueryClient } from "./client.mjs";
+//#region src/load.d.ts
+/**
+ * A small serializable reference to a query: its key and its factory's
+ * input. It carries no data; readers get that from the cache. Handles of
+ * different factories have different types.
+ */
+export interface QueryHandle<TFactory extends QueryFactory = QueryFactory> {
+  readonly input: InputOf<TFactory>;
+  readonly queryKey: KeyOf<TFactory>;
+}
+type LoadKind = "prefetch" | "revalidate" | "swr";
+/** A query for `load` to start. Building one starts nothing. */
+export interface LoadEntry<TFactory extends QueryFactory = QueryFactory, TKind extends LoadKind = LoadKind> {
+  readonly factory: TFactory;
+  readonly input: InputOf<TFactory>;
+  readonly kind: TKind;
+  /** For paged factories: how many pages a first load fetches. */
+  readonly pages?: number;
+}
+export interface LoadEntryOptions {
+  /** For paged factories: how many pages a first load fetches. Default 1. */
+  readonly pages?: number;
+}
+type LoadEntryArgs<TFactory extends QueryFactory> = [input: InputOf<TFactory>, options?: LoadEntryOptions] | InputArgs<TFactory>;
+/**
+ * Start the query if the cache has no fresh data, and don't wait for it.
+ * It never makes the load reject: errors show up where a component reads
+ * the handle.
+ */
+export declare function prefetch<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadEntryArgs<TFactory>): LoadEntry<TFactory, "prefetch">;
+/**
+ * Use cached data even when it's stale, and wait only when the cache has
+ * none. Stale data resolves at once and refetches in the background, as
+ * HTTP's
+ * [`stale-while-revalidate`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#stale-while-revalidate)
+ * does. The load rejects if the fetch it waits for fails.
+ */
+export declare function swr<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadEntryArgs<TFactory>): LoadEntry<TFactory, "swr">;
+/**
+ * Wait for fresh data, as HTTP's
+ * [`must-revalidate`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#must-revalidate)
+ * does. Fresh cached data resolves at once without a refetch (`staleTime`
+ * is the max-age); with stale data or none it waits for the fetch. On a
+ * server client, data counts as fresh until a write invalidates it. The
+ * load rejects if the fetch fails.
+ */
+export declare function revalidate<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadEntryArgs<TFactory>): LoadEntry<TFactory, "revalidate">;
+/**
+ * In place of a `load` entry: skip the query. Its handle is `undefined` and
+ * `data` has no key for it, so a component renders its reader only when
+ * there's a handle.
+ *
+ * ```ts
+ * const [handles] = await load(queryClient, {
+ *   drafts: user.isAdmin ? prefetch(draftsQuery, { slug }) : skipToken,
+ * });
+ * ```
+ */
+export declare const skipToken: unique symbol;
+/** What `load` takes per name: an entry, or `skipToken`. */
+type LoadEntries = Record<string, LoadEntry | typeof skipToken>;
+type HandleOf<TEntry> = TEntry extends LoadEntry ? QueryHandle<TEntry["factory"]> : undefined;
+type DataOfEntry<TEntry> = TEntry extends LoadEntry ? DataOf<TEntry["factory"]> : never;
+type LoadedData<TEntries extends LoadEntries> = { [TName in keyof TEntries as TEntries[TName] extends LoadEntry<QueryFactory, "revalidate" | "swr"> ? TName : never]: DataOfEntry<TEntries[TName]>; };
+/**
+ * What `load` resolves to: a handle per entry (`undefined` for `skipToken`),
+ * and the data of `swr` and `revalidate` entries.
+ */
+export type Loaded<TEntries extends LoadEntries> = readonly [handles: { [TName in keyof TEntries]: HandleOf<TEntries[TName]>; }, data: LoadedData<TEntries>];
+/** A `load` call as devtools show it. */
+export interface LoadRecord {
+  readonly entries: ReadonlyArray<{
+    readonly hash: string;
+    readonly kind: LoadKind;
+    readonly name: string;
+  }>;
+  readonly startedAt: number;
+}
+/** The latest `load` calls on a client, newest last. Recorded in development only. */
+export declare function loadsOf(client: QueryClient): ReadonlyArray<LoadRecord>;
+/** Read an entry's data the way its readers see it: through `select`. */
+export declare function readData(entry: Entry): unknown;
+/** Start the entry's request if its data isn't fresh. Never waits. */
+export declare function startIfStale(entry: Entry): void;
+/**
+ * Start a loader's queries and return a serializable handle for each. It
+ * starts every entry before it waits for any, so the order of the entries
+ * can't create a waterfall. Resolves with `[handles, data]` once every
+ * `swr` and `revalidate` entry has data, and rejects with the error as soon
+ * as one fails.
+ * `prefetch` entries never make it reject. A `skipToken` in place of an
+ * entry starts nothing and gets no handle.
+ *
+ * ```ts
+ * const [handles, data] = await load(queryClient, {
+ *   comments: prefetch(commentsQuery, { issueId: id }),
+ *   issue: swr(issueQuery, { id }),
+ * });
+ * ```
+ */
+export declare function load<const TEntries extends LoadEntries>(client: QueryClient, entries: TEntries): Promise<Loaded<TEntries>>;
+/** Whether a handle came from `waterfallHandle()`: reading it is expected to fetch. */
+export declare function isWaterfallHandle(handle: Pick<QueryHandle, "queryKey">): boolean;
+/**
+ * The handle of a query whose input is only known while rendering, like an
+ * id in another query's data. It starts nothing: the component that reads
+ * it fetches when it renders, which makes it a request waterfall, and the
+ * name keeps that visible. Prefer starting queries in a loader with `load`.
+ *
+ * With a handle and an updater, it derives a handle from that one: the
+ * updater gets the handle's input and returns the new one (say, with a
+ * search term being typed). While the new input maps to the same query, it
+ * returns the handle as is, so readers keep it.
+ *
+ * ```ts
+ * const searchHandle = waterfallHandle(searchQuery, props.search, (input) => ({ ...input, q }));
+ * ```
+ */
+export declare function waterfallHandle<TFactory extends QueryFactory>(factory: TFactory, ...input: InputArgs<TFactory>): QueryHandle<TFactory>;
+export declare function waterfallHandle<TFactory extends QueryFactory>(factory: TFactory, handle: QueryHandle<TFactory>, update: (input: InputOf<TFactory>) => InputOf<TFactory>): QueryHandle<TFactory>;
+//#endregion

package/dist/load.mjs

@@ -0,0 +1,165 @@
+import { hashKey } from "./keys/keys.mjs";
+import { optionsOf } from "./options.mjs";
+import { entryOf, fetchEntry, isInvalidated, isStale } from "./entry.mjs";
+//#region src/load.ts
+function loadEntry(kind, factory, args) {
+	return {
+		factory,
+		input: args[0],
+		kind,
+		pages: args[1]?.pages
+	};
+}
+/**
+* Start the query if the cache has no fresh data, and don't wait for it.
+* It never makes the load reject: errors show up where a component reads
+* the handle.
+*/
+function prefetch(factory, ...args) {
+	return loadEntry("prefetch", factory, args);
+}
+/**
+* Use cached data even when it's stale, and wait only when the cache has
+* none. Stale data resolves at once and refetches in the background, as
+* HTTP's
+* [`stale-while-revalidate`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#stale-while-revalidate)
+* does. The load rejects if the fetch it waits for fails.
+*/
+function swr(factory, ...args) {
+	return loadEntry("swr", factory, args);
+}
+/**
+* Wait for fresh data, as HTTP's
+* [`must-revalidate`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#must-revalidate)
+* does. Fresh cached data resolves at once without a refetch (`staleTime`
+* is the max-age); with stale data or none it waits for the fetch. On a
+* server client, data counts as fresh until a write invalidates it. The
+* load rejects if the fetch fails.
+*/
+function revalidate(factory, ...args) {
+	return loadEntry("revalidate", factory, args);
+}
+/**
+* In place of a `load` entry: skip the query. Its handle is `undefined` and
+* `data` has no key for it, so a component renders its reader only when
+* there's a handle.
+*
+* ```ts
+* const [handles] = await load(queryClient, {
+*   drafts: user.isAdmin ? prefetch(draftsQuery, { slug }) : skipToken,
+* });
+* ```
+*/
+const skipToken = Symbol("skipToken");
+const loadRecords = /* @__PURE__ */ new WeakMap();
+/** The latest `load` calls on a client, newest last. Recorded in development only. */
+function loadsOf(client) {
+	return loadRecords.get(client) ?? [];
+}
+/** Read an entry's data the way its readers see it: through `select`. */
+function readData(entry) {
+	const select = entry.options?.select;
+	return select ? select(entry.state.data) : entry.state.data;
+}
+/** Start the entry's request if its data isn't fresh. Never waits. */
+function startIfStale(entry) {
+	if (isStale(entry) && !(entry.client.isServer && entry.state.hasData)) fetchEntry(entry);
+}
+/**
+* Whether `revalidate` can use the entry's data. A server client belongs to
+* one request, so what it fetched is fresh for that request until a write
+* invalidates it.
+*/
+function isFresh(entry) {
+	return entry.client.isServer ? entry.state.hasData && !isInvalidated(entry) : !isStale(entry);
+}
+function waitFresh(entry, pages) {
+	if (isFresh(entry)) return Promise.resolve({ ok: true });
+	return fetchEntry(entry, { pages });
+}
+function waitAny(entry, pages) {
+	if (!entry.state.hasData) return waitFresh(entry, pages);
+	startIfStale(entry);
+	return Promise.resolve({ ok: true });
+}
+/**
+* Start a loader's queries and return a serializable handle for each. It
+* starts every entry before it waits for any, so the order of the entries
+* can't create a waterfall. Resolves with `[handles, data]` once every
+* `swr` and `revalidate` entry has data, and rejects with the error as soon
+* as one fails.
+* `prefetch` entries never make it reject. A `skipToken` in place of an
+* entry starts nothing and gets no handle.
+*
+* ```ts
+* const [handles, data] = await load(queryClient, {
+*   comments: prefetch(commentsQuery, { issueId: id }),
+*   issue: swr(issueQuery, { id }),
+* });
+* ```
+*/
+async function load(client, entries) {
+	const started = Object.entries(entries).flatMap(([name, item]) => item === skipToken ? [] : [{
+		item,
+		name
+	}]).map((loaded) => {
+		const item = loaded.item;
+		const cached = entryOf(client, item.factory, item.input);
+		let wait;
+		if (item.kind === "prefetch") startIfStale(cached);
+		else wait = (item.kind === "revalidate" ? waitFresh : waitAny)(cached, item.pages);
+		return {
+			entry: cached,
+			item,
+			name: loaded.name,
+			wait
+		};
+	});
+	if (process.env.NODE_ENV !== "production") {
+		const records = loadRecords.get(client) ?? [];
+		records.push({
+			entries: started.map((one) => ({
+				hash: one.entry.hash,
+				kind: one.item.kind,
+				name: one.name
+			})),
+			startedAt: client.clock.now()
+		});
+		loadRecords.set(client, records.slice(-20));
+	}
+	const waits = started.map((one) => one.wait?.then((outcome) => {
+		if (!outcome.ok) throw outcome.error;
+	}));
+	await Promise.all(waits);
+	const handles = {};
+	const data = {};
+	for (const one of started) {
+		handles[one.name] = {
+			input: one.item.input,
+			queryKey: one.entry.key
+		};
+		if (one.wait) data[one.name] = readData(one.entry);
+	}
+	return [handles, data];
+}
+const waterfallHandles = /* @__PURE__ */ new WeakSet();
+/** Whether a handle came from `waterfallHandle()`: reading it is expected to fetch. */
+function isWaterfallHandle(handle) {
+	return waterfallHandles.has(handle);
+}
+function toHandle(factory, input) {
+	const handle = {
+		input,
+		queryKey: optionsOf(factory, input).queryKey
+	};
+	waterfallHandles.add(handle);
+	return handle;
+}
+function waterfallHandle(factory, ...args) {
+	if (args.length < 2) return toHandle(factory, args[0]);
+	const [handle, update] = args;
+	const next = toHandle(factory, update(handle.input));
+	return hashKey(next.queryKey) === hashKey(handle.queryKey) ? handle : next;
+}
+//#endregion
+export { isWaterfallHandle, load, loadsOf, prefetch, readData, revalidate, skipToken, startIfStale, swr, waterfallHandle };