@octanejs/tanstack-query 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @octanejs/tanstack-query
+
+[TanStack Query](https://tanstack.com/query) for the [octane](https://github.com/octanejs/octane) UI framework.
+
+TanStack Query separates a framework-agnostic core (`@tanstack/query-core` — the
+`QueryClient`, observers, and caches) from a React binding (`@tanstack/react-query`)
+built on `useSyncExternalStore` + context. This package reuses the core verbatim and
+reimplements only the binding on octane's hooks. The public surface matches
+`@tanstack/react-query`, so most query code works by changing the import.
+
+```tsx
+// before
+import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';
+// after
+import { QueryClient, QueryClientProvider, useQuery } from '@octanejs/tanstack-query';
+
+const client = new QueryClient();
+
+function Todos() @{
+  const q = useQuery({ queryKey: ['todos'], queryFn: fetchTodos });
+  @if (q.isPending) { <span>loading…</span> }
+  @else if (q.isError) { <span>{(q.error as Error).message as string}</span> }
+  @else { <ul>{q.data as unknown}</ul> }
+}
+
+function App() @{
+  <QueryClientProvider client={client}>
+    <Todos />
+  </QueryClientProvider>
+}
+```
+
+## What's bound
+
+- Queries: `useQuery`, `useInfiniteQuery`, `useSuspenseQuery`,
+  `useSuspenseInfiniteQuery`, `useQueries`, `usePrefetchQuery`,
+  `usePrefetchInfiniteQuery`
+- Mutations: `useMutation`, `useMutationState`
+- Status: `useIsFetching`, `useIsMutating`
+- Components / context: `QueryClientProvider`, `useQueryClient`, `QueryClientContext`,
+  `HydrationBoundary`, `IsRestoringProvider`, `useIsRestoring`,
+  `QueryErrorResetBoundary`, `useQueryErrorResetBoundary`
+- everything from `@tanstack/query-core` (`QueryClient`, `QueryCache`, observers,
+  `dehydrate`/`hydrate`, …), re-exported verbatim.
+
+The whole `@tanstack/react-query` surface is bound. The separate companion packages
+(`@tanstack/react-query-persist-client`, `@tanstack/react-query-devtools`) are not
+included.
+
+## How it works
+
+octane keys hooks by a compiler-injected per-call-site `Symbol`, appended as the last
+argument of every `use*` call. The binding's hooks compose several base hooks
+(`useState` for the observer, `useSyncExternalStore` to subscribe, `useEffect` for
+option changes), so each forwards a distinct sub-slot derived from the one it receives.
+`QueryClientProvider` is a component (it renders a context Provider + a mount effect),
+so it's authored in `.tsrx`.
+
+## Suspense & error boundaries
+
+A query with `suspense: true` suspends, and a query/mutation with `throwOnError` throws
+its error. Catch them with either octane form — the `<Suspense>` / `<ErrorBoundary>`
+components or the `@try { } @pending { } @catch { }` directive:
+
+```tsx
+import { Suspense, ErrorBoundary } from 'octane';
+
+<ErrorBoundary fallback={(err) => <Oops error={err} />}>
+  <Suspense fallback={<Spinner />}>
+    <Profile />   {/* useQuery({ queryKey, queryFn, suspense: true }) */}
+  </Suspense>
+</ErrorBoundary>
+```
+
+## Persistence & error resets
+
+`IsRestoringProvider` / `useIsRestoring` gate fetching while a persisted client is
+restored, and `QueryErrorResetBoundary` / `useQueryErrorResetBoundary` coordinate
+error-boundary retries with `@catch` / `<ErrorBoundary>` — call the boundary's
+`reset()` alongside `useQueryErrorResetBoundary().reset()` so a `throwOnError` query
+refetches instead of immediately re-throwing.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@octanejs/tanstack-query",
+  "version": "0.1.2",
+  "license": "MIT",
+  "type": "module",
+  "description": "TanStack Query bindings for the octane renderer — reuses @tanstack/query-core and swaps the React binding for octane's hooks.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-query"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/query-core": "^5.0.0",
+    "octane": "0.1.3"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/HydrationBoundary.tsrx

@@ -0,0 +1,74 @@
+// HydrationBoundary — hydrates dehydrated query state into the client, then
+// renders its children. Full port of react-query's HydrationBoundary.tsx:
+//
+//  - NEW queries hydrate IN RENDER (after SSR, hydration must land before the
+//    children render; during a transition, prerender as much as is safe).
+//  - EXISTING queries hydrate in an EFFECT: during a transition we must not
+//    update live queries/observers until the transition commits — an aborted
+//    transition must not clobber committed data (octane has transitions, so
+//    upstream's abort-safety applies here too).
+//  - A dehydrated query counts as NEWER than the cache when its dataUpdatedAt
+//    is ahead, OR when it carries a streaming `promise` and was dehydrated
+//    after the cached data settled (`dehydratedAt > dataUpdatedAt`) — that's
+//    what lets later stream chunks re-hydrate an already-settled query.
+import { useRef, useMemo, useEffect } from 'octane';
+import { hydrate } from '@tanstack/query-core';
+import { resolveClient } from './context.ts';
+
+export function HydrationBoundary(props) @{
+	const client = resolveClient(props.queryClient);
+	const state = props.state;
+
+	const optionsRef = useRef(props.options);
+	useEffect(() => {
+		optionsRef.current = props.options;
+	});
+
+	// "In render" on purpose (the memo is a perf cache, not a semantic barrier) —
+	// hydrate new queries now, queue existing ones for the commit effect.
+	const hydrationQueue = useMemo(() => {
+		if (state && typeof state === 'object') {
+			const queryCache = client.getQueryCache();
+			const queries = state.queries || [];
+
+			const newQueries = [];
+			const existingQueries = [];
+			for (const dehydratedQuery of queries) {
+				const existingQuery = queryCache.get(dehydratedQuery.queryHash);
+				if (!existingQuery) {
+					newQueries.push(dehydratedQuery);
+				} else {
+					const hydrationIsNewer =
+						dehydratedQuery.state.dataUpdatedAt > existingQuery.state.dataUpdatedAt ||
+							dehydratedQuery.promise && existingQuery.state.status !== 'pending' &&
+								existingQuery.state.fetchStatus !== 'fetching' &&
+								dehydratedQuery.dehydratedAt !== undefined &&
+								dehydratedQuery.dehydratedAt > existingQuery.state.dataUpdatedAt;
+					if (hydrationIsNewer) {
+						existingQueries.push(dehydratedQuery);
+					}
+				}
+			}
+
+			if (newQueries.length > 0) {
+				// hydrate() is idempotent for queries — safe to run in render.
+				hydrate(client, { queries: newQueries }, optionsRef.current);
+			}
+			if (existingQueries.length > 0) {
+				return existingQueries;
+			}
+		}
+		return undefined;
+	}, [client, state]);
+
+	// Existing-query hydration lands at commit time (transition abort-safe).
+	useEffect(() => {
+		if (hydrationQueue) {
+			hydrate(client, { queries: hydrationQueue }, optionsRef.current);
+		}
+	}, [client, hydrationQueue]);
+
+	<>
+		{props.children}
+	</>
+}

package/src/HydrationBoundary.tsrx.d.ts

@@ -0,0 +1,9 @@
+// Type declaration for the .tsrx component (resolved by relative path).
+import type { DehydratedState, HydrateOptions, QueryClient } from '@tanstack/query-core';
+
+export declare const HydrationBoundary: (props: {
+	state: DehydratedState | null | undefined;
+	options?: HydrateOptions;
+	children?: unknown;
+	queryClient?: QueryClient;
+}) => unknown;

package/src/QueryClientProvider.tsrx

@@ -0,0 +1,16 @@
+import { useEffect } from 'octane';
+import { QueryClientContext } from './context.ts';
+
+// QueryClientProvider — provides the QueryClient via context and mounts/unmounts
+// it with the component. It's authored in .tsrx because it's a COMPONENT that
+// renders a context Provider with children + a mount effect, which only the
+// octane compiler can emit (the binding's hooks stay plain TS).
+export function QueryClientProvider(props) @{
+	useEffect(() => {
+		props.client.mount();
+		return () => {
+			props.client.unmount();
+		};
+	}, [props.client]);
+	<QueryClientContext.Provider value={props.client}>{props.children}</QueryClientContext.Provider>
+}

package/src/QueryClientProvider.tsrx.d.ts

@@ -0,0 +1,10 @@
+// Type declaration for the .tsrx provider component (QueryClientProvider.tsrx).
+// It's a SPECIFIC module declaration (resolved by relative path), not an ambient
+// `declare module '*.tsrx'` — so it types only this module and doesn't pollute a
+// consumer's own .tsrx imports. The runtime resolves the real compiled .tsrx.
+import type { QueryClient } from '@tanstack/query-core';
+
+export declare const QueryClientProvider: (props: {
+	client: QueryClient;
+	children?: unknown;
+}) => unknown;

package/src/QueryErrorResetBoundary.tsrx

@@ -0,0 +1,21 @@
+import { useState, isChildrenBlock } from 'octane';
+import { QueryErrorResetBoundaryContext, createValue } from './errorResetBoundary.ts';
+
+// QueryErrorResetBoundary — provides a fresh reset coordinator to its subtree.
+// Place it above an error boundary; call `.reset()` from the boundary's retry so
+// the query refetches instead of immediately re-throwing. Children may be a
+// render prop receiving the boundary value — upstream's documented primary form:
+// `<QueryErrorResetBoundary>{({ reset }) => <ErrorBoundary onReset={reset}…/>}
+// </QueryErrorResetBoundary>` (react-query QueryErrorResetBoundary.tsx renders
+// `typeof children === 'function' ? children(value) : children`; octane
+// additionally excludes compiled children-blocks via isChildrenBlock).
+export function QueryErrorResetBoundary(props) @{
+	const [value] = useState(() => createValue());
+	const resolved =
+		typeof props.children === 'function' && !isChildrenBlock(props.children)
+			? props.children(value)
+			: props.children;
+	<QueryErrorResetBoundaryContext.Provider
+		value={value}
+	>{resolved}</QueryErrorResetBoundaryContext.Provider>
+}

package/src/QueryErrorResetBoundary.tsrx.d.ts

@@ -0,0 +1,4 @@
+// Type declaration for the .tsrx QueryErrorResetBoundary component (see
+// QueryErrorResetBoundary.tsrx). A specific module declaration (not an ambient
+// `*.tsrx` wildcard), so it doesn't pollute a consumer's own .tsrx imports.
+export declare const QueryErrorResetBoundary: (props: { children?: unknown }) => unknown;

package/src/context.ts

@@ -0,0 +1,29 @@
+import { createContext, useContext } from 'octane';
+import type { QueryClient } from '@tanstack/query-core';
+
+// The QueryClient context — read by useQuery/useMutation/useQueryClient. Mirrors
+// react-query's QueryClientContext.
+export const QueryClientContext = createContext<QueryClient | undefined>(undefined);
+
+// Resolve the client: an explicitly-passed one wins, else the context value.
+// `useContext` is keyed by context identity (not a per-call-site slot), so it's
+// safe to call from this binding code without a compiler-injected slot.
+export function resolveClient(queryClient: QueryClient | undefined): QueryClient {
+	const ctxClient = useContext(QueryClientContext);
+	const client = queryClient ?? ctxClient;
+	if (!client) {
+		throw new Error('No QueryClient set, use QueryClientProvider to set one');
+	}
+	return client;
+}
+
+// Signature matches @tanstack/react-query's QueryClientProvider.tsx.
+export function useQueryClient(queryClient?: QueryClient): QueryClient;
+
+export function useQueryClient(...args: unknown[]): QueryClient {
+	// Args are `[queryClient?, slot?]`; the slot (symbol) is appended by the
+	// compiler. An explicit client is the first non-symbol arg.
+	const queryClient =
+		args.length && typeof args[0] !== 'symbol' ? (args[0] as QueryClient) : undefined;
+	return resolveClient(queryClient);
+}

package/src/errorResetBoundary.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext } from 'octane';
+import type { QueryErrorResetBoundaryValue } from './types';
+
+export type { QueryErrorResetBoundaryValue };
+
+export function createValue(): QueryErrorResetBoundaryValue {
+	let isReset = false;
+	return {
+		clearReset: () => {
+			isReset = false;
+		},
+		reset: () => {
+			isReset = true;
+		},
+		isReset: () => isReset,
+	};
+}
+
+// The reset coordinator for error-boundary retries. While "reset", a thrown query
+// error is NOT re-thrown (so the boundary's retry refetches instead of looping).
+// The default value means: without a `<QueryErrorResetBoundary>`, `isReset()` is
+// always false — identical to having no boundary.
+export const QueryErrorResetBoundaryContext =
+	createContext<QueryErrorResetBoundaryValue>(createValue());
+
+export function useQueryErrorResetBoundary(): QueryErrorResetBoundaryValue {
+	return useContext(QueryErrorResetBoundaryContext);
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+// @octanejs/tanstack-query — TanStack Query for the octane renderer.
+//
+// Reuses @tanstack/query-core verbatim (QueryClient, observers, caches — all
+// framework-agnostic) and reimplements the React binding on octane's hooks. The
+// public surface matches @tanstack/react-query, so most query code works by
+// changing the import.
+export * from '@tanstack/query-core';
+
+export { useQuery } from './useQuery';
+export { useMutation } from './useMutation';
+export { useInfiniteQuery } from './useInfiniteQuery';
+export { useSuspenseQuery, useSuspenseInfiniteQuery } from './useSuspenseQuery';
+export { useSuspenseQueries } from './useSuspenseQueries';
+export { usePrefetchQuery, usePrefetchInfiniteQuery } from './usePrefetch';
+export { useQueries } from './useQueries';
+export { queryOptions } from './queryOptions';
+export { infiniteQueryOptions } from './infiniteQueryOptions';
+export { mutationOptions } from './mutationOptions';
+export { useIsFetching } from './useIsFetching';
+export { useMutationState, useIsMutating } from './useMutationState';
+export { useQueryClient, QueryClientContext } from './context';
+export { QueryClientProvider } from './QueryClientProvider.tsrx';
+export { HydrationBoundary } from './HydrationBoundary.tsrx';
+export { IsRestoringProvider, useIsRestoring } from './isRestoring';
+export { QueryErrorResetBoundary } from './QueryErrorResetBoundary.tsrx';
+export { useQueryErrorResetBoundary } from './errorResetBoundary';
+
+// The binding-level type surface (1:1 with @tanstack/react-query's exports).
+export type {
+	AnyUseBaseQueryOptions,
+	UseBaseQueryOptions,
+	UsePrefetchQueryOptions,
+	AnyUseQueryOptions,
+	UseQueryOptions,
+	AnyUseSuspenseQueryOptions,
+	UseSuspenseQueryOptions,
+	AnyUseInfiniteQueryOptions,
+	UseInfiniteQueryOptions,
+	AnyUseSuspenseInfiniteQueryOptions,
+	UseSuspenseInfiniteQueryOptions,
+	UseBaseQueryResult,
+	UseQueryResult,
+	UseSuspenseQueryResult,
+	DefinedUseQueryResult,
+	UseInfiniteQueryResult,
+	DefinedUseInfiniteQueryResult,
+	UseSuspenseInfiniteQueryResult,
+	AnyUseMutationOptions,
+	UseMutationOptions,
+	UseMutateFunction,
+	UseMutateAsyncFunction,
+	UseBaseMutationResult,
+	UseMutationResult,
+	QueryClientProviderProps,
+	HydrationBoundaryProps,
+	QueryErrorResetFunction,
+	QueryErrorIsResetFunction,
+	QueryErrorClearResetFunction,
+	QueryErrorResetBoundaryValue,
+	QueryErrorResetBoundaryFunction,
+	QueryErrorResetBoundaryProps,
+} from './types';
+export type {
+	DefinedInitialDataOptions,
+	UndefinedInitialDataOptions,
+	UnusedSkipTokenOptions,
+} from './queryOptions';
+export type {
+	DefinedInitialDataInfiniteOptions,
+	UndefinedInitialDataInfiniteOptions,
+	UnusedSkipTokenInfiniteOptions,
+} from './infiniteQueryOptions';
+export type { QueriesOptions, QueriesResults } from './queries-types';
+export type { SuspenseQueriesOptions, SuspenseQueriesResults } from './suspense-queries-types';

package/src/infiniteQueryOptions.ts

@@ -0,0 +1,94 @@
+// Verbatim port of @tanstack/react-query's infiniteQueryOptions.ts — a typed identity helper
+import type {
+	DataTag,
+	DefaultError,
+	InfiniteData,
+	InitialDataFunction,
+	NonUndefinedGuard,
+	OmitKeyof,
+	QueryKey,
+	SkipToken,
+} from '@tanstack/query-core';
+import type { UseInfiniteQueryOptions } from './types';
+
+export type UndefinedInitialDataInfiniteOptions<
+	TQueryFnData,
+	TError = DefaultError,
+	TData = InfiniteData<TQueryFnData>,
+	TQueryKey extends QueryKey = QueryKey,
+	TPageParam = unknown,
+> = UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
+	initialData?:
+		| undefined
+		| NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
+		| InitialDataFunction<NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>>;
+};
+
+export type UnusedSkipTokenInfiniteOptions<
+	TQueryFnData,
+	TError = DefaultError,
+	TData = InfiniteData<TQueryFnData>,
+	TQueryKey extends QueryKey = QueryKey,
+	TPageParam = unknown,
+> = OmitKeyof<
+	UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
+	'queryFn'
+> & {
+	queryFn?: Exclude<
+		UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>['queryFn'],
+		SkipToken | undefined
+	>;
+};
+
+export type DefinedInitialDataInfiniteOptions<
+	TQueryFnData,
+	TError = DefaultError,
+	TData = InfiniteData<TQueryFnData>,
+	TQueryKey extends QueryKey = QueryKey,
+	TPageParam = unknown,
+> = UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
+	initialData:
+		| NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
+		| (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
+		| undefined;
+};
+
+export function infiniteQueryOptions<
+	TQueryFnData,
+	TError = DefaultError,
+	TData = InfiniteData<TQueryFnData>,
+	TQueryKey extends QueryKey = QueryKey,
+	TPageParam = unknown,
+>(
+	options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
+): DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
+	queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
+};
+
+export function infiniteQueryOptions<
+	TQueryFnData,
+	TError = DefaultError,
+	TData = InfiniteData<TQueryFnData>,
+	TQueryKey extends QueryKey = QueryKey,
+	TPageParam = unknown,
+>(
+	options: UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
+): UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
+	queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
+};
+
+export function infiniteQueryOptions<
+	TQueryFnData,
+	TError = DefaultError,
+	TData = InfiniteData<TQueryFnData>,
+	TQueryKey extends QueryKey = QueryKey,
+	TPageParam = unknown,
+>(
+	options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
+): UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
+	queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
+};
+
+export function infiniteQueryOptions(options: unknown) {
+	return options;
+}

