@raf-query/core 0.0.17 → 0.0.19

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # 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)
+
 ## [0.0.17](https://github.com/KATT/raf-query/compare/0.0.16...0.0.17) (2026-10-12)
 
 ### Features
 
-* **core:** pause retries while the browser is offline ([#18](https://github.com/KATT/raf-query/issues/18)) ([a25c664](https://github.com/KATT/raf-query/commit/a25c664359fe7248cdc8d91a14d524e37b467c6c))
+- **core:** pause retries while the browser is offline ([#18](https://github.com/KATT/raf-query/issues/18)) ([a25c664](https://github.com/KATT/raf-query/commit/a25c664359fe7248cdc8d91a14d524e37b467c6c))
 
 ## [0.0.16](https://github.com/KATT/raf-query/compare/0.0.15...0.0.16) (2026-10-12)
 

package/README.md

@@ -363,6 +363,8 @@ 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.
+
 ## SSR and hydration
 
 The server's query client streams its cache to the browser's query client as entries settle. Pending queries cross as promises, so the browser resumes the server's request instead of starting a new one. Components never hydrate anything themselves; a handle only needs its key to find the entry.
@@ -572,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.d.mts

@@ -34,7 +34,10 @@ export interface QueryFilter {
 }
 /** `ensure` / `fetch` arguments: the input, then load options for paged factories. */
 export type LoadArgs<TFactory extends QueryFactory> = InputArgs<TFactory> | [input: InputOf<TFactory>, options: LoadOptions<TFactory>];
-/** A new value, or a function of the current one. */
+/**
+ * A new value, or a function of the current one. `previous` is `undefined`
+ * both with no data and with `undefined` data.
+ */
 export type Updater<TData> = TData | ((previous: TData | undefined) => TData);
 /** Effect-returning twins of the client's async methods. */
 export interface QueryClientEffect {
@@ -100,7 +103,10 @@ export declare class QueryClient {
   remove(filter: QueryFilter): void;
   /** Write data for a factory call. Readers re-render without suspending. */
   setData<TFactory extends QueryFactory>(factory: TFactory, input: InputOf<TFactory>, updater: Updater<DataOf<TFactory>>): void;
-  /** Cached data for a factory call, or `undefined`. */
+  /**
+   * Cached data for a factory call, or `undefined` if there is none. Data can
+   * itself be `undefined`; `getQuery(...).getState().hasData` tells them apart.
+   */
   getData<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): DataOf<TFactory> | undefined;
   /** Every entry, for devtools and integrations. */
   getAll(): ReadonlyArray<Query>;

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 data = typed(entry).getState().data;
-		if (data === void 0) throw new Error(`Query ${entry.hash} has no data`);
-		return 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()));
@@ -134,7 +131,10 @@ var QueryClient = class {
 		const next = isUpdateFunction(updater) ? updater(typed(entry).getState().data) : updater;
 		entry.setData(next);
 	}
-	/** Cached data for a factory call, or `undefined`. */
+	/**
+	* Cached data for a factory call, or `undefined` if there is none. Data can
+	* itself be `undefined`; `getQuery(...).getState().hasData` tells them apart.
+	*/
 	getData(factory, ...args) {
 		const options = optionsFor(factory, args[0]);
 		const entry = this.#cache.get(hashKey(options.queryKey));
@@ -198,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.17",
+  "version": "0.0.19",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",