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

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,101 @@
+import { fragmentKey } from 'houdini/runtime'
+import type {
+	GraphQLObject,
+	GraphQLVariables,
+	FragmentArtifact,
+	QueryResult,
+} from 'houdini/runtime'
+import * as React from 'react'
+
+import { useRouterContext } from '../routing/index.js'
+import { useDocumentSubscription } from './useDocumentSubscription.js'
+
+export function useFragment<
+	_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,
+		disabled: loading,
+		send: {
+			stuff: {
+				parentID: parent,
+			},
+			setup: true,
+		},
+		initialState,
+	})
+
+	return storeValue.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,191 @@
+import { extractPageInfo, cursorHandlers, offsetHandlers } 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 {
+	// get the fragment values
+	const fragmentData = useFragment<_Data, _ReferenceType, _Input>(reference, document)
+
+	// look at the fragment reference to get the variables
+	const { variables } = fragmentReference<_Data, _Input, _ReferenceType>(reference, document)
+
+	const client = useClient()
+	const [session] = useSession()
+
+	const [forwardPending, setForwardPending] = React.useState(false)
+	const [backwardPending, setBackwardPending] = React.useState(false)
+
+	// Stable cursor stacks for SinglePage pagination — must survive re-renders
+	const previousCursorsRef = React.useRef<(string | null)[]>([])
+	const nextCursorsRef = React.useRef<(string | null)[]>([])
+
+	const refetchArtifact = document.refetchArtifact as QueryArtifact | undefined
+	const refetchPath = refetchArtifact?.refetch?.path
+
+	// Dedicated observer for pagination queries — separate from the fragment observer.
+	// cursorHandlers derives entity variables (e.g. { id }) and artifact defaults
+	// automatically via the type config, so no manual variable extraction is needed here.
+	const paginationObserver = React.useMemo(() => {
+		if (!refetchArtifact?.refetch?.paginated) return null
+		return client.observe<_Data, _Input>({ artifact: refetchArtifact })
+	}, [refetchArtifact?.name])
+
+	// Subscribe to the pagination observer so React re-renders whenever a new page is fetched
+	// or served from cache (CacheOrNetwork). The fragment store subscription only watches the
+	// initial page's cache key; the observer is the live source of truth for SinglePage
+	// pagination where each page lives at its own per-cursor cache key.
+	const subscribeToObserver = React.useCallback(
+		(onChange: () => void) => {
+			if (!paginationObserver) return () => {}
+			return paginationObserver.subscribe(onChange)
+		},
+		[paginationObserver]
+	)
+	const getObserverSnapshot = React.useCallback(
+		() => paginationObserver?.state.data ?? null,
+		[paginationObserver]
+	)
+	const paginationData = React.useSyncExternalStore(
+		subscribeToObserver,
+		getObserverSnapshot,
+		getObserverSnapshot
+	)
+
+	// Extract entity-level data from the pagination query response. For Node targetType
+	// the response is { node: EntityData }; we take the first root field to handle any type.
+	// Guard against partial cache hits (artifact has partial:true): only use the entity once the
+	// paginated connection field at refetch.path[0] is actually present in the response.
+	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
+		const entity = (paginationData as any)[rootField]
+		if (!entity) return null
+		const path = refetchArtifact.refetch?.path
+		if (path && path.length > 0 && (entity as any)[path[0]] == null) {
+			return null
+		}
+		return entity as _Data
+	}, [paginationData, refetchArtifact])
+
+	const isSinglePage = refetchArtifact?.refetch?.mode === 'SinglePage'
+
+	// For SinglePage: use the pagination observer's entity data (each page has its own
+	// cache key) once a page fetch has landed. For Infinite: always use fragmentData,
+	// which reads accumulated pages from cache via the fragment's cache subscription.
+	const displayData =
+		isSinglePage && paginationEntityData !== null ? paginationEntityData : 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 })
+		}
+
+		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,
+				// Use the observer's own variable state so cursor history is preserved
+				// across page navigations without manual tracking in the hook.
+				getVariables: () =>
+					(paginationObserver.state.variables ?? variables) as NonNullable<_Input>,
+				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>,
+				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])
+
+	return {
+		...handle,
+		variables,
+		data: displayData,
+	}
+}

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/useMutation.ts

