@raf-query/core 0.0.3 → 0.0.4

package/dist/hydration.d.mts

@@ -0,0 +1,50 @@
+import { QueryKey } from "./key.mjs";
+import { Query } from "./query.mjs";
+import { QueryClient } from "./client.mjs";
+//#region src/hydration.d.ts
+/**
+ * One cache entry in transit. Settled entries carry `data`; entries still
+ * loading their first data carry the request's `promise`, so the receiving
+ * cache resumes it instead of fetching again.
+ */
+export interface DehydratedQuery {
+  readonly data?: unknown;
+  readonly key: QueryKey;
+  readonly promise?: Promise<unknown>;
+  /** When `data` was fetched; `0` while pending. */
+  readonly updatedAt: number;
+}
+export interface DehydratedState {
+  readonly queries: ReadonlyArray<DehydratedQuery>;
+}
+export interface DehydrateOptions {
+  /**
+   * Which entries to send. Default: entries with data or a request in
+   * flight ({@link canDehydrate}).
+   */
+  readonly filter?: (query: Query) => boolean;
+  /**
+   * Send a pending query's rejection as-is. By default the receiving side
+   * gets a generic error, so server errors don't leak into the page; its
+   * error boundary can still retry on the client.
+   */
+  readonly keepErrors?: boolean;
+  /** Transform data before it is serialized. */
+  readonly serializeData?: (data: unknown) => unknown;
+}
+export interface HydrateOptions {
+  /** Reverse `serializeData`. */
+  readonly deserializeData?: (data: unknown) => unknown;
+}
+/** The default dehydrate filter: entries with data or a request in flight. */
+export declare function canDehydrate(query: Query): boolean;
+/** Snapshot one entry for transfer. */
+export declare function dehydrateQuery(query: Query, options?: DehydrateOptions): DehydratedQuery;
+/** Snapshot the cache for transfer to another client (server → browser). */
+export declare function dehydrate(client: QueryClient, options?: DehydrateOptions): DehydratedState;
+/**
+ * Write dehydrated entries into a client. Existing entries only take newer
+ * data; pending entries resume the sender's request.
+ */
+export declare function hydrate(client: QueryClient, state: DehydratedState, options?: HydrateOptions): void;
+//#endregion

package/dist/hydration.mjs

@@ -0,0 +1,50 @@
+import { cacheOf } from "./client.mjs";
+//#region src/hydration.ts
+const noop = () => {};
+const identity = (value) => value;
+/** The default dehydrate filter: entries with data or a request in flight. */
+function canDehydrate(query) {
+	const state = query.getState();
+	return state.hasData || state.isFetching;
+}
+/** Snapshot one entry for transfer. */
+function dehydrateQuery(query, options = {}) {
+	const state = query.getState();
+	const serialize = options.serializeData ?? identity;
+	if (state.hasData) return {
+		data: serialize(state.data),
+		key: query.key,
+		updatedAt: state.updatedAt
+	};
+	const promise = state.promise.then(serialize, (error) => {
+		throw options.keepErrors ? error : /* @__PURE__ */ new Error(`Query ${query.hash} failed`);
+	});
+	promise.catch(noop);
+	return {
+		key: query.key,
+		promise,
+		updatedAt: 0
+	};
+}
+/** Snapshot the cache for transfer to another client (server → browser). */
+function dehydrate(client, options = {}) {
+	const filter = options.filter ?? canDehydrate;
+	return { queries: client.getAll().filter(filter).map((query) => dehydrateQuery(query, options)) };
+}
+/**
+* Write dehydrated entries into a client. Existing entries only take newer
+* data; pending entries resume the sender's request.
+*/
+function hydrate(client, state, options = {}) {
+	const deserialize = options.deserializeData ?? identity;
+	const cache = cacheOf(client);
+	for (const query of state.queries) {
+		const entry = cache.entryFor(query.key);
+		const current = entry.getState();
+		if (query.updatedAt > 0) {
+			if (!current.hasData || current.updatedAt < query.updatedAt) entry.setData(deserialize(query.data), query.updatedAt);
+		} else if (query.promise && !current.hasData) entry.resume(Promise.resolve(query.promise).then(deserialize));
+	}
+}
+//#endregion
+export { canDehydrate, dehydrate, dehydrateQuery, hydrate };

