@raf-query/core 0.9.2 → 0.10.1

package/CHANGELOG.md

@@ -1,10 +1,36 @@
 # Changelog
 
+## [0.10.1](https://github.com/KATT/raf-query/compare/0.10.0...0.10.1) (2026-10-16)
+
+### Features
+
+* **core:** export QueryClient, dehydrate, hydrate, allKeyed and the useQuery controls from @raf-query/core ([#193](https://github.com/KATT/raf-query/issues/193)) ([54492ab](https://github.com/KATT/raf-query/commit/54492abbe2966a0645e8a4c77f9c5ab31d6e3a20)), references [#194](https://github.com/KATT/raf-query/issues/194)
+
+### Documentation
+
+* React Router client-only and server sections with one server client per request, Effect under Integrations, official docs links, and ensure waits like fetch in server-only code ([#192](https://github.com/KATT/raf-query/issues/192)) ([841ffcf](https://github.com/KATT/raf-query/commit/841ffcf4d0fa0a40dfc58dc65bfcfadca8948874)), references [#190](https://github.com/KATT/raf-query/issues/190)
+
+## [0.10.0](https://github.com/KATT/raf-query/compare/0.9.2...0.10.0) (2026-10-16)
+
+### ⚠ BREAKING CHANGES
+
+- **react:** import HydrationBoundary from @raf-query/react in RSC and React Router ([#175](https://github.com/KATT/raf-query/issues/175))
+- **react:** import QueryProvider from @raf-query/react ([#177](https://github.com/KATT/raf-query/issues/177))
+
+### Features
+
+- **react:** import HydrationBoundary from @raf-query/react in RSC and React Router ([#175](https://github.com/KATT/raf-query/issues/175)) ([244705c](https://github.com/KATT/raf-query/commit/244705c74841d280a596195dec5cf5e5d5617fe5))
+- **react:** import QueryProvider from @raf-query/react ([#177](https://github.com/KATT/raf-query/issues/177)) ([fb4fceb](https://github.com/KATT/raf-query/commit/fb4fcebb404906b4a9d5716a1d45cb33c82da2fb)), references [#175](https://github.com/KATT/raf-query/issues/175) [#175](https://github.com/KATT/raf-query/issues/175) [#175](https://github.com/KATT/raf-query/issues/175) [#175](https://github.com/KATT/raf-query/issues/175)
+
+### Code Refactoring
+
+- **react:** group the HydrationBoundary and QueryProvider files in folders ([#186](https://github.com/KATT/raf-query/issues/186)) ([ad07bb4](https://github.com/KATT/raf-query/commit/ad07bb45ca77fc797cd6b8432685e58f43907258)), references [#175](https://github.com/KATT/raf-query/issues/175)
+
 ## [0.9.2](https://github.com/KATT/raf-query/compare/0.9.1...0.9.2) (2026-10-15)
 
 ### Bug Fixes
 
-* **core:** keep handles of factories with the same signature apart ([#167](https://github.com/KATT/raf-query/issues/167)) ([5894bcb](https://github.com/KATT/raf-query/commit/5894bcbcc382c60e9c04768c0e178bf0996f4b45))
+- **core:** keep handles of factories with the same signature apart ([#167](https://github.com/KATT/raf-query/issues/167)) ([5894bcb](https://github.com/KATT/raf-query/commit/5894bcbcc382c60e9c04768c0e178bf0996f4b45))
 
 ## [0.9.1](https://github.com/KATT/raf-query/compare/0.9.0...0.9.1) (2026-10-15)
 

package/README.md

@@ -1,6 +1,6 @@
 # @raf-query/core
 
-The framework-agnostic cache behind [raf-query](https://raf-query.katt.dev), written in and for [Effect](https://effect.website): every verb is an Effect with typed errors and services, and entries can be watched as Streams.
+The framework-agnostic cache behind [raf-query](https://raf-query.katt.dev), written in and for [Effect](https://effect.website): every verb is an Effect with typed errors and services, and entries can be watched as Streams. It also holds `QueryClient`, the same cache with Promise methods, which the framework bindings re-export.
 
 **[Documentation](https://raf-query.katt.dev/docs/effect)** · [API reference](https://raf-query.katt.dev/docs/api-reference#raf-querycore) · [GitHub](https://github.com/KATT/raf-query)
 

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/cache.d.mts

@@ -1,7 +1,7 @@
 import { QueryKey } from "./key.mjs";
 import { DataOf, ErrorOf, InputArgs, InputOf, LoadOptions, PagedQueryFactory, QueryBehavior, QueryFactory, QueryHandle, QueryHandleWithData, ServicesOf } from "./options.mjs";
-import { DehydrateOptions, DehydratedState, DehydratedStream, HydrateOptions } from "./hydration.mjs";
 import { CancelledError, Query, State, query_d_exports } from "./query.mjs";
+import { DehydrateOptions, DehydratedState, DehydratedStream, HydrateOptions } from "./hydration.mjs";
 import { Context, Effect, Layer, Option, Scope, Stream } from "effect";
 declare namespace cache_d_exports {
   export { Config, Event, Filter, QueryCache, Target, TypeId, Updater, isQueryCache, layer, make };

package/dist/cache.mjs

@@ -1,7 +1,7 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
-import { Platform } from "./platform.mjs";
 import { hashKey, matchesKey } from "./key.mjs";
 import { listen } from "./listen.mjs";
+import { Platform } from "./platform.mjs";
 import { changes, emit, fetch, invalidate, isObserved, make as make$1, needsRefetch, onPlatformEvent, provide, remove, reset, revalidate, setData, setOptions, start } from "./entry.mjs";
 import { dehydrateEntries, dehydrateStream, hydrateEntries } from "./hydration.mjs";
 import { optionsFor } from "./options.mjs";

package/dist/client.d.mts

@@ -0,0 +1,127 @@
+import { DataOf, InputArgs, InputOf, LoadOptions, PagedQueryFactory, QueryFactory, QueryHandle, QueryHandleWithData } from "./options.mjs";
+import { Query, query_d_exports } from "./query.mjs";
+import { DehydrateOptions, DehydratedState, HydrateOptions } from "./hydration.mjs";
+import { Config, Event, Filter, QueryCache, Target, Updater, cache_d_exports } from "./cache.mjs";
+import { Effect, Layer } from "effect";
+//#region src/client.d.ts
+export interface QueryClientConfig<TServices = never> extends 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): void;
+  /**
+   * When `false`, `useQuery` for an Effect `queryFn` (a typed `ErrorOf`)
+   * returns a `Result` in the first tuple slot instead of a promise that
+   * rejects. Defaults to `false` when `layer` is set, `true` otherwise.
+   * Promise `queryFn`s always throw; this flag does not apply to them.
+   */
+  readonly throwOnError?: boolean;
+}
+/**
+ * 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;
+  readonly isServer: boolean;
+  /**
+   * Default for Effect `useQuery` reads. See
+   * {@link QueryClientConfig.throwOnError}.
+   */
+  readonly throwOnError: 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<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>;
+  /**
+   * {@link fetch} without waiting on stale data: start a query and wait for
+   * it on a cache miss. Stale cached data resolves immediately and
+   * revalidates in the browser. Rejects if that request fails.
+   */
+  ensure<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<QueryHandleWithData<TFactory>>;
+  /** {@link ensure}, loading `options.pages` pages of a paged query. */
+  ensure<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<QueryHandleWithData<TFactory>>;
+  /**
+   * Start a query and resolve to a handle holding its data. Waits on a cache
+   * miss and on stale data (on the server, only invalidated data), so the
+   * data is fresh. Rejects if that request fails.
+   */
+  fetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<QueryHandleWithData<TFactory>>;
+  /** {@link fetch}, loading `options.pages` pages of a paged query. */
+  fetch<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<QueryHandleWithData<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 QueryCache.Filter}.
+   */
+  invalidate<TFactory extends QueryFactory<TServices>>(...target: 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: 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: 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: 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>;
+  /**
+   * How many entries have a request in flight: all of them, or those
+   * matching `filter`. For global loading indicators.
+   */
+  isFetching(filter?: Filter): number;
+  /** Listen to entries being added, updated, and removed. */
+  subscribe(listener: (event: 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;
+  /**
+   * Run an Effect with the cache (`QueryCache`) and the services of
+   * `config.layer`, as `Effect.runPromise` does: it rejects with the
+   * Effect's failure, or its defect. For an app's loaders and actions.
+   */
+  runPromise<A, E>(effect: Effect.Effect<A, E, QueryCache | TServices>): Promise<A>;
+  /**
+   * 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,176 @@
+import { QueryCache, layer } from "./cache.mjs";
+import { Context, Effect, Exit, Layer, Option, Predicate, 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 effect;
+}
+/**
+* Run a verb that waits on a request. A cancelled request rejects with an
+* `AbortError`, as an aborted `fetch` does, not with the Effect API's
+* `Query.CancelledError`.
+*/
+function runLoad(effect) {
+	return Effect.runPromise(effect).catch((error) => {
+		throw Predicate.isTagged(error, "CancelledError") ? new DOMException("The query was cancelled", "AbortError") : error;
+	});
+}
+/** `ensure` / `fetch` arguments, forwarded to the cache's same verb. */
+function loadArgs(input, options) {
+	return [input, options];
+}
+/**
+* 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;
+	/**
+	* Default for Effect `useQuery` reads. See
+	* {@link QueryClientConfig.throwOnError}.
+	*/
+	throwOnError;
+	/**
+	* The cache and the layer's services. Typed `never` so clients of any
+	* `TServices` stay assignable to each other; `runPromise` restores it.
+	*/
+	#context;
+	/**
+	* Owns the cache's fibers, mounts and the layer's services; lives until
+	* `dispose()`.
+	*/
+	#scope = Scope.makeUnsafe();
+	constructor(config = {}) {
+		const cache = layer(config);
+		const services = Effect.runSync(Layer.buildWithScope(config.layer ? Layer.provideMerge(cache, config.layer) : cache, this.#scope));
+		this.#context = services;
+		this.effect = Context.get(services, QueryCache);
+		this.isServer = this.effect.isServer;
+		this.throwOnError = config.throwOnError ?? config.layer === void 0;
+		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)));
+	}
+	ensure(factory, input, options) {
+		return runLoad(provided(this.effect.ensure(factory, ...loadArgs(input, options))));
+	}
+	fetch(factory, input, options) {
+		return runLoad(provided(this.effect.fetch(factory, ...loadArgs(input, options))));
+	}
+	/**
+	* 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 QueryCache.Filter}.
+	*/
+	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);
+	}
+	/**
+	* How many entries have a request in flight: all of them, or those
+	* matching `filter`. For global loading indicators.
+	*/
+	isFetching(filter) {
+		return this.effect.isFetchingUnsafe(filter);
+	}
+	/** 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));
+		};
+	}
+	/**
+	* Run an Effect with the cache (`QueryCache`) and the services of
+	* `config.layer`, as `Effect.runPromise` does: it rejects with the
+	* Effect's failure, or its defect. For an app's loaders and actions.
+	*/
+	runPromise(effect) {
+		return Effect.runPromiseWith(this.#context)(effect);
+	}
+	/**
+	* 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/controls.d.mts

@@ -0,0 +1,85 @@
+import { QueryKey } from "./key.mjs";
+import { DataOf, ErrorOf, InputOf, IsPaged, QueryFactory } from "./options.mjs";
+import { Thenable } from "./thenable.mjs";
+import { Options, Result as Result$1, observer_d_exports } from "./observer.mjs";
+import { Result } from "effect";
+//#region src/controls.d.ts
+/** `refetchInterval`, `refetchOnWindowFocus`, `refetchOnReconnect`, `whilePending`. */
+export type UseQueryOptions = Options;
+/**
+ * `throwOnError` only when {@link ErrorOf} is typed (Effect `queryFn`).
+ * Promise factories always throw; the option is not part of their options.
+ */
+export type UseQueryThrowOptions<TFactory extends QueryFactory> = HasTypedError<TFactory> extends true ? {
+  /**
+   * When `false`, the data is a `Result` instead of a rejecting
+   * promise. Omit to use the client's default (`false` with a
+   * `layer`, `true` without).
+   */
+  readonly throwOnError?: boolean;
+} : {
+  readonly throwOnError?: never;
+};
+/** What `useQuery` returns next to the data. */
+export interface QueryControls<TFactory extends QueryFactory> {
+  /** Error of the last failed request. Existing data stays readable. */
+  readonly error: unknown;
+  /** Stable string form of the handle's key, for `key` props. */
+  readonly hash: string;
+  /** Input of the data in the promise; differs from the handle's while `isPrevious`. */
+  readonly input: InputOf<TFactory>;
+  /** A request is in flight: first load, new input, or background refetch. */
+  readonly isFetching: boolean;
+  /** No data yet for the handle's input. */
+  readonly isPending: boolean;
+  /** The promise holds a previous input's data (`whilePending: "previous"`). */
+  readonly isPrevious: boolean;
+  /** The data is older than `staleTime`, or was invalidated. */
+  readonly isStale: boolean;
+  /** Key of the data in the promise; differs from the handle's while `isPrevious`. */
+  readonly key: QueryKey;
+  /** Refetch now. Resolves when the request settles; never rejects. */
+  refetch(): Promise<void>;
+  /** When the data in the promise was fetched (ms since epoch); `0` before that. */
+  readonly updatedAt: number;
+}
+/** Extra controls for factories that return `infiniteQueryOptions(...)`. */
+export interface PagingControls {
+  fetchNextPage(): Promise<void>;
+  fetchPreviousPage(): Promise<void>;
+  readonly hasNextPage: boolean;
+  readonly hasPreviousPage: boolean;
+  readonly isFetchingNextPage: boolean;
+  readonly isFetchingPreviousPage: boolean;
+}
+export type UseQueryControls<TFactory extends QueryFactory> = IsPaged<TFactory> extends true ? QueryControls<TFactory> & PagingControls : QueryControls<TFactory>;
+/**
+ * `true` when the factory's error channel is typed (Effect `queryFn`), not
+ * `unknown` (promise / plain value).
+ */
+export type HasTypedError<TFactory extends QueryFactory> = unknown extends ErrorOf<TFactory> ? false : true;
+/**
+ * Whether this read throws on failure. Untyped errors always throw. Typed
+ * errors follow `options.throwOnError`, else the client's default (`false`
+ * with a `layer`, `true` without). Types treat an omitted flag as `false`
+ * (Result), matching a client with a `layer`.
+ */
+export type ThrowsOnError<TFactory extends QueryFactory, TThrow extends boolean | undefined> = HasTypedError<TFactory> extends false ? true : TThrow extends boolean ? TThrow : false;
+/** What a read settles with: the data, or a `Result` when it doesn't throw. */
+export type ReadValue<TFactory extends QueryFactory, TThrow extends boolean | undefined = undefined> = ThrowsOnError<TFactory, TThrow> extends true ? DataOf<TFactory> : Result.Result<DataOf<TFactory>, ErrorOf<TFactory>>;
+type Command = "fetchNextPage" | "fetchPreviousPage" | "refetch";
+/** An observer result whose command Effects are Promise functions. */
+export type PromiseControls = Omit<Result$1, Command> & Record<Command, () => Promise<void>>;
+/**
+ * `result`, with the observer's command Effects as Promise functions. Reads
+ * of every other property go through to `result`, so a tracked result
+ * (`QueryObserver.trackResult`) stays tracked. For bindings.
+ */
+export declare function promiseControls(result: Result$1): PromiseControls;
+/**
+ * A thenable that fulfills with a `Result` when `promise` settles, for reads
+ * that don't throw (`throwOnError: false`). Settled already when `promise`
+ * is, and the same thenable for the same `promise`. For bindings.
+ */
+export declare function resultThenable<A, E>(promise: Thenable<A>): Thenable<Result.Result<A, E>>;
+//#endregion

package/dist/controls.mjs

@@ -0,0 +1,59 @@
+import { fulfilled, pending } from "./thenable.mjs";
+import { Effect, Result } from "effect";
+//#region src/controls.ts
+/**
+* What a framework binding's `useQuery` returns next to the data: the
+* observer's result with Promise commands, and the types every binding
+* shares. The React, Svelte and Vue packages build their reads on this.
+*/
+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;
+}
+/**
+* `result`, with the observer's command Effects as Promise functions. Reads
+* of every other property go through to `result`, so a tracked result
+* (`QueryObserver.trackResult`) stays tracked. For bindings.
+*/
+function promiseControls(result) {
+	return new Proxy(result, { get: (target, name, receiver) => {
+		if (name === "fetchNextPage" || name === "fetchPreviousPage" || name === "refetch") return commandFor(target[name]);
+		return Reflect.get(target, name, receiver);
+	} });
+}
+/**
+* One `Result` thenable per data thenable, so readers see a stable identity
+* across re-renders the same way they do for the data promise.
+*/
+const resultThenables = /* @__PURE__ */ new WeakMap();
+/**
+* A thenable that fulfills with a `Result` when `promise` settles, for reads
+* that don't throw (`throwOnError: false`). Settled already when `promise`
+* is, and the same thenable for the same `promise`. For bindings.
+*/
+function resultThenable(promise) {
+	const cached = resultThenables.get(promise);
+	if (cached) return cached;
+	let next;
+	if (promise.status === "fulfilled") next = fulfilled(Result.succeed(promise.value));
+	else if (promise.status === "rejected") next = fulfilled(Result.fail(promise.reason));
+	else {
+		const deferred = pending();
+		promise.then((value) => {
+			deferred.resolve(Result.succeed(value));
+		}, (error) => {
+			deferred.resolve(Result.fail(error));
+		});
+		next = deferred.promise;
+	}
+	resultThenables.set(promise, next);
+	return next;
+}
+//#endregion
+export { promiseControls, resultThenable };

package/dist/entry.d.mts

@@ -1,9 +1,9 @@
-import { Platform, PlatformEvent } from "./platform.mjs";
 import { QueryKey } from "./key.mjs";
 import { AnyQueryOptions, QueryBehavior, QueryFactory, QueryHandle, QueryMeta } from "./options.mjs";
-import { Event } from "./cache.mjs";
+import { Platform, PlatformEvent } from "./platform.mjs";
 import { Pending, Thenable } from "./thenable.mjs";
 import { FetchRequest, Query, State, SubscribeOptions } from "./query.mjs";
+import { Event } from "./cache.mjs";
 import { Cause, Clock, Context, Deferred, Effect, Scope, Stream } from "effect";
 declare namespace entry_d_exports {
   export { BrowserOnlyError, CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isBrowserOnly, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };

package/dist/entry.mjs

@@ -1,8 +1,8 @@
-import { whenOnline } from "./platform.mjs";
 import { replaceEqualDeep } from "./share.mjs";
 import { fetchPages, isInfiniteData, nextPageParam, previousPageParam } from "./infinite.mjs";
 import { listen } from "./listen.mjs";
 import { scheduleNotify } from "./notify.mjs";
+import { whenOnline } from "./platform.mjs";
 import { fromQueryFn, requestServices, runRequest } from "./request.mjs";
 import { retrySchedule } from "./retry.mjs";
 import { fulfilled, pending } from "./thenable.mjs";

package/dist/hydration.d.mts

@@ -1,8 +1,8 @@
 import { QueryKey } from "./key.mjs";
 import { QueryFactory, QueryMeta } from "./options.mjs";
-import "./cache.mjs";
-import "./entry.mjs";
 import { Query, query_d_exports } from "./query.mjs";
+import "./entry.mjs";
+import "./cache.mjs";
 import { Cause, Effect, Scope, Stream } from "effect";
 //#region src/hydration.d.ts
 /** What a dehydrated pending query's promise resolves to. */

package/dist/index.d.mts

@@ -1,9 +1,12 @@
-import { platform_d_exports } from "./platform.mjs";
+import { Settled, allKeyed } from "./all-keyed.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
 import { AnyQueryOptions, DataOf, ErrorOf, InfiniteData, InfiniteQueryOptions, InfiniteQueryTypes, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, PagedQueryFactory, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryHandleWithData, QueryMeta, QueryOptions, QueryTypes, Register, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
-import { DehydrateOptions, DehydratedQuery, DehydratedResult, DehydratedState, DehydratedStream, HydrateOptions, RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
-import { cache_d_exports } from "./cache.mjs";
+import { platform_d_exports } from "./platform.mjs";
 import { Pending, Thenable, fulfilled, pending } from "./thenable.mjs";
 import { query_d_exports } from "./query.mjs";
+import { DehydrateOptions, DehydratedQuery, DehydratedResult, DehydratedState, DehydratedStream, HydrateOptions, RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
+import { cache_d_exports } from "./cache.mjs";
+import { QueryClient, QueryClientConfig, dehydrate, hydrate } from "./client.mjs";
 import { observer_d_exports } from "./observer.mjs";
-export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type ErrorOf, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InfiniteQueryTypes, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, type PagedQueryFactory, type Pending, platform_d_exports as Platform, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryHandleWithData, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, type QueryTypes, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Thenable, canDehydrate, dehydrateQuery, fulfilled, hashKey, infiniteQueryOptions, matchesKey, pending, queryOptions };
+import { HasTypedError, PagingControls, PromiseControls, QueryControls, ReadValue, ThrowsOnError, UseQueryControls, UseQueryOptions, UseQueryThrowOptions, promiseControls, resultThenable } from "./controls.mjs";
+export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type ErrorOf, type HasTypedError, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InfiniteQueryTypes, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, type PagedQueryFactory, type PagingControls, type Pending, platform_d_exports as Platform, type PromiseControls, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, QueryClient, type QueryClientConfig, type QueryControls, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryHandleWithData, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, type QueryTypes, type ReadValue, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Settled, type Thenable, type ThrowsOnError, type UseQueryControls, type UseQueryOptions, type UseQueryThrowOptions, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable };

package/dist/index.mjs

@@ -1,9 +1,12 @@
-import { platform_exports } from "./platform.mjs";
+import { allKeyed } from "./all-keyed.mjs";
 import { hashKey, matchesKey } from "./key.mjs";
+import { platform_exports } from "./platform.mjs";
 import { fulfilled, pending } from "./thenable.mjs";
 import { query_exports } from "./query.mjs";
 import { RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
 import { infiniteQueryOptions, queryOptions } from "./options.mjs";
 import { cache_exports } from "./cache.mjs";
+import { QueryClient, dehydrate, hydrate } from "./client.mjs";
+import { promiseControls, resultThenable } from "./controls.mjs";
 import { observer_exports } from "./observer.mjs";
-export { platform_exports as Platform, query_exports as Query, cache_exports as QueryCache, observer_exports as QueryObserver, RedactedError, canDehydrate, dehydrateQuery, fulfilled, hashKey, infiniteQueryOptions, matchesKey, pending, queryOptions };
+export { platform_exports as Platform, query_exports as Query, cache_exports as QueryCache, QueryClient, observer_exports as QueryObserver, RedactedError, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable };

package/dist/observer.d.mts

@@ -4,7 +4,7 @@ import { Thenable } from "./thenable.mjs";
 import { Query, query_d_exports } from "./query.mjs";
 import { Effect, Pipeable, Stream } from "effect";
 declare namespace observer_d_exports {
-  export { Options, QueryObserver, Result, ResultKey, TypeId, changes, get, getOptimisticResultUnsafe, getUnsafe, isQueryObserver, make, makeUnsafe, setOptionsUnsafe, subscribeUnsafe, trackProp, trackResult };
+  export { Options, QueryObserver, Result$1 as Result, ResultKey, TypeId, changes, get, getOptimisticResultUnsafe, getUnsafe, isQueryObserver, make, makeUnsafe, setOptionsUnsafe, subscribeUnsafe, trackProp, trackResult };
 }
 export declare const TypeId = "~@raf-query/core/QueryObserver";
 export type TypeId = typeof TypeId;
@@ -24,7 +24,7 @@ export interface Options {
   readonly whilePending?: "previous" | "suspend";
 }
 /** What a reader sees of its query. Replaced, never mutated, on every change. */
-export interface Result<TData = unknown> {
+interface Result$1<TData = unknown> {
   /** Error of the last failed request. Existing data stays readable. */
   readonly error: unknown;
   /** The query's `fetchNextPage`. */
@@ -56,7 +56,7 @@ export interface Result<TData = unknown> {
   /** When the data in `promise` was fetched (ms since epoch); `0` before that. */
   readonly updatedAt: number;
 }
-export type ResultKey = keyof Result;
+export type ResultKey = keyof Result$1;
 /** An observer of a factory's queries; its results hold the factory's {@link DataOf}. */
 export interface QueryObserver<TFactory extends QueryFactory = QueryFactory> extends Pipeable.Pipeable {
   /** The options set by the latest `make` or {@link setOptionsUnsafe}. */
@@ -73,14 +73,14 @@ export declare function makeUnsafe<TFactory extends QueryFactory>(query: Query<T
 /** {@link makeUnsafe}, as an Effect. */
 export declare function make<TFactory extends QueryFactory>(query: Query<TFactory>, options?: Options): Effect.Effect<QueryObserver<TFactory>>;
 /** The current result. */
-export declare function getUnsafe<TFactory extends QueryFactory>(self: QueryObserver<TFactory>): Result<DataOf<TFactory>>;
+export declare function getUnsafe<TFactory extends QueryFactory>(self: QueryObserver<TFactory>): Result$1<DataOf<TFactory>>;
 /** {@link getUnsafe}, as an Effect. */
-export declare function get<TFactory extends QueryFactory>(self: QueryObserver<TFactory>): Effect.Effect<Result<DataOf<TFactory>>>;
+export declare function get<TFactory extends QueryFactory>(self: QueryObserver<TFactory>): Effect.Effect<Result$1<DataOf<TFactory>>>;
 /**
  * The result for `query` with `options` right now, without switching to
  * them. Bindings call this during render, before `setOptionsUnsafe` commits.
  */
-export declare function getOptimisticResultUnsafe<TFactory extends QueryFactory>(self: QueryObserver<TFactory>, query: Query<TFactory>, options: Options): Result<DataOf<TFactory>>;
+export declare function getOptimisticResultUnsafe<TFactory extends QueryFactory>(self: QueryObserver<TFactory>, query: Query<TFactory>, options: Options): Result$1<DataOf<TFactory>>;
 /** Observe `query` with `options` from now on. */
 export declare function setOptionsUnsafe<TFactory extends QueryFactory>(self: QueryObserver<TFactory>, query: Query<TFactory>, options: Options): void;
 /** Listen for result changes. The first listener subscribes to the query. */
@@ -89,14 +89,14 @@ export declare function subscribeUnsafe<TFactory extends QueryFactory>(self: Que
  * The current result, then every change listeners are notified of. Counts
  * as a listener while the stream runs, so the query counts as read.
  */
-export declare function changes<TFactory extends QueryFactory>(self: QueryObserver<TFactory>): Stream.Stream<Result<DataOf<TFactory>>>;
+export declare function changes<TFactory extends QueryFactory>(self: QueryObserver<TFactory>): Stream.Stream<Result$1<DataOf<TFactory>>>;
 /**
  * Wrap `result` so that reading a property marks it tracked. Once any
  * property is tracked, listeners are only notified when a tracked one
  * changes.
  */
-export declare function trackResult<TFactory extends QueryFactory, TResult extends Result<DataOf<TFactory>>>(self: QueryObserver<TFactory>, result: TResult): TResult;
+export declare function trackResult<TFactory extends QueryFactory, TResult extends Result$1<DataOf<TFactory>>>(self: QueryObserver<TFactory>, result: TResult): TResult;
 /** Mark `name` as read, for bindings that track access themselves. */
 export declare function trackProp<TFactory extends QueryFactory>(self: QueryObserver<TFactory>, name: ResultKey): void;
 //#endregion
-export { observer_d_exports };
+export { Result$1 as Result, observer_d_exports };

package/dist/observer.mjs

@@ -1,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
-import { Platform } from "./platform.mjs";
 import { listen } from "./listen.mjs";
+import { Platform } from "./platform.mjs";
 import { entryOf } from "./entry.mjs";
 import { fetchNextPage, fetchPreviousPage, getUnsafe as getUnsafe$1, hasNextPageUnsafe, hasPreviousPageUnsafe, refetch, subscribeUnsafe as subscribeUnsafe$1 } from "./query.mjs";
 import { Effect, Exit, FiberHandle, Pipeable, Predicate, Scope } from "effect";

package/dist/query.d.mts

@@ -1,8 +1,8 @@
 import { QueryKey } from "./key.mjs";
 import { AnyQueryOptions, DataOf, ErrorOf, QueryFactory, QueryHandle, QueryMeta, ServicesOf } from "./options.mjs";
+import { Direction } from "./infinite.mjs";
 import { Thenable } from "./thenable.mjs";
 import { BrowserOnlyError as BrowserOnlyError$1, CancelledError as CancelledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.mjs";
-import { Direction } from "./infinite.mjs";
 import { Effect, Pipeable, Stream } from "effect";
 declare namespace query_d_exports {
   export { BrowserOnlyError, CancelledError, FetchRequest, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, revalidateUnsafe, subscribeUnsafe };

package/package.json

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