houdini-react 2.0.0-next.9 → 2.0.0

package/runtime/hooks/useDocumentSubscription.ts

@@ -0,0 +1,65 @@
+import type {
+	DocumentArtifact,
+	GraphQLVariables,
+	QueryResult,
+	GraphQLObject,
+} from 'houdini/runtime'
+import type { DocumentStore, SendParams } from 'houdini/runtime/client'
+
+import { useSession } from '../routing/Router.js'
+import useDeepCompareEffect from './useDeepCompareEffect.js'
+import { useDocumentStore, type UseDocumentStoreParams } from './useDocumentStore.js'
+
+export function useDocumentSubscription<
+	_Artifact extends DocumentArtifact = DocumentArtifact,
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+>({
+	artifact,
+	variables,
+	send,
+	initialState,
+	disabled,
+	...observeParams
+}: UseDocumentStoreParams<_Artifact, _Data, _Input> & {
+	variables: _Input
+	disabled?: boolean
+	send?: Partial<Omit<SendParams, 'initialState'>>
+}): [QueryResult<_Data, _Input> & { parent?: string | null }, DocumentStore<_Data, _Input>] {
+	const [storeValue, observer] = useDocumentStore<_Data, _Input>({
+		artifact,
+		initialState,
+		...observeParams,
+	})
+
+	// grab the current session value
+	const [session] = useSession()
+
+	// whenever the variables change, we need to retrigger the query
+	useDeepCompareEffect(() => {
+		if (!disabled) {
+			observer.send({
+				variables,
+				session,
+				// TODO: metadata
+				metadata: {},
+				...send,
+				initialState,
+			})
+		}
+
+		return () => {
+			if (!disabled) {
+				observer.cleanup()
+			}
+		}
+	}, [disabled, session, observer, variables ?? {}, send ?? {}])
+
+	return [
+		{
+			parent: send?.stuff?.parentID,
+			...storeValue,
+		},
+		observer,
+	]
+}

package/runtime/hooks/useFragment.ts

@@ -0,0 +1,269 @@
+import { fragmentKey } from 'houdini/runtime'
+import type {
+	GraphQLObject,
+	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 {},
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	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>(
+		reference,
+		document
+	)
+
+	// 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])
+
+	// 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]
+	)
+
+	const [storeValue] = useDocumentSubscription<FragmentArtifact, _Data, _Input>({
+		artifact: document.artifact,
+		variables,
+		initialValue: cachedValue,
+		// 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,
+			},
+			setup: true,
+		},
+		initialState,
+	})
+
+	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 }
+): { variables: _Input; parent: string; loading: boolean } {
+	// @ts-expect-error: typescript can't guarantee that the fragment key is defined
+	// but if its not, then the fragment wasn't mixed into the right thing
+	// the variables for the fragment live on the initial value's $fragment key
+	const { variables, parent } = reference?.[fragmentKey]?.values?.[document.artifact.name] ?? {}
+	if (reference && fragmentKey in reference && (!variables || !parent)) {
+		console.warn(
+			`⚠️ Parent does not contain the information for this fragment. Something is wrong.
+Please ensure that you have passed a record that has ${document.artifact.name} mixed into it.`
+		)
+	}
+	// @ts-expect-error
+	const loading = Boolean(reference?.[fragmentKey]?.loading)
+
+	return { variables, parent, loading }
+}

package/runtime/hooks/useFragmentHandle.ts

