orpc-fn 0.2.0 → 0.4.0

package/src/live/fn-live.ts

@@ -66,10 +66,14 @@ export type FnLiveConfig<
 	ChannelQueueOptions & {
 		/** Subscribe route name; default `${name}.live`. */
 		name?: string
-		/** Validates parsed reducer state without reapplying an output transform. Required with a transformer. */
-		stateSchema?: Schema<TOutput, TOutput>
+		/**
+		 * Validates reducer state without reapplying an output transform. Required with a
+		 * transformer. Its input may be looser than its output (e.g. branded IDs); it is
+		 * checked at runtime.
+		 */
+		stateSchema?: Schema<unknown, TOutput>
 		/** Validates patch payloads. Required when a transformer returns fnLivePatch. */
-		emitSchema?: Schema<TEmit, TEmit>
+		emitSchema?: Schema<unknown, TEmit>
 		/** Optional access check before each update; idle streams keep their initial authorization. */
 		reauthorize?: AuthFn<TInput, FnContext<TDef, TKey>>
 		eventSchema: TEventSchema
@@ -122,10 +126,10 @@ export type FnLiveConfig<
 					TEmit,
 					TErrors
 				>
-				stateSchema: Schema<TOutput, TOutput>
+				stateSchema: Schema<unknown, TOutput>
 		  }
 	) &
-	([TEmit] extends [never] ? object : { emitSchema: Schema<TEmit, TEmit> })
+	([TEmit] extends [never] ? object : { emitSchema: Schema<unknown, TEmit> })
 
 type FnLiveConfigTransformer<
 	TDef extends FnDefinition,

package/src/live/pub-sub.ts

@@ -2,7 +2,12 @@ import type { Schema } from '@orpc/contract'
 import { ORPCError } from '@orpc/server'
 import type { ZodObject, ZodRawShape, ZodType, z } from 'zod'
 import type { FnLogger } from '../logger.js'
