@raf-query/core 0.12.0 → 0.13.1

package/dist/infinite/infinite.d.mts

@@ -3,11 +3,20 @@ import { DefaultTypes, RootOf, RootTypes } from "../root.mjs";
 import { BaseOptions, FromQueryFn, QueryFunctionContext, QueryOptions } from "../options.mjs";
 import { Operation } from "../client.mjs";
 //#region src/infinite/infinite.d.ts
-/** A paged query's data. */
+/**
+ * A paged query's data.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries
+ */
 export interface InfiniteData<TPage, TParam = unknown> {
   readonly pageParams: ReadonlyArray<TParam>;
   readonly pages: ReadonlyArray<TPage>;
 }
+/**
+ * What a paged `queryFn` gets: the query function context, plus the page param and the direction it loads in.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries
+ */
 export interface InfiniteQueryFunctionContext<TKey extends QueryKey, TParam> extends QueryFunctionContext<TKey> {
   readonly direction: "backward" | "forward";
   readonly pageParam: TParam;
@@ -17,15 +26,33 @@ interface InfiniteOptions<TKey extends QueryKey, TPage, TParam, TData, TTypes ex
   readonly getNextPageParam: PageParamFn<TPage, TParam>;
   readonly getPreviousPageParam?: PageParamFn<TPage, TParam>;
   readonly initialPageParam: TParam;
+  /**
+   * Whether the cached pages suit this input. Pages grow from the
+   * `initialPageParam` the entry was first loaded with; when part of the
+   * input picks only that start and stays out of the key (the item a list
+   * opens at), inputs that differ there share one entry. `load` asks
+   * before it uses the pages: on `false` it drops them, and the list loads
+   * again from this input's `initialPageParam`. Readers never drop pages.
+   * Default: keep them.
+   */
+  readonly keepPages?: (data: InfiniteData<TPage, TParam>) => boolean;
   /** Keep at most this many pages, dropping from the other end. */
   readonly maxPages?: number;
   readonly select?: (data: InfiniteData<TPage, TParam>) => TData;
 }
-/** What `infiniteQueryOptions` returns. */
+/**
+ * What `infiniteQueryOptions` returns.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries
+ */
 export type InfiniteQueryOptions<TKey extends QueryKey = QueryKey, TPage = unknown, TParam = unknown, TData = InfiniteData<TPage, TParam>, TTypes extends RootTypes = RootTypes> = QueryOptions<TKey, InfiniteData<TPage, TParam>, TData, TTypes> & Pick<InfiniteOptions<TKey, TPage, TParam, TData, TTypes>, "getNextPageParam" | "getPreviousPageParam" | "initialPageParam" | "maxPages"> & {
   readonly "~run": (op: Operation) => Promise<unknown>;
 };