package/dist/index.d.mts

@@ -1,4 +1,7 @@
-//#region src/index.d.ts
-/** Placeholder export until the core API lands. */
-export declare const name = "@raf-query/core";
-//#endregion
+import { Settled, allKeyed } from "./all-keyed.mjs";
+import { QueryKey, hashKey, matchesKey } from "./key.mjs";
+import { AnyQueryOptions, DataOf, InfiniteData, InfiniteQueryOptions, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryOptions, RetryPolicy, infiniteQueryOptions, queryOptions } from "./options.mjs";
+import { CancelledError, FetchRequest, Query, QueryObserver, QueryState } from "./query.mjs";
+import { CacheEvent, LoadArgs, QueryClient, QueryClientConfig, QueryClientEffect, QueryFilter, Updater } from "./client.mjs";
+import { DehydrateOptions, DehydratedQuery, DehydratedState, HydrateOptions, canDehydrate, dehydrate, dehydrateQuery, hydrate } from "./hydration.mjs";
+export { type AnyQueryOptions, type CacheEvent, CancelledError, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type FetchRequest, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadArgs, type LoadOptions, type PageFunctionContext, type PageOf, type Query, type QueryBehavior, QueryClient, type QueryClientConfig, type QueryClientEffect, type QueryFactory, type QueryFilter, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, type QueryObserver, type QueryOptions, type QueryState, type RetryPolicy, type Settled, type Updater, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };

package/dist/index.mjs

@@ -1,5 +1,7 @@
-//#region src/index.ts
-/** Placeholder export until the core API lands. */
-const name = "@raf-query/core";
-//#endregion
-export { name };
+import { allKeyed } from "./all-keyed.mjs";
+import { hashKey, matchesKey } from "./key.mjs";
+import { infiniteQueryOptions, queryOptions } from "./options.mjs";
+import { CancelledError } from "./query.mjs";
+import { QueryClient } from "./client.mjs";
+import { canDehydrate, dehydrate, dehydrateQuery, hydrate } from "./hydration.mjs";
+export { CancelledError, QueryClient, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };

package/dist/key.d.mts

@@ -0,0 +1,18 @@
+//#region src/key.d.ts
+/**
+ * A query's cache key. Must be JSON-serializable (plain objects, arrays and
+ * primitives): it travels inside handles.
+ */
+export type QueryKey = ReadonlyArray<unknown>;
+/**
+ * Stable string form of a key. Object keys are sorted, so `{ a, b }` and
+ * `{ b, a }` hash the same.
+ */
+export declare function hashKey(key: QueryKey): string;
+/**
+ * Whether `key` starts with `prefix`. Object segments match when every field
+ * in the prefix's segment matches, so `["posts", { sort: "new" }]` matches
+ * `["posts", { sort: "new", page: 2 }]`.
+ */
+export declare function matchesKey(key: QueryKey, prefix: QueryKey): boolean;
+//#endregion

package/dist/key.mjs

