houdini-react 2.0.0-next.34 → 2.0.0-next.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "houdini-react",
-  "version": "2.0.0-next.34",
+  "version": "2.0.0-next.35",
   "description": "The React plugin for houdini",
   "keywords": [
     "typescript",
@@ -81,13 +81,13 @@
     }
   },
   "optionalDependencies": {
-    "houdini-react-darwin-x64": "2.0.0-next.34",
-    "houdini-react-darwin-arm64": "2.0.0-next.34",
-    "houdini-react-linux-x64": "2.0.0-next.34",
-    "houdini-react-linux-arm64": "2.0.0-next.34",
-    "houdini-react-win32-x64": "2.0.0-next.34",
-    "houdini-react-win32-arm64": "2.0.0-next.34",
-    "houdini-react-wasm": "2.0.0-next.34"
+    "houdini-react-darwin-x64": "2.0.0-next.35",
+    "houdini-react-darwin-arm64": "2.0.0-next.35",
+    "houdini-react-linux-x64": "2.0.0-next.35",
+    "houdini-react-linux-arm64": "2.0.0-next.35",
+    "houdini-react-win32-x64": "2.0.0-next.35",
+    "houdini-react-win32-arm64": "2.0.0-next.35",
+    "houdini-react-wasm": "2.0.0-next.35"
   },
   "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.34'
+const BINARY_DISTRIBUTION_VERSION = '2.0.0-next.35'
 
 // 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/recycleNodesInto.ts

@@ -0,0 +1,53 @@
+/**
+ * Walk `next` and, wherever a sub-tree is deeply equal to the corresponding
+ * sub-tree in `prev`, substitute `prev`'s reference.  This preserves object
+ * identity for unchanged branches so React.memo can bail out on re-renders
+ * when a cache write touches unrelated parts of the graph.
+ *
+ * Arrays are reconciled by index.  When lengths differ the array itself gets a
+ * new reference, but individual matching elements are still recycled so that
+ * items from the previous render keep their identities.
+ */
+export function recycleNodesInto<T>(prev: T | null | undefined, next: T): T {
+	if (Object.is(prev, next)) return prev as T
+
+	if (next === null || typeof next !== 'object') return next
+	if (prev === null || prev === undefined || typeof prev !== 'object') return next
+
+	if (Array.isArray(next)) {
+		if (!Array.isArray(prev)) return next
+
+		const nextLen = next.length
+		const prevLen = (prev as unknown[]).length
+		const minLen = Math.min(prevLen, nextLen)
+
+		let changed = false
+		const result: unknown[] = new Array(nextLen)
+
+		for (let i = 0; i < minLen; i++) {
+			result[i] = recycleNodesInto((prev as unknown[])[i], next[i])
+			if (result[i] !== (prev as unknown[])[i]) changed = true
+		}
+		for (let i = minLen; i < nextLen; i++) {
+			result[i] = next[i]
+		}
+
+		if (!changed && prevLen === nextLen) return prev as T
+		return result as unknown as T
+	}
+
+	const prevObj = prev as Record<string, unknown>
+	const nextObj = next as Record<string, unknown>
+	const nextKeys = Object.keys(nextObj)
+	const prevKeyCount = Object.keys(prevObj).length
+
+	let changed = prevKeyCount !== nextKeys.length
+	const result: Record<string, unknown> = {}
+
+	for (const key of nextKeys) {
+		result[key] = recycleNodesInto(prevObj[key], nextObj[key])
+		if (result[key] !== prevObj[key]) changed = true
+	}
+
+	return changed ? (result as T) : (prev as T)
+}

package/runtime/hooks/useDeepCompareEffect.ts

