houdini-react 2.0.0-next.11 → 2.0.0-next.22

package/runtime/hooks/useDeepCompareEffect.ts

@@ -0,0 +1,91 @@
+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)
+	const signalRef = React.useRef<number>(0)
+
+	if (!deepEquals(value, ref.current)) {
+		ref.current = value
+		signalRef.current += 1
+	}
+
+	return React.useMemo(() => 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,232 @@
+import { extractPageInfo } from 'houdini/runtime'
+import { cursorHandlers, offsetHandlers } from 'houdini/runtime'
+import { ArtifactKind } from 'houdini/runtime'
+import type {
+	GraphQLObject,
+	GraphQLVariables,
+	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'
+
+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)
+	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,
+				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!.send,
+		location.params,
+	])
+}
+
+export type DocumentHandle<
+	_Artifact extends QueryArtifact,
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+> = {
+	data: _Data
+	partial: boolean
+	fetching: boolean
+	errors: { message: string }[] | 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,76 @@
+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'
+import { useIsMountedRef } from './useIsMounted'
+
+export type UseDocumentStoreParams<
+	_Artifact extends DocumentArtifact,
+	_Data extends GraphQLObject,
+	_Input extends GraphQLVariables,
+> = {
+	artifact: _Artifact
+	observer?: DocumentStore<_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,
+	...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)
+	}
+
+	// the function that registers a new subscription for the observer
+	const subscribe: any = React.useCallback(
+		(fn: () => void) => {
+			return observer.subscribe((val) => {
+				box.current = val
+				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]
+}

package/runtime/hooks/useDocumentSubscription.ts

@@ -0,0 +1,62 @@
+import type {
+	DocumentArtifact,
+	GraphQLVariables,
+	QueryResult,
+	GraphQLObject,
+} from 'houdini/runtime'
+import type { DocumentStore, SendParams } from 'houdini/runtime/client'
+
+import { useSession } from '../routing/Router'
+import useDeepCompareEffect from './useDeepCompareEffect'
+import { useDocumentStore, type UseDocumentStoreParams } from './useDocumentStore'
+
+export function useDocumentSubscription<
+	_Artifact extends DocumentArtifact = DocumentArtifact,
+	_Data extends GraphQLObject = GraphQLObject,
+	_Input extends GraphQLVariables = GraphQLVariables,
+>({
+	artifact,
+	variables,
+	send,
+	disabled,
+	...observeParams
+}: UseDocumentStoreParams<_Artifact, _Data, _Input> & {
+	variables: _Input
+	disabled?: boolean
+	send?: Partial<SendParams>
+}): [QueryResult<_Data, _Input> & { parent?: string | null }, DocumentStore<_Data, _Input>] {
+	const [storeValue, observer] = useDocumentStore<_Data, _Input>({
+		artifact,
+		...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,
+			})
+		}
+
+		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,93 @@
+import { deepEquals } from 'houdini/runtime'
+import { fragmentKey } from 'houdini/runtime'
+import type { GraphQLObject, GraphQLVariables, FragmentArtifact } from 'houdini/runtime'
+import * as React from 'react'
+
+import { useRouterContext } from '../routing'
+import { useDocumentSubscription } from './useDocumentSubscription'
+
+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()
+
+	// get the fragment reference info
+	const { parent, variables, loading } = fragmentReference<_Data, _Input, _ReferenceType>(
+		reference,
+		document
+	)
+
+	// if we got this far then we are safe to use the fields on the object
+	let cachedValue = reference as _Data | null
+
+	// on the client, we want to ensure that we apply masking to the initial value by
+	// loading the value from cache
+	if (reference && parent) {
+		cachedValue = cache.read({
+			selection: document.artifact.selection,
+			parent,
+			variables,
+			loading,
+		}).data as _Data
+	}
+
+	// we're ready to setup the live document
+	const [storeValue] = useDocumentSubscription<FragmentArtifact, _Data, _Input>({
+		artifact: document.artifact,
+		variables,
+		initialValue: cachedValue,
+		// dont subscribe to anything if we are loading
+		disabled: loading,
+		send: {
+			stuff: {
+				parentID: parent,
+			},
+			setup: true,
+		},
+	})
+
+	// the parent has changed, we need to use initialValue for this render
+	// if we don't, then there is a very brief flash where we will show the old data
+	// before the store has had a chance to update
+	const lastReference = React.useRef<{ parent: string; variables: _Input } | null>(null)
+	return React.useMemo(() => {
+		// if the parent reference has changed we need to always prefer the cached value
+		const parentChange =
+			storeValue.parent !== parent ||
+			!deepEquals({ parent, variables }, lastReference.current)
+		if (parentChange) {
+			// make sure we keep track of the last reference we used
+			lastReference.current = { parent, variables: { ...variables } }
+
+			// and use the cached value
+			return cachedValue
+		}
+
+		return storeValue.data
+	}, [variables, parent, storeValue.parent, storeValue.data, cachedValue])
+}
+
+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,46 @@
+import type {
+	GraphQLObject,
+	FragmentArtifact,
+	QueryArtifact,
+	GraphQLVariables,
+} from 'houdini/runtime'
+
+import { useDocumentHandle } from './useDocumentHandle'
+import { useDocumentStore } from './useDocumentStore'
+import { fragmentReference, useFragment } from './useFragment'
+
+// 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 data = useFragment<_Data, _ReferenceType, _Input>(reference, document)
+
+	// look at the fragment reference to get the variables
+	const { variables } = fragmentReference<_Data, _Input, _ReferenceType>(reference, document)
+
+	// use the pagination fragment for meta data if it exists.
+	// if we pass this a fragment artifact, it won't add any data
+	const [handleValue, handleObserver] = useDocumentStore<_Data, _Input>({
+		artifact: document.refetchArtifact ?? document.artifact,
+	})
+	const handle = useDocumentHandle<_PaginationArtifact, _Data, _Input>({
+		observer: handleObserver,
+		storeValue: handleValue,
+		artifact: document.refetchArtifact ?? document.artifact,
+	})
+
+	return {
+		...handle,
+		variables,
+		data,
+	}
+}

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'
+import { useDocumentStore } from './useDocumentStore'
+
+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
+}): [boolean, MutationHandler<_Result, _Input, _Optimistic>] {
+	// 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 [pending, mutate]
+}
+
+export class RuntimeGraphQLError extends Error {
+	raw: QueryResult['errors'] = []
+}

package/runtime/hooks/useQuery.ts

@@ -0,0 +1,12 @@
+import type { GraphQLObject, QueryArtifact } from 'houdini/runtime'
+
+import type { UseQueryConfig } from './useQueryHandle'
+import { useQueryHandle } from './useQueryHandle'
+
+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
+}