@raf-query/core 0.11.1 → 0.12.0

package/dist/features/focus-refetch/focus-refetch.d.mts

@@ -0,0 +1,15 @@
+import { Feature } from "../../client.mjs";
+//#region src/features/focus-refetch/focus-refetch.d.ts
+/** What `focusRefetch()` reads from a query's `meta`. */
+export interface FocusRefetchMeta {
+  /** `false`: don't refetch this query on focus. */
+  readonly refetchOnWindowFocus?: boolean;
+}
+/**
+ * Refetch read, stale queries when the window regains focus, except those
+ * with `meta: { refetchOnWindowFocus: false }`.
+ */
+export declare function focusRefetch(): Feature<{
+  readonly meta: FocusRefetchMeta;
+}>;
+//#endregion

package/dist/features/focus-refetch/focus-refetch.mjs

@@ -0,0 +1,18 @@
+import { feature } from "../../client.mjs";
+import { refetchStaleReads } from "../shared.mjs";
+//#region src/features/focus-refetch/focus-refetch.ts
+/**
+* Refetch read, stale queries when the window regains focus, except those
+* with `meta: { refetchOnWindowFocus: false }`.
+*/
+function focusRefetch() {
+	return feature((client, signal) => {
+		const onFocus = () => {
+			if (document.visibilityState === "visible") refetchStaleReads(client, "refetchOnWindowFocus");
+		};
+		document.addEventListener("visibilitychange", onFocus, { signal });
+		window.addEventListener("focus", onFocus, { signal });
+	});
+}
+//#endregion
+export { focusRefetch };

package/dist/features/polling/polling.d.mts

@@ -0,0 +1,12 @@
+import { Feature } from "../../client.mjs";
+//#region src/features/polling/polling.d.ts
+/** What `polling()` reads from a query's `meta`. */
+export interface PollingMeta {
+  /** Refetch every `n` ms while the query is read. */
+  readonly refetchInterval?: number | false;
+}
+/** Refetch read queries every `meta.refetchInterval` ms. */
+export declare function polling(): Feature<{
+  readonly meta: PollingMeta;
+}>;
+//#endregion

package/dist/features/polling/polling.mjs

@@ -0,0 +1,35 @@
+import { feature } from "../../client.mjs";
+import { isNumber } from "../../guards.mjs";
+import { fetchEntry } from "../../entry.mjs";
+import { metaOf } from "../shared.mjs";
+//#region src/features/polling/polling.ts
+/** Refetch read queries every `meta.refetchInterval` ms. */
+function polling() {
+	return feature((client, signal) => {
+		const timers = /* @__PURE__ */ new Map();
+		const stop = (entry) => {
+			client.clock.clearTimeout(timers.get(entry));
+			timers.delete(entry);
+		};
+		const sync = (entry) => {
+			const interval = metaOf(entry, "refetchInterval");
+			if (!(entry.readers.size > 0 && isNumber(interval) && interval > 0 && client["~entries"].get(entry.hash) === entry)) stop(entry);
+			else if (!timers.has(entry)) {
+				const tick = () => {
+					timers.set(entry, client.clock.setTimeout(tick, interval));
+					fetchEntry(entry);
+				};
+				timers.set(entry, client.clock.setTimeout(tick, interval));
+			}
+		};
+		client.subscribe((event) => {
+			if (event.type === "readers" || event.type === "removed") sync(event.entry);
+		}, { signal });
+		for (const entry of client["~entries"].values()) sync(entry);
+		signal.addEventListener("abort", () => {
+			for (const entry of timers.keys()) stop(entry);
+		});
+	});
+}
+//#endregion
+export { polling };

package/dist/features/reconnect-refetch/reconnect-refetch.d.mts

@@ -0,0 +1,15 @@
+import { Feature } from "../../client.mjs";
+//#region src/features/reconnect-refetch/reconnect-refetch.d.ts
+/** What `reconnectRefetch()` reads from a query's `meta`. */
+export interface ReconnectRefetchMeta {
+  /** `false`: don't refetch this query when the browser comes back online. */
+  readonly refetchOnReconnect?: boolean;
+}
+/**
+ * Refetch read, stale queries when the browser comes back online, except
+ * those with `meta: { refetchOnReconnect: false }`.
+ */
+export declare function reconnectRefetch(): Feature<{
+  readonly meta: ReconnectRefetchMeta;
+}>;
+//#endregion

