orpc-fn 0.8.0 → 0.9.0

package/src/mcp/server.ts

@@ -3,16 +3,23 @@ import type { AnyRouter } from '@orpc/server'
 import {
 	createToolHandlers,
 	formatMcpResult,
+	type McpCallOptions,
+	type PreparedMcpTools,
+	prepareMcpTools,
 	type RegisterMcpToolsOptions as CoreOptions
 } from './core.js'
 
-export { formatMcpResult }
+export { formatMcpResult, prepareMcpTools, type PreparedMcpTools }
 
 export type RegisterMcpToolsOptions<R extends AnyRouter> = CoreOptions<
 	R,
 	CallToolResult
 >
 
+/** Options for registering tools from {@link prepareMcpTools}. */
+export type RegisterPreparedMcpToolsOptions<R extends AnyRouter> =
+	McpCallOptions<R, CallToolResult>
+
 /**
  * Register on the SDK v2 (`@modelcontextprotocol/server`) low-level Server, or
  * on McpServer.server. Declare `capabilities: { tools: {} }` on the Server.
@@ -22,7 +29,25 @@ export function registerMcpTools<R extends AnyRouter>(
 	router: R,
 	options: RegisterMcpToolsOptions<R>
 ): readonly string[] {
-	const handlers = createToolHandlers(router, options)
+	return install(
+		server,
+		createToolHandlers(prepareMcpTools(router, options), options)
+	)
+}
+
+/** Register tools listed once with {@link prepareMcpTools}, e.g. on a server built per request. */
+export function registerPreparedMcpTools<R extends AnyRouter>(
+	server: Pick<Server, 'setRequestHandler'>,
+	tools: PreparedMcpTools<R>,
+	options: RegisterPreparedMcpToolsOptions<R>
+): readonly string[] {
+	return install(server, createToolHandlers(tools, options))
+}
+
+function install(
+	server: Pick<Server, 'setRequestHandler'>,
+	handlers: ReturnType<typeof createToolHandlers<AnyRouter, CallToolResult>>
+): readonly string[] {
 	server.setRequestHandler('tools/list', handlers.list)
 	server.setRequestHandler('tools/call', (request, ctx) =>
 		handlers.call(

package/src/mcp.ts

@@ -6,16 +6,11 @@ import {
 } from '@orpc/server'
 import { procedureDefinition } from './compatibility.js'
 import { rawInputSchema, type ToolSchema } from './json-schema.js'
-import { readFnMeta, toToolName } from './meta.js'
+import { hasTag, type ProcedureFilter, readFnMeta, toToolName } from './meta.js'
 
-export { toToolName }
+export { hasTag, toToolName }
 export { rawInputSchema as toolInputSchema }
-export type { ToolSchema }
-
-/** Picks procedures; also fits oRPC's `OpenAPIHandler({ filter })`. */
-export type ProcedureFilter = (
-	options: TraverseContractProcedureCallbackOptions
-) => boolean
+export type { ProcedureFilter, ToolSchema }
 
 export type McpTool = {
 	/** Tool name: the sanitized `fn` name (`user.me` becomes `user-me`). */
@@ -32,12 +27,6 @@ export type McpTool = {
 	}
 }
 
-/** Procedures whose route has `tag`: `listTools(router, { filter: hasTag('external') })`. */
-export const hasTag =
-	(tag: string): ProcedureFilter =>
-	({ contract }) =>
-		procedureDefinition(contract).route?.tags?.includes(tag) ?? false
-
 const isGet: ProcedureFilter = ({ contract }) =>
 	procedureDefinition(contract).route?.method === 'GET'
 
@@ -80,8 +69,8 @@ export function listTools(
 					`orpc-fn: MCP tool name collision: ${name}; provide a name override`
 				)
 			names.set(name, procedure)
-			const { inputSchema, route = {} } = procedureDefinition(procedure)
-			const description = route.description ?? route.summary
+			const { inputSchema } = procedureDefinition(procedure)
+			const description = meta.description || undefined
 			tools.push({
 				name,
 				procedure,

package/src/meta.ts

@@ -1,6 +1,20 @@
 import { getEventIteratorSchemaDetails, type AnySchema } from '@orpc/contract'
 import { type LibraryMeta, procedureDefinition } from './compatibility.js'
-import type { AnyProcedure } from '@orpc/server'
+import type {
+	AnyProcedure,
+	TraverseContractProcedureCallbackOptions
+} from '@orpc/server'
+
+/** Picks procedures; also fits oRPC's `OpenAPIHandler({ filter })`. */
+export type ProcedureFilter = (
+	options: TraverseContractProcedureCallbackOptions
+) => boolean
+
+/** Procedures whose route has `tag`: `listTools(router, { filter: hasTag('external') })`. */
+export const hasTag =
+	(tag: string): ProcedureFilter =>
+	({ contract }) =>
+		procedureDefinition(contract).route?.tags?.includes(tag) ?? false
 
 /**
  * Key under which `fn()` stores its metadata in oRPC's procedure meta
@@ -18,6 +32,10 @@ export type StoredFnMeta<
 	procedure: TKey
 	meta: TMeta
 	stream: boolean
+	/** Guard values set on the route. */
+	guards?: Record<string, unknown>
+	/** Guards decided per call through `guardResolvers`. */
+	dynamicGuards?: readonly string[]
 }
 
 export type FnMeta<
@@ -30,7 +48,7 @@ export type FnMeta<
 	procedure: TKey | undefined
 	/** The app's typed meta (`createFn({ meta })`) declared on this route. */
 	meta: Partial<TMeta>
-	/** Route summary, falling back to description, falling back to ''. */
+	/** Route description, falling back to summary, falling back to ''. */
 	description: string
 	summary: string | undefined
 	method: string | undefined
@@ -39,6 +57,10 @@ export type FnMeta<
 	tags: readonly string[]
 	inputSchema: AnySchema | undefined
 	outputSchema: AnySchema | undefined
+	/** Guard values set on the route (`permission: 'deal.read'`). */
+	guards: Record<string, unknown>
+	/** Guards the route decides per call through `guardResolvers`. */
+	dynamicGuards: readonly string[]
 }
 
 /** Read what `fn()` (and oRPC) recorded on a procedure. */
@@ -69,7 +91,7 @@ export function readFnMeta<T extends AnyProcedure>(
 		name: stored?.name,
 		procedure: stored?.procedure as KeyFrom<T> | undefined,
 		meta: (stored?.meta ?? {}) as Partial<MetaFrom<T>>,
-		description: route.summary ?? route.description ?? '',
+		description: route.description ?? route.summary ?? '',
 		summary: route.summary,
 		method: route.method,
 		path: route.path,
@@ -78,7 +100,9 @@ export function readFnMeta<T extends AnyProcedure>(
 			stored?.stream === true ||
 			getEventIteratorSchemaDetails(def.outputSchema) !== undefined,
 		inputSchema: def.inputSchema,
-		outputSchema: def.outputSchema
+		outputSchema: def.outputSchema,
+		guards: stored?.guards ?? {},
+		dynamicGuards: stored?.dynamicGuards ?? []
 	}
 }
 

package/src/otel.ts

@@ -83,7 +83,15 @@ export type Tracing = {
 	end(span: SpanLike | undefined, error?: unknown): void
 }
 
-export function createTracing(otel: OtelApiLike | undefined): Tracing {
+export function createTracing(
+	otel: OtelApiLike | undefined,
+	/**
+	 * Errors the caller drives (4xx, aborts). Their span keeps an unset status
+	 * and no exception event, as OpenTelemetry asks of server spans, so the
+	 * caller's text stays out of the trace; `fn.error_code` still names them.
+	 */
+	isExpectedError: (error: unknown) => boolean = () => false
+): Tracing {
 	let tracer: TracerLike<SpanLike> | undefined
 	try {
 		tracer = otel?.trace.getTracer('orpc-fn')
@@ -96,11 +104,21 @@ export function createTracing(otel: OtelApiLike | undefined): Tracing {
 		if (error.length === 0) {
 			span.setStatus({ code: otel.SpanStatusCode.OK })
 		} else {
-			span.setStatus({
-				code: otel.SpanStatusCode.ERROR,
-				message: errorMessageOf(error[0])
-			})
-			if (error[0] instanceof Error) span.recordException(error[0])
+			const code = errorCodeOf(error[0])
+			if (code !== undefined) span.setAttribute('fn.error_code', code)
+			let expected = false
+			try {
+				expected = isExpectedError(error[0])
+			} catch {
+				/* A failing classifier treats the error as unexpected. */
+			}
+			if (!expected) {
+				span.setStatus({
+					code: otel.SpanStatusCode.ERROR,
+					message: errorMessageOf(error[0])
+				})
+				if (error[0] instanceof Error) span.recordException(error[0])
+			}
 		}
 		span.end()
 	}
@@ -195,11 +213,25 @@ export function errorMessageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error)
 }
 
-/** Error fields for a log line, named like the `fn.completed` ones. */
-export function errorAttributes(error: unknown) {
+/** An error's string `code` (`ORPCError`'s `NOT_FOUND`, Node's `ECONNRESET`). */
+export function errorCodeOf(error: unknown): string | undefined {
+	const code =
+		typeof error === 'object' && error !== null
+			? (error as { code?: unknown }).code
+			: undefined
+	return typeof code === 'string' ? code : undefined
+}
+
+/**
+ * Error fields for a log line, named like the `fn.completed` ones. Without
+ * `message`, the error's text (written for the caller) is left out.
+ */
+export function errorAttributes(error: unknown, message = true) {
+	const code = errorCodeOf(error)
 	return {
 		error_type: error instanceof Error ? error.name : typeof error,
-		error_message: errorMessageOf(error)
+		...(code === undefined ? {} : { error_code: code }),
+		...(message ? { error_message: errorMessageOf(error) } : {})
 	}
 }
 

package/src/react.ts

@@ -18,13 +18,17 @@ import {
 	type SubscriptionRunner,
 	seedQueryFn
 } from './realtime.js'
+import { streamCall } from './stream-call.js'
 
 export type { InvalidationDomain, LiveConnectionStatus } from './realtime.js'
 
-/** An oRPC client procedure fits: `client.order.watch`. */
+/**
+ * An oRPC client procedure fits: `client.order.watch`. It gets `streamCall`
+ * as its client context, which keeps it out of `createRpcLink`'s batches.
+ */
 export type SubscribeFn<TInput, TEvent> = (
 	input: TInput,
-	options: { signal: AbortSignal }
+	options: { signal: AbortSignal; context: typeof streamCall }
 ) => Promise<AsyncIterable<TEvent>>
 
 export type UseOrpcSubscriptionOptions<TInput, TEvent> = {
@@ -78,7 +82,10 @@ export function useOrpcSubscription<TInput, TEvent>(
 		runnerRef.current = createSubscriptionRunner<TEvent>({
 			open: (signal) => {
 				openedInput = latest.current.input
-				return latest.current.subscribe(openedInput, { signal })
+				return latest.current.subscribe(openedInput, {
+					signal,
+					context: streamCall
+				})
 			},
 			canConnect: () => latest.current.shouldRun,
 			shouldReconnect: () => latest.current.shouldRun,

package/src/route-options.ts

@@ -72,6 +72,14 @@ export function normalizeRoute(
 		throw new TypeError(
 			'orpc-fn: an event iterator schema cannot declare stream: false'
 		)
+	if (
+		stream !== true &&
+		!iterator &&
+		handler.constructor?.name === 'AsyncGeneratorFunction'
+	)
+		throw new TypeError(
+			`orpc-fn: ${name} has an async generator handler; declare stream: true`
+		)
 	for (const [guard, resolver] of Object.entries(guardResolvers)) {
 		if (!isGuard(guard))
 			throw new TypeError(`orpc-fn: unknown guard resolver "${guard}"`)

package/src/stream-call.ts

@@ -0,0 +1,15 @@
+/**
+ * Client-context key the `orpc-fn/vue` and `orpc-fn/react` stream helpers set,
+ * so `createRpcLink` keeps the call out of a batch without a stream manifest.
+ * Shared across package copies.
+ */
+export const STREAM_CALL: unique symbol = Symbol.for('orpc-fn.streamCall')
+
+/**
+ * Pass as the client context of a stream opened by hand:
+ * `client.metrics.run(input, { signal, context: streamCall })`.
+ */
+export const streamCall = { [STREAM_CALL]: true } as const
+
+export const isStreamCall = (context: object) =>
+	(context as { [STREAM_CALL]?: unknown })[STREAM_CALL] === true

package/src/timing.ts

@@ -3,3 +3,6 @@ export const REQUEST_TIMING = Symbol('orpc-fn.requestTiming')
 export type InvocationTiming = { procedureMs: number; calls: number }
 
 export const RAW_INPUT = Symbol('orpc-fn.rawInput')
+
+/** Extras a `createTestCall` replaces, carried through nested calls. */
+export const EXTRAS_OVERRIDE = Symbol('orpc-fn.extrasOverride')

package/src/tool-errors.ts

@@ -0,0 +1,52 @@
+import { isExpectedClientError } from './expected-client-error.js'
+import { formatIssue, issuesOf } from './issues.js'
+import { errorCodeOf, errorMessageOf } from './otel.js'
+
+/** How a tool adapter turns a failed call into text for the model. */
+export type ToolErrorOptions = {
+	/**
+	 * Errors the model may read. Default: `isExpectedClientError` (4xx
+	 * `ORPCError`, aborts, and whatever the factory's `isExpectedError` accepted).
+	 */
+	isExpectedError?: (error: unknown) => boolean
+	/** Unexpected errors, whose text the model does not see. Report them here. */
+	onError?: (error: unknown, info: { tool: string }) => void
+	/** Replace the text the model reads. */
+	formatError?: (
+		error: unknown,
+		info: { tool: string; expected: boolean }
+	) => string
+}
+
+/**
+ * An expected error reads `CODE: message`, then one `path: message` line per
+ * validation issue, so the model can fix its arguments. Anything else reads
+ * as a fixed sentence: its text may hold internals and goes to `onError`.
+ */
+export function toolErrorText(
+	error: unknown,
+	tool: string,
+	options: ToolErrorOptions
+): string {
+	let expected = false
+	try {
+		expected = (options.isExpectedError ?? isExpectedClientError)(error)
+	} catch {
+		/* A failing classifier hides the error. */
+	}
+	if (!expected) {
+		try {
+			options.onError?.(error, { tool })
+		} catch {
+			/* Reporting cannot change the tool's answer. */
+		}
+	}
+	if (options.formatError) return options.formatError(error, { tool, expected })
+	if (!expected) return `${tool} failed unexpectedly. The error was reported.`
+	const code = errorCodeOf(error)
+	const message = errorMessageOf(error)
+	return [
+		code ? `${code}: ${message}` : message,
+		...issuesOf(error).map(formatIssue)
+	].join('\n')
+}

package/src/types.ts

@@ -122,6 +122,8 @@ export type BuildProcedure = (options: {
 	procedure: string | undefined
 	route: Record<string, unknown>
 	meta: Record<string, unknown>
+	guards?: Record<string, unknown>
+	dynamicGuards?: readonly string[]
 	input?: AnySchema | undefined
 	output?: AnySchema | undefined
 	stream?: boolean

package/src/vue.ts

@@ -30,12 +30,13 @@ import {
 	type MaybeRefOrGetter,
 	onScopeDispose,
 	type Ref,
+	reactive,
 	ref,
 	shallowRef,
 	toValue,
 	watch
 } from 'vue'
-import { userFacingErrorMessage } from './client.js'
+import { streamCall, userFacingErrorMessage } from './client.js'
 import {
 	createInvalidationCoordinator,
 	createStreamScope,
@@ -93,17 +94,23 @@ const missingOrpc = () =>
 		'orpc-fn/vue: no oRPC client provided. Call provideOrpc(app, { client, utils }) or pass `orpc` to the composable.'
 	)
 
-/** The client and utils from {@link provideOrpc}. */
-export function useOrpc(): {
+type RegisteredOrpc = {
 	client: RegisteredOrpcClient
 	utils: RegisteredOrpcUtils
-} {
+}
+
+/**
+ * The client and utils from {@link provideOrpc}. Throws when none was
+ * provided, unless `optional`, which returns null instead.
+ */
+export function useOrpc(options: { optional: true }): RegisteredOrpc | null
+export function useOrpc(options?: { optional?: false }): RegisteredOrpc
+export function useOrpc(options?: {
+	optional?: boolean
+}): RegisteredOrpc | null {
 	const provided = hasInjectionContext() ? inject(orpcKey, null) : null
-	if (!provided) throw missingOrpc()
-	return provided as {
-		client: RegisteredOrpcClient
-		utils: RegisteredOrpcUtils
-	}
+	if (!provided && !options?.optional) throw missingOrpc()
+	return provided as RegisteredOrpc | null
 }
 
 /** Resolve the provided utils now; fail only when they are needed and missing. */
@@ -123,7 +130,7 @@ let documentVisible: Ref<boolean> | null = null
  * Whether the page is visible, from TanStack's `focusManager` (which follows
  * `visibilitychange` in browsers). Live streams pause while it is false.
  */
-function useDocumentVisible(): Ref<boolean> {
+export function useDocumentVisible(): Ref<boolean> {
 	if (!documentVisible) {
 		const visible = ref(focusManager.isFocused())
 		focusManager.subscribe((focused) => {
@@ -142,13 +149,15 @@ function resolveQueryEnabled(enabled: unknown): boolean {
 
 /**
  * Picks the stream to open from the utils. A procedure's `call` fits as is:
- * `(o) => o.order.watch.call`. The composable passes the input and an abort signal.
+ * `(o) => o.order.watch.call`. The composable passes the input, an abort
+ * signal and `streamCall` as the client context, which keeps the call out of
+ * `createRpcLink`'s batches.
  */
 export type OrpcSubscribeFn<TInput, TEvent, TOrpc = RegisteredOrpcUtils> = (
 	orpc: TOrpc
 ) => (
 	input: TInput,
-	options: { signal: AbortSignal }
+	options: { signal: AbortSignal; context: typeof streamCall }
 ) => Promise<AsyncIterable<TEvent>>
 
 export interface UseSubscriptionOptions<TEvent, TOrpc = RegisteredOrpcUtils> {
@@ -226,7 +235,8 @@ export function useOrpcSubscription<
 	const error = ref<Error | null>(null)
 
 	const runner = createSubscriptionRunner<TEvent>({
-		open: (signal) => subscribeFn(getUtils())(toValue(input), { signal }),
+		open: (signal) =>
+			subscribeFn(getUtils())(toValue(input), { signal, context: streamCall }),
 		canConnect: () => isStreamAllowed.value,
 		shouldReconnect: () => autoReconnectOnClose && shouldAutoConnect.value,
 		onStatus: (next) => {
@@ -393,7 +403,9 @@ function useBoundApiClient<TOrpc>(orpc: MaybeRefOrGetter<TOrpc> | undefined) {
 
 	/**
 	 * With `initialInput`, also returns `inputData`, a ref that `mutate()` and
-	 * `mutateAsync()` use when called without variables (form state).
+	 * `mutateAsync()` use when called without variables (form state). With
+	 * `invalidates`, a success invalidates those keys, awaited before the
+	 * options' own `onSuccess`: `{ invalidates: (o) => [o.order.key()] }`.
 	 */
 	// The input type comes from the route alone; `initialInput` is only checked
 	// against it. `unknown`, not `void`, lets `initialInput` pass the first
@@ -407,7 +419,10 @@ function useBoundApiClient<TOrpc>(orpc: MaybeRefOrGetter<TOrpc> | undefined) {
 		optionsFn: (
 			orpc: TOrpc
 		) => MutationObserverOptions<TData, TError, TVariables, TContext>,
-		config: { initialInput: NoInfer<TVariables> }
+		config: {
+			initialInput: NoInfer<TVariables>
+			invalidates?: (orpc: TOrpc) => readonly QueryKey[]
+		}
 	): UseMutationReturnType<TData, TError, TVariables, TContext> & {
 		inputData: Ref<TVariables>
 		mutate: (variables?: TVariables) => void
@@ -421,17 +436,41 @@ function useBoundApiClient<TOrpc>(orpc: MaybeRefOrGetter<TOrpc> | undefined) {
 	>(
 		optionsFn: (
 			orpc: TOrpc
-		) => MutationObserverOptions<TData, TError, TVariables, TContext>
+		) => MutationObserverOptions<TData, TError, TVariables, TContext>,
+		config?: { invalidates?: (orpc: TOrpc) => readonly QueryKey[] }
 	): UseMutationReturnType<TData, TError, TVariables, TContext>
 	function useMutation<TData, TError, TVariables, TContext>(
 		optionsFn: (
 			orpc: TOrpc
 		) => MutationObserverOptions<TData, TError, TVariables, TContext>,
-		config?: { initialInput: TVariables }
+		config?: {
+			initialInput?: TVariables
+			invalidates?: (orpc: TOrpc) => readonly QueryKey[]
+		}
 	) {
-		const mutation = useVueMutation(computed(() => optionsFn(getO())))
+		const invalidates = config?.invalidates
+		const mutation = useVueMutation(
+			computed(() => {
+				const options = optionsFn(getO())
+				if (!invalidates) return options
+				return {
+					...options,
+					onSuccess: async (
+						...args: Parameters<NonNullable<typeof options.onSuccess>>
+					) => {
+						await Promise.all(
+							invalidates(getO()).map((queryKey) =>
+								queryClient.invalidateQueries({ queryKey })
+							)
+						)
+						return options.onSuccess?.(...args)
+					}
+				}
+			})
+		)
 		if (config?.initialInput === undefined) return mutation
-		const inputData = ref(config.initialInput) as Ref<TVariables>
+		const initialInput = config.initialInput
+		const inputData = ref(initialInput) as Ref<TVariables>
 		return {
 			...mutation,
 			inputData,
@@ -796,3 +835,37 @@ export function useQueryErrorMessage(
 		return err ? userFacingErrorMessage(err, toValue(fallback)) : null
 	})
 }
+
+/** The parts of a query `useQueryState` reads. */
+export type QueryStateSource = {
+	status: Ref<'pending' | 'error' | 'success'>
+	error: Ref<unknown>
+	isFetching: Ref<boolean>
+	failureCount: Ref<number>
+	refetch: () => Promise<unknown>
+}
+
+/**
+ * A query as the props a list or loading component takes, in one reactive
+ * object: `<ListStates v-bind="useQueryState(query, { fallback })" />`.
+ * `errorMessage` follows {@link useQueryErrorMessage}.
+ */
+export function useQueryState(
+	query: QueryStateSource,
+	options: { fallback: MaybeRefOrGetter<string> }
+) {
+	const errorMessage = useQueryErrorMessage(query.error, options.fallback)
+	return reactive({
+		status: computed(() => query.status.value),
+		error: computed(() => query.error.value),
+		errorMessage,
+		isRetrying: computed(
+			() =>
+				query.isFetching.value &&
+				(query.status.value === 'error' || query.failureCount.value > 0)
+		),
+		retry: () => {
+			void query.refetch()
+		}
+	})
+}