@@ -36,14 +36,16 @@ function isPrimitive(val: unknown) {
  */
 export function useDeepCompareMemoize<T>(value: T) {
 	const ref = React.useRef<T>(value)
-	const signalRef = React.useRef<number>(0)
 
 	if (!deepEquals(value, ref.current)) {
 		ref.current = value
-		signalRef.current += 1
 	}
 
-	return React.useMemo(() => ref.current, [])
+	// Return ref.current directly so React.useEffect sees a new reference only
+	// when the deep value actually changes — matching the original use-deep-compare-effect.
+	// The useMemo(() => ref.current, []) wrapper that was here previously was incorrect:
+	// it froze the returned value at mount time, preventing effects from ever re-firing.
+	return ref.current
 }
 
 function useDeepCompareEffect(

package/runtime/hooks/useDocumentStore.ts

@@ -9,6 +9,7 @@ import * as React from 'react'
 
 import { useClient } from '../routing/index.js'
 import { useIsMountedRef } from './useIsMounted.js'
+import { recycleNodesInto } from './recycleNodesInto.js'
 
 export type UseDocumentStoreParams<
 	_Artifact extends DocumentArtifact,
@@ -17,6 +18,10 @@ export type UseDocumentStoreParams<
 > = {
 	artifact: _Artifact
 	observer?: DocumentStore<_Data, _Input>
+	// Optional synchronous seed for box.current. When provided, box.current is updated
+	// during render so useSyncExternalStore's snapshot is immediately correct (e.g. on
+	// fragment parent change). Must be memoized by the caller — tracked by reference.
+	initialState?: QueryResult<_Data, _Input>
 } & Partial<ObserveParams<_Data, DocumentArtifact, _Input>>
 
 export function useDocumentStore<
@@ -26,6 +31,7 @@ export function useDocumentStore<
 >({
 	artifact,
 	observer: obs,
+	initialState,
 	...observeParams
 }: UseDocumentStoreParams<_Artifact, _Data, _Input>): [
 	QueryResult<_Data, _Input>,
@@ -52,11 +58,41 @@ export function useDocumentStore<
 		setObserver(obs)
 	}
 
+	// Relay-style synchronous seeding: when initialState changes (i.e., the fragment
+	// parent changed), update box.current immediately during this render so
+	// useSyncExternalStore's getSnapshot returns the correct data without waiting for
+	// the subscription effect to fire. Tracked by reference — if provided, callers
+	// must memoize initialState to avoid spurious reseeds on every render.
+	const prevInitialStateRef = React.useRef<QueryResult<_Data, _Input> | undefined>(undefined)
+	if (initialState !== undefined && initialState !== prevInitialStateRef.current) {
+		prevInitialStateRef.current = initialState
+		box.current = initialState
+	}
+
 	// the function that registers a new subscription for the observer
 	const subscribe: any = React.useCallback(
 		(fn: () => void) => {
 			return observer.subscribe((val) => {
-				box.current = val
+				const prev = box.current
+				// Preserve object identity for unchanged subtrees so React.memo on
+				// fragment components can bail out when their data wasn't touched.
+				const stableData = recycleNodesInto(prev?.data, val.data)
+				const next = stableData === val.data ? val : { ...val, data: stableData }
+
+				// Skip the re-render entirely if the new state is semantically identical
+				// to what React already has (e.g. an idempotent cache write).
+				if (
+					next === prev ||
+					(stableData === prev?.data &&
+						val.fetching === prev?.fetching &&
+						val.errors === prev?.errors &&
+						val.source === prev?.source &&
+						val.stale === prev?.stale)
+				) {
+					return
+				}
+
+				box.current = next
 				if (isMountedRef.current) {
 					fn()
 				}

package/runtime/hooks/useDocumentSubscription.ts

@@ -18,15 +18,17 @@ export function useDocumentSubscription<
 	artifact,
 	variables,
 	send,
+	initialState,
 	disabled,
 	...observeParams
 }: UseDocumentStoreParams<_Artifact, _Data, _Input> & {
 	variables: _Input
 	disabled?: boolean
-	send?: Partial<SendParams>
+	send?: Partial<Omit<SendParams, 'initialState'>>
 }): [QueryResult<_Data, _Input> & { parent?: string | null }, DocumentStore<_Data, _Input>] {
 	const [storeValue, observer] = useDocumentStore<_Data, _Input>({
 		artifact,
+		initialState,
 		...observeParams,
 	})
 
@@ -42,6 +44,7 @@ export function useDocumentSubscription<
 				// TODO: metadata
 				metadata: {},
 				...send,
+				initialState,
 			})
 		}
 

package/runtime/hooks/useFragment.ts

@@ -1,6 +1,10 @@
-import { deepEquals } from 'houdini/runtime'
 import { fragmentKey } from 'houdini/runtime'
-import type { GraphQLObject, GraphQLVariables, FragmentArtifact } from 'houdini/runtime'
+import type {
+	GraphQLObject,
+	GraphQLVariables,
+	FragmentArtifact,
+	QueryResult,
+} from 'houdini/runtime'
 import * as React from 'react'
 
 import { useRouterContext } from '../routing/index.js'
@@ -15,33 +19,54 @@ export function useFragment<
 	document: { artifact: FragmentArtifact }
 ): _Data | null {
 	const { cache } = useRouterContext()
-
-	// get the fragment reference info
 	const { parent, variables, loading } = fragmentReference<_Data, _Input, _ReferenceType>(
 		reference,
 		document
 	)
 
-	// if we got this far then we are safe to use the fields on the object
-	let cachedValue = reference as _Data | null
+	// Read from cache whenever the parent or loading state changes. The parent
+	// path uniquely identifies which cache record this fragment is bound to, so
+	// variables are excluded from the dep array — they are forwarded to
+	// observer.send() separately and don't affect which record we read.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: variables intentionally excluded
+	const cachedValue = React.useMemo(() => {
+		if (reference && parent) {
+			return cache.read({
+				selection: document.artifact.selection,
+				parent,
+				variables,
+				loading,
+			}).data as _Data
+		}
+		return reference as _Data | null
+	}, [parent, loading])
 
-	// on the client, we want to ensure that we apply masking to the initial value by
-	// loading the value from cache
-	if (reference && parent) {
-		cachedValue = cache.read({
-			selection: document.artifact.selection,
-			parent,
-			variables,
-			loading,
-		}).data as _Data
-	}
+	// Stable initialState derived from cachedValue. useDocumentStore uses this to
+	// seed box.current synchronously during render when the parent changes, so
+	// storeValue.data is immediately correct without waiting for the subscription
+	// effect to fire. Must be memoized (reference-stable) so the store doesn't
+	// re-seed on every render.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: variables changes don't require re-seeding
+	const initialState = React.useMemo(
+		(): QueryResult<_Data, _Input> | undefined =>
+			cachedValue !== null
+				? {
+						data: cachedValue,
+						errors: null,
+						fetching: false,
+						partial: false,
+						stale: false,
+						source: null,
+						variables: variables ?? null,
+					}
+				: undefined,
+		[cachedValue]
+	)
 
-	// we're ready to setup the live document
 	const [storeValue] = useDocumentSubscription<FragmentArtifact, _Data, _Input>({
 		artifact: document.artifact,
 		variables,
 		initialValue: cachedValue,
-		// dont subscribe to anything if we are loading
 		disabled: loading,
 		send: {
 			stuff: {
@@ -49,27 +74,10 @@ export function useFragment<
 			},
 			setup: true,
 		},
+		initialState,
 	})
 
-	// the parent has changed, we need to use initialValue for this render
-	// if we don't, then there is a very brief flash where we will show the old data
-	// before the store has had a chance to update
-	const lastReference = React.useRef<{ parent: string; variables: _Input } | null>(null)
-	return React.useMemo(() => {
-		// if the parent reference has changed we need to always prefer the cached value
-		const parentChange =
-			storeValue.parent !== parent ||
-			!deepEquals({ parent, variables }, lastReference.current)
-		if (parentChange) {
-			// make sure we keep track of the last reference we used
-			lastReference.current = { parent, variables: { ...variables } }
-
-			// and use the cached value
-			return cachedValue
-		}
-
-		return storeValue.data
-	}, [variables, parent, storeValue.parent, storeValue.data, cachedValue])
+	return storeValue.data
 }
 
 export function fragmentReference<_Data extends GraphQLObject, _Input, _ReferenceType extends {}>(

package/runtime/routing/Router.tsx

@@ -73,7 +73,7 @@ export function Router({
 		injectToStream,
 	})
 	// if we get this far, it's safe to load the component
-	const { component_cache, data_cache } = useRouterContext()
+	const { component_cache, data_cache, ssr_signals } = useRouterContext()
 	const PageComponent = component_cache.get(page.id)!
 
 	// if we got this far then we're past suspense
@@ -107,6 +107,8 @@ export function Router({
 	const goto = (url: string) => {
 		// clear the data cache so that we refetch queries with the new session (will force a cache-lookup)
 		data_cache.clear()
+		// clear pending signals so the next render starts fresh load_query calls
+		ssr_signals.clear()
 
 		// perform the navigation
 		setCurrentURL(url)
@@ -333,17 +335,20 @@ function usePageData({
 						</script>
 					`)
 
+					ssr_signals.delete(id)
 					resolve()
 				})
-				.catch(reject)
+				.catch((err) => {
+					ssr_signals.delete(id)
+					reject(err)
+				})
 		})
 
-		// if we are on the server, we need to save a signal that we can use to
-		// communicate with the client when we're done
+		// register the pending signal on both client and server so that concurrent React renders
+		// (concurrent mode / strict mode) that call load_query before data_cache is populated
+		// find the existing signal and don't create a duplicate observer+send
 		const resolvable = { ...promise, resolve, reject }
-		if (!globalThis.window) {
-			ssr_signals.set(id, resolvable)
-		}
+		ssr_signals.set(id, resolvable)
 
 		// we're done
 		return resolvable
@@ -378,6 +383,7 @@ function usePageData({
 			// before we can compare we need to only look at the variables that the artifact cares about
 			if (Object.keys(usedVariables ?? {}).length > 0 && !deepEquals(last, usedVariables)) {
 				data_cache.delete(artifact)
+				ssr_signals.delete(artifact)
 			}
 		}
 
@@ -583,6 +589,7 @@ export function useSession(): [App.Session, (newSession: Partial<App.Session>) =
 	const updateSession = (newSession: Partial<App.Session>) => {
 		// clear the data cache so that we refetch queries with the new session (will force a cache-lookup)
 		ctx.data_cache.clear()
+		ctx.ssr_signals.clear()
 
 		// update the local state
 		ctx.setSession(newSession)