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

package/runtime/resolve-href.ts

@@ -1,14 +1,164 @@
+// A marshaler turns a rich runtime value (e.g. a Date) into the transport form that
+// belongs in the URL (e.g. a timestamp). Keyed by param / search-param name.
+type Marshaler = (value: any) => any
+type Marshalers = Record<string, Marshaler>
+
+// scalarMarshalers builds a name→marshal map for the route's params or search params by
+// looking each declared GraphQL type up in the config's custom scalars. Names without a
+// custom-scalar marshal function are omitted, so callers fall back to String(value).
+// Kept pure (scalars are passed in) so it can be unit-tested without the runtime config.
+export function scalarMarshalers(
+	defs: ReadonlyArray<{ name: string; type?: string }> | undefined,
+	scalars: Record<string, { marshal?: Marshaler } | undefined> | undefined
+): Marshalers {
+	const out: Marshalers = {}
+	for (const def of defs ?? []) {
+		const marshal = def.type ? scalars?.[def.type]?.marshal : undefined
+		if (marshal) {
+			out[def.name] = marshal
+		}
+	}
+	return out
+}
+
+// marshalValue applies the per-key marshaler (if any) and stringifies the result.
+function marshalValue(value: unknown, marshal?: Marshaler): string {
+	return String(marshal ? marshal(value) : value)
+}
+
+// An unmarshaler is the inverse of a Marshaler: it turns the transport form a URL carries
+// back into a rich runtime value (e.g. a timestamp string into a Date).
+type Unmarshaler = (value: any) => any
+type Unmarshalers = Record<string, Unmarshaler>
+
+// scalarUnmarshalers is the read-side mirror of scalarMarshalers: a name→unmarshal map for
+// the declared params/search params whose GraphQL type is a custom scalar. Names without a
+// custom-scalar unmarshal function are omitted (built-ins and UI-only keys are left as-is).
+export function scalarUnmarshalers(
+	defs: ReadonlyArray<{ name: string; type?: string }> | undefined,
+	scalars: Record<string, { unmarshal?: Unmarshaler } | undefined> | undefined
+): Unmarshalers {
+	const out: Unmarshalers = {}
+	for (const def of defs ?? []) {
+		const unmarshal = def.type ? scalars?.[def.type]?.unmarshal : undefined
+		if (unmarshal) {
+			out[def.name] = unmarshal
+		}
+	}
+	return out
+}
+
+// decodeScalar recovers the marshaled value from the string the URL carries. marshalValue
+// wrote it with String(), which dropped the type, so we JSON.parse to get numbers, booleans
+// and null back, falling back to the raw string when it isn't valid JSON (e.g. a custom
+// scalar that marshals to a plain string). Consequence worth documenting: a value like
+// "true" or "123" always decodes to a boolean / number before it reaches unmarshal.
+function decodeScalar(value: string): unknown {
+	try {
+		return JSON.parse(value)
+	} catch {
+		return value
+	}
+}
+
+// unmarshalScalars turns the transport values a parsed query string carries back into rich
+// runtime values for every key that has a custom-scalar unmarshaler. Keys without one
+// (built-ins, UI-only keys) pass through untouched; List values are unmarshaled
+// element-wise. Used for both useRoute().search and the query variables the router feeds
+// back into marshalInputs, so a custom-scalar search param round-trips correctly. When
+// there's nothing to unmarshal the input object is returned as-is (no allocation).
+export function unmarshalScalars(
+	values: Record<string, any>,
+	unmarshalers: Unmarshalers
+): Record<string, any> {
+	if (Object.keys(unmarshalers).length === 0) {
+		return values
+	}
+	const out: Record<string, any> = { ...values }
+	for (const [key, unmarshal] of Object.entries(unmarshalers)) {
+		if (!(key in out) || out[key] == null) {
+			continue
+		}
+		const value = out[key]
+		out[key] = Array.isArray(value)
+			? value.map((entry) => unmarshal(decodeScalar(entry)))
+			: unmarshal(decodeScalar(value))
+	}
+	return out
+}
+
+// the per-route info buildHref needs to marshal: the declared param and search types.
+export type RouteHrefInfo = {
+	params?: ReadonlyArray<{ name: string; type?: string }>
+	searchParams?: ReadonlyArray<{ name: string; type?: string }>
+}
+
+// buildHref assembles a full href for a route: it fills the path params and appends the
+// search string, marshaling custom-scalar values in both so the URL always carries their
+// transport form. This is the one place params + search become a URL, shared by <Link>
+// and goto so they behave identically. `route` provides the type info (undefined for an
+// external href, which is returned untouched).
+export function buildHref(
+	to: string,
+	route: RouteHrefInfo | undefined,
+	scalars: Record<string, { marshal?: Marshaler } | undefined> | undefined,
+	params?: Record<string, unknown>,
+	search?: Record<string, unknown>
+): string {
+	let href =
+		params != null ? resolveHref(to, params, scalarMarshalers(route?.params, scalars)) : to
+	if (search != null) {
+		href += serializeSearch(search, scalarMarshalers(route?.searchParams, scalars))
+	}
+	return href
+}
+
 export function resolveHref(
 	href: string,
-	params: Record<string, string | number | boolean>
+	params: Record<string, unknown>,
+	marshalers?: Marshalers
 ): string {
+	// renders a present param value through its marshaler, or undefined when absent
+	const render = (key: string): string | undefined => {
+		const val = params[key]
+		if (val === undefined || val === null) {
+			return undefined
+		}
+		return marshalValue(val, marshalers?.[key])
+	}
 	// optional [[param]] — strip the whole /[[param]] segment when the value is absent
 	href = href.replace(/\/\[\[([^\]]+)\]\]/g, (_, key: string) => {
-		const val = params[key]
-		return val !== undefined ? '/' + String(val) : ''
+		const val = render(key)
+		return val !== undefined ? '/' + val : ''
 	})
 	// rest [...slug] — substitute [..slug] with the value (or empty string when absent)
