houdini-react 2.1.2 → 2.2.0

package/package.json

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

package/runtime/hooks/observerRefs.ts

@@ -0,0 +1,51 @@
+// Committed components hold a reference on their document store: two components
+// rendering the same query+variables share one store through the suspense cache, so the
+// store can only tear down when the LAST holder unmounts. The count is backed by a real
+// (no-op) subscription because the underlying store runs its plugin cleanups (dropping
+// the cache subscription) whenever its subscriber count touches zero — which react's
+// strict-mode effect replay does to the component's own subscription.
+
+// the only thing retain/release need from a store is subscribe
+type Holdable = {
+	subscribe: (fn: (value: any) => void) => () => void
+}
+
+const observerRefs = new WeakMap<Holdable, { count: number; hold: () => void }>()
+
+export function retainObserver(observer: Holdable) {
+	const entry = observerRefs.get(observer)
+	if (entry) {
+		entry.count++
+		return
+	}
+	observerRefs.set(observer, { count: 1, hold: observer.subscribe(() => {}) })
+}
+
+export function releaseObserver(observer: Holdable) {
+	const entry = observerRefs.get(observer)
+	if (!entry) {
+		return
+	}
+	entry.count--
+	if (entry.count > 0) {
+		return
+	}
+	// defer the disposal a tick: strict mode releases and synchronously re-retains, and
+	// dropping the hold at zero immediately would tear the store down mid-replay
+	setTimeout(() => {
+		const current = observerRefs.get(observer)
+		if (!current || current.count > 0) {
+			return
+		}
+		observerRefs.delete(observer)
+		// dropping the hold makes the store's own last-unsubscriber teardown run the
+		// plugin cleanups (including the cache unsubscribe)
+		current.hold()
+	}, 0)
+}
+
+// whether any committed component currently holds the store (used to decide if an
+// evicted suspense unit's store was abandoned and needs explicit disposal)
+export function isObserverRetained(observer: Holdable): boolean {
+	return observerRefs.has(observer)
+}

package/runtime/hooks/suspenseCache.ts

@@ -0,0 +1,58 @@
+import { createLRUCache } from 'houdini/runtime'
+import type { GraphQLObject, GraphQLVariables, QueryArtifact, LRUCache } from 'houdini/runtime'
+import type { Cache } from 'houdini/runtime/cache'
+import type { DocumentStore } from 'houdini/runtime/client'
+
+import { isObserverRetained } from './observerRefs.js'
+import type { DocumentHandle } from './useDocumentHandle.js'
+
+export type QuerySuspenseUnit<
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+> = {
+	resolve: () => void
+	resolved?: DocumentHandle<QueryArtifact, _Data, _Input>
+	// a failed fetch parks its error here (and resolves the thenable): the suspense
+	// protocol retries the render on resolution, and the retry throws this to the
+	// nearest error boundary. rejecting the thenable instead would make react retry a
+	// render that starts a brand new fetch — an error loop.
+	rejected?: unknown
+	then: (val: any) => any
+	// the store that started the fetch. suspending discards the component instance that
+	// created it, so the retry render has to pick this store back up — the cache
+	// subscription created by the fetch belongs to it, and a fresh store would never
+	// hear about later cache updates (a mutation write, a list operation)
+	observer: DocumentStore<GraphQLObject, GraphQLVariables>
+}
+
+// suspense state is scoped to the Cache instance: the browser has exactly one so the
+// scoping is invisible there, but on the server the cache is created per request — and
+// suspense units carry resolved query data, which can be session-dependent. a module-wide
+// cache would let one request's render serve another user's data.
+const promiseCaches = new WeakMap<Cache, LRUCache<QuerySuspenseUnit>>()
+
+export function promiseCacheFor(cache: Cache): LRUCache<QuerySuspenseUnit> {
+	let result = promiseCaches.get(cache)
+	if (!result) {
+		result = createLRUCache<QuerySuspenseUnit>(1000, (unit) => {
+			// a unit leaving the cache whose store no committed component ever picked up is
+			// an abandoned suspense (suspended, then unmounted before commit) or an errored
+			// fetch — dispose the store so its cache subscription doesn't outlive it.
+			// retained stores are governed by their holders instead.
+			if (!isObserverRetained(unit.observer)) {
+				unit.observer.cleanup()
+			}
+		})
+		promiseCaches.set(cache, result)
+	}
+	return result
+}
+
+// a session change invalidates every cached query result. the router clears its own
+// caches (data_cache et al); this is the same sweep for useQuery's suspense state, so a
+// session-dependent useQuery refetches instead of serving data fetched under the old
+// session. clearing evicts every unit (disposing unretained stores); mounted components
+// re-render off the session context, miss the cache, and re-suspend into a fresh fetch.
+export function invalidateSuspenseCache(cache: Cache) {
+	promiseCaches.get(cache)?.clear()
+}

