@raf-query/core 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,14 +1,24 @@
 # Changelog
 
+## [0.15.0](https://github.com/KATT/raf-query/compare/0.14.0...0.15.0) (2026-11-11)
+
+### ⚠ BREAKING CHANGES
+
+* **core:** a part's link can give or change the queryFn context per request ([#251](https://github.com/KATT/raf-query/issues/251))
+
+### Features
+
+* **core:** a part's link can give or change the queryFn context per request ([#251](https://github.com/KATT/raf-query/issues/251)) ([3358dde](https://github.com/KATT/raf-query/commit/3358ddeb1a0a19b0459af55d70b6e23a05a902d5))
+
 ## [0.14.0](https://github.com/KATT/raf-query/compare/0.13.2...0.14.0) (2026-11-11)
 
 ### ⚠ BREAKING CHANGES
 
-* **core:** parts declare the options and queryFn context a client's queries get ([#250](https://github.com/KATT/raf-query/issues/250))
+- **core:** parts declare the options and queryFn context a client's queries get ([#250](https://github.com/KATT/raf-query/issues/250))
 
 ### Features
 
-* **core:** parts declare the options and queryFn context a client's queries get ([#250](https://github.com/KATT/raf-query/issues/250)) ([931b7ed](https://github.com/KATT/raf-query/commit/931b7ed83837576c607b63e2dfdd1c795129cd41))
+- **core:** parts declare the options and queryFn context a client's queries get ([#250](https://github.com/KATT/raf-query/issues/250)) ([931b7ed](https://github.com/KATT/raf-query/commit/931b7ed83837576c607b63e2dfdd1c795129cd41))
 
 ## [0.13.2](https://github.com/KATT/raf-query/compare/0.13.1...0.13.2) (2026-11-10)
 

package/dist/client.d.mts

@@ -1,6 +1,6 @@
 import { QueryKey } from "./keys/keys.mjs";
 import { Stamp } from "./keys/targets.mjs";
-import { AnyDeclares, Decl, Declares, NoDecl, NoParts, OptionsOfDecl, Root, RootOfParts, RootTypes } from "./root.mjs";
+import { AnyDeclares, ContextOfDecl, Decl, Declares, NoDecl, NoParts, OptionsOfDecl, Root, RootOfParts, RootTypes } from "./root.mjs";
 import { CoreOptions, QueryOptions } from "./options.mjs";
 import { Listeners, SubscribeOptions } from "./subscribe.mjs";
 import { Entry } from "./entry.mjs";
