@raf-query/core 0.11.1 → 0.13.0

package/dist/infinite/infinite.mjs

@@ -0,0 +1,120 @@
+import { hashKey } from "../keys/keys.mjs";
+//#region src/infinite/infinite.ts
+/**
+* Typed options for a paged query factory. Readers get `{ pages, pageParams }`
+* and, on their state, `fetchNextPage` and `fetchPreviousPage`:
+*
+* ```ts
+* export const commentsQuery = (input: { slug: string }) =>
+*   infiniteQueryOptions({
+*     queryKey: comments(input.slug),
+*     queryFn: ({ pageParam, signal }) => listComments({ ...input, cursor: pageParam }, { signal }),
+*     initialPageParam: 0,
+*     getNextPageParam: (lastPage) => lastPage.nextCursor,
+*   });
+* ```
+*
+* Its `meta` is any record. To check `meta` against a client's links and
+* features, use the builder {@link bindInfiniteQueryOptions} returns.
+*
+* @see https://raf-query.katt.dev/docs/infinite-queries
+*/
+const infiniteQueryOptions = (options) => ({
+	...options,
+	"~run": (op) => runPages(op, options)
+});
+/**
+* `infiniteQueryOptions` bound to a root, like `bindQueryOptions`. Bind it
+* next to `queryOptions`, in apps that page:
+*
+* ```ts
+* // raf.ts
+* export const infiniteQueryOptions = bindInfiniteQueryOptions<typeof makeQueryClient>();
+* ```
+*
+* @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
+*/
+function bindInfiniteQueryOptions() {
+	return infiniteQueryOptions;
+}
+/** The param of the page after (or before) `data`, or `undefined` at the end. */
+function pageParamAfter(options, data, direction) {
+	const forward = direction === "next";
+	const index = forward ? data.pages.length - 1 : 0;
+	const page = data.pages[index];
+	const getParam = forward ? options.getNextPageParam : options.getPreviousPageParam;
+	if (page === void 0 || !getParam) return;
+	return getParam(page, data.pages, data.pageParams[index]) ?? void 0;
+}
+/**
+* The entry's data as it is now, which writes may have changed since `op`
+* started, or `fallback` while it has none.
+*/
+function latest(op, fallback) {
+	const state = op.client["~entries"].get(op.hash)?.state;
+	return state?.hasData ? state.data : fallback;
+}
+function sameParam(a, b) {
+	return hashKey([a]) === hashKey([b]);
+}
+/** The page `data` holds for `pageParam`, if any. */
+function pageFor(data, pageParam) {
+	const index = data?.pageParams.findIndex((param) => sameParam(param, pageParam)) ?? -1;
+	return index === -1 ? void 0 : data?.pages[index];
+}
+async function runPages(op, source) {
+	const fetchPage = (pageParam, direction) => Promise.resolve(source.queryFn({
+		client: op.client,
+		direction,
+		meta: op.meta,
+		pageParam,
+		queryKey: op.queryKey,
+		signal: op.signal
+	}));
+	const previous = op.hasData ? op.data : void 0;
+	const direction = op.direction;
+	if (previous && direction) {
+		const pageParam = pageParamAfter(source, previous, direction);
+		if (pageParam === void 0) return previous;
+		const page = await fetchPage(pageParam, direction === "next" ? "forward" : "backward");
+		const current = latest(op, previous);
+		const edge = (data) => direction === "next" ? data.pageParams.at(-1) : data.pageParams[0];
+		if (!sameParam(edge(current), edge(previous))) return current;
+		const max = source.maxPages ?? Infinity;
+		return direction === "next" ? {
+			pageParams: [...current.pageParams, pageParam].slice(-max),
+			pages: [...current.pages, page].slice(-max)
+		} : {
+			pageParams: [pageParam, ...current.pageParams].slice(0, max),
+			pages: [page, ...current.pages].slice(0, max)
+		};
+	}
+	const count = previous?.pages.length ?? op.pages ?? 1;
+	const pages = [];
+	const pageParams = [];
+	/** The page the entry held for each param when that page's read started. */
+	const before = [];
+	let pageParam = previous?.pageParams[0] ?? source.initialPageParam;
+	while (pages.length < count) {
+		before.push(pageFor(latest(op, void 0), pageParam));
+		const page = await fetchPage(pageParam, "forward");
+		pages.push(page);
+		pageParams.push(pageParam);
+		const next = pageParamAfter(source, {
+			pageParams,
+			pages
+		}, "next");
+		if (next === void 0) break;
+		pageParam = next;
+	}
+	const now = latest(op, void 0);
+	return {
+		pageParams,
+		pages: pages.map((page, index) => {
+			const written = pageFor(now, pageParams[index]);
+			return written !== void 0 && written !== before[index] ? written : page;
+		})
+	};
+}
+//#endregion
+export { bindInfiniteQueryOptions, infiniteQueryOptions, pageParamAfter };

package/dist/infinite/paging.d.mts