package/runtime/hooks/useQueryHandle.ts

@@ -1,8 +1,10 @@
-import { createLRUCache } from 'houdini/runtime'
 import type { GraphQLObject, CachePolicies, QueryArtifact, GraphQLVariables } from 'houdini/runtime'
+import type { DocumentStore } from 'houdini/runtime/client'
 import React from 'react'
 
-import { useClient } from '../routing/index.js'
+import { GraphQLErrors, useRouterContext } from '../routing/index.js'
+import { releaseObserver, retainObserver } from './observerRefs.js'
+import { promiseCacheFor, type QuerySuspenseUnit } from './suspenseCache.js'
 import type { DocumentHandle } from './useDocumentHandle.js'
 import { useDocumentHandle } from './useDocumentHandle.js'
 import { useIsMountedRef } from './useIsMounted.js'
@@ -17,16 +19,9 @@ import { useIsMountedRef } from './useIsMounted.js'
 // - If we have a cached promise that's been resolved, we should return that value
 //
 // When the Component unmounts, we need to remove the entry from the cache (so we can load again)
-
-const promiseCache = createLRUCache<QuerySuspenseUnit>()
-type QuerySuspenseUnit<
-	_Data extends GraphQLObject = GraphQLObject,
-	_Input extends GraphQLVariables = GraphQLVariables,
-> = {
-	resolve: () => void
-	resolved?: DocumentHandle<QueryArtifact, _Data, _Input>
-	then: (val: any) => any
-}
+//
+// The suspense state itself lives in suspenseCache.ts, scoped per Cache instance (i.e.
+// per request on the server) and invalidated on session changes.
 
 export function useQueryHandle<
 	_Artifact extends QueryArtifact,
@@ -37,22 +32,45 @@ export function useQueryHandle<
 	variables: any = null,
 	config: UseQueryConfig = {}
 ): any {
+	// the client, the per-request cache (a singleton in the browser), and — during a
+	// server render — the stream injector all come from the router context
+	const { client, cache, injectToStream } = useRouterContext()
+
+	// suspense state lives on the per-request cache so SSR requests can't see each other's
+	const promiseCache = promiseCacheFor(cache)
+
 	// figure out the identifier so we know what to look for
 	const identifier = queryIdentifier({ artifact, variables, config })
 
 	// see if we have an entry in the cache for the identifier
 	const suspenseValue = promiseCache.get(identifier)
 
-	const client = useClient()
+	// a failed fetch: surface the error to the nearest boundary, and drop the unit so a
+	// later mount (e.g. navigating back after the error boundary took over) retries
+	// instead of re-throwing the stale error forever
+	if (suspenseValue?.rejected) {
+		promiseCache.delete(identifier)
+		throw suspenseValue.rejected
+	}
 
 	const isMountedRef = useIsMountedRef()
 
-	// hold onto an observer we'll use
+	// hold onto an observer we'll use. if a fetch for this identifier already started, we
+	// have to reuse the store that started it: suspending threw away the component
+	// instance that created it, and the cache subscription set up by that fetch belongs
+	// to that store — a fresh one would render fine but never hear about later cache
+	// updates. the initial value has to stay null (not an empty object) until the
+	// suspense promise resolves: every "do we have data yet" check below is a truthiness
+	// check, and a truthy empty object makes a re-render that happens mid-flight (eg a
+	// parent state update) commit the component with empty data instead of re-throwing
+	// the pending promise.
 	const [observer] = React.useState(
-		client.observe<_Data, _Input>({
-			artifact,
-			initialValue: (suspenseValue?.resolved?.data ?? {}) as _Data,
-		})
+		() =>
+			(suspenseValue?.observer as DocumentStore<_Data, _Input> | undefined) ??
+			client.observe<_Data, _Input>({
+				artifact,
+				initialValue: (suspenseValue?.resolved?.data ?? null) as _Data,
+			})
 	)
 
 	// a ref flag we'll enable before throwing so that we don't update while suspend
@@ -74,8 +92,14 @@ export function useQueryHandle<
 		[observer, isMountedRef.current]
 	)
 
