orpc-fn 0.4.0 → 0.5.1

package/src/procedure-cli.ts

@@ -0,0 +1,99 @@
+import { type AnyProcedure, call, isProcedure, ORPCError } from '@orpc/server'
+import {
+	CliError,
+	type Command,
+	type CommandGroup,
+	defineCommand
+} from 'hanzio/cli'
+import { z } from 'zod'
+import { type FnMeta, readFnMeta } from './meta.js'
+
+export type ProcedureCommandsOptions<C> = {
+	/**
+	 * Which procedures become commands. Default: those declared with
+	 * `meta: { cli: true }` (add `cli?: boolean` to the app's meta type).
+	 */
+	filter?: (meta: FnMeta) => boolean
+	/**
+	 * The oRPC context a command calls its procedure with, from the CLI's
+	 * context (`defineCli({ context })`). Default: that context as-is. It gets
+	 * the procedure's meta, so it can refuse early with a `CliError`, e.g. a
+	 * protected procedure run without a user.
+	 */
+	context?: (cliContext: C, meta: FnMeta) => unknown
+}
+
+const optedIn = (meta: FnMeta) => (meta.meta as { cli?: unknown }).cli === true
+
+const kebab = (key: string) =>
+	key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+
+/**
+ * The opted-in `fn()` procedures of a router as hanzio/cli commands, nested
+ * like the router: `supportLearning.syncRun` is `support-learning sync-run`.
+ * Flags come from the procedure's input schema, help from its summary. A
+ * command calls the procedure through oRPC, so middleware, guards, tracing
+ * and errors run as they do over HTTP.
+ */
+export function procedureCommands<C = unknown>(
+	router: object,
+	options: ProcedureCommandsOptions<C> = {}
+): CommandGroup<C> {
+	const filter = options.filter ?? optedIn
+	const commands: Record<string, Command<C> | CommandGroup<C>> = {}
+
+	for (const [key, value] of Object.entries(router)) {
+		if (isProcedure(value)) {
+			const meta = readFnMeta(value)
+			if (filter(meta)) commands[kebab(key)] = toCommand(value, meta, options)
+		} else if (value && typeof value === 'object') {
+			const group = procedureCommands(value, options)
+			if (Object.keys(group).length > 0) commands[kebab(key)] = group
+		}
+	}
+
+	return commands
+}
+
+function toCommand<C>(
+	procedure: AnyProcedure,
+	meta: FnMeta,
+	options: ProcedureCommandsOptions<C>
+): Command<C> {
+	const name = meta.name ?? 'procedure'
+	if (meta.stream) {
+		throw new TypeError(`orpc-fn: ${name} streams and cannot be a CLI command`)
+	}
+	const input = meta.inputSchema
+	if (input !== undefined && !(input instanceof z.ZodObject)) {
+		throw new TypeError(
+			`orpc-fn: ${name} must take a z.object() input to be a CLI command`
+		)
+	}
+
+	return defineCommand<z.ZodObject, unknown, C>({
+		description: meta.description,
+		input: input ?? z.object({}),
+		run: async (parsed, ctx) => {
+			const context = options.context
+				? await options.context(ctx.context, meta)
+				: ctx.context
+			try {
+				// The flags were validated against this schema; the procedure parses
+				// them again, like any nested call with a parsed value.
+				return await call(procedure, input ? parsed : undefined, {
+					context: context as Record<never, never>
+				})
+			} catch (error) {
+				// A refusal the caller drives (auth, permission, not found) reads as
+				// a message, not a crash with a stack trace.
+				if (error instanceof ORPCError && error.status < 500) {
+					throw new CliError(`${error.code}: ${error.message}`, {
+						cause: error
+					})
+				}
+				throw error
+			}
+		}
+	})
+}

package/src/react.ts

