houdini-react 2.0.0-next.38 → 2.0.0-next.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "houdini-react",
-  "version": "2.0.0-next.38",
+  "version": "2.0.0-next.40",
   "description": "The React plugin for houdini",
   "keywords": [
     "typescript",
@@ -81,13 +81,13 @@
     }
   },
   "optionalDependencies": {
-    "houdini-react-darwin-x64": "2.0.0-next.38",
-    "houdini-react-darwin-arm64": "2.0.0-next.38",
-    "houdini-react-linux-x64": "2.0.0-next.38",
-    "houdini-react-linux-arm64": "2.0.0-next.38",
-    "houdini-react-win32-x64": "2.0.0-next.38",
-    "houdini-react-win32-arm64": "2.0.0-next.38",
-    "houdini-react-wasm": "2.0.0-next.38"
+    "houdini-react-darwin-x64": "2.0.0-next.40",
+    "houdini-react-darwin-arm64": "2.0.0-next.40",
+    "houdini-react-linux-x64": "2.0.0-next.40",
+    "houdini-react-linux-arm64": "2.0.0-next.40",
+    "houdini-react-win32-x64": "2.0.0-next.40",
+    "houdini-react-win32-arm64": "2.0.0-next.40",
+    "houdini-react-wasm": "2.0.0-next.40"
   },
   "scripts": {
     "compile": "scripts build-go",

package/postInstall.js

@@ -5,7 +5,7 @@ const https = require('https')
 const child_process = require('child_process')
 
 // Adjust the version you want to install. You can also make this dynamic.
-const BINARY_DISTRIBUTION_VERSION = '2.0.0-next.38'
+const BINARY_DISTRIBUTION_VERSION = '2.0.0-next.40'
 
 // Windows binaries end with .exe so we need to special case them.
 const binaryName = process.platform === 'win32' ? 'houdini-react.exe' : 'houdini-react'

package/runtime/Link.tsx

@@ -59,16 +59,22 @@ type _ParamsForRoute<H extends string> = [_PageForRoute<H>] extends [never]
 export type LinkProps<H extends RouteHrefs | _ExternalHref = RouteHrefs | _ExternalHref> = Omit<
 	DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>,
 	'href'
-> & { to: H; preload?: boolean | 'data' | 'component' | 'page' } & _ParamsForRoute<H>
+> & {
+	to: H
+	disabled?: boolean
+	preload?: boolean | 'data' | 'component' | 'page'
+} & _ParamsForRoute<H>
 
 export function Link<H extends RouteHrefs | _ExternalHref>({
 	to,
 	params,
+	disabled,
 	preload,
 	...rest
 }: LinkProps<H>): React.ReactElement {
-	const href =
-		params != null
+	const href = disabled
+		? undefined
+		: params != null
 			? resolveHref(to as string, params as Record<string, string | number | boolean>)
 			: (to as string)
 	return React.createElement('a', { ...rest, href, 'data-houdini-preload': preload })

package/runtime/hooks/useDocumentHandle.ts

@@ -33,6 +33,9 @@ export function useDocumentHandle<
 }): DocumentHandle<_Artifact, _Data, _Input> & { fetch: FetchFn<_Data, _Input> } {
 	const [forwardPending, setForwardPending] = React.useState(false)
 	const [backwardPending, setBackwardPending] = React.useState(false)
+	// Stable cursor stacks for SinglePage pagination — must survive re-renders caused by store updates
+	const previousCursorsRef = React.useRef<(string | null)[]>([])
+	const nextCursorsRef = React.useRef<(string | null)[]>([])
 	const location = useLocation()
 
 	// grab the current session value
@@ -127,6 +130,8 @@ export function useDocumentHandle<
 				getState: () => storeValue.data,
 				getVariables: () => storeValue.variables!,
 				fetch: fetchQuery,
+				previousCursors: previousCursorsRef.current,
+				nextCursors: nextCursorsRef.current,
 				fetchUpdate: (args, updates) => {
 					return paginationObserver!.send({
 						...args,

package/runtime/hooks/useFragmentHandle.ts

@@ -1,12 +1,15 @@
+import { extractPageInfo, cursorHandlers, offsetHandlers } from 'houdini/runtime'
 import type {
 	GraphQLObject,
 	FragmentArtifact,
 	QueryArtifact,
 	GraphQLVariables,
+	FetchFn,
 } from 'houdini/runtime'
+import * as React from 'react'
 
-import { useDocumentHandle, type DocumentHandle } from './useDocumentHandle.js'
-import { useDocumentStore } from './useDocumentStore.js'
+import { useClient, useSession } from '../routing/Router.js'
+import type { DocumentHandle } from './useDocumentHandle.js'
 import { fragmentReference, useFragment } from './useFragment.js'
 
 // useFragmentHandle is just like useFragment except it also returns an imperative handle
@@ -22,25 +25,167 @@ export function useFragmentHandle<
 	document: { artifact: FragmentArtifact; refetchArtifact?: QueryArtifact }
 ): any {
 	// get the fragment values
-	const data = useFragment<_Data, _ReferenceType, _Input>(reference, document)
+	const fragmentData = useFragment<_Data, _ReferenceType, _Input>(reference, document)
 
 	// look at the fragment reference to get the variables
 	const { variables } = fragmentReference<_Data, _Input, _ReferenceType>(reference, document)
 
-	// use the pagination fragment for meta data if it exists.
-	// if we pass this a fragment artifact, it won't add any data
-	const [handleValue, handleObserver] = useDocumentStore<_Data, _Input>({
-		artifact: document.refetchArtifact ?? document.artifact,
-	})
-	const handle = useDocumentHandle<_PaginationArtifact, _Data, _Input>({
-		observer: handleObserver,
-		storeValue: handleValue,
-		artifact: document.refetchArtifact ?? document.artifact,
-	})
+	const client = useClient()
+	const [session] = useSession()
+
+	const [forwardPending, setForwardPending] = React.useState(false)
+	const [backwardPending, setBackwardPending] = React.useState(false)
+
+	// Stable cursor stacks for SinglePage pagination — must survive re-renders
+	const previousCursorsRef = React.useRef<(string | null)[]>([])
+	const nextCursorsRef = React.useRef<(string | null)[]>([])
+
+	const refetchArtifact = document.refetchArtifact as QueryArtifact | undefined
+	const refetchPath = refetchArtifact?.refetch?.path
+
+	// Dedicated observer for pagination queries — separate from the fragment observer.
+	// cursorHandlers derives entity variables (e.g. { id }) and artifact defaults
+	// automatically via the type config, so no manual variable extraction is needed here.
+	const paginationObserver = React.useMemo(() => {
+		if (!refetchArtifact?.refetch?.paginated) return null
+		return client.observe<_Data, _Input>({ artifact: refetchArtifact })
+	}, [refetchArtifact?.name])
+
+	// Subscribe to the pagination observer so React re-renders whenever a new page is fetched
+	// or served from cache (CacheOrNetwork). The fragment store subscription only watches the
+	// initial page's cache key; the observer is the live source of truth for SinglePage
+	// pagination where each page lives at its own per-cursor cache key.
+	const subscribeToObserver = React.useCallback(
+		(onChange: () => void) => {
+			if (!paginationObserver) return () => {}
+			return paginationObserver.subscribe(onChange)
+		},
+		[paginationObserver]
+	)
+	const getObserverSnapshot = React.useCallback(
+		() => paginationObserver?.state.data ?? null,
+		[paginationObserver]
+	)
+	const paginationData = React.useSyncExternalStore(
+		subscribeToObserver,
+		getObserverSnapshot,
+		getObserverSnapshot
+	)
+
+	// Extract entity-level data from the pagination query response. For Node targetType
+	// the response is { node: EntityData }; we take the first root field to handle any type.
+	// Guard against partial cache hits (artifact has partial:true): only use the entity once the
+	// paginated connection field at refetch.path[0] is actually present in the response.
+	const paginationEntityData = React.useMemo<_Data | null>(() => {
+		if (!paginationData || !refetchArtifact?.selection?.fields) return null
+		const rootField = Object.keys(refetchArtifact.selection.fields)[0]
+		if (!rootField) return null
+		const entity = (paginationData as any)[rootField]
+		if (!entity) return null
+		const path = refetchArtifact.refetch?.path
+		if (path && path.length > 0 && (entity as any)[path[0]] == null) {
+			return null
+		}
+		return entity as _Data
+	}, [paginationData, refetchArtifact])
+
+	const isSinglePage = refetchArtifact?.refetch?.mode === 'SinglePage'
+
+	// For SinglePage: use the pagination observer's entity data (each page has its own
+	// cache key) once a page fetch has landed. For Infinite: always use fragmentData,
+	// which reads accumulated pages from cache via the fragment's cache subscription.
+	const displayData =
+		isSinglePage && paginationEntityData !== null ? paginationEntityData : fragmentData
+
+	const wrapLoad = <_Result>(
+		setLoading: (val: boolean) => void,
+		fn: (value: any) => Promise<_Result>
+	) => {
+		return async (value: any) => {
+			setLoading(true)
+			let err: Error | null = null
+			let result: _Result | null = null
+			try {
+				result = await fn(value)
+			} catch (e) {
+				err = e as Error
+			}
+			setLoading(false)
+			if (err && err.name !== 'AbortError') throw err
+			return result
+		}
+	}
+
+	const handle = React.useMemo(() => {
+		if (!refetchArtifact?.refetch?.paginated || !paginationObserver) return null
+
+		const fetchFn: FetchFn<_Data, _Input> = (args) => {
+			return paginationObserver.send({ ...args, session })
+		}
+
+		const fetchUpdate = (args: any, updates: string[]) => {
+			return paginationObserver.send({
+				...args,
+				cacheParams: {
+					...args?.cacheParams,
+					disableSubscriptions: true,
+					applyUpdates: updates,
+				},
+				session,
+			})
+		}
+
+		if (refetchArtifact.refetch!.method === 'cursor') {
+			const handlers = cursorHandlers<_Data, _Input>({
+				artifact: refetchArtifact,
+				getState: () => displayData as _Data | null,
+				// Use the observer's own variable state so cursor history is preserved
+				// across page navigations without manual tracking in the hook.
+				getVariables: () =>
+					(paginationObserver.state.variables ?? variables) as NonNullable<_Input>,
+				fetch: fetchFn,
+				fetchUpdate,
+				getSession: async () => session,
+				previousCursors: previousCursorsRef.current,
+				nextCursors: nextCursorsRef.current,
+			})
+
+			return {
+				loadNext: wrapLoad(setForwardPending, handlers.loadNextPage),
+				loadNextPending: forwardPending,
+				loadPrevious: wrapLoad(setBackwardPending, handlers.loadPreviousPage),
+				loadPreviousPending: backwardPending,
+				pageInfo: refetchPath
+					? extractPageInfo(displayData as GraphQLObject, refetchPath)
+					: null,
+			}
+		}
+
+		if (refetchArtifact.refetch!.method === 'offset') {
+			const handlers = offsetHandlers({
+				artifact: refetchArtifact,
+				getState: () => displayData as _Data | null,
+				getVariables: () =>
+					(paginationObserver.state.variables ?? variables) as NonNullable<_Input>,
+				storeName: refetchArtifact.name,
+				fetch: fetchFn,
+				fetchUpdate: async (args: any, updates = ['append']) =>
+					fetchUpdate(args, updates) as any,
+				getSession: async () => session,
+			})
+
+			return {
+				loadNext: wrapLoad(setForwardPending, handlers.loadNextPage),
+				loadNextPending: forwardPending,
+			}
+		}
+
+		return null
+	}, [refetchArtifact, paginationObserver, displayData, session, forwardPending, backwardPending])
 
 	return {
 		...handle,
 		variables,
-		data,
+		data: displayData,
 	}
 }

package/runtime/hooks/useQueryHandle.ts

@@ -107,7 +107,11 @@ export function useQueryHandle<
 		// when it resolves the cached value will be updated
 		// and it will be picked up in the next render
 		let resolve: () => void = () => {}
-		const loadPromise = new Promise<void>((r) => (resolve = r))
+		let reject: (reason?: any) => void = () => {}
+		const loadPromise = new Promise<void>((res, rej) => {
+			resolve = res
+			reject = rej
+		})
 
 		const suspenseUnit: QuerySuspenseUnit<_Data, _Input> = {
 			// biome-ignore lint/suspicious/noThenProperty: suspense protocol requires a thenable
@@ -141,6 +145,10 @@ export function useQueryHandle<
 
 				suspenseUnit.resolve()
 			})
+			.catch((err) => {
+				promiseCache.delete(identifier)
+				reject(err)
+			})
 		suspenseTracker.current = true
 		throw suspenseUnit
 	}

package/runtime/index.tsx

@@ -6,7 +6,23 @@ import manifest from './manifest.js'
 import { Router as RouterImpl, type RouterCache, RouterContextProvider } from './routing/index.js'
 
 export * from './hooks/index.js'
-export { router_cache, useCache, useSession, useLocation, useRoute } from './routing/index.js'
+export {
+	router_cache,
+	useCache,
+	useSession,
+	useLocation,
+	useRoute,
+	useCurrentVariables,
+	notFound,
+	unauthorized,
+	forbidden,
+	httpError,
+	redirect,
+	isRoutingError,
+	isApiError,
+	RoutingError,
+	RedirectError,
+} from './routing/index.js'
 export * from './Link.js'
 
 export function Router({

package/runtime/routing/Router.tsx

@@ -7,16 +7,17 @@ import configFile from '$houdini/runtime/imports/config'
 import { deepEquals } from 'houdini/runtime'
 import type { LRUCache } from 'houdini/runtime'
 import { marshalSelection, marshalInputs } from 'houdini/runtime'
-import { find_match } from 'houdini/router/match'
+import { find_match, find_prefix_match } from 'houdini/router/match'
 import type { RouterManifest, RouterPageManifest } from 'houdini/router/types'
 import React from 'react'
-import { useContext } from 'react'
+import { useContext, useEffect } from 'react'
 
 import { type DocumentHandle, useDocumentHandle } from '../hooks/useDocumentHandle.js'
 import { useDocumentStore } from '../hooks/useDocumentStore.js'
 import { type SuspenseCache, suspense_cache } from './cache.js'
+import { GraphQLErrors, RoutingError, StatusContext } from './errors.js'
 
-type PageComponent = React.ComponentType<{ url: string }>
+type PageComponent = React.ComponentType<{ url: string; children?: React.ReactNode }>
 
 const PreloadWhich = {
 	component: 'component',
@@ -55,9 +56,12 @@ export function Router({
 
 	// find the matching page for the current route
 	const [page, variables] = find_match(configFile, manifest, currentURL)
-	// if we dont have a page, its a 404
-	if (!page) {
-		throw new Error('404')
+	const is404 = !page
+	// When no exact match, find the deepest prefix-matching page to render
+	// its layout chain with NotFoundGate throwing inside the appropriate boundary.
+	const targetPage = page ?? find_prefix_match(manifest, currentURL)
+	if (!targetPage) {
+		throw new RoutingError(404)
 	}
 
 	// the only time this component will directly suspend (instead of one of its children)
@@ -67,14 +71,14 @@ export function Router({
 	// load the page assets (source, artifacts, data). this will suspend if the component is not available yet
 	// this hook embeds pending requests in context so that the component can suspend if necessary14
 	const { loadData, loadComponent } = usePageData({
-		page,
+		page: targetPage,
 		variables,
 		assetPrefix,
 		injectToStream,
 	})
 	// if we get this far, it's safe to load the component
 	const { component_cache, data_cache, ssr_signals } = useRouterContext()
-	const PageComponent = component_cache.get(page.id)!
+	const PageComponent = component_cache.get(targetPage.id)!
 
 	// if we got this far then we're past suspense
 
@@ -150,7 +154,15 @@ export function Router({
 					params: variables ?? {},
 				}}
 			>
-				<PageComponent url={currentURL} key={page.id} />
+				<Is404Context.Provider value={is404}>
+					{is404 ? (
+						<NotFoundLayoutBoundary key={targetPage.id}>
+							<PageComponent url={currentURL} key={targetPage.id + '__404'} />
+						</NotFoundLayoutBoundary>
+					) : (
+						<PageComponent url={currentURL} key={targetPage.id} />
+					)}
+				</Is404Context.Provider>
 			</LocationContext.Provider>
 		</VariableContext.Provider>
 	)
@@ -159,6 +171,14 @@ export function Router({
 // export the location information in context
 export const useLocation = () => useContext(LocationContext)
 
+export const ClientRedirect = ({ to }: { to: string }) => {
+	const { goto } = useLocation()
+	useEffect(() => {
+		goto(to)
+	}, [to])
+	return null
+}
+
 /**
  * usePageData is responsible for kicking off the network requests necessary to render the page.
  * This includes loading the artifact, the component source, and any query results. This hook
@@ -240,9 +260,11 @@ function usePageData({
 				.then(async () => {
 					data_cache.set(id, observer)
 
-					// if there is an error, we need to reject the promise
+					// if there is an error, signal completion (the error is visible via
+					// useQueryResult reading observer.state.errors) and clean up
 					if (observer.state.errors && observer.state.errors.length > 0) {
-						reject(observer.state.errors.map((e) => e.message).join('\n'))
+						ssr_signals.delete(id)
+						resolve()
 						return
 					}
 
@@ -340,6 +362,9 @@ function usePageData({
 				})
 				.catch((err) => {
 					ssr_signals.delete(id)
+					if (err?.name === 'AbortError') {
+						return
+					}
 					reject(err)
 				})
 		})
@@ -432,18 +457,11 @@ function usePageData({
 		}
 	}
 
-	// if we don't have the component then we need to load it, save it in the cache, and
-	// then suspend with a promise that will resolve once its in cache
 	async function loadComponent(targetPage: RouterPageManifest<ComponentType>) {
-		// if we already have the component, don't do anything
 		if (component_cache.has(targetPage.id)) {
 			return
 		}
-
-		// load the component and then save it in the cache
 		const mod = await targetPage.component()
-
-		// save the component in the cache
 		component_cache.set(targetPage.id, mod.default)
 	}
 
@@ -651,7 +669,7 @@ export function useQueryResult<_Data extends GraphQLObject, _Input extends Graph
 
 	// if there is an error in the response we need to throw to the nearest boundary
 	if (errors && errors.length > 0) {
-		throw new Error(JSON.stringify(errors))
+		throw new GraphQLErrors(errors)
 	}
 	// create the handle that we will use to interact with the store
 	const handle = useDocumentHandle({
@@ -853,6 +871,51 @@ export function router_cache({
 	return result
 }
 
+// Catches RoutingErrors that escape all HoudiniErrorBoundary instances during prefix-match
+// (is404) rendering, preventing an infinite loop when a layout itself throws notFound().
+class NotFoundLayoutBoundary extends React.Component<
+	{ children: React.ReactNode },
+	{ caught: boolean }
+> {
+	static contextType = StatusContext
+	declare context: React.ContextType<typeof StatusContext>
+
+	constructor(props: { children: React.ReactNode }) {
+		super(props)
+		this.state = { caught: false }
+	}
+
+	static getDerivedStateFromError(error: unknown) {
+		if (error instanceof RoutingError) {
+			return { caught: true }
+		}
+		return null
+	}
+
+	componentDidCatch(error: Error): void {
+		if (error instanceof RoutingError && this.context) {
+			this.context.status = error.status
+		}
+	}
+
+	render() {
+		if (this.state.caught) {
+			return null
+		}
+		return this.props.children
+	}
+}
+
+export const Is404Context = React.createContext(false)
+
+export function NotFoundGate({ children }: { children: React.ReactNode }) {
+	const is404 = React.useContext(Is404Context)
+	if (is404) {
+		throw new RoutingError(404)
+	}
+	return <>{children}</>
+}
+
 const PageContext = React.createContext<{ params: Record<string, any> }>({ params: {} })
 
 export function PageContextProvider({

package/runtime/routing/cache.ts

@@ -31,7 +31,10 @@ export class SuspenseCache<_Data> extends LRUCache<_Data> {
 		})
 	}
 
-	// TODO: reject?
+	override clear() {
+		super.clear()
+		this.#callbacks.clear()
+	}
 
 	set(key: string, value: _Data) {
 		// perform the set like normal

package/runtime/routing/errors.tsx

@@ -0,0 +1,145 @@
+import type { GraphQLError } from 'houdini/runtime'
+import React from 'react'
+
+export class GraphQLErrors extends Error {
+	graphqlErrors: GraphQLError[]
+
+	constructor(errors: GraphQLError[]) {
+		super(errors.map((e) => e.message).join('\n'))
+		this.name = 'GraphQLErrors'
+		this.graphqlErrors = errors
+	}
+}
+
+let _currentSegment: string | undefined
+
+export function setCurrentSegment(id: string | undefined): void {
+	_currentSegment = id
+}
+
+function getCurrentSegment(): string | undefined {
+	return _currentSegment
+}
+
+export class RoutingError extends Error {
+	status: number
+	segment: string | undefined
+
+	constructor(status: number) {
+		super(`Routing error: ${status}`)
+		this.name = 'RoutingError'
+		this.status = status
+		this.segment = getCurrentSegment()
+	}
+}
+
+export class RedirectError extends Error {
+	status: number
+	location: string
+
+	constructor(status: number, location: string) {
+		super(`Redirect: ${status} ${location}`)
+		this.name = 'RedirectError'
+		this.status = status
+		this.location = location
+	}
+}
+
+export function isRoutingError(error: unknown): error is RoutingError {
+	return error instanceof RoutingError
+}
+
+export function isApiError(error: unknown): error is GraphQLErrors {
+	return error instanceof GraphQLErrors
+}
+
+export function notFound(): never {
+	throw new RoutingError(404)
+}
+
+export function unauthorized(): never {
+	throw new RoutingError(401)
+}
+
+export function forbidden(): never {
+	throw new RoutingError(403)
+}
+
+export function httpError(status: number): never {
+	throw new RoutingError(status)
+}
+
+export function redirect(status: 300 | 301 | 302 | 303 | 307 | 308, location: string): never {
+	throw new RedirectError(status, location)
+}
+
+// Mutable ref passed from the server renderer so that a synchronous RoutingError
+// or redirect() can propagate the correct HTTP status/location before streaming.
+export const StatusContext = React.createContext<{ status: number; location?: string } | null>(null)
+
+type HoudiniErrorBoundaryProps = {
+	errorView: React.ComponentType<{
+		errors: Array<Error | GraphQLError>
+		children: React.ReactNode
+	}>
+	children: React.ReactNode
+}
+
+type HoudiniErrorBoundaryState = {
+	hasError: boolean
+	errors: Array<Error | GraphQLError>
+}
+
+export class HoudiniErrorBoundary extends React.Component<
+	HoudiniErrorBoundaryProps,
+	HoudiniErrorBoundaryState
+> {
+	static contextType = StatusContext
+	declare context: React.ContextType<typeof StatusContext>
+
+	constructor(
+		props: HoudiniErrorBoundaryProps,
+		context: React.ContextType<typeof StatusContext>
+	) {
+		super(props, context)
+		// Second-pass SSR: statusRef is pre-set to an error status by on_render after the first
+		// render threw. Start in error state immediately so children never render (and never throw).
+		if (typeof window === 'undefined' && context && context.status >= 400) {
+			this.state = {
+				hasError: true,
+				errors: [new RoutingError(context.status)],
+			}
+		} else {
+			this.state = { hasError: false, errors: [] }
+		}
+	}
+
+	static getDerivedStateFromError(error: unknown): HoudiniErrorBoundaryState {
+		if (error instanceof GraphQLErrors) {
+			return { hasError: true, errors: error.graphqlErrors }
+		}
+		return {
+			hasError: true,
+			errors: [error instanceof Error ? error : new Error(String(error))],
+		}
+	}
+
+	componentDidCatch(error: Error): void {
+		if (this.context) {
+			if (error instanceof RoutingError) {
+				this.context.status = error.status
+			} else if (error instanceof RedirectError) {
+				this.context.status = error.status
+				this.context.location = error.location
+			}
+		}
+	}
+
+	render() {
+		if (this.state.hasError) {
+			const ErrorView = this.props.errorView
+			return <ErrorView errors={this.state.errors}>{this.props.children}</ErrorView>
+		}
+		return this.props.children
+	}
+}

package/runtime/routing/index.ts

@@ -1,2 +1,17 @@
 export * from './Router.js'
 export { type SuspenseCache, suspense_cache } from './cache.js'
+export {
+	HoudiniErrorBoundary,
+	GraphQLErrors,
+	RoutingError,
+	RedirectError,
+	notFound,
+	unauthorized,
+	forbidden,
+	httpError,
+	redirect,
+	isRoutingError,
+	isApiError,
+	StatusContext,
+	setCurrentSegment,
+} from './errors.js'