-import { errorMessageOf, type SpanLike, type Tracing } from '../otel.js'
+import {
+	errorAttributes,
+	errorMessageOf,
+	type SpanLike,
+	type Tracing
+} from '../otel.js'
 import type {
 	GuardOptions,
 	FnContext,
@@ -204,7 +209,11 @@ export type CreatePublisher = <TEventSchema extends ZodType>(
 export type PubSubRuntimeOptions = {
 	/** Queue depths, drops, successful reconnects and parse failures. */
 	onMetric?: (event: PubSubMetric) => void
-	transport: PubSubTransport
+	/**
+	 * The broker, or a function creating it on first use so importing routes
+	 * opens no connection: `transport: () => bunRedisTransport(getRedis())`.
+	 */
+	transport: PubSubTransport | (() => PubSubTransport)
 	/**
 	 * Called per event dropped from ingress, replay or delivery queues.
 	 * Delivery drops count events before subscriber filtering.
@@ -525,13 +534,19 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 	// the client's backoff reconnects to the new deployment.
 	const activeSubscriberCleanups = new Set<() => void>()
 
+	let transport: PubSubTransport | undefined
 	const requireTransport = () => {
 		if (!options.pubsub) {
 			throw new Error(
 				'orpc-fn: live routes need a transport, pass createFn({ pubsub: { transport } })'
 			)
 		}
-		return options.pubsub.transport
+		if (transport) return transport
+		// A lazy transport is never created during or after shutdown.
+		assertOpen()
+		const configured = options.pubsub.transport
+		transport = typeof configured === 'function' ? configured() : configured
+		return transport
 	}
 
 	/**
@@ -696,8 +711,9 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 								name: config.name,
 								channel
 							})
-							logger.warn(`Dropped malformed message on ${channel}`, {
-								error: errorMessageOf(error)
+							logger.warn('pubsub.message_dropped', {
+								channel,
+								...errorAttributes(error)
 							})
 						}
 					}
@@ -711,7 +727,8 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				if (closed || timer) return
 				const delayMs = getResubscribeDelayMs(attempt)
 				attempt++
-				logger.warn(`Scheduling resubscribe for ${channel}`, {
+				logger.warn('pubsub.resubscribe_scheduled', {
+					channel,
 					reason,
 					attempt,
 					delayMs
@@ -739,8 +756,9 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 								connected = false
 								markPending()
 							}
-							logger.error(`Subscription to ${channel} lost`, {
-								error: error.message
+							logger.error('pubsub.subscription_lost', {
+								channel,
+								...errorAttributes(error)
 							})
 							scheduleResubscribe('lost')
 						},
@@ -774,10 +792,11 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 					connectedOnce = true
 					markReady()
 					attempt = 0
-					logger.info(`Subscribed to ${channel}`)
+					logger.debug('pubsub.subscribed', { channel })
 				} catch (error) {
-					logger.error(`Failed to subscribe to ${channel}`, {
-						error: errorMessageOf(error)
+					logger.error('pubsub.subscribe_failed', {
+						channel,
+						...errorAttributes(error)
 					})
 					scheduleResubscribe('subscribe-failed')
 				}
@@ -916,7 +935,7 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				throw error
 			}
 
-			subscriberLogger.info(`Subscribing to ${channelName}`)
+			subscriberLogger.debug('pubsub.subscribing', { channel: channelName })
 
 			let messageCount = 0
 			let droppedCount = 0
@@ -1041,7 +1060,8 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				span?.setAttribute('pubsub.message_count', messageCount)
 				span?.setAttribute('pubsub.dropped_count', droppedCount)
 				tracing.end(span, ...error)
-				subscriberLogger.info(`Unsubscribed from ${channelName}`, {
+				subscriberLogger.debug('pubsub.unsubscribed', {
+					channel: channelName,
 					messageCount,
 					droppedCount,
 					durationMs: Math.round(durationMs)
@@ -1096,10 +1116,10 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 						if (items.length > maxReplay) replayGap = true
 					} catch (error) {
 						replayGap = true
-						subscriberLogger.warn(
-							`Failed to replay backlog for ${channelName}`,
-							{ error: errorMessageOf(error) }
-						)
+						subscriberLogger.warn('pubsub.replay_failed', {
+							channel: channelName,
+							...errorAttributes(error)
+						})
 					}
 				}
 				for (const { data, id } of replaying ?? [])
@@ -1241,8 +1261,7 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			shutdownPromise = (async () => {
 				await Promise.allSettled([...pendingOpens])
 				await Promise.all([...releases])
-				if (options.pubsub?.ownsTransport)
-					await options.pubsub.transport.close?.()
+				if (options.pubsub?.ownsTransport) await transport?.close?.()
 			})()
 			return shutdownPromise
 		},

package/src/mcp/core.ts

@@ -0,0 +1,102 @@
+import {
+	type AnyRouter,
+	type InferRouterInitialContext,
+	call
+} from '@orpc/server'
+import { isObjectJsonSchema } from '../json-schema.js'
+import { listTools, type McpTool, type ProcedureFilter } from '../mcp.js'
+
+/** Text-only tool result: the shape both MCP SDK majors accept. */
+export type TextToolResult = {
+	content: { type: 'text'; text: string }[]
+	isError?: boolean
+}
+
+export type RegisterMcpToolsOptions<R extends AnyRouter, TResult> = {
+	/** Tool exposure must be an explicit application choice. */
+	filter: ProcedureFilter
+	context: (request: {
+		name: string
+		signal: AbortSignal
+	}) => InferRouterInitialContext<R> | Promise<InferRouterInitialContext<R>>
+	readOnly?: ProcedureFilter
+	name?: NonNullable<Parameters<typeof listTools>[1]>['name']
+	formatResult?: (value: unknown, tool: McpTool) => TResult | Promise<TResult>
+}
+
+/** Default protocol result: JSON/text. Provide formatResult for other MCP content. */
+export function formatMcpResult(value: unknown): TextToolResult {
+	const text =
+		typeof value === 'string'
+			? value
+			: (JSON.stringify(value, (_key, item) =>
+					typeof item === 'bigint' ? item.toString() : item
+				) ?? 'null')
+	return { content: [{ type: 'text', text }] }
+}
+
+const errorResult = (text: string): TextToolResult => ({
+	content: [{ type: 'text', text }],
+	isError: true
+})
+
+/** @internal SDK-independent `tools/list` and `tools/call` behind both adapters. */
+export function createToolHandlers<R extends AnyRouter, TResult>(
+	router: R,
+	options: RegisterMcpToolsOptions<R, TResult>
+) {
+	const definitions = listTools(router, {
+		filter: options.filter,
+		...(options.readOnly ? { readOnly: options.readOnly } : {}),
+		...(options.name ? { name: options.name } : {})
+	})
+	const tools = new Map(definitions.map((tool) => [tool.name, tool]))
+	const descriptions = definitions.map((tool) => {
+		const inputSchema = tool.config.inputSchema?.[
+			'~standard'
+		].jsonSchema.input() ?? { type: 'object', properties: {} }
+		if (!isObjectJsonSchema(inputSchema))
+			throw new TypeError(
+				`orpc-fn: MCP tool ${tool.name} needs an object input`
+			)
+		// MCP requires a top-level object; object unions retain their constraints.
+		return {
+			name: tool.name,
+			...tool.config,
+			inputSchema: { ...inputSchema, type: 'object' as const }
+		}
+	})
+	return {
+		names: [...tools.keys()] as readonly string[],
+		list: () => ({ tools: descriptions }),
+		call: async (
+			name: string,
+			args: Record<string, unknown> | undefined,
+			signal: AbortSignal
+		): Promise<TResult | TextToolResult> => {
+			const tool = tools.get(name)
+			if (!tool) return errorResult(`Unknown tool: ${name}`)
+			try {
+				signal.throwIfAborted()
+				const validation = await tool.config.inputSchema?.[
+					'~standard'
+				].validate(args ?? {})
+				if (validation?.issues)
+					return errorResult(
+						validation.issues.map((issue) => issue.message).join('; ')
+					)
+				const context = await options.context({ name: tool.name, signal })
+				const result = await call(tool.procedure, validation?.value, {
+					context,
+					signal
+				})
+				return await (options.formatResult ?? formatMcpResult)(result, tool)
+			} catch (error) {
+				if (signal.aborted) throw error
+				return errorResult(
+					error instanceof Error ? error.message : String(error)
+				)
+			}
+		}
+	}
+}

package/src/mcp/sdk.ts

@@ -4,115 +4,33 @@ import {
 	ListToolsRequestSchema,
 	type CallToolResult
 } from '@modelcontextprotocol/sdk/types.js'
+import type { AnyRouter } from '@orpc/server'
 import {
-	type AnyRouter,
-	type InferRouterInitialContext,
-	call
-} from '@orpc/server'
-import { isObjectJsonSchema } from '../json-schema.js'
-import { listTools, type McpTool, type ProcedureFilter } from '../mcp.js'
+	createToolHandlers,
+	formatMcpResult,
+	type RegisterMcpToolsOptions as CoreOptions
+} from './core.js'
 
-export type RegisterMcpToolsOptions<R extends AnyRouter> = {
-	/** Tool exposure must be an explicit application choice. */
-	filter: ProcedureFilter
-	context: (request: {
-		name: string
-		signal: AbortSignal
-	}) => InferRouterInitialContext<R> | Promise<InferRouterInitialContext<R>>
-	readOnly?: ProcedureFilter
-	name?: NonNullable<Parameters<typeof listTools>[1]>['name']
-	formatResult?: (
-		value: unknown,
-		tool: McpTool
-	) => CallToolResult | Promise<CallToolResult>
-}
+export { formatMcpResult }
 
-/** Default protocol result: JSON/text. Provide formatResult for other MCP content. */
-export function formatMcpResult(value: unknown): CallToolResult {
-	const text =
-		typeof value === 'string'
-			? value
-			: (JSON.stringify(value, (_key, item) =>
-					typeof item === 'bigint' ? item.toString() : item
-				) ?? 'null')
-	return { content: [{ type: 'text', text }] }
-}
+export type RegisterMcpToolsOptions<R extends AnyRouter> = CoreOptions<
+	R,
+	CallToolResult
+>
 
-/** Register on the SDK's low-level Server, or on McpServer.server. */
+/**
+ * Register on the SDK v1 low-level Server, or on McpServer.server. For SDK v2
+ * (`@modelcontextprotocol/server`) use `orpc-fn/mcp/server`.
+ */
 export function registerMcpTools<R extends AnyRouter>(
 	server: Pick<Server, 'setRequestHandler'>,
 	router: R,
 	options: RegisterMcpToolsOptions<R>
 ): readonly string[] {
-	const definitions = listTools(router, {
-		filter: options.filter,
-		...(options.readOnly ? { readOnly: options.readOnly } : {}),
-		...(options.name ? { name: options.name } : {})
-	})
-	const tools = new Map(definitions.map((tool) => [tool.name, tool]))
-	const descriptions = definitions.map((tool) => {
-		const inputSchema = tool.config.inputSchema?.[
-			'~standard'
-		].jsonSchema.input() ?? { type: 'object', properties: {} }
-		if (!isObjectJsonSchema(inputSchema))
-			throw new TypeError(
-				`orpc-fn: MCP tool ${tool.name} needs an object input`
-			)
-		// MCP requires a top-level object; object unions retain their constraints.
-		return {
-			name: tool.name,
-			...tool.config,
-			inputSchema: { ...inputSchema, type: 'object' as const }
-		}
-	})
-	server.setRequestHandler(ListToolsRequestSchema, () => ({
-		tools: descriptions
-	}))
-	server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-		const tool = tools.get(request.params.name)
-		if (!tool)
-			return {
-				content: [
-					{ type: 'text', text: `Unknown tool: ${request.params.name}` }
-				],
-				isError: true
-			}
-		try {
-			extra.signal.throwIfAborted()
-			const validation = await tool.config.inputSchema?.['~standard'].validate(
-				request.params.arguments ?? {}
-			)
-			if (validation?.issues)
-				return {
-					content: [
-						{
-							type: 'text',
-							text: validation.issues.map((issue) => issue.message).join('; ')
-						}
-					],
-					isError: true
-				}
-			const context = await options.context({
-				name: tool.name,
-				signal: extra.signal
-			})
-			const result = await call(tool.procedure, validation?.value, {
-				context,
-				signal: extra.signal
-			})
-			return await (options.formatResult ?? formatMcpResult)(result, tool)
-		} catch (error) {
-			if (extra.signal.aborted) throw error
-			return {
-				content: [
-					{
-						type: 'text',
-						text: error instanceof Error ? error.message : String(error)
-					}
-				],
-				isError: true
-			}
-		}
-	})
-	return [...tools.keys()]
+	const handlers = createToolHandlers(router, options)
+	server.setRequestHandler(ListToolsRequestSchema, handlers.list)
+	server.setRequestHandler(CallToolRequestSchema, (request, extra) =>
+		handlers.call(request.params.name, request.params.arguments, extra.signal)
+	)
+	return handlers.names
 }

