houdini-react 2.0.1 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "houdini-react",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "The React plugin for houdini",
   "keywords": [
     "typescript",
@@ -81,13 +81,13 @@
     }
   },
   "optionalDependencies": {
-    "houdini-react-darwin-x64": "2.0.1",
-    "houdini-react-darwin-arm64": "2.0.1",
-    "houdini-react-linux-x64": "2.0.1",
-    "houdini-react-linux-arm64": "2.0.1",
-    "houdini-react-win32-x64": "2.0.1",
-    "houdini-react-win32-arm64": "2.0.1",
-    "houdini-react-wasm": "2.0.1"
+    "houdini-react-darwin-x64": "2.0.2",
+    "houdini-react-darwin-arm64": "2.0.2",
+    "houdini-react-linux-x64": "2.0.2",
+    "houdini-react-linux-arm64": "2.0.2",
+    "houdini-react-win32-x64": "2.0.2",
+    "houdini-react-win32-arm64": "2.0.2",
+    "houdini-react-wasm": "2.0.2"
   },
   "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.1'
+const BINARY_DISTRIBUTION_VERSION = '2.0.2'
 
 // Windows binaries end with .exe so we need to special case them.
 const binaryName = process.platform === 'win32' ? 'houdini-react.exe' : 'houdini-react'

package/runtime/contexts.ts

@@ -0,0 +1,54 @@
+import { createContext } from 'react'
+
+import type { Goto } from './routes.js'
+import type { RouterContext } from './routing/Router.js'
+
+// All of the runtime's React contexts are defined in this module on purpose.
+//
+// A React context is a module-level singleton: provider and consumer must hold
+// the *same* object returned by createContext(). When a context is created
+// inside a module that also exports components/hooks (like Router.tsx), Vite's
+// dev server re-evaluates that module on an HMR update (for example when codegen
+// rewrites a neighboring generated unit, or when react-refresh falls back to a
+// full module re-run). Each re-evaluation mints a brand-new context object, and
+// if a consumer rebinds to the new one while the still-mounted provider holds
+// the old one, useContext() reads a context the provider never populated and
+// throws "Could not find router context".
+//
+// This module imports only `react` at runtime (everything else is `import type`,
+// erased at build time), so it is a pure leaf in the dependency graph. Route
+// edits never re-evaluate it, so these context objects keep a stable identity
+// across granular HMR updates. We deliberately avoid a globalThis registry to
+// pin identity: multiple independent Router contexts can legitimately coexist in
+// one process (for example across Astro islands), and a global singleton would
+// wrongly collapse them into one.
+
+export const RouterContextObject = createContext<RouterContext | null>(null)
+
+export const LocationContext = createContext<{
+	pathname: string
+	params: Record<string, any>
+	// the parsed query string of the current url (declared search params coerced to
+	// their scalar type, other keys raw; repeated keys are arrays).
+	search: Record<string, any>
+	// a function to imperatively navigate to a url
+	goto: Goto
+}>({
+	pathname: '',
+	params: {},
+	search: {},
+	goto: () => {},
+})
+
+export const Is404Context = createContext(false)
+
+export const PageContext = createContext<{ params: Record<string, any> }>({ params: {} })
+
+// 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 = createContext<{ status: number; location?: string } | null>(null)
+
+// FormStatusContext carries the nearest <Form>'s pending state to useMutationFormStatus(),
+// the no-prop-drilling ergonomic of React's useFormStatus (which only tracks function-action
+// submissions, so it can't see our forms).
+export const FormStatusContext = createContext<{ pending: boolean }>({ pending: false })

package/runtime/hooks/useMutationForm.tsx

@@ -3,6 +3,7 @@ import type { MutationArtifact, GraphQLObject, GraphQLVariables } from 'houdini/
 import { coerceFormData, interpolateRedirect } from 'houdini/runtime'
 import React from 'react'
 
+import { FormStatusContext } from '../contexts.js'
 import { useSession, useRoute, useFormResult, useFormToken } from '../routing/Router.js'
 import { useDocumentStore } from './useDocumentStore.js'
 
@@ -40,10 +41,9 @@ export type MutationForm<_Result = any> = {
 	pending: boolean
 }
 