@@ -0,0 +1,355 @@
+import {
+	focusManager,
+	hashKey,
+	keepPreviousData,
+	type QueryKey,
+	type UseQueryOptions,
+	type UseQueryResult,
+	useQuery,
+	useQueryClient
+} from '@tanstack/react-query'
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import {
+	createInvalidationCoordinator,
+	createStreamScope,
+	createSubscriptionRunner,
+	type InvalidationStreamOptions,
+	type LiveConnectionStatus,
+	type SubscriptionRunner,
+	seedQueryFn
+} from './realtime.js'
+
+export type { InvalidationDomain, LiveConnectionStatus } from './realtime.js'
+
+/** An oRPC client procedure fits: `client.order.watch`. */
+export type SubscribeFn<TInput, TEvent> = (
+	input: TInput,
+	options: { signal: AbortSignal }
+) => Promise<AsyncIterable<TEvent>>
+
+export type UseOrpcSubscriptionOptions<TInput, TEvent> = {
+	/** Run the stream (default: true). */
+	enabled?: boolean | undefined
+	onEvent?: (
+		event: TEvent,
+		meta: { connectionId: number; input: TInput }
+	) => void
+	/** Every successful connect; `connectionId > 1` is a reconnect. */
+	onConnect?: (connectionId: number) => void
+	onError?: ((error: Error) => void) | undefined
+	onClose?: () => void
+	/**
+	 * Close the stream while the app is not focused (default: true). Focus is
+	 * TanStack's `focusManager`: on React Native, wire it to `AppState` once.
+	 */
+	pauseWhenUnfocused?: boolean | undefined
+}
+
+const subscribeFocus = (listener: () => void) =>
+	focusManager.subscribe(listener)
+const getFocus = () => focusManager.isFocused()
+
+/** Whether the app is focused, from TanStack's `focusManager`. */
+function useIsFocused(): boolean {
+	return useSyncExternalStore(subscribeFocus, getFocus, getFocus)
+}
+
+/**
+ * An oRPC event iterator with backoff reconnects that closes while the app is
+ * backgrounded. A changed input (compared as JSON) reconnects with a fresh
+ * retry budget.
+ */
+export function useOrpcSubscription<TInput, TEvent>(
+	input: TInput,
+	subscribe: SubscribeFn<TInput, TEvent>,
+	options: UseOrpcSubscriptionOptions<TInput, TEvent> = {}
+): { status: LiveConnectionStatus } {
+	const { enabled = true, pauseWhenUnfocused = true } = options
+	const focused = useIsFocused()
+	const shouldRun = enabled && (!pauseWhenUnfocused || focused)
+	const [status, setStatus] = useState<LiveConnectionStatus>('idle')
+
+	const latest = useRef({ input, subscribe, options, shouldRun })
+	latest.current = { input, subscribe, options, shouldRun }
+
+	const runnerRef = useRef<SubscriptionRunner | null>(null)
+	if (!runnerRef.current) {
+		let openedInput = input
+		runnerRef.current = createSubscriptionRunner<TEvent>({
+			open: (signal) => {
+				openedInput = latest.current.input
+				return latest.current.subscribe(openedInput, { signal })
+			},
+			canConnect: () => latest.current.shouldRun,
+			shouldReconnect: () => latest.current.shouldRun,
+			onStatus: setStatus,
+			onEvent: (event, connectionId) =>
+				latest.current.options.onEvent?.(event, {
+					connectionId,
+					input: openedInput
+				}),
+			onConnect: (id) => latest.current.options.onConnect?.(id),
+			onError: (error) => latest.current.options.onError?.(error),
+			onClose: () => latest.current.options.onClose?.()
+		})
+	}
+	const runner = runnerRef.current
+	const serializedInput = JSON.stringify(input)
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: a changed input resubscribes
+	useEffect(() => {
+		if (!shouldRun) return
+		void runner.start()
+		return () => void runner.disconnect()
+	}, [runner, shouldRun, serializedInput])
+
+	return { status }
+}
+
+type ApplyEvent<TStreamEvent, TData> = (
+	event: TStreamEvent,
+	previous: TData | undefined
+) => TData | undefined
+
+type LiveQueryOptions<
+	TInput,
+	TRouteData,
+	TStreamEvent,
+	TData,
+	TSubscriptionInput
+> = {
+	/** Run the query and its stream (default: true). */
+	enabled?: boolean | undefined
+	/** Input for the stream when it differs from the query's. */
+	subscriptionInput?: TSubscriptionInput | undefined
+	/**
+	 * Convert the route output once at fetch time into a differently typed
+	 * cache; `applyEvent` then reduces stream events into that cache.
+	 */
+	select?: (data: TRouteData) => TData
+	/** The raw route output of a seed, before `select` drops fields. */
+	onSeed?: (data: TRouteData, input: TInput) => void
+	/**
+	 * Fold a stream event into the cached data. Required when the stream sends
+	 * something other than the cached type (an `fnLive` patch route, or a
+	 * `select`ed cache). Return `undefined` to skip the write.
+	 */
+	applyEvent?: ApplyEvent<TStreamEvent, NoInfer<TData>>
+	onEvent?: (event: TStreamEvent, meta: { connectionId: number }) => void
+	onError?: ((error: Error) => void) | undefined
+	/**
+	 * Reconcile a fetched seed with what the stream already wrote. The HTTP
+	 * request can resolve last, so a plain overwrite would drop events that
+	 * arrived while it was in flight. Default: take the fetched value.
+	 */
+	mergeSeed?: (
+		fetched: NoInfer<TData>,
+		cached: NoInfer<TData> | undefined
+	) => NoInfer<TData>
+	/** Show the previous key's data while a new key loads (default: true). */
+	keepPreviousData?: boolean
+	/** Close the stream while the app is not focused (default: true). */
+	pauseWhenUnfocused?: boolean | undefined
+}
+
+type LiveQueryOptionsFn<TInput, TData, TError> = (
+	input: TInput
+) => UseQueryOptions<TData, TError, TData, QueryKey>
+
+type LiveQueryResult<TData, TError> = UseQueryResult<TData, TError> & {
+	liveStatus: LiveConnectionStatus
+}
+
+/**
+ * The client half of `fnLive`: the HTTP query seeds the cache, and the live
+ * route's stream writes each snapshot into the same cache entry. Marked
+ * `meta.live`, so invalidation streams leave it alone.
+ *
+ * ```tsx
+ * const order = useLiveQuery({ id }, (input) => orpc.order.get.queryOptions({ input }), client.order.watch)
+ * ```
+ *
+ * One signature, not overloads: TypeScript fixes an untyped callback's
+ * parameters at the first overload it tries, which made valid calls fail.
+ */
+export function useLiveQuery<
+	TInput,
+	TRouteData,
+	TStreamEvent,
+	TData = TRouteData,
+	TError = Error,
+	TSubscriptionInput = TInput
+>(
+	input: TInput,
+	queryOptionsFn: LiveQueryOptionsFn<TInput, TRouteData, TError>,
+	subscribe: SubscribeFn<NoInfer<TSubscriptionInput>, TStreamEvent>,
+	...options: [TStreamEvent] extends [TData]
+		? [
+				options?: LiveQueryOptions<
+					TInput,
+					TRouteData,
+					TStreamEvent,
+					TData,
+					TSubscriptionInput
+				>
+			]
+		: [
+				options: LiveQueryOptions<
+					TInput,
+					TRouteData,
+					TStreamEvent,
+					TData,
+					TSubscriptionInput
+				> & { applyEvent: ApplyEvent<TStreamEvent, NoInfer<TData>> }
+			]
+): LiveQueryResult<TData, TError>
+export function useLiveQuery<
+	TInput,
+	TRouteData,
+	TStreamEvent,
+	TData,
+	TError,
+	TSubscriptionInput
+>(
+	input: TInput,
+	queryOptionsFn: LiveQueryOptionsFn<TInput, TRouteData, TError>,
+	subscribe: SubscribeFn<TSubscriptionInput, TStreamEvent>,
+	options: LiveQueryOptions<
+		TInput,
+		TRouteData,
+		TStreamEvent,
+		TData,
+		TSubscriptionInput
+	> = {}
+): LiveQueryResult<TData, TError> {
+	const queryClient = useQueryClient()
+	const focused = useIsFocused()
+	const [scope] = useState(createStreamScope)
+
+	// oRPC query options are plain objects; `queryFn` is read through one shape.
+	const raw = queryOptionsFn(input) as unknown as {
+		queryKey: QueryKey
+		queryFn?: (context: unknown) => Promise<TRouteData>
+		enabled?: UseQueryOptions['enabled']
+		meta?: Record<string, unknown>
+	} & Record<string, unknown>
+	const keyHash = hashKey(raw.queryKey)
+	const latest = useRef({ raw, keyHash, options })
+	latest.current = { raw, keyHash, options }
+
+	const { status } = useOrpcSubscription(
+		(options.subscriptionInput === undefined
+			? input
+			: options.subscriptionInput) as TSubscriptionInput,
+		subscribe,
+		{
+			enabled: options.enabled,
+			pauseWhenUnfocused: options.pauseWhenUnfocused,
+			onError: options.onError,
+			onConnect: (connectionId) =>
+				scope.open(connectionId, latest.current.keyHash),
+			onEvent: (event, { connectionId }) => {
+				const current = latest.current
+				// The consumer callback must not see an event for a scope no longer shown.
+				if (!scope.owns(connectionId, current.keyHash)) return
+				// Without `applyEvent` the stream event is the cache type (the first overload).
+				const applyEvent =
+					current.options.applyEvent ??
+					((streamEvent: TStreamEvent) => streamEvent as unknown as TData)
+				const key = current.raw.queryKey
+				const next = applyEvent(event, queryClient.getQueryData<TData>(key))
+				if (next !== undefined) queryClient.setQueryData(key, next)
+				current.options.onEvent?.(event, { connectionId })
+			}
+		}
+	)
+
+	const wrapsSeed = options.select || options.mergeSeed
+	const queryFn =
+		raw.queryFn && wrapsSeed
+			? seedQueryFn(raw.queryFn, {
+					input,
+					readCache: () => queryClient.getQueryData<TData>(raw.queryKey),
+					select: options.select,
+					onSeed: options.onSeed,
+					mergeSeed: options.mergeSeed
+				})
+			: raw.queryFn
+	const runs = options.enabled !== false && focused
+	const query = useQuery({
+		...raw,
+		...(queryFn ? { queryFn } : {}),
+		enabled: runs ? (raw.enabled ?? true) : false,
+		...(options.keepPreviousData === false
+			? {}
+			: { placeholderData: keepPreviousData }),
+		staleTime: Number.POSITIVE_INFINITY,
+		meta: { ...raw.meta, live: true }
+	} as UseQueryOptions<TData, TError, TData, QueryKey>)
+
+	return Object.assign(query, { liveStatus: status })
+}
+
+/**
+ * One app-wide stream of `{ domain }` change events that keeps list and count
+ * queries fresh: each event invalidates its domain's query keys (debounced),
+ * and a reconnect that proves healthy invalidates every domain to cover
+ * events lost while it was down. Mount once, in the signed-in shell.
+ *
+ * ```ts
+ * useInvalidationStream({}, client.realtime.subscribeChanges, {
+ *   enabled: signedIn,
+ *   domains: { order: { debounceMs: 100, queryKeys: [orpc.order.key()] } }
+ * })
+ * ```
+ */
+export function useInvalidationStream<
+	TInput,
+	TEvent extends { domain: string }
+>(
+	input: TInput,
+	subscribe: SubscribeFn<TInput, TEvent>,
+	options: InvalidationStreamOptions<TEvent> &
+		Pick<
+			UseOrpcSubscriptionOptions<TInput, TEvent>,
+			'enabled' | 'pauseWhenUnfocused'
+		>
+): { status: LiveConnectionStatus } {
+	const queryClient = useQueryClient()
+	const latestOptions = useRef(options)
+	latestOptions.current = options
+	// `domains`, `refetchType` and `logger` are read on mount; `onEvent` stays current.
+	const [coordinator] = useState(() =>
+		createInvalidationCoordinator<TEvent>(queryClient, {
+			...options,
+			onEvent: (event) => latestOptions.current.onEvent?.(event)
+		})
+	)
+	useEffect(() => coordinator.dispose, [coordinator])
+
+	return useOrpcSubscription<TInput, TEvent>(input, subscribe, {
+		enabled: options.enabled,
+		pauseWhenUnfocused: options.pauseWhenUnfocused,
+		onEvent: coordinator.event,
+		onConnect: coordinator.connect,
+		onError: coordinator.lost,
+		onClose: coordinator.lost
+	})
+}
+
+/**
+ * Clear the query cache when the signed-in owner of the cached data changes
+ * (another user, another organization), so the next one never sees it.
+ * `null` means signed out: signing in starts from the cache sign-out emptied.
+ * Pass the same owner as the persister's `buster` so a saved cache from
+ * someone else is discarded on the next launch too.
+ */
+export function useQueryCacheOwner(owner: string | null): void {
+	const queryClient = useQueryClient()
+	const previous = useRef(owner)
+	useEffect(() => {
+		const before = previous.current
+		previous.current = owner
+		if (owner !== before && before !== null) queryClient.clear()
+	}, [owner, queryClient])
+}