-	href = href.replace(/\[\.\.\.([^\]]+)\]/g, (_, key: string) => String(params[key] ?? ''))
+	href = href.replace(/\[\.\.\.([^\]]+)\]/g, (_, key: string) => render(key) ?? '')
 	// regular [param]
-	return href.replace(/\[([^\]]+)\]/g, (_, key: string) => String(params[key] ?? key))
+	return href.replace(/\[([^\]]+)\]/g, (_, key: string) => render(key) ?? key)
+}
+
+// serializeSearch turns a search object into a query string (including the leading
+// "?"), skipping null/undefined values and expanding arrays into repeated keys so
+// they round-trip with List-typed query variables. A custom-scalar value is run
+// through its marshaler so the URL holds the transport form. Returns "" when nothing
+// is set.
+export function serializeSearch(search: Record<string, unknown>, marshalers?: Marshalers): string {
+	const params = new URLSearchParams()
+	for (const [key, value] of Object.entries(search)) {
+		if (value === null || value === undefined) {
+			continue
+		}
+		const marshal = marshalers?.[key]
+		if (Array.isArray(value)) {
+			for (const entry of value) {
+				if (entry !== null && entry !== undefined) {
+					params.append(key, marshalValue(entry, marshal))
+				}
+			}
+		} else {
+			params.append(key, marshalValue(value, marshal))
+		}
+	}
+	const str = params.toString()
+	return str ? '?' + str : ''
 }

package/runtime/routes.ts

