@raf-query/core 0.13.2 → 0.14.0

package/dist/options.mjs

@@ -14,25 +14,34 @@
 * fold its chunks into the data. Readers get the data after the first chunk,
 * and every later chunk updates it in place.
 *
-* Its `meta` is any record. To check `meta` against a client's links and
-* features, use the builder {@link bindQueryOptions} returns.
+* It takes the core's options only, and its factories run on any client.
+* For the options and the `queryFn` context a client's parts declare, use
+* the builder {@link bindQueryOptions} returns.
 *
 * @see https://raf-query.katt.dev/docs/query-factories
 */
 const queryOptions = (options) => options;
 /**
-* `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:
+* `queryOptions` bound to a root: it takes the options the root's parts
+* declare, its `queryFn`s get their context, and its factories run on the
+* clients that have those parts. `T` is the client's type, or the type of a
+* function that makes it. Bind once per client:
 *
 * ```ts
 * // raf.ts
 * export const queryOptions = bindQueryOptions<typeof makeQueryClient>();
 * ```
 *
+* A library names the parts its factories need by their declarations, and
+* as `Optional` the ones whose options it sets where the client has them:
+*
+* ```ts
+* const queryOptions = bindQueryOptions<Convex & Optional<Retry>>();
+* ```
+*
 * It returns `queryOptions` itself; only the types change.
 *
-* @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
+* @see https://raf-query.katt.dev/docs/links-and-features#typing-options-by-the-client
 */
 function bindQueryOptions() {
 	return queryOptions;

package/dist/presets.d.mts

@@ -1,32 +1,21 @@
-import { Feature, Link } 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 { RetryMeta } from "./links/retry/retry.mjs";
+import { Part } 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 { Retry } 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 what they declare.
  *
  * @see https://raf-query.katt.dev/docs/important-defaults
  */
-export interface Recommended {
-  readonly features: readonly [Feature<{
-    readonly meta: FocusRefetchMeta;
-  }>, Feature<{
-    readonly meta: ReconnectRefetchMeta;
-  }>, Feature<{
-    readonly meta: PollingMeta;
-  }>];
-  readonly links: readonly [Link<{
-    readonly meta: RetryMeta;
-  }>];
-}
+export type Recommended = readonly [Part<Retry>, Part<FocusRefetch>, Part<ReconnectRefetch>, Part<Polling>];
 /**
  * The behaviors most apps want: retries, refetching on focus and reconnect,
- * and polling. Spread it into the config:
+ * and polling. Pass it as the client's parts, or spread it among your own:
  *
  * ```ts
- * createQueryClient({ ...recommended(), staleTime: 30_000 });
+ * createQueryClient({ parts: recommended(), defaults: { staleTime: 30_000 } });
  * ```
  *
  * @see https://raf-query.katt.dev/docs/important-defaults

package/dist/presets.mjs

@@ -5,23 +5,21 @@ import { retry } from "./links/retry/retry.mjs";
 //#region src/presets.ts
 /**
 * The behaviors most apps want: retries, refetching on focus and reconnect,
-* and polling. Spread it into the config:
+* and polling. Pass it as the client's parts, or spread it among your own:
 *
 * ```ts
-* createQueryClient({ ...recommended(), staleTime: 30_000 });
+* createQueryClient({ parts: recommended(), defaults: { staleTime: 30_000 } });
 * ```
 *
 * @see https://raf-query.katt.dev/docs/important-defaults
 */
 function recommended() {
-	return {
-		features: [
-			focusRefetch(),
-			reconnectRefetch(),
-			polling()
-		],
-		links: [retry()]
-	};
+	return [
+		retry(),
+		focusRefetch(),
+		reconnectRefetch(),
+		polling()
+	];
 }
 //#endregion
 export { recommended };

package/dist/root.d.mts

@@ -1,36 +1,45 @@
 //#region src/root.d.ts
 /**
- * Root types, the way tRPC v12 types a client from its links: each link and
- * feature declares the `meta` fields it reads, a client's `meta` is what its
- * parts declare, and builders bound to a root (`bindQueryOptions`) carry it
- * as a phantom on the options they build.
+ * Root types, the way tRPC v12 types a client from its links: each part
+ * declares the per-query options it reads and what it gives every
+ * `queryFn`, a client's root is what its parts declare, and builders bound
+ * to a root (`bindQueryOptions`) carry it as a phantom on the options they
+ * build. A client runs a factory when it has at least the parts the
+ * factory's builder names.
  */
 /**
- * A query's `meta` when its builder isn't bound to a root.
+ * What a part declares: the per-query `options` it reads, and the `context`
+ * it gives every `queryFn`.
  *
- * @see https://raf-query.katt.dev/docs/links-and-features
+ * @see https://raf-query.katt.dev/docs/links-and-features#parts
  */
-export type QueryMeta = Readonly<Record<string, unknown>>;
-/** What a link or feature declares: the `meta` fields it reads. */
 export interface Decl {
-  readonly meta?: object;
+  readonly context?: object;
+  readonly options?: object;
 }
-/** A root's types. */
-export interface RootTypes {
-  readonly meta: object;
+/** What a part that reads no option and gives no context declares. */
+export interface NoDecl {
+  readonly options?: object;
 }
-/** The root of the unbound builders. A type only, never a value. */
-export interface DefaultTypes {
-  readonly "~default": true;
-  readonly meta: QueryMeta;
+/** A root's types: what a client's parts declare, together. */
+export interface RootTypes {
+  readonly context: object;
+  readonly options: object;
 }
+declare const optionalDecl: unique symbol;
 /**
- * The root of a client typed only as `QueryClient`: any root. The one way
- * an invariant phantom takes every root.
+ * In a library's binding: a part whose options its queries set where the
+ * client has it, without needing it.
+ *
+ * ```ts
+ * const queryOptions = bindQueryOptions<Convex & Optional<Retry>>();
+ * ```
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#binding-a-library-to-parts
  */
-export type AnyRoot = any;
-/** Whether `TTypes` is {@link AnyRoot}. */
-export type IsAnyRoot<TTypes> = 0 extends 1 & TTypes ? true : false;
+export interface Optional<TDecl extends Decl> {
+  readonly [optionalDecl]?: TDecl;
+}
 /**
  * Phantom carrier of a part's declaration, `undefined` at runtime.
  * Invariant, so a part that declares nothing doesn't absorb the
@@ -42,45 +51,82 @@ export interface Declares<TDecl extends Decl> {
     readonly out: TDecl;
   };
 }
-/** Any link or feature, whatever it declares. */
-export interface AnyPart {
+/** Any part's phantom, whatever it declares. */
+export interface AnyDeclares {
   readonly "~decl"?: {
     readonly in: (decl: never) => void;
     readonly out: unknown;
   };
 }
+/** The options a declaration adds to its root. */
+export type OptionsOfDecl<TDecl> = TDecl extends {
+  readonly options?: infer TOptions extends object;
+} ? TOptions : unknown;
+/** The `queryFn` context a declaration adds to its root. */
+type ContextOfDecl<TDecl> = TDecl extends {
+  readonly context?: infer TContext extends object;
+} ? TContext : unknown;
 /**
- * The `meta` a declaration adds to its root. Every declared key is present
- * and may be `undefined`: roots of all-optional metas would be assignable to
- * one another. Queries pass a `Partial` of it.
+ * Every key of `T` required, its value possibly `undefined`: a root whose
+ * options were all optional would be assignable from a root without them.
+ * Mapping over `Exclude<keyof T, never>` rather than `keyof T` drops the
+ * modifiers without dropping `undefined`, which `-?` would.
+ *
+ * A conditional type, like {@link Plain} and {@link Root}, so the result is
+ * a plain object type that TypeScript compares field by field. As an alias
+ * of a mapped type, it compares `Root<A>` with `Root<A & B>` by a variance
+ * it measures wrong, and takes a client that lacks a part for one that has it.
  */
-export type MetaOfDecl<TDecl> = TDecl extends {
-  readonly meta?: infer TMeta extends object;
-} ? Present<TMeta> : unknown;
+type Present<T> = T extends unknown ? { readonly [K in Exclude<keyof T, never>]: T[K] | undefined; } : never;
+type Plain<T> = T extends unknown ? { readonly [K in keyof T]: T[K]; } : never;
 /**
- * Every key of `T` required, its value possibly `undefined`. Mapping over
- * `Exclude<keyof T, never>` rather than `keyof T` drops the modifiers
- * without dropping `undefined`, which `-?` would.
+ * The root of a declaration, or of several intersected. Every declared
+ * option is present and may be `undefined`; queries set a `Partial` of them.
  */
-type Present<T> = { readonly [K in Exclude<keyof T, never>]: T[K] | undefined; };
+export type Root<TDecl> = TDecl extends unknown ? {
+  readonly context: Plain<ContextOfDecl<TDecl>>;
+  readonly options: Present<OptionsOfDecl<TDecl>>;
+} : never;
+/**
+ * The root of a client with no parts, and of the unbound builders. Every
+ * client has it, so the bare `QueryClient` type takes any client.
+ */
+export type NoParts = Root<unknown>;
 type DeclOf<TPart> = TPart extends {
   readonly "~decl"?: {
     readonly out: infer TDecl;
   };
 } ? TDecl : never;
 type Intersect<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends ((value: infer TIntersection) => void) ? TIntersection : never;
-type Flat<T> = { readonly [K in keyof T]: T[K]; };
-/** A root's `meta`: what its links and features declare. */
-export type MetaOf<TParts extends ReadonlyArray<AnyPart>> = [DeclOf<TParts[number]>] extends [never] ? Flat<unknown> : Flat<Intersect<MetaOfDecl<DeclOf<TParts[number]>>>>;
+/** A client's root: what its parts declare. */
+export type RootOfParts<TParts extends ReadonlyArray<AnyDeclares>> = [DeclOf<TParts[number]>] extends [never] ? NoParts : Root<Intersect<DeclOf<TParts[number]>>>;
 declare const rootBrand: unique symbol;
 /** Phantom carrier of the root a factory's builder is bound to. Never set at runtime. */
 export interface RootTag<TTypes extends RootTypes> {
   readonly [rootBrand]: TTypes;
 }
-/** A root's types, from a client or from a function that makes one. */
-export type RootOf<T> = T extends ((...args: never) => infer TClient) ? RootOf<TClient> : T extends {
+/** A client's root, from the client or from a function that makes one. `never` for anything else. */
+type RootOfClient<T> = T extends ((...args: never) => infer TClient) ? RootOfClient<TClient> : T extends {
   readonly "~types"?: {
-    readonly root: (types: infer TTypes extends RootTypes) => unknown;
+    readonly root: infer TTypes;
   };
-} ? TTypes : never;
+} ? TTypes extends RootTypes ? TTypes : never : never;
+type WithoutOptional<T> = Omit<T, typeof optionalDecl>;
+type OptionalOf<T> = T extends {
+  readonly [optionalDecl]?: infer TDecl;
+} ? TDecl : unknown;
+/**
+ * The root a builder is bound to: a client's, the root of a function that
+ * makes one, or the root of the parts a library names by their
+ * declarations. `QueryClient<RootOf<Convex>>` is a client that has the part
+ * that declares `Convex`.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#binding-a-library-to-parts
+ */
+export type RootOf<T> = [RootOfClient<T>] extends [never] ? Root<WithoutOptional<T>> : RootOfClient<T>;
+/**
+ * The options a bound builder takes: its root's, and those of the parts a
+ * library named as {@link Optional}.
+ */
+export type SetsOf<T> = [RootOfClient<T>] extends [never] ? Root<WithoutOptional<T> & OptionalOf<T>> : RootOfClient<T>;
 //#endregion

package/dist/verbs.d.mts

@@ -1,6 +1,6 @@
 import { Group } from "./keys/keys.mjs";
-import { IsAnyRoot, RootTypes } from "./root.mjs";
 import { AnyInvalidation, AnyTarget, ParamArgs, Target } from "./keys/targets.mjs";
+import { RootTypes } from "./root.mjs";
 import { InputArgs, InputOf, QueryFactory, QueryFnDataOf, RootOfFactory } from "./options.mjs";
 import { QueryClient } from "./client.mjs";
 //#region src/verbs.d.ts
@@ -13,22 +13,21 @@ type DeepPartial<T> = T extends object ? { readonly [TName in keyof T]?: DeepPar
  */
 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.
+ * The clients a factory runs on: those with the parts its builder is bound
+ * to, 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
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-options-by-the-client
  */
 export type ClientFor<TFactory extends QueryFactory> = QueryClient<RootOfFactory<TFactory>>;
 /**
- * A target a client's root can match: its `where` reads that root's `meta`.
- * A client typed only as `QueryClient` (from `useQueryClient()`, say) may
- * be of any root, so it takes any target.
+ * A target a client's root can match: its `where` reads the options that
+ * root's parts declare.
  */
-export type TargetFor<TTypes extends RootTypes, TParam> = IsAnyRoot<TTypes> extends true ? Target<never, TParam> : Target<NoInfer<TTypes["meta"]>, TParam>;
+export type TargetFor<TTypes extends RootTypes, TParam> = Target<NoInfer<TTypes["options"]>, TParam>;
 type ParamOf<TTarget> = TTarget extends {
   readonly where: (query: never, param: infer TParam) => boolean;
 } ? TParam : never;
-/** A factory, if the client's root is its root; else nothing fits. */
+/** A factory, if the client has the parts it needs; else nothing fits. */
 type FactoryFor<TTypes extends RootTypes, TFactory extends QueryFactory> = [QueryClient<TTypes>] extends [ClientFor<TFactory>] ? TFactory : never;
 /** A target on its own, if it needs no parameter; else with its parameter. */
 type BareTarget<TTypes extends RootTypes, TParam> = [] extends ParamArgs<TParam> ? TargetFor<TTypes, TParam> : readonly [TargetFor<TTypes, TParam>, TParam];

package/package.json

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