orpc-fn 0.1.0 → 0.3.0

package/src/live/fn-live.ts

@@ -1,6 +1,8 @@
-import type { Schema } from '@orpc/contract'
+import type { AnySchema, ErrorMap, Schema } from '@orpc/contract'
 import { type AnyProcedure, ORPCError } from '@orpc/server'
 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 type {
@@ -17,6 +19,7 @@ import type {
 	Channel,
 	ChannelDefinition,
 	ChannelOptions,
+	ChannelQueueOptions,
 	ObjectSchema,
 	PublisherConfig
 } from './pub-sub.js'
@@ -57,45 +60,92 @@ export type FnLiveConfig<
 	TEventSchema extends ZodType,
 	TOutput,
 	TKey extends ProcedureKey<TDef>,
-	TEmit = never
-> = Omit<PublisherConfig, 'name'> & {
-	/** Subscribe route name; default `${name}.live`. */
-	name?: string
-	eventSchema: TEventSchema
-	channel: ChannelDefinition<
-		TInput,
-		z.output<TEventSchema>,
-		FnContext<TDef, TKey>
-	>
-	/** Fold an event into the snapshot; without it every event re-runs the handler. */
-	transformerFn?: (
-		params: HandlerParams<TDef, TInput, TKey> & {
-			event: z.output<TEventSchema>
-			previous: TOutput | undefined
-			rerun: (input?: TInput) => Promise<TOutput>
-		}
-	) => MaybePromise<TOutput | FnLivePatch<TOutput, TEmit> | undefined>
-	/** Return false to skip an event. */
-	shouldUpdate?: (
-		params: HandlerParams<TDef, TInput, TKey> & {
-			event: z.output<TEventSchema>
-			previous: TOutput | undefined
-		}
-	) => 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
-	/**
-	 * When a slow subscriber's queue overflows (drop-oldest), this marker is
-	 * enqueued INSTEAD of the dropped event so the client resyncs. Return
-	 * `null` to skip.
-	 */
-	overflowMarker?: (input: TInput) => z.output<TEventSchema> | null
-	summary?: string
-	description?: string
-}
+	TEmit = never,
+	TErrors extends ErrorMap = Record<never, never>
+> = Omit<PublisherConfig, 'name'> &
+	ChannelQueueOptions & {
+		/** Subscribe route name; default `${name}.live`. */
+		name?: string
+		/**
+		 * 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<unknown, TEmit>
+		/** Optional access check before each update; idle streams keep their initial authorization. */
+		reauthorize?: AuthFn<TInput, FnContext<TDef, TKey>>
+		eventSchema: TEventSchema
+		channel: ChannelDefinition<
+			TInput,
+			z.output<TEventSchema>,
+			FnContext<TDef, TKey>
+		>
+		/** Fold an event into the snapshot; without it every event re-runs the handler. */
+		transformerFn?: FnLiveConfigTransformer<
+			TDef,
+			TInput,
+			TEventSchema,
+			TOutput,
+			TKey,
+			TEmit,
+			TErrors
+		>
+		/** Return false to skip an event. */
+		shouldUpdate?: (
+			params: HandlerParams<TDef, TInput, TKey, TErrors> & {
+				event: z.output<TEventSchema>
+				previous: TOutput
+			}
+		) => 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). */
+		maxBatchSize?: number
+		/**
+		 * When a slow subscriber's queue overflows (drop-oldest), this marker is
+		 * enqueued INSTEAD of the dropped event so the client resyncs. Return
+		 * `null` to skip.
+		 */
+		overflowMarker?: (input: TInput) => z.output<TEventSchema> | null
+		summary?: string
+		description?: string
+	} & (
+		| { transformerFn?: undefined }
+		| {
+				transformerFn: FnLiveConfigTransformer<
+					TDef,
+					TInput,
+					TEventSchema,
+					TOutput,
+					TKey,
+					TEmit,
+					TErrors
+				>
+				stateSchema: Schema<unknown, TOutput>
+		  }
+	) &
+	([TEmit] extends [never] ? object : { emitSchema: Schema<unknown, TEmit> })
+
+type FnLiveConfigTransformer<
+	TDef extends FnDefinition,
+	TInput,
+	TEventSchema extends ZodType,
+	TOutput,
+	TKey extends ProcedureKey<TDef>,
+	TEmit,
+	TErrors extends ErrorMap
+> = (
+	params: HandlerParams<TDef, TInput, TKey, TErrors> & {
+		event: z.output<TEventSchema>
+		previous: TOutput
+		rerun: () => Promise<TOutput>
+	}
+) => MaybePromise<TOutput | FnLivePatch<TOutput, TEmit> | undefined>
 
 export type FnLiveReturn<
 	TDef extends FnDefinition,
