@raf-query/core 0.11.1 → 0.13.0

package/dist/options.d.mts

@@ -1,374 +1,203 @@
-import { QueryKey } from "./key.mjs";
-import { Effect, Schedule } from "effect";
+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
 /**
- * The types of a plain query: what its `queryFn` resolves to, for an Effect
- * `queryFn` its error and the services it needs, and the shape of its key.
- * Leave `error` out and it is `unknown` (promises reject with anything);
- * leave `services` out and it is `never`; leave `key` out and it is any
- * {@link QueryKey}. `throwOnError` is the query's `throwOnError` option;
- * leave it out when the query doesn't set one.
+ * What a `queryFn` gets: the client making the request, the query's key,
+ * `meta` and abort `signal`.
  *
- * ```ts
- * type PostOptions = QueryOptions<{ data: Post }>;
- * ```
- */
-export interface QueryTypes {
-  readonly data: unknown;
-  readonly error?: unknown;
-  readonly key?: QueryKey;
-  readonly services?: unknown;
-  readonly throwOnError?: boolean;
-}
-/**
- * The types of a paged query: one page, the param that loads it, and as in
- * {@link QueryTypes}, an Effect `queryFn`'s error and services, the key and
- * `throwOnError`.
- */
-export interface InfiniteQueryTypes {
-  readonly error?: unknown;
-  readonly key?: QueryKey;
-  readonly page: unknown;
-  readonly pageParam: unknown;
-  readonly services?: unknown;
-  readonly throwOnError?: boolean;
-}
-/** `error` of a types bag, `unknown` when it has none. */
-type ErrorIn<TTypes> = TTypes extends {
-  readonly error: infer TError;
-} ? TError : unknown;
-/** `services` of a types bag, `never` when it has none. */
-type ServicesIn<TTypes> = TTypes extends {
-  readonly services: infer TServices;
-} ? TServices : never;
-/** `key` of a types bag, any {@link QueryKey} when it has none. */
-type KeyIn<TTypes> = TTypes extends {
-  readonly key: infer TKey extends QueryKey;
-} ? TKey : QueryKey;
-/** `throwOnError` of a types bag, `undefined` when it has none. */
-type ThrowIn<TTypes> = TTypes extends {
-  readonly throwOnError: infer TThrow extends boolean;
-} ? TThrow : undefined;
-/** One object type for an intersection, so bags read as written. */
-type Flat<T> = { [K in keyof T]: T[K]; };
-type ErrorPart<TError> = unknown extends TError ? unknown : {
-  error: TError;
-};
-type ServicesPart<TServices> = [TServices] extends [never] ? unknown : {
-  services: TServices;
-};
-type ThrowPart<TThrow> = [TThrow] extends [boolean] ? {
-  throwOnError: TThrow;
-} : unknown;
-/**
- * The bag `queryOptions` returns. `error` is left out when the `queryFn`
- * doesn't name one (`unknown`: a promise or a plain value). `services` is
- * left out when the `queryFn` needs none (`never`). An Effect's error,
- * including `never` when it can't fail, stays. `key` is always there, so two
- * factories with different key shapes have different types. `throwOnError`
- * is there when the options set it.
- */
-type QueryTypesOf<TData, TError, TServices, TKey, TThrow> = Flat<{
-  data: TData;
-  key: TKey;
-} & ErrorPart<TError> & ServicesPart<TServices> & ThrowPart<TThrow>>;
-/** As {@link QueryTypesOf}, for a paged query. */
-type InfiniteQueryTypesOf<TPage, TPageParam, TError, TServices, TKey, TThrow> = Flat<{
-  key: TKey;
-  page: TPage;
-  pageParam: TPageParam;
-} & ErrorPart<TError> & ServicesPart<TServices> & ThrowPart<TThrow>>;
-/**
- * What a `queryFn` may return: a value, a promise, or an `Effect`. An
- * Effect's error type becomes the query's (promises reject with `unknown`),
- * and the services it needs become requirements of the verbs that start it.
+ * @see https://raf-query.katt.dev/docs/query-functions#the-query-function-context
  */
