orpc-fn 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "orpc-fn",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Define a backend function once: a typed oRPC procedure with tracing, logging, guards, injected handler extras, nested calls and live queries over Redis.",
 	"type": "module",
 	"license": "MIT",
@@ -74,9 +74,16 @@
 		"./mcp/sdk": {
 			"types": "./dist/mcp/sdk.d.ts",
 			"import": "./dist/mcp/sdk.js"
+		},
+		"./mcp/server": {
+			"types": "./dist/mcp/server.d.ts",
+			"import": "./dist/mcp/server.js"
 		}
 	},
 	"types": "./dist/index.d.ts",
+	"bin": {
+		"orpc-fn": "./dist/cli.js"
+	},
 	"files": [
 		"dist",
 		"LICENSE",
@@ -113,7 +120,8 @@
 		"hono": "^4.0.0",
 		"ioredis": "^5.0.0",
 		"zod": "^4.0.0",
-		"@modelcontextprotocol/sdk": "^1.32.0"
+		"@modelcontextprotocol/sdk": "^1.32.0",
+		"@modelcontextprotocol/server": "^2.0.0"
 	},
 	"peerDependenciesMeta": {
 		"@mastra/core": {
@@ -139,13 +147,18 @@
 		},
 		"@modelcontextprotocol/sdk": {
 			"optional": true
+		},
+		"@modelcontextprotocol/server": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.2",
 		"@biomejs/biome": "^2.2.4",
 		"@mastra/core": "1.51.0",
+		"@modelcontextprotocol/client": "2.3.0",
 		"@modelcontextprotocol/sdk": "1.32.0",
+		"@modelcontextprotocol/server": "2.3.0",
 		"@opentelemetry/api": "^1.9.0",
 		"@orpc/client": "1.14.8",
 		"@orpc/contract": "1.14.8",

package/src/cli.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// biome-ignore-all lint/suspicious/noConsole: a CLI reports on the console
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { parseArgs } from 'node:util'
+import type { AnyRouter } from '@orpc/server'
+import { createStreamManifestAsync, renderStreamManifest } from './router.js'
+
+const usage = `Usage: orpc-fn stream-manifest <module>[#export] --out <file.ts|file.json> [--name streamPaths] [--check]
+
+Imports the router (export "default" unless #export is given) and writes the
+paths of its streaming routes for createRpcLink({ streamPaths }). The file is
+only written when its content changes. --check writes nothing and exits 1 when
+the file is missing or stale. Importing the router runs its module code; run
+TypeScript routers with a runtime that loads .ts (bun, tsx, node >= 22.18).`
+
+async function run(argv: readonly string[]): Promise<number> {
+	const { positionals, values } = parseArgs({
+		args: [...argv],
+		allowPositionals: true,
+		options: {
+			out: { type: 'string' },
+			name: { type: 'string' },
+			check: { type: 'boolean' },
+			help: { type: 'boolean', short: 'h' }
+		}
+	})
+	const [command, target] = positionals
+	if (values.help || command !== 'stream-manifest' || !target || !values.out) {
+		console.error(usage)
+		return values.help ? 0 : 2
+	}
+	const [modulePath = '', exportName = 'default'] = target.split('#')
+	const loaded: Record<string, unknown> = await import(
+		pathToFileURL(resolve(modulePath)).href
+	)
+	const router = loaded[exportName]
+	if (!router || typeof router !== 'object') {
+		console.error(`orpc-fn: ${modulePath} has no router export "${exportName}"`)
+		return 2
+	}
+	const out = resolve(values.out)
+	const source = renderStreamManifest(
+		await createStreamManifestAsync(router as AnyRouter),
+		{ format: out.endsWith('.json') ? 'json' : 'ts', name: values.name }
+	)
+	const current = await readFile(out, 'utf8').catch(() => undefined)
+	if (current === source) return 0
+	if (values.check) {
+		console.error(
+			`orpc-fn: ${values.out} is stale; rerun without --check to update it`
+		)
+		return 1
+	}
+	await writeFile(out, source)
+	console.log(`orpc-fn: wrote ${values.out}`)
+	return 0
+}
+
+// Exit explicitly: the imported router may hold open database or broker handles.
+run(process.argv.slice(2)).then(
+	(code) => process.exit(code),
+	(error) => {
+		console.error(error)
+		process.exit(1)
+	}
+)

package/src/create-fn.ts

@@ -38,7 +38,7 @@ import {
 	type CurrentContextOf,
 	type BuilderLike,
 	type FiniteExtras,
-	type FiniteScopedExtras,
+	type ScopedExtrasGuard,
 	type Fn,
 	type FnCompletedEvent,
 	type FnDefinition,
@@ -115,7 +115,7 @@ export type CreateFnOptions<
 			signal: AbortSignal | undefined
 			name: string
 			procedure: K
-		}) => MaybePromise<TScoped[K]>
+		}) => MaybePromise<TScoped[K] & ScopedExtrasGuard<NoInfer<TScoped[K]>>>
 	}
 	/**
 	 * Checks run before the handler; each key becomes a typed `fn()` option.
@@ -240,8 +240,7 @@ export function createFn<
 		TLogger,
 		TScoped
 	> &
-		FiniteExtras<NoInfer<TExtras>> &
-		FiniteScopedExtras<NoInfer<TScoped>>
+		FiniteExtras<NoInfer<TExtras>>
 ): FnFactory<
 	Definition<
 		TProcedures,

package/src/index.ts

@@ -22,7 +22,8 @@ export type {
 export {
 	createRouter,
 	createStreamManifest,
-	createStreamManifestAsync
+	createStreamManifestAsync,
+	renderStreamManifest
 } from './router.js'
 export type {
 	AnyFnContext,

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

@@ -204,7 +204,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 +529,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
 	}
 
 	/**
@@ -1241,8 +1251,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/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 }