-	// get a safe reference to the cache
-	const storeValue = React.useSyncExternalStore(subscribe, () => box.current)
+	// get a safe reference to the cache. the server snapshot is what lets this hook render
+	// during SSR at all: without it react throws before the fetch ever starts and the whole
+	// subtree falls back to client rendering.
+	const storeValue = React.useSyncExternalStore(
+		subscribe,
+		() => box.current,
+		() => box.current
+	)
 
 	// compute the imperative handle for this artifact
 	const handle = useDocumentHandle<_Artifact, _Data, _Input>({
@@ -92,13 +116,24 @@ export function useQueryHandle<
 		}
 	}, [identifier])
 
-	// when we unmount, we need to clean up
+	// a committed component holds a reference on its store; the store tears down when
+	// the last holder unmounts (see observerRefs.ts)
 	React.useEffect(() => {
+		retainObserver(observer)
 		return () => {
-			observer.cleanup()
+			releaseObserver(observer)
 		}
 	}, [observer])
 
+	// suspenseTracker mutes store notifications while we're suspended. on the initial
+	// mount the flag dies with the discarded pre-commit instance, but when a committed
+	// instance re-suspends (its variables changed) the flag flips on its own ref and
+	// nothing else clears it — the subscription would stay muted forever. effects only
+	// run for committed (non-throwing) renders, so this is the spot to unmute.
+	React.useEffect(() => {
+		suspenseTracker.current = false
+	})
+
 	// if the promise has resolved, let's use that for our first render
 	const result = storeValue.data
 
@@ -106,17 +141,18 @@ export function useQueryHandle<
 		// we are going to cache the promise and then throw it
 		// when it resolves the cached value will be updated
 		// and it will be picked up in the next render
+		// note: the thenable only ever resolves — failures park on suspenseUnit.rejected
+		// and resolve, so the retry render throws them (see the rejected check above)
 		let resolve: () => void = () => {}
-		let reject: (reason?: any) => void = () => {}
-		const loadPromise = new Promise<void>((res, rej) => {
+		const loadPromise = new Promise<void>((res) => {
 			resolve = res
-			reject = rej
 		})
 
 		const suspenseUnit: QuerySuspenseUnit<_Data, _Input> = {
 			// biome-ignore lint/suspicious/noThenProperty: suspense protocol requires a thenable
 			then: loadPromise.then.bind(loadPromise),
 			resolve,
+			observer: observer as unknown as DocumentStore<GraphQLObject, GraphQLVariables>,
 			// @ts-expect-error
 			variables,
 		}
@@ -135,6 +171,18 @@ export function useQueryHandle<
 				},
 			})
 			.then((value) => {
+				// a graphql error must reach the error boundary, not resolve the suspense
+				// with null data (the component would crash reading its fields). same error
+				// shape route queries throw, so +error boundaries see the graphql errors.
+				// park it on the unit and resolve — the retry render throws it (see the
+				// rejected check above; rejecting the thenable would make react retry into
+				// a brand new fetch, an error loop)
+				if (value.errors && value.errors.length > 0) {
+					suspenseUnit.rejected = new GraphQLErrors(value.errors)
+					suspenseUnit.resolve()
+					return
+				}
+
 				// the final value
 				suspenseUnit.resolved = {
 					...handle,
@@ -143,11 +191,39 @@ export function useQueryHandle<
 					artifact,
 				} as unknown as DocumentHandle<QueryArtifact, _Data, _Input>
 
+				// on the server, ship the resolved cache snapshot to the browser the same way
+				// route queries stream theirs: hydration then serves this query straight from
+				// the cache instead of refetching over the network. (a query that resolves
+				// before the shell flushes doesn't need this — its data rides the initial
+				// cache snapshot the server embeds in the document — and the injector wrapper
+				// no-ops in that window.)
+				if (!globalThis.window) {
+					injectToStream?.(`
+						<script>
+						{
+							const __houdini__snapshot__ = ${cache.serialize()}
+							if (window.__houdini__cache__) {
+								// hydrate into a fresh layer and merge it down, rather than clobbering the
+								// shared hydration layer (which would drop everything hydrated before it)
+								const __houdini__layer__ = window.__houdini__cache__.hydrate(__houdini__snapshot__)
+								if (__houdini__layer__) {
+									window.__houdini__cache__._internal_unstable.storage.resolveLayer(__houdini__layer__.id)
+								}
+							} else {
+								(window.__houdini__pending_cache__ = window.__houdini__pending_cache__ || []).push(__houdini__snapshot__)
+							}
+						}
+						</script>
+					`)
+				}
+
 				suspenseUnit.resolve()
 			})
 			.catch((err) => {
-				promiseCache.delete(identifier)
-				reject(err)
+				// same protocol as graphql errors: park and resolve so the retry render
+				// throws to the boundary instead of starting a fresh fetch
+				suspenseUnit.rejected = err
+				suspenseUnit.resolve()
 			})
 		suspenseTracker.current = true
 		throw suspenseUnit

