@raf-query/core 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Changelog
 
+## [0.1.4](https://github.com/KATT/raf-query/compare/0.1.3...0.1.4) (2026-10-12)
+
+### Features
+
+* **core:** add per-query meta ([#26](https://github.com/KATT/raf-query/issues/26)) ([863c915](https://github.com/KATT/raf-query/commit/863c915d884bdfa3bcb3053da348d51aa0e697cf))
+
+## [0.1.3](https://github.com/KATT/raf-query/compare/0.1.2...0.1.3) (2026-10-12)
+
+### Features
+
+- **core:** cancel requests nobody reads anymore ([#27](https://github.com/KATT/raf-query/issues/27)) ([c3c1e4b](https://github.com/KATT/raf-query/commit/c3c1e4bb9250164b6df17d7d4b7bd4043f908961))
+
 ## [0.1.2](https://github.com/KATT/raf-query/compare/0.1.1...0.1.2) (2026-10-12)
 
 ### Features
 
-* add isFetching(filter?) and useIsFetching(filter?) ([#25](https://github.com/KATT/raf-query/issues/25)) ([70c3b98](https://github.com/KATT/raf-query/commit/70c3b981027f717b1d619d5a2b23822f685c032a))
+- add isFetching(filter?) and useIsFetching(filter?) ([#25](https://github.com/KATT/raf-query/issues/25)) ([70c3b98](https://github.com/KATT/raf-query/commit/70c3b981027f717b1d619d5a2b23822f685c032a))
 
 ## [0.1.1](https://github.com/KATT/raf-query/compare/0.1.0...0.1.1) (2026-10-12)
 

package/README.md

@@ -66,10 +66,46 @@ export function commentsQuery(input: { slug: string }) {
 
 Factories must take at most one argument; the type rejects two or more. The single argument is the query's **input** and must be serializable, because it is what a handle carries.
 
-A `queryFn` returns a value, a promise, or an [Effect](#effect). It receives `queryKey` and an abort `signal`; paged ones also get `pageParam` and `direction`. TypeScript infers the page type from `queryFn`, so if `getNextPageParam` comes first in the object literal (sorted keys), pass the types instead: `infiniteQueryOptions<CommentPage, number>({ ... })`.
+A `queryFn` returns a value, a promise, or an [Effect](#effect). It receives `queryKey`, the query's [`meta`](#query-meta) and an abort `signal`; paged ones also get `pageParam` and `direction`. TypeScript infers the page type from `queryFn`, so if `getNextPageParam` comes first in the object literal (sorted keys), pass the types instead: `infiniteQueryOptions<CommentPage, number>({ ... })`.
 
 The factory is the only place a query is declared paged. Every other API — `prefetch`, `ensure`, `fetch`, `useQuery`, `useWaterfall`, `invalidate`, `setData` — takes either kind and infers the rest from the factory's type.
 
+### Query meta
+
+`meta` attaches anything you want to know about a query elsewhere. It reaches the `queryFn` context, `Query.metaUnsafe(query)` (from the latest factory call) and the devtools. A common use is a per-query message for one global error handler:
+
+```ts
+import { Query, QueryClient, queryOptions } from "@raf-query/react";
+
+export function issuesQuery() {
+	return queryOptions({
+		queryKey: ["issues"],
+		queryFn: () => listIssues(),
+		meta: { errorMessage: "Couldn't load issues" },
+	});
+}
+
+const queryClient = new QueryClient({
+	onError: (error, query) => {
+		toast.error(
+			Query.metaUnsafe(query)?.errorMessage ?? "Something went wrong",
+		);
+	},
+});
+```
+
+`meta` is `Record<string, unknown>` by default. Type it for the whole app by augmenting `Register` in the package you import from (`@raf-query/react` re-exports it from `@raf-query/core`, so either works):
+
+```ts
+declare module "@raf-query/react" {
+	interface Register {
+		queryMeta: { errorMessage?: string };
+	}
+}
+```
+
+`config.defaults` takes `meta` too, for queries that set none; a query's own `meta` replaces the default as a whole. `meta` is sent with dehydrated state, so keep it serializable: a hydrated entry reports the sender's `meta` until the receiving side calls its factory.
+
 ## Starting queries
 
 All three verbs live on the query client and accept a factory plus its input.
@@ -593,7 +629,7 @@ A button in the corner opens a panel docked to the edge of the viewport. The pan
 | `fresh`    | Read, and within `staleTime`               |
 | `inactive` | Nothing reads it; it's removed at `gcTime` |
 
-Select an entry to see its key, input, data, error, and last update, and to **Refetch**, **Invalidate**, **Reset** (drop its data, so readers suspend and refetch) or **Remove** it. The header filters entries by key, sorts them, and has **Invalidate all** and **Clear cache**. The panel keeps its open state and size in `localStorage`.
+Select an entry to see its key, input, meta, data, error, and last update, and to **Refetch**, **Invalidate**, **Reset** (drop its data, so readers suspend and refetch) or **Remove** it. The header filters entries by key, sorts them, and has **Invalidate all** and **Clear cache**. The panel keeps its open state and size in `localStorage`.
 
 `QueryDevtools` props, all optional:
 
@@ -639,29 +675,33 @@ Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.de
 | `retryDelay` (ms, or a function of the failure count) | Doubling from 1 s, at most 30 s           |
 | `refetchOnWindowFocus`, `refetchOnReconnect`          | `true` (only read, stale queries refetch) |
 | `structuralSharing` (keep deeply equal parts of data) | `true`                                    |
+| [`meta`](#query-meta)                                 | None                                      |
 
 `infiniteQueryOptions` also takes `getPreviousPageParam` and `maxPages`.
 
 In the browser, retries pause while `navigator.onLine` is `false`: after the retry delay, the next attempt waits for the window's `online` event. The request stays fetching meanwhile, and cancelling it (`remove`, `clear`, a restart) stops the wait. The first attempt runs regardless.
 
+When the last reader of a query unsubscribes during a background refetch, a `queryFn` that read its `signal` (or returned an Effect) is aborted: the entry keeps its data and goes back to how it was before the request, and `fetch` callers waiting on it get the cached data. Other requests, including every first load (a render may be suspended on it), finish so their result is cached, but don't retry unless a reader comes back. Requests nothing has subscribed to yet, like a loader's `prefetch`, keep running.
+
 `@raf-query/core`:
 
-| Export                                                       | Use                                                                        |
-| ------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `QueryCache`                                                 | The cache service (`qc.effect`): `make`, `layer`, and the verbs as Effects |
-| `Query`                                                      | Cache entries: `Query.fetch`, `Query.changes`, `Query.getUnsafe`, …        |
-| `Platform`                                                   | The page the cache watches (focus, network); swap it in tests              |
-| `queryOptions(options)`                                      | Typed options for a query factory                                          |
-| `infiniteQueryOptions(options)`                              | Typed options for a paged query factory                                    |
-| `hashKey(key)`, `matchesKey(key, prefix)`                    | Key helpers                                                                |
-| `QueryObserver`                                              | One reader's view of a query, with tracked results; for bindings           |
-| `Query.CancelledError`                                       | Failure of a request whose entry was removed or cleared before it settled  |
-| `RedactedError`                                              | What a streamed pending query rejects with when its server request failed  |
-| `QueryHandle<TFactory>`                                      | Handle type for props                                                      |
-| `EnsuredQueryHandle<TFactory>`                               | Handle type for props fed by `ensure`                                      |
-| `Thenable<T>`                                                | Promise with `status` / `value` / `reason`, read by `use()`                |
-| `DataOf<TFactory>`, `InputOf<TFactory>`, `ErrorOf<TFactory>` | A factory's data, input and error types                                    |
-| `ServicesOf<TFactory>`                                       | The services a factory's `queryFn` Effect needs; `never` for promises      |
+| Export                                                       | Use                                                                                     |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `QueryCache`                                                 | The cache service (`qc.effect`): `make`, `layer`, and the verbs as Effects              |
+| `Query`                                                      | Cache entries: `Query.fetch`, `Query.changes`, `Query.getUnsafe`, `Query.metaUnsafe`, … |
+| `Platform`                                                   | The page the cache watches (focus, network); swap it in tests                           |
+| `queryOptions(options)`                                      | Typed options for a query factory                                                       |
+| `infiniteQueryOptions(options)`                              | Typed options for a paged query factory                                                 |
+| `hashKey(key)`, `matchesKey(key, prefix)`                    | Key helpers                                                                             |
+| `QueryObserver`                                              | One reader's view of a query, with tracked results; for bindings                        |
+| `Query.CancelledError`                                       | Failure of a request whose entry was removed or cleared before it settled               |
+| `RedactedError`                                              | What a streamed pending query rejects with when its server request failed               |
+| `QueryHandle<TFactory>`                                      | Handle type for props                                                                   |
+| `EnsuredQueryHandle<TFactory>`                               | Handle type for props fed by `ensure`                                                   |
+| `Thenable<T>`                                                | Promise with `status` / `value` / `reason`, read by `use()`                             |
+| `DataOf<TFactory>`, `InputOf<TFactory>`, `ErrorOf<TFactory>` | A factory's data, input and error types                                                 |
+| `ServicesOf<TFactory>`                                       | The services a factory's `queryFn` Effect needs; `never` for promises                   |
+| `Register`, `QueryMeta`                                      | Augment `Register` with `queryMeta` to type [`meta`](#query-meta)                       |
 
 `@raf-query/react` (plus all of the above):
 

package/dist/entry.d.mts

@@ -1,12 +1,12 @@
 import { Platform, PlatformEvent } from "./platform.mjs";
 import { QueryKey } from "./key.mjs";
-import { AnyQueryOptions, QueryBehavior, QueryFactory, QueryHandle } from "./options.mjs";
+import { AnyQueryOptions, QueryBehavior, QueryFactory, QueryHandle, QueryMeta } from "./options.mjs";
 import { Event } from "./cache.mjs";
 import { Pending, Thenable } from "./thenable.mjs";
 import { FetchRequest, Query, State, SubscribeOptions } from "./query.mjs";
 import { Cause, Clock, Context, Deferred, Effect, Scope, Stream } from "effect";
 declare namespace entry_d_exports {
-  export { CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, setData, setOptions, start, subscribeUnsafe };
+  export { CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, setData, setOptions, start, subscribeUnsafe };
 }
 export declare const TypeId = "~@raf-query/core/Query";
 declare const CancelledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
@@ -54,13 +54,19 @@ export interface Entry extends Query {
   readonly commands: Commands;
   /** A failed first load was shown; the next read retries it. */
   errorShown: boolean;
+  /** `failureCount` before the request in flight, restored if it's cancelled. */
+  failureCountBefore: number;
   handle: QueryHandle;
+  /** `meta` sent with dehydrated state, for an entry no factory call has reached. */
+  hydratedMeta: QueryMeta | undefined;
   /** Awaited by every caller of the request in flight; outlives restarts. */
   inFlight: Deferred.Deferred<unknown, unknown> | undefined;
   readonly listeners: Map<() => void, SubscribeOptions>;
   options: AnyQueryOptions | undefined;
   /** The first load's promise, until it settles. */
   pending: Pending<unknown> | undefined;
+  /** The last reader left during the request in flight: it retries no more. */
+  retriesStopped: boolean;
   /** Open while the entry is cached; owns its fibers. */
   readonly scope: Scope.Closeable;
   /**
@@ -68,6 +74,11 @@ export interface Entry extends Query {
    * latest verb that called for this entry ({@link provide}).
    */
   services: Context.Context<never>;
+  /**
+   * The request in flight read its `signal`, or returned an Effect, so
+   * interrupting it cancels its work (TanStack's `abortSignalConsumed`).
+   */
+  signalRead: boolean;
   state: State<unknown>;
   readonly tasks: Tasks;
 }
@@ -78,6 +89,8 @@ export declare function make(cache: CacheState, key: QueryKey, hash: string): En
 export declare function now(entry: Entry): number;
 /** Readers are subscribed; `invalidate` and focus refetch only what is read. */
 export declare function isObserved(entry: Entry): boolean;
+/** Until a factory call attaches options, `meta` comes from hydration. */
+export declare function metaOf(entry: Entry): QueryMeta | undefined;
 export declare function isStaleUnsafe(entry: Entry): boolean;
 export declare function hasNextPageUnsafe(entry: Entry): boolean;
 export declare function hasPreviousPageUnsafe(entry: Entry): boolean;

package/dist/entry.mjs

@@ -7,7 +7,7 @@ import { fromQueryFn, requestServices, runRequest } from "./request.mjs";
 import { retrySchedule } from "./retry.mjs";
 import { replaceEqualDeep } from "./share.mjs";
 import { fulfilled, pending } from "./thenable.mjs";
-import { Cause, Data, Deferred, Effect, Exit, FiberMap, Pipeable, Predicate, Scope } from "effect";
+import { Cause, Data, Deferred, Effect, Exit, FiberMap, Pipeable, Predicate, Schedule, Scope } from "effect";
 //#region src/entry.ts
 const TypeId = "~@raf-query/core/Query";
 /**
@@ -55,18 +55,22 @@ function make(cache, key, hash) {
 	const entry = Object.assign(Object.create(Proto), {
 		cache,
 		errorShown: false,
+		failureCountBefore: 0,
 		handle: {
 			input: void 0,
 			key
 		},
 		hash,
+		hydratedMeta: void 0,
 		inFlight: void 0,
 		key,
 		listeners: /* @__PURE__ */ new Map(),
 		options: void 0,
 		pending: first,
+		retriesStopped: false,
 		scope,
 		services: cache.services,
+		signalRead: false,
 		state: {
 			data: void 0,
 			error: null,
@@ -101,6 +105,10 @@ function isObserved(entry) {
 function behavior(entry, name) {
 	return entry.options?.[name] ?? entry.cache.defaults[name];
 }
+/** Until a factory call attaches options, `meta` comes from hydration. */
+function metaOf(entry) {
+	return entry.options ? behavior(entry, "meta") : entry.hydratedMeta ?? entry.cache.defaults.meta;
+}
 function computeStale(entry, state) {
 	if (state.isInvalidated || !state.hasData) return true;
 	const staleTime = behavior(entry, "staleTime") ?? 0;
@@ -121,6 +129,7 @@ function hasPreviousPageUnsafe(entry) {
 }
 function subscribeUnsafe(entry, listener, options = defaultSubscribeOptions) {
 	entry.listeners.set(listener, options);
+	entry.retriesStopped = false;
 	entry.tasks.cancel("gc");
 	scheduleStale(entry);
 	emit(entry.cache, {
@@ -132,6 +141,8 @@ function subscribeUnsafe(entry, listener, options = defaultSubscribeOptions) {
 		if (entry.listeners.size === 0) {
 			entry.tasks.cancel("stale");
 			scheduleGc(entry);
+			const inFlight = entry.inFlight;
+			if (inFlight) scheduleNotify(() => unobserved(entry, inFlight));
 		}
 		emit(entry.cache, {
 			query: entry,
@@ -273,8 +284,11 @@ function set(entry, patch) {
 }
 /** Run `request` as the entry's request fiber, settling into its awaiter. */
 function startRequest(entry, request, direction) {
+	if (!entry.inFlight) entry.failureCountBefore = entry.state.failureCount;
 	const awaiter = entry.inFlight ?? Deferred.makeUnsafe();
 	entry.inFlight = awaiter;
+	entry.retriesStopped = false;
+	entry.signalRead = false;
 	entry.tasks.cancel("gc");
 	if (!entry.state.hasData && entry.state.status === "error") {
 		entry.pending = pending();
@@ -312,6 +326,29 @@ function settle(entry, awaiter, exit) {
 	}
 	scheduleGc(entry);
 }
+/**
+* The last reader left while `awaiter`'s request was in flight. A refetch
+* whose work an interrupt cancels (`signalRead`) is interrupted, and the
+* entry goes back to its state before the request; its awaiters get the
+* cached data. Any other request finishes, so its result is cached, but
+* runs no more retries.
+*/
+function unobserved(entry, awaiter) {
+	if (isObserved(entry) || entry.inFlight !== awaiter) return;
+	if (!entry.signalRead || !entry.state.hasData) {
+		entry.retriesStopped = true;
+		return;
+	}
+	entry.inFlight = void 0;
+	entry.tasks.cancel("request");
+	set(entry, {
+		failureCount: entry.failureCountBefore,
+		fetchDirection: void 0,
+		isFetching: false
+	});
+	Deferred.doneUnsafe(awaiter, Exit.succeed(entry.state.data));
+	scheduleGc(entry);
+}
 function succeed(entry, next, updatedAt) {
 	const previous = entry.state;
 	const data = previous.hasData && behavior(entry, "structuralSharing") !== false ? replaceEqualDeep(previous.data, next) : next;
@@ -364,25 +401,41 @@ function markErrorShown(entry) {
 	}))), { onlyIfMissing: true });
 }
 function requestEffect(entry, options, request) {
+	const meta = metaOf(entry);
 	const queryKey = options.queryKey;
-	if (options.kind === "query") return attempt(entry, (signal) => options.queryFn({
+	if (options.kind === "query") return attempt(entry, (readSignal) => options.queryFn({
+		meta,
 		queryKey,
-		signal
+		get signal() {
+			return readSignal();
+		}
 	}));
 	const current = isInfiniteData(entry.state.data) ? entry.state.data : void 0;
-	return fetchPages(options, current, request, (pageParam, direction) => attempt(entry, (signal) => options.queryFn({
+	return fetchPages(options, current, request, (pageParam, direction) => attempt(entry, (readSignal) => options.queryFn({
 		direction,
+		meta,
 		pageParam,
 		queryKey,
-		signal
+		get signal() {
+			return readSignal();
+		}
 	})));
 }
 /**
 * One `queryFn` call, retried per the query's policy. Every failure counts.
-* Its services are erased with its data type; `runRequest` provides them.
+* `call` reads the signal through `readSignal`, which marks the entry's
+* `signalRead`. Its services are erased with its data type; `runRequest`
+* provides them.
 */
 function attempt(entry, call) {
-	const once = fromQueryFn(call).pipe(Effect.tapError(() => Effect.sync(() => set(entry, { failureCount: entry.state.failureCount + 1 }))));
+	const once = fromQueryFn((signal) => {
+		const result = call(() => {
+			entry.signalRead = true;
+			return signal;
+		});
+		if (Effect.isEffect(result)) entry.signalRead = true;
+		return result;
+	}).pipe(Effect.tapError(() => Effect.sync(() => set(entry, { failureCount: entry.state.failureCount + 1 }))));
 	const schedule = retrySchedule({
 		retry: behavior(entry, "retry"),
 		retryDelay: behavior(entry, "retryDelay")
@@ -391,12 +444,18 @@ function attempt(entry, call) {
 	const online = entry.cache.isServer ? Effect.void : whenOnline;
 	return Effect.suspend(() => {
 		let retrying = false;
+		let lastError;
+		const unlessStopped = (next) => Effect.suspend(() => entry.retriesStopped ? Effect.fail(lastError) : next);
 		const gated = Effect.suspend(() => {
-			const wait = retrying ? online : Effect.void;
-			retrying = true;
-			return Effect.andThen(wait, once);
-		});
-		return Effect.retry(gated, schedule);
+			if (!retrying) {
+				retrying = true;
+				return once;
+			}
+			return unlessStopped(Effect.andThen(online, unlessStopped(once)));
+		}).pipe(Effect.tapError((error) => Effect.sync(() => {
+			lastError = error;
+		})));
+		return Effect.retry(gated, Schedule.while(schedule, () => !entry.retriesStopped));
 	});
 }
 function scheduleGc(entry) {
@@ -418,4 +477,4 @@ function scheduleStale(entry) {
 	entry.tasks.fork("stale", Effect.sleep(Math.max(remaining, 0) + 1).pipe(Effect.andThen(Effect.sync(() => set(entry, {})))));
 }
 //#endregion
-export { CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, setData, setOptions, start, subscribeUnsafe };
+export { CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, setData, setOptions, start, subscribeUnsafe };

package/dist/hydration.d.mts

@@ -1,5 +1,5 @@
 import { QueryKey } from "./key.mjs";
-import { QueryFactory } from "./options.mjs";
+import { QueryFactory, QueryMeta } from "./options.mjs";
 import "./cache.mjs";
 import "./entry.mjs";
 import { Query, query_d_exports } from "./query.mjs";
@@ -13,6 +13,8 @@ import { Cause, Effect, Scope, Stream } from "effect";
 export interface DehydratedQuery {
   readonly data?: unknown;
   readonly key: QueryKey;
+  /** The query's `meta`, for receivers that haven't called its factory. */
+  readonly meta?: QueryMeta;
   readonly promise?: Promise<unknown>;
   /** When `data` was fetched; `0` while pending. */
   readonly updatedAt: number;

package/dist/hydration.mjs

@@ -1,5 +1,5 @@
 import { resume, setData } from "./entry.mjs";
-import { getUnsafe } from "./query.mjs";
+import { getUnsafe, metaUnsafe } from "./query.mjs";
 import { Data, Effect, Queue, Stream } from "effect";
 //#region src/hydration.ts
 /**
@@ -21,9 +21,14 @@ function canDehydrate(query) {
 function dehydrateUnsafe(query, options) {
 	const state = getUnsafe(query);
 	const serialize = options.serializeData ?? identity;
+	const meta = metaUnsafe(query);
+	const sent = meta === void 0 ? { key: query.key } : {
+		key: query.key,
+		meta
+	};
 	if (state.hasData) return {
+		...sent,
 		data: serialize(state.data),
-		key: query.key,
 		updatedAt: state.updatedAt
 	};
 	const promise = state.promise.then(serialize, (error) => {
@@ -31,7 +36,7 @@ function dehydrateUnsafe(query, options) {
 	});
 	promise.catch(noop);
 	return {
-		key: query.key,
+		...sent,
 		promise,
 		updatedAt: 0
 	};
@@ -101,6 +106,7 @@ function hydrateEntries(entryFor, state, options) {
 	const deserialize = options.deserializeData ?? identity;
 	for (const query of state.queries) {
 		const entry = entryFor(query.key);
+		if (!entry.options && query.meta !== void 0) entry.hydratedMeta = query.meta;
 		const current = entry.state;
 		if (query.updatedAt > 0) {
 			if (!current.hasData || current.updatedAt < query.updatedAt) setData(entry, deserialize(query.data), query.updatedAt);

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { platform_d_exports } from "./platform.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
-import { AnyQueryOptions, DataOf, EnsuredQueryHandle, ErrorOf, InfiniteData, InfiniteQueryOptions, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryOptions, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
+import { AnyQueryOptions, DataOf, EnsuredQueryHandle, ErrorOf, InfiniteData, InfiniteQueryOptions, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryMeta, QueryOptions, Register, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
 import { DehydrateOptions, DehydratedQuery, DehydratedState, DehydratedStream, HydrateOptions, RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
 import { cache_d_exports } from "./cache.mjs";
 import { Thenable } from "./thenable.mjs";
 import { query_d_exports } from "./query.mjs";
 import { observer_d_exports } from "./observer.mjs";
-export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type DehydratedStream, type EnsuredQueryHandle, type ErrorOf, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, platform_d_exports as Platform, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, observer_d_exports as QueryObserver, type QueryOptions, RedactedError, type RetryPolicy, type ServicesOf, type Thenable, canDehydrate, dehydrateQuery, hashKey, infiniteQueryOptions, matchesKey, queryOptions };
+export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type DehydratedStream, type EnsuredQueryHandle, type ErrorOf, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, platform_d_exports as Platform, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Thenable, canDehydrate, dehydrateQuery, hashKey, infiniteQueryOptions, matchesKey, queryOptions };

package/dist/options.d.mts

@@ -7,7 +7,30 @@ import { Effect, Schedule } from "effect";
  * and the services it needs become requirements of the verbs that start it.
  */
 export type QueryFnResult<TData, TError = unknown, TServices = never> = TData | PromiseLike<TData> | Effect.Effect<TData, TError, TServices>;
+/**
+ * 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. */
@@ -28,6 +51,12 @@ export type RetryPolicy = boolean | number | Schedule.Schedule<unknown, unknown>
 export interface QueryBehavior {
   /** How long an unread entry stays cached, in ms. `Infinity` keeps it. */
   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.
+   */
+  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. */

package/dist/query.d.mts

@@ -1,11 +1,11 @@
 import { QueryKey } from "./key.mjs";
-import { AnyQueryOptions, DataOf, ErrorOf, QueryFactory, QueryHandle, ServicesOf } from "./options.mjs";
+import { AnyQueryOptions, DataOf, ErrorOf, QueryFactory, QueryHandle, QueryMeta, ServicesOf } from "./options.mjs";
 import { Thenable } from "./thenable.mjs";
 import { CancelledError as CancelledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.mjs";
 import { Direction } from "./infinite.mjs";
 import { Effect, Pipeable, Stream } from "effect";
 declare namespace query_d_exports {
-  export { CancelledError, FetchRequest, Of, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, subscribeUnsafe };
+  export { CancelledError, FetchRequest, Of, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, subscribeUnsafe };
 }
 export declare const TypeId: typeof TypeId$1;
 export type TypeId = typeof TypeId;
@@ -89,6 +89,11 @@ export declare function invalidate<TData, TFactory extends QueryFactory, TError>
  * and refetch; succeeds when that refetch settles.
  */
 export declare function reset<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<void>;
+/**
+ * The query's `meta`: the latest factory call's (the one it was hydrated
+ * with, before any), else the cache default's.
+ */
+export declare function metaUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): QueryMeta | undefined;
 /** The entry's current state. */
 export declare function get<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<State<TData>>;
 /** {@link get}, synchronously. */

package/dist/query.mjs

@@ -1,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { CancelledError as CancelledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, provide, readUnsafe as readUnsafe$1, reset as reset$1, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
+import { CancelledError as CancelledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, metaOf, provide, readUnsafe as readUnsafe$1, reset as reset$1, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
 import { Effect } from "effect";
 import { dual } from "effect/Function";
 //#region src/query.ts
@@ -26,6 +26,7 @@ var query_exports = /* @__PURE__ */ __exportAll({
 	invalidate: () => invalidate,
 	isQuery: () => isQuery,
 	isStaleUnsafe: () => isStaleUnsafe,
+	metaUnsafe: () => metaUnsafe,
 	observerCountUnsafe: () => observerCountUnsafe,
 	readUnsafe: () => readUnsafe,
 	refetch: () => refetch,
@@ -75,6 +76,13 @@ function invalidate(self) {
 function reset(self) {
 	return reset$1(entryOf(self));
 }
+/**
+* The query's `meta`: the latest factory call's (the one it was hydrated
+* with, before any), else the cache default's.
+*/
+function metaUnsafe(self) {
+	return metaOf(entryOf(self));
+}
 /** The entry's current state. */
 function get(self) {
 	return Effect.sync(() => getUnsafe(self));
@@ -116,4 +124,4 @@ function observerCountUnsafe(self) {
 	return entryOf(self).listeners.size;
 }
 //#endregion
-export { CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, subscribeUnsafe };
+export { CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, subscribeUnsafe };

package/package.json

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