orpc-fn 0.1.0 → 0.3.0

package/src/otel.ts

@@ -84,9 +84,15 @@ export type Tracing = {
 }
 
 export function createTracing(otel: OtelApiLike | undefined): Tracing {
-	const tracer = otel?.trace.getTracer('orpc-fn')
+	let tracer: TracerLike<SpanLike> | undefined
+	try {
+		tracer = otel?.trace.getTracer('orpc-fn')
+	} catch {
+		/* Missing telemetry cannot prevent execution. */
+	}
 	const end: Tracing['end'] = (span, ...error) => {
 		if (!span || !otel) return
+		span = protectSpan(span)
 		if (error.length === 0) {
 			span.setStatus({ code: otel.SpanStatusCode.OK })
 		} else {
@@ -103,6 +109,8 @@ export function createTracing(otel: OtelApiLike | undefined): Tracing {
 			const settle = (span: SpanLike | undefined, ...error: [] | [unknown]) => {
 				try {
 					onSettled?.(span, ...error)
+				} catch {
+					/* Telemetry callbacks cannot replace the original result. */
 				} finally {
 					end(span, ...error)
 				}
@@ -111,6 +119,7 @@ export function createTracing(otel: OtelApiLike | undefined): Tracing {
 				span: SpanLike | undefined,
 				scope?: StreamScope
 			): Promise<Awaited<ReturnType<typeof fn>>> => {
+				span = span ? protectSpan(span) : undefined
 				let result: Awaited<ReturnType<typeof fn>>
 				try {
 					result = await fn(span)
@@ -129,18 +138,54 @@ export function createTracing(otel: OtelApiLike | undefined): Tracing {
 				return result
 			}
 			if (!tracer || !otel) return run(undefined)
-			return tracer.startActiveSpan(
-				name,
-				{ kind: otel.SpanKind[kind] },
-				(span) => {
-					const active = otel.context.active()
-					return run(span, (step) => otel.context.with(active as never, step))
-				}
-			)
+			let started: Promise<Awaited<ReturnType<typeof fn>>> | undefined
+			try {
+				return tracer.startActiveSpan(
+					name,
+					{ kind: otel.SpanKind[kind] },
+					(span) => {
+						let active: unknown
+						try {
+							active = otel.context.active()
+						} catch {
+							/* Fall back to the span without scope restoration. */
+						}
+						started = run(span, (step) => {
+							let completed: { value: ReturnType<typeof step> } | undefined
+							let failed: { error: unknown } | undefined
+							try {
+								return otel.context.with(active as never, () => {
+									try {
+										const value = step()
+										completed = { value }
+										return value
+									} catch (error) {
+										failed = { error }
+										throw error
+									}
+								})
+							} catch {
+								if (completed) return completed.value
+								if (failed) throw failed.error
+								return step()
+							}
+						})
+						return started
+					}
+				)
+			} catch {
+				return started ?? run(undefined)
+			}
 		},
 		startSpan(name, kind, attributes) {
 			if (!tracer || !otel) return undefined
-			return tracer.startSpan(name, { kind: otel.SpanKind[kind], attributes })
+			try {
+				return protectSpan(
+					tracer.startSpan(name, { kind: otel.SpanKind[kind], attributes })
+				)
+			} catch {
+				return undefined
+			}
 		},
 		end
 	}
@@ -149,3 +194,25 @@ export function createTracing(otel: OtelApiLike | undefined): Tracing {
 export function errorMessageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error)
 }
+
+function protectSpan<T extends SpanLike>(span: T): T {
+	return new Proxy(span, {
+		get(target, key) {
+			const value = Reflect.get(target, key, target)
+			if (typeof value !== 'function') return value
+			if (
+				['setAttribute', 'setStatus', 'recordException', 'end'].includes(
+					String(key)
+				)
+			)
+				return (...args: unknown[]) => {
+					try {
+						return value.apply(target, args)
+					} catch {
+						/* Ignore exporter failures. */
+					}
+				}
+			return value.bind(target)
+		}
+	})
+}

package/src/route-options.ts

@@ -0,0 +1,100 @@
+import {
+	type AnySchema,
+	type ErrorMap,
+	getEventIteratorSchemaDetails
+} from '@orpc/contract'
+import { ROUTE_OPTION_KEYS } from './types.js'
+
+type Resolver = (params: {
+	input: unknown
+	context: unknown
+	signal: AbortSignal | undefined
+}) => unknown
+function schemaOption(schema: unknown, name: string): AnySchema | undefined {
+	if (schema === undefined) return undefined
+	if (
+		typeof schema !== 'object' ||
+		schema === null ||
+		!('~standard' in schema) ||
+		typeof (schema as AnySchema)['~standard']?.validate !== 'function'
+	)
+		throw new TypeError(`orpc-fn: ${name} must be a Standard Schema`)
+	return schema as AnySchema
+}
+
+/** Runtime validation for JavaScript callers and spread route options. */
+export function normalizeRoute(
+	options: Record<string, unknown>,
+	isGuard: (key: string) => boolean
+) {
+	const {
+		handler,
+		input: rawInput,
+		output: rawOutput,
+		name,
+		procedure,
+		meta: appMeta = {},
+		stream,
+		errors,
+		guardResolvers = {},
+		...rest
+	} = options
+	if (typeof name !== 'string' || !name || typeof handler !== 'function')
+		throw new TypeError('orpc-fn: routes require a name and handler')
+	if (procedure !== undefined && typeof procedure !== 'string')
+		throw new TypeError('orpc-fn: procedure must be a configured key')
+	if (typeof appMeta !== 'object' || appMeta === null || Array.isArray(appMeta))
+		throw new TypeError('orpc-fn: meta must be an object')
+	if (stream !== undefined && typeof stream !== 'boolean')
+		throw new TypeError('orpc-fn: stream must be boolean')
+	if (
+		typeof guardResolvers !== 'object' ||
+		guardResolvers === null ||
+		Array.isArray(guardResolvers)
+	)
+		throw new TypeError('orpc-fn: guardResolvers must be an object')
+	const input = schemaOption(rawInput, 'input')
+	const output = schemaOption(rawOutput, 'output')
+	const route: Record<string, unknown> = {}
+	const guardChecks: Array<[string, unknown]> = []
+	for (const [option, value] of Object.entries(rest)) {
+		if ((ROUTE_OPTION_KEYS as readonly string[]).includes(option))
+			route[option] = value
+		else if (isGuard(option)) {
+			if (value !== undefined) guardChecks.push([option, value])
+		} else
+			throw new TypeError(
+				`orpc-fn: unknown route option "${option}"; put application metadata in meta`
+			)
+	}
+	const iterator = getEventIteratorSchemaDetails(output) !== undefined
+	if (stream === false && iterator)
+		throw new TypeError(
+			'orpc-fn: an event iterator schema cannot declare stream: false'
+		)
+	for (const [guard, resolver] of Object.entries(guardResolvers)) {
+		if (!isGuard(guard))
+			throw new TypeError(`orpc-fn: unknown guard resolver "${guard}"`)
+		if (typeof resolver !== 'function')
+			throw new TypeError(
+				`orpc-fn: guard resolver "${guard}" must be a function`
+			)
+		if (guardChecks.some(([key]) => key === guard))
+			throw new TypeError(
+				`orpc-fn: guard "${guard}" has both a value and resolver`
+			)
+	}
+	return {
+		handler: handler as (params: Record<PropertyKey, unknown>) => unknown,
+		input,
+		output,
+		name,
+		procedure,
+		meta: appMeta as Record<string, unknown>,
+		stream: stream === true || iterator,
+		errors: errors as ErrorMap | undefined,
+		guardResolvers: guardResolvers as Record<string, Resolver>,
+		route,
+		guardChecks
+	}
+}

package/src/router.ts

@@ -1,4 +1,10 @@
-import type { AnyRouter } from '@orpc/server'
+import {
+	type AnyRouter,
+	type AnyProcedure,
+	resolveContractProcedures,
+	traverseContractProcedures
+} from '@orpc/server'
+import { readFnMeta } from './meta.js'
 
 /**
  * Creates a router object from routes or nested routers.
@@ -13,3 +19,54 @@ import type { AnyRouter } from '@orpc/server'
 export function createRouter<T extends AnyRouter>(routes: T): Readonly<T> {
 	return routes
 }
+
+/** Serialize these paths to a frontend module; this helper belongs on the server. */
+export function createStreamManifest(
+	router: AnyRouter
+): readonly (readonly string[])[] {
+	const paths: string[][] = []
+	const unresolved = traverseContractProcedures(
+		{ router, path: [] },
+		({ contract, path }) => {
+			if (readFnMeta(contract as AnyProcedure).stream) paths.push([...path])
+		}
+	)
+	if (unresolved.length)
+		throw new TypeError(
+			'orpc-fn: lazy routers require createStreamManifestAsync'
+		)
+	return paths
+}
+
+/** Resolve lazy routers before generating the same serializable path manifest. */
+export async function createStreamManifestAsync(
+	router: AnyRouter
+): Promise<readonly (readonly string[])[]> {
+	const paths: string[][] = []
+	await resolveContractProcedures(
+		{ router, path: [] },
+		({ contract, path }) => {
+			if (readFnMeta(contract as AnyProcedure).stream) paths.push([...path])
+		}
+	)
+	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/timing.ts

@@ -0,0 +1,5 @@
+/** Internal bridge shared by the execution middleware and HTTP adapters. */
+export const REQUEST_TIMING = Symbol('orpc-fn.requestTiming')
+export type InvocationTiming = { procedureMs: number; calls: number }
+
+export const RAW_INPUT = Symbol('orpc-fn.rawInput')