package/runtime/index.tsx

@@ -66,6 +66,7 @@ export function Router({
 			session={session}
 			formResult={formResult}
 			formToken={formToken}
+			injectToStream={injectToStream}
 		>
 			<RouterImpl
 				initialURL={initialURL}

package/runtime/routing/Router.tsx

@@ -23,6 +23,7 @@ import {
 import { escapeScriptTag } from '../escape.js'
 import { buildHref, scalarUnmarshalers, unmarshalScalars } from '../resolve-href.js'
 import type { Goto } from '../routes.js'
+import { invalidateSuspenseCache } from '../hooks/suspenseCache.js'
 import { type DocumentHandle, useDocumentHandle } from '../hooks/useDocumentHandle.js'
 import { useDocumentStore } from '../hooks/useDocumentStore.js'
 import { type SuspenseCache, suspense_cache } from './cache.js'
@@ -931,6 +932,7 @@ export function RouterContextProvider({
 	session: ssrSession = {},
 	formResult = null,
 	formToken = null,
+	injectToStream,
 }: {
 	children: React.ReactNode
 	client: HoudiniClient
@@ -943,6 +945,7 @@ export function RouterContextProvider({
 	session?: App.Session
 	formResult?: FormResult | null
 	formToken?: string | null
+	injectToStream?: (chunk: string) => void
 }) {
 	// the session is top level state
 	// on the server, we can just use
@@ -974,12 +977,12 @@ export function RouterContextProvider({
 			// navigation no longer clears the data cache, so without this an event-driven
 			// session change (updateLocalSession) would keep serving results fetched under the
 			// old session
-			invalidate_session_caches({ data_cache, ssr_signals, last_variables })
+			invalidate_session_caches({ cache, data_cache, ssr_signals, last_variables })
 
 			latestSession.current = merge ? { ...latestSession.current, ...next } : next
 			setSession(latestSession.current)
 		},
-		[data_cache, ssr_signals, last_variables]
+		[cache, data_cache, ssr_signals, last_variables]
 	)
 
 	React.useEffect(() => {
@@ -1017,6 +1020,7 @@ export function RouterContextProvider({
 				},
 				formResult,
 				formToken,
+				injectToStream,
 			}}
 		>
 			{children}
@@ -1071,6 +1075,11 @@ export type RouterContext = {
 	// the session-bound CSRF token forms render in their hidden field (always present from a
 	// server render; null only when there is no server, e.g. a static export).
 	formToken: string | null
+
+	// present only during a server render: appends a chunk to the response stream. queries
+	// that resolve after the shell flushes use this to ship their cache snapshot to the
+	// browser (route queries via load_query, component-level useQuery via useQueryHandle).
+	injectToStream?: (chunk: string) => void
 }
 
 // FormResult mirrors the server's injected shape: a no-JS submission's result keyed by
@@ -1128,6 +1137,7 @@ export function updateLocalSession(session: App.Session, merge = false) {
 // suspends into its loading state and refetches). One helper shared by both session-change
 // paths (updateSession and the HOUDINI_SESSION_EVENT listener) so they can't drift.
 function invalidate_session_caches(caches: {
+	cache: Cache
 	data_cache: SuspenseCache<DocumentStore<GraphQLObject, GraphQLVariables>>
 	ssr_signals: PendingCache
 	last_variables: LRUCache<GraphQLVariables>
@@ -1135,6 +1145,14 @@ function invalidate_session_caches(caches: {
 	caches.data_cache.clear()
 	caches.ssr_signals.clear()
 	caches.last_variables.clear()
+	// useQuery's suspense state is keyed off the Cache instance and holds resolved query
+	// data too — sweep it as well so session-dependent useQuery components refetch
+	invalidateSuspenseCache(caches.cache)
+	// the normalized cache still holds values fetched under the old session. mark it all
+	// stale (not clear — the data can render while revalidating) so a refetch whose
+	// variables didn't change with the session still continues to the network instead of
+	// being served the old session's value from cache.
+	caches.cache.markTypeStale()
 }
 
 export function useSession(): [