@raf-query/core 0.12.0 → 0.13.1

package/dist/load.mjs

@@ -1,6 +1,6 @@
 import { hashKey } from "./keys/keys.mjs";
 import { optionsOf } from "./options.mjs";
-import { entryOf, fetchEntry, isInvalidated, isStale } from "./entry.mjs";
+import { entryOf, fetchEntry, isBrowserOnly, isInvalidated, isStale, reset } from "./entry.mjs";
 //#region src/load.ts
 function loadEntry(kind, factory, args) {
 	return {
@@ -14,6 +14,8 @@ function loadEntry(kind, factory, args) {
 * 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
 */
 function prefetch(factory, ...args) {
 	return loadEntry("prefetch", factory, args);
@@ -24,6 +26,8 @@ function prefetch(factory, ...args) {
 * 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
 */
 function swr(factory, ...args) {
 	return loadEntry("swr", factory, args);
@@ -35,6 +39,8 @@ function swr(factory, ...args) {
 * 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
 */
 function revalidate(factory, ...args) {
 	return loadEntry("revalidate", factory, args);
@@ -49,6 +55,8 @@ function revalidate(factory, ...args) {
 *   drafts: user.isAdmin ? prefetch(draftsQuery, { slug }) : skipToken,
 * });
 * ```
+*
+* @see https://raf-query.katt.dev/docs/starting-queries#conditional-queries
 */
 const skipToken = Symbol("skipToken");
 const loadRecords = /* @__PURE__ */ new WeakMap();
@@ -73,6 +81,14 @@ function startIfStale(entry) {
 function isFresh(entry) {
 	return entry.client.isServer ? entry.state.hasData && !isInvalidated(entry) : !isStale(entry);
 }
+/**
+* Drop pages the entry's `keepPages` turns down for the input it was just
+* loaded with, so they load again from that input's `initialPageParam`.
+*/
+function dropUnkeptPages(entry) {
+	const keep = entry.options?.["~keep"];
+	if (keep && entry.state.hasData && !keep(entry.state.data)) reset(entry);
+}
 function waitFresh(entry, pages) {
 	if (isFresh(entry)) return Promise.resolve({ ok: true });
 	return fetchEntry(entry, { pages });
@@ -93,10 +109,12 @@ function waitAny(entry, pages) {
 *
 * ```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
 */
 async function load(client, entries) {
 	const started = Object.entries(entries).flatMap(([name, item]) => item === skipToken ? [] : [{
@@ -105,8 +123,13 @@ async function load(client, entries) {
 	}]).map((loaded) => {
 		const item = loaded.item;
 		const cached = entryOf(client, item.factory, item.input);
+		dropUnkeptPages(cached);
 		let wait;
 		if (item.kind === "prefetch") startIfStale(cached);
+		else if (isBrowserOnly(cached) && !cached.state.hasData) wait = Promise.resolve({
+			error: /* @__PURE__ */ new Error(`raf-query: ${cached.hash} has \`ssr: false\`, so the server can't wait for it. Load it with prefetch() instead of ${item.kind}().`),
+			ok: false
+		});
 		else wait = (item.kind === "revalidate" ? waitFresh : waitAny)(cached, item.pages);
 		return {
 			entry: cached,

package/dist/options.d.mts

@@ -1,7 +1,20 @@
 import { QueryKey } from "./keys/keys.mjs";
 import { AnyRoot, DefaultTypes, RootOf, RootTag, RootTypes } from "./root.mjs";
+import { QueryClient } from "./client.mjs";
 //#region src/options.d.ts
+/**
+ * What a `queryFn` gets: the client making the request, the query's key,
+ * `meta` and abort `signal`.
+ *
+ * @see https://raf-query.katt.dev/docs/query-functions#the-query-function-context
+ */
 export interface QueryFunctionContext<TKey extends QueryKey = QueryKey> {
+  /**
+   * The client making the request. A server makes one per request, so it
+   * keys per-request services, such as an API client with the request's
+   * cookies.
+   */
+  readonly client: QueryClient;
   /** The query's `meta`, typed by its root where the query is defined. */
   readonly meta: object;
   readonly queryKey: TKey;
@@ -9,6 +22,7 @@ export interface QueryFunctionContext<TKey extends QueryKey = QueryKey> {
   readonly signal: AbortSignal;
 }
 declare const dataTag: unique symbol;
+declare const queryFnDataTag: unique symbol;
 /** Options every query takes. */
 export interface BaseOptions<TKey extends QueryKey, TTypes extends RootTypes = RootTypes> {
   /** How long an entry with no reader stays cached. Default 5 minutes; never on the server. */
@@ -21,22 +35,48 @@ export interface BaseOptions<TKey extends QueryKey, TTypes extends RootTypes = R
   readonly meta?: NoInfer<Partial<TTypes["meta"]>>;
   /** A plain array, usually built by a `group()`. Handles keep its literal type. */
   readonly queryKey: TKey;
+  /**
+   * `false` for a query only a browser can run (a permission, the service
+   * worker, `localStorage`): a server client never starts it, never sends
+   * it, and reads it as not loaded yet, so the browser runs it once it
+   * renders. Default `true`.
+   *
+   * @see https://raf-query.katt.dev/docs/ssr-and-hydration#browser-only-queries
+   */
+  readonly ssr?: boolean;
   /** How long data stays fresh, in ms. Default `0`. */
   readonly staleTime?: number;
   /** Keep the deeply equal parts of new data, so they keep their identity. Default `true`. */
   readonly structuralSharing?: boolean;
 }
-/** What `queryOptions` and `infiniteQueryOptions` return. */
+/**
+ * What `queryOptions` and `infiniteQueryOptions` return.
+ *
+ * @see https://raf-query.katt.dev/docs/api-reference#query-factories
+ */
 export interface QueryOptions<TKey extends QueryKey = QueryKey, TQueryFnData = unknown, TData = TQueryFnData, TTypes extends RootTypes = RootTypes> extends BaseOptions<TKey, TTypes> {
+  /** Set by `infiniteQueryOptions` from `keepPages`: whether `load` keeps the cached pages. */
+  readonly "~keep"?: (data: never) => boolean;
   /** Phantom: the root the builder is bound to. Never set at runtime. */
   readonly "~root"?: RootTag<TTypes>;
   /** Set by `infiniteQueryOptions`: runs the request page by page. */
   readonly "~run"?: (op: never) => Promise<unknown>;
   readonly [dataTag]?: TData;
   readonly queryFn: (context: never) => unknown;
+  /**
+   * Phantom: the `queryFn`'s data, before `select`. What `setData` writes,
+   * read from a property rather than `select`'s parameter, so a factory
+   * built inline by a generic maker still infers where it's passed.
+   */
+  readonly [queryFnDataTag]?: TQueryFnData;
   readonly select?: (data: TQueryFnData) => TData;
   readonly stream?: StreamOptions<TQueryFnData, never>;
 }
+/**
+ * How a `queryFn` that returns an async iterable folds its chunks into data.
+ *
+ * @see https://raf-query.katt.dev/docs/query-functions#streaming
+ */
 export interface StreamOptions<TData, TChunk> {
   /** The data before the first chunk. */
   readonly initial: TData;
@@ -50,7 +90,11 @@ type Awaitable<T> = PromiseLike<T> | T;
  * doesn't widen it.
  */
 export type FromQueryFn<T> = T extends unknown ? T : never;
-/** `queryOptions`, with `meta` checked against the root `TTypes`. */
+/**
+ * `queryOptions`, with `meta` checked against the root `TTypes`.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
+ */
 export interface QueryOptionsBuilder<TTypes extends RootTypes> {
   <const TKey extends QueryKey, TChunk, TData>(options: BaseOptions<TKey, TTypes> & {
     readonly queryFn: (context: QueryFunctionContext<TKey>) => AsyncIterable<TChunk>;
@@ -65,10 +109,10 @@ export interface QueryOptionsBuilder<TTypes extends RootTypes> {
  * Typed options for a query factory:
  *
  * ```ts
- * export const issueQuery = (input: { id: number }) =>
+ * export const postQuery = (input: { slug: string }) =>
  *   queryOptions({
- *     queryKey: issues("byId", input),
- *     queryFn: ({ signal }) => getIssue(input.id, { signal }),
+ *     queryKey: posts(input.slug),
+ *     queryFn: ({ signal }) => getPost(input.slug, { signal }),
  *   });
  * ```
  *
@@ -78,6 +122,8 @@ export interface QueryOptionsBuilder<TTypes extends RootTypes> {
  *
  * Its `meta` is any record. To check `meta` against a client's links and
  * features, use the builder {@link bindQueryOptions} returns.
+ *
+ * @see https://raf-query.katt.dev/docs/query-factories
  */
 export declare const queryOptions: QueryOptionsBuilder<DefaultTypes>;
 /**
@@ -91,6 +137,8 @@ export declare const queryOptions: QueryOptionsBuilder<DefaultTypes>;
  * ```
  *
  * It returns `queryOptions` itself; only the types change.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
  */
 export declare function bindQueryOptions<T>(): QueryOptionsBuilder<RootOf<T>>;
 /**
@@ -99,6 +147,8 @@ export declare function bindQueryOptions<T>(): QueryOptionsBuilder<RootOf<T>>;
  * every factory fits, and an inline generic factory maker passed where a
  * `QueryFactory` is expected infers its own type parameters instead of
  * `never`.
+ *
+ * @see https://raf-query.katt.dev/docs/query-factories
  */
 export type QueryFactory = {
   factory(input: unknown): {
@@ -106,23 +156,43 @@ export type QueryFactory = {
     readonly queryKey: QueryKey;
   };
 }["factory"];
-/** A factory whose query has one value, not pages: what `useQuery` reads. */
+/**
+ * A factory whose query has one value, not pages: what `useQuery` reads.
+ *
+ * @see https://raf-query.katt.dev/docs/query-factories
+ */
 export type SingleQueryFactory = {
   factory(input: unknown): ReturnType<QueryFactory> & {
     readonly getNextPageParam?: never;
   };
 }["factory"];
-/** A factory of paged queries (`infiniteQueryOptions`): what `useInfiniteQuery` reads. */
+/**
+ * A factory of paged queries (`infiniteQueryOptions`): what `useInfiniteQuery` reads.
+ *
+ * @see https://raf-query.katt.dev/docs/query-factories
+ */
 export type InfiniteQueryFactory = {
   factory(input: unknown): ReturnType<QueryFactory> & {
     readonly getNextPageParam: (...args: never) => unknown;
   };
 }["factory"];
-/** What a reader gets: the `select`ed data, or else the `queryFn`'s. */
+/** The `queryFn`'s data, before `select`: what `setData` writes and `getData` reads. */
+export type QueryFnDataOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends {
+  readonly [queryFnDataTag]?: infer TData;
+} ? TData : unknown;
+/**
+ * What a reader gets: the `select`ed data, or else the `queryFn`'s.
+ *
+ * @see https://raf-query.katt.dev/docs/query-factories#type-inference
+ */
 export type DataOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends {
   readonly [dataTag]?: infer TData;
 } ? TData : never;
-/** A factory's input: its first parameter, or `undefined` if it takes none. */
+/**
+ * A factory's input: its first parameter, or `undefined` if it takes none.
+ *
+ * @see https://raf-query.katt.dev/docs/query-factories#type-inference
+ */
 export type InputOf<TFactory extends QueryFactory> = Parameters<TFactory> extends [] ? undefined : Parameters<TFactory>[0];
 /** The input arguments of a factory: none, or its input. */
 export type InputArgs<TFactory extends QueryFactory> = Parameters<TFactory> extends [] ? [] : Parameters<TFactory> extends [infer TInput, ...Array<unknown>] ? [input: TInput] : [input?: Parameters<TFactory>[0]];

package/dist/options.mjs

@@ -3,10 +3,10 @@
 * Typed options for a query factory:
 *
 * ```ts
-* export const issueQuery = (input: { id: number }) =>
+* export const postQuery = (input: { slug: string }) =>
 *   queryOptions({
-*     queryKey: issues("byId", input),
-*     queryFn: ({ signal }) => getIssue(input.id, { signal }),
+*     queryKey: posts(input.slug),
+*     queryFn: ({ signal }) => getPost(input.slug, { signal }),
 *   });
 * ```
 *
@@ -16,6 +16,8 @@
 *
 * Its `meta` is any record. To check `meta` against a client's links and
 * features, use the builder {@link bindQueryOptions} returns.
+*
+* @see https://raf-query.katt.dev/docs/query-factories
 */
 const queryOptions = (options) => options;
 /**
@@ -29,6 +31,8 @@ const queryOptions = (options) => options;
 * ```
 *
 * It returns `queryOptions` itself; only the types change.
+*
+* @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
 */
 function bindQueryOptions() {
 	return queryOptions;

package/dist/presets.d.mts

@@ -4,7 +4,11 @@ import { ReconnectRefetchMeta } from "./features/reconnect-refetch/reconnect-ref
 import { PollingMeta } from "./features/polling/polling.mjs";
 import { RetryMeta } from "./links/retry/retry.mjs";
 //#region src/presets.d.ts
-/** What `recommended()` returns: its parts keep the `meta` they declare. */
+/**
+ * What `recommended()` returns: its parts keep the `meta` they declare.
+ *
+ * @see https://raf-query.katt.dev/docs/important-defaults
+ */
 export interface Recommended {
   readonly features: readonly [Feature<{
     readonly meta: FocusRefetchMeta;
@@ -24,6 +28,8 @@ export interface Recommended {
  * ```ts
  * createQueryClient({ ...recommended(), staleTime: 30_000 });
  * ```
+ *
+ * @see https://raf-query.katt.dev/docs/important-defaults
  */
 export declare function recommended(): Recommended;
 //#endregion

package/dist/presets.mjs

@@ -10,6 +10,8 @@ import { retry } from "./links/retry/retry.mjs";
 * ```ts
 * createQueryClient({ ...recommended(), staleTime: 30_000 });
 * ```
+*
+* @see https://raf-query.katt.dev/docs/important-defaults
 */
 function recommended() {
 	return {

package/dist/root.d.mts

@@ -5,7 +5,11 @@
  * parts declare, and builders bound to a root (`bindQueryOptions`) carry it
  * as a phantom on the options they build.
  */
-/** A query's `meta` when its builder isn't bound to a root. */
+/**
+ * A query's `meta` when its builder isn't bound to a root.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features
+ */
 export type QueryMeta = Readonly<Record<string, unknown>>;
 /** What a link or feature declares: the `meta` fields it reads. */
 export interface Decl {

package/dist/thenable.d.mts

@@ -3,6 +3,8 @@
  * Promises that carry their own result in the fields React's `use()` reads
  * before suspending (`status`, `value`, `reason`). A settled one is read
  * synchronously, so React renders it without a fallback.
+ *
+ * @see https://raf-query.katt.dev/docs/reading-queries
  */
 export type Thenable<T> = Promise<T> & ({
   readonly reason: unknown;

package/dist/verbs.d.mts

@@ -1,19 +1,22 @@
 import { Group } from "./keys/keys.mjs";
 import { IsAnyRoot, RootTypes } from "./root.mjs";
 import { AnyInvalidation, AnyTarget, ParamArgs, Target } from "./keys/targets.mjs";
-import { InputArgs, InputOf, QueryFactory, RootOfFactory } from "./options.mjs";
+import { InputArgs, InputOf, QueryFactory, QueryFnDataOf, RootOfFactory } from "./options.mjs";
 import { QueryClient } from "./client.mjs";
-import { InfiniteData } from "./infinite/infinite.mjs";
 //#region src/verbs.d.ts
 type DeepPartial<T> = T extends object ? { readonly [TName in keyof T]?: DeepPartial<T[TName]>; } : T;
 /**
  * What `invalidateMany(factory, partial)` takes: part of the factory's
  * input, whatever its key looks like.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation
  */
 export type PartialInput<TFactory extends QueryFactory> = DeepPartial<InputOf<TFactory>>;
 /**
  * The clients a factory's verbs take: its root's, or any client for a
  * factory from an unbound builder.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
  */
 export type ClientFor<TFactory extends QueryFactory> = QueryClient<RootOfFactory<TFactory>>;
 /**
@@ -42,12 +45,12 @@ type Item<TTypes extends RootTypes, TItem> = TItem extends Group ? Group : TItem
  */
 export type TargetList<TTypes extends RootTypes, TItems extends ReadonlyArray<unknown>> = { readonly [TIndex in keyof TItems]: Item<TTypes, TItems[TIndex]>; };
 /** The data `setData` writes: plain for a query, paged for an infinite one. */
-type WritableData<TFactory extends QueryFactory> = ReturnType<TFactory> extends {
-  readonly select?: (data: infer TData) => unknown;
-} ? TData : InfiniteData<unknown>;
+type WritableData<TFactory extends QueryFactory> = QueryFnDataOf<TFactory>;
 /**
  * Mark one query stale: a factory and its full input. If it's read, it
  * refetches; resolves when that settles.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation
  */
 export declare function invalidateOne<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): Promise<void>;
 /**
@@ -62,35 +65,63 @@ export declare function invalidateOne<TFactory extends QueryFactory>(client: Cli
  * call after another runs them one after another instead.
  *
  * ```ts
- * await invalidateMany(client, [todos, [issuesQuery, { status: "open" }], [ownedBy, "billing"]]);
+ * await invalidateMany(client, [authors, [commentsQuery, { slug }], [ownedBy, "editorial"]]);
  * ```
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#several-targets
  */
 export declare function invalidateMany<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, partial?: PartialInput<TFactory>): Promise<void>;
 export declare function invalidateMany(client: QueryClient, group: Group): Promise<void>;
 export declare function invalidateMany<TTypes extends RootTypes, TParam = never>(client: QueryClient<TTypes>, target: TargetFor<TTypes, TParam>, ...param: ParamArgs<NoInfer<TParam>>): Promise<void>;
 export declare function invalidateMany<TTypes extends RootTypes, const TItems extends ReadonlyArray<unknown>>(client: QueryClient<TTypes>, targets: TargetList<TTypes, TItems>): Promise<void>;
-/** Mark every query stale; read ones refetch. For sign-out, or after any write. */
+/**
+ * Mark every query stale; read ones refetch. For sign-out, or after any write.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation
+ */
 export declare function invalidateAll(client: QueryClient): Promise<void>;
 /**
  * Drop one query's data and error. If it's read, it suspends and refetches;
  * resolves when that settles.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
  */
 export declare function resetOne<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): Promise<void>;
-/** {@link resetOne} for every query a target, or a list of them, covers. */
+/**
+ * {@link resetOne} for every query a target, or a list of them, covers.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+ */
 export declare function resetMany<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, partial?: PartialInput<TFactory>): Promise<void>;
 export declare function resetMany(client: QueryClient, group: Group): Promise<void>;
 export declare function resetMany<TTypes extends RootTypes, TParam = never>(client: QueryClient<TTypes>, target: TargetFor<TTypes, TParam>, ...param: ParamArgs<NoInfer<TParam>>): Promise<void>;
 export declare function resetMany<TTypes extends RootTypes, const TItems extends ReadonlyArray<unknown>>(client: QueryClient<TTypes>, targets: TargetList<TTypes, TItems>): Promise<void>;
-/** {@link resetOne} for every query. */
+/**
+ * {@link resetOne} for every query.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+ */
 export declare function resetAll(client: QueryClient): Promise<void>;
-/** Remove one query from the cache, aborting its request. */
+/**
+ * Remove one query from the cache, aborting its request.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+ */
 export declare function removeOne<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): void;
-/** {@link removeOne} for every query a target, or a list of them, covers. */
+/**
+ * {@link removeOne} for every query a target, or a list of them, covers.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+ */
 export declare function removeMany<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, partial?: PartialInput<TFactory>): void;
 export declare function removeMany(client: QueryClient, group: Group): void;
 export declare function removeMany<TTypes extends RootTypes, TParam = never>(client: QueryClient<TTypes>, target: TargetFor<TTypes, TParam>, ...param: ParamArgs<NoInfer<TParam>>): void;
 export declare function removeMany<TTypes extends RootTypes, const TItems extends ReadonlyArray<unknown>>(client: QueryClient<TTypes>, targets: TargetList<TTypes, TItems>): void;
-/** Remove every query, aborting their requests. */
+/**
+ * Remove every query, aborting their requests.
+ *
+ * @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+ */
 export declare function removeAll(client: QueryClient): void;
 /** New data for `setData`, or a function from the current data to it. */
 type Updater<TFactory extends QueryFactory> = ((previous: WritableData<TFactory> | undefined) => WritableData<TFactory>) | WritableData<TFactory>;
@@ -98,12 +129,22 @@ type Updater<TFactory extends QueryFactory> = ((previous: WritableData<TFactory>
  * Write a query's data, as if a request had just returned it. `updater`
  * gets the current data, or `undefined` if there is none. A factory that
  * takes no input (or an optional one) skips the input:
- * `setData(client, todosQuery, updater)`.
+ * `setData(client, feedQuery, updater)`.
+ *
+ * @see https://raf-query.katt.dev/docs/mutations#updates-from-mutation-responses
  */
 export declare function setData<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...updater: [] extends Parameters<TFactory> ? [updater: Updater<TFactory>] : never): void;
 export declare function setData<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, input: Parameters<TFactory> extends [] ? never : Parameters<TFactory>[0], updater: Updater<TFactory>): void;
-/** A query's cached data (before `select`), or `undefined`. */
+/**
+ * A query's cached data (before `select`), or `undefined`.
+ *
+ * @see https://raf-query.katt.dev/docs/api-reference#changing-the-cache
+ */
 export declare function getData<TFactory extends QueryFactory>(client: ClientFor<TFactory>, factory: TFactory, ...input: InputArgs<TFactory>): WritableData<TFactory> | undefined;
-/** How many queries have a request in flight, optionally only a factory's, a group's or a target's. */
+/**
+ * How many queries have a request in flight, optionally only a factory's, a group's or a target's.
+ *
+ * @see https://raf-query.katt.dev/docs/background-fetching-indicators
+ */
 export declare function isFetching(client: QueryClient, target?: AnyInvalidation): number;
 //#endregion

package/dist/verbs.mjs

@@ -20,6 +20,8 @@ function settle(outcomes) {
 /**
 * Mark one query stale: a factory and its full input. If it's read, it
 * refetches; resolves when that settles.
+*
+* @see https://raf-query.katt.dev/docs/query-invalidation
 */
 function invalidateOne(client, factory, ...input) {
 	return invalidate(client, (at) => [entryStamp(hashOf(factory, input[0]), at)]);
@@ -27,7 +29,11 @@ function invalidateOne(client, factory, ...input) {
 function invalidateMany(client, target, partial) {
 	return invalidate(client, (at) => stampsOf(target, partial, at));
 }
-/** Mark every query stale; read ones refetch. For sign-out, or after any write. */
+/**
+* Mark every query stale; read ones refetch. For sign-out, or after any write.
+*
+* @see https://raf-query.katt.dev/docs/query-invalidation
+*/
 function invalidateAll(client) {
 	return invalidate(client, (at) => [{
 		at,
@@ -40,6 +46,8 @@ function oneEntry(client, factory, input) {
 /**
 * Drop one query's data and error. If it's read, it suspends and refetches;
 * resolves when that settles.
+*
+* @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
 */
 function resetOne(client, factory, ...input) {
 	const entry = oneEntry(client, factory, input[0]);
@@ -48,11 +56,19 @@ function resetOne(client, factory, ...input) {
 function resetMany(client, target, partial) {
 	return settle(entriesMatching(client, stampsOf(target, partial, 0)).map(reset));
 }
-/** {@link resetOne} for every query. */
+/**
+* {@link resetOne} for every query.
+*
+* @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+*/
 function resetAll(client) {
 	return settle([...client["~entries"].values()].map(reset));
 }
-/** Remove one query from the cache, aborting its request. */
+/**
+* Remove one query from the cache, aborting its request.
+*
+* @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+*/
 function removeOne(client, factory, ...input) {
 	const entry = oneEntry(client, factory, input[0]);
 	if (entry) remove(entry);
@@ -60,7 +76,11 @@ function removeOne(client, factory, ...input) {
 function removeMany(client, target, partial) {
 	for (const entry of entriesMatching(client, stampsOf(target, partial, 0))) remove(entry);
 }
-/** Remove every query, aborting their requests. */
+/**
+* Remove every query, aborting their requests.
+*
+* @see https://raf-query.katt.dev/docs/query-invalidation#invalidate-reset-or-remove
+*/
 function removeAll(client) {
 	for (const entry of client["~entries"].values()) remove(entry);
 }
@@ -71,12 +91,20 @@ function setData(client, factory, ...args) {
 	const data = isFunction(updater) ? updater(previous) : updater;
 	write(entry, data, client.clock.now(), ++client["~seq"]);
 }
-/** A query's cached data (before `select`), or `undefined`. */
+/**
+* A query's cached data (before `select`), or `undefined`.
+*
+* @see https://raf-query.katt.dev/docs/api-reference#changing-the-cache
+*/
 function getData(client, factory, ...input) {
 	const entry = oneEntry(client, factory, input[0]);
 	return entry?.state.hasData ? entry.state.data : void 0;
 }
-/** How many queries have a request in flight, optionally only a factory's, a group's or a target's. */
+/**
+* How many queries have a request in flight, optionally only a factory's, a group's or a target's.
+*
+* @see https://raf-query.katt.dev/docs/background-fetching-indicators
+*/
 function isFetching(client, target) {
 	return entriesMatching(client, [target === void 0 ? {
 		at: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/core",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",