houdini-react 2.0.0-next.41 → 2.0.0-next.45

package/package.json

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

@@ -1,81 +1,50 @@
 // this file is generated by houdini — do not edit
 // @refresh reset
 import type { AnchorHTMLAttributes, DetailedHTMLProps } from 'react'
+import { getCurrentConfig } from '$houdini/runtime/config'
 import React from 'react'
 
 // @ts-ignore
-import type rawManifest from './manifest.js'
-// @ts-ignore
-import type { RouteScalars } from './manifest.js'
-
-import { resolveHref } from './resolve-href.js'
-
-type _Pages = (typeof rawManifest)['pages']
-type _TSType<T extends string> = T extends keyof RouteScalars
-	? RouteScalars[T]
-	: T extends 'Int' | 'Float'
-		? number
-		: T extends 'ID'
-			? string | number
-			: T extends 'Boolean'
-				? boolean
-				: string
-type _Param = { readonly name: string; readonly type: string; readonly optional: boolean }
-type _ParamObj<Ps extends readonly _Param[]> = {
-	[P in Ps[number] as P['optional'] extends true ? P['name'] : never]?: _TSType<P['type']>
-} & {
-	[P in Ps[number] as P['optional'] extends true ? never : P['name']]: _TSType<P['type']>
-}
-
-type _ExternalHref =
-	| `http://${string}`
-	| `https://${string}`
-	| `mailto:${string}`
-	| `tel:${string}`
-	| `blob:${string}`
-	| `data:${string}`
-	| `//${string}`
-	| `#${string}`
-	| `./${string}`
-	| `../${string}`
+import manifest from './manifest.js'
+import type { RouteHrefs, ExternalHref, ParamsForRoute, SearchForRoute } from './routes.js'
 
-// All known app route URL strings — useful as a constraint for custom link wrappers.
-export type RouteHrefs = _Pages[keyof _Pages] extends { readonly url: infer U extends string }
-	? U
-	: never
+import { buildHref, type RouteHrefInfo } from './resolve-href.js'
 
-// Separate 'to' from 'params' so TypeScript evaluates them independently:
-// - 'to' completions show all routes (including parameterized) because 'to' itself is always valid
-// - 'params' is a separate intersection that errors when required but absent
-type _PageForRoute<H extends string> = Extract<_Pages[keyof _Pages], { readonly url: H }>
-type _ParamsForRoute<H extends string> = [_PageForRoute<H>] extends [never]
-	? { params?: never }
-	: _PageForRoute<H> extends { readonly params: readonly [] }
-		? { params?: never }
-		: _PageForRoute<H> extends { readonly params: infer Ps extends readonly _Param[] }
-			? { params: _ParamObj<Ps> }
-			: { params?: never }
+// re-exported for custom link wrappers that constrain their own `to` prop
+export type { RouteHrefs }
 
-export type LinkProps<H extends RouteHrefs | _ExternalHref = RouteHrefs | _ExternalHref> = Omit<
+export type LinkProps<H extends RouteHrefs | ExternalHref = RouteHrefs | ExternalHref> = Omit<
 	DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>,
 	'href'
 > & {
 	to: H
 	disabled?: boolean
 	preload?: boolean | 'data' | 'component' | 'page'
-} & _ParamsForRoute<H>
+} & ParamsForRoute<H> &
+	SearchForRoute<H>
 
