orpc-fn 0.1.0

package/src/otel.ts

@@ -0,0 +1,151 @@
+import {
+	isAsyncIteratorObject,
+	onStreamEnd,
+	type StreamScope
+} from './stream.js'
+
+/** Attribute values accepted by OpenTelemetry spans. */
+export type AttributeValue = string | number | boolean
+
+/** The part of an OpenTelemetry `Span` this package uses. */
+export interface SpanLike {
+	setAttribute(key: string, value: AttributeValue): unknown
+	setStatus(status: { code: number; message?: string }): unknown
+	recordException(exception: Error): unknown
+	end(): unknown
+}
+
+type SpanOptionsLike = {
+	kind?: number
+	attributes?: Record<string, AttributeValue>
+}
+
+interface TracerLike<TSpan> {
+	startActiveSpan<F extends (span: TSpan) => unknown>(
+		name: string,
+		options: SpanOptionsLike,
+		fn: F
+	): ReturnType<F>
+	startSpan(name: string, options?: SpanOptionsLike): TSpan
+}
+
+/**
+ * The part of `@opentelemetry/api` this package uses. Pass the module itself:
+ * `import * as otel from '@opentelemetry/api'` then `createFn({ otel })`.
+ * Without it no spans are created and handlers receive `span: undefined`.
+ */
+export interface OtelApiLike<TSpan extends SpanLike = SpanLike> {
+	trace: { getTracer(name: string): TracerLike<TSpan> }
+	SpanStatusCode: { OK: number; ERROR: number }
+	SpanKind: {
+		INTERNAL: number
+		SERVER: number
+		PRODUCER: number
+	}
+	/** Restores a span's context for each step of a stream it returned. */
+	context: {
+		active(): unknown
+		with<T>(context: never, fn: () => T): T
+	}
+}
+
+/** The span type of an OpenTelemetry API, or `SpanLike` when absent. */
+export type SpanOf<TOtel> =
+	TOtel extends OtelApiLike<infer TSpan> ? TSpan : SpanLike
+
+/** Called once when a span's work is done, before the span ends. */
+export type OnSettled = (
+	span: SpanLike | undefined,
+	...error: [] | [unknown]
+) => void
+
+export type Tracing = {
+	/**
+	 * Run `fn` inside an active span: OK when it resolves, ERROR when it throws,
+	 * ended either way. When `fn` resolves to a stream, the span stays open -
+	 * and active for each step of the stream - until the stream ends.
+	 * `onSettled` runs once at that point, before the span ends. Without
+	 * OpenTelemetry `span` is undefined and `onSettled` still runs.
+	 */
+	inSpan<T>(
+		name: string,
+		kind: 'INTERNAL' | 'SERVER' | 'PRODUCER',
+		fn: (span: SpanLike | undefined) => Promise<T>,
+		onSettled?: OnSettled
+	): Promise<T>
+	/** Start a span that the caller ends with `end` (long-lived streams). */
+	startSpan(
+		name: string,
+		kind: 'SERVER',
+		attributes: Record<string, AttributeValue>
+	): SpanLike | undefined
+	/** Set OK, or ERROR with `error`, and end the span. */
+	end(span: SpanLike | undefined, error?: unknown): void
+}
+
+export function createTracing(otel: OtelApiLike | undefined): Tracing {
+	const tracer = otel?.trace.getTracer('orpc-fn')
+	const end: Tracing['end'] = (span, ...error) => {
+		if (!span || !otel) return
+		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])
+		}
+		span.end()
+	}
+	return {
+		inSpan(name, kind, fn, onSettled) {
+			const settle = (span: SpanLike | undefined, ...error: [] | [unknown]) => {
+				try {
+					onSettled?.(span, ...error)
+				} finally {
+					end(span, ...error)
+				}
+			}
+			const run = async (
+				span: SpanLike | undefined,
+				scope?: StreamScope
+			): Promise<Awaited<ReturnType<typeof fn>>> => {
+				let result: Awaited<ReturnType<typeof fn>>
+				try {
+					result = await fn(span)
+				} catch (error) {
+					settle(span, error)
+					throw error
+				}
+				if (isAsyncIteratorObject(result)) {
+					return onStreamEnd(
+						result,
+						(...error) => settle(span, ...error),
+						scope
+					) as typeof result
+				}
+				settle(span)
+				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))
+				}
+			)
+		},
+		startSpan(name, kind, attributes) {
+			if (!tracer || !otel) return undefined
+			return tracer.startSpan(name, { kind: otel.SpanKind[kind], attributes })
+		},
+		end
+	}
+}
+
+export function errorMessageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}