@@ -0,0 +1,70 @@
+import type {
+	MutationArtifact,
+	GraphQLObject,
+	QueryResult,
+	GraphQLVariables,
+} from 'houdini/runtime'
+
+import { useSession } from '../routing/Router.js'
+import { useDocumentStore } from './useDocumentStore.js'
+
+export type MutationHandler<_Result, _Input, _Optimistic extends GraphQLObject> = (args: {
+	variables: _Input
+
+	metadata?: App.Metadata
+	fetch?: typeof globalThis.fetch
+	optimisticResponse?: _Optimistic
+	abortController?: AbortController
+}) => Promise<void>
+
+export function useMutation<
+	_Result extends GraphQLObject,
+	_Input extends GraphQLVariables,
+	_Optimistic extends GraphQLObject,
+>({
+	artifact,
+}: {
+	artifact: MutationArtifact
+}): [MutationHandler<_Result, _Input, _Optimistic>, boolean] {
+	// build the live document we'll use to send values
+	const [storeValue, observer] = useDocumentStore<_Result, _Input>({ artifact })
+
+	// grab the pending state from the document store
+	const pending = storeValue.fetching
+
+	// grab the current session value
+	const [session] = useSession()
+
+	//  sending the mutation just means invoking the observer's send method
+	const mutate: MutationHandler<_Result, _Input, _Optimistic> = async ({
+		metadata,
+		fetch,
+		variables,
+		abortController,
+		...mutationConfig
+	}) => {
+		const result = await observer.send({
+			variables,
+			metadata,
+			session,
+			abortController,
+			stuff: {
+				...mutationConfig,
+			},
+		})
+
+		if (result.errors && result.errors.length > 0) {
+			const err = new RuntimeGraphQLError(
+				result.errors.map((error) => error.message).join('. ')
+			)
+			err.raw = result.errors
+			throw err
+		}
+	}
+
+	return [mutate, pending]
+}
+
+export class RuntimeGraphQLError extends Error {
+	raw: QueryResult['errors'] = []
+}

package/runtime/hooks/useQuery.ts

@@ -0,0 +1,12 @@
+import type { GraphQLObject, GraphQLVariables, QueryArtifact } from 'houdini/runtime'
+
+import type { UseQueryConfig } from './useQueryHandle.js'
+import { useQueryHandle } from './useQueryHandle.js'
+
+export function useQuery<
+	_Artifact extends QueryArtifact,
+	_Data extends GraphQLObject = GraphQLObject,
+>(document: { artifact: _Artifact }, variables: any = null, config: UseQueryConfig = {}): _Data {
+	const { data } = useQueryHandle<_Artifact, _Data>(document, variables, config)
+	return data as unknown as _Data
+}

package/runtime/hooks/useQueryHandle.ts