-export function Link<H extends RouteHrefs | _ExternalHref>({
+export function Link<H extends RouteHrefs | ExternalHref>({
 	to,
 	params,
+	search,
 	disabled,
 	preload,
 	...rest
 }: LinkProps<H>): React.ReactElement {
+	// look up the destination route (O(1) via the codegen'd pagesByUrl map) so custom-scalar
+	// param/search values can be marshaled into their transport form (e.g. a Date →
+	// timestamp) before they hit the URL. External hrefs won't match a page, so marshalers
+	// stay empty.
+	const m = manifest as any
+	const page = m.pages[m.pagesByUrl[to as string]] as RouteHrefInfo | undefined
 	const href = disabled
 		? undefined
-		: params != null
-			? resolveHref(to as string, params as Record<string, string | number | boolean>)
-			: (to as string)
+		: buildHref(
+				to as string,
+				page,
+				getCurrentConfig()?.scalars,
+				params as Record<string, unknown> | undefined,
+				search as Record<string, unknown> | undefined
+			)
 	return React.createElement('a', { ...rest, href, 'data-houdini-preload': preload })
 }

package/runtime/hooks/useDocumentHandle.ts

@@ -16,7 +16,7 @@ import type {
 import type { DocumentStore } from 'houdini/runtime/client'
 import React from 'react'
 
-import { useClient, useLocation, useSession } from '../routing/Router.js'
+import { useClient, useLocationContext, useSession } from '../routing/Router.js'
 
 export function useDocumentHandle<
 	_Artifact extends QueryArtifact,
@@ -36,7 +36,7 @@ export function useDocumentHandle<
 	// 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()
+	const location = useLocationContext()
 
 	// grab the current session value
 	const [session] = useSession()
@@ -234,5 +234,10 @@ type RefetchHandlers<_Artifact extends QueryArtifact, _Data extends GraphQLObjec
 					loadNext: OffsetHandlers<_Data, _Input>['loadNextPage']
 					loadNextPending: boolean
 				}
-			: // the artifact does not support a known pagination method, don't add anything
-				{}
+			: // a @refetchable fragment: embedded query keyed by id, re-run with new args
+				_Artifact extends { refetch: { paginated: false } }
+				? {
+						refetch: (variables?: Partial<_Input>) => Promise<_Data>
+					}
+				: // the artifact does not support a known pagination method, don't add anything
+					{}

package/runtime/hooks/useFragment.ts

@@ -4,12 +4,36 @@ import type {
 	GraphQLVariables,
 	FragmentArtifact,
 	QueryResult,
+	SubscriptionSpec,
 } from 'houdini/runtime'
 import * as React from 'react'
 
 import { useRouterContext } from '../routing/index.js'
 import { useDocumentSubscription } from './useDocumentSubscription.js'
 
+// useFragment reads a fragment's data back out of the cache. When the fragment is marked
+// @plural it is spread on a list field, so the reference is an array of fragment references
+// and the hook returns an array of data (see usePluralFragment below).
+
+// plural overloads: the reference is an array of fragment references
+export function useFragment<
+	_Data extends GraphQLObject,
+	_ReferenceType extends {},
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	reference: ReadonlyArray<_Data | { ' $fragments': _ReferenceType }>,
+	document: { artifact: FragmentArtifact }
+): _Data[]
+export function useFragment<
+	_Data extends GraphQLObject,
+	_ReferenceType extends {},
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	reference: ReadonlyArray<_Data | { ' $fragments': _ReferenceType }> | null,
+	document: { artifact: FragmentArtifact }
+): _Data[] | null
+
+// singular overload: the reference is a single fragment reference
 export function useFragment<
 	_Data extends GraphQLObject,
 	_ReferenceType extends {},