@@ -0,0 +1,71 @@
+import { InfiniteQueryFactory, InputArgs } from "../options.mjs";
+import { Entry, EntryState } from "../entry.mjs";
+import { ClientFor } from "../verbs.mjs";
+//#region src/infinite/paging.d.ts
+/**
+ * Which way a page loads: after the last one, or before the first.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#reading-pages
+ */
+export type PageDirection = "next" | "previous";
+/**
+ * Where a paged query can load more, and what it's loading now.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#reading-pages
+ */
+export interface PageState {
+  readonly hasNextPage: boolean;
+  readonly hasPreviousPage: boolean;
+  readonly isFetchingNextPage: boolean;
+  readonly isFetchingPreviousPage: boolean;
+}
+/**
+ * A paged query's {@link PageState} and the requests that load more:
+ * `useInfiniteQuery`'s paging controls.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#reading-pages
+ */
+export interface PageControls extends PageState {
+  /** Load the page after the last one. Resolves when it's there. */
+  fetchNextPage(): Promise<void>;
+  /** Load the page before the first one. Resolves when it's there. */
+  fetchPreviousPage(): Promise<void>;
+}
+/** A paged entry's {@link PageState}, from `state` (the entry's own by default). */
+export declare function pageState(entry: Entry, state?: EntryState): PageState;
+/**
+ * Load a paged entry's page in `direction`; resolves when the request
+ * settles, and does nothing without a page at that end. An error stays in
+ * the entry's state.
+ */
+export declare function fetchPage(entry: Entry, direction: PageDirection): Promise<void>;
+/**
+ * Load the page after the last one of a paged query, as `useInfiniteQuery`'s
+ * `fetchNextPage()` does. Resolves when the page is there, or the request
+ * settles; does nothing without a next page.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+ */
+export declare function fetchNextPage<TFactory extends InfiniteQueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): Promise<void>;
+/**
+ * Load the page before the first one of a paged query, as
+ * `useInfiniteQuery`'s `fetchPreviousPage()` does. See {@link fetchNextPage}.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+ */
+export declare function fetchPreviousPage<TFactory extends InfiniteQueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): Promise<void>;
+/**
+ * Whether a paged query has a page after its last one: `false` while it has
+ * no data, or once `getNextPageParam` returns `undefined`.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+ */
+export declare function hasNextPage<TFactory extends InfiniteQueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): boolean;
+/**
+ * Whether a paged query has a page before its first one. See
+ * {@link hasNextPage}.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+ */
+export declare function hasPreviousPage<TFactory extends InfiniteQueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): boolean;
+//#endregion

package/dist/infinite/paging.mjs

@@ -0,0 +1,62 @@
+import { entryOf, fetchEntry } from "../entry.mjs";
+import { pageParamAfter } from "./infinite.mjs";
+//#region src/infinite/paging.ts
+function hasPage(entry, state, direction) {
+	return state.hasData && pageParamAfter(entry.options, state.data, direction) !== void 0;
+}
+/** A paged entry's {@link PageState}, from `state` (the entry's own by default). */
+function pageState(entry, state = entry.state) {
+	return {
+		hasNextPage: hasPage(entry, state, "next"),
+		hasPreviousPage: hasPage(entry, state, "previous"),
+		isFetchingNextPage: state.fetchingDirection === "next",
+		isFetchingPreviousPage: state.fetchingDirection === "previous"
+	};
+}
+/**
+* Load a paged entry's page in `direction`; resolves when the request
+* settles, and does nothing without a page at that end. An error stays in
+* the entry's state.
+*/
+function fetchPage(entry, direction) {
+	return fetchEntry(entry, { direction }).then(() => {});
+}
+/**
+* Load the page after the last one of a paged query, as `useInfiniteQuery`'s
+* `fetchNextPage()` does. Resolves when the page is there, or the request
+* settles; does nothing without a next page.
+*
+* @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+*/
+function fetchNextPage(client, factory, ...input) {
+	return fetchPage(entryOf(client, factory, input[0]), "next");
+}
+/**
+* Load the page before the first one of a paged query, as
+* `useInfiniteQuery`'s `fetchPreviousPage()` does. See {@link fetchNextPage}.
+*
+* @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+*/
+function fetchPreviousPage(client, factory, ...input) {
+	return fetchPage(entryOf(client, factory, input[0]), "previous");
+}
+/**
+* Whether a paged query has a page after its last one: `false` while it has
+* no data, or once `getNextPageParam` returns `undefined`.
+*
+* @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+*/
+function hasNextPage(client, factory, ...input) {
+	return pageState(entryOf(client, factory, input[0])).hasNextPage;
+}
+/**
+* Whether a paged query has a page before its first one. See
+* {@link hasNextPage}.
+*
+* @see https://raf-query.katt.dev/docs/infinite-queries#outside-react
+*/
+function hasPreviousPage(client, factory, ...input) {
+	return pageState(entryOf(client, factory, input[0])).hasPreviousPage;
+}
+//#endregion
+export { fetchNextPage, fetchPage, fetchPreviousPage, hasNextPage, hasPreviousPage, pageState };

