houdini-react 2.0.0-go.4 → 2.0.0-go.5

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,102 @@
+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 { useDeepCompareMemoize } from './useDeepCompareEffect'
+import { useDocumentSubscription } from './useDocumentSubscription'
+
+export function useFragment<
+	_Data extends GraphQLObject,
+	_ReferenceType extends {},
+	_Input extends GraphQLVariables = GraphQLVariables
+>(
+	reference: _Data | { [fragmentKey]: _ReferenceType } | null,
+	document: { artifact: FragmentArtifact }
+) {
+	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
+	}, [
+		useDeepCompareMemoize({
+			parent,
+			variables,
+			cachedValue,
+			storeValue: storeValue.data,
+			storeParent: storeValue.parent,
+		}),
+	])
+}
+
+export function fragmentReference<_Data extends GraphQLObject, _Input, _ReferenceType extends {}>(
+	reference: _Data | { [fragmentKey]: _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,47 @@
+import type {
+	GraphQLObject,
+	FragmentArtifact,
+	QueryArtifact,
+	fragmentKey,
+	GraphQLVariables,
+} from 'houdini/runtime'
+
+import { useDocumentHandle, type DocumentHandle } 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 | { [fragmentKey]: _ReferenceType } | null,
+	document: { artifact: FragmentArtifact; refetchArtifact?: QueryArtifact }
+): DocumentHandle<_PaginationArtifact, _Data, _Input> {
+	// 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,54 @@
+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
+}) => Promise<QueryResult<_Result, _Input>>
+
+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> = ({
+		metadata,
+		fetch,
+		variables,
+		...mutationConfig
+	}) =>
+		observer.send({
+			variables,
+			metadata,
+			session,
+			stuff: {
+				...mutationConfig,
+			},
+		})
+
+	return [pending, mutate]
+}

package/runtime/hooks/useQuery.ts

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

package/runtime/hooks/useQueryHandle.ts

@@ -0,0 +1,184 @@
+import { createLRUCache } from 'houdini/runtime'
+import type { GraphQLObject, CachePolicies, QueryArtifact, GraphQLVariables } from 'houdini/runtime'
+import React from 'react'
+
+import { useClient } from '../routing'
+import type { DocumentHandle } from './useDocumentHandle'
+import { useDocumentHandle } from './useDocumentHandle'
+import { useIsMountedRef } from './useIsMounted'
+
+// 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 = {
+	resolve: () => void
+	resolved?: DocumentHandle<QueryArtifact, GraphQLObject, {}>
+	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 = {}
+): DocumentHandle<_Artifact, _Data, _Input> {
+	// 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
+	let [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]
+	)
+
+	// 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
+	let 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 = () => {}
+		const loadPromise = new Promise<void>((r) => (resolve = r))
+
+		const suspenseUnit: QuerySuspenseUnit = {
+			then: loadPromise.then.bind(loadPromise),
+			resolve,
+			// @ts-ignore
+			variables,
+		}
+
+		// @ts-ignore
+		promiseCache.set(identifier, suspenseUnit)
+
+		// 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-ignore: this is actually allowed... 🤫
+				stuff: {
+					silenceLoading: true,
+				},
+			})
+			.then((value) => {
+				// @ts-expect-error
+				// the final value
+				suspenseUnit.resolved = {
+					...handle,
+					data: value.data,
+					partia: value.partial,
+					artifact,
+				}
+
+				suspenseUnit.resolve()
+			})
+		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'
+
+// 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,33 @@
+import type { SubscriptionArtifact, GraphQLObject, GraphQLVariables } from 'houdini/runtime'
+
+import { useDocumentSubscription } from './useDocumentSubscription'
+
+export type SubscriptionHandle<_Result extends GraphQLObject, _Input extends GraphQLVariables> = {
+	data: _Result | null
+	errors: { message: string }[] | 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,
+	}
+}

package/runtime/index.tsx

@@ -0,0 +1,49 @@
+import type { GraphQLObject } from 'houdini/runtime'
+import type { Cache } from 'houdini/runtime/cache'
+
+import client from './client'
+import manifest from './manifest'
+import { Router as RouterImpl, RouterCache, RouterContextProvider } from './routing'
+
+export * from './hooks'
+export { router_cache, useSession, useLocation, useRoute } from './routing'
+
+export function Router({
+	cache,
+	initialURL,
+	artifact_cache,
+	component_cache,
+	data_cache,
+	ssr_signals,
+	last_variables,
+	session,
+	assetPrefix,
+	injectToStream,
+}: {
+	initialURL: string
+	initialVariables: GraphQLObject
+	cache: Cache
+	session?: App.Session
+	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}
+		>
+			<RouterImpl
+				initialURL={initialURL}
+				manifest={manifest}
+				assetPrefix={assetPrefix}
+				injectToStream={injectToStream}
+			/>
+		</RouterContextProvider>
+	)
+}

package/runtime/manifest.ts

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

package/runtime/package.json

@@ -0,0 +1 @@
+{"type":"module"}