-export type QueryFnResult<TTypes extends QueryTypes> = TTypes["data"] | PromiseLike<TTypes["data"]> | Effect.Effect<TTypes["data"], ErrorIn<TTypes>, ServicesIn<TTypes>>;
-/**
- * App-wide types, filled in by module augmentation. Declare `queryMeta` to
- * type every query's `meta`. Augment the package you import from;
- * `@raf-query/react` re-exports this interface, so either works:
- *
- * ```ts
- * declare module "@raf-query/react" {
- *   interface Register {
- *     queryMeta: { errorMessage?: string };
- *   }
- * }
- * ```
- */
-export interface Register {}
-/**
- * Type of a query's `meta`. `Record<string, unknown>` unless `queryMeta` is
- * declared on {@link Register}.
- */
-export type QueryMeta = Register extends {
-  queryMeta: infer TQueryMeta;
-} ? TQueryMeta : Record<string, unknown>;
-export interface QueryFunctionContext {
-  /** The query's `meta` when this request started ({@link QueryBehavior.meta}). */
-  readonly meta: QueryMeta | undefined;
-  /** 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. `QueryCache` defaults fill in the rest. */
-export interface QueryBehavior {
+export interface QueryFunctionContext<TKey extends QueryKey = QueryKey> {
   /**
-   * `false` keeps the query from running. Default `true`. The factory
-   * decides per call, so `enabled: typeof window !== "undefined"` runs a
-   * query only in the browser, for data only a browser has (permissions,
-   * device APIs, `localStorage`).
-   *
-   * While disabled, readers see `isPending`, `ensure` and `fetch` fail with
-   * `Query.DisabledError`, and `invalidate`, `reset` and `refetch` do
-   * nothing. In the browser, its promise stays pending until a factory
-   * call returns `true` and runs it. A server cache never sends it, and its
-   * promise rejects with `Query.DisabledError`: under Suspense, React
-   * renders the fallback on the server and the component in the browser.
+   * 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 enabled?: boolean;
-  /** How long an unread entry stays cached, in ms. `Infinity` keeps it. */
+  readonly client: QueryClient;
+  /** The query's `meta`, typed by its root where the query is defined. */
+  readonly meta: object;
+  readonly queryKey: TKey;
+  /** Aborted when the request is restarted or its entry is removed. */
+  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. */
   readonly gcTime?: number;
   /**
-   * Anything to know about the query elsewhere: the `queryFn` context,
-   * `Query.metaUnsafe(query)` (e.g. in the client's `onError`), devtools. A
-   * query's own `meta` replaces the default's as a whole.
+   * Settings for the root's links and features, and data for targets: the
+   * fields the root's parts declare, such as `retry` with the `retry()`
+   * link.
    */
-  readonly meta?: QueryMeta;
-  /** 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;
+  readonly meta?: NoInfer<Partial<TTypes["meta"]>>;
+  /** A plain array, usually built by a `group()`. Handles keep its literal type. */
+  readonly queryKey: TKey;
   /**
-   * Keep the parts of new data that are deeply equal to the old data, so
-   * unchanged objects keep their identity and unchanged data keeps its
-   * promise. Compares plain objects and arrays. Default `true`.
+   * `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;
 }
-declare const servicesType: unique symbol;
-interface ServicesField<TServices> {
-  /**
-   * Type-only: the services the `queryFn`'s Effect needs. Never present at
-   * runtime. A `queryFn`'s return type can't carry them on its own: with
-   * `unknown` data, any return type is assignable to `QueryFnResult`.
-   */
-  readonly [servicesType]?: () => TServices;
-}
-interface ThrowOnErrorField<TThrow> {
+/**
+ * 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> {
+  /** 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;
   /**
-   * How reads of this query settle on failure when they don't set
-   * `throwOnError` themselves: `true` rejects (to an error boundary),
-   * `false` settles with a `Result`. Omit it for the client's default.
-   * Only an Effect `queryFn`'s typed error reads as a `Result`; a promise
-   * `queryFn` always rejects.
+   * 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 throwOnError?: TThrow;
-}
-export interface QueryOptions<TTypes extends QueryTypes> extends QueryBehavior, ServicesField<ServicesIn<TTypes>>, ThrowOnErrorField<ThrowIn<TTypes>> {
-  readonly kind: "query";
-  queryFn(context: QueryFunctionContext): QueryFnResult<TTypes>;
-  readonly queryKey: KeyIn<TTypes>;
+  readonly [queryFnDataTag]?: TQueryFnData;
+  readonly select?: (data: TQueryFnData) => TData;
+  readonly stream?: StreamOptions<TQueryFnData, never>;
 }
 /**
- * The functions of paged options, typed by the page and page param types
- * themselves. Typed through the bag, inference breaks: TypeScript fixes
- * every type parameter a contextually typed parameter's type mentions, so
- * `context` would fix the page type before `queryFn`'s return could infer it.
+ * How a `queryFn` that returns an async iterable folds its chunks into data.
+ *
+ * @see https://raf-query.katt.dev/docs/query-functions#streaming
  */
-interface PageFunctions<TPage, TPageParam, TResult> {
-  /** 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;
-  queryFn(context: PageFunctionContext<TPageParam>): TResult;
+export interface StreamOptions<TData, TChunk> {
+  /** The data before the first chunk. */
+  readonly initial: TData;
+  /** Fold a chunk into the data. */
+  readonly reduce: (data: TData, chunk: TChunk) => TData;
 }
-export interface InfiniteQueryOptions<TTypes extends InfiniteQueryTypes> extends PageFunctions<TTypes["page"], TTypes["pageParam"], QueryFnResult<{
-  data: TTypes["page"];
-  error: ErrorIn<TTypes>;
-  services: ServicesIn<TTypes>;
-}>>, QueryBehavior, ServicesField<ServicesIn<TTypes>>, ThrowOnErrorField<ThrowIn<TTypes>> {
-  readonly initialPageParam: TTypes["pageParam"];
-  readonly kind: "infinite";
-  /** Keep at most this many pages; the far end is dropped when paging. */
-  readonly maxPages?: number;
-  readonly queryKey: KeyIn<TTypes>;
-}
-/** Data of a paged query. */
-export interface InfiniteData<TTypes extends Pick<InfiniteQueryTypes, "page" | "pageParam">> {
-  readonly pageParams: ReadonlyArray<TTypes["pageParam"]>;
-  readonly pages: ReadonlyArray<TTypes["page"]>;
+type Awaitable<T> = PromiseLike<T> | T;
+/**
+ * `T` as a conditional type, so a builder infers its data type from the
+ * `queryFn` alone: an annotated `select` or `getNextPageParam` parameter
+ * doesn't widen it.
+ */
+export type FromQueryFn<T> = T extends unknown ? T : never;
+/**
+ * `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>;
+    readonly stream: StreamOptions<TData, TChunk>;
+  }): QueryOptions<TKey, TData, TData, TTypes>;
+  <const TKey extends QueryKey, TQueryFnData, TData = TQueryFnData>(options: BaseOptions<TKey, TTypes> & {
+    readonly queryFn: (context: QueryFunctionContext<TKey>) => Awaitable<TQueryFnData>;
+    readonly select?: (data: FromQueryFn<TQueryFnData>) => TData;
+  }): QueryOptions<TKey, TQueryFnData, TData, TTypes>;
 }
-export type AnyQueryOptions = QueryOptions<{
-  data: unknown;
-  error: unknown;
-  services: unknown;
-  throwOnError: boolean;
-}> | InfiniteQueryOptions<{
-  error: unknown;
-  page: unknown;
-  pageParam: unknown;
-  services: unknown;
-  throwOnError: boolean;
-}>;
 /**
  * Typed options for a query factory:
  *
  * ```ts
- * export function postQuery(input: { slug: string }) {
- *   return queryOptions({
- *     queryKey: ["post", input.slug],
- *     queryFn: () => getPost(input),
+ * export const postQuery = (input: { slug: string }) =>
+ *   queryOptions({
+ *     queryKey: posts(input.slug),
+ *     queryFn: ({ signal }) => getPost(input.slug, { signal }),
  *   });
- * }
  * ```
  *
- * A `queryFn` Effect may need services; they're inferred, and every verb
- * that can start the query requires them. Its error is part of the returned
- * type. A promise or a plain value has no error to infer, so the type leaves
- * `error` out (`ErrorOf` is `unknown`).
- *
- * The key's literal type is kept too (`readonly ["post", string]`), so two
- * factories with the same input and data but different keys have different
- * types, and a handle of one doesn't type-check where the other's goes.
+ * A `queryFn` that returns an async iterable is a stream: pass `stream` to
+ * fold its chunks into the data. Readers get the data after the first chunk,
+ * and every later chunk updates it in place.
  *
- * `throwOnError: true` or `false` is kept as a literal too, so reads that
- * don't set their own follow it in their types.
+ * Its `meta` is any record. To check `meta` against a client's links and
+ * features, use the builder {@link bindQueryOptions} returns.
  *
- * The type parameters are only there for TypeScript to infer the types bag
- * from `queryFn`, `queryKey` and `throwOnError`; it can't infer a bag's
- * members. Passing them explicitly, pass `TThrow` too when setting
- * `throwOnError`.
+ * @see https://raf-query.katt.dev/docs/query-factories
  */
-export declare function queryOptions<TData, TError = unknown, TServices = never, const TKey extends QueryKey = QueryKey, TThrow extends boolean | undefined = undefined>(options: Omit<QueryOptions<{
-  data: TData;
-  error: TError;
-  key: TKey;
-  services: TServices;
-}>, "kind" | "throwOnError"> & ThrowOnErrorField<TThrow>): QueryOptions<QueryTypesOf<TData, TError, TServices, TKey, TThrow>>;
+export declare const queryOptions: QueryOptionsBuilder<DefaultTypes>;
 /**
- * Typed options for a paged query factory. The page type is inferred from
- * `queryFn`, as in {@link queryOptions}. So is an Effect `queryFn`'s error;
- * a promise or a plain value leaves `error` out. The key's literal type is
- * kept, as in {@link queryOptions}.
- */
-export declare function infiniteQueryOptions<TPage, TPageParam, TError = unknown, TServices = never, const TKey extends QueryKey = QueryKey, TThrow extends boolean | undefined = undefined>(options: Omit<InfiniteQueryOptions<{
-  error: TError;
-  key: TKey;
-  page: TPage;
-  pageParam: TPageParam;
-  services: TServices;
-}>, "kind" | "throwOnError"> & ThrowOnErrorField<TThrow>): InfiniteQueryOptions<InfiniteQueryTypesOf<TPage, TPageParam, TError, TServices, TKey, TThrow>>;
-interface FactoryResult {
-  readonly kind: "infinite" | "query";
-  readonly queryKey: QueryKey;
-}
-/**
- * A function of zero or one argument returning `queryOptions(...)` or
- * `infiniteQueryOptions(...)` whose `queryFn` needs at most `TServices`
- * (any services by default). A second parameter is a type error: the single
- * argument is the query's input, and a handle carries it.
+ * `queryOptions` bound to a root: `meta` takes the fields the root's links
+ * and features declare, and verbs take only that root's clients. `T` is the
+ * client's type, or the type of a function that makes it. Bind once per app:
  *
- * The return type names no `queryFn`, and no services for the default:
- * TypeScript infers an inline factory's `queryOptions` type arguments from
- * it, and an `unknown` there would infer `unknown` services.
- */
-export type QueryFactory<TServices = unknown> = FactorySignature<unknown extends TServices ? FactoryResult : FactoryResult & ServicesField<TServices>>["call"];
-/** A {@link QueryFactory} returning `infiniteQueryOptions(...)`. */
-export type PagedQueryFactory<TServices = unknown> = FactorySignature<unknown extends TServices ? PagedFactoryResult : PagedFactoryResult & ServicesField<TServices>>["call"];
-interface PagedFactoryResult extends FactoryResult {
-  readonly kind: "infinite";
-}
-/**
- * A method, so its `input` is checked bivariantly: a factory of any input
- * type is assignable. A verb's factory parameter is contextually typed by
- * this, and a generic factory maker called inline
- * (`qc.ensure(makeFactory(x), input)`) infers its own type parameters
- * against it. An `input: never` there would infer `never` for them.
- */
-interface FactorySignature<TResult> {
-  call(input: unknown): TResult;
-}
-/** 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; `unknown` for a factory of no
- * particular query.
- */
-export type DataOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? InfiniteData<{
-  page: TTypes["page"];
-  pageParam: TTypes["pageParam"];
-}> : ReturnType<TFactory> extends QueryOptions<infer TTypes> ? TTypes["data"] : unknown;
-/**
- * The error a factory's request fails with: the `queryFn`'s Effect error
- * type, or `unknown` for promises and plain values.
- */
-export type ErrorOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? ErrorIn<TTypes> : ReturnType<TFactory> extends QueryOptions<infer TTypes> ? ErrorIn<TTypes> : unknown;
-/**
- * The services a factory's `queryFn` Effect needs: what `ensure`, `fetch`,
- * `prefetch`, `getQuery` and `watch` require. `never` for promises and plain
- * values, and for a factory of no particular query.
+ * ```ts
+ * // raf.ts
+ * export const queryOptions = bindQueryOptions<typeof makeQueryClient>();
+ * ```
+ *
+ * It returns `queryOptions` itself; only the types change.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
  */
-export type ServicesOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? ServicesIn<TTypes> : ReturnType<TFactory> extends QueryOptions<infer TTypes> ? ServicesIn<TTypes> : never;
+export declare function bindQueryOptions<T>(): QueryOptionsBuilder<RootOf<T>>;
 /**
- * The `throwOnError` a factory's options set, `undefined` when they set
- * none (or for a factory of no particular query).
+ * A function of the query's input that returns its options. The input is a
+ * method parameter typed `unknown`, which TypeScript checks bivariantly:
+ * 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 ThrowOnErrorOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? ThrowIn<TTypes> : ReturnType<TFactory> extends QueryOptions<infer TTypes> ? ThrowIn<TTypes> : undefined;
-/** Page type of a paged factory. */
-export type PageOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? TTypes["page"] : never;
+export type QueryFactory = {
+  factory(input: unknown): {
+    readonly queryFn: (context: never) => unknown;
+    readonly queryKey: QueryKey;
+  };
+}["factory"];
 /**
- * `ensure` / `fetch` options, for {@link PagedQueryFactory paged factories}
- * only. Not generic: an options type that depends on the factory's type stops
- * a generic factory maker called inline from inferring.
+ * A factory whose query has one value, not pages: what `useQuery` reads.
+ *
+ * @see https://raf-query.katt.dev/docs/query-factories
  */
-export interface LoadOptions {
-  /** Load this many pages up front (default 1). */
-  readonly pages?: number;
-}
-declare const factoryType: unique symbol;
+export type SingleQueryFactory = {
+  factory(input: unknown): ReturnType<QueryFactory> & {
+    readonly getNextPageParam?: never;
+  };
+}["factory"];
 /**
- * The serializable reference a loader or server component hands to the
- * component that reads the query. It holds no functions.
+ * 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"];
+/** 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 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: InputOf<TFactory>;
-  readonly key: QueryKey;
-}
+export type DataOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends {
+  readonly [dataTag]?: infer TData;
+} ? TData : never;
 /**
- * A handle from `ensure` or `fetch`, with the data they waited for. `data`
- * is a snapshot from when the handle was returned; components read the live
- * entry with `useQuery`.
+ * 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 interface QueryHandleWithData<TFactory extends QueryFactory = QueryFactory> extends QueryHandle<TFactory> {
-  readonly data: DataOf<TFactory>;
-}
+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]];
+/** A factory's key type, the way handles carry it. */
+export type KeyOf<TFactory extends QueryFactory> = ReturnType<TFactory>["queryKey"];
+/** The root a factory's builder is bound to; any root for an unbound one. */
+export type RootOfFactory<TFactory extends QueryFactory> = ReturnType<TFactory> extends {
+  readonly "~root"?: RootTag<infer TTypes>;
+} ? TTypes extends DefaultTypes ? AnyRoot : TTypes : AnyRoot;
 //#endregion

package/dist/options.mjs

@@ -3,55 +3,43 @@
 * Typed options for a query factory:
 *
 * ```ts
-* export function postQuery(input: { slug: string }) {
-*   return queryOptions({
-*     queryKey: ["post", input.slug],
-*     queryFn: () => getPost(input),
+* export const postQuery = (input: { slug: string }) =>
+*   queryOptions({
+*     queryKey: posts(input.slug),
+*     queryFn: ({ signal }) => getPost(input.slug, { signal }),
 *   });
-* }
 * ```
 *
-* A `queryFn` Effect may need services; they're inferred, and every verb
-* that can start the query requires them. Its error is part of the returned
-* type. A promise or a plain value has no error to infer, so the type leaves
-* `error` out (`ErrorOf` is `unknown`).
+* A `queryFn` that returns an async iterable is a stream: pass `stream` to
+* fold its chunks into the data. Readers get the data after the first chunk,
+* and every later chunk updates it in place.
 *
-* The key's literal type is kept too (`readonly ["post", string]`), so two
-* factories with the same input and data but different keys have different
-* types, and a handle of one doesn't type-check where the other's goes.
+* Its `meta` is any record. To check `meta` against a client's links and
+* features, use the builder {@link bindQueryOptions} returns.
 *
-* `throwOnError: true` or `false` is kept as a literal too, so reads that
-* don't set their own follow it in their types.
-*
-* The type parameters are only there for TypeScript to infer the types bag
-* from `queryFn`, `queryKey` and `throwOnError`; it can't infer a bag's
-* members. Passing them explicitly, pass `TThrow` too when setting
-* `throwOnError`.
+* @see https://raf-query.katt.dev/docs/query-factories
 */
-function queryOptions(options) {
-	return {
-		...options,
-		kind: "query"
-	};
-}
+const queryOptions = (options) => options;
 /**
-* Typed options for a paged query factory. The page type is inferred from
-* `queryFn`, as in {@link queryOptions}. So is an Effect `queryFn`'s error;
-* a promise or a plain value leaves `error` out. The key's literal type is
-* kept, as in {@link queryOptions}.
+* `queryOptions` bound to a root: `meta` takes the fields the root's links
+* and features declare, and verbs take only that root's clients. `T` is the
+* client's type, or the type of a function that makes it. Bind once per app:
+*
+* ```ts
+* // raf.ts
+* export const queryOptions = bindQueryOptions<typeof makeQueryClient>();
+* ```
+*
+* It returns `queryOptions` itself; only the types change.
+*
+* @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
 */
-function infiniteQueryOptions(options) {
-	return {
-		...options,
-		kind: "infinite"
-	};
+function bindQueryOptions() {
+	return queryOptions;
 }
-/**
-* Calls a factory with an input the caller has already type-checked against
-* `InputArgs<TFactory>`.
-*/
-function optionsFor(factory, input) {
+/** Call a factory with an input its caller's types already checked. */
+function optionsOf(factory, input) {
 	return factory(input);
 }
 //#endregion
-export { infiniteQueryOptions, optionsFor, queryOptions };
+export { bindQueryOptions, optionsOf, queryOptions };