package/dist/features/reconnect-refetch/reconnect-refetch.mjs

@@ -0,0 +1,14 @@
+import { feature } from "../../client.mjs";
+import { refetchStaleReads } from "../shared.mjs";
+//#region src/features/reconnect-refetch/reconnect-refetch.ts
+/**
+* Refetch read, stale queries when the browser comes back online, except
+* those with `meta: { refetchOnReconnect: false }`.
+*/
+function reconnectRefetch() {
+	return feature((client, signal) => {
+		window.addEventListener("online", () => refetchStaleReads(client, "refetchOnReconnect"), { signal });
+	});
+}
+//#endregion
+export { reconnectRefetch };

package/dist/features/shared.mjs

@@ -0,0 +1,13 @@
+import { isObject } from "../guards.mjs";
+import { fetchEntry, isStale } from "../entry.mjs";
+//#region src/features/shared.ts
+function metaOf(entry, field) {
+	const meta = entry.options?.meta;
+	if (!isObject(meta) || !(field in meta)) return;
+	return meta[field];
+}
+function refetchStaleReads(client, optOut) {
+	for (const entry of client["~entries"].values()) if (entry.readers.size > 0 && isStale(entry) && metaOf(entry, optOut) !== false) fetchEntry(entry);
+}
+//#endregion
+export { metaOf, refetchStaleReads };

package/dist/guards.mjs

