houdini-react 2.0.0-next.9 → 2.0.0

package/runtime/index.tsx

@@ -0,0 +1,77 @@
+import type { GraphQLObject } from 'houdini/runtime'
+import type { Cache } from 'houdini/runtime/cache'
+
+import client from './client.js'
+import manifest from './manifest.js'
+import {
+	Router as RouterImpl,
+	type RouterCache,
+	type FormResult,
+	RouterContextProvider,
+} from './routing/index.js'
+
+export * from './hooks/index.js'
+export {
+	router_cache,
+	useCache,
+	useSession,
+	useRoute,
+	notFound,
+	unauthorized,
+	forbidden,
+	httpError,
+	redirect,
+	isRoutingError,
+	isApiError,
+	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,
+	initialURL,
+	artifact_cache,
+	component_cache,
+	data_cache,
+	ssr_signals,
+	last_variables,
+	session,
+	formResult,
+	formToken,
+	assetPrefix,
+	injectToStream,
+}: {
+	initialURL: string
+	initialVariables: GraphQLObject
+	cache: Cache
+	session?: App.Session
+	formResult?: FormResult | null
+	formToken?: string | null
+	assetPrefix: string
+	injectToStream?: (chunk: string) => void
+} & RouterCache) {
+	return (
+		<RouterContextProvider
+			client={client()}
+			cache={cache}
+			artifact_cache={artifact_cache}
+			component_cache={component_cache}
+			data_cache={data_cache}
+			ssr_signals={ssr_signals}
+			last_variables={last_variables}
+			session={session}
+			formResult={formResult}
+			formToken={formToken}
+		>
+			<RouterImpl
+				initialURL={initialURL}
+				manifest={manifest}
+				assetPrefix={assetPrefix}
+				injectToStream={injectToStream}
+			/>
+		</RouterContextProvider>
+	)
+}

package/runtime/login.ts

@@ -0,0 +1,22 @@
+import { getAuthUrl } from 'houdini/runtime'
+
+// loginURL builds the URL for Houdini's redirect-login entry point (`/login`). Point a link at it
+// to start the flow: `redirectTo` is where the user lands afterward (passed as a query param on
+// this initial request, then captured into a signed cookie server-side for the OAuth round-trip) —
+// omit it to return the user to the page they came from. `params`
+// are forwarded verbatim to the trusted integration (e.g. `{ provider: 'github' }`) — Houdini stays
+// out of the provider business.
+//
+// This helper is only exported from `$houdini` when `auth.redirect` is configured in
+// `src/server/+config`; without a trusted integration there is no flow to start.
+export function loginURL(opts?: { redirectTo?: string; params?: Record<string, string> }): string {
+	const search = new URLSearchParams()
+	if (opts?.redirectTo) {
+		search.set('redirectTo', opts.redirectTo)
+	}
+	for (const [key, value] of Object.entries(opts?.params ?? {})) {
+		search.set(key, value)
+	}
+	const qs = search.toString()
+	return `${getAuthUrl()}/login${qs ? `?${qs}` : ''}`
+}

package/runtime/manifest.ts

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

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.')
+}

package/runtime/package.json

@@ -0,0 +1 @@
+{"type":"module","main":"./index.tsx"}

package/runtime/resolve-href.ts

@@ -0,0 +1,151 @@
+import { unmarshalValue, type Unmarshaler } from 'houdini/runtime'
+
+// 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). The shared
+// coercion core (houdini/runtime) owns the type and the per-leaf logic.
+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
+}
+
+// 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 (via the shared coercion core). 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
+		}
+		out[key] = unmarshalValue(out[key], unmarshal)
+	}
+	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, 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 = render(key)
+		return val !== undefined ? '/' + val : ''
+	})
+	// rest [...slug] — substitute [..slug] with the value (or empty string when absent)
+	href = href.replace(/\[\.\.\.([^\]]+)\]/g, (_, key: string) => render(key) ?? '')
+	// regular [param]
+	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
+}