-// FormStatusContext carries the nearest <Form>'s pending state to useMutationFormStatus(),
-// the no-prop-drilling ergonomic of React's useFormStatus (which only tracks function-action
-// submissions, so it can't see our forms).
-const FormStatusContext = React.createContext<{ pending: boolean }>({ pending: false })
+// FormStatusContext (defined in ../contexts.js) carries the nearest <Form>'s pending state
+// to useMutationFormStatus(), the no-prop-drilling ergonomic of React's useFormStatus (which
+// only tracks function-action submissions, so it can't see our forms).
 
 /** useMutationFormStatus reads the pending state of the nearest <Form> from a child. */
 export function useMutationFormStatus(): { pending: boolean } {

package/runtime/hydration.tsx

@@ -26,6 +26,7 @@ declare global {
 		__houdini__auth_url__?: string | null
 		__houdini__pending_artifacts__?: Record<string, QueryArtifact>
 		__houdini__pending_data__?: Record<string, any>
+		__houdini__pending_errors__?: Record<string, any>
 		__houdini__pending_variables__?: Record<string, GraphQLVariables>
 		__houdini__pending_cache__?: any[]
 		__houdini__nav_caches__?: RouterCache
@@ -127,6 +128,26 @@ export function hydrate_page(
 		}
 	}
 
+	// an @loading query that errored streams its errors here (its data is null, so it has no
+	// pending_data entry above). build a store that already carries the errors so the page's
+	// useQueryResult throws to the error boundary instead of hanging on the loading frame.
+	for (const [artifactName, errors] of Object.entries(window.__houdini__pending_errors__ ?? {})) {
+		const artifact = window.__houdini__pending_artifacts__?.[artifactName]
+		if (!artifact) {
+			continue
+		}
+		initialArtifacts[artifactName] = artifact
+		const variables = window.__houdini__pending_variables__?.[artifactName]
+		const observer = window.__houdini__client__!.observe({
+			artifact,
+			cache: window.__houdini__cache__,
+			initialVariables: variables,
+		})
+		observer.update((state) => ({ ...state, fetching: false, errors }))
+		initialData[artifactName] = observer
+	}
+	window.__houdini__pending_errors__ = {}
+
 	if (!window.__houdini__nav_caches__) {
 		window.__houdini__nav_caches__ = router_cache({
 			pending_queries: pendingQueries,

package/runtime/routing/Router.tsx

@@ -1,4 +1,4 @@
-import type { GraphQLObject, GraphQLVariables } from 'houdini/runtime'
+import type { GraphQLError, GraphQLObject, GraphQLVariables } from 'houdini/runtime'
 import type { QueryArtifact } from 'houdini/runtime'
 import type { Cache } from 'houdini/runtime/cache'
 import type { DocumentStore, HoudiniClient } from 'houdini/runtime/client'
@@ -13,6 +13,13 @@ import type { RouterManifest, RouterPageManifest } from 'houdini/router/types'
 import React from 'react'
 import { useContext, useEffect } from 'react'
 
+import {
+	RouterContextObject as Context,
+	LocationContext,
+	Is404Context,
+	PageContext,
+} from '../contexts.js'
+import { escapeScriptTag } from '../escape.js'
 import { buildHref, scalarUnmarshalers, unmarshalScalars } from '../resolve-href.js'
 import type { Goto } from '../routes.js'
 import { type DocumentHandle, useDocumentHandle } from '../hooks/useDocumentHandle.js'
@@ -285,6 +292,64 @@ function usePageData({
 			? data_cache.get(artifact.name)!
 			: client.observe({ artifact, cache })
 
+		// surface a query error to the client. an @loading query streams its result while the
+		// document is still open, so on the initial SSR load the client is parked on the loading
+		// frame waiting for this query's pending signal to resolve. unlike the success path the
+		// store carries no data we can hydrate from the cache (errors aren't cache data), so we
+		// stream the errors directly and rebuild an erroring store on the client. without this the
+		// pending signal never resolves and the page hangs on the loading state instead of reaching
+		// the nearest error boundary.
+		function stream_error(errors: GraphQLError[]) {
+			injectToStream?.(`
+				<script>
+				{
+					const artifactName = ${escapeScriptTag(JSON.stringify(artifact.name))}
+					const errors = ${escapeScriptTag(JSON.stringify(errors))}
+					const variables = ${escapeScriptTag(JSON.stringify(observer.state.variables))}
+					const artifact = ${escapeScriptTag(JSON.stringify(artifact))}
+
+					// build a document store that already carries the errors so useQueryResult
+					// throws to the nearest boundary the moment it reads the store
+					const __houdini__error_store__ = (knownArtifact) => {
+						const store = window.__houdini__client__.observe({
+							artifact: knownArtifact ?? artifact,
+							cache: window.__houdini__cache__,
+							initialVariables: variables,
+						})
+						store.update((state) => ({ ...state, fetching: false, errors }))
+						return store
+					}
+
+					// if the client has already hydrated (a client-side navigation to an @loading
+					// route) push the error store straight into the live caches and release the signal
+					if (window.__houdini__nav_caches__) {
+						const caches = window.__houdini__nav_caches__
+						caches.data_cache.set(
+							artifactName,
+							__houdini__error_store__(caches.artifact_cache.get(artifactName))
+						)
+						if (caches.ssr_signals.has(artifactName)) {
+							caches.ssr_signals.get(artifactName).resolve()
+							caches.ssr_signals.delete(artifactName)
+						}
+					} else {
+						// otherwise the page module hasn't run yet (the common @loading case): stash the
+						// error so hydrate_page can build the error store when it sets up the caches
+						const pendingArtifacts = (window.__houdini__pending_artifacts__ =
+							window.__houdini__pending_artifacts__ || {})
+						pendingArtifacts[artifactName] = artifact
+						const pendingVariables = (window.__houdini__pending_variables__ =
+							window.__houdini__pending_variables__ || {})
+						pendingVariables[artifactName] = variables
+						const pendingErrors = (window.__houdini__pending_errors__ =
+							window.__houdini__pending_errors__ || {})
+						pendingErrors[artifactName] = errors
+					}
+				}
+				</script>
+			`)
+		}
+
 		// store the observer immediately so useQueryResult can access it
 		// during SSR rendering before the fetch resolves
 		let resolve: () => void = () => {}
@@ -301,9 +366,12 @@ function usePageData({
 				.then(async () => {
 					data_cache.set(id, observer)
 
-					// if there is an error, signal completion (the error is visible via
-					// useQueryResult reading observer.state.errors) and clean up
+					// if there is an error, stream it to the client (so an @loading query
+					// reaches the error boundary instead of hanging on the loading state) and
+					// clean up. on the client data_cache.set above is enough for useQueryResult
+					// to read the errors and throw; the stream is what carries them across SSR.
 					if (observer.state.errors && observer.state.errors.length > 0) {
+						stream_error(observer.state.errors)
 						ssr_signals.delete(id)
 						resolve()
 						return
@@ -422,7 +490,14 @@ function usePageData({
 					if (err?.name === 'AbortError') {
 						return
 					}
-					reject(err)
+					// a thrown error (e.g. a throwOnError plugin) never lands in observer.state, so
+					// seed it as a synthetic GraphQL error on the store and stream it to the client,
+					// otherwise an @loading query that rejects hangs on the loading state
+					const errors = [{ message: err?.message ?? String(err) }]
+					observer.update((state) => ({ ...state, fetching: false, errors }))
+					data_cache.set(id, observer)
+					stream_error(errors)
+					resolve()
 				})
 		})
 
@@ -611,7 +686,7 @@ export function RouterContextProvider({
 	)
 }
 
-type RouterContext = {
+export type RouterContext = {
 	client: HoudiniClient
 	cache: Cache
 
@@ -662,8 +737,6 @@ export type PendingCache = SuspenseCache<
 	Promise<void> & { resolve: () => void; reject: (message: string) => void }
 >
 
-const Context = React.createContext<RouterContext | null>(null)
-
 export const useRouterContext = () => {
 	const ctx = React.useContext(Context)
 
@@ -740,21 +813,6 @@ export function useSession(): [
 	return [ctx.session, updateSession]
 }
 
-const LocationContext = React.createContext<{
-	pathname: string
-	params: Record<string, any>
-	// the parsed query string of the current url (declared search params coerced to
-	// their scalar type, other keys raw; repeated keys are arrays).
-	search: Record<string, any>
-	// a function to imperatively navigate to a url
-	goto: Goto
-}>({
-	pathname: '',
-	params: {},
-	search: {},
-	goto: () => {},
-})
-
 export function useQueryResult<_Data extends GraphQLObject, _Input extends GraphQLVariables>(
 	name: string
 ): [_Data | null, DocumentHandle<any, _Data, _Input>] {
@@ -1018,7 +1076,8 @@ class NotFoundLayoutBoundary extends React.Component<
 	}
 }
 
-export const Is404Context = React.createContext(false)
+// re-exported (defined in ../contexts.js) so existing `routing` barrel consumers keep working
+export { Is404Context }
 
 export function NotFoundGate({ children }: { children: React.ReactNode }) {
 	const is404 = React.useContext(Is404Context)
@@ -1028,8 +1087,6 @@ export function NotFoundGate({ children }: { children: React.ReactNode }) {
 	return <>{children}</>
 }
 
-const PageContext = React.createContext<{ params: Record<string, any> }>({ params: {} })
-
 export function PageContextProvider({
 	keys,
 	children,

package/runtime/routing/errors.tsx

@@ -1,6 +1,8 @@
 import type { GraphQLError } from 'houdini/runtime'
 import React from 'react'
 
+import { StatusContext } from '../contexts.js'
+
 export class GraphQLErrors extends Error {
 	graphqlErrors: GraphQLError[]
 
@@ -73,9 +75,9 @@ export function redirect(status: 300 | 301 | 302 | 303 | 307 | 308, location: st
 	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)
+// StatusContext is defined in ../contexts.js (a dependency-only leaf module) so its
+// identity survives Vite HMR re-evaluation; re-exported here to keep the existing surface.
+export { StatusContext }
 
 type HoudiniErrorBoundaryProps = {
 	errorView: React.ComponentType<{