@@ -0,0 +1,36 @@
+import { Predicate } from "effect";
+//#region src/key.ts
+function isPlainRecord(value) {
+	if (!Predicate.isObject(value) || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function sortKeys(_name, value) {
+	if (!isPlainRecord(value)) return value;
+	const sorted = {};
+	for (const name of Object.keys(value).toSorted()) sorted[name] = value[name];
+	return sorted;
+}
+/**
+* Stable string form of a key. Object keys are sorted, so `{ a, b }` and
+* `{ b, a }` hash the same.
+*/
+function hashKey(key) {
+	return JSON.stringify(key, sortKeys);
+}
+function partialMatch(actual, expected) {
+	if (actual === expected) return true;
+	if (Array.isArray(actual) && Array.isArray(expected)) return actual.length === expected.length && expected.every((part, index) => partialMatch(actual[index], part));
+	if (isPlainRecord(actual) && isPlainRecord(expected)) return Object.keys(expected).every((name) => partialMatch(actual[name], expected[name]));
+	return false;
+}
+/**
+* Whether `key` starts with `prefix`. Object segments match when every field
+* in the prefix's segment matches, so `["posts", { sort: "new" }]` matches
+* `["posts", { sort: "new", page: 2 }]`.
+*/
+function matchesKey(key, prefix) {
+	return prefix.length <= key.length && prefix.every((part, index) => partialMatch(key[index], part));
+}
+//#endregion
+export { hashKey, matchesKey };

package/dist/notify.mjs

@@ -0,0 +1,21 @@
+//#region src/notify.ts
+let queued;
+/**
+* Calls `listener` in a microtask, once per batch. State changes made while
+* React renders (a fetch started by a read) must not notify subscribers
+* synchronously, and several changes in one turn should re-render once.
+*/
+function scheduleNotify(listener) {
+	if (queued) {
+		queued.add(listener);
+		return;
+	}
+	const batch = /* @__PURE__ */ new Set([listener]);
+	queued = batch;
+	queueMicrotask(() => {
+		queued = void 0;
+		for (const queuedListener of batch) queuedListener();
+	});
+}
+//#endregion
+export { scheduleNotify };

package/dist/options.d.mts

@@ -0,0 +1,111 @@
+import { QueryKey } from "./key.mjs";
+import { Effect, Schedule } from "effect";
+//#region src/options.d.ts
+/** What a `queryFn` may return: a value, a promise, or an `Effect`. */
+export type QueryFnResult<TData> = TData | PromiseLike<TData> | Effect.Effect<TData, unknown>;
+export interface QueryFunctionContext {
+  /** The query's key, as returned by the factory. */
+  readonly queryKey: QueryKey;
+  /** Aborted when the request is cancelled or superseded. */
+  readonly signal: AbortSignal;
+}
+export interface PageFunctionContext<TPageParam> extends QueryFunctionContext {
+  /** Which end of the list this page is being added to. */
+  readonly direction: "backward" | "forward";
+  readonly pageParam: TPageParam;
+}
+/**
+ * How many times to retry a failed request: `false`, `true` (forever), a
+ * count, a predicate, or an Effect `Schedule`. The predicate gets the number
+ * of failures so far (1 after the first).
+ */
+export type RetryPolicy = boolean | number | Schedule.Schedule<unknown, unknown> | ((failureCount: number, error: unknown) => boolean);
+/** Options every query accepts. `QueryClient` defaults fill in the rest. */
+export interface QueryBehavior {
+  /** How long an unread entry stays cached, in ms. `Infinity` keeps it. */
+  readonly gcTime?: number;
+  /** Refetch read, stale queries when the browser comes back online. */
+  readonly refetchOnReconnect?: boolean;
+  /** Refetch read, stale queries when the window regains focus. */
+  readonly refetchOnWindowFocus?: boolean;
+  /** Retries after a failed request. */
+  readonly retry?: RetryPolicy;
+  /** Delay before retry number `failureCount` (1-based), in ms. */
+  readonly retryDelay?: number | ((failureCount: number, error: unknown) => number);
+  /** How long data counts as fresh, in ms. Fresh data is never refetched. */
+  readonly staleTime?: number;
+}
+export interface QueryOptions<TData> extends QueryBehavior {
+  readonly kind: "query";
+  queryFn(context: QueryFunctionContext): QueryFnResult<TData>;
+  readonly queryKey: QueryKey;
+}
+export interface InfiniteQueryOptions<TPage, TPageParam> extends QueryBehavior {
+  /** Param for the page after `lastPage`, or `null` / `undefined` at the end. */
+  getNextPageParam(lastPage: TPage, pages: ReadonlyArray<TPage>, lastPageParam: TPageParam, pageParams: ReadonlyArray<TPageParam>): TPageParam | null | undefined;
+  /** Param for the page before `firstPage`, or `null` / `undefined` at the start. */
+  getPreviousPageParam?(firstPage: TPage, pages: ReadonlyArray<TPage>, firstPageParam: TPageParam, pageParams: ReadonlyArray<TPageParam>): TPageParam | null | undefined;
+  readonly initialPageParam: TPageParam;
+  readonly kind: "infinite";
+  /** Keep at most this many pages; the far end is dropped when paging. */
+  readonly maxPages?: number;
+  queryFn(context: PageFunctionContext<TPageParam>): QueryFnResult<TPage>;
+  readonly queryKey: QueryKey;
+}
+/** Data of a paged query. */
+export interface InfiniteData<TPage, TPageParam = unknown> {
+  readonly pageParams: ReadonlyArray<TPageParam>;
+  readonly pages: ReadonlyArray<TPage>;
+}
+export type AnyQueryOptions = QueryOptions<unknown> | InfiniteQueryOptions<unknown, unknown>;
+/**
+ * Typed options for a query factory:
+ *
+ * ```ts
+ * export function postQuery(input: { slug: string }) {
+ *   return queryOptions({
+ *     queryKey: ["post", input.slug],
+ *     queryFn: () => getPost(input),
+ *   });
+ * }
+ * ```
+ */
+export declare function queryOptions<TData>(options: Omit<QueryOptions<TData>, "kind">): QueryOptions<TData>;
+/** Typed options for a paged query factory. */
+export declare function infiniteQueryOptions<TPage, TPageParam>(options: Omit<InfiniteQueryOptions<TPage, TPageParam>, "kind">): InfiniteQueryOptions<TPage, TPageParam>;
+/**
+ * A function of zero or one argument returning `queryOptions(...)` or
+ * `infiniteQueryOptions(...)`. A second parameter is a type error: the single
+ * argument is the query's input, and a handle carries it.
+ */
+export type QueryFactory = (input: never) => AnyQueryOptions;
+/** The factory's input type; `undefined` for factories without one. */
+export type InputOf<TFactory extends QueryFactory> = Parameters<TFactory> extends [] ? undefined : Parameters<TFactory>[0];
+/** Arguments after the factory: the input, optional when the factory's is. */
+export type InputArgs<TFactory extends QueryFactory> = [] extends Parameters<TFactory> ? [input?: InputOf<TFactory>] : [input: InputOf<TFactory>];
+/** Whether the factory returns `infiniteQueryOptions(...)`. */
+export type IsPaged<TFactory extends QueryFactory> = ReturnType<TFactory> extends {
+  readonly kind: "infinite";
+} ? true : false;
+/** The data a factory's query resolves to. */
+export type DataOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TPage, infer TPageParam> ? InfiniteData<TPage, TPageParam> : ReturnType<TFactory> extends QueryOptions<infer TData> ? TData : never;
+/** Page type of a paged factory. */
+export type PageOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TPage, unknown> ? TPage : never;
+/** `ensure` / `fetch` options. Only paged factories accept `pages`. */
+export type LoadOptions<TFactory extends QueryFactory> = IsPaged<TFactory> extends true ? {
+  /** Load this many pages up front (default 1). */
+  readonly pages?: number;
+} : never;
+declare const factoryType: unique symbol;
+/**
+ * The serializable reference a loader or server component hands to the
+ * component that reads the query. It holds no data and no functions.
+ */
+export interface QueryHandle<TFactory extends QueryFactory = QueryFactory> {
+  /** Type-only: ties the handle to its factory. Never present at runtime. */
+  readonly [factoryType]?: TFactory;
+  /** The factory's input; `unknown` on a handle of no particular factory. */
+  readonly input: QueryFactory extends TFactory ? unknown : InputOf<TFactory>;
+  readonly key: QueryKey;
+}
+//#endregion

package/dist/options.mjs

@@ -0,0 +1,35 @@
+//#region src/options.ts
+/**
+* Typed options for a query factory:
+*
+* ```ts
+* export function postQuery(input: { slug: string }) {
+*   return queryOptions({
+*     queryKey: ["post", input.slug],
+*     queryFn: () => getPost(input),
+*   });
+* }
+* ```
+*/
+function queryOptions(options) {
+	return {
+		...options,
+		kind: "query"
+	};
+}
+/** Typed options for a paged query factory. */
+function infiniteQueryOptions(options) {
+	return {
+		...options,
+		kind: "infinite"
+	};
+}
+/**
+* Calls a factory with an input the caller has already type-checked against
+* `InputArgs<TFactory>`.
+*/
+function optionsFor(factory, input) {
+	return factory(input);
+}
+//#endregion
+export { infiniteQueryOptions, optionsFor, queryOptions };

package/dist/query.d.mts

@@ -0,0 +1,77 @@
+import { QueryKey } from "./key.mjs";
+import { AnyQueryOptions, QueryFactory, QueryHandle } from "./options.mjs";
+//#region src/query.d.ts
+/** A snapshot of one cache entry. Replaced, never mutated, on every change. */
+export interface QueryState<TData> {
+  /** Last successful data, kept through background errors. */
+  readonly data: TData | undefined;
+  /** Error of the last failed request, or `null`. */
+  readonly error: unknown;
+  /** Failed attempts of the current request, retries included. */
+  readonly failureCount: number;
+  /** Set while a paged query loads a page at one end of the list. */
+  readonly fetchDirection: "backward" | "forward" | undefined;
+  readonly hasData: boolean;
+  /** A request is in flight. */
+  readonly isFetching: boolean;
+  /** Marked stale by `invalidate`; cleared by the next successful request. */
+  readonly isInvalidated: boolean;
+  /** Older than `staleTime`, invalidated, or without data. */
+  readonly isStale: boolean;
+  /**
+   * Settles with `data`. A new promise is created per data version, already
+   * fulfilled once data exists, so React's `use()` reads it synchronously.
+   */
+  readonly promise: Promise<TData>;
+  readonly status: "error" | "pending" | "success";
+  /** When `data` was fetched (ms since epoch); `0` without data. */
+  readonly updatedAt: number;
+}
+/** Per-reader preferences, registered with {@link Query.subscribe}. */
+export interface QueryObserver {
+  readonly refetchOnReconnect?: boolean;
+  readonly refetchOnWindowFocus?: boolean;
+}
+export interface FetchRequest {
+  /** Load one more page at this end of a paged query. */
+  readonly direction?: "backward" | "forward";
+  /** Pages to load when a paged query has none yet. */
+  readonly pages?: number;
+  /** Abort an in-flight request and start over (used by `invalidate`). */
+  readonly restart?: boolean;
+}
+/**
+ * A cache entry, as seen by bindings. Obtain one with
+ * `QueryClient.getQuery(factory, input)`.
+ */
+export interface Query<TData = unknown, TFactory extends QueryFactory = QueryFactory> {
+  /** Start a request, or join the one in flight. */
+  fetch(request?: FetchRequest): Promise<TData>;
+  fetchNextPage(): Promise<void>;
+  fetchPreviousPage(): Promise<void>;
+  getState(): QueryState<TData>;
+  /** The serializable handle for this entry's factory call. */
+  readonly handle: QueryHandle<TFactory>;
+  /** Stable string form of `key`. */
+  readonly hash: string;
+  hasNextPage(): boolean;
+  hasPreviousPage(): boolean;
+  invalidate(): Promise<void>;
+  readonly key: QueryKey;
+  /** Options from the latest factory call; `undefined` for an entry only hydrated so far. */
+  readonly options: AnyQueryOptions | undefined;
+  /**
+   * The promise a render should unwrap. Starts the first request if nothing
+   * has, and retries a failed first load once its error has been shown.
+   */
+  read(): Promise<TData>;
+  /** Refetch now; resolves when the request settles. */
+  refetch(): Promise<void>;
+  /** Listen for state changes. Subscribed entries count as read. */
+  subscribe(listener: () => void, observer?: QueryObserver): () => void;
+}
+/** Thrown into a request's awaiters when the cache is cleared mid-request. */
+export declare class CancelledError extends Error {
+  constructor();
+}
+//#endregion