@@ -17,6 +41,35 @@ export function useFragment<
 >(
 	reference: _Data | { ' $fragments': _ReferenceType } | null,
 	document: { artifact: FragmentArtifact }
+): _Data | null
+
+export function useFragment(reference: any, document: { artifact: FragmentArtifact }): any {
+	const plural = Boolean(document.artifact.plural)
+
+	// a non-plural fragment given a list of references is a mistake (the fragment needs
+	// @plural to be read as an array)
+	if (!plural && Array.isArray(reference)) {
+		throw new Error(
+			`useFragment received a list of references for "${document.artifact.name}", but it is not marked @plural.`
+		)
+	}
+
+	// Both implementations run on every render so the rules of hooks are preserved; the one
+	// that isn't relevant is fed a null reference and becomes a no-op. Which result we return
+	// is keyed off the static @plural artifact flag, so a given call-site is always consistent.
+	const singularResult = useSingularFragment(plural ? null : reference, document)
+	const pluralResult = usePluralFragment(plural ? (reference ?? null) : null, document)
+
+	return plural ? pluralResult : singularResult
+}
+
+function useSingularFragment<
+	_Data extends GraphQLObject,
+	_ReferenceType extends {},
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	reference: _Data | { ' $fragments': _ReferenceType } | null,
+	document: { artifact: FragmentArtifact }
 ): _Data | null {
 	const { cache } = useRouterContext()
 	const { parent, variables, loading } = fragmentReference<_Data, _Input, _ReferenceType>(
@@ -67,7 +120,9 @@ export function useFragment<
 		artifact: document.artifact,
 		variables,
 		initialValue: cachedValue,
-		disabled: loading,
+		// no parent means there is nothing to subscribe to (eg a null reference, or this
+		// singular hook running in no-op mode for a @plural fragment)
+		disabled: loading || !parent,
 		send: {
 			stuff: {
 				parentID: parent,
@@ -80,6 +135,119 @@ export function useFragment<
 	return storeValue.data
 }
 
+// usePluralFragment consumes a @plural fragment: the reference is an array of fragment
+// references (one per item in the list the fragment was spread on). Each item is bound to
+// its own cache record, so we keep the list in state and register one cache subscription
+// per item inside a single effect. A subscription message carries the new value for just
+// that record, so we patch it into the list in place rather than re-reading everything.
+// Doing the subscriptions in one effect keeps the hook count stable regardless of how many
+// items the list contains (we can't call a hook per item).
+function usePluralFragment<
+	_Data extends GraphQLObject,
+	_ReferenceType extends {},
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	references: ReadonlyArray<_Data | { ' $fragments': _ReferenceType }> | null,
+	document: { artifact: FragmentArtifact }
+): _Data[] | null {
+	const { cache } = useRouterContext()
+	const artifact = document.artifact
+
+	// resolve the cache record + variables for each reference in the list
+	// biome-ignore lint/correctness/useExhaustiveDependencies: document is a stable import
+	const entries = React.useMemo(
+		() =>
+			references
+				? references.map((reference) =>
+						fragmentReference<_Data, _Input, _ReferenceType>(reference, document)
+					)
+				: null,
+		[references]
+	)
+
+	// a stable key describing which records (and variables) we are bound to, so we only
+	// re-seed and re-subscribe when the set of records actually changes (eg an insert/remove)
+	const subscriptionKey = entries
+		? entries
+				.map((entry) => `${entry.parent}:${JSON.stringify(entry.variables ?? {})}`)
+				.join('|')
+		: ''
+
+	// read every item from the cache. used to seed the list, and to re-seed it when the set
+	// of records changes (membership changes don't necessarily message the existing records).
+	const readAll = (): _Data[] | null => {
+		if (!references || !entries) {
+			return null
+		}
+		return entries.map(({ parent, variables, loading }, i) =>
+			parent
+				? (cache.read({ selection: artifact.selection, parent, variables, loading })
+						.data as _Data)
+				: (references[i] as _Data)
+		)
+	}
+
+	const [data, setData] = React.useState<_Data[] | null>(readAll)
+
+	// the subscriptionKey the current `data` was seeded for; starts matching the initial
+	// useState seed so we don't redundantly re-seed on mount
+	const seededKey = React.useRef(subscriptionKey)
+
+	// re-seed when the set of records changes, then subscribe to each record individually.
+	// onMessage carries the new value for just that record, so we patch it in place.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: keyed on subscriptionKey
+	React.useEffect(() => {
+		if (seededKey.current !== subscriptionKey) {
+			seededKey.current = subscriptionKey
+			setData(readAll())
+		}
+
+		if (!entries) {
+			return
+		}
+
+		const specs: SubscriptionSpec[] = []
+		entries.forEach(({ parent, variables, loading }, index) => {
+			if (!parent || loading) {
+				return
+			}
+			const spec: SubscriptionSpec = {
+				rootType: artifact.rootType,
+				kind: artifact.kind,
+				selection: artifact.selection,
+				parentID: parent,
+				variables: () => variables ?? {},
+				onMessage: (message) => {
+					// only a cache write ('update') carries a new value for this record. other
+					// messages (eg 'refetch' from cache.refresh()) don't apply to a fragment,
+					// which has no refetch of its own; the refreshed value arrives as an 'update'.
+					if (message.kind !== 'update') {
+						return
+					}
+					setData((current) => {
+						if (!current) {
+							return current
+						}
+						const next = current.slice()
+						next[index] = message.data as _Data
+						return next
+					})
+				},
+			}
+			cache.subscribe(spec)
+			specs.push(spec)
+		})
+
+		return () => {
+			for (const spec of specs) {
+				cache.unsubscribe(spec)
+			}
+		}
+	}, [subscriptionKey])
+
+	return data
+}
+
 export function fragmentReference<_Data extends GraphQLObject, _Input, _ReferenceType extends {}>(
 	reference: _Data | { ' $fragments': _ReferenceType } | null,
 	document: { artifact: FragmentArtifact }

package/runtime/hooks/useFragmentHandle.ts

@@ -1,4 +1,10 @@
-import { extractPageInfo, cursorHandlers, offsetHandlers } from 'houdini/runtime'
+import {
+	extractPageInfo,
+	cursorHandlers,
+	offsetHandlers,
+	getCurrentConfig,
+	entityRefetchVariables,
+} from 'houdini/runtime'
 import type {
 	GraphQLObject,
 	FragmentArtifact,
@@ -71,8 +77,44 @@ export function useFragmentHandle<
 		return (paginationData as any)[rootField] ?? null
 	}, [paginationData, refetchArtifact])
 
+	// @refetchable fragments embed the fragment in a query keyed by id (paginated: false).
+	// We observe that query so refetch() can swap in fresh data computed with new argument
+	// values, just like SinglePage pagination swaps in the latest page.
+	const isRefetchable = !!refetchArtifact?.refetch && !refetchArtifact.refetch.paginated
+
+	const refetchObserver = React.useMemo(() => {
+		if (!isRefetchable || !refetchArtifact) return null
+		return client.observe<_Data, _Input>({ artifact: refetchArtifact })
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [refetchArtifact?.name, isRefetchable])
+
+	const subscribeToRefetch = React.useCallback(
+		(fn: () => void) => refetchObserver?.subscribe(() => fn()) ?? (() => {}),
+		[refetchObserver]
+	)
+	const getRefetchSnapshot = React.useCallback(
+		() => refetchObserver?.state.data ?? null,
+		[refetchObserver]
+	)
+	const refetchData = React.useSyncExternalStore(
+		subscribeToRefetch,
+		getRefetchSnapshot,
+		getRefetchSnapshot
+	)
+
+	const refetchEntityData = React.useMemo<_Data | null>(() => {
+		if (!refetchData || !refetchArtifact?.selection?.fields) return null
+		const rootField = Object.keys(refetchArtifact.selection.fields)[0]
+		if (!rootField) return null
+		return (refetchData as any)[rootField] ?? null
+	}, [refetchData, refetchArtifact])
+
 	const displayData =
-		isSinglePage && paginationEntityData !== null ? paginationEntityData : fragmentData
+		isSinglePage && paginationEntityData !== null
+			? paginationEntityData
+			: isRefetchable && refetchEntityData !== null
+				? refetchEntityData
+				: fragmentData
 
 	const wrapLoad = <_Result>(
 		setLoading: (val: boolean) => void,
@@ -170,9 +212,48 @@ export function useFragmentHandle<
 		return null
 	}, [refetchArtifact, paginationObserver, displayData, session, forwardPending, backwardPending])
 
+	// the fragment's current argument values: the initial args overlaid with everything that
+	// has been passed to refetch() so far. we track these explicitly rather than reading them
+	// back off the embedded query, whose variables also carry the synthetic id-lookup keys.
+	const [refetchArgs, setRefetchArgs] = React.useState<Partial<_Input>>({})
+
+	// re-run the embedded query with new argument values. the entity's id is derived from
+	// the fragment data (the parent reference), which always carries the visible id. we must
+	// NOT derive it from displayData: after a refetch that becomes the embedded query result,
+	// which masks the entity's id out of its selection, so reading it back would yield
+	// `id: undefined` and clobber the real id on a second refetch.
+	const refetch = React.useMemo(() => {
+		if (!isRefetchable || !refetchObserver || !refetchArtifact) return undefined
+		return (newVariables?: _Input) => {
+			setRefetchArgs((prev) => ({ ...prev, ...newVariables }))
+			const idVariables = entityRefetchVariables(
+				getCurrentConfig(),
+				refetchArtifact.refetch?.targetType,
+				fragmentData as Record<string, any> | null
+			)
+			return refetchObserver.send({
+				variables: {
+					...(refetchObserver.state.variables ?? variables),
+					...idVariables,
+					...newVariables,
+				} as _Input,
+				// suppress loading-state placeholder data during the transition so the
+				// currently displayed value stays put until the fresh result arrives
+				stuff: { silenceLoading: true },
+				cacheParams: { disableSubscriptions: true, disablePartial: true },
+				session,
+			})
+		}
+	}, [isRefetchable, refetchObserver, refetchArtifact, fragmentData, variables, session])
+
+	const displayVariables = isRefetchable
+		? ({ ...(variables as Record<string, any>), ...refetchArgs } as _Input)
+		: variables
+
 	return {
 		...handle,
-		variables,
+		variables: displayVariables,
 		data: displayData,
+		refetch,
 	}
 }

package/runtime/hooks/useSubscription.ts

@@ -5,7 +5,7 @@ import { useSubscriptionHandle } from './useSubscriptionHandle.js'
 // a hook to subscribe to a subscription artifact
 export function useSubscription<_Result extends GraphQLObject, _Input extends GraphQLVariables>(
 	document: { artifact: SubscriptionArtifact },
-	variables: _Input
+	variables?: _Input
 ) {
 	const { data } = useSubscriptionHandle(document, variables)
 	return data

package/runtime/hooks/useSubscriptionHandle.ts

@@ -1,5 +1,6 @@
 import type {
 	SubscriptionArtifact,
+	DocumentArtifact,
 	GraphQLObject,
 	GraphQLVariables,
 	GraphQLError,
@@ -18,20 +19,23 @@ export type SubscriptionHandle<_Result extends GraphQLObject, _Input extends Gra
 
 // a hook to subscribe to a subscription artifact
 export function useSubscriptionHandle<
-	_Result extends GraphQLObject,
-	_Input extends GraphQLVariables,
->({ artifact }: { artifact: SubscriptionArtifact }, variables: _Input) {
+	_Result extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	{ artifact }: { artifact: SubscriptionArtifact },
+	variables?: _Input
+): SubscriptionHandle<_Result, _Input> {
 	// a subscription is basically just a live document
-	const [storeValue, observer] = useDocumentSubscription({
+	const [storeValue, observer] = useDocumentSubscription<DocumentArtifact, _Result, _Input>({
 		artifact,
-		variables,
+		variables: variables as _Input,
 	})
 
 	return {
 		data: storeValue.data,
 		errors: storeValue.errors,
 		fetching: storeValue.fetching,
-		variables,
+		variables: variables as _Input,
 		unlisten: observer.cleanup,
 		listen: observer.send,
 	}

package/runtime/hydration.tsx

@@ -112,7 +112,7 @@ export function hydrate_page(
 	hydrateRoot(
 		document,
 		<App
-			initialURL={window.location.pathname}
+			initialURL={window.location.pathname + window.location.search}
 			cache={window.__houdini__cache__}
 			session={window.__houdini__initial__session__}
 			{...window.__houdini__nav_caches__}
@@ -145,7 +145,7 @@ export function mount_static_app(App: React.ComponentType<any>, manifest: any) {
 
 	root.render(
 		React.createElement(App, {
-			initialURL: window.location.pathname,
+			initialURL: window.location.pathname + window.location.search,
 			cache: cacheRef,
 			session: null,
 			manifest,

package/runtime/index.tsx

@@ -10,9 +10,7 @@ export {
 	router_cache,
 	useCache,
 	useSession,
-	useLocation,
 	useRoute,
-	useCurrentVariables,
 	notFound,
 	unauthorized,
 	forbidden,
@@ -23,7 +21,9 @@ export {
 	RoutingError,
 	RedirectError,
 } from './routing/index.js'
+export type { GenericRoute } from './routing/index.js'
 export * from './Link.js'
+export { createMock } from './mock.js'
 
 export function Router({
 	cache,

package/runtime/manifest.ts

@@ -1,4 +1,4 @@
-import type { RouterManifest } from 'houdini/runtime'
+import type { RouterManifest } from 'houdini/router/types'
 
 // @ts-expect-error: this file will get replaced by the build system
 const manifest: RouterManifest = {}

package/runtime/mock.ts

@@ -0,0 +1,9 @@
+import type React from 'react'
+
+export function createMock(_args: {
+	url: string
+	params: any
+	data: any
+}): React.ComponentType<{}> {
+	throw new Error('createMock: no routes have been generated yet. Run `houdini generate` first.')
+}