@raf-query/core 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,19 +1,25 @@
 # Changelog
 
+## [0.1.1](https://github.com/KATT/raf-query/compare/0.1.0...0.1.1) (2026-10-12)
+
+### Features
+
+* **core:** add predicate to QueryFilter ([#24](https://github.com/KATT/raf-query/issues/24)) ([c0b9c18](https://github.com/KATT/raf-query/commit/c0b9c1829cb3b6446f765b151e520f0195af5276))
+
 ## [0.1.0](https://github.com/KATT/raf-query/compare/0.0.19...0.1.0) (2026-10-12)
 
 ### ⚠ BREAKING CHANGES
 
-* Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23))
-* **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29))
+- Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23))
+- **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29))
 
-* **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29)) ([50fbb45](https://github.com/KATT/raf-query/commit/50fbb45bf3edcaa83673e2177894a76bdf76560b))
-* Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23)) ([8e0bb09](https://github.com/KATT/raf-query/commit/8e0bb09a63d644ede053f443406a521ff2613a6f))
+- **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29)) ([50fbb45](https://github.com/KATT/raf-query/commit/50fbb45bf3edcaa83673e2177894a76bdf76560b))
+- Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23)) ([8e0bb09](https://github.com/KATT/raf-query/commit/8e0bb09a63d644ede053f443406a521ff2613a6f))
 
 ### Features
 
-* **core:** stream SSR dehydration as Effect APIs; integrations become thin edges ([#30](https://github.com/KATT/raf-query/issues/30)) ([6b2b570](https://github.com/KATT/raf-query/commit/6b2b5703f5463c0f3805c233cf4ead90df9efb76)), references [#29](https://github.com/KATT/raf-query/issues/29)
-* typed services for Effect queries; QueryClient layer and dispose() ([#31](https://github.com/KATT/raf-query/issues/31)) ([6aeaa3d](https://github.com/KATT/raf-query/commit/6aeaa3d356f6483654729620ac26762508eb8fd8))
+- **core:** stream SSR dehydration as Effect APIs; integrations become thin edges ([#30](https://github.com/KATT/raf-query/issues/30)) ([6b2b570](https://github.com/KATT/raf-query/commit/6b2b5703f5463c0f3805c233cf4ead90df9efb76)), references [#29](https://github.com/KATT/raf-query/issues/29)
+- typed services for Effect queries; QueryClient layer and dispose() ([#31](https://github.com/KATT/raf-query/issues/31)) ([6aeaa3d](https://github.com/KATT/raf-query/commit/6aeaa3d356f6483654729620ac26762508eb8fd8))
 
 ## [0.0.19](https://github.com/KATT/raf-query/compare/0.0.18...0.0.19) (2026-10-12)
 

package/README.md

@@ -358,12 +358,22 @@ function EditTitle(props: { post: Post }) {
 
 `updatePost` is a server function (or a Next.js server action). `await qc.invalidate(...)` resolves once every query currently being read has refetched, so the action's pending state lasts until the fresh data is on screen. For an error message, wrap the action in `useActionState` and return the caught error.
 
-| Call                                  | Effect                                                                  |
-| ------------------------------------- | ----------------------------------------------------------------------- |
-| `qc.invalidate(factory, input)`       | Mark one query stale and refetch it if it is being read                 |
-| `qc.invalidate({ queryKey, exact? })` | Same, for every query whose key starts with `queryKey` (unless `exact`) |
-| `qc.setData(factory, input, updater)` | Write data directly                                                     |
-| `qc.getData(factory, input)`          | Read cached data, or `undefined`                                        |
+| Call                                  | Effect                                                  |
+| ------------------------------------- | ------------------------------------------------------- |
+| `qc.invalidate(factory, input)`       | Mark one query stale and refetch it if it is being read |
+| `qc.invalidate(filter)`               | Same, for every query the [filter](#filters) selects    |
+| `qc.setData(factory, input, updater)` | Write data directly                                     |
+| `qc.getData(factory, input)`          | Read cached data, or `undefined`                        |
+
+### Filters
+
+`invalidate`, `reset` and `remove` also take a filter, `{ queryKey?, exact?, predicate? }`. `queryKey` selects every query whose key starts with it, or only that key with `exact: true`; object segments match partially, so `{ queryKey: ["issues", { projectId: 3 }] }` selects every issue list in project 3. `predicate` gets each remaining `Query` and keeps the ones it returns `true` for: read its `key` and `handle.input`, or use the `Query` functions (`Query.getUnsafe(query)` for its state, `Query.observerCountUnsafe(query)`, `Query.isStaleUnsafe(query)`). Without `queryKey` every key matches, so `{}` selects the whole cache.
+
+```ts
+qc.remove({ predicate: (query) => Query.observerCountUnsafe(query) === 0 }); // everything not being read
+```
+
+`handle.input` is the input of the latest factory call for that entry. An entry that was only hydrated, and not yet read or started on this client, has `undefined` input, so match on `key` to include those.
 
 Data can be `undefined` when the `queryFn`'s type allows it (`Promise<User | undefined>`); it's cached and reused like any other value, unlike in TanStack Query, where an `undefined` result is an error. So `getData` and an updater's `previous` return `undefined` both with no data and with `undefined` data; `Query.getUnsafe(qc.getQuery(factory, input)).hasData` tells them apart.
 
@@ -598,8 +608,8 @@ Both render nothing on the server, since the server's cache isn't the browser's.
 | `new QueryClient(config?)`                  | `config.defaults` (query options below), `config.onError`, `config.isServer`, `config.layer` ([services](#services))    |
 | `prefetch`, `ensure`, `fetch`               | [Start queries](#starting-queries)                                                                                      |
 | `invalidate`, `setData`, `getData`          | [Write and read the cache](#mutations)                                                                                  |
-| `reset(factory, input)` / `reset(filter)`   | Drop data and errors; read queries suspend and refetch. Resolves when they settle                                       |
-| `remove(factory, input)` / `remove(filter)` | Remove entries and abort their requests                                                                                 |
+| `reset(factory, input)` / `reset(filter)`   | Drop data and errors; read queries suspend and refetch. Resolves when they settle. [Filters](#filters)                  |
+| `remove(factory, input)` / `remove(filter)` | Remove entries and abort their requests. [Filters](#filters)                                                            |
 | `effect`                                    | The [Effect](#effect) `QueryCache` behind the client                                                                    |
 | `subscribe(listener)`                       | Cache events: `added`, `updated`, `observers` (a reader subscribed or left), `removed`, and `failed` (with the `error`) |
 | `getAll()`, `getQuery(factory, input?)`     | Cache entries, for devtools and integrations                                                                            |

package/dist/cache.d.mts

@@ -30,10 +30,21 @@ export type Event = {
   readonly query: Query;
   readonly type: "failed";
 };
-/** Matches cache entries by key prefix, or by exact key with `exact`. */
+/**
+ * Selects cache entries: by key prefix (exact key with `exact`), then by
+ * `predicate`. Without `queryKey` every key matches, so `{}` selects the
+ * whole cache.
+ */
 export interface Filter {
   readonly exact?: boolean;
-  readonly queryKey: QueryKey;
+  /**
+   * Keep only entries this returns `true` for; runs after key matching.
+   * `query.handle.input` is the input of the latest factory call, and stays
+   * `undefined` for an entry only hydrated so far; match on `query.key` to
+   * include those.
+   */
+  readonly predicate?: (query: Query) => boolean;
+  readonly queryKey?: QueryKey;
 }
 /** `ensure` / `fetch` arguments: the input, then load options for paged factories. */
 export type LoadArgs<TFactory extends QueryFactory> = InputArgs<TFactory> | [input: InputOf<TFactory>, options: LoadOptions<TFactory>];

package/dist/cache.mjs

@@ -44,6 +44,15 @@ function handleOf(entry) {
 function dataOf(entry) {
 	return unsafeCast(entry.state.data);
 }
+function keyMatcher(filter) {
+	const prefix = filter.queryKey;
+	if (prefix === void 0) return () => true;
+	if (filter.exact) {
+		const hash = hashKey(prefix);
+		return (entry) => entry.hash === hash;
+	}
+	return (entry) => matchesKey(entry.key, prefix);
+}
 /**
 * Background refetch of cached data a verb reuses. A server cache renders
 * once, so a refetch there could only duplicate a request whose result is
@@ -113,8 +122,8 @@ const make = Effect.fnUntraced(function* (config = {}) {
 			const entry = state.entries.get(hashKey(optionsFor(first, input).queryKey));
 			return entry ? [entry] : [];
 		}
-		const hash = hashKey(first.queryKey);
-		return [...state.entries.values()].filter((entry) => first.exact ? entry.hash === hash : matchesKey(entry.key, first.queryKey));
+		const keyMatches = keyMatcher(first);
+		return [...state.entries.values()].filter((entry) => keyMatches(entry) && (first.predicate?.(entry) ?? true));
 	};
 	const subscription = yield* RcRef.make({ acquire: Effect.acquireRelease(Effect.sync(() => platform.subscribeUnsafe((event) => {
 		for (const entry of state.entries.values()) if (isObserved(entry)) onPlatformEvent(entry, event);

package/package.json

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