orpc-fn 0.1.0 → 0.3.0

package/src/live/redis-bun.ts

@@ -64,11 +64,13 @@ export function bunRedisTransport(
 					subscriber.onclose = () => {}
 					if (owned) return subscriber.close()
 					// A given subscriber stays open: remove only this transport's listeners.
-					for (const channel of ours) {
-						void Promise.resolve()
-							.then(() => subscriber.unsubscribe(channel, dispatch))
-							.catch(() => {})
-					}
+					return Promise.all(
+						[...ours].map((channel) =>
+							Promise.resolve()
+								.then(() => subscriber.unsubscribe(channel, dispatch))
+								.catch(() => {})
+						)
+					).then(() => {})
 				}
 			}
 		}

package/src/live/redis.ts

@@ -76,7 +76,7 @@ export type SubscriberConnection = {
 	 */
 	resubscribe?(channel: string): Promise<unknown>
 	/** Stop delivering and release the connection (if the driver created it). */
-	close(): void
+	close(): void | Promise<void>
 }
 
 /** Callbacks for one connection; they do nothing once it is replaced. */
@@ -91,6 +91,7 @@ export type SubscriberHandlers = {
 type Entry = {
 	listener: (payload: string) => void
 	onLost: ((error: Error) => void) | undefined
+	onReconnect: (() => void) | undefined
 }
 
 type ChannelState = {
@@ -114,27 +115,35 @@ export function createRedisTransport(driver: {
 	connectSubscriber: (
 		handlers: SubscriberHandlers
 	) => Promise<SubscriberConnection>
-}): PubSubTransport & { close(): void } {
+}): PubSubTransport & { close(): Promise<void> } {
 	const publishScript = createLuaScript(driver.send, PUBLISH_LUA)
 	const channels = new Map<string, ChannelState>()
 	// An UNSUBSCRIBE still in flight would cancel a SUBSCRIBE sent after it.
 	const unsubscribing = new Map<string, Promise<unknown>>()
 	let current: {
 		connection: Promise<SubscriberConnection>
-		retire: () => void
+		retire: () => Promise<void>
 	} | null = null
 
 	const connect = () => {
 		let retired = false
+		let closing: Promise<void> | undefined
 		const retire = (error?: Error) => {
-			if (retired) return
+			if (retired) return closing ?? Promise.resolve()
 			retired = true
 			if (current?.connection === connection) current = null
-			void connection.then((open) => open.close()).catch(() => {})
-			if (!error) return
+			closing = connection.then((open) => open.close()).catch(() => {})
+			if (!error) return closing
 			const lost = [...channels.values()].flatMap((state) => [...state.entries])
 			channels.clear()
-			for (const entry of lost) entry.onLost?.(error)
+			for (const entry of lost) {
+				try {
+					entry.onLost?.(error)
+				} catch {
+					/* One callback cannot interrupt retirement. */
+				}
+			}
+			return closing
 		}
 		const handlers: SubscriberHandlers = {
 			onMessage(channel, message) {
@@ -157,6 +166,17 @@ export function createRedisTransport(driver: {
 					.then((open) =>
 						Promise.all(settled.map((channel) => open.resubscribe?.(channel)))
 					)
+					.then(() => {
+						if (retired) return
+						for (const channel of settled)
+							for (const entry of [...(channels.get(channel)?.entries ?? [])]) {
+								try {
+									entry.onReconnect?.()
+								} catch {
+									/* Isolate subscriber callbacks. */
+								}
+							}
+					})
 					.catch((error) => retire(asError(error)))
 			},
 			onLost: (error) => retire(error)
@@ -202,9 +222,13 @@ export function createRedisTransport(driver: {
 			])
 			return Array.isArray(items) ? items.map(String) : []
 		},
-		async subscribe(channel, listener, onLost) {
+		async subscribe(channel, listener, onLost, options) {
 			const connection = await (current?.connection ?? connect())
-			const entry: Entry = { listener, onLost }
+			const entry: Entry = {
+				listener,
+				onLost,
+				onReconnect: options?.onReconnect
+			}
 			await unsubscribing.get(channel)
 			let state = channels.get(channel)
 			if (!state) {
@@ -244,9 +268,11 @@ export function createRedisTransport(driver: {
 				await done
 			}
 		},
-		close() {
-			current?.retire()
+		async close() {
+			const closing = current?.retire()
 			channels.clear()
+			await closing
+			await Promise.allSettled([...unsubscribing.values()])
 		}
 	}
 }

package/src/live/transport.ts

@@ -15,6 +15,8 @@ export type BacklogOptions = {
  * The backlog of a channel lives at `${channel}:backlog` (see {@link backlogKey}).
  */
 export interface PubSubTransport {
+	/** Optional disposal, used only with ownsTransport: true. */
+	close?: () => void | Promise<void>
 	/**
 	 * Publish every message, in order. With `backlog`, also append each payload
 	 * to its channel's backlog, trim and refresh its TTL - atomically, so a
@@ -34,7 +36,8 @@ export interface PubSubTransport {
 	subscribe(
 		channel: string,
 		listener: (payload: string) => void,
-		onLost?: (error: Error) => void
+		onLost?: (error: Error) => void,
+		options?: { onReconnect?: () => void }
 	): Promise<() => Promise<void>>
 }
 

package/src/logger.ts

@@ -26,3 +26,23 @@ export function createDefaultLogger(scope: string): FnLogger {
 			console.error(format(scope, message, attributes))
 	}
 }
+
+/** Protect telemetry calls while preserving application logger extensions. */
+export function protectLogger<T extends FnLogger>(logger: T): T {
+	return new Proxy(logger, {
+		get(target, key) {
+			const value = Reflect.get(target, key, target)
+			if (typeof value !== 'function') return value
+			if (['debug', 'info', 'warn', 'error'].includes(String(key))) {
+				return (...args: unknown[]) => {
+					try {
+						return value.apply(target, args)
+					} catch {
+						/* Telemetry must not replace a procedure outcome. */
+					}
+				}
+			}
+			return value.bind(target)
+		}
+	})
+}

package/src/mastra.ts

@@ -2,6 +2,7 @@ import type { RequestContext } from '@mastra/core/request-context'
 import { createTool, type Tool } from '@mastra/core/tools'
 import { type AnyProcedure, call } from '@orpc/server'
 import {
+	isObjectJsonSchema,
 	passThroughOutputSchema,
 	rawInputSchema,
 	type ToolSchema
@@ -64,6 +65,8 @@ export function createMastraTool<TProc extends AnyProcedure>(
 	options: CreateMastraToolOptions = {}
 ): MastraTool<TProc> {
 	const meta = readFnMeta(procedure)
+	if (meta.stream)
+		throw new TypeError('orpc-fn: streaming procedures cannot be Mastra tools')
 	const name = options.id ?? meta.name
 	if (!name) {
 		throw new Error(
@@ -73,7 +76,7 @@ export function createMastraTool<TProc extends AnyProcedure>(
 	let inputSchema: ToolSchema | undefined
 	if (meta.inputSchema) {
 		inputSchema = rawInputSchema(meta.inputSchema)
-		if (inputSchema['~standard'].jsonSchema.input().type !== 'object') {
+		if (!isObjectJsonSchema(inputSchema['~standard'].jsonSchema.input())) {
 			throw new Error(`${name} must take an object input to be an agent tool`)
 		}
 	} else if (!options.allowMissingInputSchema) {
@@ -114,12 +117,17 @@ export function createMastraTool<TProc extends AnyProcedure>(
 				)
 			}
 			const startedAt = performance.now()
-			const finish = (outcome: 'success' | 'error') =>
-				options.onExecuteFinish?.({
-					toolId: id,
-					durationMs: performance.now() - startedAt,
-					outcome
-				})
+			const finish = (outcome: 'success' | 'error') => {
+				try {
+					options.onExecuteFinish?.({
+						toolId: id,
+						durationMs: performance.now() - startedAt,
+						outcome
+					})
+				} catch {
+					/* A telemetry hook cannot change tool execution. */
+				}
+			}
 			try {
 				const result = await call(
 					procedure,

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

@@ -0,0 +1,36 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+	CallToolRequestSchema,
+	ListToolsRequestSchema,
+	type CallToolResult
+} from '@modelcontextprotocol/sdk/types.js'
+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 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 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/mcp.ts

@@ -4,6 +4,7 @@ import {
 	type TraverseContractProcedureCallbackOptions,
 	traverseContractProcedures
 } from '@orpc/server'
+import { procedureDefinition } from './compatibility.js'
 import { rawInputSchema, type ToolSchema } from './json-schema.js'
 import { readFnMeta, toToolName } from './meta.js'
 
@@ -35,39 +36,66 @@ export type McpTool = {
 export const hasTag =
 	(tag: string): ProcedureFilter =>
 	({ contract }) =>
-		contract['~orpc'].route.tags?.includes(tag) ?? false
+		procedureDefinition(contract).route?.tags?.includes(tag) ?? false
 
 const isGet: ProcedureFilter = ({ contract }) =>
-	contract['~orpc'].route.method === 'GET'
+	procedureDefinition(contract).route?.method === 'GET'
 
 /**
  * MCP tool definitions for the procedures in `router` matching `filter`
- * (default: all). Register them with any MCP server:
- * `server.registerTool(tool.name, tool.config, run)`.
+ * (default: all). These are inspection definitions, not McpServer.registerTool configs.
+ * Use registerMcpTools from orpc-fn/mcp/sdk for executable registration.
  *
  * `readOnly` sets `readOnlyHint`; it defaults to GET routes, since an MCP
  * client treats anything else as a mutation and may ask for approval.
  */
 export function listTools(
 	router: AnyRouter,
-	options: { filter?: ProcedureFilter; readOnly?: ProcedureFilter } = {}
+	options: {
+		filter?: ProcedureFilter
+		readOnly?: ProcedureFilter
+		name?: (options: TraverseContractProcedureCallbackOptions) => string
+	} = {}
 ): McpTool[] {
 	const { filter, readOnly = isGet } = options
 	const tools: McpTool[] = []
-	traverseContractProcedures({ router, path: [] }, (traversed) => {
-		if (filter && !filter(traversed)) return
-		const procedure = traversed.contract as AnyProcedure
-		const { inputSchema, route } = procedure['~orpc']
-		const description = route.description ?? route.summary
-		tools.push({
-			name: toToolName(readFnMeta(procedure).name ?? traversed.path.join('.')),
-			procedure,
-			config: {
-				...(description === undefined ? {} : { description }),
-				...(inputSchema ? { inputSchema: rawInputSchema(inputSchema) } : {}),
-				annotations: { readOnlyHint: readOnly(traversed) }
-			}
-		})
-	})
+	const names = new Map<string, AnyProcedure>()
+	const unresolved = traverseContractProcedures(
+		{ router, path: [] },
+		(traversed) => {
+			if (filter && !filter(traversed)) return
+			const procedure = traversed.contract as AnyProcedure
+			const meta = readFnMeta(procedure)
+			if (meta.stream)
+				throw new TypeError(
+					`orpc-fn: streaming procedure ${meta.name ?? traversed.path.join('.')} cannot be an MCP tool`
+				)
+			const name =
+				options.name?.(traversed) ??
+				toToolName(meta.name ?? traversed.path.join('.'))
+			const previous = names.get(name)
+			if (previous === procedure) return
+			if (previous)
+				throw new TypeError(
+					`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
+			tools.push({
+				name,
+				procedure,
+				config: {
+					...(description === undefined ? {} : { description }),
+					...(inputSchema ? { inputSchema: rawInputSchema(inputSchema) } : {}),
+					annotations: { readOnlyHint: readOnly(traversed) }
+				}
+			})
+		}
+	)
+	if (unresolved.length)
+		throw new TypeError(
+			'orpc-fn: resolve lazy routers with unlazyRouter before listing MCP tools'
+		)
 	return tools
 }

package/src/meta.ts

@@ -1,4 +1,5 @@
-import type { AnySchema } from '@orpc/contract'
+import { getEventIteratorSchemaDetails, type AnySchema } from '@orpc/contract'
+import { type LibraryMeta, procedureDefinition } from './compatibility.js'
 import type { AnyProcedure } from '@orpc/server'
 
 /**
@@ -9,17 +10,24 @@ import type { AnyProcedure } from '@orpc/server'
  */
 export const FN_META_KEY = 'orpc-fn'
 
-export type StoredFnMeta = {
+export type StoredFnMeta<
+	TMeta extends object = Record<string, unknown>,
+	TKey extends string = string
+> = {
 	name: string
-	procedure: string
-	meta: Record<string, unknown>
+	procedure: TKey
+	meta: TMeta
+	stream: boolean
 }
 
-export type FnMeta<TMeta extends object = Record<string, unknown>> = {
+export type FnMeta<
+	TMeta extends object = Record<string, unknown>,
+	TKey extends string = string
+> = {
 	/** `fn({ name })`, also the OpenAPI operationId; undefined if not made by `fn()`. */
 	name: string | undefined
 	/** The `procedures` key the route was built from. */
-	procedure: string | undefined
+	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 ''. */
@@ -27,40 +35,48 @@ export type FnMeta<TMeta extends object = Record<string, unknown>> = {
 	summary: string | undefined
 	method: string | undefined
 	path: string | undefined
+	stream: boolean
 	tags: readonly string[]
 	inputSchema: AnySchema | undefined
 	outputSchema: AnySchema | undefined
 }
 
-type ProcedureDefinition = {
-	meta?: Record<string, unknown>
-	route?: {
-		summary?: string
-		description?: string
-		method?: string
-		path?: string
-		tags?: readonly string[]
-	}
-	inputSchema?: AnySchema
-	outputSchema?: AnySchema
+/** Read what `fn()` (and oRPC) recorded on a procedure. */
+type MetaFrom<T> = [LibraryMeta<T>] extends [never]
+	? Record<string, unknown>
+	: LibraryMeta<T> extends StoredFnMeta<infer M, string>
+		? M
+		: Record<string, unknown>
+
+type KeyFrom<T> = [LibraryMeta<T>] extends [never]
+	? string
+	: LibraryMeta<T> extends StoredFnMeta<object, infer K>
+		? K
+		: string
+
+/** Declares the route metadata contract; it does not provide defaults. */
+export function defineMeta<T extends object>(): T {
+	return {} as T
 }
 
-/** Read what `fn()` (and oRPC) recorded on a procedure. */
-export function readFnMeta<TMeta extends object = Record<string, unknown>>(
-	procedure: AnyProcedure
-): FnMeta<TMeta> {
-	const def = (procedure as { '~orpc'?: ProcedureDefinition })['~orpc'] ?? {}
+export function readFnMeta<T extends AnyProcedure>(
+	procedure: T
+): FnMeta<MetaFrom<T>, KeyFrom<T>> {
+	const def = procedureDefinition(procedure)
 	const stored = def.meta?.[FN_META_KEY] as StoredFnMeta | undefined
 	const route = def.route ?? {}
 	return {
 		name: stored?.name,
-		procedure: stored?.procedure,
-		meta: (stored?.meta ?? {}) as Partial<TMeta>,
+		procedure: stored?.procedure as KeyFrom<T> | undefined,
+		meta: (stored?.meta ?? {}) as Partial<MetaFrom<T>>,
 		description: route.summary ?? route.description ?? '',
 		summary: route.summary,
 		method: route.method,
 		path: route.path,
 		tags: route.tags ?? [],
+		stream:
+			stored?.stream === true ||
+			getEventIteratorSchemaDetails(def.outputSchema) !== undefined,
 		inputSchema: def.inputSchema,
 		outputSchema: def.outputSchema
 	}