@raf-query/core 0.11.1 → 0.13.0

package/dist/load.d.mts

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

package/dist/load.mjs

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