@raf-query/core 0.7.12 → 0.9.0

package/CHANGELOG.md

@@ -1,15 +1,44 @@
 # Changelog
 
+## [0.9.0](https://github.com/KATT/raf-query/compare/0.8.0...0.9.0) (2026-10-15)
+
+### ⚠ BREAKING CHANGES
+
+* useQuery returns the data for a handle from ensure or fetch ([#144](https://github.com/KATT/raf-query/issues/144))
+
+### Features
+
+* useQuery returns the data for a handle from ensure or fetch ([#144](https://github.com/KATT/raf-query/issues/144)) ([1845244](https://github.com/KATT/raf-query/commit/18452443ba61c205a53c4f71d60ec99a9b8620a7)), references [#142](https://github.com/KATT/raf-query/issues/142)
+
+### Documentation
+
+* call the early API a note about minor releases ([#143](https://github.com/KATT/raf-query/issues/143)) ([2d79eed](https://github.com/KATT/raf-query/commit/2d79eed7b107b6d16898ebb203a9bdfcfb3856c4))
+* show prefetch and ensure, and make list queries infinite ([#140](https://github.com/KATT/raf-query/issues/140)) ([25cfaa0](https://github.com/KATT/raf-query/commit/25cfaa08f9f192af7efded1269f4ae8a9e5f1026))
+
+## [0.8.0](https://github.com/KATT/raf-query/compare/0.7.12...0.8.0) (2026-10-15)
+
+### ⚠ BREAKING CHANGES
+
+- ensure and fetch return a QueryHandleWithData ([#142](https://github.com/KATT/raf-query/issues/142))
+
+### Features
+
+- ensure and fetch return a QueryHandleWithData ([#142](https://github.com/KATT/raf-query/issues/142)) ([504cd2a](https://github.com/KATT/raf-query/commit/504cd2a19e04b614eb648f02b256128c4eb31d38))
+
+### Miscellaneous Chores
+
+- group experiments under `.experimental/<topic>/` ([#137](https://github.com/KATT/raf-query/issues/137)) ([52ce752](https://github.com/KATT/raf-query/commit/52ce7522223346e82687338d6ac6d34f793b6fcf))
+
 ## [0.7.12](https://github.com/KATT/raf-query/compare/0.7.11...0.7.12) (2026-10-15)
 
-* add knip with every issue type as an error ([#129](https://github.com/KATT/raf-query/issues/129)) ([603719d](https://github.com/KATT/raf-query/commit/603719dcb834312d4a813ecae865df7d56faf8c5))
-* cache Next.js Turbopack builds ([#128](https://github.com/KATT/raf-query/issues/128)) ([667b38f](https://github.com/KATT/raf-query/commit/667b38ff5728dad3fdad6d90445aea480cfbd063))
-* explain how a route loads its data on the homepage ([#121](https://github.com/KATT/raf-query/issues/121)) ([ec1d6ef](https://github.com/KATT/raf-query/commit/ec1d6efdad75ea2d05dd56790e5e980756afea13))
-* frame the cache as async data, not server-state-only ([#126](https://github.com/KATT/raf-query/issues/126)) ([db9ba02](https://github.com/KATT/raf-query/commit/db9ba02995aa01cadacb2739fd258de3c920d440))
+- add knip with every issue type as an error ([#129](https://github.com/KATT/raf-query/issues/129)) ([603719d](https://github.com/KATT/raf-query/commit/603719dcb834312d4a813ecae865df7d56faf8c5))
+- cache Next.js Turbopack builds ([#128](https://github.com/KATT/raf-query/issues/128)) ([667b38f](https://github.com/KATT/raf-query/commit/667b38ff5728dad3fdad6d90445aea480cfbd063))
+- explain how a route loads its data on the homepage ([#121](https://github.com/KATT/raf-query/issues/121)) ([ec1d6ef](https://github.com/KATT/raf-query/commit/ec1d6efdad75ea2d05dd56790e5e980756afea13))
+- frame the cache as async data, not server-state-only ([#126](https://github.com/KATT/raf-query/issues/126)) ([db9ba02](https://github.com/KATT/raf-query/commit/db9ba02995aa01cadacb2739fd258de3c920d440))
 
 ### Features
 
-* **examples:** reinstall shadcn on Base UI without Radix ([#125](https://github.com/KATT/raf-query/issues/125)) ([7c13ef3](https://github.com/KATT/raf-query/commit/7c13ef379dc297edbbe160516b26916d465a48d1))
+- **examples:** reinstall shadcn on Base UI without Radix ([#125](https://github.com/KATT/raf-query/issues/125)) ([7c13ef3](https://github.com/KATT/raf-query/commit/7c13ef379dc297edbbe160516b26916d465a48d1))
 
 ## [0.7.11](https://github.com/KATT/raf-query/compare/0.7.10...0.7.11) (2026-10-14)
 

package/README.md

@@ -4,8 +4,8 @@ The framework-agnostic cache behind [raf-query](https://raf-query.katt.dev), wri
 
 **[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)
 
-> [!WARNING]
-> raf-query is early. The API can still change between patch releases, and you use it at your own risk.
+> [!NOTE]
+> raf-query is early. The API can still change between minor releases, and you use it at your own risk.
 
 React apps install [`@raf-query/react`](https://www.npmjs.com/package/@raf-query/react) instead: it re-exports this package, so you never import core directly. Install core on its own for Effect programs and for bindings to other frameworks.
 
@@ -31,7 +31,7 @@ export function issueQuery(input: { id: number }) {
 
 const program = Effect.gen(function* () {
 	const cache = yield* QueryCache.QueryCache;
-	const issue = yield* cache.fetch(issueQuery, { id: 1 }); // fails with IssueNotFound
+	yield* cache.fetch(issueQuery, { id: 1 }); // fails with IssueNotFound
 	yield* cache.watch(issueQuery, { id: 1 }).pipe(
 		Stream.map((state) => state.data?.title),
 		Stream.runForEach((title) => Effect.log(title)),

package/dist/cache.d.mts

@@ -1,5 +1,5 @@
 import { QueryKey } from "./key.mjs";
-import { DataOf, EnsuredQueryHandle, ErrorOf, InputArgs, InputOf, LoadOptions, PagedQueryFactory, QueryBehavior, QueryFactory, QueryHandle, ServicesOf } from "./options.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 { Context, Effect, Layer, Option, Scope, Stream } from "effect";
@@ -53,8 +53,7 @@ export type Target<TFactory extends QueryFactory> = [factory: TFactory, ...args:
  * both with no data and with `undefined` data.
  */
 export type Updater<TData> = TData | ((previous: TData | undefined) => TData);
-type Ensured<TFactory extends QueryFactory> = Effect.Effect<EnsuredQueryHandle<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
-type Fetched<TFactory extends QueryFactory> = Effect.Effect<DataOf<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
+type Loaded<TFactory extends QueryFactory> = Effect.Effect<QueryHandleWithData<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
 export interface QueryCache {
   /** Every entry. */
   readonly all: Effect.Effect<ReadonlyArray<Query>>;
@@ -70,24 +69,23 @@ export interface QueryCache {
    */
   dehydrateStream(options?: DehydrateOptions): Effect.Effect<DehydratedStream, never, Scope.Scope>;
   /**
-   * Start a query and wait for it on a cache miss. Fails if that request
-   * fails. Stale cached data succeeds immediately and revalidates in the
-   * browser. The handle is marked `ensured`, so `useQuery` returns its data
-   * directly.
+   * {@link fetch} without waiting on stale data: start a query and wait for
+   * it on a cache miss. Stale cached data succeeds immediately and
+   * revalidates in the browser. Fails if that request fails.
    */
-  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Ensured<TFactory>;
+  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Loaded<TFactory>;
   /** {@link ensure}, loading `options.pages` pages of a paged query. */
-  ensure<TFactory extends PagedQueryFactory>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Ensured<TFactory>;
+  ensure<TFactory extends PagedQueryFactory>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Loaded<TFactory>;
   /** Cache events from the moment the stream starts. */
   readonly events: Stream.Stream<Event>;
   /**
-   * Start a query and succeed with its data. Waits on a cache miss and on
-   * stale data (on the server, only invalidated data), so the data is fresh.
-   * Fails if that request fails.
+   * Start a query and succeed with 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. Fails if that request fails.
    */
-  fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Fetched<TFactory>;
+  fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Loaded<TFactory>;
   /** {@link fetch}, loading `options.pages` pages of a paged query. */
-  fetch<TFactory extends PagedQueryFactory>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Fetched<TFactory>;
+  fetch<TFactory extends PagedQueryFactory>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Loaded<TFactory>;
   /**
    * Cached data for a factory call. `Some(undefined)` when the data itself
    * is `undefined`.

package/dist/cache.mjs

@@ -63,6 +63,14 @@ function load(entry, pages, fresh) {
 	revalidate(entry);
 	return Effect.succeed(dataOf(entry));
 }
+/** The entry's handle as of this call, with the data `loaded` succeeds with. */
+function withData(entry, loaded) {
+	const handle = handleOf(entry);
+	return Effect.map(loaded, (data) => ({
+		...handle,
+		data
+	}));
+}
 /** Settles every effect, started together. */
 function settleAll(effects) {
 	return Effect.all(effects, {
@@ -134,12 +142,9 @@ const make = /*#__PURE__*/ Effect.fnUntraced(function* (config = {}) {
 		}),
 		dehydrate: (options = {}) => Effect.sync(() => dehydrateEntries(state.entries.values(), options)),
 		dehydrateStream: (options = {}) => dehydrateStream(() => state.entries.values(), subscribeUnsafe, options),
-		ensure: (factory, input, options) => Effect.flatMap(buildFor(factory, input), (entry) => load(entry, options?.pages, false).pipe(Effect.as({
-			...handleOf(entry),
-			ensured: true
-		}))),
+		ensure: (factory, input, options) => Effect.flatMap(buildFor(factory, input), (entry) => withData(entry, load(entry, options?.pages, false))),
 		events: listen(subscribeUnsafe),
-		fetch: (factory, input, options) => Effect.flatMap(buildFor(factory, input), (entry) => load(entry, options?.pages, true)),
+		fetch: (factory, input, options) => Effect.flatMap(buildFor(factory, input), (entry) => withData(entry, load(entry, options?.pages, true))),
 		getData: (factory, ...args) => Effect.sync(() => {
 			const options = optionsFor(factory, args[0]);
 			const entry = state.entries.get(hashKey(options.queryKey));

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { platform_d_exports } from "./platform.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
-import { AnyQueryOptions, DataOf, EnsuredQueryHandle, ErrorOf, InfiniteData, InfiniteQueryOptions, InfiniteQueryTypes, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, PagedQueryFactory, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryMeta, QueryOptions, QueryTypes, Register, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.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 { Pending, Thenable, fulfilled, pending } from "./thenable.mjs";
 import { query_d_exports } from "./query.mjs";
 import { observer_d_exports } from "./observer.mjs";
-export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type EnsuredQueryHandle, 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 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 };
+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 };

package/dist/options.d.mts

@@ -311,27 +311,23 @@ export interface LoadOptions {
   readonly pages?: number;
 }
 declare const factoryType: unique symbol;
-interface HandleFields<TFactory extends QueryFactory> {
+/**
+ * The serializable reference a loader or server component hands to the
+ * component that reads the query. It holds no functions.
+ */
+export interface QueryHandle<TFactory extends QueryFactory = QueryFactory> {
   /** Type-only: ties the handle to its factory. Never present at runtime. */
   readonly [factoryType]?: TFactory;
   /** The factory's input; `unknown` on a handle of no particular factory. */
-  readonly input: QueryFactory extends TFactory ? unknown : InputOf<TFactory>;
+  readonly input: InputOf<TFactory>;
   readonly key: QueryKey;
 }
 /**
- * The serializable reference a loader or server component hands to the
- * component that reads the query. It holds no data and no functions.
- */
-export interface QueryHandle<TFactory extends QueryFactory = QueryFactory> extends HandleFields<TFactory> {
-  readonly ensured?: false;
-}
-/**
- * A handle from `ensure`: its data was loaded before the handle was
- * returned, so `useQuery` returns the data rather than a promise. Not
- * assignable to {@link QueryHandle}, so a prop typed for one can't receive
- * the other.
+ * A handle from `ensure` or `fetch`, with the data they waited for. `data`
+ * is a snapshot from when the handle was returned; components read the live
+ * entry with `useQuery`.
  */
-export interface EnsuredQueryHandle<TFactory extends QueryFactory = QueryFactory> extends HandleFields<TFactory> {
-  readonly ensured: true;
+export interface QueryHandleWithData<TFactory extends QueryFactory = QueryFactory> extends QueryHandle<TFactory> {
+  readonly data: DataOf<TFactory>;
 }
 //#endregion

package/package.json

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