@@ -104,16 +154,24 @@ export type FnLiveReturn<
 	TOutputSchema extends Schema<unknown, unknown>,
 	TOutput,
 	TEventSchema extends ZodType,
-	TEmit = never
+	TEmit = never,
+	TErrors extends ErrorMap = Record<never, never>
 > = {
-	procedure: FnProcedure<TDef, TKey, TInput, TOutputSchema>
+	procedure: FnProcedure<TDef, TKey, TInput, TOutputSchema, TErrors>
 	subscribe: FnProcedure<
 		TDef,
 		TKey,
 		TInput,
-		Schema<AsyncGenerator<TOutput | TEmit>, AsyncGenerator<TOutput | TEmit>>
+		Schema<AsyncGenerator<TOutput | TEmit>, AsyncGenerator<TOutput | TEmit>>,
+		TErrors
 	>
 	publish: (event: z.input<TEventSchema>) => Promise<void>
+	getSubscriptionChannelName: (params: {
+		input: z.output<TInput>
+		context: FnContext<TDef, TKey>
+	}) => string
+	getPublishChannelName: (event: z.output<TEventSchema>) => string
+	/** @deprecated Prefer the separate required-input resolver methods. */
 	getChannelName: (
 		params: Partial<z.output<TInput>> | Partial<z.output<TEventSchema>>,
 		context?: FnContext<TDef, TKey>
@@ -130,13 +188,19 @@ export interface FnLive<TDef extends FnDefinition> {
 		TOutputSchema extends ZodType,
 		TEventSchema extends ZodType,
 		TKey extends ProcedureKey<TDef> = TDef['default'],
-		TEmit = never
+		TEmit = never,
+		TErrors extends ErrorMap = Record<never, never>
 	>(
 		options: {
 			input: TInput
 			output: TOutputSchema
 			handler: (
-				params: HandlerParams<TDef, z.output<TInput>, NoInfer<TKey>> & {
+				params: HandlerParams<
+					TDef,
+					z.output<TInput>,
+					NoInfer<TKey>,
+					TErrors
+				> & {
 					publish: (event: z.input<TEventSchema>) => Promise<void>
 				}
 				// The output schema parses what the handler returns: its input type.
@@ -147,9 +211,10 @@ export interface FnLive<TDef extends FnDefinition> {
 				TEventSchema,
 				z.output<TOutputSchema>,
 				NoInfer<TKey>,
-				TEmit
+				TEmit,
+				TErrors
 			>
-		} & FnRouteOptions<TDef, TKey>
+		} & FnRouteOptions<TDef, TKey, z.output<TInput>, TErrors>
 	): FnLiveReturn<
 		TDef,
 		TKey,
@@ -157,7 +222,8 @@ export interface FnLive<TDef extends FnDefinition> {
 		TOutputSchema,
 		z.output<TOutputSchema>,
 		TEventSchema,
-		TEmit
+		TEmit,
+		TErrors
 	>
 
 	<
@@ -165,13 +231,19 @@ export interface FnLive<TDef extends FnDefinition> {
 		TOutput,
 		TEventSchema extends ZodType,
 		TKey extends ProcedureKey<TDef> = TDef['default'],
-		TEmit = never
+		TEmit = never,
+		TErrors extends ErrorMap = Record<never, never>
 	>(
 		options: {
 			input: TInput
 			output?: undefined
 			handler: (
-				params: HandlerParams<TDef, z.output<TInput>, NoInfer<TKey>> & {
+				params: HandlerParams<
+					TDef,
+					z.output<TInput>,
+					NoInfer<TKey>,
+					TErrors
+				> & {
 					publish: (event: z.input<TEventSchema>) => Promise<void>
 				}
 			) => MaybePromise<TOutput>
@@ -181,9 +253,10 @@ export interface FnLive<TDef extends FnDefinition> {
 				TEventSchema,
 				TOutput,
 				NoInfer<TKey>,
-				TEmit
+				TEmit,
+				TErrors
 			>
-		} & FnRouteOptions<TDef, TKey>
+		} & FnRouteOptions<TDef, TKey, z.output<TInput>, TErrors>
 	): FnLiveReturn<
 		TDef,
 		TKey,
@@ -191,7 +264,8 @@ export interface FnLive<TDef extends FnDefinition> {
 		Schema<TOutput, TOutput>,
 		TOutput,
 		TEventSchema,
-		TEmit
+		TEmit,
+		TErrors
 	>
 }
 
@@ -253,6 +327,12 @@ export async function* streamLiveSnapshots<
 	TEmit = never
 >(opts: {
 	source: AsyncIterator<TEvent>
+	/** Maximum events retained in one coalescing batch. */
+	maxBatchSize?: number
+	applyBatch?: (
+		events: readonly TEvent[],
+		previous: TOutput
+	) => MaybePromise<TOutput | undefined>
 	initial: TOutput
 	coalesceMs?: number | undefined
 	apply: (
@@ -261,6 +341,15 @@ export async function* streamLiveSnapshots<
 	) => MaybePromise<TOutput | FnLivePatch<TOutput, TEmit> | undefined>
 }): AsyncGenerator<TOutput | TEmit> {
 	const { source, initial, coalesceMs, apply } = opts
+	const maxBatchSize = positiveInteger(
+		opts.maxBatchSize ?? 1000,
+		'maxBatchSize'
+	)
+	if (
+		coalesceMs !== undefined &&
+		(!Number.isFinite(coalesceMs) || coalesceMs < 0)
+	)
+		throw new RangeError('orpc-fn: coalesceMs must be finite and nonnegative')
 
 	let pending: Promise<IteratorResult<TEvent>> | null = null
 	const readNext = () => {
@@ -280,7 +369,7 @@ export async function* streamLiveSnapshots<
 
 		if (coalesceMs) {
 			const endAt = Date.now() + coalesceMs
-			while (Date.now() < endAt) {
+			while (Date.now() < endAt && batch.length < maxBatchSize) {
 				const remainingMs = endAt - Date.now()
 				const read = readNext()
 				let timer: ReturnType<typeof setTimeout> | undefined
@@ -307,17 +396,31 @@ export async function* streamLiveSnapshots<
 			}
 		}
 
+		if (opts.applyBatch) {
+			const next = await opts.applyBatch(batch, previous)
+			if (next !== undefined) {
+				previous = next
+				yield previous
+			}
+			continue
+		}
+		let changed = false
 		for (const event of batch) {
 			const next = await apply(event, previous)
 			if (next === undefined) continue
 			if (isFnLivePatch(next)) {
+				if (changed) {
+					yield previous
+					changed = false
+				}
 				previous = next.state as TOutput
 				yield next.emit as TEmit
 				continue
 			}
 			previous = next
-			yield previous
+			changed = true
 		}
+		if (changed) yield previous
 	}
 }
 
@@ -326,15 +429,21 @@ type RuntimeParams = Record<string, unknown> & {
 	context: unknown
 	signal: AbortSignal | undefined
 	logger: FnLogger
+	call: (procedure: AnyProcedure, input: unknown) => Promise<unknown>
+	[RAW_INPUT]: unknown
 }
 
 /** `FnLiveConfig` with the generics erased: what the implementation reads. */
 type RuntimeLiveConfig = Omit<ChannelOptions, 'name'> & {
 	name?: string
+	stateSchema?: AnySchema
+	emitSchema?: AnySchema
+	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
 	description?: string
 }
@@ -367,6 +476,17 @@ export function createFnLive(runtime: {
 		} & Record<string, unknown>
 	) => {
 		const { live, handler, input, output, name, ...routeConfig } = options
+		if (live.transformerFn && !live.stateSchema)
+			throw new TypeError(
+				'orpc-fn: live transformers require a stateSchema for parsed state'
+			)
+		if (
+			live.coalesceMs !== undefined &&
+			(!Number.isFinite(live.coalesceMs) || live.coalesceMs < 0)
+		)
+			throw new RangeError('orpc-fn: coalesceMs must be finite and nonnegative')
+		if (live.maxBatchSize !== undefined)
+			positiveInteger(live.maxBatchSize, 'maxBatchSize')
 		const liveName = live.name ?? `${name}.live`
 		const liveSummary =
 			live.summary ?? `Live updates of ${routeConfig.summary ?? name}`
@@ -391,11 +511,6 @@ export function createFnLive(runtime: {
 
 		const runHandler = (params: RuntimeParams) =>
 			handler({ ...params, publish })
-		// Snapshots go through the output schema like the route's own result.
-		const runSnapshot = async (params: RuntimeParams) => {
-			const result = await runHandler(params)
-			return output ? output.parseAsync(result) : result
-		}
 
 		const procedure = fn({
 			...routeConfig,
@@ -405,12 +520,28 @@ export function createFnLive(runtime: {
 			handler: runHandler
 		})
 
-		// Guards run on the subscribe route too; route meta stays on `procedure`.
+		const validate = async (schema: AnySchema, value: unknown) => {
+			const result = await schema['~standard'].validate(value)
+			if (result.issues)
+				throw new ORPCError('INTERNAL_SERVER_ERROR', {
+					message: 'Invalid live state or patch',
+					cause: result.issues
+				})
+			return result.value
+		}
+		const runSnapshot = (params: RuntimeParams) =>
+			params.call(procedure, params[RAW_INPUT])
+		// Generated streams inherit access policies and metadata; tool adapters reject streams.
+
 		const guardOptions = Object.fromEntries(
 			Object.entries(routeConfig).filter(([option]) => isGuard(option))
 		)
 		const subscribe = fn({
 			...guardOptions,
+			guardResolvers: routeConfig.guardResolvers,
+			errors: routeConfig.errors,
+			meta: routeConfig.meta,
+			stream: true,
 			procedure: routeConfig.procedure,
 			tags: routeConfig.tags,
 			name: liveName,
@@ -424,9 +555,11 @@ export function createFnLive(runtime: {
 				const subscription = await channel.open({
 					input: params.input,
 					context: params.context,
-					signal: params.signal
+					signal: params.signal,
+					recoverGaps: true
 				})
 				try {
+					if (subscription.isClosed()) return
 					let initial: unknown
 					try {
 						initial = await runSnapshot(params)
@@ -435,24 +568,68 @@ export function createFnLive(runtime: {
 						throw toSnapshotError(err, liveName)
 					}
 
-					const rerun = (nextInput?: Record<string, unknown>) =>
-						runSnapshot({ ...params, input: nextInput ?? params.input })
+					const rerun = () => runSnapshot(params)
+					const authorize = async () => {
+						if (
+							live.reauthorize &&
+							live.reauthorize !== true &&
+							!(await live.reauthorize({
+								input: params.input,
+								ctx: params.context
+							}))
+						)
+							throw new ORPCError('FORBIDDEN')
+					}
 					const apply = async (event: unknown, previous: unknown) => {
+						await authorize()
+						if (event === LIVE_GAP) return rerun()
 						if (
 							live.shouldUpdate &&
 							!(await live.shouldUpdate({ ...params, event, previous }))
-						) {
+						)
 							return undefined
+						if (!live.transformerFn) return rerun()
+						const next = await live.transformerFn({
+							...params,
+							event,
+							previous,
+							rerun
+						})
+						if (next === undefined) return undefined
+						if (isFnLivePatch(next)) {
+							if (!live.emitSchema)
+								throw new TypeError('orpc-fn: live patches require emitSchema')
+							return fnLivePatch(
+								await validate(live.stateSchema as AnySchema, next.state),
+								await validate(live.emitSchema, next.emit)
+							)
 						}
-						if (!live.transformerFn) return runSnapshot(params)
-						return live.transformerFn({ ...params, event, previous, rerun })
+						return validate(live.stateSchema as AnySchema, next)
 					}
+					const applyBatch = live.transformerFn
+						? undefined
+						: async (events: readonly unknown[], previous: unknown) => {
+								await authorize()
+								let invalidated = false
+								for (const event of events)
+									if (
+										event === LIVE_GAP ||
+										!live.shouldUpdate ||
+										(await live.shouldUpdate({ ...params, event, previous }))
+									)
+										invalidated = true
+								return invalidated ? rerun() : undefined
+							}
 
 					yield* streamLiveSnapshots({
 						source: subscription.events,
 						initial,
 						coalesceMs: live.coalesceMs,
-						apply
+						...(live.maxBatchSize !== undefined
+							? { maxBatchSize: live.maxBatchSize }
+							: {}),
+						apply,
+						...(applyBatch ? { applyBatch } : {})
 					})
 				} finally {
 					subscription.close()
@@ -464,7 +641,9 @@ export function createFnLive(runtime: {
 			procedure,
 			subscribe,
 			publish,
-			getChannelName: channel.getChannelName
+			getChannelName: channel.getChannelName,
+			getSubscriptionChannelName: channel.getSubscriptionChannelName,
+			getPublishChannelName: channel.getPublishChannelName
 		}
 	}
 }

package/src/live/index.ts

@@ -11,6 +11,8 @@ export {
 export {
 	type AuthFn,
 	type ChannelDefinition,
+	type ChannelQueueOptions,
+	type PubSubMetric,
 	type CreatePublisher,
 	type CreatePubSub,
 	createBoundedEventQueue,

package/src/live/ioredis.ts

@@ -6,17 +6,20 @@ export interface IORedisLike {
 	subscribe(...channels: string[]): Promise<unknown>
 	unsubscribe(...channels: string[]): Promise<unknown>
 	duplicate(): IORedisLike
+	status?: string
 	disconnect(): void
 	on(
 		event: 'message',
 		listener: (channel: string, message: string) => void
 	): unknown
+	on(event: 'ready', listener: () => void): unknown
 	on(event: 'end', listener: () => void): unknown
 	on(event: 'error', listener: (error: Error) => void): unknown
 	off(
 		event: 'message',
 		listener: (channel: string, message: string) => void
 	): unknown
+	off(event: 'ready', listener: () => void): unknown
 	off(event: 'end', listener: () => void): unknown
 	off(event: 'error', listener: (error: Error) => void): unknown
 }
@@ -41,11 +44,23 @@ export function ioredisTransport(
 			const onMessage = (channel: string, message: string) =>
 				handlers.onMessage(channel, message)
 			// Without a listener an ioredis 'error' event would crash the process.
-			const onError = (error: Error) => options.onError?.(error)
+			const onError = (error: Error) => {
+				try {
+					options.onError?.(error)
+				} catch {
+					/* Isolate telemetry. */
+				}
+			}
+			let readyOnce = subscriber.status === 'ready'
+			const onReady = () => {
+				if (readyOnce) handlers.onReconnect()
+				readyOnce = true
+			}
 			// 'end' means ioredis stopped reconnecting.
 			const onEnd = () =>
 				handlers.onLost(new Error('Redis subscriber connection ended'))
 			const ours = new Set<string>()
+			subscriber.on('ready', onReady)
 			subscriber.on('message', onMessage)
 			subscriber.on('error', onError)
 			subscriber.on('end', onEnd)
@@ -54,18 +69,23 @@ export function ioredisTransport(
 					ours.add(channel)
 					return subscriber.subscribe(channel)
 				},
+				resubscribe: (channel: string) => subscriber.subscribe(channel),
 				unsubscribe: (channel) => {
 					ours.delete(channel)
 					return subscriber.unsubscribe(channel)
 				},
 				close() {
 					// Detach first: a given subscriber outlives this transport's use.
+					subscriber.off('ready', onReady)
 					subscriber.off('message', onMessage)
 					subscriber.off('end', onEnd)
 					if (owned) return subscriber.disconnect()
 					subscriber.off('error', onError)
 					if (ours.size > 0) {
-						void subscriber.unsubscribe(...ours).catch(() => {})
+						return subscriber
+							.unsubscribe(...ours)
+							.then(() => {})
+							.catch(() => {})
 					}
 				}
 			}

package/src/live/lifecycle.ts

@@ -0,0 +1,44 @@
+/** Internal control message: live queries reload after loss; raw streams fail. */
+export const LIVE_GAP = Symbol('orpc-fn.liveGap')
+
+export function positiveInteger(value: number, name: string): number {
+	if (!Number.isSafeInteger(value) || value <= 0)
+		throw new RangeError(`orpc-fn: ${name} must be a positive safe integer`)
+	return value
+}
+
+export function safely(callback: (() => unknown) | undefined): void {
+	try {
+		callback?.()
+	} catch {
+		/* Observability must not disrupt delivery. */
+	}
+}
+
+/** Abort and timeout only stop waiting; callers release late transport results. */
+export async function waitFor<T>(
+	promise: Promise<T>,
+	timeoutMs: number,
+	signal: AbortSignal
+): Promise<T> {
+	signal.throwIfAborted()
+	let timer: ReturnType<typeof setTimeout> | undefined
+	let abort = () => {}
+	try {
+		return await Promise.race([
+			promise,
+			new Promise<never>((_resolve, reject) => {
+				abort = () => reject(signal.reason)
+				signal.addEventListener('abort', abort, { once: true })
+				timer = setTimeout(
+					() =>
+						reject(new Error('orpc-fn: subscription initialization timed out')),
+					timeoutMs
+				)
+			})
+		])
+	} finally {
+		clearTimeout(timer)
+		signal.removeEventListener('abort', abort)
+	}
+}

package/src/live/memory.ts

@@ -12,6 +12,10 @@ export function memoryTransport(): PubSubTransport & {
 	const backlogs = new Map<string, { items: string[]; expiresAt: number }>()
 
 	return {
+		async close() {
+			listeners.clear()
+			backlogs.clear()
+		},
 		async publish(messages, backlog) {
 			for (const { channel, payload } of messages) {
 				if (backlog) {