package/src/internal.ts

@@ -0,0 +1,115 @@
+// Shared internals for the binding hooks.
+import { shouldThrowError } from '@tanstack/query-core';
+
+// Derive a stable, distinct sub-slot from a wrapper's compiler-injected slot, so
+// a hook composing multiple base hooks gives each one its own identity. Tags are
+// namespaced per hook (e.g. ':oq:obs', ':ms:cb') to avoid cross-hook collisions.
+// Memoized: subSlot runs on EVERY hook call every render, and the naive form
+// pays a string concat + global symbol-registry lookup each time. The cache is
+// keyed by the slot symbol itself; the minted value is byte-identical to the
+// uncached Symbol.for result, so identity is preserved across HMR re-evals and
+// the per-package copies of this helper. Key universe is bounded: slots are
+// per-call-site module constants (never minted per render).
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+export function subSlot(slot: symbol | undefined, tag: string): symbol | undefined {
+	if (slot === undefined) return undefined;
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let sym = byTag.get(tag);
+	if (sym === undefined) byTag.set(tag, (sym = Symbol.for((slot.description ?? '') + ':' + tag)));
+	return sym;
+}
+
+// Split the compiler-injected trailing slot off a hook's runtime args, returning
+// the user args (everything before it) and the slot.
+export function splitSlot(args: any[]): [any[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	return [slot !== undefined ? args.slice(0, -1) : args, slot];
+}
+
+// react-query's default suspense throwOnError: only throw if there's no data.
+export const defaultThrowOnError = (_error: unknown, query: any): boolean =>
+	query.state.data === undefined;
+
+// react-query's ensureSuspenseTimers: a suspense query gets a >=1s staleTime/gcTime
+// floor so it can't immediately refetch and re-trigger the fallback in a loop.
+export function ensureSuspenseTimers(defaultedOptions: any): void {
+	if (defaultedOptions.suspense) {
+		const MIN = 1000;
+		const clamp = (value: any) => (value === 'static' ? value : Math.max(value ?? MIN, MIN));
+		const orig = defaultedOptions.staleTime;
+		defaultedOptions.staleTime =
+			typeof orig === 'function' ? (...args: any[]) => clamp(orig(...args)) : clamp(orig);
+		if (typeof defaultedOptions.gcTime === 'number') {
+			defaultedOptions.gcTime = Math.max(defaultedOptions.gcTime, MIN);
+		}
+	}
+}
+
+// prevent-error-boundary-retry: when a query opts into throwing, don't retry on
+// mount so an already-errored cached query re-throws immediately — UNLESS the
+// reset boundary has been reset, in which case a retry is expected.
+export function ensurePreventErrorBoundaryRetry(
+	options: any,
+	errorResetBoundary: { isReset: () => boolean },
+	query: any,
+): void {
+	const throwOnError =
+		query?.state.error && typeof options.throwOnError === 'function'
+			? shouldThrowError(options.throwOnError, [query.state.error, query])
+			: options.throwOnError;
+	if (options.suspense || options.experimental_prefetchInRender || throwOnError) {
+		if (!errorResetBoundary.isReset()) {
+			options.retryOnMount = false;
+		}
+	}
+}
+
+export const shouldSuspend = (defaultedOptions: any, result: any): boolean =>
+	defaultedOptions?.suspense && result.isPending;
+
+// A pending result that will actually fetch (not blocked by persistence restore).
+export const willFetch = (result: any, isRestoring: boolean): boolean =>
+	result.isLoading && result.isFetching && !isRestoring;
+
+// react-query's suspense fetch: kick the optimistic fetch and — CRUCIALLY — clear
+// the reset boundary on error. Without the clearReset, a boundary reset→retry
+// that fails AGAIN leaves `isReset()` true at replay, `getHasError` returns
+// false, and a suspense component falls through to render with undefined data
+// instead of re-throwing to the boundary. The returned promise resolves even on
+// error (the replay surfaces the error through the error-boundary throw).
+export function fetchOptimistic(
+	defaultedOptions: any,
+	observer: any,
+	errorResetBoundary: { clearReset: () => void },
+): Promise<unknown> {
+	return observer.fetchOptimistic(defaultedOptions).catch(() => {
+		errorResetBoundary.clearReset();
+	});
+}
+
+// react-query's getHasError: only throw if the query errored, the boundary isn't
+// reset, the query isn't refetching, and the options opt into throwing.
+export function getHasError({
+	result,
+	errorResetBoundary,
+	throwOnError,
+	query,
+	suspense,
+}: {
+	result: any;
+	errorResetBoundary: { isReset: () => boolean };
+	throwOnError: any;
+	query: any;
+	suspense: any;
+}): boolean {
+	return (
+		result.isError &&
+		!errorResetBoundary.isReset() &&
+		!result.isFetching &&
+		query &&
+		((suspense && result.data === undefined) ||
+			shouldThrowError(throwOnError, [result.error, query]))
+	);
+}

package/src/isRestoring.ts

@@ -0,0 +1,13 @@
+import { createContext, useContext } from 'octane';
+
+// IsRestoring — true while a persisted client is being restored from storage. While
+// restoring, queries read the cache but don't subscribe/fetch (they wait for the
+// restore to finish). Defaults to false, so without a provider it's inert.
+export const IsRestoringContext = createContext(false);
+
+export function useIsRestoring(): boolean {
+	return useContext(IsRestoringContext);
+}
+
+// `<IsRestoringProvider value={true}>…` — octane's built-in context Provider.
+export const IsRestoringProvider = IsRestoringContext.Provider;