package/src/mcp/server.ts

@@ -0,0 +1,35 @@
+import type { CallToolResult, Server } from '@modelcontextprotocol/server'
+import type { AnyRouter } from '@orpc/server'
+import {
+	createToolHandlers,
+	formatMcpResult,
+	type RegisterMcpToolsOptions as CoreOptions
+} from './core.js'
+
+export { formatMcpResult }
+
+export type RegisterMcpToolsOptions<R extends AnyRouter> = CoreOptions<
+	R,
+	CallToolResult
+>
+
+/**
+ * Register on the SDK v2 (`@modelcontextprotocol/server`) low-level Server, or
+ * on McpServer.server. Declare `capabilities: { tools: {} }` on the Server.
+ */
+export function registerMcpTools<R extends AnyRouter>(
+	server: Pick<Server, 'setRequestHandler'>,
+	router: R,
+	options: RegisterMcpToolsOptions<R>
+): readonly string[] {
+	const handlers = createToolHandlers(router, options)
+	server.setRequestHandler('tools/list', handlers.list)
+	server.setRequestHandler('tools/call', (request, ctx) =>
+		handlers.call(
+			request.params.name,
+			request.params.arguments,
+			ctx.mcpReq.signal
+		)
+	)
+	return handlers.names
+}

package/src/otel.ts