package/src/router.ts

@@ -0,0 +1,15 @@
+import type { AnyRouter } from '@orpc/server'
+
+/**
+ * Creates a router object from routes or nested routers.
+ * Simply returns the routes as a const object for type inference.
+ *
+ * @example
+ * ```ts
+ * const items = createRouter({ getItem, updateItem })
+ * export const api = createRouter({ metabase, items })
+ * ```
+ */
+export function createRouter<T extends AnyRouter>(routes: T): Readonly<T> {
+	return routes
+}

package/src/stream.ts

@@ -0,0 +1,54 @@
+/** A value oRPC streams to the client (an async generator or iterator). */
+export function isAsyncIteratorObject(
+	value: unknown
+): value is AsyncIterator<unknown> & AsyncIterable<unknown> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as AsyncIterable<unknown>)[Symbol.asyncIterator] ===
+			'function' &&
+		typeof (value as AsyncIterator<unknown>).next === 'function'
+	)
+}
+
+/** Runs one step of a stream inside some context (e.g. its tracing span). */
+export type StreamScope = <T>(step: () => T) => T
+
+/**
+ * Wraps a stream so `finish` runs once when it ends: after the last item,
+ * when it throws (with the error), or when the consumer stops early with
+ * `return()` - also before the first `next()`, which a plain async generator
+ * wrapper would miss. With `scope`, every `next`/`return`/`throw` runs inside
+ * it: a generator's body runs on those calls, long after it was created.
+ */
+export function onStreamEnd<T>(
+	stream: AsyncIterator<T> & AsyncIterable<T>,
+	finish: (...error: [] | [unknown]) => void,
+	scope: StreamScope = (step) => step()
+): AsyncIterator<T> & AsyncIterable<T> {
+	let finished = false
+	const done = (...error: [] | [unknown]) => {
+		if (finished) return
+		finished = true
+		finish(...error)
+	}
+	const settle = async (step: () => Promise<IteratorResult<T>> | undefined) => {
+		try {
+			const result = await step()
+			if (!result || result.done) done()
+			return result ?? { done: true as const, value: undefined }
+		} catch (error) {
+			done(error)
+			throw error
+		}
+	}
+	const wrapped: AsyncIterator<T> & AsyncIterable<T> = {
+		next: (...args) => settle(() => scope(() => stream.next(...args))),
+		return: (value) =>
+			settle(() => scope(() => stream.return?.(value))).finally(() => done()),
+		throw: (error) =>
+			settle(() => scope(() => stream.throw?.(error) ?? Promise.reject(error))),
+		[Symbol.asyncIterator]: () => wrapped
+	}
+	return wrapped
+}

package/src/types.ts

