houdini-react 2.0.0-next.4 → 2.0.0-next.40

package/runtime/Link.tsx

@@ -0,0 +1,81 @@
+// this file is generated by houdini — do not edit
+// @refresh reset
+import type { AnchorHTMLAttributes, DetailedHTMLProps } from 'react'
+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}`
+
+// 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
+
+// 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 }
+
+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>
+
+export function Link<H extends RouteHrefs | _ExternalHref>({
+	to,
+	params,
+	disabled,
+	preload,
+	...rest
+}: LinkProps<H>): React.ReactElement {
+	const href = disabled
+		? undefined
+		: params != null
+			? resolveHref(to as string, params as Record<string, string | number | boolean>)
+			: (to as string)
+	return React.createElement('a', { ...rest, href, 'data-houdini-preload': preload })
+}

package/runtime/client.ts

@@ -0,0 +1,5 @@
+import type { HoudiniClient } from '$houdini/runtime/client'
+
+// this file will be replaced by the code generation process
+
+export default (() => {}) as () => HoudiniClient

package/runtime/clientPlugin.ts

@@ -0,0 +1,17 @@
+import type { ClientPlugin } from 'houdini/runtime/client'
+
+const plugin: () => ClientPlugin = () => () => {
+	return {
+		start(ctx, { next }) {
+			next({
+				...ctx,
+				cacheParams: {
+					...ctx.cacheParams,
+					serverSideFallback: false,
+				},
+			})
+		},
+	}
+}
+
+export default plugin

package/runtime/componentFields.ts

@@ -0,0 +1,79 @@
+import { getFieldsForType } from 'houdini/runtime'
+import type { DocumentArtifact, GraphQLObject, GraphQLValue } from 'houdini/runtime'
+import { defaultComponentField, type Cache } from 'houdini/runtime/cache'
+
+export function injectComponents({
+	cache,
+	selection,
+	data,
+	variables,
+	parentType = 'Query',
+}: {
+	cache: Cache
+	selection: DocumentArtifact['selection']
+	data: GraphQLValue | null
+	variables: Record<string, GraphQLValue> | undefined | null
+	parentType?: string
+}) {
+	// if the value is null, we're done
+	if (data === null) {
+		return
+	}
+
+	// if the value is not an object (ie its a scalar) we're done
+	if (typeof data !== 'object') {
+		return
+	}
+	data = data as GraphQLObject
+
+	// if the value is an array we need to instantiate each item
+	if (Array.isArray(data)) {
+		data.forEach((item) => {
+			injectComponents({
+				cache,
+				selection,
+				data: item,
+				variables,
+				parentType,
+			})
+		})
+		return
+	}
+
+	// if the object has a subselection we need to walk down
+	const typename = '__typename' in data ? (data.__typename as string) : ''
+	const fields = getFieldsForType(selection, typename, false)
+	if (!fields) {
+		return
+	}
+
+	// walk down each field
+	for (const [field, subSelection] of Object.entries(fields)) {
+		// if the field is a component then we need to assign the value to the target
+		if (subSelection.component) {
+			// if the component is already in the cache, we're done
+			if (!cache._internal_unstable.componentCache[subSelection.component.key]) {
+				continue
+			}
+
+			data[field] = defaultComponentField({
+				variables,
+				parent: cache._internal_unstable.id(parentType, data) ?? '',
+				cache,
+				component: subSelection.component,
+			}) as any as GraphQLValue
+		}
+
+		// if there is a selection, we need to walk down
+		const dataValue = data[field]
+		if (subSelection.selection) {
+			injectComponents({
+				cache,
+				selection: subSelection.selection,
+				data: dataValue,
+				variables,
+				parentType: subSelection.type,
+			})
+		}
+	}
+}

package/runtime/hooks/index.ts

@@ -0,0 +1,9 @@
+export { useQuery } from './useQuery.js'
+export { useQueryHandle } from './useQueryHandle.js'
+export { useFragment } from './useFragment.js'
+export { useFragmentHandle } from './useFragmentHandle.js'
+export { useMutation } from './useMutation.js'
+export { useSubscription } from './useSubscription.js'
+
+export type { DocumentHandle } from './useDocumentHandle.js'
+export type { UseQueryConfig } from './useQueryHandle.js'

package/runtime/hooks/recycleNodesInto.ts

@@ -0,0 +1,60 @@
+/**
+ * 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
+
+		// Copy non-index own properties from next (e.g. __id from @includeListID)
+		for (const key of Object.keys(next as any)) {
+			if (isNaN(Number(key))) {
+				;(result as any)[key] = (next as any)[key]
+			}
+		}
+		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

@@ -0,0 +1,93 @@
+import { deepEquals } from 'houdini/runtime'
+import * as React from 'react'
+
+// This file is largely a copy and paste from Kent C. Dodd's use-deep-compare-effect (appropriate license at the bottom).
+// It has been copied locally in order to avoid any awkward third party peer dependencies
+// on generated files (which would make the install annoying). The deep equals library has
+// also been changed to use one that was already included in the runtime (avoiding the extra bundle size)
+
+type UseEffectParams = Parameters<typeof React.useEffect>
+type EffectCallback = UseEffectParams[0]
+type DependencyList = UseEffectParams[1]
+// yes, I know it's void, but I like what this communicates about
+// the intent of these functions: It's just like useEffect
+type UseEffectReturn = ReturnType<typeof React.useEffect>
+
+function checkDeps(deps: DependencyList) {
+	if (!deps?.length) {
+		throw new Error(
+			'useDeepCompareEffect should not be used with no dependencies. Use React.useEffect instead.'
+		)
+	}
+	if (deps.every(isPrimitive)) {
+		throw new Error(
+			'useDeepCompareEffect should not be used with dependencies that are all primitive values. Use React.useEffect instead.'
+		)
+	}
+}
+
+function isPrimitive(val: unknown) {
+	return val == null || /^[sbn]/.test(typeof val)
+}
+
+/**
+ * @param value the value to be memoized (usually a dependency list)
+ * @returns a memoized version of the value as long as it remains deeply equal
+ */
+export function useDeepCompareMemoize<T>(value: T) {
+	const ref = React.useRef<T>(value)
+
+	if (!deepEquals(value, ref.current)) {
+		ref.current = value
+	}
+
+	// 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(
+	callback: EffectCallback,
+	dependencies: DependencyList
+): UseEffectReturn {
+	if (process.env.NODE_ENV !== 'production') {
+		checkDeps(dependencies)
+	}
+	// biome-ignore lint/correctness/useExhaustiveDependencies: intentional deep-compare effect
+	return React.useEffect(callback, useDeepCompareMemoize(dependencies))
+}
+
+export function useDeepCompareEffectNoCheck(
+	callback: EffectCallback,
+	dependencies: DependencyList
+): UseEffectReturn {
+	// biome-ignore lint/correctness/useExhaustiveDependencies: intentional deep-compare effect
+	return React.useEffect(callback, useDeepCompareMemoize(dependencies))
+}
+
+export default useDeepCompareEffect
+
+/**
+The MIT License (MIT)
+Copyright (c) 2020 Kent C. Dodds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/

package/runtime/hooks/useDocumentHandle.ts

@@ -0,0 +1,238 @@
+import { extractPageInfo } from 'houdini/runtime'
+import { cursorHandlers, offsetHandlers } from 'houdini/runtime'
+import { ArtifactKind } from 'houdini/runtime'
+import type {
+	GraphQLObject,
+	GraphQLVariables,
+	GraphQLError,
+	CursorHandlers,
+	OffsetHandlers,
+	PageInfo,
+	FetchFn,
+	QueryResult,
+	DocumentArtifact,
+	QueryArtifact,
+} from 'houdini/runtime'
+import type { DocumentStore } from 'houdini/runtime/client'
+import React from 'react'
+
+import { useClient, useLocation, useSession } from '../routing/Router.js'
+
+export function useDocumentHandle<
+	_Artifact extends QueryArtifact,
+	_Data extends GraphQLObject,
+	_Input extends GraphQLVariables,
+>({
+	artifact,
+	observer,
+	storeValue,
+}: {
+	artifact: DocumentArtifact
+	observer: DocumentStore<_Data, _Input>
+	storeValue: QueryResult<_Data, _Input>
+}): DocumentHandle<_Artifact, _Data, _Input> & { fetch: FetchFn<_Data, _Input> } {
+	const [forwardPending, setForwardPending] = React.useState(false)
+	const [backwardPending, setBackwardPending] = React.useState(false)
+	// 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()
+
+	// grab the current session value
+	const [session] = useSession()
+
+	// we want to use a separate observer for pagination queries
+	const client = useClient()
+	const paginationObserver = React.useMemo(() => {
+		// if the artifact doesn't support pagination, don't do anything
+		if (!artifact.refetch?.paginated) {
+			return null
+		}
+
+		return client.observe<_Data, _Input>({ artifact })
+	}, [artifact.name, artifact, client.observe])
+
+	// @ts-expect-error: avoiding an as DocumentHandle<_Artifact, _Data, _Input>
+	return React.useMemo<DocumentHandle<_Artifact, _Data, _Input>>(() => {
+		const wrapLoad = <_Result>(
+			setLoading: (val: boolean) => void,
+			fn: (value: any) => Promise<_Result>
+		) => {
+			return async (value: any) => {
+				setLoading(true)
+				let result: _Result | null = null
+				let err: Error | null = null
+				try {
+					result = await fn(value)
+				} catch (e) {
+					err = e as Error
+				}
+				setLoading(false)
+				// ignore abort errors when loading pages
+				if (err && err.name !== 'AbortError') {
+					throw err
+				}
+
+				// we're done
+				return result || observer.state
+			}
+		}
+
+		// add the session value to the
+		const fetchQuery: FetchFn<_Data, _Input> = (args) => {
+			// before we send the query, we need to figure out which variables are
+			// actually useful for this document
+			const usedVariables = Object.fromEntries(
+				Object.keys(observer.artifact.input?.fields ?? {}).reduce<[string, any][]>(
+					(entries, fieldName) => {
+						// if the field is not a url parameter, skip it
+						if (!(fieldName in location.params)) {
+							return entries
+						}
+
+						return [...entries, [fieldName, location.params[fieldName]]]
+					},
+					[]
+				)
+			)
+
+			return observer.send({
+				...args,
+				variables: {
+					...usedVariables,
+					...args?.variables,
+				},
+				session,
+			})
+		}
+
+		const baseFields = {
+			artifact,
+			data: storeValue.data,
+			variables: storeValue.variables,
+			partial: storeValue.partial,
+			fetching: storeValue.fetching,
+			errors: storeValue.errors,
+		}
+
+		// only consider paginated queries
+		if (artifact.kind !== ArtifactKind.Query || !artifact.refetch?.paginated) {
+			return {
+				...baseFields,
+				fetch: fetchQuery,
+			}
+		}
+
+		// if the artifact supports cursor pagination, then add the cursor handlers
+		if (artifact.refetch.method === 'cursor') {
+			const handlers = cursorHandlers<_Data, _Input>({
+				artifact,
+				getState: () => storeValue.data,
+				getVariables: () => storeValue.variables!,
+				fetch: fetchQuery,
+				previousCursors: previousCursorsRef.current,
+				nextCursors: nextCursorsRef.current,
+				fetchUpdate: (args, updates) => {
+					return paginationObserver!.send({
+						...args,
+						cacheParams: {
+							...args?.cacheParams,
+							disableSubscriptions: true,
+							applyUpdates: updates,
+						},
+						session,
+					})
+				},
+				getSession: async () => session,
+			})
+
+			return {
+				...baseFields,
+				fetch: handlers.fetch,
+				loadNext: wrapLoad(setForwardPending, handlers.loadNextPage),
+				loadNextPending: forwardPending,
+				loadPrevious: wrapLoad(setBackwardPending, handlers.loadPreviousPage),
+				loadPreviousPending: backwardPending,
+				pageInfo: extractPageInfo(storeValue.data, artifact.refetch!.path),
+			}
+		}
+
+		if (artifact.refetch.method === 'offset') {
+			const handlers = offsetHandlers({
+				artifact,
+				getState: () => storeValue.data,
+				getVariables: () => storeValue.variables!,
+				storeName: artifact.name,
+				fetch: fetchQuery,
+				fetchUpdate: async (args, updates = ['append']) => {
+					return paginationObserver!.send({
+						...args,
+						cacheParams: {
+							disableSubscriptions: true,
+							applyUpdates: updates,
+							...args?.cacheParams,
+						},
+					})
+				},
+				getSession: async () => session,
+			})
+
+			return {
+				...baseFields,
+				fetch: handlers.fetch,
+				loadNext: wrapLoad(setForwardPending, handlers.loadNextPage),
+				loadNextPending: forwardPending,
+			}
+		}
+
+		// we don't want to add anything
+		return {
+			...baseFields,
+			fetch: fetchQuery,
+			refetch: fetchQuery,
+		}
+	}, [
+		artifact,
+		observer,
+		session,
+		storeValue,
+		backwardPending,
+		forwardPending,
+		paginationObserver,
+		location.params,
+	])
+}
+
+export type DocumentHandle<
+	_Artifact extends QueryArtifact,
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+> = {
+	data: _Data
+	partial: boolean
+	fetching: boolean
+	errors: GraphQLError[] | null
+	fetch: FetchFn<_Data, Partial<_Input>>
+	variables: _Input
+} & RefetchHandlers<_Artifact, _Data, _Input>
+
+type RefetchHandlers<_Artifact extends QueryArtifact, _Data extends GraphQLObject, _Input> =
+	// we need to add different methods if the artifact supports cursor pagination
+	_Artifact extends {
+		refetch: { paginated: true; method: 'cursor' }
+	}
+		? {
+				loadNext: CursorHandlers<_Data, _Input>['loadNextPage']
+				loadNextPending: boolean
+				loadPrevious: CursorHandlers<_Data, _Input>['loadPreviousPage']
+				loadPreviousPending: boolean
+				pageInfo: PageInfo
+			}
+		: // offset pagination
+			_Artifact extends { refetch: { paginated: true; method: 'offset' } }
+			? {
+					loadNext: OffsetHandlers<_Data, _Input>['loadNextPage']
+					loadNextPending: boolean
+				}
+			: // the artifact does not support a known pagination method, don't add anything
+				{}

package/runtime/hooks/useDocumentStore.ts

@@ -0,0 +1,112 @@
+import type {
+	DocumentArtifact,
+	GraphQLVariables,
+	QueryResult,
+	GraphQLObject,
+} from 'houdini/runtime'
+import type { DocumentStore, ObserveParams } from 'houdini/runtime/client'
+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,
+	_Data extends GraphQLObject,
+	_Input extends GraphQLVariables,
+> = {
+	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<
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+	_Artifact extends DocumentArtifact = DocumentArtifact,
+>({
+	artifact,
+	observer: obs,
+	initialState,
+	...observeParams
+}: UseDocumentStoreParams<_Artifact, _Data, _Input>): [
+	QueryResult<_Data, _Input>,
+	DocumentStore<_Data, _Input>,
+] {
+	const client = useClient()
+	const isMountedRef = useIsMountedRef()
+
+	// hold onto an observer we'll use
+	const [observer, setObserver] = React.useState(
+		() =>
+			obs ??
+			client.observe<_Data, _Input>({
+				artifact,
+				...observeParams,
+			})
+	)
+
+	const box = React.useRef(observer.state)
+
+	// if the observer changes, we need to track the new one
+	if (obs && obs !== observer) {
+		box.current = obs.state
+		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) => {
+				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()
+				}
+			})
+		},
+		[observer, isMountedRef.current]
+	)
+
+	// get a safe reference to the cache
+	const storeValue = React.useSyncExternalStore(
+		subscribe,
+		() => box.current,
+		() => box.current
+	)
+
+	return [storeValue!, observer]
+}