houdini-react 2.0.0-next.3 → 2.0.0-next.31

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
+}): [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.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,186 @@
+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 = () => {}
+		const loadPromise = new Promise<void>((r) => (resolve = r))
+
+		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,
+					partia: value.partial,
+					artifact,
+				} as unknown as DocumentHandle<QueryArtifact, _Data, _Input>
+
+				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.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,33 @@
+import type { SubscriptionArtifact, GraphQLObject, GraphQLVariables } from 'houdini/runtime'
+
+import { useDocumentSubscription } from './useDocumentSubscription.js'
+
+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/hydration.tsx

@@ -0,0 +1,155 @@
+import React from 'react'
+import { hydrateRoot, createRoot } from 'react-dom/client'
+import type { QueryArtifact, GraphQLVariables } from '$houdini/runtime'
+import type { Cache } from '$houdini/runtime/cache'
+import type { HoudiniClient } from '$houdini/runtime/client'
+import cacheRef from '$houdini/runtime/cache'
+
+import { injectComponents } from './componentFields.js'
+import { router_cache, type RouterCache } from './routing/index.js'
+import clientFactory from './client.js'
+
+declare global {
+	interface Window {
+		__houdini__client__?: HoudiniClient
+		__houdini__pending_components__?: Record<string, any>
+		__houdini__cache__?: Cache
+		__houdini__hydration__layer__?: any
+		__houdini__initial__cache__?: any
+		__houdini__initial__session__?: any
+		__houdini__pending_artifacts__?: Record<string, QueryArtifact>
+		__houdini__pending_data__?: Record<string, any>
+		__houdini__pending_variables__?: Record<string, GraphQLVariables>
+		__houdini__nav_caches__?: RouterCache
+	}
+}
+
+export function hydrate_page(
+	App: React.ComponentType<any>,
+	Component: React.ComponentType<any>,
+	pageName: string,
+	pendingQueries: string[]
+) {
+	// set up the client using its internally-managed singleton cache (cacheRef).
+	// the client's cachePolicy and queryPlugin are closure-bound to cacheRef at
+	// construction time, so we must use that same instance as window.__houdini__cache__
+	// rather than creating a second cache and trying to wire them together afterward.
+	window.__houdini__client__ ??= clientFactory()
+	window.__houdini__cache__ ??= cacheRef
+
+	// configure the singleton for React component field support
+	if (window.__houdini__pending_components__) {
+		window.__houdini__client__.componentCache = window.__houdini__pending_components__
+	}
+	window.__houdini__cache__._internal_unstable.componentCache =
+		window.__houdini__client__.componentCache
+	window.__houdini__cache__._internal_unstable.createComponent = (
+		fn: React.ComponentType<any>,
+		props: any
+	) => React.createElement(fn, props)
+
+	window.__houdini__hydration__layer__ ??=
+		window.__houdini__cache__._internal_unstable.storage.createLayer()
+
+	// rehydrate the cache from the server-serialized snapshot
+	window.__houdini__cache__?.hydrate(
+		window.__houdini__initial__cache__,
+		window.__houdini__hydration__layer__
+	)
+
+	// prime the data/artifact caches from anything the server streamed
+	const initialData: Record<string, any> = {}
+	const initialArtifacts: Record<string, QueryArtifact> = {}
+
+	for (const [artifactName, artifact] of Object.entries(
+		window.__houdini__pending_artifacts__ ?? {}
+	)) {
+		initialArtifacts[artifactName] = artifact
+
+		if (window.__houdini__pending_data__?.[artifactName]) {
+			const variables = window.__houdini__pending_variables__![artifactName]
+
+			if ((artifact as any).hasComponents) {
+				injectComponents({
+					cache: window.__houdini__cache__!,
+					selection: (artifact as any).selection,
+					data: window.__houdini__pending_data__[artifactName],
+					variables,
+				})
+			}
+
+			const observer = window.__houdini__client__!.observe({
+				artifact,
+				cache: window.__houdini__cache__,
+				initialValue: window.__houdini__cache__!.read({
+					selection: (artifact as any).selection,
+					variables,
+				}).data,
+				initialVariables: variables,
+			})
+
+			observer.send({
+				setup: true,
+				variables,
+				session: window.__houdini__initial__session__,
+			})
+
+			initialData[artifactName] = observer
+		}
+	}
+
+	if (!window.__houdini__nav_caches__) {
+		window.__houdini__nav_caches__ = router_cache({
+			pending_queries: pendingQueries,
+			initialData,
+			initialVariables: window.__houdini__pending_variables__,
+			initialArtifacts,
+			components: { [pageName]: Component },
+		})
+		_flush_pending_artifacts()
+	}
+
+	hydrateRoot(
+		document,
+		<App
+			initialURL={window.location.pathname}
+			cache={window.__houdini__cache__}
+			session={window.__houdini__initial__session__}
+			{...window.__houdini__nav_caches__}
+		/>
+	)
+}
+
+const _pendingArtifacts: Array<[string, QueryArtifact]> = []
+
+export function register_artifact(name: string, artifact: QueryArtifact) {
+	const caches = window.__houdini__nav_caches__
+	if (!caches?.artifact_cache) {
+		_pendingArtifacts.push([name, artifact])
+		return
+	}
+	if (!caches.artifact_cache.has(name)) {
+		caches.artifact_cache.set(name, artifact)
+	}
+}
+
+function _flush_pending_artifacts() {
+	while (_pendingArtifacts.length > 0) {
+		const [name, artifact] = _pendingArtifacts.shift()!
+		register_artifact(name, artifact)
+	}
+}
+
+export function mount_static_app(App: React.ComponentType<any>, manifest: any) {
+	const root = createRoot(document.getElementById('app')!)
+
+	root.render(
+		React.createElement(App, {
+			initialURL: window.location.pathname,
+			cache: cacheRef,
+			session: null,
+			manifest,
+			...router_cache(),
+		})
+	)
+}

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.js'
+import manifest from './manifest.js'
+import { Router as RouterImpl, type RouterCache, RouterContextProvider } from './routing/index.js'
+
+export * from './hooks/index.js'
+export { router_cache, useSession, useLocation, useRoute } from './routing/index.js'
+
+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-expect-error: this file will get replaced by the build system
+const manifest: RouterManifest = {}
+
+export default manifest

package/runtime/package.json

@@ -0,0 +1 @@
+{"type":"module","main":"./index.tsx"}