@raf-query/react 0.0.18 → 0.1.0

package/CHANGELOG.md

@@ -1,10 +1,31 @@
 # Changelog
 
+## [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))
+
 ## [0.0.18](https://github.com/KATT/raf-query/compare/0.0.17...0.0.18) (2026-10-12)
 
 ### Bug Fixes
 
-* **core:** allow undefined query data ([#22](https://github.com/KATT/raf-query/issues/22)) ([9b85e57](https://github.com/KATT/raf-query/commit/9b85e57bf2fed4413cdbc1b49f925cc60dad695f)), references [#20](https://github.com/KATT/raf-query/issues/20)
+- **core:** allow undefined query data ([#22](https://github.com/KATT/raf-query/issues/22)) ([9b85e57](https://github.com/KATT/raf-query/commit/9b85e57bf2fed4413cdbc1b49f925cc60dad695f)), references [#20](https://github.com/KATT/raf-query/issues/20)
 
 ## [0.0.17](https://github.com/KATT/raf-query/compare/0.0.16...0.0.17) (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:
 
@@ -363,7 +365,7 @@ function EditTitle(props: { post: Post }) {
 | `qc.setData(factory, input, updater)` | Write data directly                                                     |
 | `qc.getData(factory, input)`          | Read cached data, or `undefined`                                        |
 
-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.
+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 +394,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 +460,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 +484,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 +595,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`                                             |
+| `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,28 +625,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`                            |
-| `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?)` | `[Promise<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/all-keyed.d.mts

@@ -0,0 +1,18 @@
+//#region src/all-keyed.d.ts
+/** The resolved form of a record passed to {@link allKeyed}. */
+export type Settled<TRecord> = { -readonly [TKey in keyof TRecord]: Awaited<TRecord[TKey]>; };
+/**
+ * Ponyfill of the TC39 `Promise.allKeyed` proposal: a record of promises in,
+ * a promise of the same record out, rejecting on the first failure.
+ *
+ * ```ts
+ * const data = await allKeyed({
+ *   post: qc.ensure(postQuery, { slug }),
+ *   author: qc.ensure(authorQuery, { slug }),
+ * });
+ * ```
+ */
+export declare function allKeyed<TRecord extends {
+  readonly [key: string]: unknown;
+}>(record: TRecord): Promise<Settled<TRecord>>;
+//#endregion

package/dist/all-keyed.mjs

@@ -0,0 +1,19 @@
+//#region src/all-keyed.ts
+/**
+* Ponyfill of the TC39 `Promise.allKeyed` proposal: a record of promises in,
+* a promise of the same record out, rejecting on the first failure.
+*
+* ```ts
+* const data = await allKeyed({
+*   post: qc.ensure(postQuery, { slug }),
+*   author: qc.ensure(authorQuery, { slug }),
+* });
+* ```
+*/
+async function allKeyed(record) {
+	const keys = Object.keys(record);
+	const values = await Promise.all(keys.map((key) => record[key]));
+	return Object.fromEntries(keys.map((key, index) => [key, values[index]]));
+}
+//#endregion
+export { allKeyed };

package/dist/client.d.mts

@@ -0,0 +1,94 @@
+import { DataOf, DehydrateOptions, DehydratedState, EnsuredQueryHandle, HydrateOptions, InputArgs, InputOf, Query, QueryCache, QueryFactory, QueryHandle } from "@raf-query/core";
+import { Layer } from "effect";
+//#region src/client.d.ts
+export interface QueryClientConfig<TServices = never> extends QueryCache.Config {
+  /**
+   * Services for queries whose `queryFn` returns an Effect. Built with the
+   * client, so it must build synchronously; `dispose()` runs its
+   * finalizers.
+   */
+  readonly layer?: Layer.Layer<TServices>;
+  /** Called with every failed request, including failed prefetches. */
+  onError?(error: unknown, query: Query.Query): void;
+}
+/**
+ * The query cache, with Promise methods. Create one per request on the
+ * server and one per browser tab. `effect` is the same cache's Effect API.
+ * Its verbs take factories whose `queryFn` needs at most `TServices`, the
+ * services of `config.layer`.
+ */
+export declare class QueryClient<TServices = never> {
+  #private;
+  /** The Effect-native cache behind this client. */
+  readonly effect: QueryCache.QueryCache;
+  readonly isServer: boolean;
+  constructor(config?: QueryClientConfig<TServices>);
+  /**
+   * The cache entry for a factory call, created if missing. Doesn't fetch.
+   * For bindings; apps use the verbs.
+   */
+  getQuery<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Query.Of<TFactory>;
+  /**
+   * Start a query without waiting and return its handle. Fresh data is
+   * reused; stale data refetches in the background (in the browser only).
+   * Errors surface where the data is read, never here.
+   */
+  prefetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): QueryHandle<TFactory>;
+  /**
+   * Start a query and wait for it on a cache miss. Rejects if that request
+   * fails. Stale cached data resolves immediately and revalidates in the
+   * browser. The handle is marked `ensured`, so `useQuery` returns its data
+   * directly.
+   */
+  ensure<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: QueryCache.LoadArgs<TFactory>): Promise<EnsuredQueryHandle<TFactory>>;
+  /** Like `ensure`, but resolves to the data. */
+  fetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: QueryCache.LoadArgs<TFactory>): Promise<DataOf<TFactory>>;
+  /**
+   * Mark queries stale and refetch the ones being read. Resolves once those
+   * refetches settle, so an action stays pending until fresh data is on
+   * screen. Takes a factory and its input, or a {@link QueryFilter}.
+   */
+  invalidate<TFactory extends QueryFactory<TServices>>(...target: QueryCache.Target<TFactory>): Promise<void>;
+  /**
+   * Drop queries' data and errors, as if they were never fetched. Read ones
+   * suspend and refetch; resolves once those refetches settle.
+   */
+  reset<TFactory extends QueryFactory<TServices>>(...target: QueryCache.Target<TFactory>): Promise<void>;
+  /**
+   * Remove queries from the cache and abort their requests. Readers keep the
+   * removed entry until they render again.
+   */
+  remove<TFactory extends QueryFactory<TServices>>(...target: QueryCache.Target<TFactory>): void;
+  /** Write data for a factory call. Readers re-render without suspending. */
+  setData<TFactory extends QueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, updater: QueryCache.Updater<DataOf<TFactory>>): void;
+  /**
+   * Cached data for a factory call, or `undefined` if there is none. Data can
+   * itself be `undefined`; `Query.getUnsafe(getQuery(...)).hasData` tells
+   * them apart.
+   */
+  getData<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): DataOf<TFactory> | undefined;
+  /** Every entry, for devtools and integrations. */
+  getAll(): ReadonlyArray<Query.Query>;
+  /** Listen to entries being added, updated, and removed. */
+  subscribe(listener: (event: QueryCache.Event) => void): () => void;
+  /** Drop every entry and abort in-flight requests. */
+  clear(): void;
+  /**
+   * Start refetching read, stale queries on window focus and reconnect.
+   * Returns the matching unmount. Providers call this; mounts are counted.
+   */
+  mount(): () => void;
+  /**
+   * Close the client: interrupt every request and timer, and release the
+   * layer's services. Resolves once the layer's finalizers have run.
+   */
+  dispose(): Promise<void>;
+}
+/** Snapshot the cache for transfer to another client (server → browser). */
+export declare function dehydrate(client: QueryClient, options?: DehydrateOptions): DehydratedState;
+/**
+ * Write dehydrated entries into a client. Existing entries only take newer
+ * data; pending entries resume the sender's request.
+ */
+export declare function hydrate(client: QueryClient, state: DehydratedState, options?: HydrateOptions): void;
+//#endregion