@@ -0,0 +1,93 @@
+// this file is part of houdini's generated runtime — do not edit
+//
+// It is the single source of per-route typing: the types here are derived from the
+// generated manifest's shape and drive <Link>, goto(), and createMock so the rules for
+// "which params/search does this route accept" live in exactly one place.
+
+// @ts-ignore
+import type rawManifest from './manifest.js'
+// @ts-ignore
+import type { _TSType } from './manifest.js'
+
+type _Pages = (typeof rawManifest)['pages']
+
+// ---- route params ----
+
+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']>
+}
+
+// ---- search params ----
+
+// Search params are derived from a query's nullable variables, so every key is
+// optional. A `List`-wrapped variable accepts an array (serialized as repeated keys).
+type _SearchParam = {
+	readonly name: string
+	readonly type: string
+	readonly wrappers: readonly string[]
+}
+type _SearchValue<P extends _SearchParam> = 'List' extends P['wrappers'][number]
+	? _TSType<P['type']>[]
+	: _TSType<P['type']>
+// The route's nullable query variables get precise types, but search isn't limited to
+// them: extra keys are allowed so the query string can also carry UI-only state that no
+// query reads (a selected tab, an open modal, a client-side sort). The query consumes
+// only the declared keys; the rest just ride along in the URL.
+type _SearchObj<Ps extends readonly _SearchParam[]> = {
+	[P in Ps[number] as P['name']]?: _SearchValue<P>
+} & Record<string, unknown>
+
+// ---- public route typing ----
+
+// 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
+
+// hrefs that aren't app routes: external links, mailto/tel, fragments, relative paths.
+export type ExternalHref =
+	| `http://${string}`
+	| `https://${string}`
+	| `mailto:${string}`
+	| `tel:${string}`
+	| `blob:${string}`
+	| `data:${string}`
+	| `//${string}`
+	| `#${string}`
+	| `./${string}`
+	| `../${string}`
+
+type _PageForRoute<H extends string> = Extract<_Pages[keyof _Pages], { readonly url: H }>
+
+// params is required (and typed) when the route has dynamic segments, and absent
+// otherwise. Kept a separate intersection so TS evaluates `to` independently — route
+// completions still include parameterized routes even before params is filled in.
+export 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 }
+
+// search is always optional and always open (any route can carry UI-only query string
+// state). When the route declares nullable query variables, those keys get precise
+// types; otherwise search is just an open record of serializable values.
+export type SearchForRoute<H extends string> = [_PageForRoute<H>] extends [never]
+	? { search?: Record<string, unknown> }
+	: _PageForRoute<H> extends { readonly searchParams: infer Ps extends readonly _SearchParam[] }
+		? { search?: _SearchObj<Ps> }
+		: { search?: Record<string, unknown> }
+
+// a typed navigation target: a known route plus its (typed) params and search. Used by
+// goto(); <Link> intersects the same pieces onto its anchor props.
+export type NavTarget<H extends RouteHrefs> = { to: H } & ParamsForRoute<H> & SearchForRoute<H>
+
+// goto() accepts either a ready-made url string (escape hatch) or a typed NavTarget.
+export interface Goto {
+	(url: string): void
+	<H extends RouteHrefs>(target: NavTarget<H>): void
+}

package/runtime/routing/Router.tsx

@@ -12,6 +12,8 @@ import type { RouterManifest, RouterPageManifest } from 'houdini/router/types'
 import React from 'react'
 import { useContext, useEffect } from 'react'
 
+import { buildHref, scalarUnmarshalers, unmarshalScalars } from '../resolve-href.js'
+import type { Goto } from '../routes.js'
 import { type DocumentHandle, useDocumentHandle } from '../hooks/useDocumentHandle.js'
 import { useDocumentStore } from '../hooks/useDocumentStore.js'
 import { type SuspenseCache, suspense_cache } from './cache.js'