-/** `infiniteQueryOptions`, with `meta` checked against the root `TTypes`. */
+/**
+ * `infiniteQueryOptions`, with `meta` checked against the root `TTypes`.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
+ */
 export interface InfiniteQueryOptionsBuilder<TTypes extends RootTypes> {
   <const TKey extends QueryKey, TPage, TParam, TData = InfiniteData<TPage, TParam>>(options: InfiniteOptions<TKey, FromQueryFn<TPage>, TParam, TData, TTypes> & {
     readonly queryFn: (context: InfiniteQueryFunctionContext<TKey, TParam>) => PromiseLike<TPage> | TPage;
@@ -36,10 +63,10 @@ export interface InfiniteQueryOptionsBuilder<TTypes extends RootTypes> {
  * and, on their state, `fetchNextPage` and `fetchPreviousPage`:
  *
  * ```ts
- * export const issueList = (input: { status: Status }) =>
+ * export const commentsQuery = (input: { slug: string }) =>
  *   infiniteQueryOptions({
- *     queryKey: issues("list", input),
- *     queryFn: ({ pageParam, signal }) => listIssues({ ...input, cursor: pageParam }, { signal }),
+ *     queryKey: comments(input.slug),
+ *     queryFn: ({ pageParam, signal }) => listComments({ ...input, cursor: pageParam }, { signal }),
  *     initialPageParam: 0,
  *     getNextPageParam: (lastPage) => lastPage.nextCursor,
  *   });
@@ -47,6 +74,8 @@ export interface InfiniteQueryOptionsBuilder<TTypes extends RootTypes> {
  *
  * 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
  */
 export declare const infiniteQueryOptions: InfiniteQueryOptionsBuilder<DefaultTypes>;
 /**
@@ -57,15 +86,8 @@ export declare const infiniteQueryOptions: InfiniteQueryOptionsBuilder<DefaultTy
  * // raf.ts
  * export const infiniteQueryOptions = bindInfiniteQueryOptions<typeof makeQueryClient>();
  * ```
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
  */
 export declare function bindInfiniteQueryOptions<T>(): InfiniteQueryOptionsBuilder<RootOf<T>>;
-interface PagedSource {
-  readonly getNextPageParam: PageParamFn<unknown, unknown>;
-  readonly getPreviousPageParam?: PageParamFn<unknown, unknown>;
-  readonly initialPageParam: unknown;
-  readonly maxPages?: number;
-  readonly queryFn: (context: InfiniteQueryFunctionContext<QueryKey, unknown>) => unknown;
-}
-/** The param of the page after (or before) `data`, or `undefined` at the end. */
-export declare function pageParamAfter(options: Pick<PagedSource, "getNextPageParam" | "getPreviousPageParam">, data: InfiniteData<unknown>, direction: "next" | "previous"): unknown;
 //#endregion

package/dist/infinite/infinite.mjs

@@ -1,13 +1,14 @@
+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 issueList = (input: { status: Status }) =>
+* export const commentsQuery = (input: { slug: string }) =>
 *   infiniteQueryOptions({
-*     queryKey: issues("list", input),
-*     queryFn: ({ pageParam, signal }) => listIssues({ ...input, cursor: pageParam }, { signal }),
+*     queryKey: comments(input.slug),
+*     queryFn: ({ pageParam, signal }) => listComments({ ...input, cursor: pageParam }, { signal }),
 *     initialPageParam: 0,
 *     getNextPageParam: (lastPage) => lastPage.nextCursor,
 *   });
@@ -15,9 +16,12 @@
 *
 * 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,
+	"~keep": options.keepPages,
 	"~run": (op) => runPages(op, options)
 });
 /**
@@ -28,6 +32,8 @@ const infiniteQueryOptions = (options) => ({
 * // 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;
@@ -41,8 +47,25 @@ function pageParamAfter(options, data, direction) {
 	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,
@@ -55,20 +78,26 @@ async function runPages(op, source) {
 		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: [...previous.pageParams, pageParam].slice(-max),
-			pages: [...previous.pages, page].slice(-max)
+			pageParams: [...current.pageParams, pageParam].slice(-max),
+			pages: [...current.pages, page].slice(-max)
 		} : {
-			pageParams: [pageParam, ...previous.pageParams].slice(0, max),
-			pages: [page, ...previous.pages].slice(0, 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);
@@ -79,9 +108,13 @@ async function runPages(op, source) {
 		if (next === void 0) break;
 		pageParam = next;
 	}
+	const now = latest(op, void 0);
 	return {
 		pageParams,
-		pages
+		pages: pages.map((page, index) => {
+			const written = pageFor(now, pageParams[index]);
+			return written !== void 0 && written !== before[index] ? written : page;
+		})
 	};
 }
 //#endregion

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

@@ -2,12 +2,12 @@ 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, isInvalidated, isStale, remove, reset, subscribeEntry } from "./entry.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 { pageParamAfter } from "./infinite/infinite.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, fulfilled, hashKey, isInvalidated, isStale, isWaterfallHandle, loadsOf, mapThenable, mount, pageParamAfter, pending, readData, rejected, remove, reset, startIfStale, subscribeEntry, systemClock };
+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

@@ -1,7 +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, isInvalidated, isStale, remove, reset, subscribeEntry } from "./entry.mjs";
-import { pageParamAfter } from "./infinite/infinite.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, fulfilled, hashKey, isInvalidated, isStale, isWaterfallHandle, loadsOf, mapThenable, mount, pageParamAfter, pending, readData, rejected, remove, reset, startIfStale, subscribeEntry, systemClock };
+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

@@ -8,13 +8,19 @@
  * 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. */
+/**
+ * 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];
@@ -34,6 +40,8 @@ export interface Group<TPath extends ReadonlyArray<string> = ReadonlyArray<strin
  *   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]>;

package/dist/keys/targets.d.mts

@@ -1,7 +1,11 @@
 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. */
+/**
+ * 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;
@@ -16,8 +20,10 @@ export interface QueryInfo<TMeta = QueryMeta> {
  *
  * ```ts
  * const ownedBy: Target<AppMeta, Team> = { where: (query, team) => query.meta.owner === team };
- * await invalidateMany(client, ownedBy, "posts-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;

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

@@ -1,5 +1,10 @@
 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;
@@ -19,6 +24,8 @@ export interface RetryMeta {
  * 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;

package/dist/links/retry/retry.mjs

@@ -32,6 +32,8 @@ const notThrownResponse = (error) => !isResponse(error);
 * 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) => {

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

@@ -1,9 +1,17 @@
 import { Link } from "../../client.mjs";
 //#region src/links/timeout/timeout.d.ts
-/** What a request that took too long fails with. */
+/**
+ * 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`. */
+/**
+ * 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

@@ -1,9 +1,17 @@
 //#region src/links/timeout/timeout.ts
-/** What a request that took too long fails with. */
+/**
+* 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`. */
+/**
+* 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();

package/dist/load.d.mts

@@ -6,13 +6,19 @@ import { QueryClient } from "./client.mjs";
  * 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.
+ *
+ * @see https://raf-query.katt.dev/docs/reading-queries#handles
  */
 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. */
+/**
+ * A query for `load` to start. Building one starts nothing.
+ *
+ * @see https://raf-query.katt.dev/docs/starting-queries
+ */
 export interface LoadEntry<TFactory extends QueryFactory = QueryFactory, TKind extends LoadKind = LoadKind> {
   readonly factory: TFactory;
   readonly input: InputOf<TFactory>;
@@ -20,6 +26,11 @@ export interface LoadEntry<TFactory extends QueryFactory = QueryFactory, TKind e
   /** For paged factories: how many pages a first load fetches. */
   readonly pages?: number;
 }
+/**
+ * Options for a `load` entry.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#loading-several-pages-up-front
+ */
 export interface LoadEntryOptions {
   /** For paged factories: how many pages a first load fetches. Default 1. */
   readonly pages?: number;
@@ -29,6 +40,8 @@ type LoadEntryArgs<TFactory extends QueryFactory> = [input: InputOf<TFactory>, o
  * 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.
+ *
+ * @see https://raf-query.katt.dev/docs/starting-queries#prefetch-or-swr
  */
 export declare function prefetch<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadEntryArgs<TFactory>): LoadEntry<TFactory, "prefetch">;
 /**
@@ -37,6 +50,8 @@ export declare function prefetch<TFactory extends QueryFactory>(factory: TFactor
  * 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.
+ *
+ * @see https://raf-query.katt.dev/docs/starting-queries#prefetch-or-swr
  */
 export declare function swr<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadEntryArgs<TFactory>): LoadEntry<TFactory, "swr">;
 /**
@@ -46,6 +61,8 @@ export declare function swr<TFactory extends QueryFactory>(factory: TFactory, ..
  * 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.
+ *
+ * @see https://raf-query.katt.dev/docs/starting-queries#the-three-entries
  */
 export declare function revalidate<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadEntryArgs<TFactory>): LoadEntry<TFactory, "revalidate">;
 /**
@@ -58,6 +75,8 @@ export declare function revalidate<TFactory extends QueryFactory>(factory: TFact
  *   drafts: user.isAdmin ? prefetch(draftsQuery, { slug }) : skipToken,
  * });
  * ```
+ *
+ * @see https://raf-query.katt.dev/docs/starting-queries#conditional-queries
  */
 export declare const skipToken: unique symbol;
 /** What `load` takes per name: an entry, or `skipToken`. */
@@ -68,6 +87,8 @@ type LoadedData<TEntries extends LoadEntries> = { [TName in keyof TEntries as TE
 /**
  * What `load` resolves to: a handle per entry (`undefined` for `skipToken`),
  * and the data of `swr` and `revalidate` entries.
+ *
+ * @see https://raf-query.katt.dev/docs/starting-queries
  */
 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. */
@@ -96,10 +117,12 @@ export declare function startIfStale(entry: Entry): void;
  *
  * ```ts
  * const [handles, data] = await load(queryClient, {
- *   comments: prefetch(commentsQuery, { issueId: id }),
- *   issue: swr(issueQuery, { id }),
+ *   comments: prefetch(commentsQuery, { slug }),
+ *   post: swr(postQuery, { slug }),
  * });
  * ```
+ *
+ * @see https://raf-query.katt.dev/docs/starting-queries
  */
 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. */
@@ -118,6 +141,8 @@ export declare function isWaterfallHandle(handle: Pick<QueryHandle, "queryKey">)
  * ```ts
  * const searchHandle = waterfallHandle(searchQuery, props.search, (input) => ({ ...input, q }));
  * ```
+ *
+ * @see https://raf-query.katt.dev/docs/request-waterfalls#render-time-inputs-waterfallhandle
  */
 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>;