@@ -195,6 +195,14 @@ 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) {
+	return {
+		error_type: error instanceof Error ? error.name : typeof error,
+		error_message: errorMessageOf(error)
+	}
+}
+
 function protectSpan<T extends SpanLike>(span: T): T {
 	return new Proxy(span, {
 		get(target, key) {

package/src/router.ts

@@ -51,3 +51,22 @@ export async function createStreamManifestAsync(
 	)
 	return paths
 }
+
+/**
+ * Deterministic module source for a stream manifest: paths sorted, `json`
+ * as an array, `ts` as `export const <name>`. Used by `orpc-fn stream-manifest`.
+ */
+export function renderStreamManifest(
+	paths: readonly (readonly string[])[],
+	options: { format: 'json' | 'ts'; name?: string | undefined }
+): string {
+	const lines = paths
+		.map(
+			(path) =>
+				`\t[${path.map((segment) => JSON.stringify(segment)).join(', ')}]`
+		)
+		.sort()
+	const array = lines.length ? `[\n${lines.join(',\n')}\n]` : '[]'
+	if (options.format === 'json') return `${array}\n`
+	return `// Generated by \`orpc-fn stream-manifest\`. Do not edit.\nexport const ${options.name ?? 'streamPaths'}: readonly (readonly string[])[] = ${array}\n`
+}

package/src/types.ts

@@ -140,6 +140,17 @@ export type RejectKeys<T, K extends PropertyKey, TMessage extends string> = {
 	[P in Extract<keyof T, K>]: TMessage
 }
 
+/** Params every handler receives; extras may not reuse these names. */
+type HandlerParamKey =
+	| 'input'
+	| 'context'
+	| 'call'
+	| 'signal'
+	| 'span'
+	| 'logger'
+	| 'errors'
+	| 'lastEventId'
+
 /**
  * Handler extras must have known keys: an index signature would claim every
  * handler param. Intersected into `createFn`'s options to reject it.
@@ -149,17 +160,7 @@ export type FiniteExtras<T> = T extends unknown
 		? { extras: 'orpc-fn: extras need known keys, not an index signature' }
 		: number extends keyof T
 			? { extras: 'orpc-fn: extras need known keys, not an index signature' }
-			: Extract<
-						keyof T,
-						| 'input'
-						| 'context'
-						| 'call'
-						| 'signal'
-						| 'span'
-						| 'logger'
-						| 'errors'
-						| 'lastEventId'
-					> extends never
+			: Extract<keyof T, HandlerParamKey> extends never
 				? unknown
 				: { extras: 'orpc-fn: extras cannot shadow handler parameters' }
 	: never
@@ -272,14 +273,7 @@ export type HandlerParams<
 				: object
 			: object
 	>,
-	| 'input'
-	| 'context'
-	| 'call'
-	| 'signal'
-	| 'span'
-	| 'logger'
-	| 'errors'
-	| 'lastEventId'
+	HandlerParamKey
 > & {
 	input: TInput
 	context: FnContext<TDef, TKey>
@@ -506,26 +500,14 @@ export type CompletedHookEvent<
 		)
 }[keyof TProcedures & string]
 
-export type FiniteScopedExtras<T> = {
-	[K in keyof T]: string extends keyof T[K]
-		? K
-		: number extends keyof T[K]
-			? K
-			: Extract<
-						keyof T[K],
-						| 'input'
-						| 'context'
-						| 'call'
-						| 'signal'
-						| 'span'
-						| 'logger'
-						| 'errors'
-						| 'lastEventId'
-					> extends never
-				? never
-				: K
-}[keyof T] extends never
-	? unknown
-	: {
-			extrasByProcedure: 'orpc-fn: scoped extras need finite keys and cannot shadow handler parameters'
-		}
+/**
+ * Intersected into each scoped extras function's return type: rejects index
+ * signatures and handler-parameter names at the offending property. A
+ * top-level conditional over the whole map broke inference when zero-argument
+ * and context-reading functions were mixed.
+ */
+export type ScopedExtrasGuard<T> = (string extends keyof T
+	? { 'orpc-fn: scoped extras need finite keys': never }
+	: number extends keyof T
+		? { 'orpc-fn: scoped extras need finite keys': never }
+		: unknown) & { [K in HandlerParamKey]?: never }