@raf-query/core 0.0.16 → 0.0.18

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Changelog
 
+## [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))
+
 ## [0.0.16](https://github.com/KATT/raf-query/compare/0.0.15...0.0.16) (2026-10-12)
 
 ### Bug Fixes
 
-* **core:** don't revalidate cached data in server verbs ([#19](https://github.com/KATT/raf-query/issues/19)) ([0ed7d9f](https://github.com/KATT/raf-query/commit/0ed7d9fefd0b70a8aa9a85c8d2c309a9fed42903))
+- **core:** don't revalidate cached data in server verbs ([#19](https://github.com/KATT/raf-query/issues/19)) ([0ed7d9f](https://github.com/KATT/raf-query/commit/0ed7d9fefd0b70a8aa9a85c8d2c309a9fed42903))
 
 ## [0.0.15](https://github.com/KATT/raf-query/compare/0.0.14...0.0.15) (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.
@@ -556,6 +558,8 @@ Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.de
 
 `infiniteQueryOptions` also takes `getPreviousPageParam` and `maxPages`.
 
+In the browser, retries pause while `navigator.onLine` is `false`: after the retry delay, the next attempt waits for the window's `online` event. The request stays fetching meanwhile, and cancelling it (`remove`, `clear`, a restart) stops the wait. The first attempt runs regardless.
+
 `@raf-query/core`:
 
 | Export                                         | Use                                                              |

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

@@ -115,9 +115,9 @@ var QueryClient = class {
 	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 state = entry.getState();
+		if (!state.hasData) throw new Error(`Query ${entry.hash} has no data`);
+		return unsafeCast(state.data);
 	}
 	async invalidate(target, input) {
 		await Promise.all(this.#match(target, input).map((entry) => entry.invalidate()));
@@ -134,7 +134,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));

package/dist/online.mjs

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+//#region src/online.ts
+function isOffline() {
+	return "window" in globalThis && "navigator" in globalThis && "onLine" in navigator && !navigator.onLine;
+}
+/**
+* Succeeds now if the browser is online, else on the window's next `online`
+* event. Interrupting it removes the listener.
+*/
+const whenOnline = Effect.suspend(() => isOffline() ? Effect.callback((resume) => {
+	const onOnline = () => resume(Effect.void);
+	window.addEventListener("online", onOnline, { once: true });
+	return Effect.sync(() => window.removeEventListener("online", onOnline));
+}) : Effect.void);
+//#endregion
+export { whenOnline };

package/dist/query.mjs

@@ -1,4 +1,5 @@
 import { scheduleNotify } from "./notify.mjs";
+import { whenOnline } from "./online.mjs";
 import { replaceEqualDeep } from "./share.mjs";
 import { fulfilled, pending } from "./thenable.mjs";
 import { Cause, Effect, Exit, Predicate, Schedule } from "effect";
@@ -382,7 +383,16 @@ var QueryEntry = class {
 		const retry = this.#behavior("retry") ?? (this.#host.isServer ? 0 : 3);
 		const countFailure = Effect.sync(() => this.#set({ failureCount: this.#state.failureCount + 1 }));
 		const counted = once.pipe(Effect.tapError(() => countFailure));
-		if (Schedule.isSchedule(retry)) return Effect.retry(counted, retry);
+		const online = this.#host.isServer ? Effect.void : whenOnline;
+		if (Schedule.isSchedule(retry)) return Effect.suspend(() => {
+			let first = true;
+			const each = Effect.suspend(() => {
+				const wait = first ? Effect.void : online;
+				first = false;
+				return wait.pipe(Effect.andThen(counted));
+			});
+			return Effect.retry(each, retry);
+		});
 		const retryDelay = this.#behavior("retryDelay");
 		const delayFor = (failureCount, error) => {
 			if (retryDelay === void 0) return Math.min(1e3 * 2 ** (failureCount - 1), 3e4);
@@ -391,7 +401,7 @@ var QueryEntry = class {
 		const attempt = counted.pipe(Effect.catch((error) => {
 			const failureCount = this.#state.failureCount;
 			if (!shouldRetry(retry, failureCount, error)) return Effect.fail(error);
-			return Effect.sleep(delayFor(failureCount, error)).pipe(Effect.andThen(Effect.suspend(() => attempt)));
+			return Effect.sleep(delayFor(failureCount, error)).pipe(Effect.andThen(online), Effect.andThen(Effect.suspend(() => attempt)));
 		}));
 		return attempt;
 	}

package/package.json

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