@raf-query/core 0.0.18 → 0.0.19

package/CHANGELOG.md

@@ -1,10 +1,16 @@
 # Changelog
 
+## [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

@@ -574,16 +574,17 @@ In the browser, retries pause while `navigator.onLine` is `false`: after the ret
 | `CancelledError`                               | Rejection of a request cancelled by `clear()` or a restart       |
 | `QueryHandle<TFactory>`                        | Handle type for props                                            |
 | `EnsuredQueryHandle<TFactory>`                 | Handle type for props fed by `ensure`                            |
+| `Thenable<T>`                                  | Promise with `status` / `value` / `reason`, read by `use()`      |
 | `DataOf<TFactory>`, `InputOf<TFactory>`        | A factory's data and input types                                 |
 
 `@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                                                                                                             |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `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/client.mjs

@@ -113,11 +113,8 @@ var QueryClient = class {
 	}
 	/** Like `ensure`, but resolves to the data. */
 	async fetch(factory, ...args) {
-		const entry = this.#build(factory, args[0]);
-		await this.#load(entry, args[1]?.pages);
-		const state = entry.getState();
-		if (!state.hasData) throw new Error(`Query ${entry.hash} has no data`);
-		return unsafeCast(state.data);
+		const entry = typed(this.#build(factory, args[0]));
+		return this.#load(entry, args[1]?.pages);
 	}
 	async invalidate(target, input) {
 		await Promise.all(this.#match(target, input).map((entry) => entry.invalidate()));
@@ -201,11 +198,12 @@ var QueryClient = class {
 		entry.setOptions(options, input);
 		return entry;
 	}
+	/** Resolves to the entry's data: the cached thenable, or the first fetch. */
 	#load(entry, pages) {
 		const state = entry.getState();
 		if (!state.hasData) return entry.fetch({ pages });
 		this.#revalidate(entry);
-		return Promise.resolve(state.data);
+		return state.promise;
 	}
 	/**
 	* Background refetch of cached data a verb reuses. A server client renders

package/dist/index.d.mts

@@ -1,8 +1,9 @@
 import { Settled, allKeyed } from "./all-keyed.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
 import { AnyQueryOptions, DataOf, EnsuredQueryHandle, InfiniteData, InfiniteQueryOptions, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryOptions, RetryPolicy, infiniteQueryOptions, queryOptions } from "./options.mjs";
+import { Thenable } from "./thenable.mjs";
 import { CancelledError, FetchRequest, Query, QueryState, SubscribeOptions } from "./query.mjs";
 import { CacheEvent, LoadArgs, QueryClient, QueryClientConfig, QueryClientEffect, QueryFilter, Updater } from "./client.mjs";
 import { DehydrateOptions, DehydratedQuery, DehydratedState, HydrateOptions, canDehydrate, dehydrate, dehydrateQuery, hydrate } from "./hydration.mjs";
 import { QueryObserver, QueryObserverOptions, QueryObserverResult } from "./observer.mjs";
-export { type AnyQueryOptions, type CacheEvent, CancelledError, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type EnsuredQueryHandle, type FetchRequest, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadArgs, type LoadOptions, type PageFunctionContext, type PageOf, type Query, type QueryBehavior, QueryClient, type QueryClientConfig, type QueryClientEffect, type QueryFactory, type QueryFilter, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, QueryObserver, type QueryObserverOptions, type QueryObserverResult, type QueryOptions, type QueryState, type RetryPolicy, type Settled, type SubscribeOptions, type Updater, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };
+export { type AnyQueryOptions, type CacheEvent, CancelledError, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type EnsuredQueryHandle, type FetchRequest, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadArgs, type LoadOptions, type PageFunctionContext, type PageOf, type Query, type QueryBehavior, QueryClient, type QueryClientConfig, type QueryClientEffect, type QueryFactory, type QueryFilter, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, QueryObserver, type QueryObserverOptions, type QueryObserverResult, type QueryOptions, type QueryState, type RetryPolicy, type Settled, type SubscribeOptions, type Thenable, type Updater, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };

package/dist/observer.d.mts

@@ -1,5 +1,6 @@
 import { QueryKey } from "./key.mjs";
 import { QueryFactory } from "./options.mjs";
+import { Thenable } from "./thenable.mjs";
 import { Query } from "./query.mjs";
 //#region src/observer.d.ts
 /** How one reader observes its query. */
@@ -42,7 +43,7 @@ export interface QueryObserverResult<TData = unknown> {
   /** Key of the data in `promise`; differs from the query's while `isPrevious`. */
   readonly key: QueryKey;
   /** Settles with the data to show; see `QueryState.promise`. */
-  readonly promise: Promise<TData>;
+  readonly promise: Thenable<TData>;
   refetch(): Promise<void>;
   /** When the data in `promise` was fetched (ms since epoch); `0` before that. */
   readonly updatedAt: number;

package/dist/query.d.mts

@@ -1,5 +1,6 @@
 import { QueryKey } from "./key.mjs";
 import { AnyQueryOptions, QueryFactory, QueryHandle } from "./options.mjs";
+import { Thenable } from "./thenable.mjs";
 //#region src/query.d.ts
 /** A snapshot of one cache entry. Replaced, never mutated, on every change. */
 export interface QueryState<TData> {
@@ -20,9 +21,9 @@ export interface QueryState<TData> {
   readonly isStale: boolean;
   /**
    * Settles with `data`. A new promise is created per data version, already
-   * fulfilled once data exists, so React's `use()` reads it synchronously.
+   * fulfilled once data exists, so it can be read synchronously.
    */
-  readonly promise: Promise<TData>;
+  readonly promise: Thenable<TData>;
   readonly status: "error" | "pending" | "success";
   /** When `data` was fetched (ms since epoch); `0` without data. */
   readonly updatedAt: number;

package/dist/thenable.d.mts

@@ -0,0 +1,24 @@
+//#region src/thenable.d.ts
+/**
+ * Promises that carry their own result, in the fields React's `use()` reads
+ * before suspending (`status`, `value`, `reason`). A settled one can be read
+ * synchronously, so React renders it without a fallback.
+ */
+interface PendingStatus {
+  readonly status: "pending";
+}
+interface FulfilledStatus<T> {
+  readonly status: "fulfilled";
+  readonly value: T;
+}
+interface RejectedStatus {
+  readonly reason: unknown;
+  readonly status: "rejected";
+}
+/**
+ * A promise that says whether it has settled, and with what. `status` moves
+ * from `"pending"` to `"fulfilled"` (with `value`) or `"rejected"` (with
+ * `reason`) once, when the promise settles.
+ */
+export type Thenable<T> = Promise<T> & (FulfilledStatus<T> | PendingStatus | RejectedStatus);
+//#endregion

package/dist/thenable.mjs

@@ -1,8 +1,8 @@
 //#region src/thenable.ts
 /**
-* Promises that React's `use()` can read synchronously. React checks
-* `status` / `value` / `reason` on a thenable before suspending, so a
-* settled one renders without a fallback.
+* Promises that carry their own result, in the fields React's `use()` reads
+* before suspending (`status`, `value`, `reason`). A settled one can be read
+* synchronously, so React renders it without a fallback.
 */
 const noop = () => {};
 function fulfilled(value) {

package/package.json

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