@@ -0,0 +1,389 @@
+import type {
+	AnySchema,
+	ErrorMap,
+	InferSchemaInput,
+	InferSchemaOutput,
+	Meta,
+	Schema
+} from '@orpc/contract'
+import type {
+	AnyProcedure,
+	DecoratedProcedure,
+	Procedure,
+	Route
+} from '@orpc/server'
+import type { ZodType, z } from 'zod'
+import type { BoundCall } from './bound-call.js'
+import type { FnLogger } from './logger.js'
+import type { SpanLike } from './otel.js'
+
+export type MaybePromise<T> = T | Promise<T>
+
+/**
+ * An oRPC builder without input or output schema: `os`, `os.$context<T>()`,
+ * `os.use(...)`. A schema set on the builder is rejected by `createFn`; set it
+ * on the route instead.
+ */
+/* biome-ignore-start lint/suspicious/noExplicitAny: matches every builder's generic methods */
+export type BuilderLike = {
+	route(route: any): unknown
+	meta(meta: any): unknown
+	input(schema: any): unknown
+	output(schema: any): unknown
+	handler(handler: any): Procedure<any, any, any, any, any, any>
+}
+/* biome-ignore-end lint/suspicious/noExplicitAny: matches every builder's generic methods */
+
+/** Input a procedure is called with (before its input schema runs). */
+export type ProcedureInput<T> =
+	T extends Procedure<
+		infer _TInitial,
+		infer _TCurrent,
+		infer TInputSchema extends AnySchema,
+		infer _TOut,
+		infer _TErrors,
+		infer _TMeta
+	>
+		? InferSchemaInput<TInputSchema>
+		: unknown
+
+/** What a procedure resolves to (after its output schema runs). */
+export type ProcedureOutput<T> =
+	T extends Procedure<
+		infer _TInitial,
+		infer _TCurrent,
+		infer _TIn,
+		infer TOutputSchema extends AnySchema,
+		infer _TErrors,
+		infer _TMeta
+	>
+		? InferSchemaOutput<TOutputSchema>
+		: unknown
+
+/** Context a procedure must be called with. */
+export type ProcedureContext<T> =
+	T extends Procedure<
+		infer TContext,
+		infer _TCurrent,
+		infer _TIn,
+		infer _TOut,
+		infer _TErrors,
+		infer _TMeta
+	>
+		? TContext
+		: never
+
+/** `Omit` that keeps each member of a union (handler params narrow by discriminant). */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
+	? Omit<T, K>
+	: never
+
+/** `fn()` options passed to oRPC's `.route()`; `RouteConfig` is derived from it. */
+export const ROUTE_OPTION_KEYS = [
+	'path',
+	'method',
+	'summary',
+	'description',
+	'deprecated',
+	'successStatus',
+	'successDescription',
+	'inputStructure',
+	'outputStructure',
+	'tags'
+] as const satisfies readonly (keyof Route)[]
+
+/**
+ * `fn()` option names owned by the route itself. Guard and meta keys must not
+ * reuse them: such an option would be read as the route option and the guard
+ * would never run.
+ */
+export const RESERVED_OPTION_KEYS = [
+	...ROUTE_OPTION_KEYS,
+	'name',
+	'procedure',
+	'input',
+	'output',
+	'handler',
+	'live',
+	'operationId'
+] as const
+
+export type ReservedOptionKey = (typeof RESERVED_OPTION_KEYS)[number]
+
+/** @internal Builds one route from a `procedures` builder; shared by `fn` and `createPubSub`. */
+export type BuildProcedure = (options: {
+	name: string
+	procedure: string | undefined
+	route: Record<string, unknown>
+	meta: Record<string, unknown>
+	input?: AnySchema | undefined
+	output?: AnySchema | undefined
+	handler: (options: {
+		input: unknown
+		context: Record<string, unknown>
+		signal?: AbortSignal
+	}) => unknown
+}) => AnyProcedure
+
+/** Turns every key of `T` found in `K` into a readable type error. */
+export type RejectKeys<T, K extends PropertyKey, TMessage extends string> = {
+	[P in Extract<keyof T, K>]: TMessage
+}
+
+/**
+ * Handler extras must have known keys: an index signature would claim every
+ * handler param. Intersected into `createFn`'s options to reject it.
+ */
+export type FiniteExtras<T> = string extends keyof T
+	? { 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' }
+		: unknown
+
+type ProcedureOf<TBuilder> = TBuilder extends {
+	handler(handler: never): infer TProcedure
+}
+	? TProcedure
+	: never
+
+/** Context a route built from this builder is called with. */
+export type InitialContextOf<TBuilder> = ProcedureContext<ProcedureOf<TBuilder>>
+
+/** Context the handler sees, after the builder's middleware. */
+export type CurrentContextOf<TBuilder> =
+	ProcedureOf<TBuilder> extends Procedure<
+		infer _TInitial,
+		infer TContext,
+		infer _TIn,
+		infer _TOut,
+		infer _TErrors,
+		infer _TMeta
+	>
+		? TContext
+		: never
+
+type ErrorMapOf<TBuilder> =
+	ProcedureOf<TBuilder> extends {
+		'~orpc': { errorMap: infer T extends ErrorMap }
+	}
+		? T
+		: ErrorMap
+type MetaOf<TBuilder> =
+	ProcedureOf<TBuilder> extends { '~orpc': { meta: infer T extends Meta } }
+		? T
+		: Meta
+
+/**
+ * Everything `createFn` inferred from its options. Route types read from it;
+ * apps rarely spell it out.
+ */
+export type FnDefinition = {
+	procedures: Record<string, BuilderLike>
+	default: string
+	extras: object
+	guards: object
+	meta: object
+	tag: string
+	span: SpanLike
+	logger: FnLogger
+}
+
+export type ProcedureKey<TDef extends FnDefinition> = keyof TDef['procedures'] &
+	string
+
+/** Context the handler of a `procedure: TKey` route receives. */
+export type FnContext<
+	TDef extends FnDefinition,
+	TKey extends ProcedureKey<TDef>
+> = CurrentContextOf<TDef['procedures'][TKey]>
+
+/** Union of every procedure's handler context: what guards and extras see. */
+export type AnyFnContext<TDef extends FnDefinition> = {
+	[K in ProcedureKey<TDef>]: FnContext<TDef, K>
+}[ProcedureKey<TDef>]
+
+export type GuardParams<TContext, TMeta> = {
+	context: TContext
+	input: unknown
+	/** Route name (operationId). */
+	name: string
+	/** Procedures key the route was built from. */
+	procedure: string
+	meta: Partial<TMeta>
+	signal: AbortSignal | undefined
+}
+
+/**
+ * A check run before the handler. Its first parameter becomes an option on
+ * `fn({...})`; the guard runs only on routes that set it. Throw (usually an
+ * `ORPCError`) to refuse the call.
+ */
+export type Guard<TValue, TParams> = (value: TValue, params: TParams) => unknown
+
+export type GuardOptions<TGuards> = {
+	[K in keyof TGuards]?: TGuards[K] extends (
+		value: infer TValue,
+		params: never
+	) => unknown
+		? TValue
+		: never
+}
+
+export type HandlerParams<
+	TDef extends FnDefinition,
+	TInput,
+	TKey extends ProcedureKey<TDef>
+> = DistributiveOmit<
+	TDef['extras'],
+	'input' | 'context' | 'call' | 'signal' | 'span' | 'logger'
+> & {
+	input: TInput
+	context: FnContext<TDef, TKey>
+	/** Calls another procedure with this context and signal, in a child span. */
+	call: BoundCall<FnContext<TDef, TKey>>
+	/** Cancellation is inherited by nested calls; pass to interruptible I/O. */
+	signal: AbortSignal | undefined
+	/** Active OpenTelemetry span, undefined when `createFn({ otel })` is not set. */
+	span: TDef['span'] | undefined
+	logger: TDef['logger']
+}
+
+/** Route options shared by every `fn()` overload. */
+export type RouteConfig<TTag extends string = string> = Pick<
+	Route,
+	Exclude<(typeof ROUTE_OPTION_KEYS)[number], 'tags'>
+> & {
+	/** Required. Becomes the OpenAPI operationId and the span name (e.g. 'user.create'). */
+	name: string
+	tags?: TTag[]
+}
+
+export type FnRouteOptions<
+	TDef extends FnDefinition,
+	TKey extends ProcedureKey<TDef>
+> = RouteConfig<TDef['tag']> &
+	GuardOptions<TDef['guards']> &
+	TDef['meta'] &
+	ProcedureOption<TDef, TKey>
+
+/**
+ * Which `createFn({ procedures })` builder a route uses. Optional when
+ * `createFn` has a `default`; required on every route when it has none.
+ */
+export type ProcedureOption<
+	TDef extends FnDefinition,
+	TKey extends ProcedureKey<TDef>
+> = [TDef['default']] extends [never]
+	? { procedure: TKey }
+	: { procedure?: TKey }
+
+export type FnProcedure<
+	TDef extends FnDefinition,
+	TKey extends ProcedureKey<TDef>,
+	TInputSchema extends Schema<unknown, unknown>,
+	TOutputSchema extends Schema<unknown, unknown>
+> = DecoratedProcedure<
+	InitialContextOf<TDef['procedures'][TKey]>,
+	FnContext<TDef, TKey>,
+	TInputSchema,
+	TOutputSchema,
+	ErrorMapOf<TDef['procedures'][TKey]>,
+	MetaOf<TDef['procedures'][TKey]>
+>
+
+type InputOf<T> = [T] extends [ZodType] ? z.output<T> : unknown
+type ReturnOf<TOut, TReturn> = [TOut] extends [ZodType]
+	? z.input<TOut>
+	: TReturn
+
+/** `fn()`: four overloads for input/output schema × inferred. */
+export interface Fn<TDef extends FnDefinition> {
+	// 1. With input + output schema
+	<
+		TInput extends ZodType,
+		TOut extends ZodType,
+		TKey extends ProcedureKey<TDef> = TDef['default']
+	>(
+		options: {
+			input: TInput
+			output: TOut
+			// The output schema parses what the handler returns: its input type.
+			handler: (
+				params: HandlerParams<TDef, z.output<TInput>, NoInfer<TKey>>
+			) => MaybePromise<z.input<TOut>>
+		} & FnRouteOptions<TDef, TKey>
+	): FnProcedure<TDef, TKey, TInput, TOut>
+
+	// 2. With input, inferred output
+	<
+		TInput extends ZodType,
+		TReturn,
+		TKey extends ProcedureKey<TDef> = TDef['default']
+	>(
+		options: {
+			input: TInput
+			output?: undefined
+			handler: (
+				params: HandlerParams<TDef, z.output<TInput>, NoInfer<TKey>>
+			) => MaybePromise<TReturn>
+		} & FnRouteOptions<TDef, TKey>
+	): FnProcedure<TDef, TKey, TInput, Schema<TReturn, TReturn>>
+
+	// 3. No input, with output schema
+	<TOut extends ZodType, TKey extends ProcedureKey<TDef> = TDef['default']>(
+		options: {
+			input?: undefined
+			output: TOut
+			handler: (
+				params: HandlerParams<TDef, unknown, NoInfer<TKey>>
+			) => MaybePromise<z.input<TOut>>
+		} & FnRouteOptions<TDef, TKey>
+	): FnProcedure<TDef, TKey, Schema<unknown, unknown>, TOut>
+
+	// 4. No input, inferred output
+	<TReturn, TKey extends ProcedureKey<TDef> = TDef['default']>(
+		options: {
+			input?: undefined
+			output?: undefined
+			handler: (
+				params: HandlerParams<TDef, unknown, NoInfer<TKey>>
+			) => MaybePromise<TReturn>
+		} & FnRouteOptions<TDef, TKey>
+	): FnProcedure<TDef, TKey, Schema<unknown, unknown>, Schema<TReturn, TReturn>>
+
+	// 5. Never matches valid code first; it only words the type errors, which
+	// TypeScript reports against the last overload.
+	<
+		TReturn,
+		TInput extends ZodType | undefined = undefined,
+		TOut extends ZodType | undefined = undefined,
+		TKey extends ProcedureKey<TDef> = TDef['default']
+	>(
+		options: {
+			input?: TInput
+			output?: TOut
+			// The output schema parses what the handler returns: its input type.
+			handler: (
+				params: HandlerParams<TDef, InputOf<TInput>, NoInfer<TKey>>
+			) => MaybePromise<ReturnOf<TOut, TReturn>>
+		} & FnRouteOptions<TDef, TKey>
+	): FnProcedure<
+		TDef,
+		TKey,
+		[TInput] extends [ZodType] ? TInput : Schema<unknown, unknown>,
+		[TOut] extends [ZodType] ? TOut : Schema<TReturn, TReturn>
+	>
+}
+
+/** What `fn.completed` reports, and what `onCompleted` receives. */
+export type FnCompletedEvent<TContext = unknown, TSpan = SpanLike> = {
+	name: string
+	procedure: string
+	durationMs: number
+	success: boolean
+	error: unknown
+	input: unknown
+	context: TContext
+	span: TSpan | undefined
+	meta: Record<string, unknown>
+}