@raf-query/core 0.10.4 → 0.11.0

package/CHANGELOG.md

@@ -1,11 +1,21 @@
 # Changelog
 
+## [0.11.0](https://github.com/KATT/raf-query/compare/0.10.4...0.11.0) (2026-10-16)
+
+### ⚠ BREAKING CHANGES
+
+* **core:** enabled replaces ssr, as a boolean like TanStack Query's ([#204](https://github.com/KATT/raf-query/issues/204))
+
+### Features
+
+* **core:** enabled replaces ssr, as a boolean like TanStack Query's ([#204](https://github.com/KATT/raf-query/issues/204)) ([b7e543b](https://github.com/KATT/raf-query/commit/b7e543b9d1d34e02061740f749f2ddabcdee2ad2))
+
 ## [0.10.4](https://github.com/KATT/raf-query/compare/0.10.3...0.10.4) (2026-10-16)
 
 ### Bug Fixes
 
-* **core:** keep pages written during a paged refetch ([#215](https://github.com/KATT/raf-query/issues/215)) ([b6a5946](https://github.com/KATT/raf-query/commit/b6a5946e806e12e9b7df40e80ef0e532c0871b25)), references [#75](https://github.com/KATT/raf-query/issues/75)
-* **react:** read promise queryFns as plain data on a client with a layer (1/2) ([#205](https://github.com/KATT/raf-query/issues/205)) ([a9b156e](https://github.com/KATT/raf-query/commit/a9b156edfa18b1e41e9ea929afc412252a61b83c))
+- **core:** keep pages written during a paged refetch ([#215](https://github.com/KATT/raf-query/issues/215)) ([b6a5946](https://github.com/KATT/raf-query/commit/b6a5946e806e12e9b7df40e80ef0e532c0871b25)), references [#75](https://github.com/KATT/raf-query/issues/75)
+- **react:** read promise queryFns as plain data on a client with a layer (1/2) ([#205](https://github.com/KATT/raf-query/issues/205)) ([a9b156e](https://github.com/KATT/raf-query/commit/a9b156edfa18b1e41e9ea929afc412252a61b83c))
 
 ## [0.10.3](https://github.com/KATT/raf-query/compare/0.10.2...0.10.3) (2026-10-16)
 

package/dist/entry.d.mts

@@ -6,7 +6,7 @@ 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 };
+  export { CacheState, CancelledError, DisabledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isDisabled, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
 }
 export declare const TypeId = "~@raf-query/core/Query";
 declare const CancelledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
@@ -19,14 +19,14 @@ declare const CancelledError_base: new <A extends Record<string, any> = {}>(args
 export declare class CancelledError extends CancelledError_base {
   readonly message = "The query was cancelled";
 }
-declare const BrowserOnlyError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
-  readonly _tag: "BrowserOnlyError";
+declare const DisabledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+  readonly _tag: "DisabledError";
 } & Readonly<A>;
 /**
- * Why a query with `ssr: false` has no data on the server: its promise
- * there rejects with this, and `ensure` / `fetch` die with it.
+ * Why a query with `enabled: false` has no data: `ensure` / `fetch` die
+ * with it, and on a server its promise rejects with it.
  */
-export declare class BrowserOnlyError extends BrowserOnlyError_base<{
+export declare class DisabledError extends DisabledError_base<{
   readonly hash: string;
 }> {
   get message(): string;
@@ -106,8 +106,8 @@ export declare function emit(cache: CacheState, event: Event): void;
 export declare function make(cache: CacheState, key: QueryKey, hash: string): Entry;
 /** Readers are subscribed; `invalidate` and focus refetch only what is read. */
 export declare function isObserved(entry: Entry): boolean;
-/** A server cache's entry for an `ssr: false` query: it never runs here. */
-export declare function isBrowserOnly(entry: Entry): boolean;
+/** The entry's latest factory call returned `enabled: false`: it doesn't run. */
+export declare function isDisabled(entry: Entry): boolean;
 /** Until a factory call attaches options, `meta` comes from hydration. */
 export declare function metaOf(entry: Entry): QueryMeta | undefined;
 export declare function isStaleUnsafe(entry: Entry): boolean;

package/dist/entry.mjs

@@ -17,12 +17,12 @@ var CancelledError = class extends Data.TaggedError("CancelledError") {
 	message = "The query was cancelled";
 };
 /**
-* Why a query with `ssr: false` has no data on the server: its promise
-* there rejects with this, and `ensure` / `fetch` die with it.
+* Why a query with `enabled: false` has no data: `ensure` / `fetch` die
+* with it, and on a server its promise rejects with it.
 */
-var BrowserOnlyError = class extends Data.TaggedError("BrowserOnlyError") {
+var DisabledError = class extends Data.TaggedError("DisabledError") {
 	get message() {
-		return `Query ${this.hash} runs in the browser only (ssr: false)`;
+		return `Query ${this.hash} is disabled (enabled: false)`;
 	}
 };
 const Proto = {
@@ -95,7 +95,7 @@ function make(cache, key, hash) {
 		},
 		tasks: makeTasks(cache, scope)
 	});
-	const command = (request) => Effect.suspend(() => isBrowserOnly(entry) ? Effect.void : Effect.ignore(fetch(entry, request)));
+	const command = (request) => Effect.suspend(() => isDisabled(entry) ? Effect.void : Effect.ignore(fetch(entry, request)));
 	const commands = {
 		fetchNextPage: command({ direction: "forward" }),
 		fetchPreviousPage: command({ direction: "backward" }),
@@ -115,9 +115,9 @@ function isObserved(entry) {
 function behavior(entry, name) {
 	return entry.options?.[name] ?? entry.cache.defaults[name];
 }
-/** A server cache's entry for an `ssr: false` query: it never runs here. */
-function isBrowserOnly(entry) {
-	return entry.cache.isServer && behavior(entry, "ssr") === false;
+/** The entry's latest factory call returned `enabled: false`: it doesn't run. */
+function isDisabled(entry) {
+	return behavior(entry, "enabled") === false;
 }
 /** Until a factory call attaches options, `meta` comes from hydration. */
 function metaOf(entry) {
@@ -225,7 +225,7 @@ function fetch(entry, request = {}) {
 function invalidate(entry) {
 	return Effect.suspend(() => {
 		set(entry, { isInvalidated: true });
-		if (!isObserved(entry) || !entry.options || isBrowserOnly(entry)) return Effect.void;
+		if (!isObserved(entry) || !entry.options || isDisabled(entry)) return Effect.void;
 		return Effect.ignore(begin(entry, { restart: true }));
 	});
 }
@@ -244,7 +244,7 @@ function reset(entry) {
 			status: "pending",
 			updatedAt: 0
 		});
-		if (!entry.options || isBrowserOnly(entry) || !isObserved(entry) && !entry.inFlight) return Effect.void;
+		if (!entry.options || isDisabled(entry) || !isObserved(entry) && !entry.inFlight) return Effect.void;
 		return Effect.ignore(begin(entry, { restart: true }));
 	});
 }
@@ -291,11 +291,13 @@ function remove(entry) {
 */
 function begin(entry, request) {
 	if (Predicate.isTagged(entry.scope.state, "Closed")) return Effect.fail(new CancelledError());
-	if (isBrowserOnly(entry)) {
-		const error = new BrowserOnlyError({ hash: entry.hash });
-		const firstLoad = entry.pending;
-		entry.pending = void 0;
-		firstLoad?.reject(error);
+	if (isDisabled(entry)) {
+		const error = new DisabledError({ hash: entry.hash });
+		if (entry.cache.isServer) {
+			const firstLoad = entry.pending;
+			entry.pending = void 0;
+			firstLoad?.reject(error);
+		}
 		return Effect.die(error);
 	}
 	const options = entry.options;
@@ -332,7 +334,7 @@ function startRequest(entry, request, direction, updatedAt) {
 	entry.retriesStopped = false;
 	entry.signalRead = false;
 	entry.tasks.cancel("gc");
-	if (!entry.state.hasData && entry.state.status === "error") {
+	if (!entry.state.hasData && !entry.pending) {
 		entry.pending = pending();
 		set(entry, {
 			error: null,
@@ -521,4 +523,4 @@ function scheduleStale(entry) {
 	entry.tasks.fork("stale", Effect.sleep(Math.max(remaining, 0) + 1).pipe(Effect.andThen(Effect.sync(() => set(entry, {})))));
 }
 //#endregion
-export { BrowserOnlyError, CancelledError, 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 };
+export { CancelledError, DisabledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isDisabled, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };

package/dist/hydration.mjs

@@ -1,4 +1,4 @@
-import { entryOf, isBrowserOnly, resume, revalidate, setData } from "./entry.mjs";
+import { entryOf, isDisabled, resume, revalidate, setData } from "./entry.mjs";
 import { getUnsafe, metaUnsafe, returnsEffectUnsafe } from "./query.mjs";
 import { Data, Effect, Queue, Stream } from "effect";
 //#region src/hydration.ts
@@ -62,7 +62,7 @@ function dehydrateEntries(queries, options) {
 	const filter = options.filter ?? canDehydrate;
 	const sent = options.sent;
 	const dehydrated = [];
-	for (const query of queries) if (!sent?.has(query.hash) && !isBrowserOnly(entryOf(query)) && filter(query)) {
+	for (const query of queries) if (!sent?.has(query.hash) && !isDisabled(entryOf(query)) && filter(query)) {
 		sent?.add(query.hash);
 		dehydrated.push(dehydrateUnsafe(query, options));
 	}

package/dist/options.d.mts

@@ -135,6 +135,20 @@ export interface PageFunctionContext<TPageParam> extends QueryFunctionContext {
 export type RetryPolicy = boolean | number | Schedule.Schedule<unknown, unknown> | ((failureCount: number, error: unknown) => boolean);
 /** Options every query accepts. `QueryCache` defaults fill in the rest. */
 export interface QueryBehavior {
+  /**
+   * `false` keeps the query from running. Default `true`. The factory
+   * decides per call, so `enabled: typeof window !== "undefined"` runs a
+   * query only in the browser, for data only a browser has (permissions,
+   * device APIs, `localStorage`).
+   *
+   * While disabled, readers see `isPending`, `ensure` and `fetch` fail with
+   * `Query.DisabledError`, and `invalidate`, `reset` and `refetch` do
+   * nothing. In the browser, its promise stays pending until a factory
+   * call returns `true` and runs it. A server cache never sends it, and its
+   * promise rejects with `Query.DisabledError`: under Suspense, React
+   * renders the fallback on the server and the component in the browser.
+   */
+  readonly enabled?: boolean;
   /** How long an unread entry stays cached, in ms. `Infinity` keeps it. */
   readonly gcTime?: number;
   /**
@@ -151,15 +165,6 @@ export interface QueryBehavior {
   readonly retry?: RetryPolicy;
   /** Delay before retry number `failureCount` (1-based), in ms. */
   readonly retryDelay?: number | ((failureCount: number, error: unknown) => number);
-  /**
-   * `false`: only the browser runs the query, for data only a browser has
-   * (permissions, device APIs). A server cache never starts it or sends it.
-   * Readers there see `isPending`, and a promise that rejects with
-   * `Query.BrowserOnlyError`: under Suspense, React renders the fallback on
-   * the server and the query in the browser. `ensure` and `fetch` on the
-   * server fail with that error. Default `true`.
-   */
-  readonly ssr?: boolean;
   /** How long data counts as fresh, in ms. Fresh data is never refetched. */
   readonly staleTime?: number;
   /**

package/dist/query.d.mts

@@ -2,10 +2,10 @@ 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 { CancelledError as CancelledError$1, DisabledError as DisabledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.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, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };
+  export { CancelledError, DisabledError, FetchRequest, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };
 }
 export declare const TypeId: typeof TypeId$1;
 export type TypeId = typeof TypeId;
@@ -67,8 +67,8 @@ export interface FetchRequest {
 }
 export declare const CancelledError: typeof CancelledError$1;
 export type CancelledError = CancelledError$1;
-export declare const BrowserOnlyError: typeof BrowserOnlyError$1;
-export type BrowserOnlyError = BrowserOnlyError$1;
+export declare const DisabledError: typeof DisabledError$1;
+export type DisabledError = DisabledError$1;
 export declare const isQuery: (value: unknown) => value is Query;
 /**
  * Start a request, or join the one in flight. Fails with the request's

package/dist/query.mjs

@@ -1,5 +1,5 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
-import { BrowserOnlyError as BrowserOnlyError$1, CancelledError as CancelledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, metaOf, provide, readUnsafe as readUnsafe$1, reset as reset$1, revalidate, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
+import { CancelledError as CancelledError$1, DisabledError as DisabledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, metaOf, provide, readUnsafe as readUnsafe$1, reset as reset$1, revalidate, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
 import { Effect } from "effect";
 import { dual } from "effect/Function";
 //#region src/query.ts
@@ -12,8 +12,8 @@ import { dual } from "effect/Function";
 * synchronously, for renders and external stores that can't run an Effect.
 */
 var query_exports = /* @__PURE__ */ __exportAll({
-	BrowserOnlyError: () => BrowserOnlyError,
 	CancelledError: () => CancelledError,
+	DisabledError: () => DisabledError,
 	TypeId: () => TypeId,
 	changes: () => changes,
 	fetch: () => fetch,
@@ -37,7 +37,7 @@ var query_exports = /* @__PURE__ */ __exportAll({
 });
 const TypeId = TypeId$1;
 const CancelledError = CancelledError$1;
-const BrowserOnlyError = BrowserOnlyError$1;
+const DisabledError = DisabledError$1;
 const isQuery = isQuery$1;
 function typed(effect) {
 	return effect;
@@ -144,4 +144,4 @@ function observerCountUnsafe(self) {
 	return entryOf(self).listeners.size;
 }
 //#endregion
-export { BrowserOnlyError, CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };
+export { CancelledError, DisabledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };

package/package.json

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