@@ -0,0 +1,23 @@
+//#region src/guards.ts
+function isFunction(value) {
+	return typeof value === "function";
+}
+/** `Array.isArray` that narrows readonly arrays and tuples too. */
+function isArray(value) {
+	return Array.isArray(value);
+}
+function isNumber(value) {
+	return typeof value === "number";
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function isString(value) {
+	return typeof value === "string";
+}
+/** A `Response`, also one from another realm or polyfill. */
+function isResponse(value) {
+	return Object.prototype.toString.call(value) === "[object Response]";
+}
+//#endregion
+export { isArray, isFunction, isNumber, isObject, isResponse, isString };

package/dist/hydration/hydration.d.mts

@@ -0,0 +1,73 @@
+import { QueryKey } from "../keys/keys.mjs";
+import { Entry } from "../entry.mjs";
+import { QueryClient } from "../client.mjs";
+//#region src/hydration/hydration.d.ts
+/** What a dehydrated pending entry's promise resolves to. */
+export interface DehydratedResult {
+  readonly data?: unknown;
+  /** When the sender got the result (ms since epoch). */
+  readonly updatedAt: number;
+}
+/**
+ * One cache entry in transit. Settled entries carry `data` and
+ * `updatedAt > 0`; entries still loading carry their request's `promise`,
+ * so the receiver resumes it instead of fetching again.
+ */
+export interface DehydratedEntry {
+  readonly data?: unknown;
+  readonly promise?: Promise<DehydratedResult>;
+  readonly queryKey: QueryKey;
+  /** When the data was fetched; `0` while pending. */
+  readonly updatedAt: number;
+}
+export interface DehydratedState {
+  readonly entries: ReadonlyArray<DehydratedEntry>;
+}
+export interface DehydrateOptions {
+  /**
+   * Which entries to send. Default: entries with data or a request in
+   * flight. An entry with neither has nothing to send and stays behind.
+   */
+  readonly filter?: (entry: Entry) => boolean;
+  /** Send a pending entry's error as is, instead of a `RedactedError`. */
+  readonly keepErrors?: boolean;
+  /**
+   * Hashes already sent in this transfer (one request). Those entries are
+   * skipped, and the ones sent are added.
+   */
+  readonly sent?: Set<string>;
+}
+/**
+ * What a streamed pending entry rejects with when its server request threw:
+ * the browser learns which query failed, not why.
+ */
+export declare class RedactedError extends Error {
+  readonly name = "RedactedError";
+  readonly hash: string;
+  constructor(hash: string);
+}
+/** The default filter: entries with data or a request in flight. */
+export declare function canDehydrate(entry: Entry): boolean;
+/** Snapshot the client's entries for transfer. */
+export declare function dehydrate(client: QueryClient, options?: DehydrateOptions): DehydratedState;
+export interface DehydratedStream {
+  /** Stop: send what changed, then end `updates`. */
+  close(): void;
+  /** The entries to send first. */
+  readonly initial: DehydratedState;
+  /** Entries as they start or settle, batched per microtask. */
+  readonly updates: ReadableStream<DehydratedState>;
+}
+/**
+ * The cache now, then entries as they start, until `close()`. Snapshots and
+ * subscribes in one synchronous step, so no change falls between the two.
+ */
+export declare function dehydrateStream(client: QueryClient, options?: DehydrateOptions): DehydratedStream;
+/**
+ * Write dehydrated entries into a client. Existing entries only take newer
+ * data. A pending entry the client has nothing for resumes the sender's
+ * request; one that has data or a request of its own waits for the
+ * sender's, takes it if newer, and revalidates if the sender's failed.
+ */
+export declare function hydrate(client: QueryClient, state: DehydratedState): void;
+//#endregion

package/dist/hydration/hydration.mjs

@@ -0,0 +1,128 @@
+import { adopt, entryForKey, fetchEntry, isStale, write } from "../entry.mjs";
+//#region src/hydration/hydration.ts
+/**
+* What a streamed pending entry rejects with when its server request threw:
+* the browser learns which query failed, not why.
+*/
+var RedactedError = class extends Error {
+	name = "RedactedError";
+	hash;
+	constructor(hash) {
+		super(`Query ${hash} failed on the server`);
+		this.hash = hash;
+	}
+};
+/** The default filter: entries with data or a request in flight. */
+function canDehydrate(entry) {
+	const state = entry.state;
+	return state.hasData || state.isFetching;
+}
+function dehydrateEntry(entry, options) {
+	const state = entry.state;
+	const base = { queryKey: entry.key };
+	if (state.hasData) return {
+		...base,
+		data: state.data,
+		updatedAt: state.updatedAt
+	};
+	const run = entry.run;
+	if (!run) return;
+	const promise = run.done.promise.then((outcome) => {
+		if (outcome.ok) return {
+			data: entry.state.data,
+			updatedAt: entry.state.updatedAt
+		};
+		throw options.keepErrors ? outcome.error : new RedactedError(entry.hash);
+	});
+	promise.catch(() => {});
+	return {
+		...base,
+		promise,
+		updatedAt: 0
+	};
+}
+function dehydrateEntries(entries, options) {
+	const filter = options.filter ?? canDehydrate;
+	const sent = options.sent;
+	const dehydrated = [];
+	for (const entry of entries) {
+		const dehydratedEntry = !sent?.has(entry.hash) && filter(entry) ? dehydrateEntry(entry, options) : void 0;
+		if (dehydratedEntry) {
+			sent?.add(entry.hash);
+			dehydrated.push(dehydratedEntry);
+		}
+	}
+	return { entries: dehydrated };
+}
+/** Snapshot the client's entries for transfer. */
+function dehydrate(client, options = {}) {
+	return dehydrateEntries(client["~entries"].values(), options);
+}
+/**
+* The cache now, then entries as they start, until `close()`. Snapshots and
+* subscribes in one synchronous step, so no change falls between the two.
+*/
+function dehydrateStream(client, options = {}) {
+	const send = {
+		...options,
+		sent: options.sent ?? /* @__PURE__ */ new Set()
+	};
+	const unsubscribe = new AbortController();
+	let controller;
+	const updates = new ReadableStream({ start(streamController) {
+		controller = streamController;
+	} });
+	let batch;
+	const flush = () => {
+		const changed = batch;
+		batch = void 0;
+		if (!changed) return;
+		const state = dehydrateEntries(changed, send);
+		if (state.entries.length > 0) controller?.enqueue(state);
+	};
+	client.subscribe((event) => {
+		if (event.type === "removed" || send.sent.has(event.entry.hash)) return;
+		if (!batch) {
+			batch = /* @__PURE__ */ new Set();
+			queueMicrotask(flush);
+		}
+		batch.add(event.entry);
+	}, { signal: unsubscribe.signal });
+	return {
+		close() {
+			if (unsubscribe.signal.aborted) return;
+			flush();
+			unsubscribe.abort();
+			controller?.close();
+		},
+		initial: dehydrate(client, send),
+		updates
+	};
+}
+function revalidate(entry) {
+	if (entry.options && entry.readers.size > 0 && isStale(entry)) fetchEntry(entry);
+}
+/** Take the sender's data if it's newer than the entry's. */
+function takeNewer(entry, result) {
+	if (!entry.state.hasData || entry.state.updatedAt < result.updatedAt) write(entry, result.data, result.updatedAt, entry.client["~seq"]);
+	else revalidate(entry);
+}
+/**
+* Write dehydrated entries into a client. Existing entries only take newer
+* data. A pending entry the client has nothing for resumes the sender's
+* request; one that has data or a request of its own waits for the
+* sender's, takes it if newer, and revalidates if the sender's failed.
+*/
+function hydrate(client, state) {
+	for (const sent of state.entries) {
+		const entry = entryForKey(client, sent.queryKey);
+		if (sent.promise === void 0) takeNewer(entry, sent);
+		else {
+			const result = Promise.resolve(sent.promise);
+			if (!entry.state.hasData && !entry.run) adopt(entry, result);
+			else result.then((settled) => takeNewer(entry, settled), () => revalidate(entry));
+		}
+	}
+}
+//#endregion
+export { RedactedError, canDehydrate, dehydrate, dehydrateStream, hydrate };

package/dist/index.d.mts

@@ -1,13 +1,18 @@
-import { Settled, allKeyed } from "./all-keyed.mjs";
-import { QueryKey, hashKey, matchesKey } from "./key.mjs";
-import { AnyQueryOptions, DataOf, ErrorOf, InfiniteData, InfiniteQueryOptions, InfiniteQueryTypes, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, PagedQueryFactory, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryHandleWithData, QueryMeta, QueryOptions, QueryTypes, Register, RetryPolicy, ServicesOf, ThrowOnErrorOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
-import { platform_d_exports } from "./platform.mjs";
-import { Pending, Thenable, fulfilled, pending } from "./thenable.mjs";
-import { query_d_exports } from "./query.mjs";
-import { DehydrateOptions, DehydratedQuery, DehydratedResult, DehydratedState, DehydratedStream, HydrateOptions, RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
-import { cache_d_exports } from "./cache.mjs";
-import { QueryClient, QueryClientConfig, dehydrate, hydrate } from "./client.mjs";
-import { observer_d_exports } from "./observer.mjs";
-import { HasTypedError, PagingControls, PromiseControls, QueryControls, ReadValue, ThrowsOnError, UseQueryControls, UseQueryOptions, UseQueryThrowOptions, promiseControls, resultThenable, throwsOnError } from "./controls.mjs";
-import { binding_d_exports } from "./binding.mjs";
-export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type ErrorOf, type HasTypedError, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InfiniteQueryTypes, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, type PagedQueryFactory, type PagingControls, type Pending, platform_d_exports as Platform, type PromiseControls, query_d_exports as Query, type QueryBehavior, binding_d_exports as QueryBinding, cache_d_exports as QueryCache, QueryClient, type QueryClientConfig, type QueryControls, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryHandleWithData, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, type QueryTypes, type ReadValue, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Settled, type Thenable, type ThrowOnErrorOf, type ThrowsOnError, type UseQueryControls, type UseQueryOptions, type UseQueryThrowOptions, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable, throwsOnError };
+import { Group, QueryKey, group } from "./keys/keys.mjs";
+import { QueryMeta } from "./root.mjs";
+import { QueryInfo, Target } from "./keys/targets.mjs";
+import { DataOf, InfiniteQueryFactory, InputOf, QueryFactory, QueryFunctionContext, QueryOptions, QueryOptionsBuilder, SingleQueryFactory, StreamOptions, bindQueryOptions, queryOptions } from "./options.mjs";
+import { Thenable } from "./thenable.mjs";
+import { abortError } from "./entry.mjs";
+import { Clock, Feature, Link, Operation, QueryClient, QueryClientConfig, createQueryClient, feature, link } from "./client.mjs";
+import { focusRefetch } from "./features/focus-refetch/focus-refetch.mjs";
+import { reconnectRefetch } from "./features/reconnect-refetch/reconnect-refetch.mjs";
+import { polling } from "./features/polling/polling.mjs";
+import { DehydrateOptions, DehydratedEntry, DehydratedResult, DehydratedState, DehydratedStream, RedactedError, canDehydrate, dehydrate, dehydrateStream, hydrate } from "./hydration/hydration.mjs";
+import { InfiniteData, InfiniteQueryFunctionContext, InfiniteQueryOptions, InfiniteQueryOptionsBuilder, bindInfiniteQueryOptions, infiniteQueryOptions } from "./infinite/infinite.mjs";
+import { RetryOptions, retry } from "./links/retry/retry.mjs";
+import { QueryTimeoutError, timeout } from "./links/timeout/timeout.mjs";
+import { LoadEntry, LoadEntryOptions, Loaded, QueryHandle, load, prefetch, revalidate, skipToken, swr, waterfallHandle } from "./load.mjs";
+import { Recommended, recommended } from "./presets.mjs";
+import { ClientFor, PartialInput, getData, invalidateAll, invalidateMany, invalidateOne, isFetching, removeAll, removeMany, removeOne, resetAll, resetMany, resetOne, setData } from "./verbs.mjs";
+export { type ClientFor, type Clock, type DataOf, type DehydrateOptions, type DehydratedEntry, type DehydratedResult, type DehydratedState, type DehydratedStream, type Feature, type Group, type InfiniteData, type InfiniteQueryFactory, type InfiniteQueryFunctionContext, type InfiniteQueryOptions, type InfiniteQueryOptionsBuilder, type InputOf, type Link, type LoadEntry, type LoadEntryOptions, type Loaded, type Operation, type PartialInput, type QueryClient, type QueryClientConfig, type QueryFactory, type QueryFunctionContext, type QueryHandle, type QueryInfo, type QueryKey, type QueryMeta, type QueryOptions, type QueryOptionsBuilder, QueryTimeoutError, type Recommended, RedactedError, type RetryOptions, type SingleQueryFactory, type StreamOptions, type Target, type Thenable, abortError, bindInfiniteQueryOptions, bindQueryOptions, canDehydrate, createQueryClient, dehydrate, dehydrateStream, feature, focusRefetch, getData, group, hydrate, infiniteQueryOptions, invalidateAll, invalidateMany, invalidateOne, isFetching, link, load, polling, prefetch, queryOptions, recommended, reconnectRefetch, removeAll, removeMany, removeOne, resetAll, resetMany, resetOne, retry, revalidate, setData, skipToken, swr, timeout, waterfallHandle };

package/dist/index.mjs

@@ -1,13 +1,15 @@
-import { allKeyed } from "./all-keyed.mjs";
-import { hashKey, matchesKey } from "./key.mjs";
-import { platform_exports } from "./platform.mjs";
-import { fulfilled, pending } from "./thenable.mjs";
-import { query_exports } from "./query.mjs";
-import { RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
-import { infiniteQueryOptions, queryOptions } from "./options.mjs";
-import { cache_exports } from "./cache.mjs";
-import { QueryClient, dehydrate, hydrate } from "./client.mjs";
-import { promiseControls, resultThenable, throwsOnError } from "./controls.mjs";
-import { observer_exports } from "./observer.mjs";
-import { binding_exports } from "./binding.mjs";
-export { platform_exports as Platform, query_exports as Query, binding_exports as QueryBinding, cache_exports as QueryCache, QueryClient, observer_exports as QueryObserver, RedactedError, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable, throwsOnError };
+import { createQueryClient, feature, link } from "./client.mjs";
+import { group } from "./keys/keys.mjs";
+import { bindQueryOptions, queryOptions } from "./options.mjs";
+import { abortError } from "./entry.mjs";
+import { focusRefetch } from "./features/focus-refetch/focus-refetch.mjs";
+import { reconnectRefetch } from "./features/reconnect-refetch/reconnect-refetch.mjs";
+import { polling } from "./features/polling/polling.mjs";
+import { RedactedError, canDehydrate, dehydrate, dehydrateStream, hydrate } from "./hydration/hydration.mjs";
+import { bindInfiniteQueryOptions, infiniteQueryOptions } from "./infinite/infinite.mjs";
+import { retry } from "./links/retry/retry.mjs";
+import { QueryTimeoutError, timeout } from "./links/timeout/timeout.mjs";
+import { load, prefetch, revalidate, skipToken, swr, waterfallHandle } from "./load.mjs";
+import { recommended } from "./presets.mjs";
+import { getData, invalidateAll, invalidateMany, invalidateOne, isFetching, removeAll, removeMany, removeOne, resetAll, resetMany, resetOne, setData } from "./verbs.mjs";
+export { QueryTimeoutError, RedactedError, abortError, bindInfiniteQueryOptions, bindQueryOptions, canDehydrate, createQueryClient, dehydrate, dehydrateStream, feature, focusRefetch, getData, group, hydrate, infiniteQueryOptions, invalidateAll, invalidateMany, invalidateOne, isFetching, link, load, polling, prefetch, queryOptions, recommended, reconnectRefetch, removeAll, removeMany, removeOne, resetAll, resetMany, resetOne, retry, revalidate, setData, skipToken, swr, timeout, waterfallHandle };

package/dist/infinite/infinite.d.mts

@@ -0,0 +1,71 @@
+import { QueryKey } from "../keys/keys.mjs";
+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. */
+export interface InfiniteData<TPage, TParam = unknown> {
+  readonly pageParams: ReadonlyArray<TParam>;
+  readonly pages: ReadonlyArray<TPage>;
+}
+export interface InfiniteQueryFunctionContext<TKey extends QueryKey, TParam> extends QueryFunctionContext<TKey> {
+  readonly direction: "backward" | "forward";
+  readonly pageParam: TParam;
+}
+type PageParamFn<TPage, TParam> = (page: TPage, pages: ReadonlyArray<TPage>, pageParam: TParam) => TParam | null | undefined;
+interface InfiniteOptions<TKey extends QueryKey, TPage, TParam, TData, TTypes extends RootTypes = RootTypes> extends BaseOptions<TKey, TTypes> {
+  readonly getNextPageParam: PageParamFn<TPage, TParam>;
+  readonly getPreviousPageParam?: PageParamFn<TPage, TParam>;
+  readonly initialPageParam: TParam;
+  /** Keep at most this many pages, dropping from the other end. */
+  readonly maxPages?: number;
+  readonly select?: (data: InfiniteData<TPage, TParam>) => TData;
+}
+/** What `infiniteQueryOptions` returns. */
+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`. */
+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;
+  }): InfiniteQueryOptions<TKey, TPage, TParam, TData, TTypes>;
+}
+/**
+ * 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 }) =>
+ *   infiniteQueryOptions({
+ *     queryKey: issues("list", input),
+ *     queryFn: ({ pageParam, signal }) => listIssues({ ...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.
+ */
+export declare const infiniteQueryOptions: InfiniteQueryOptionsBuilder<DefaultTypes>;
+/**
+ * `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>();
+ * ```
+ */
+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

@@ -0,0 +1,88 @@
+//#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 }) =>
+*   infiniteQueryOptions({
+*     queryKey: issues("list", input),
+*     queryFn: ({ pageParam, signal }) => listIssues({ ...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.
+*/
+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>();
+* ```
+*/
+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;
+}
+async function runPages(op, source) {
+	const fetchPage = (pageParam, direction) => Promise.resolve(source.queryFn({
+		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 max = source.maxPages ?? Infinity;
+		return direction === "next" ? {
+			pageParams: [...previous.pageParams, pageParam].slice(-max),
+			pages: [...previous.pages, page].slice(-max)
+		} : {
+			pageParams: [pageParam, ...previous.pageParams].slice(0, max),
+			pages: [page, ...previous.pages].slice(0, max)
+		};
+	}
+	const count = previous?.pages.length ?? op.pages ?? 1;
+	const pages = [];
+	const pageParams = [];
+	let pageParam = previous?.pageParams[0] ?? source.initialPageParam;
+	while (pages.length < count) {
+		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;
+	}
+	return {
+		pageParams,
+		pages
+	};
+}
+//#endregion
+export { bindInfiniteQueryOptions, infiniteQueryOptions, pageParamAfter };

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, 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 { 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 };

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, isInvalidated, isStale, remove, reset, subscribeEntry } from "./entry.mjs";
+import { pageParamAfter } from "./infinite/infinite.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 };