package/dist/client.mjs

@@ -0,0 +1,143 @@
+import { unsafeCast } from "./cast.mjs";
+import { QueryCache } from "@raf-query/core";
+import { Context, Effect, Exit, Layer, Option, Scope } from "effect";
+//#region src/client.ts
+/**
+* A verb's Effect, run by a client. Its requirement is the factory's
+* `ServicesOf`, which the client's verbs only accept when its `layer`
+* provides them.
+*/
+function provided(effect) {
+	return unsafeCast(effect);
+}
+/**
+* The query cache, with Promise methods. Create one per request on the
+* server and one per browser tab. `effect` is the same cache's Effect API.
+* Its verbs take factories whose `queryFn` needs at most `TServices`, the
+* services of `config.layer`.
+*/
+var QueryClient = class {
+	/** The Effect-native cache behind this client. */
+	effect;
+	isServer;
+	/**
+	* Owns the cache's fibers, mounts and the layer's services; lives until
+	* `dispose()`.
+	*/
+	#scope = Scope.makeUnsafe();
+	constructor(config = {}) {
+		const cache = QueryCache.layer(config);
+		const services = Effect.runSync(Layer.buildWithScope(config.layer ? Layer.provide(cache, config.layer) : cache, this.#scope));
+		this.effect = Context.get(services, QueryCache.QueryCache);
+		this.isServer = this.effect.isServer;
+		const onError = config.onError;
+		if (onError) this.effect.subscribeUnsafe((event) => {
+			if (event.type === "failed") onError(event.error, event.query);
+		});
+	}
+	/**
+	* The cache entry for a factory call, created if missing. Doesn't fetch.
+	* For bindings; apps use the verbs.
+	*/
+	getQuery(factory, ...args) {
+		return this.effect.getQueryUnsafe(factory, ...args);
+	}
+	/**
+	* Start a query without waiting and return its handle. Fresh data is
+	* reused; stale data refetches in the background (in the browser only).
+	* Errors surface where the data is read, never here.
+	*/
+	prefetch(factory, ...args) {
+		return Effect.runSync(provided(this.effect.prefetch(factory, ...args)));
+	}
+	/**
+	* Start a query and wait for it on a cache miss. Rejects if that request
+	* fails. Stale cached data resolves immediately and revalidates in the
+	* browser. The handle is marked `ensured`, so `useQuery` returns its data
+	* directly.
+	*/
+	ensure(factory, ...args) {
+		return Effect.runPromise(provided(this.effect.ensure(factory, ...args)));
+	}
+	/** Like `ensure`, but resolves to the data. */
+	fetch(factory, ...args) {
+		return Effect.runPromise(provided(this.effect.fetch(factory, ...args)));
+	}
+	/**
+	* Mark queries stale and refetch the ones being read. Resolves once those
+	* refetches settle, so an action stays pending until fresh data is on
+	* screen. Takes a factory and its input, or a {@link QueryFilter}.
+	*/
+	invalidate(...target) {
+		return Effect.runPromise(this.effect.invalidate(...target));
+	}
+	/**
+	* Drop queries' data and errors, as if they were never fetched. Read ones
+	* suspend and refetch; resolves once those refetches settle.
+	*/
+	reset(...target) {
+		return Effect.runPromise(this.effect.reset(...target));
+	}
+	/**
+	* Remove queries from the cache and abort their requests. Readers keep the
+	* removed entry until they render again.
+	*/
+	remove(...target) {
+		Effect.runSync(this.effect.remove(...target));
+	}
+	/** Write data for a factory call. Readers re-render without suspending. */
+	setData(factory, input, updater) {
+		Effect.runSync(this.effect.setData(factory, input, updater));
+	}
+	/**
+	* Cached data for a factory call, or `undefined` if there is none. Data can
+	* itself be `undefined`; `Query.getUnsafe(getQuery(...)).hasData` tells
+	* them apart.
+	*/
+	getData(factory, ...args) {
+		return Option.getOrUndefined(Effect.runSync(this.effect.getData(factory, ...args)));
+	}
+	/** Every entry, for devtools and integrations. */
+	getAll() {
+		return Effect.runSync(this.effect.all);
+	}
+	/** Listen to entries being added, updated, and removed. */
+	subscribe(listener) {
+		return this.effect.subscribeUnsafe(listener);
+	}
+	/** Drop every entry and abort in-flight requests. */
+	clear() {
+		Effect.runSync(this.effect.clear);
+	}
+	/**
+	* Start refetching read, stale queries on window focus and reconnect.
+	* Returns the matching unmount. Providers call this; mounts are counted.
+	*/
+	mount() {
+		const scope = Scope.forkUnsafe(this.#scope);
+		Effect.runSync(this.effect.mount.pipe(Scope.provide(scope)));
+		return () => {
+			Effect.runSync(Scope.close(scope, Exit.void));
+		};
+	}
+	/**
+	* Close the client: interrupt every request and timer, and release the
+	* layer's services. Resolves once the layer's finalizers have run.
+	*/
+	dispose() {
+		return Effect.runPromise(Scope.close(this.#scope, Exit.void));
+	}
+};
+/** Snapshot the cache for transfer to another client (server → browser). */
+function dehydrate(client, options) {
+	return Effect.runSync(client.effect.dehydrate(options));
+}
+/**
+* Write dehydrated entries into a client. Existing entries only take newer
+* data; pending entries resume the sender's request.
+*/
+function hydrate(client, state, options) {
+	Effect.runSync(client.effect.hydrate(state, options));
+}
+//#endregion
+export { QueryClient, dehydrate, hydrate };

package/dist/devtools-panel.d.mts

@@ -1,4 +1,4 @@
-import { QueryClient } from "@raf-query/core";
+import { QueryClient } from "./client.mjs";
 import { CSSProperties } from "react";
 //#region src/devtools-panel.d.ts
 export type DevtoolsTheme = "dark" | "light" | "system";

package/dist/devtools-panel.mjs

@@ -1,9 +1,10 @@
 "use client";
 import { useOptionalQueryClient } from "./provider.mjs";
 import { countByStatus, sortOrders, statuses, useQueryRows, visibleRows } from "./devtools-store.mjs";
+import { Query } from "@raf-query/core";
+import { Effect, Predicate } from "effect";
 import { useState, useSyncExternalStore } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { Predicate } from "effect";
 //#region src/devtools-panel.tsx
 const palettes = {
 	dark: {
@@ -346,17 +347,17 @@ function QueryDetails(props) {
 						color: statusColors.fetching,
 						disabled: options === void 0 || state.isFetching,
 						label: "Refetch",
-						onClick: () => void query.refetch()
+						onClick: () => void Effect.runPromise(Query.refetch(query))
 					}),
 					/* @__PURE__ */ jsx(ActionButton, {
 						color: statusColors.stale,
 						label: "Invalidate",
-						onClick: () => void query.invalidate()
+						onClick: () => void Effect.runPromise(Query.invalidate(query))
 					}),
 					/* @__PURE__ */ jsx(ActionButton, {
 						color: statusColors.inactive,
 						label: "Reset",
-						onClick: () => void query.reset()
+						onClick: () => void Effect.runPromise(Query.reset(query))
 					}),
 					/* @__PURE__ */ jsx(ActionButton, {
 						color: statusColors.error,

package/dist/devtools-store.mjs

@@ -1,3 +1,4 @@
+import { Query } from "@raf-query/core";
 import { useSyncExternalStore } from "react";
 //#region src/devtools-store.ts
 const statuses = [
@@ -14,18 +15,18 @@ const sortOrders = [
 ];
 const stores = /* @__PURE__ */ new WeakMap();
 function statusOf(query) {
-	const state = query.getState();
+	const state = Query.getUnsafe(query);
 	if (state.isFetching) return "fetching";
 	if (state.status === "error") return "error";
-	if (query.observerCount === 0) return "inactive";
-	return query.isStaleNow() ? "stale" : "fresh";
+	if (Query.observerCountUnsafe(query) === 0) return "inactive";
+	return Query.isStaleUnsafe(query) ? "stale" : "fresh";
 }
 function rowOf(query) {
 	return {
 		hash: query.hash,
-		observers: query.observerCount,
+		observers: Query.observerCountUnsafe(query),
 		query,
-		state: query.getState(),
+		state: Query.getUnsafe(query),
 		status: statusOf(query)
 	};
 }

package/dist/hydrate.mjs

@@ -1,27 +1,21 @@
 "use client";
+import { hydrate } from "./client.mjs";
 import { useQueryClient } from "./provider.mjs";
-import { hashKey, hydrate } from "@raf-query/core";
+import { sentHashes } from "./sent.mjs";
+import { Query, hashKey } from "@raf-query/core";
 import { useEffect, useState } from "react";
 //#region src/hydrate.tsx
-const hydratedByClient = /* @__PURE__ */ new WeakMap();
-/** Hashes of entries a client received through {@link Hydrate}. */
-function hydratedHashes(client) {
-	return hydratedByClient.get(client) ?? /* @__PURE__ */ new Set();
-}
-function markHydrated(client, state) {
-	let hashes = hydratedByClient.get(client);
-	if (!hashes) {
-		hashes = /* @__PURE__ */ new Set();
-		hydratedByClient.set(client, hashes);
-	}
-	for (const query of state.queries) hashes.add(hashKey(query.key));
+/** In the SSR pass, entries from the RSC payload needn't be streamed again. */
+function markSent(client, state) {
+	const sent = sentHashes(client);
+	for (const query of state.queries) sent.add(hashKey(query.key));
 }
 /**
 * Entries the client has no data for, which children need during this
 * render, and entries it already shows, which must wait for a commit.
 */
 function split(client, state) {
-	const shown = new Set(client.getAll().filter((query) => query.getState().hasData).map((query) => query.hash));
+	const shown = new Set(client.getAll().filter((query) => Query.getUnsafe(query).hasData).map((query) => query.hash));
 	const isShown = (query) => shown.has(hashKey(query.key));
 	return {
 		deferred: { queries: state.queries.filter(isShown) },
@@ -43,7 +37,7 @@ function Hydrate(props) {
 	const [hydrated, setHydrated] = useState();
 	if (hydrated?.state !== state) {
 		const parts = split(client, state);
-		markHydrated(client, state);
+		markSent(client, state);
 		hydrate(client, parts.now, options);
 		setHydrated({
 			deferred: parts.deferred,
@@ -61,4 +55,4 @@ function Hydrate(props) {
 	return props.children;
 }
 //#endregion
-export { Hydrate, hydratedHashes };
+export { Hydrate };

package/dist/index.d.mts

@@ -1,5 +1,7 @@
+import { QueryClient, QueryClientConfig, dehydrate, hydrate } from "./client.mjs";
+import { Settled, allKeyed } from "./all-keyed.mjs";
 import { QueryClientProvider, useQueryClient } from "./provider.mjs";
 import { PagingControls, QueryControls, UseEnsuredQueryResult, UseQueryControls, UseQueryOptions, UseQueryResult, useQuery } from "./use-query.mjs";
 import { useWaterfall } from "./use-waterfall.mjs";
 export * from "@raf-query/core";
-export { type PagingControls, QueryClientProvider, type QueryControls, type UseEnsuredQueryResult, type UseQueryControls, type UseQueryOptions, type UseQueryResult, useQuery, useQueryClient, useWaterfall };
+export { type PagingControls, QueryClient, type QueryClientConfig, QueryClientProvider, type QueryControls, type Settled, type UseEnsuredQueryResult, type UseQueryControls, type UseQueryOptions, type UseQueryResult, allKeyed, dehydrate, hydrate, useQuery, useQueryClient, useWaterfall };

package/dist/index.mjs

@@ -1,5 +1,7 @@
+import { allKeyed } from "./all-keyed.mjs";
+import { QueryClient, dehydrate, hydrate } from "./client.mjs";
 import { QueryClientProvider, useQueryClient } from "./provider.mjs";
 import { useQuery } from "./use-query.mjs";
 import { useWaterfall } from "./use-waterfall.mjs";
 export * from "@raf-query/core";
-export { QueryClientProvider, useQuery, useQueryClient, useWaterfall };
+export { QueryClient, QueryClientProvider, allKeyed, dehydrate, hydrate, useQuery, useQueryClient, useWaterfall };

package/dist/next.d.mts

@@ -1,4 +1,5 @@
-import { DehydratedState, QueryClientConfig } from "@raf-query/core";
+import { QueryClientConfig } from "./client.mjs";
+import { DehydratedState } from "@raf-query/core";
 import { ReactNode } from "react";
 //#region src/next.d.ts
 declare global {

package/dist/next.mjs

@@ -1,7 +1,8 @@
 "use client";
+import { QueryClient, dehydrate, hydrate } from "./client.mjs";
 import { QueryClientProvider } from "./provider.mjs";
-import { hydratedHashes } from "./hydrate.mjs";
-import { QueryClient, dehydrateQuery, hydrate } from "@raf-query/core";
+import { sentHashes } from "./sent.mjs";
+import { Query } from "@raf-query/core";
 import { useState } from "react";
 import { jsx } from "react/jsx-runtime";
 import { useServerInsertedHTML } from "next/navigation";
@@ -15,22 +16,23 @@ function receiveStream(client) {
 	if (Array.isArray(queued)) for (const state of queued) hydrate(client, state);
 	globalThis.RAF_QUERY_SSR = { push: (state) => hydrate(client, state) };
 }
+function hasData(query) {
+	return Query.getUnsafe(query).hasData;
+}
 /**
 * Streams entries that client components loaded during SSR (`useWaterfall`)
 * into the HTML, ahead of the markup that reads them. Entries that arrived
 * through `HydrationBoundary` are skipped: the RSC payload carries them.
-* Data must be JSON-serializable.
+* Data must be JSON-serializable, so only settled entries are sent.
 */
 function useServerStream(client) {
-	const [sent] = useState(() => /* @__PURE__ */ new Set());
 	useServerInsertedHTML(() => {
-		const hydrated = hydratedHashes(client);
-		const queries = client.getAll().filter((query) => query.getState().hasData && !sent.has(query.hash) && !hydrated.has(query.hash)).map((query) => {
-			sent.add(query.hash);
-			return dehydrateQuery(query);
+		const state = dehydrate(client, {
+			filter: hasData,
+			sent: sentHashes(client)
 		});
-		if (queries.length === 0) return null;
-		const json = escapeJson(JSON.stringify({ queries }));
+		if (state.queries.length === 0) return null;
+		const json = escapeJson(JSON.stringify(state));
 		return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: `(self.RAF_QUERY_SSR=self.RAF_QUERY_SSR||[]).push(${json})` } });
 	});
 }

package/dist/provider.d.mts

@@ -1,4 +1,4 @@
-import { QueryClient } from "@raf-query/core";
+import { QueryClient } from "./client.mjs";
 import { ReactNode } from "react";
 //#region src/provider.d.ts
 /**
@@ -7,8 +7,8 @@ import { ReactNode } from "react";
  */
 export declare function QueryClientProvider(props: {
   readonly children?: ReactNode;
-  readonly client: QueryClient;
+  readonly client: QueryClient<unknown>;
 }): import("react").JSX.Element;
 /** The client from the nearest {@link QueryClientProvider}. */
-export declare function useQueryClient(): QueryClient;
+export declare function useQueryClient(): QueryClient<unknown>;
 //#endregion

package/dist/provider.mjs

@@ -2,6 +2,10 @@
 import { createContext, use, useEffect } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/provider.tsx
+/**
+* A hook can't know which services the provider's client has, so its verbs
+* take any factory here.
+*/
 const QueryClientContext = createContext(null);
 /**
 * Provides a client to the tree, and refetches its read, stale queries on

package/dist/rsc.d.mts

@@ -1,4 +1,5 @@
-import { DehydrateOptions, QueryClient } from "@raf-query/core";
+import { QueryClient } from "./client.mjs";
+import { DehydrateOptions } from "@raf-query/core";
 import { ReactNode } from "react";
 //#region src/rsc.d.ts
 /**

package/dist/rsc.mjs

@@ -1,8 +1,8 @@
+import { dehydrate } from "./client.mjs";
+import { sentHashes } from "./sent.mjs";
 import { Hydrate } from "./hydrate.mjs";
-import { canDehydrate, dehydrate, hashKey } from "@raf-query/core";
 import { jsx } from "react/jsx-runtime";
 //#region src/rsc.tsx
-const sentByClient = /* @__PURE__ */ new WeakMap();
 /**
 * Server component: sends the request client's entries to the browser cache.
 * Pending entries cross as promises and stream in as they settle. Entries an
@@ -20,18 +20,10 @@ const sentByClient = /* @__PURE__ */ new WeakMap();
 */
 function HydrationBoundary(props) {
 	const client = props.client;
-	let sent = sentByClient.get(client);
-	if (!sent) {
-		sent = /* @__PURE__ */ new Set();
-		sentByClient.set(client, sent);
-	}
-	const alreadySent = sent;
-	const filter = props.options?.filter ?? canDehydrate;
 	const state = dehydrate(client, {
-		...props.options,
-		filter: (query) => !alreadySent.has(query.hash) && filter(query)
+		sent: sentHashes(client),
+		...props.options
 	});
-	for (const query of state.queries) alreadySent.add(hashKey(query.key));
 	return /* @__PURE__ */ jsx(Hydrate, {
 		state,
 		children: props.children

package/dist/sent.mjs

@@ -0,0 +1,18 @@
+//#region src/sent.ts
+const sentByClient = /* @__PURE__ */ new WeakMap();
+/**
+* Hashes of a client's entries that already have a way to the browser
+* cache: sent by an earlier `HydrationBoundary` of the request, or, in the
+* SSR pass, hydrated from the RSC payload or streamed by `QueryProvider`.
+* Integrations pass it as `sent`, so each entry crosses once.
+*/
+function sentHashes(client) {
+	let sent = sentByClient.get(client);
+	if (!sent) {
+		sent = /* @__PURE__ */ new Set();
+		sentByClient.set(client, sent);
+	}
+	return sent;
+}
+//#endregion
+export { sentHashes };

package/dist/tanstack-router.d.mts

@@ -1,4 +1,5 @@
-import { DehydrateOptions, HydrateOptions, QueryClient } from "@raf-query/core";
+import { QueryClient } from "./client.mjs";
+import { DehydrateOptions, HydrateOptions } from "@raf-query/core";
 import { AnyRouter } from "@tanstack/react-router";
 //#region src/tanstack-router.d.ts
 export interface RouterIntegrationOptions<TRouter extends AnyRouter> {

package/dist/tanstack-router.mjs

@@ -1,13 +1,10 @@
-import { canDehydrate, dehydrateQuery, hydrate } from "@raf-query/core";
-import { Predicate } from "effect";
+import { Effect, Exit, Predicate, Scope, Stream } from "effect";
 import { isRedirect } from "@tanstack/react-router";
 //#region src/tanstack-router.ts
 const noop = () => {};
 function setupServer(options) {
 	const router = options.router;
 	const queryClient = options.queryClient;
-	const dehydrateOptions = options.dehydrateOptions;
-	const shouldSend = dehydrateOptions?.filter ?? canDehydrate;
 	const originalDehydrate = router.options.dehydrate;
 	let finish = noop;
 	let cleanedUp = false;
@@ -26,50 +23,18 @@ function setupServer(options) {
 			queryClient.clear();
 			return;
 		}
-		const sent = /* @__PURE__ */ new Set();
-		const initial = [];
-		for (const query of queryClient.getAll()) if (shouldSend(query)) {
-			initial.push(dehydrateQuery(query, dehydrateOptions));
-			sent.add(query.hash);
-		}
-		let controller;
-		const stream = new ReadableStream({ start(streamController) {
-			controller = streamController;
-		} });
-		let batch;
-		const flush = () => {
-			const queries = batch;
-			batch = void 0;
-			if (!queries || !controller) return;
-			const chunk = [];
-			for (const query of queries.values()) if (!sent.has(query.hash) && shouldSend(query)) {
-				chunk.push(dehydrateQuery(query, dehydrateOptions));
-				sent.add(query.hash);
-			}
-			if (chunk.length > 0) controller.enqueue(chunk);
-		};
-		const unsubscribe = queryClient.subscribe((event) => {
-			if (event.type === "removed" || sent.has(event.query.hash)) return;
-			if (!batch) {
-				batch = /* @__PURE__ */ new Map();
-				queueMicrotask(flush);
-			}
-			batch.set(event.query.hash, event.query);
-		});
+		const scope = Scope.makeUnsafe();
+		const stream = Effect.runSync(queryClient.effect.dehydrateStream(options.dehydrateOptions).pipe(Scope.provide(scope)));
 		finish = () => {
 			finish = noop;
-			flush();
-			unsubscribe();
-			try {
-				controller?.close();
-			} catch {}
+			Effect.runSync(Scope.close(scope, Exit.void));
 		};
 		router.serverSsr?.onRenderFinished(() => finish());
 		return {
 			...dehydrated,
 			raf: {
-				initial,
-				stream
+				initial: stream.initial,
+				stream: Stream.toReadableStream(stream.updates)
 			}
 		};
 	};
@@ -79,28 +44,18 @@ function hasRafQueries(value) {
 }
 function setupClient(options) {
 	const router = options.router;
-	const queryClient = options.queryClient;
+	const cache = options.queryClient.effect;
 	const hydrateOptions = options.hydrateOptions;
 	const originalHydrate = router.options.hydrate;
 	router.options.hydrate = async (dehydrated) => {
 		await originalHydrate?.(dehydrated);
 		if (!hasRafQueries(dehydrated)) return;
-		hydrate(queryClient, { queries: dehydrated.raf.initial }, hydrateOptions);
-		const reader = dehydrated.raf.stream.getReader();
-		(async () => {
-			try {
-				for (;;) {
-					const chunk = await reader.read();
-					if (chunk.done) return;
-					hydrate(queryClient, { queries: chunk.value }, hydrateOptions);
-				}
-			} catch (error) {
-				console.error("raf-query: reading the query stream failed", error);
-				reader.cancel(error).catch(() => {});
-			} finally {
-				reader.releaseLock();
-			}
-		})();
+		const raf = dehydrated.raf;
+		Effect.runSync(cache.hydrate(raf.initial, hydrateOptions));
+		Effect.runFork(cache.hydrateStream(Stream.fromReadableStream({
+			evaluate: () => raf.stream,
+			onError: (error) => error
+		}), hydrateOptions).pipe(Effect.catchCause((cause) => Effect.logError("raf-query: reading the query stream failed", cause))));
 	};
 }
 /**

package/dist/use-query.d.mts

@@ -1,7 +1,8 @@
-import { DataOf, EnsuredQueryHandle, InputOf, IsPaged, QueryClient, QueryFactory, QueryHandle, QueryKey, QueryObserverOptions } from "@raf-query/core";
+import "./client.mjs";
+import { DataOf, EnsuredQueryHandle, InputOf, IsPaged, Query, QueryFactory, QueryHandle, QueryKey, QueryObserver, Thenable } from "@raf-query/core";
 //#region src/use-query.d.ts
 /** `refetchInterval`, `refetchOnWindowFocus`, `refetchOnReconnect`, `whilePending`. */
-export type UseQueryOptions = QueryObserverOptions;
+export type UseQueryOptions = QueryObserver.Options;
 /** The second element of {@link useQuery}'s result. */
 export interface QueryControls<TFactory extends QueryFactory> {
   /** Error of the last failed request. Existing data stays readable. */
@@ -35,7 +36,7 @@ export interface PagingControls {
   readonly isFetchingPreviousPage: boolean;
 }
 export type UseQueryControls<TFactory extends QueryFactory> = IsPaged<TFactory> extends true ? QueryControls<TFactory> & PagingControls : QueryControls<TFactory>;
-export type UseQueryResult<TFactory extends QueryFactory> = readonly [promise: Promise<DataOf<TFactory>>, controls: UseQueryControls<TFactory>];
+export type UseQueryResult<TFactory extends QueryFactory> = readonly [promise: Thenable<DataOf<TFactory>>, controls: UseQueryControls<TFactory>];
 /** {@link useQuery}'s result for a handle from `ensure`. */
 export type UseEnsuredQueryResult<TFactory extends QueryFactory> = readonly [data: DataOf<TFactory>, controls: UseQueryControls<TFactory>];
 /**

package/dist/use-query.mjs

@@ -1,25 +1,52 @@
 "use client";
-import { useQueryClient } from "./provider.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { QueryObserver } from "@raf-query/core";
+import { useQueryClient } from "./provider.mjs";
+import { Query, QueryObserver } from "@raf-query/core";
+import { Effect } from "effect";
 import { use, useEffect, useState, useSyncExternalStore } from "react";
 //#region src/use-query.ts
 function queryFor(client, factory, input) {
 	const args = [input];
 	return client.getQuery(factory, ...args);
 }
+const commands = /* @__PURE__ */ new WeakMap();
+/** One stable Promise function per command Effect, so identities track the query's. */
+function commandFor(effect) {
+	let command = commands.get(effect);
+	if (!command) {
+		command = () => Effect.runPromise(effect);
+		commands.set(effect, command);
+	}
+	return command;
+}
+/** `tracked`, with the observer's command Effects as Promise functions. */
+function withPromiseCommands(tracked) {
+	return unsafeCast(new Proxy(tracked, { get: (target, name, receiver) => {
+		if (name === "fetchNextPage" || name === "fetchPreviousPage" || name === "refetch") return commandFor(target[name]);
+		return Reflect.get(target, name, receiver);
+	} }));
+}
+function storeFor(query, options) {
+	const observer = QueryObserver.makeUnsafe(query, options);
+	return {
+		getSnapshot: () => QueryObserver.getUnsafe(observer),
+		observer,
+		subscribe: (onChange) => QueryObserver.subscribeUnsafe(observer, onChange)
+	};
+}
 function useQuery(factory, handle, options = {}) {
 	const query = queryFor(useQueryClient(), factory, handle.input);
-	query.read();
+	Query.readUnsafe(query);
 	const refetchInterval = options.refetchInterval;
 	const refetchOnReconnect = options.refetchOnReconnect;
 	const refetchOnWindowFocus = options.refetchOnWindowFocus;
 	const whilePending = options.whilePending;
-	const [observer] = useState(() => new QueryObserver(query, options));
-	const result = observer.getOptimisticResult(query, options);
-	useSyncExternalStore(observer.subscribe, observer.getCurrentResult, observer.getCurrentResult);
+	const [store] = useState(() => storeFor(query, options));
+	const observer = store.observer;
+	const result = QueryObserver.getOptimisticResultUnsafe(observer, query, options);
+	useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
 	useEffect(() => {
-		observer.setOptions(query, {
+		QueryObserver.setOptionsUnsafe(observer, query, {
 			refetchInterval,
 			refetchOnReconnect,
 			refetchOnWindowFocus,
@@ -33,8 +60,8 @@ function useQuery(factory, handle, options = {}) {
 		refetchOnWindowFocus,
 		whilePending
 	]);
-	observer.trackProp("promise");
-	const controls = observer.trackResult(result);
+	QueryObserver.trackProp(observer, "promise");
+	const controls = withPromiseCommands(QueryObserver.trackResult(observer, result));
 	if (handle.ensured === true) return unsafeCast([use(result.promise), controls]);
 	return unsafeCast([result.promise, controls]);
 }

package/dist/use-waterfall.mjs

@@ -1,5 +1,6 @@
 "use client";
 import { useQueryClient } from "./provider.mjs";
+import { Query } from "@raf-query/core";
 //#region src/use-waterfall.ts
 /**
 * Start a query during render and return its handle, for inputs only known
@@ -13,7 +14,7 @@ import { useQueryClient } from "./provider.mjs";
 */
 function useWaterfall(factory, ...args) {
 	const query = useQueryClient().getQuery(factory, ...args);
-	query.read();
+	Query.readUnsafe(query);
 	return query.handle;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.0.18",
+  "version": "0.1.0",
   "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.0.18",
+    "@raf-query/core": "0.1.0",
     "effect": "^4.0.1"
   },
   "peerDependencies": {