package/dist/internal.d.mts

@@ -0,0 +1,13 @@
+import { AnyFactory, hashKey } from "./keys/keys.mjs";
+import { Decl, DefaultTypes, MetaOf, RootOf, RootTypes } from "./root.mjs";
+import { AnyTarget } from "./keys/targets.mjs";
+import { fulfilled, mapThenable, pending, rejected } from "./thenable.mjs";
+import { Entry, EntryState, entryOf, fetchEntry, isBrowserOnly, isInvalidated, isStale, remove, reset, subscribeEntry } from "./entry.mjs";
+import { AnyFeature, AnyLink, ClientEvent, mount, systemClock } from "./client.mjs";
+import { FocusRefetchMeta } from "./features/focus-refetch/focus-refetch.mjs";
+import { ReconnectRefetchMeta } from "./features/reconnect-refetch/reconnect-refetch.mjs";
+import { PollingMeta } from "./features/polling/polling.mjs";
+import { fetchPage, pageState } from "./infinite/paging.mjs";
+import { RetryMeta } from "./links/retry/retry.mjs";
+import { LoadRecord, isWaterfallHandle, loadsOf, readData, startIfStale } from "./load.mjs";
+export { type AnyFactory, type AnyFeature, type AnyLink, type AnyTarget, type ClientEvent, type Decl, type DefaultTypes, type Entry, type EntryState, type FocusRefetchMeta, type LoadRecord, type MetaOf, type PollingMeta, type ReconnectRefetchMeta, type RetryMeta, type RootOf, type RootTypes, entryOf, fetchEntry, fetchPage, fulfilled, hashKey, isBrowserOnly, isInvalidated, isStale, isWaterfallHandle, loadsOf, mapThenable, mount, pageState, pending, readData, rejected, remove, reset, startIfStale, subscribeEntry, systemClock };

package/dist/internal.mjs

@@ -0,0 +1,7 @@
+import { mount, systemClock } from "./client.mjs";
+import { hashKey } from "./keys/keys.mjs";
+import { fulfilled, mapThenable, pending, rejected } from "./thenable.mjs";
+import { entryOf, fetchEntry, isBrowserOnly, isInvalidated, isStale, remove, reset, subscribeEntry } from "./entry.mjs";
+import { fetchPage, pageState } from "./infinite/paging.mjs";
+import { isWaterfallHandle, loadsOf, readData, startIfStale } from "./load.mjs";
+export { entryOf, fetchEntry, fetchPage, fulfilled, hashKey, isBrowserOnly, isInvalidated, isStale, isWaterfallHandle, loadsOf, mapThenable, mount, pageState, pending, readData, rejected, remove, reset, startIfStale, subscribeEntry, systemClock };

package/dist/keys/keys.d.mts

@@ -0,0 +1,54 @@
+//#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.
+ *
+ * @see https://raf-query.katt.dev/docs/query-keys
+ */
+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.
+ *
+ * @see https://raf-query.katt.dev/docs/query-keys#groups
+ */
+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
+ * ```
+ *
+ * @see https://raf-query.katt.dev/docs/query-keys#groups
+ */
+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,62 @@
+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.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#matching-with-where
+ */
+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, "editorial");
+ * ```
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#targets
+ */
+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,33 @@
+import { Link } from "../../client.mjs";
+//#region src/links/retry/retry.d.ts
+/**
+ * Options for {@link retry}.
+ *
+ * @see https://raf-query.katt.dev/docs/retries#options
+ */
+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 }`.
+ *
+ * @see https://raf-query.katt.dev/docs/retries
+ */
+export declare function retry(options?: RetryOptions): Link<{
+  readonly meta: RetryMeta;
+}>;
+//#endregion

package/dist/links/retry/retry.mjs

@@ -0,0 +1,53 @@
+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 }`.
+*
+* @see https://raf-query.katt.dev/docs/retries
+*/
+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,17 @@
+import { Link } from "../../client.mjs";
+//#region src/links/timeout/timeout.d.ts
+/**
+ * What a request that took too long fails with.
+ *
+ * @see https://raf-query.katt.dev/docs/retries#timeouts
+ */
+export declare class QueryTimeoutError extends Error {
+  readonly name = "QueryTimeoutError";
+}
+/**
+ * Fail a request (and abort its `signal`) when it takes longer than `ms`.
+ *
+ * @see https://raf-query.katt.dev/docs/retries#timeouts
+ */
+export declare function timeout(ms: number): Link;
+//#endregion

package/dist/links/timeout/timeout.mjs

@@ -0,0 +1,35 @@
+//#region src/links/timeout/timeout.ts
+/**
+* What a request that took too long fails with.
+*
+* @see https://raf-query.katt.dev/docs/retries#timeouts
+*/
+var QueryTimeoutError = class extends Error {
+	name = "QueryTimeoutError";
+};
+/**
+* Fail a request (and abort its `signal`) when it takes longer than `ms`.
+*
+* @see https://raf-query.katt.dev/docs/retries#timeouts
+*/
+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 };