@@ -0,0 +1,194 @@
+import { createLRUCache } from 'houdini/runtime'
+import type { GraphQLObject, CachePolicies, QueryArtifact, GraphQLVariables } from 'houdini/runtime'
+import React from 'react'
+
+import { useClient } from '../routing/index.js'
+import type { DocumentHandle } from './useDocumentHandle.js'
+import { useDocumentHandle } from './useDocumentHandle.js'
+import { useIsMountedRef } from './useIsMounted.js'
+
+// Suspense requires a way to throw a promise that resolves to a place
+// we can put when we go back on a susequent render. This means that we have to have
+// a stable way to identify _this_ useQueryHandle called.
+// For now, we're going to compute an identifier based on the name of the artifact
+// and the variables that we were given.
+//
+// - If we have a cached promise that's pending, we should just throw that promise
+// - If we have a cached promise that's been resolved, we should return that value
+//
+// When the Component unmounts, we need to remove the entry from the cache (so we can load again)
+
+const promiseCache = createLRUCache<QuerySuspenseUnit>()
+type QuerySuspenseUnit<
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+> = {
+	resolve: () => void
+	resolved?: DocumentHandle<QueryArtifact, _Data, _Input>
+	then: (val: any) => any
+}
+
+export function useQueryHandle<
+	_Artifact extends QueryArtifact,
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+>(
+	{ artifact }: { artifact: QueryArtifact },
+	variables: any = null,
+	config: UseQueryConfig = {}
+): any {
+	// figure out the identifier so we know what to look for
+	const identifier = queryIdentifier({ artifact, variables, config })
+
+	// see if we have an entry in the cache for the identifier
+	const suspenseValue = promiseCache.get(identifier)
+
+	const client = useClient()
+
+	const isMountedRef = useIsMountedRef()
+
+	// hold onto an observer we'll use
+	const [observer] = React.useState(
+		client.observe<_Data, _Input>({
+			artifact,
+			initialValue: (suspenseValue?.resolved?.data ?? {}) as _Data,
+		})
+	)
+
+	// a ref flag we'll enable before throwing so that we don't update while suspend
+	const suspenseTracker = React.useRef(false)
+
+	// a stable box to put the store's value
+	const box = React.useRef(observer.state)
+
+	// a stable subscribe function for the document store
+	const subscribe: any = React.useCallback(
+		(fn: () => void) => {
+			return observer.subscribe((val) => {
+				box.current = val
+				if (isMountedRef.current && !suspenseTracker.current) {
+					fn()
+				}
+			})
+		},
+		[observer, isMountedRef.current]
+	)
+
+	// get a safe reference to the cache
+	const storeValue = React.useSyncExternalStore(subscribe, () => box.current)
+
+	// compute the imperative handle for this artifact
+	const handle = useDocumentHandle<_Artifact, _Data, _Input>({
+		artifact,
+		observer,
+		storeValue,
+	})
+
+	// if the identifier changes, we need to remove the old identifier from the
+	// suspense cache
+	React.useEffect(() => {
+		return () => {
+			promiseCache.delete(identifier)
+		}
+	}, [identifier])
+
+	// when we unmount, we need to clean up
+	React.useEffect(() => {
+		return () => {
+			observer.cleanup()
+		}
+	}, [observer])
+
+	// if the promise has resolved, let's use that for our first render
+	const result = storeValue.data
+
+	if (!suspenseValue) {
+		// we are going to cache the promise and then throw it
+		// when it resolves the cached value will be updated
+		// and it will be picked up in the next render
+		let resolve: () => void = () => {}
+		let reject: (reason?: any) => void = () => {}
+		const loadPromise = new Promise<void>((res, rej) => {
+			resolve = res
+			reject = rej
+		})
+
+		const suspenseUnit: QuerySuspenseUnit<_Data, _Input> = {
+			// biome-ignore lint/suspicious/noThenProperty: suspense protocol requires a thenable
+			then: loadPromise.then.bind(loadPromise),
+			resolve,
+			// @ts-expect-error
+			variables,
+		}
+
+		promiseCache.set(identifier, suspenseUnit as QuerySuspenseUnit)
+
+		// the suspense unit gives react something to hold onto
+		// and it acts as a place for us to register a callback on
+		// send to update the cache before resolving the suspense
+		handle
+			.fetch({
+				variables,
+				// @ts-expect-error: this is actually allowed... 🤫
+				stuff: {
+					silenceLoading: true,
+				},
+			})
+			.then((value) => {
+				// the final value
+				suspenseUnit.resolved = {
+					...handle,
+					data: value.data,
+					partial: value.partial,
+					artifact,
+				} as unknown as DocumentHandle<QueryArtifact, _Data, _Input>
+
+				suspenseUnit.resolve()
+			})
+			.catch((err) => {
+				promiseCache.delete(identifier)
+				reject(err)
+			})
+		suspenseTracker.current = true
+		throw suspenseUnit
+	}
+
+	// if the promise is still pending, we're still waiting
+	if (!result && suspenseValue && !suspenseValue.resolved) {
+		suspenseTracker.current = true
+		throw suspenseValue
+	}
+
+	// make sure we prefer the latest store value instead of the initial version we loaded on mount
+	if (!result && suspenseValue?.resolved) {
+		return suspenseValue.resolved as unknown as DocumentHandle<_Artifact, _Data, _Input>
+	}
+
+	return {
+		...handle,
+		variables: storeValue.variables,
+		data: result,
+	}
+}
+
+export type UseQueryConfig = {
+	policy?: CachePolicies
+	metadata?: App.Metadata
+	fetchKey?: any
+}
+
+function queryIdentifier(args: {
+	artifact: QueryArtifact
+	fetchKey?: number
+	variables: {}
+	config: UseQueryConfig
+}): string {
+	// make sure there is always a fetchKey
+	args.fetchKey ??= 0
+
+	// pull the common stuff out
+	const { artifact, variables, fetchKey } = args
+
+	// a query identifier is a mix of its name, arguments, and the fetch key
+	return [artifact.name, JSON.stringify(variables), fetchKey].join('@@')
+}

package/runtime/hooks/useSubscription.ts

@@ -0,0 +1,12 @@
+import type { SubscriptionArtifact, GraphQLObject, GraphQLVariables } from 'houdini/runtime'
+
+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
+) {
+	const { data } = useSubscriptionHandle(document, variables)
+	return data
+}

package/runtime/hooks/useSubscriptionHandle.ts

@@ -0,0 +1,38 @@
+import type {
+	SubscriptionArtifact,
+	GraphQLObject,
+	GraphQLVariables,
+	GraphQLError,
+} from 'houdini/runtime'
+
+import { useDocumentSubscription } from './useDocumentSubscription.js'
+
+export type SubscriptionHandle<_Result extends GraphQLObject, _Input extends GraphQLVariables> = {
+	data: _Result | null
+	errors: GraphQLError[] | null
+	variables: _Input
+	listen: (args: { variables?: _Input }) => void
+	unlisten: () => void
+	fetching: boolean
+}
+
+// a hook to subscribe to a subscription artifact
+export function useSubscriptionHandle<
+	_Result extends GraphQLObject,
+	_Input extends GraphQLVariables,
+>({ artifact }: { artifact: SubscriptionArtifact }, variables: _Input) {
+	// a subscription is basically just a live document
+	const [storeValue, observer] = useDocumentSubscription({
+		artifact,
+		variables,
+	})
+
+	return {
+		data: storeValue.data,
+		errors: storeValue.errors,
+		fetching: storeValue.fetching,
+		variables,
+		unlisten: observer.cleanup,
+		listen: observer.send,
+	}
+}