orpc-fn 0.4.0 → 0.5.0

package/src/live/fn-live.ts

@@ -4,7 +4,7 @@ import type { ZodType, z } from 'zod'
 import { RAW_INPUT } from '../timing.js'
 import { LIVE_GAP, positiveInteger } from './lifecycle.js'
 import type { FnLogger } from '../logger.js'
-import { errorMessageOf, type SpanLike } from '../otel.js'
+import { errorMessageOf } from '../otel.js'
 import type {
 	FnContext,
 	FnDefinition,
@@ -100,8 +100,6 @@ export type FnLiveConfig<
 			}
 		) => MaybePromise<boolean>
 		authFn?: AuthFn<TInput, FnContext<TDef, TKey>>
-		/** Log publish failures instead of throwing them into the publishing route. */
-		safePublish?: boolean
 		/** Batch events arriving within this window into one snapshot update. */
 		coalesceMs?: number
 		/** Maximum events collected in one coalescing batch (default 1000). */
@@ -441,7 +439,6 @@ type RuntimeLiveConfig = Omit<ChannelOptions, 'name'> & {
 	reauthorize?: AuthFn<Record<string, unknown>, unknown>
 	transformerFn?: (params: RuntimeParams & Record<string, unknown>) => unknown
 	shouldUpdate?: (params: RuntimeParams & Record<string, unknown>) => unknown
-	safePublish?: boolean
 	coalesceMs?: number
 	maxBatchSize?: number
 	summary?: string
@@ -456,11 +453,9 @@ export function createFnLive(runtime: {
 	// biome-ignore lint/suspicious/noExplicitAny: runtime half of the typed `Fn`
 	fn: (options: any) => AnyProcedure
 	createChannel: (options: ChannelOptions) => Channel
-	createLogger: (scope: string, span: SpanLike | undefined) => FnLogger
 	isGuard: (option: string) => boolean
 }) {
 	const { fn, createChannel, isGuard } = runtime
-	const liveLogger = runtime.createLogger('fn-live', undefined)
 
 	return (
 		options: {
@@ -495,22 +490,8 @@ export function createFnLive(runtime: {
 		// `createChannel` reads only the channel keys of the live config.
 		const channel = createChannel({ ...live, name: liveName })
 
-		const publish = async (event: unknown) => {
-			if (!live.safePublish) return channel.publish(event)
-			try {
-				await channel.publish(event)
-			} catch (err) {
-				// Live update failures must not roll back the route that emitted them,
-				// but they should still be visible in logs.
-				liveLogger.error('fnLive publish failed', {
-					name: liveName,
-					err: errorMessageOf(err)
-				})
-			}
-		}
-
 		const runHandler = (params: RuntimeParams) =>
-			handler({ ...params, publish })
+			handler({ ...params, publish: channel.publish })
 
 		const procedure = fn({
 			...routeConfig,
@@ -640,7 +621,7 @@ export function createFnLive(runtime: {
 		return {
 			procedure,
 			subscribe,
-			publish,
+			publish: channel.publish,
 			getChannelName: channel.getChannelName,
 			getSubscriptionChannelName: channel.getSubscriptionChannelName,
 			getPublishChannelName: channel.getPublishChannelName

package/src/live/index.ts

@@ -8,6 +8,10 @@ export {
 	streamLiveSnapshots,
 	throwInitialSnapshotError
 } from './fn-live.js'
+export {
+	type InvalidationEvent,
+	invalidationStream
+} from './invalidation-stream.js'
 export {
 	type AuthFn,
 	type ChannelDefinition,
@@ -25,9 +29,16 @@ export {
 	type PubSubOptions,
 	type PubSubRuntimeOptions
 } from './pub-sub.js'
+export {
+	type ChangeBusChannel,
+	type ChangeBusScope,
+	defineScopedChangeBus,
+	type ScopedChangeBus
+} from './scoped-change-bus.js'
 export {
 	type BacklogOptions,
 	backlogKey,
 	type PubSubMessage,
-	type PubSubTransport
+	type PubSubTransport,
+	type PubSubTransportStats
 } from './transport.js'

package/src/live/invalidation-stream.ts

@@ -0,0 +1,142 @@
+import {
+	type AnyProcedure,
+	call,
+	type Procedure,
+	type Schema
+} from '@orpc/server'
+
+/** A streaming procedure taking no input, such as a `createPubSub` subscribe route. */
+/* biome-ignore-start lint/suspicious/noExplicitAny: matches any context, input, errors and meta */
+type StreamProcedure<TEvent> = Procedure<
+	any,
+	any,
+	any,
+	Schema<any, AsyncIterable<TEvent>>,
+	any,
+	any
+>
+/* biome-ignore-end lint/suspicious/noExplicitAny: matches any context, input, errors and meta */
+
+/** One event of an invalidation stream: the domain that changed, plus whatever its mapper added. */
+export type InvalidationEvent<
+	TEvents extends Record<string, unknown>,
+	TExtras extends { [K in keyof TEvents]?: object }
+> = {
+	[K in keyof TEvents & string]: { domain: K } & (K extends keyof TExtras
+		? Partial<TExtras[K]>
+		: unknown)
+}[keyof TEvents & string]
+
+/**
+ * Fans several change streams into one stream of `{ domain }` events, so a
+ * client keeps one connection and invalidates queries per domain. Use it as
+ * the body of a streaming `fn`:
+ *
+ * ```ts
+ * fn({
+ *   name: 'realtime.changes',
+ *   stream: true,
+ *   input: z.object({}),
+ *   handler: ({ context, signal }) =>
+ *     invalidationStream({
+ *       context,
+ *       signal,
+ *       sources: { deal: dealChanges.subscribe, workItem: workItemChanges.subscribe },
+ *       // Optional: forward fields a client acts on (alerts), not just the domain.
+ *       events: { deal: (event) => (event.kind === 'won' ? { dealId: event.dealId } : undefined) }
+ *     })
+ * })
+ * ```
+ *
+ * Each source is called with `{}`, the caller's context and a signal of its
+ * own. Events that queue up while the consumer is busy collapse when equal.
+ * When one source ends, the stream ends (a deploy drain); when one throws,
+ * the stream throws. Either way every source is closed and the client
+ * reconnects, which recreates them all.
+ */
+export async function* invalidationStream<
+	TEvents extends Record<string, unknown>,
+	TExtras extends { [K in keyof TEvents]?: object } = Record<never, never>
+>(options: {
+	context: unknown
+	signal?: AbortSignal | undefined
+	sources: { [K in keyof TEvents]: StreamProcedure<TEvents[K]> }
+	events?: {
+		[K in keyof TExtras]: (
+			value: NoInfer<TEvents[K & keyof TEvents]>
+		) => TExtras[K] | undefined
+	}
+}): AsyncGenerator<InvalidationEvent<TEvents, TExtras>, void, unknown> {
+	type Event = InvalidationEvent<TEvents, TExtras>
+	const controller = new AbortController()
+	const abort = () => controller.abort()
+	if (options.signal?.aborted) abort()
+	options.signal?.addEventListener('abort', abort, { once: true })
+
+	// Keyed by the serialized event: equal events collapse while queued.
+	const queue = new Map<string, Event>()
+	let wake: (() => void) | undefined
+	let ended = false
+	let failure: { error: unknown } | undefined
+	const stop = (error?: { error: unknown }) => {
+		if (ended) return
+		ended = true
+		failure = error
+		controller.abort()
+		wake?.()
+	}
+	controller.signal.addEventListener('abort', () => stop(), { once: true })
+
+	const mappers = (options.events ?? {}) as Record<
+		string,
+		((value: unknown) => object | undefined) | undefined
+	>
+	const pump = async (domain: string, procedure: AnyProcedure) => {
+		let iterator: AsyncIterator<unknown> | undefined
+		try {
+			// oRPC's `call`, not the handler's bound call: closing a source needs
+			// a signal of its own, because return() waits behind a pending next().
+			const stream = (await call(
+				procedure,
+				{},
+				{ context: options.context, signal: controller.signal }
+			)) as AsyncIterable<unknown>
+			iterator = stream[Symbol.asyncIterator]()
+			while (!ended) {
+				const result = await iterator.next()
+				if (result.done) return stop()
+				const event = { ...mappers[domain]?.(result.value), domain } as Event
+				queue.set(JSON.stringify(event), event)
+				wake?.()
+			}
+		} catch (error) {
+			stop({ error })
+		} finally {
+			await iterator?.return?.().catch(() => {})
+		}
+	}
+	const pumps = Object.entries(options.sources).map(([domain, procedure]) =>
+		pump(domain, procedure as AnyProcedure)
+	)
+
+	try {
+		while (true) {
+			const [next] = queue
+			if (next) {
+				queue.delete(next[0])
+				yield next[1]
+				continue
+			}
+			if (ended) break
+			await new Promise<void>((resolve) => {
+				wake = resolve
+			})
+			wake = undefined
+		}
+		if (failure) throw failure.error
+	} finally {
+		stop()
+		options.signal?.removeEventListener('abort', abort)
+		await Promise.allSettled(pumps)
+	}
+}

package/src/live/ioredis.ts

@@ -74,6 +74,8 @@ export function ioredisTransport(
 					ours.delete(channel)
 					return subscriber.unsubscribe(channel)
 				},
+				connected: () =>
+					subscriber.status === undefined || subscriber.status === 'ready',
 				close() {
 					// Detach first: a given subscriber outlives this transport's use.
 					subscriber.off('ready', onReady)

package/src/live/memory.ts

@@ -1,4 +1,4 @@
-import type { PubSubTransport } from './transport.js'
+import type { PubSubTransport, PubSubTransportStats } from './transport.js'
 
 /**
  * In-process transport for tests and single-process development. Delivery is
@@ -7,6 +7,7 @@ import type { PubSubTransport } from './transport.js'
 export function memoryTransport(): PubSubTransport & {
 	/** Active listeners per channel, for assertions. */
 	listenerCount(channel: string): number
+	stats(): PubSubTransportStats
 } {
 	const listeners = new Map<string, Set<(payload: string) => void>>()
 	const backlogs = new Map<string, { items: string[]; expiresAt: number }>()
@@ -49,6 +50,14 @@ export function memoryTransport(): PubSubTransport & {
 				if (set.size === 0) listeners.delete(channel)
 			}
 		},
-		listenerCount: (channel) => listeners.get(channel)?.size ?? 0
+		listenerCount: (channel) => listeners.get(channel)?.size ?? 0,
+		stats: () => ({
+			channels: listeners.size,
+			listeners: [...listeners.values()].reduce(
+				(sum, set) => sum + set.size,
+				0
+			),
+			subscriberConnected: true
+		})
 	}
 }

package/src/live/pub-sub.ts

@@ -84,6 +84,11 @@ export type PublisherConfig = {
 	 * channel means no duplicate work.
 	 */
 	mirrorChannel?: string
+	/**
+	 * Log publish failures (validation or broker) instead of throwing them, so
+	 * a publish after a committed write cannot fail the request. No retry.
+	 */
+	safePublish?: boolean
 }
 
 /** Per-definition overrides of the factory queue bounds. */
@@ -612,10 +617,25 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				}
 			})
 
+		const guarded = async (
+			operation: 'publish' | 'publishMany',
+			items: readonly unknown[]
+		) => {
+			if (!config.safePublish) return send(operation, items)
+			try {
+				await send(operation, items)
+			} catch (error) {
+				logger.error('pubsub.publish_failed', {
+					name,
+					...errorAttributes(error)
+				})
+			}
+		}
+
 		return {
-			publish: (data: unknown) => send('publish', [data]),
+			publish: (data: unknown) => guarded('publish', [data]),
 			publishMany: async (items: readonly unknown[]) => {
-				if (items.length > 0) await send('publishMany', items)
+				if (items.length > 0) await guarded('publishMany', items)
 			}
 		}
 	}
@@ -1205,6 +1225,7 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			backlogSize: _backlogSize,
 			backlogTtl: _backlogTtl,
 			mirrorChannel: _mirrorChannel,
+			safePublish: _safePublish,
 			maxQueueSize: _maxQueueSize,
 			maxIngressSize: _maxIngressSize,
 			maxReplaySize: _maxReplaySize,

package/src/live/redis-bun.ts

@@ -9,6 +9,8 @@ export interface BunRedisClientLike {
 	unsubscribe(channel: string, listener?: Listener): Promise<unknown>
 	duplicate(): Promise<BunRedisClientLike>
 	close(): void
+	/** Bun's `RedisClient.connected`; read by `stats()` when present. */
+	readonly connected?: boolean
 	onconnect: ((this: never) => void) | null
 	onclose: ((this: never, error: Error) => void) | null
 }
@@ -58,6 +60,7 @@ export function bunRedisTransport(
 					ours.delete(channel)
 					return subscriber.unsubscribe(channel, dispatch)
 				},
+				connected: () => subscriber.connected !== false,
 				close() {
 					// No-ops, not null: Bun calls `onclose` without checking it.
 					subscriber.onconnect = () => {}

package/src/live/redis.ts

@@ -1,5 +1,9 @@
 import { errorMessageOf } from '../otel.js'
-import { backlogKey, type PubSubTransport } from './transport.js'
+import {
+	backlogKey,
+	type PubSubTransport,
+	type PubSubTransportStats
+} from './transport.js'
 
 export type RedisSend = (command: string, args: string[]) => Promise<unknown>
 
@@ -77,6 +81,8 @@ export type SubscriberConnection = {
 	resubscribe?(channel: string): Promise<unknown>
 	/** Stop delivering and release the connection (if the driver created it). */
 	close(): void | Promise<void>
+	/** The driver reports the connection open; omitted means open until lost. */
+	connected?(): boolean
 }
 
 /** Callbacks for one connection; they do nothing once it is replaced. */
@@ -115,7 +121,10 @@ export function createRedisTransport(driver: {
 	connectSubscriber: (
 		handlers: SubscriberHandlers
 	) => Promise<SubscriberConnection>
-}): PubSubTransport & { close(): Promise<void> } {
+}): PubSubTransport & {
+	close(): Promise<void>
+	stats(): PubSubTransportStats
+} {
 	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.
@@ -124,6 +133,8 @@ export function createRedisTransport(driver: {
 		connection: Promise<SubscriberConnection>
 		retire: () => Promise<void>
 	} | null = null
+	// The open connection of the current generation, once it resolves.
+	let open: SubscriberConnection | null = null
 
 	const connect = () => {
 		let retired = false
@@ -131,7 +142,10 @@ export function createRedisTransport(driver: {
 		const retire = (error?: Error) => {
 			if (retired) return closing ?? Promise.resolve()
 			retired = true
-			if (current?.connection === connection) current = null
+			if (current?.connection === connection) {
+				current = null
+				open = null
+			}
 			closing = connection.then((open) => open.close()).catch(() => {})
 			if (!error) return closing
 			const lost = [...channels.values()].flatMap((state) => [...state.entries])
@@ -182,9 +196,14 @@ export function createRedisTransport(driver: {
 			onLost: (error) => retire(error)
 		}
 		const connection = driver.connectSubscriber(handlers)
-		connection.catch(() => {
-			if (current?.connection === connection) current = null
-		})
+		connection.then(
+			(resolved) => {
+				if (!retired) open = resolved
+			},
+			() => {
+				if (current?.connection === connection) current = null
+			}
+		)
 		current = { connection, retire: () => retire() }
 		return connection
 	}
@@ -268,6 +287,14 @@ export function createRedisTransport(driver: {
 				await done
 			}
 		},
+		stats: () => ({
+			channels: channels.size,
+			listeners: [...channels.values()].reduce(
+				(sum, state) => sum + state.entries.size,
+				0
+			),
+			subscriberConnected: open ? (open.connected?.() ?? true) : false
+		}),
 		async close() {
 			const closing = current?.retire()
 			channels.clear()

package/src/live/scoped-change-bus.ts

@@ -0,0 +1,98 @@
+import type { ZodType, z } from 'zod'
+import type {
+	AnyFnContext,
+	FnDefinition,
+	FnRouteOptions,
+	GuardOptions,
+	ProcedureKey,
+	ProcedureOption
+} from '../types.js'
+import type {
+	CreatePubSub,
+	ObjectSchema,
+	PubSub,
+	PubSubOptions
+} from './pub-sub.js'
+
+/** Where a change bus partitions its channels, e.g. one per organization. */
+export type ChangeBusScope<TContext, TEvent> = {
+	/** The subscriber's scope key, from its context. Throw to refuse the subscription. */
+	subscribe: (context: TContext) => string
+	/** The event's scope key, carried in the event itself. */
+	publish: (event: TEvent) => string
+}
+
+/** A bus's channel definition; pass it to `fnLive` to share the bus's events. */
+export type ChangeBusChannel<TContext, TEvent> = {
+	subscribe: (params: { context: TContext }) => string
+	publish: (event: TEvent) => string
+}
+
+export type ScopedChangeBus<
+	TDef extends FnDefinition,
+	TInputSchema extends ObjectSchema,
+	TEventSchema extends ZodType,
+	TKey extends ProcedureKey<TDef>,
+	TScopeEvent
+> = PubSub<TDef, TInputSchema, TEventSchema, TKey> & {
+	channel: ChangeBusChannel<AnyFnContext<TDef>, TScopeEvent>
+}
+
+/**
+ * Binds the app's `createPubSub` to one scope rule, for buses that tell every
+ * subscriber in a scope "something changed". Each bus then names only its
+ * channel prefix: events go to `${prefix}:${scope}`. Publishing is safe by
+ * default (`safePublish: true`), because buses publish after committed writes.
+ *
+ * ```ts
+ * const defineChangeBus = defineScopedChangeBus(createPubSub, {
+ *   subscribe: (context) => activeOrganizationId(context),
+ *   publish: (event: { organizationId: string }) => event.organizationId
+ * })
+ * export const dealChanges = defineChangeBus({
+ *   name: 'deal.subscribe',
+ *   prefix: 'deal:change',
+ *   inputSchema: z.object({}),
+ *   eventSchema: z.object({ organizationId: z.string(), dealId: z.string() })
+ * })
+ * // fnLive({ live: { channel: dealChanges.channel, ... } }) shares the channel.
+ * ```
+ */
+export function defineScopedChangeBus<TDef extends FnDefinition, TScopeEvent>(
+	createPubSub: CreatePubSub<TDef>,
+	scope: ChangeBusScope<AnyFnContext<TDef>, TScopeEvent>
+) {
+	return <
+		TInputSchema extends ObjectSchema,
+		TEventSchema extends ZodType<TScopeEvent>,
+		TKey extends ProcedureKey<TDef> = TDef['default']
+	>(
+		options: Omit<
+			PubSubOptions<TDef, TInputSchema, TEventSchema, NoInfer<TKey>>,
+			'channel'
+		> &
+			GuardOptions<TDef['guards']> &
+			Pick<
+				FnRouteOptions<TDef, TKey, z.output<TInputSchema>>,
+				'meta' | 'guardResolvers'
+			> &
+			ProcedureOption<TDef, TKey> & {
+				/** Channel prefix; the scope key is appended as `${prefix}:${scope}`. */
+				prefix: string
+			}
+	): ScopedChangeBus<TDef, TInputSchema, TEventSchema, TKey, TScopeEvent> => {
+		const { prefix, ...pubsubOptions } = options
+		const channel: ChangeBusChannel<AnyFnContext<TDef>, TScopeEvent> = {
+			subscribe: ({ context }) => `${prefix}:${scope.subscribe(context)}`,
+			publish: (event) => `${prefix}:${scope.publish(event)}`
+		}
+		// The bus's context is one member of AnyFnContext, which the generic
+		// signature of createPubSub cannot see.
+		const bus = (createPubSub as (options: object) => object)({
+			safePublish: true,
+			...pubsubOptions,
+			channel
+		}) as PubSub<TDef, TInputSchema, TEventSchema, TKey>
+		return { ...bus, channel }
+	}
+}

package/src/live/transport.ts

@@ -1,6 +1,16 @@
 /** One payload for one channel. */
 export type PubSubMessage = { channel: string; payload: string }
 
+/** What a transport holds open on this instance, for gauges and health checks. */
+export type PubSubTransportStats = {
+	/** Broker channels subscribed (one per channel, however many listeners). */
+	channels: number
+	/** Local listeners across those channels. */
+	listeners: number
+	/** The subscriber connection is open; false before the first subscribe. */
+	subscriberConnected: boolean
+}
+
 export type BacklogOptions = {
 	/** Items kept per channel (oldest dropped). */
 	size: number
@@ -39,6 +49,8 @@ export interface PubSubTransport {
 		onLost?: (error: Error) => void,
 		options?: { onReconnect?: () => void }
 	): Promise<() => Promise<void>>
+	/** Current subscription counts and connection state. */
+	stats?(): PubSubTransportStats
 }
 
 export const backlogKey = (channel: string) => `${channel}:backlog`

package/src/procedure-cli.ts

@@ -0,0 +1,99 @@
+import { type AnyProcedure, call, isProcedure, ORPCError } from '@orpc/server'
+import {
+	CliError,
+	type Command,
+	type CommandGroup,
+	defineCommand
+} from 'hanzio/cli'
+import { z } from 'zod'
+import { type FnMeta, readFnMeta } from './meta.js'
+
+export type ProcedureCommandsOptions<C> = {
+	/**
+	 * Which procedures become commands. Default: those declared with
+	 * `meta: { cli: true }` (add `cli?: boolean` to the app's meta type).
+	 */
+	filter?: (meta: FnMeta) => boolean
+	/**
+	 * The oRPC context a command calls its procedure with, from the CLI's
+	 * context (`defineCli({ context })`). Default: that context as-is. It gets
+	 * the procedure's meta, so it can refuse early with a `CliError`, e.g. a
+	 * protected procedure run without a user.
+	 */
+	context?: (cliContext: C, meta: FnMeta) => unknown
+}
+
+const optedIn = (meta: FnMeta) => (meta.meta as { cli?: unknown }).cli === true
+
+const kebab = (key: string) =>
+	key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+
+/**
+ * The opted-in `fn()` procedures of a router as hanzio/cli commands, nested
+ * like the router: `supportLearning.syncRun` is `support-learning sync-run`.
+ * Flags come from the procedure's input schema, help from its summary. A
+ * command calls the procedure through oRPC, so middleware, guards, tracing
+ * and errors run as they do over HTTP.
+ */
+export function procedureCommands<C = unknown>(
+	router: object,
+	options: ProcedureCommandsOptions<C> = {}
+): CommandGroup<C> {
+	const filter = options.filter ?? optedIn
+	const commands: Record<string, Command<C> | CommandGroup<C>> = {}
+
+	for (const [key, value] of Object.entries(router)) {
+		if (isProcedure(value)) {
+			const meta = readFnMeta(value)
+			if (filter(meta)) commands[kebab(key)] = toCommand(value, meta, options)
+		} else if (value && typeof value === 'object') {
+			const group = procedureCommands(value, options)
+			if (Object.keys(group).length > 0) commands[kebab(key)] = group
+		}
+	}
+
+	return commands
+}
+
+function toCommand<C>(
+	procedure: AnyProcedure,
+	meta: FnMeta,
+	options: ProcedureCommandsOptions<C>
+): Command<C> {
+	const name = meta.name ?? 'procedure'
+	if (meta.stream) {
+		throw new TypeError(`orpc-fn: ${name} streams and cannot be a CLI command`)
+	}
+	const input = meta.inputSchema
+	if (input !== undefined && !(input instanceof z.ZodObject)) {
+		throw new TypeError(
+			`orpc-fn: ${name} must take a z.object() input to be a CLI command`
+		)
+	}
+
+	return defineCommand<z.ZodObject, unknown, C>({
+		description: meta.description,
+		input: input ?? z.object({}),
+		run: async (parsed, ctx) => {
+			const context = options.context
+				? await options.context(ctx.context, meta)
+				: ctx.context
+			try {
+				// The flags were validated against this schema; the procedure parses
+				// them again, like any nested call with a parsed value.
+				return await call(procedure, input ? parsed : undefined, {
+					context: context as Record<never, never>
+				})
+			} catch (error) {
+				// A refusal the caller drives (auth, permission, not found) reads as
+				// a message, not a crash with a stack trace.
+				if (error instanceof ORPCError && error.status < 500) {
+					throw new CliError(`${error.code}: ${error.message}`, {
+						cause: error
+					})
+				}
+				throw error
+			}
+		}
+	})
+}