@@ -24,6 +24,12 @@ export declare const systemClock: Clock;
  */
 export interface Operation<TDecl extends Decl = Decl> {
   readonly client: QueryClient;
+  /**
+   * What the `queryFn` gets beside the client, key and signal: the parts'
+   * context, as the links before this one left it. Pass `next` an
+   * operation with another `context` to change it for this request.
+   */
+  readonly context: Partial<ContextOfDecl<TDecl>>;
   /** The entry's data when the request started (paged queries extend it). */
   readonly data: unknown;
   /** For paged queries: which page to add. */
@@ -58,27 +64,52 @@ export interface AnyPart extends AnyDeclares {
   readonly link?: LinkFunction;
   readonly setup?: SetupFunction;
 }
-/** What {@link part} takes: `context` is required when the part declares one. */
-export type PartDefinition<TDecl extends Decl> = (TDecl extends {
-  readonly context: infer TContext extends object;
-} ? {
-  /** Merged into the context of every `queryFn` the client runs. */
-  readonly context: TContext;
-} : {
+type LinkOf<TDecl extends Decl, TNext> = (op: Operation<TDecl>, next: (op: TNext) => Promise<unknown>) => Promise<unknown>;
+interface PartSetup<TDecl extends Decl> {
+  /**
+   * A cache-wide behavior, started when a provider mounts the client and
+   * stopped by `signal`. The client is typed with this part, so it runs
+   * the factories of a builder bound to it.
+   */
+  readonly setup?: (client: QueryClient<Root<TDecl>>, signal: AbortSignal) => void;
+}
+/** The context a declaration says its part gives. */
+type DeclaredContext<TDecl extends ContextDecl> = TDecl["context"];
+/** A declaration with a `context`: its part gives it. */
+interface ContextDecl extends Decl {
+  readonly context: object;
+}
+/** What {@link part} takes for a part that declares no `context`. */
+interface PlainDefinition<TDecl extends Decl> extends PartSetup<TDecl> {
   readonly context?: never;
-}) & {
   /**
    * Wraps every request, like a tRPC link. Call `next(op)` to run the
    * rest of the chain; the last link is the query's own `queryFn`.
    */
-  readonly link?: (op: Operation<TDecl>, next: (op: Operation) => Promise<unknown>) => Promise<unknown>;
+  readonly link?: LinkOf<TDecl, Operation<TDecl>>;
+}
+/** What {@link part} takes for a part that gives its `context` for the client. */
+interface ClientContextDefinition<TDecl extends ContextDecl> extends PartSetup<TDecl> {
+  /** Merged into the context of every `queryFn` the client runs. */
+  readonly context: DeclaredContext<TDecl>;
   /**
-   * A cache-wide behavior, started when a provider mounts the client and
-   * stopped by `signal`. The client is typed with this part, so it runs
-   * the factories of a builder bound to it.
+   * Wraps every request, like a tRPC link. Call `next(op)` to run the
+   * rest of the chain; the last link is the query's own `queryFn`. An
+   * operation with another `context` changes it for that request.
    */
-  readonly setup?: (client: QueryClient<Root<TDecl>>, signal: AbortSignal) => void;
-};
+  readonly link?: LinkOf<TDecl, Operation<TDecl>>;
+}
+/** What {@link part} takes for a part that gives its `context` per request. */
+interface RequestContextDefinition<TDecl extends ContextDecl> extends PartSetup<TDecl> {
+  readonly context?: never;
+  /**
+   * Wraps every request, and gives each the context the part declares:
+   * `next` takes an operation whose `context` has it.
+   */
+  readonly link: LinkOf<TDecl, Operation<TDecl> & {
+    readonly context: DeclaredContext<TDecl>;
+  }>;
+}
 /** A declaration without a `context`: its part needs no definition. */
 interface OptionsDecl {
   readonly context?: never;
@@ -101,10 +132,24 @@ interface OptionsDecl {
  * A part without a link or `setup` only declares: an app's own options, such
  * as an `owner` its targets match on.
  *
+ * A part gives the `context` it declares for the client, as `context`, or
+ * per request, from its link:
+ *
+ * ```ts
+ * interface Session {
+ *   readonly context: { readonly token: string };
+ * }
+ * const session = part<Session>({
+ *   link: async (op, next) =>
+ *     next({ ...op, context: { ...op.context, token: await freshToken() } }),
+ * });
+ * ```
+ *
  * @see https://raf-query.katt.dev/docs/links-and-features#parts
  */
-export declare function part<TDecl extends OptionsDecl = NoDecl>(definition?: PartDefinition<NoInfer<TDecl>>): Part<NoInfer<TDecl>>;
-export declare function part<TDecl extends Decl>(definition: PartDefinition<NoInfer<TDecl>>): Part<NoInfer<TDecl>>;
+export declare function part<TDecl extends OptionsDecl = NoDecl>(definition?: PlainDefinition<NoInfer<TDecl>>): Part<NoInfer<TDecl>>;
+export declare function part<TDecl extends ContextDecl>(definition: ClientContextDefinition<NoInfer<TDecl>>): Part<NoInfer<TDecl>>;
+export declare function part<TDecl extends ContextDecl>(definition: RequestContextDefinition<NoInfer<TDecl>>): Part<NoInfer<TDecl>>;
 export type ClientEvent = {
   readonly entry: Entry;
   readonly type: "added" | "removed" | "updated";
@@ -143,6 +188,8 @@ export interface QueryClientConfig {
 export interface QueryClient<TTypes extends RootTypes = NoParts> {
   /** Entries changed since the last notification. */
   readonly "~changed": Set<Entry>;
+  /** What the parts give every `queryFn` for the client; links can change it per request. */
+  readonly "~context": object;
   readonly "~entries": Map<string, Entry>;
   readonly "~events": Listeners<ClientEvent>;
   /** Orders requests and invalidations. */
@@ -155,8 +202,6 @@ export interface QueryClient<TTypes extends RootTypes = NoParts> {
   };
   readonly clock: Clock;
   readonly config: QueryClientConfig;
-  /** What the parts give every `queryFn`, beside the client, key and signal. */
-  readonly context: TTypes["context"];
   readonly isServer: boolean;
   /**
    * Cache events: entries added, updated, removed, or gaining and losing

package/dist/client.mjs

@@ -35,13 +35,13 @@ function createQueryClient(config = {}) {
 	const entries = /* @__PURE__ */ new Map();
 	return {
 		"~changed": /* @__PURE__ */ new Set(),
+		"~context": Object.assign({}, ...(config.parts ?? []).map((one) => one.context)),
 		"~entries": entries,
 		"~events": events,
 		"~seq": 0,
 		"~stamps": [],
 		clock: config.clock ?? systemClock,
 		config,
-		context: Object.assign({}, ...(config.parts ?? []).map((one) => one.context)),
 		isServer: config.isServer ?? !("window" in globalThis),
 		subscribe: (listener, options) => {
 			const unsubscribe = events.subscribe(listener, options);

package/dist/entry.mjs

@@ -221,7 +221,7 @@ function terminal(op) {
 		const options = op.options;
 		const paged = options["~run"];
 		resolve(paged ? paged(op) : options.queryFn({
-			...op.client.context,
+			...op.context,
 			client: op.client,
 			queryKey: op.queryKey,
 			signal: op.signal
@@ -264,6 +264,7 @@ function fetchEntry(entry, request = {}) {
 	const state = entry.state;
 	chain({
 		client,
+		context: client["~context"],
 		data: state.data,
 		direction: request.direction,
 		hasData: state.hasData,

package/dist/infinite/infinite.mjs

@@ -66,7 +66,7 @@ function pageFor(data, pageParam) {
 }
 async function runPages(op, source) {
 	const fetchPage = (pageParam, direction) => Promise.resolve(source.queryFn({
-		...op.client.context,
+		...op.context,
 		client: op.client,
 		direction,
 		pageParam,

package/dist/root.d.mts

@@ -9,7 +9,7 @@
  */
 /**
  * What a part declares: the per-query `options` it reads, and the `context`
- * it gives every `queryFn`.
+ * it gives every `queryFn`, for the client or per request from its link.
  *
  * @see https://raf-query.katt.dev/docs/links-and-features#parts
  */
@@ -63,7 +63,7 @@ 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 {
+export type ContextOfDecl<TDecl> = TDecl extends {
   readonly context?: infer TContext extends object;
 } ? TContext : unknown;
 /**

package/package.json

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