@@ -0,0 +1,274 @@
+import {
+	extractPageInfo,
+	cursorHandlers,
+	offsetHandlers,
+	getCurrentConfig,
+	entityRefetchVariables,
+} from 'houdini/runtime'
+import type {
+	GraphQLObject,
+	FragmentArtifact,
+	QueryArtifact,
+	GraphQLVariables,
+	FetchFn,
+} from 'houdini/runtime'
+import * as React from 'react'
+
+import { useClient, useSession } from '../routing/Router.js'
+import type { DocumentHandle } from './useDocumentHandle.js'
+import { fragmentReference, useFragment } from './useFragment.js'
+
+// useFragmentHandle is just like useFragment except it also returns an imperative handle
+// that users can use to interact with the fragment
+export function useFragmentHandle<
+	_Artifact extends FragmentArtifact,
+	_Data extends GraphQLObject,
+	_ReferenceType extends {},
+	_PaginationArtifact extends QueryArtifact,
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	reference: _Data | { ' $fragments': _ReferenceType } | null,
+	document: { artifact: FragmentArtifact; refetchArtifact?: QueryArtifact }
+): any {
+	const fragmentData = useFragment<_Data, _ReferenceType, _Input>(reference, document)
+	const { variables, loading } = fragmentReference<_Data, _Input, _ReferenceType>(
+		reference,
+		document
+	)
+
+	const client = useClient()
+	const [session] = useSession()
+
+	const [forwardPending, setForwardPending] = React.useState(false)
+	const [backwardPending, setBackwardPending] = React.useState(false)
+
+	const previousCursorsRef = React.useRef<(string | null)[]>([])
+	const nextCursorsRef = React.useRef<(string | null)[]>([])
+
+	const refetchArtifact = document.refetchArtifact as QueryArtifact | undefined
+	const refetchPath = refetchArtifact?.refetch?.path
+
+	const paginationObserver = React.useMemo(() => {
+		if (!refetchArtifact?.refetch?.paginated) return null
+		return client.observe<_Data, _Input>({ artifact: refetchArtifact })
+	}, [refetchArtifact?.name])
+
+	const isSinglePage = refetchArtifact?.refetch?.mode === 'SinglePage'
+
+	// Subscribe to the pagination observer so the component re-renders when a new page lands.
+	// For SinglePage we pass disablePartial so partial cache hits (entity found but connection
+	// not yet fetched) are never resolved back to the observer — we go straight to the network
+	// and update the observer only once we have a complete page.
+	const subscribeToObserver = React.useCallback(
+		(fn: () => void) => paginationObserver?.subscribe(() => fn()) ?? (() => {}),
+		[paginationObserver]
+	)
+	const getObserverSnapshot = React.useCallback(
+		() => paginationObserver?.state.data ?? null,
+		[paginationObserver]
+	)
+	const paginationData = React.useSyncExternalStore(
+		subscribeToObserver,
+		getObserverSnapshot,
+		getObserverSnapshot
+	)
+
+	const paginationEntityData = React.useMemo<_Data | null>(() => {
+		if (!paginationData || !refetchArtifact?.selection?.fields) return null
+		const rootField = Object.keys(refetchArtifact.selection.fields)[0]
+		if (!rootField) return null
+		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
+			: isRefetchable && refetchEntityData !== null
+				? refetchEntityData
+				: fragmentData
+
+	const wrapLoad = <_Result>(
+		setLoading: (val: boolean) => void,
+		fn: (value: any) => Promise<_Result>
+	) => {
+		return async (value: any) => {
+			setLoading(true)
+			let err: Error | null = null
+			let result: _Result | null = null
+			try {
+				result = await fn(value)
+			} catch (e) {
+				err = e as Error
+			}
+			setLoading(false)
+			if (err && err.name !== 'AbortError') throw err
+			return result
+		}
+	}
+
+	const handle = React.useMemo(() => {
+		if (!refetchArtifact?.refetch?.paginated || !paginationObserver) return null
+
+		const fetchFn: FetchFn<_Data, _Input> = (args) => {
+			return paginationObserver.send({
+				...args,
+				session,
+				stuff: { silenceLoading: true },
+				cacheParams: {
+					disableSubscriptions: true,
+					// Suppress partial cache hits so an in-flight forward navigation never
+					// briefly resolves with an entity that is missing its connection field.
+					// Full cache hits (partial: false) still resolve, so backward navigation
+					// continues to be served instantly from cache.
+					disablePartial: true,
+				},
+			})
+		}
+
+		const fetchUpdate = (args: any, updates: string[]) => {
+			return paginationObserver.send({
+				...args,
+				cacheParams: {
+					...args?.cacheParams,
+					disableSubscriptions: true,
+					applyUpdates: updates,
+				},
+				session,
+			})
+		}
+
+		if (refetchArtifact.refetch!.method === 'cursor') {
+			const handlers = cursorHandlers<_Data, _Input>({
+				artifact: refetchArtifact,
+				getState: () => displayData as _Data | null,
+				getVariables: () =>
+					(paginationObserver.state.variables ?? variables) as NonNullable<_Input>,
+				// no-op pagination while the parent is still in its @loading state (issue #1408)
+				getLoading: () => loading,
+				fetch: fetchFn,
+				fetchUpdate,
+				getSession: async () => session,
+				previousCursors: previousCursorsRef.current,
+				nextCursors: nextCursorsRef.current,
+			})
+
+			return {
+				loadNext: wrapLoad(setForwardPending, handlers.loadNextPage),
+				loadNextPending: forwardPending,
+				loadPrevious: wrapLoad(setBackwardPending, handlers.loadPreviousPage),
+				loadPreviousPending: backwardPending,
+				pageInfo: refetchPath
+					? extractPageInfo(displayData as GraphQLObject, refetchPath)
+					: null,
+			}
+		}
+
+		if (refetchArtifact.refetch!.method === 'offset') {
+			const handlers = offsetHandlers({
+				artifact: refetchArtifact,
+				getState: () => displayData as _Data | null,
+				getVariables: () =>
+					(paginationObserver.state.variables ?? variables) as NonNullable<_Input>,
+				// no-op pagination while the parent is still in its @loading state (issue #1408)
+				getLoading: () => loading,
+				storeName: refetchArtifact.name,
+				fetch: fetchFn,
+				fetchUpdate: async (args: any, updates = ['append']) =>
+					fetchUpdate(args, updates) as any,
+				getSession: async () => session,
+			})
+
+			return {
+				loadNext: wrapLoad(setForwardPending, handlers.loadNextPage),
+				loadNextPending: forwardPending,
+			}
+		}
+
+		return null
+	}, [
+		refetchArtifact,
+		paginationObserver,
+		displayData,
+		session,
+		forwardPending,
+		backwardPending,
+		loading,
+	])
+
+	// 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: displayVariables,
+		data: displayData,
+		refetch,
+	}
+}

package/runtime/hooks/useIsMounted.ts

@@ -0,0 +1,14 @@
+import { useRef, useEffect } from 'react'
+
+export function useIsMountedRef(): { current: boolean } {
+	const isMountedRef = useRef(true)
+
+	useEffect(() => {
+		isMountedRef.current = true
+		return () => {
+			isMountedRef.current = false
+		}
+	}, [])
+
+	return isMountedRef
+}

package/runtime/hooks/useLogoutForm.tsx

@@ -0,0 +1,60 @@
+import { getAuthUrl } from 'houdini/runtime'
+import React from 'react'
+
+import { useSession, useRoute } from '../routing/Router.js'
+
+export type UseLogoutFormOptions = {
+	// where to navigate after logout. The no-JS path 303s here from the server; the enhanced
+	// path navigates with goto(). Defaults to '/'.
+	redirectTo?: string
+	// enhanced-path-only side effect (a no-op without JS, the correct degradation)
+	onSuccess?: () => void
+}
+
+export type LogoutForm = {
+	// spread onto a <form>: a real string action so the native POST clears the session before
+	// hydration; the onSubmit intercepts after. Identical server/client → clean hydration.
+	form: {
+		action: string
+		method: 'post'
+		onSubmit: (event: React.FormEvent<HTMLFormElement>) => void
+	}
+	// the hidden marker fields the no-JS POST needs; render inside the <form>
+	hidden: React.ReactNode
+}
+
+/**
+ * useLogoutForm renders a progressively-enhanced logout form. Without JS the native POST hits
+ * the auth endpoint, which deletes the session cookie and 303s to `redirectTo`. After
+ * hydration the onSubmit clears the session client-side (local state + cookie) and navigates.
+ * It mirrors `useMutationForm`, but there's no mutation — logout is just "clear the session".
+ */
+export function useLogoutForm(opts: UseLogoutFormOptions = {}): LogoutForm {
+	const [, updateSession] = useSession()
+	const { goto } = useRoute()
+	const redirectTo = opts.redirectTo ?? '/'
+
+	const onSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
+		// only reached after hydration — before that the browser submits natively
+		event.preventDefault()
+		// null logs out: clears local state and deletes the cookie
+		await updateSession(null)
+		opts.onSuccess?.()
+		goto(redirectTo)
+	}
+
+	const form: LogoutForm['form'] = {
+		action: getAuthUrl(),
+		method: 'post',
+		onSubmit,
+	}
+
+	const hidden = (
+		<>
+			<input type="hidden" name="__houdini_logout" value="1" />
+			<input type="hidden" name="redirectTo" value={redirectTo} />
+		</>
+	)
+
+	return { form, hidden }
+}