@raf-query/core 0.0.19 → 0.1.1

package/CHANGELOG.md

@@ -1,10 +1,31 @@
 # 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))
+
+- **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))
+
 ## [0.0.19](https://github.com/KATT/raf-query/compare/0.0.18...0.0.19) (2026-10-12)
 
 ### Features
 
-* **core:** type the cache's promises as Thenable ([#21](https://github.com/KATT/raf-query/issues/21)) ([c0541b0](https://github.com/KATT/raf-query/commit/c0541b0c14e687f25d47f25fe457e49b135d8c06))
+- **core:** type the cache's promises as Thenable ([#21](https://github.com/KATT/raf-query/issues/21)) ([c0541b0](https://github.com/KATT/raf-query/commit/c0541b0c14e687f25d47f25fe457e49b135d8c06))
 
 ## [0.0.18](https://github.com/KATT/raf-query/compare/0.0.17...0.0.18) (2026-10-12)
 

package/README.md

@@ -6,16 +6,18 @@ Queries start in route loaders and React Server Components, travel to components
 
 The cache's mechanics (dedupe, staleness, retries, infinite paging, SSR hydration) follow [TanStack Query](https://tanstack.com/query); the public API is built around loaders, RSC, and `use()` instead of `useQuery`-in-render.
 
+The cache is written in [Effect](https://effect.website), but using raf-query doesn't take any Effect: `queryFn`s return promises, and `QueryClient`, the hooks and the integrations speak promises. Apps that do use Effect get the same cache as Effects, with typed errors and services ([Effect](#effect)).
+
 ## Status
 
 Early. Both packages are on npm at `0.0.x`, and the API can still change between patch releases. [`examples/`](examples/) has the same issue tracker built on TanStack Start and on Next.js App Router.
 
 ## Packages
 
-| Package            | Contents                                                                                                                           |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `@raf-query/core`  | Framework-agnostic: `QueryClient`, cache, `queryOptions` / `infiniteQueryOptions`, handles, dehydrate / hydrate stream, `allKeyed` |
-| `@raf-query/react` | Hooks and provider. Re-exports everything from `@raf-query/core`, so apps install and import only this package                     |
+| Package            | Contents                                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@raf-query/core`  | Framework-agnostic and Effect-only: `QueryCache`, `queryOptions` / `infiniteQueryOptions`, handles, dehydrate / hydrate                     |
+| `@raf-query/react` | `QueryClient` (the cache with Promise methods), hooks, provider, `allKeyed`. Re-exports `@raf-query/core`, so apps import only this package |
 
 `@raf-query/react` subpath entries for framework integrations and tooling:
 
@@ -356,14 +358,24 @@ 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
+```
 
-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; `qc.getQuery(factory, input).getState().hasData` tells them apart.
+`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.
 
 ## SSR and hydration
 
@@ -392,7 +404,7 @@ export function getRouter() {
 }
 ```
 
-`setupRouterIntegration` streams queries during SSR, clears the request's cache when the response finishes, and turns `redirect()` thrown from a `queryFn` into a router navigation. `getRouter` runs per request on the server, so each request gets its own client. Options: `dehydrateOptions` (`filter`, `keepErrors`, `serializeData`), `hydrateOptions` (`deserializeData`), and `handleRedirects: false` to handle redirects yourself. By default a server error crosses to the browser as a generic error, so its message doesn't leak into the page.
+`setupRouterIntegration` streams queries during SSR, clears the request's cache when the response finishes, and turns `redirect()` thrown from a `queryFn` into a router navigation. `getRouter` runs per request on the server, so each request gets its own client. Options: `dehydrateOptions` (`filter`, `keepErrors`, `serializeData`), `hydrateOptions` (`deserializeData`), and `handleRedirects: false` to handle redirects yourself. By default a server error crosses to the browser as a `RedactedError` naming the query, so its message doesn't leak into the page.
 
 ### Next.js App Router
 
@@ -458,13 +470,19 @@ A factory that imports server-only code (a database client) can't be imported by
 
 ## Effect
 
-raf-query runs requests on [Effect](https://effect.website), and Effect code can use it without wrapping:
+raf-query's cache is written in [Effect](https://effect.website): `QueryClient` is a Promise wrapper around a `QueryCache` service from `@raf-query/core`, available as `qc.effect`. Effect code uses the cache directly, or builds its own with `QueryCache.make(config)` (scoped: closing the scope interrupts every request and timer) or `QueryCache.layer(config)`:
 
 - A `queryFn` can return an `Effect`. Cancelling the request interrupts it.
+- An Effect `queryFn`'s error type is the query's: `qc.effect.fetch(issueQuery, input)` fails with `IssueNotFound | Query.CancelledError`. `ErrorOf<TFactory>` names it; it's `unknown` for promises. A `queryFn` that throws instead of returning is a defect, and isn't retried.
 - `retry` accepts a `Schedule` as well as a count or predicate.
-- `qc.effect` has Effect versions of `ensure`, `fetch` and `invalidate`, plus `watch`, a `Stream` of the entry's state.
+- `qc.effect` has every verb as an Effect: `prefetch`, `ensure`, `fetch`, `invalidate`, `reset`, `remove`, `setData`, `getData` (an `Option`), `dehydrate`, `hydrate`. `watch` is a `Stream` of an entry's state, and `events` a `Stream` of cache events.
+- SSR streaming is Effect too, and the integrations are thin wrappers over it. `dehydrateStream(options)` (scoped) returns the cache's `initial` state and a `Stream` of `updates`: entries that start or settle later, each sent once, batched per microtask. The stream ends when the scope closes. `hydrateStream(stream)` hydrates each state as it arrives. `Stream.toReadableStream` / `Stream.fromReadableStream` carry it over a web stream. The `sent` option (a `Set` of hashes) makes separate `dehydrate` calls of one request skip entries already sent.
+- Entries are a data type with module functions, as in Effect's own modules: `Query.fetch(query)`, `Query.refetch(query)`, `Query.invalidate(query)`, `Query.changes(query)`, and `Query.getUnsafe(query)` / `Query.subscribeUnsafe(query, listener)` for synchronous reads.
+- `QueryObserver` is a data type too: one reader's view of a query, as `useQuery` sees it (the controls and the promise, with `whilePending`, `refetchInterval` and the focus / reconnect options). `QueryObserver.make(query, options)` creates one, and `QueryObserver.changes(observer)` streams its results; while it runs, the query counts as read and polls on `refetchInterval`.
+- Time comes from the `Clock` and the page from the `Platform` service (focus, visibility, `navigator.onLine`; the default reads the globals). Provide `TestClock` or another `Platform` to test staleness, gc and offline retries without a browser.
 
 ```ts
+import { QueryCache, queryOptions } from "@raf-query/core";
 import { Effect, Schedule, Stream } from "effect";
 
 export function issueQuery(input: { id: number }) {
@@ -476,15 +494,69 @@ export function issueQuery(input: { id: number }) {
 }
 
 const program = Effect.gen(function* () {
-	const issue = yield* qc.effect.fetch(issueQuery, { id: 1 });
-	yield* qc.effect.watch(issueQuery, { id: 1 }).pipe(
+	const cache = yield* QueryCache.QueryCache;
+	const issue = yield* cache.fetch(issueQuery, { id: 1 });
+	yield* cache.watch(issueQuery, { id: 1 }).pipe(
 		Stream.map((state) => state.data?.title),
 		Stream.runForEach((title) => Effect.log(title)),
 	);
 });
+
+Effect.runFork(program.pipe(Effect.provide(QueryCache.layer())));
+```
+
+`watch` counts as a reader while it runs, so invalidation and window focus refetch the entry. Outside React, `cache.mount` (`Effect<void, never, Scope>`) refetches read, stale entries on window focus and reconnect while its scope is open.
+
+### Services
+
+A `queryFn`'s Effect can require services. They're part of the factory's type, `ServicesOf<TFactory>`, and every verb that can start the query requires them:
+
+```ts
+import { QueryCache, queryOptions } from "@raf-query/core";
+import { Context, Effect, Layer } from "effect";
+
+class IssueApi extends Context.Service<
+	IssueApi,
+	{ readonly get: (id: number) => Effect.Effect<Issue, IssueNotFound> }
+>()("app/IssueApi") {}
+
+const IssueApiLive = Layer.succeed(IssueApi, { get: IssueRepo.get });
+
+export function issueQuery(input: { id: number }) {
+	return queryOptions({
+		queryKey: ["issue", input.id],
+		queryFn: () =>
+			Effect.gen(function* () {
+				const api = yield* IssueApi;
+				return yield* api.get(input.id);
+			}),
+	});
+}
+
+// Effect<Issue, IssueNotFound | Query.CancelledError, QueryCache | IssueApi>
+const issue = QueryCache.QueryCache.use((cache) =>
+	cache.fetch(issueQuery, { id: 1 }),
+);
+
+Effect.runFork(
+	issue.pipe(Effect.provide(QueryCache.layer()), Effect.provide(IssueApiLive)),
+);
+```
+
+- On `QueryCache`, `ensure`, `fetch`, `prefetch`, `getQuery` and `watch` require the factory's services, and so does `Query.fetch`. A request runs with the services the cache was built with, under those of the latest of these calls for its entry. Requests that start without a caller (a render's read, `refetch`, polling, focus and reconnect, `invalidate`) reuse the entry's last services.
+- The caller's `Scope` isn't passed on: a request outlives the call that started it. Scope a `queryFn`'s resources with `Effect.scoped`.
+- Each request runs in a `raf-query.request` span with a `raf_query.hash` attribute, under the latest caller's span if it had one. Defects are logged with `Effect.logError`; typed failures are the query's error.
+
+`QueryClient` gets its services from a `layer`. It's built into the client's scope with the cache, so it must build synchronously. The client's type is `QueryClient<TServices>`, and its verbs accept only factories whose services the layer provides; any other factory is a type error. `dispose()` interrupts every request and runs the layer's finalizers:
+
+```ts
+const queryClient = new QueryClient({ layer: IssueApiLive }); // QueryClient<IssueApi>
+const handle = queryClient.prefetch(issueQuery, { id: 1 });
+
+await queryClient.dispose();
 ```
 
-`watch` counts as a reader while it runs, so invalidation and window focus refetch the entry.
+`QueryClientProvider` takes a client of any services. A hook can't know which ones, so `useQueryClient()` returns a `QueryClient<unknown>`, whose verbs accept any factory, and `useQuery` reads any factory: a request then fails with a defect if the client's layer lacks a service it needs.
 
 ## Devtools
 
@@ -533,17 +605,18 @@ Both render nothing on the server, since the server's cache isn't the browser's.
 
 | Member                                      | Use                                                                                                                     |
 | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `new QueryClient(config?)`                  | `config.defaults` (query options below), `config.onError`, `config.isServer`                                            |
+| `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                                                                                 |
-| `effect`                                    | [Effect versions](#effect) of `ensure`, `fetch`, `invalidate`, plus `watch`                                             |
+| `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                                                                            |
 | `clear()`                                   | Drop every entry and abort in-flight requests                                                                           |
 | `mount()`                                   | Start window-focus and reconnect refetching. The providers call it                                                      |
 | `isServer`                                  | Detected from `window`. Server clients don't retry, never gc, skip stale timers, and never revalidate cached data       |
+| `dispose()`                                 | Interrupt every request and release the layer's services. Resolves when its finalizers have run                         |
 
 Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.defaults`:
 
@@ -562,29 +635,34 @@ In the browser, retries pause while `navigator.onLine` is `false`: after the ret
 
 `@raf-query/core`:
 
-| Export                                         | Use                                                              |
-| ---------------------------------------------- | ---------------------------------------------------------------- |
-| `QueryClient`                                  | The cache                                                        |
-| `queryOptions(options)`                        | Typed options for a query factory                                |
-| `infiniteQueryOptions(options)`                | Typed options for a paged query factory                          |
-| `allKeyed(record)`                             | Await a record of promises, keeping keys                         |
-| `dehydrate(client)` / `hydrate(client, state)` | Low-level cache transfer used by the integrations                |
-| `hashKey(key)`, `matchesKey(key, prefix)`      | Key helpers                                                      |
-| `QueryObserver`                                | One reader's view of a query, with tracked results; for bindings |
-| `CancelledError`                               | Rejection of a request cancelled by `clear()` or a restart       |
-| `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>`        | A factory's data and input types                                 |
+| 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      |
 
 `@raf-query/react` (plus all of the above):
 
-| Export                                | Use                                                                                                             |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `QueryClientProvider`                 | Provides a client to the tree                                                                                   |
-| `useQueryClient()`                    | Read the client                                                                                                 |
-| `useQuery(factory, handle, options?)` | `[Thenable<Data>, controls]`; for paged factories `Data` is `{ pages, pageParams }` and controls include paging |
-| `useWaterfall(factory, input)`        | Start a query during render and return its handle                                                               |
+| Export                                         | Use                                                                                                             |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `QueryClient`                                  | The cache with Promise methods ([above](#api-reference))                                                        |
+| `allKeyed(record)`                             | Await a record of promises, keeping keys                                                                        |
+| `dehydrate(client)` / `hydrate(client, state)` | Low-level cache transfer used by the integrations                                                               |
+| `QueryClientProvider`                          | Provides a client to the tree                                                                                   |
+| `useQueryClient()`                             | Read the client                                                                                                 |
+| `useQuery(factory, handle, options?)`          | `[Thenable<Data>, controls]`; for paged factories `Data` is `{ pages, pageParams }` and controls include paging |
+| `useWaterfall(factory, input)`                 | Start a query during render and return its handle                                                               |
 
 ## Development
 

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/cache.d.mts

@@ -0,0 +1,151 @@
+import { QueryKey } from "./key.mjs";
+import { DataOf, EnsuredQueryHandle, ErrorOf, InputArgs, InputOf, LoadOptions, QueryBehavior, QueryFactory, QueryHandle, ServicesOf } from "./options.mjs";
+import { DehydrateOptions, DehydratedState, DehydratedStream, HydrateOptions } from "./hydration.mjs";
+import { CancelledError, Of, Query, State, query_d_exports } from "./query.mjs";
+import { Context, Effect, Layer, Option, Scope, Stream } from "effect";
+declare namespace cache_d_exports {
+  export { Config, Event, Filter, LoadArgs, QueryCache, Target, TypeId, Updater, isQueryCache, layer, make };
+}
+export declare const TypeId = "~@raf-query/core/QueryCache";
+export type TypeId = typeof TypeId;
+export interface Config {
+  /** Defaults for every query; a factory's own options win. */
+  readonly defaults?: QueryBehavior;
+  /**
+   * Whether this cache runs on the server. Default: the {@link Platform}'s.
+   * Server caches don't retry, never garbage-collect, skip stale timers, and
+   * reuse cached data in `prefetch` / `ensure` / `fetch` instead of
+   * revalidating it, unless `invalidate` marked it.
+   */
+  readonly isServer?: boolean;
+}
+/** Emitted on {@link QueryCache.events} for every cache change. */
+export type Event = {
+  readonly query: Query;
+  /** `observers`: a reader subscribed or unsubscribed. */
+  readonly type: "added" | "observers" | "removed" | "updated";
+} | {
+  /** A request failed (after retries), with this error. */
+  readonly error: unknown;
+  readonly query: Query;
+  readonly type: "failed";
+};
+/**
+ * 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;
+  /**
+   * 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>];
+/** The entries `invalidate`, `reset` and `remove` act on: one factory call, or a filter. */
+export type Target<TFactory extends QueryFactory> = [factory: TFactory, ...args: InputArgs<TFactory>] | [filter: Filter];
+/**
+ * A new value, or a function of the current one. `previous` is `undefined`
+ * both with no data and with `undefined` data.
+ */
+export type Updater<TData> = TData | ((previous: TData | undefined) => TData);
+export interface QueryCache {
+  /** Every entry. */
+  readonly all: Effect.Effect<ReadonlyArray<Query>>;
+  /** Drop every entry and interrupt their requests. */
+  readonly clear: Effect.Effect<void>;
+  /** Snapshot the cache for transfer to another cache (server → browser). */
+  dehydrate(options?: DehydrateOptions): Effect.Effect<DehydratedState>;
+  /**
+   * Snapshot the cache, then stream entries as they start or settle, each
+   * entry once. Entries that change in the same tick share a batch, which
+   * is sent a microtask later. `updates` ends when the scope closes, after
+   * sending what changed before; `hydrateStream` is the receiving end.
+   */
+  dehydrateStream(options?: DehydrateOptions): Effect.Effect<DehydratedStream, never, Scope.Scope>;
+  /**
+   * Start a query and wait for it on a cache miss. Fails if that request
+   * fails. Stale cached data succeeds immediately and revalidates in the
+   * browser. The handle is marked `ensured`, so `useQuery` returns its data
+   * directly.
+   */
+  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<EnsuredQueryHandle<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
+  /** Cache events from the moment the stream starts. */
+  readonly events: Stream.Stream<Event>;
+  /** Like `ensure`, but succeeds with the data. */
+  fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<DataOf<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
+  /**
+   * Cached data for a factory call. `Some(undefined)` when the data itself
+   * is `undefined`.
+   */
+  getData<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Effect.Effect<Option.Option<DataOf<TFactory>>>;
+  /**
+   * The cache entry for a factory call, created if missing. Doesn't fetch,
+   * but its requests run with this fiber's services from now on. For
+   * bindings; apps use the verbs.
+   */
+  getQuery<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Effect.Effect<Of<TFactory>, never, ServicesOf<TFactory>>;
+  /**
+   * `getQuery`, synchronously, for renders. Leaves the entry's services as
+   * they are: the cache's, or the latest verb caller's.
+   */
+  getQueryUnsafe<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Of<TFactory>;
+  /**
+   * Write dehydrated entries. Existing entries only take newer data; pending
+   * entries resume the sender's request.
+   */
+  hydrate(state: DehydratedState, options?: HydrateOptions): Effect.Effect<void>;
+  /** `hydrate` every state of a stream as it arrives (`dehydrateStream`'s `updates`). */
+  hydrateStream<E, R>(states: Stream.Stream<DehydratedState, E, R>, options?: HydrateOptions): Effect.Effect<void, E, R>;
+  /**
+   * Mark queries stale and refetch the ones being read. Succeeds once those
+   * refetches settle, so an action stays pending until fresh data is on
+   * screen.
+   */
+  invalidate<TFactory extends QueryFactory>(...target: Target<TFactory>): Effect.Effect<void>;
+  readonly isServer: boolean;
+  /**
+   * Refetch read, stale queries on window focus and reconnect while the
+   * scope is open. Mounts share one platform subscription. Does nothing on
+   * the server.
+   */
+  readonly mount: Effect.Effect<void, never, Scope.Scope>;
+  /**
+   * Start a query without waiting and return its handle. Fresh data is
+   * reused; stale data refetches in the background (in the browser only, see
+   * {@link Config.isServer}). Errors surface where the data is read, never
+   * here.
+   */
+  prefetch<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Effect.Effect<QueryHandle<TFactory>, never, ServicesOf<TFactory>>;
+  /**
+   * Remove queries from the cache and interrupt their requests. Readers keep
+   * the removed entry until they render again.
+   */
+  remove<TFactory extends QueryFactory>(...target: Target<TFactory>): Effect.Effect<void>;
+  /**
+   * Drop queries' data and errors, as if they were never fetched. Read ones
+   * suspend and refetch; succeeds once those refetches settle.
+   */
+  reset<TFactory extends QueryFactory>(...target: Target<TFactory>): Effect.Effect<void>;
+  /** Write data for a factory call. Readers re-render without suspending. */
+  setData<TFactory extends QueryFactory>(factory: TFactory, input: InputOf<TFactory>, updater: Updater<DataOf<TFactory>>): Effect.Effect<void>;
+  /** Listen to cache events synchronously, as they happen. */
+  subscribeUnsafe(listener: (event: Event) => void): () => void;
+  readonly [TypeId]: TypeId;
+  /** A factory call's `Query.changes`. */
+  watch<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Stream.Stream<State<DataOf<TFactory>>, never, ServicesOf<TFactory>>;
+}
+export declare const QueryCache: Context.Service<QueryCache, QueryCache>;
+export declare function isQueryCache(value: unknown): value is QueryCache;
+/** Build a cache in the current scope, with the current `Clock` and {@link Platform}. */
+export declare const make: (config?: Config) => Effect.Effect<QueryCache, never, Scope.Scope>;
+/** A layer that provides a {@link QueryCache} for the layer's lifetime. */
+export declare const layer: (config?: Config) => Layer.Layer<QueryCache>;
+//#endregion
+export { cache_d_exports };

package/dist/cache.mjs

@@ -0,0 +1,185 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { Platform } from "./platform.mjs";
+import { unsafeCast } from "./cast.mjs";
+import { listen } from "./listen.mjs";
+import { hashKey, matchesKey } from "./key.mjs";
+import { changes, emit, fetch, invalidate, isObserved, isStaleUnsafe, make as make$1, onPlatformEvent, provide, remove, reset, setData, setOptions, start } from "./entry.mjs";
+import { dehydrateEntries, dehydrateStream, hydrateEntries } from "./hydration.mjs";
+import { optionsFor } from "./options.mjs";
+import { Clock, Context, Effect, Layer, Option, Predicate, RcRef, Stream } from "effect";
+//#region src/cache.ts
+/**
+* The query cache, as an Effect service. `make` builds one in the current
+* scope; closing the scope interrupts every request and timer it started.
+* Everything that waits, or changes the cache, is an Effect; `getQueryUnsafe`
+* and `subscribeUnsafe` are for renders and external stores.
+*
+* Requests run with the services the cache was built with, under those of
+* the latest verb that called for the entry. So the verbs that can start a
+* request (`ensure`, `fetch`, `prefetch`, `getQuery`, `watch`) require the
+* factory's {@link ServicesOf}; requests a render, a refetch or `invalidate`
+* starts reuse the entry's last services.
+*/
+var cache_exports = /* @__PURE__ */ __exportAll({
+	QueryCache: () => QueryCache,
+	TypeId: () => TypeId,
+	isQueryCache: () => isQueryCache,
+	layer: () => layer,
+	make: () => make
+});
+const TypeId = "~@raf-query/core/QueryCache";
+const QueryCache = Context.Service(TypeId);
+function isQueryCache(value) {
+	return Predicate.hasProperty(value, TypeId);
+}
+function isUpdateFunction(updater) {
+	return Predicate.isFunction(updater);
+}
+function typed(entry) {
+	return unsafeCast(entry);
+}
+function handleOf(entry) {
+	return unsafeCast(entry.handle);
+}
+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
+* never shown; it refetches only what `invalidate` marked.
+*/
+function revalidate(entry) {
+	const state = entry.state;
+	const wanted = entry.cache.isServer ? state.isInvalidated : isStaleUnsafe(entry);
+	if (!state.isFetching && wanted) start(entry);
+}
+/**
+* Waits for an entry's data on a cache miss. Cached data returns at once,
+* and revalidates in the background (see `revalidate`).
+*/
+function load(entry, pages) {
+	if (!entry.state.hasData) return unsafeCast(fetch(entry, { pages }));
+	revalidate(entry);
+	return Effect.succeed(dataOf(entry));
+}
+/** Settles every effect, started together. */
+function settleAll(effects) {
+	return Effect.all(effects, {
+		concurrency: "unbounded",
+		discard: true
+	});
+}
+/** Build a cache in the current scope, with the current `Clock` and {@link Platform}. */
+const make = Effect.fnUntraced(function* (config = {}) {
+	const platform = yield* Platform;
+	const state = {
+		clock: yield* Clock.Clock,
+		defaults: config.defaults ?? {},
+		entries: /* @__PURE__ */ new Map(),
+		isServer: config.isServer ?? platform.isServer,
+		listeners: /* @__PURE__ */ new Set(),
+		platform,
+		scope: yield* Effect.scope,
+		services: yield* Effect.context()
+	};
+	const entryFor = (key) => {
+		const hash = hashKey(key);
+		const existing = state.entries.get(hash);
+		if (existing) return existing;
+		const entry = make$1(state, key, hash);
+		state.entries.set(hash, entry);
+		emit(state, {
+			query: entry,
+			type: "added"
+		});
+		return entry;
+	};
+	const build = (factory, input) => {
+		const options = optionsFor(factory, input);
+		const entry = entryFor(options.queryKey);
+		setOptions(entry, options, input);
+		return entry;
+	};
+	/** `build`, for a verb: the entry's requests get the caller's services. */
+	const buildFor = (factory, input) => Effect.contextWith((caller) => {
+		const entry = build(factory, input);
+		provide(entry, caller);
+		return Effect.succeed(entry);
+	});
+	const match = (target) => {
+		const [first, input] = unsafeCast(target);
+		if (Predicate.isFunction(first)) {
+			const entry = state.entries.get(hashKey(optionsFor(first, input).queryKey));
+			return entry ? [entry] : [];
+		}
+		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);
+	})), (unsubscribe) => Effect.sync(unsubscribe)) });
+	const subscribeUnsafe = (listener) => {
+		state.listeners.add(listener);
+		return () => {
+			state.listeners.delete(listener);
+		};
+	};
+	const getQueryUnsafe = (factory, ...args) => typed(build(factory, args[0]));
+	return {
+		all: Effect.sync(() => [...state.entries.values()]),
+		clear: Effect.sync(() => {
+			for (const entry of state.entries.values()) remove(entry);
+		}),
+		dehydrate: (options = {}) => Effect.sync(() => dehydrateEntries(state.entries.values(), options)),
+		dehydrateStream: (options = {}) => dehydrateStream(() => state.entries.values(), subscribeUnsafe, options),
+		ensure: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages).pipe(Effect.as({
+			...handleOf(entry),
+			ensured: true
+		}))),
+		events: listen(subscribeUnsafe),
+		fetch: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages)),
+		getData: (factory, ...args) => Effect.sync(() => {
+			const options = optionsFor(factory, args[0]);
+			const entry = state.entries.get(hashKey(options.queryKey));
+			return entry?.state.hasData ? Option.some(dataOf(entry)) : Option.none();
+		}),
+		getQuery: (factory, ...args) => Effect.map(buildFor(factory, args[0]), typed),
+		getQueryUnsafe,
+		hydrate: (dehydrated, options = {}) => Effect.sync(() => hydrateEntries(entryFor, dehydrated, options)),
+		hydrateStream: (states, options = {}) => Stream.runForEach(states, (dehydrated) => Effect.sync(() => hydrateEntries(entryFor, dehydrated, options))),
+		invalidate: (...target) => Effect.suspend(() => settleAll(match(target).map(invalidate))),
+		isServer: state.isServer,
+		mount: state.isServer ? Effect.void : Effect.asVoid(RcRef.get(subscription)),
+		prefetch: (factory, ...args) => Effect.map(buildFor(factory, args[0]), (entry) => {
+			if (entry.state.hasData) revalidate(entry);
+			else start(entry);
+			return handleOf(entry);
+		}),
+		remove: (...target) => Effect.sync(() => {
+			for (const entry of match(target)) remove(entry);
+		}),
+		reset: (...target) => Effect.suspend(() => settleAll(match(target).map(reset))),
+		setData: (factory, input, updater) => Effect.sync(() => {
+			const entry = build(factory, input);
+			const next = isUpdateFunction(updater) ? updater(entry.state.hasData ? dataOf(entry) : void 0) : updater;
+			setData(entry, next);
+		}),
+		subscribeUnsafe,
+		[TypeId]: TypeId,
+		watch: (factory, ...args) => Stream.unwrap(Effect.map(buildFor(factory, args[0]), (entry) => unsafeCast(changes(entry))))
+	};
+});
+/** A layer that provides a {@link QueryCache} for the layer's lifetime. */
+const layer = (config) => Layer.effect(QueryCache, make(config));
+//#endregion
+export { QueryCache, TypeId, cache_exports, isQueryCache, layer, make };