@@ -51,11 +53,21 @@ export function Router({
 }) {
 	// the current route is just a string in state.
 	const [currentURL, setCurrentURL] = React.useState(() => {
-		return initialURL || window.location.pathname
+		return initialURL || window.location.pathname + window.location.search
 	})
 
-	// find the matching page for the current route
-	const [page, variables] = find_match(configFile, manifest, currentURL)
+	// find the matching page for the current route. find_match also hands back the parsed
+	// query string (declared search params coerced, UI-only keys raw). custom-scalar route
+	// and search params arrive in their url transport form, so we unmarshal them once here
+	// — the rich values feed both the query variables (which marshalInputs re-marshals for
+	// the request) and useRoute()'s params/search.
+	const [page, rawVariables, rawSearch] = find_match(manifest, currentURL)
+	const unmarshalers = scalarUnmarshalers(
+		[...(page?.params ?? []), ...(page?.searchParams ?? [])],
+		getCurrentConfig()?.scalars
+	)
+	const variables = unmarshalScalars(rawVariables ?? {}, unmarshalers)
+	const search = unmarshalScalars(rawSearch, unmarshalers)
 	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.
@@ -88,7 +100,7 @@ export function Router({
 
 	// whenever the route changes, we need to make sure the browser's stack is up to date
 	React.useEffect(() => {
-		if (globalThis.window && window.location.pathname !== currentURL) {
+		if (globalThis.window && window.location.pathname + window.location.search !== currentURL) {
 			window.history.pushState({}, '', currentURL)
 		}
 	}, [currentURL])
@@ -99,7 +111,7 @@ export function Router({
 			return
 		}
 		const onChange = (_evt: PopStateEvent) => {
-			setCurrentURL(window.location.pathname)
+			setCurrentURL(window.location.pathname + window.location.search)
 		}
 		window.addEventListener('popstate', onChange)
 		return () => {
@@ -107,8 +119,26 @@ export function Router({
 		}
 	}, [])
 
-	// the function to call to navigate to a url
-	const goto = (url: string) => {
+	// the function to call to navigate. accepts either a ready-made url string or a
+	// typed target { to, params, search } that is assembled (and custom scalars
+	// marshaled) exactly the way <Link> builds its href. The typed surface is the
+	// shared Goto contract; the implementation takes the loose runtime shape.
+	const goto = ((
+		target:
+			| string
+			| { to: string; params?: Record<string, unknown>; search?: Record<string, unknown> }
+	) => {
+		const url =
+			typeof target === 'string'
+				? target
+				: buildHref(
+						target.to,
+						manifest.pages[manifest.pagesByUrl[target.to]],
+						getCurrentConfig()?.scalars,
+						target.params,
+						target.search
+					)
+
 		// 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
@@ -116,7 +146,7 @@ export function Router({
 
 		// perform the navigation
 		setCurrentURL(url)
-	}
+	}) as Goto
 
 	// links are powered using anchor tags that we intercept and handle ourselves
 	useLinkBehavior({
@@ -125,10 +155,19 @@ export function Router({
 			// there are 2 things that we could preload: the page component and the data
 
 			// look for the matching route information
-			const [page, variables] = find_match(configFile, manifest, url)
+			const [page, rawVariables] = find_match(manifest, url)
 			if (!page) {
 				return
 			}
+			// unmarshal any custom-scalar route/search params so the preloaded query
+			// marshals them the same way the rendered one does
+			const variables = unmarshalScalars(
+				rawVariables ?? {},
+				scalarUnmarshalers(
+					[...page.params, ...page.searchParams],
+					getCurrentConfig()?.scalars
+				)
+			)
 
 			// load the page component if necessary
 			if (['page', 'component'].includes(which)) {
@@ -146,33 +185,34 @@ export function Router({
 	// render the component embedded in the necessary context so it can orchestrate
 	// its needs
 	return (
-		<VariableContext.Provider value={variables}>
-			<LocationContext.Provider
-				value={{
-					pathname: currentURL,
-					goto,
-					params: variables ?? {},
-				}}
-			>
-				<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>
+		<LocationContext.Provider
+			value={{
+				pathname: currentURL,
+				goto,
+				params: variables ?? {},
+				search,
+			}}
+		>
+			<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>
 	)
 }
 
-// export the location information in context
-export const useLocation = () => useContext(LocationContext)
+// internal accessor for the raw location context. the public surface is useRoute, which
+// layers the per-route param/search types on top of this. not re-exported from the package
+// index, so it isn't part of the public API.
+export const useLocationContext = () => useContext(LocationContext)
 
 export const ClientRedirect = ({ to }: { to: string }) => {
-	const { goto } = useLocation()
+	const { goto } = useLocationContext()
 	useEffect(() => {
 		goto(to)
 	}, [to])
@@ -274,7 +314,23 @@ function usePageData({
 					injectToStream?.(`
 						<script>
 						{
-								window.__houdini__cache__?.hydrate(${cache.serialize()}, window.__houdini__hydration__layer__)
+								// the resolved cache snapshot for this streamed query. when the bootstrap
+								// module has already run (data arrived after hydration) we hydrate the live
+								// cache directly; otherwise the module is still deferred (an @loading query
+								// streams its data while the document is open) so we queue the snapshot for
+								// hydrate_page to apply once it creates the cache. without this the snapshot
+								// would be dropped and the query would hydrate with null data.
+								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__)
+								}
 
 								const artifactName = "${artifact.name}"
 								const value = ${JSON.stringify(
@@ -632,20 +688,18 @@ export function useSession(): [App.Session, (newSession: Partial<App.Session>) =
 	return [ctx.session, updateSession]
 }
 
-export function useCurrentVariables(): GraphQLVariables {
-	return React.useContext(VariableContext)
-}
-
-const VariableContext = React.createContext<GraphQLVariables>(null)
-
 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: (url: string) => void
+	goto: Goto
 }>({
 	pathname: '',
 	params: {},
+	search: {},
 	goto: () => {},
 })
 
@@ -686,7 +740,7 @@ function useLinkBehavior({
 	goto,
 	preload,
 }: {
-	goto: (url: string) => void
+	goto: Goto
 	preload: (url: string, which: PreloadWhichValue) => void
 }) {
 	// always use the click handler
@@ -702,7 +756,7 @@ function useLinkBehavior({
 	}
 }
 
-function useLinkNavigation({ goto }: { goto: (url: string) => void }) {
+function useLinkNavigation({ goto }: { goto: Goto }) {
 	// navigations need to be registered as transitions
 	const [_pending, startTransition] = React.useTransition()
 
@@ -925,7 +979,7 @@ export function PageContextProvider({
 	keys: string[]
 	children: React.ReactNode
 }) {
-	const location = useLocation()
+	const location = useLocationContext()
 	const params = Object.fromEntries(
 		Object.entries(location.params).filter(([key]) => keys.includes(key))
 	)
@@ -933,12 +987,42 @@ export function PageContextProvider({
 	return <PageContext.Provider value={{ params }}>{children}</PageContext.Provider>
 }
 
-export function useRoute<PageProps extends { Params: {} }>(): RouteProp<PageProps['Params']> {
-	return useContext(PageContext)
+// useRoute is the single hook for reading the current route: the route's params (scoped to
+// this route's path segments) and search, both typed when a generated PageRoute/LayoutRoute
+// is supplied, plus the current pathname and goto. This replaces the old useLocation —
+// params/search live here rather than on the component props. Unlike a conventional
+// useLocation it also carries params and goto, which is why it's named for the route.
+export function useRoute<
+	// the default leaves params/search empty (not a loose record) so that reading them
+	// without passing the route's generated PageRoute type is a compile error, while
+	// pathname and goto stay available for navigation-only code.
+	_Route extends { params: any; search: any } = { params: {}; search: {} },
+>(): {
+	pathname: string
+	params: _Route['params']
+	search: _Route['search']
+	goto: Goto
+} {
+	const location = useLocationContext()
+	const route = useContext(PageContext)
+	return {
+		pathname: location.pathname,
+		params: route.params as _Route['params'],
+		search: location.search as _Route['search'],
+		goto: location.goto,
+	}
 }
 
-export type RouteProp<Params> = {
-	params: Params
+// A route shape for useRoute. A route's generated PageRoute/LayoutRoute already satisfies the
+// `{ params; search }` shape, so the common case is useRoute<PageRoute>(). For a route-agnostic
+// component (e.g. a reusable paginator that assumes its route exposes `after`/`first` search
+// params) there's no single generated type to pass — use GenericRoute to type the axis you
+// depend on and leave the other `never` (which falls back to a loose record). Search comes
+// first since that's the usual reason to reach for it, so a search-only component writes
+// GenericRoute<{ ... }> and a params-only one writes GenericRoute<never, { ... }>.
+export type GenericRoute<Search = never, Params = never> = {
+	params: [Params] extends [never] ? Record<string, any> : Params
+	search: [Search] extends [never] ? Record<string, any> : Search
 }
 
 // a signal promise is a promise is used to send signals by having listeners attach