@raf-query/react 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,10 +1,16 @@
 # 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))
+- **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)
 

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,6 +675,7 @@ 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`.
 
@@ -648,22 +685,23 @@ When the last reader of a query unsubscribes during a background refetch, a `que
 
 `@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/devtools-panel.mjs

@@ -273,6 +273,7 @@ function QueryDetails(props) {
 	const query = props.row.query;
 	const state = props.row.state;
 	const options = query.options;
+	const meta = Query.metaUnsafe(query);
 	const section = { padding: 8 };
 	return /* @__PURE__ */ jsxs("section", {
 		"aria-label": "Query details",
@@ -431,7 +432,21 @@ function QueryDetails(props) {
 					palette,
 					value: query.handle.input
 				})
-			})
+			}),
+			meta === void 0 ? null : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+				palette,
+				title: "Meta"
+			}), /* @__PURE__ */ jsx("div", {
+				style: {
+					...section,
+					fontFamily: monoFamily
+				},
+				children: /* @__PURE__ */ jsx(Explorer, {
+					depth: 0,
+					palette,
+					value: meta
+				})
+			})] })
 		]
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -40,7 +40,7 @@
     "./tanstack-router": "./dist/tanstack-router.mjs"
   },
   "dependencies": {
-    "@raf-query/core": "0.1.3",
+    "@raf-query/core": "0.1.4",
     "effect": "^4.0.1"
   },
   "peerDependencies": {