ts-procedures 5.9.0 → 5.10.0

package/src/implementations/http/hono-stream/index.ts

@@ -0,0 +1,456 @@
+import { Hono, Context } from 'hono'
+import { streamSSE, streamText } from 'hono/streaming'
+import { kebabCase } from 'es-toolkit/string'
+import { castArray } from 'es-toolkit/compat'
+import { TStreamProcedureRegistration } from '../../../index.js'
+import { ExtractConfig, ExtractContext, ProceduresFactory, RPCConfig } from '../../types.js'
+import { HonoStreamFactoryItem, StreamHttpRouteDoc, StreamMode } from './types.js'
+import { ProcedureValidationError } from '../../../errors.js'
+
+export type { StreamHttpRouteDoc, StreamMode }
+
+export type SSEOptions = {
+  event?: string
+  id?: string
+  retry?: number
+}
+
+const sseMetadata = new WeakMap<object, SSEOptions>()
+
+export function sse<T extends object>(data: T, options?: SSEOptions): T {
+  sseMetadata.set(data, options ?? {})
+  return data
+}
+
+function getSSEMeta(value: unknown): SSEOptions | undefined {
+  if (typeof value === 'object' && value !== null) {
+    return sseMetadata.get(value)
+  }
+  return undefined
+}
+
+/**
+ * Result from onMidStreamError callback.
+ * @property data - The data to write as the SSE `data:` field content (should match yieldType schema)
+ * @property closeStream - Whether to close the stream after writing (defaults to true)
+ */
+export type MidStreamErrorResult<TErrorData = unknown> = {
+  data: TErrorData
+  closeStream?: boolean
+}
+
+export type HonoStreamAppBuilderConfig<TErrorData = unknown> = {
+  /**
+   * An existing Hono application instance to use.
+   * If not provided, a new instance will be created.
+   */
+  app?: Hono
+  /** Optional path prefix for all stream routes. */
+  pathPrefix?: string
+  /** Default stream mode for all routes. Defaults to 'sse'. */
+  defaultStreamMode?: StreamMode
+  onRequestStart?: (c: Context) => void
+  onRequestEnd?: (c: Context) => void
+  onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
+  onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
+  /**
+   * Called for errors BEFORE streaming starts (validation, auth, context resolution).
+   * Return value IS used as the HTTP response.
+   */
+  onPreStreamError?: (
+    procedure: TStreamProcedureRegistration,
+    c: Context,
+    error: ProcedureValidationError | Error
+  ) => Response | Promise<Response>
+  /**
+   * Called for errors DURING streaming (generator throws).
+   * Return value is written to the stream as a yield.
+   * Should return a value matching your yieldType schema (e.g., error variant of a union).
+   * Return undefined to use default behavior (writes { error: message }).
+   *
+   * Use sse() to attach SSE metadata (event, id, retry) to the error data object.
+   *
+   * @returns { data, closeStream? } - data to yield, whether to close after (default true)
+   */
+  onMidStreamError?: (
+    procedure: TStreamProcedureRegistration,
+    c: Context,
+    error: Error
+  ) => MidStreamErrorResult<TErrorData> | undefined
+}
+
+/**
+ * Builder class for creating a Hono application with streaming RPC routes.
+ *
+ * Usage:
+ *   const StreamRPC = Procedures<StreamContext, RPCConfig>()
+ *
+ *   const streamApp = new HonoStreamAppBuilder()
+ *     .register(StreamRPC, (c): Promise<StreamContext> => { /* context resolution logic * / })
+ *     .build();
+ *
+ *   const app = streamApp.app; // Hono application
+ *   const docs = streamApp.docs; // Stream route documentation
+ */
+export class HonoStreamAppBuilder<TErrorData = unknown> {
+  /**
+   * Constructor for HonoStreamAppBuilder.
+   */
+  constructor(readonly config?: HonoStreamAppBuilderConfig<TErrorData>) {
+    if (config?.app) {
+      this._app = config.app
+    }
+
+    if (config?.onRequestStart) {
+      this._app.use('*', async (c, next) => {
+        config.onRequestStart!(c)
+        await next()
+      })
+    }
+  }
+
+  /**
+   * Generates the stream route path based on the RPC configuration.
+   */
+  static makeStreamHttpRoutePath({
+    name,
+    config,
+    prefix,
+  }: {
+    name: string
+    prefix?: string
+    config: RPCConfig
+  }) {
+    const normalizedPrefix = prefix ? (prefix.startsWith('/') ? prefix : `/${prefix}`) : ''
+
+    return `${normalizedPrefix}/${castArray(config.scope).map(kebabCase).join('/')}/${kebabCase(name)}/${String(config.version).trim()}`
+  }
+
+  /**
+   * Instance method wrapper for makeStreamHttpRoutePath that uses the builder's pathPrefix.
+   */
+  makeStreamHttpRoutePath(name: string, config: RPCConfig): string {
+    return HonoStreamAppBuilder.makeStreamHttpRoutePath({
+      name,
+      config,
+      prefix: this.config?.pathPrefix,
+    })
+  }
+
+  private factories: HonoStreamFactoryItem<any>[] = []
+
+  private _app: Hono = new Hono()
+  private _docs: (StreamHttpRouteDoc & object)[] = []
+
+  get app(): Hono {
+    return this._app
+  }
+
+  get docs(): StreamHttpRouteDoc[] {
+    return this._docs
+  }
+
+  /**
+   * Registers a procedure factory with its context.
+   * Only streaming procedures (created with CreateStream) will be registered.
+   */
+  register<TFactory extends ProceduresFactory>(
+    factory: TFactory,
+    factoryContext:
+      | ExtractContext<TFactory>
+      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
+    options?: {
+      streamMode?: StreamMode
+      extendProcedureDoc?: (params: {
+        base: StreamHttpRouteDoc
+        procedure: TStreamProcedureRegistration<any, ExtractConfig<TFactory>>
+      }) => Record<string, any>
+    }
+  ): this {
+    this.factories.push({
+      factory,
+      factoryContext,
+      streamMode: options?.streamMode,
+      extendProcedureDoc: options?.extendProcedureDoc,
+    } as HonoStreamFactoryItem<any>)
+    return this
+  }
+
+  /**
+   * Creates a route handler for streaming procedures.
+   */
+  private createStreamHandler(
+    procedure: TStreamProcedureRegistration,
+    factoryContext: HonoStreamFactoryItem['factoryContext'],
+    streamMode: StreamMode
+  ) {
+    return async (c: Context) => {
+      try {
+        const context =
+          typeof factoryContext === 'function' ? await factoryContext(c) : factoryContext
+
+        // GET: query params, POST: JSON body
+        const params =
+          c.req.method === 'GET'
+            ? Object.fromEntries(new URL(c.req.url).searchParams)
+            : await c.req.json().catch(() => ({}))
+
+        // Validate params BEFORE starting the stream
+        if (procedure.config.validation?.params) {
+          const { errors } = procedure.config.validation.params(params)
+          if (errors) {
+            const error = new ProcedureValidationError(
+              procedure.name,
+              `Validation error for ${procedure.name}`,
+              errors
+            )
+            // Use onPreStreamError if provided
+            if (this.config?.onPreStreamError) {
+              return this.config.onPreStreamError(procedure, c, error)
+            }
+            return c.json({ error: error.message }, 400)
+          }
+        }
+
+        if (this.config?.onStreamStart) {
+          this.config.onStreamStart(procedure, c, streamMode)
+        }
+
+        if (streamMode === 'sse') {
+          return this.handleSSEStream(procedure, context, params, c)
+        } else {
+          return this.handleTextStream(procedure, context, params, c)
+        }
+      } catch (error) {
+        // Use onPreStreamError for context resolution errors
+        if (this.config?.onPreStreamError) {
+          return this.config.onPreStreamError(procedure, c, error as Error)
+        }
+        return c.json({ error: (error as Error).message }, 500)
+      }
+    }
+  }
+
+  /**
+   * Handles SSE streaming mode.
+   */
+  private handleSSEStream(
+    procedure: TStreamProcedureRegistration,
+    context: any,
+    params: any,
+    c: Context
+  ) {
+    return streamSSE(c, async (stream) => {
+      // Pass isPrevalidated: true since we already validated params in createStreamHandler
+      const generator = procedure.handler({ ...context, signal: c.req.raw.signal, isPrevalidated: true }, params)
+
+      stream.onAbort(async () => {
+        await generator.return(undefined)
+      })
+
+      let eventId = 0
+      try {
+        const iterator = generator[Symbol.asyncIterator]()
+        let iterResult = await iterator.next()
+
+        while (!iterResult.done) {
+          const value = iterResult.value
+          const currentId = eventId++
+          const meta = getSSEMeta(value)
+
+          const data =
+            typeof value === 'string'
+              ? value
+              : value != null
+                ? JSON.stringify(value)
+                : ''
+
+          await stream.writeSSE({
+            data,
+            event: meta?.event ?? procedure.name,
+            id: meta?.id ?? String(currentId),
+            ...(meta?.retry !== undefined && { retry: meta.retry }),
+          })
+
+          iterResult = await iterator.next()
+        }
+
+        // Send return value as a special 'return' event (if present)
+        if (iterResult.value !== undefined) {
+          const returnData =
+            typeof iterResult.value === 'string'
+              ? iterResult.value
+              : JSON.stringify(iterResult.value)
+
+          await stream.writeSSE({
+            data: returnData,
+            event: 'return',
+            id: String(eventId++),
+          })
+        }
+      } catch (error) {
+        // Get error yield value from callback (onMidStreamError)
+        let errorResult: MidStreamErrorResult<TErrorData> | undefined
+
+        if (this.config?.onMidStreamError) {
+          errorResult = this.config.onMidStreamError(procedure, c, error as Error)
+        }
+
+        // Write error value to stream
+        const errorData = errorResult?.data ?? { error: (error as Error).message }
+        const sseMeta = getSSEMeta(errorData)
+
+        await stream.writeSSE({
+          data: typeof errorData === 'string' ? errorData : JSON.stringify(errorData),
+          event: sseMeta?.event ?? (errorResult?.data !== undefined ? procedure.name : 'error'),
+          id: sseMeta?.id ?? String(eventId++),
+          ...(sseMeta?.retry !== undefined && { retry: sseMeta.retry }),
+        })
+
+        // closeStream defaults to true if not specified
+        // (stream closes naturally after this handler completes)
+      } finally {
+        if (this.config?.onStreamEnd) {
+          this.config.onStreamEnd(procedure, c, 'sse')
+        }
+        if (this.config?.onRequestEnd) {
+          this.config.onRequestEnd(c)
+        }
+      }
+    })
+  }
+
+  /**
+   * Handles text streaming mode.
+   */
+  private handleTextStream(
+    procedure: TStreamProcedureRegistration,
+    context: any,
+    params: any,
+    c: Context
+  ) {
+    return streamText(c, async (stream) => {
+      // Pass isPrevalidated: true since we already validated params in createStreamHandler
+      const generator = procedure.handler({ ...context, signal: c.req.raw.signal, isPrevalidated: true }, params)
+
+      stream.onAbort(async () => {
+        await generator.return(undefined)
+      })
+
+      try {
+        for await (const value of generator) {
+          await stream.writeln(JSON.stringify(value))
+        }
+      } catch (error) {
+        // Get error yield value from callback (onMidStreamError)
+        let errorResult: MidStreamErrorResult<TErrorData> | undefined
+
+        if (this.config?.onMidStreamError) {
+          errorResult = this.config.onMidStreamError(procedure, c, error as Error)
+        }
+
+        // Write error value to stream
+        const errorData = errorResult?.data ?? { error: (error as Error).message }
+        await stream.writeln(JSON.stringify(errorData))
+      } finally {
+        if (this.config?.onStreamEnd) {
+          this.config.onStreamEnd(procedure, c, 'text')
+        }
+        if (this.config?.onRequestEnd) {
+          this.config.onRequestEnd(c)
+        }
+      }
+    })
+  }
+
+  /**
+   * Builds and returns the Hono application with registered streaming routes.
+   */
+  build(): Hono {
+    this.factories.forEach(({ factory, factoryContext, streamMode, extendProcedureDoc }) => {
+      const mode = streamMode ?? this.config?.defaultStreamMode ?? 'sse'
+
+      factory
+        .getProcedures()
+        .filter(
+          (p: { isStream?: boolean }): p is TStreamProcedureRegistration => p.isStream === true
+        )
+        .forEach((procedure: TStreamProcedureRegistration<any, RPCConfig>) => {
+          const route = this.buildStreamHttpRouteDoc(procedure, mode, extendProcedureDoc)
+
+          this._docs.push(route)
+
+          const handler = this.createStreamHandler(procedure, factoryContext, mode)
+
+          // Register both GET and POST handlers
+          this._app.get(route.path, handler)
+          this._app.post(route.path, handler)
+        })
+    })
+
+    return this._app
+  }
+
+  /**
+   * Generates the Stream HTTP route documentation for the given procedure.
+   */
+  private buildStreamHttpRouteDoc(
+    procedure: TStreamProcedureRegistration<any, RPCConfig>,
+    streamMode: StreamMode,
+    extendProcedureDoc?: HonoStreamFactoryItem['extendProcedureDoc']
+  ): StreamHttpRouteDoc {
+    const { config } = procedure
+    const path = HonoStreamAppBuilder.makeStreamHttpRoutePath({
+      name: procedure.name,
+      config,
+      prefix: this.config?.pathPrefix,
+    })
+    const methods = ['get', 'post'] as const
+    const jsonSchema: { params?: Record<string, unknown>; yieldType?: Record<string, unknown>; returnType?: Record<string, unknown> } = {}
+
+    if (config.schema?.params) {
+      jsonSchema.params = config.schema.params
+    }
+    if (streamMode === 'sse') {
+      jsonSchema.yieldType = {
+        type: 'object',
+        description: 'SSE message envelope. The data field contains the procedure yield value.',
+        required: ['data', 'event', 'id'],
+        properties: {
+          data: config.schema?.yieldType ?? {},
+          event: { type: 'string' },
+          id: { type: 'string' },
+          retry: { type: 'number' },
+        },
+      }
+    } else if (config.schema?.yieldType) {
+      // Text mode: pass through as-is
+      jsonSchema.yieldType = config.schema.yieldType
+    }
+    if (config.schema?.returnType) {
+      jsonSchema.returnType = config.schema.returnType
+    }
+
+    const base: StreamHttpRouteDoc = {
+      kind: 'stream',
+      name: procedure.name,
+      version: config.version,
+      scope: config.scope,
+      path,
+      methods: [...methods],
+      streamMode,
+      jsonSchema,
+    }
+
+    let extendedDoc: object = {}
+
+    if (extendProcedureDoc) {
+      extendedDoc = extendProcedureDoc({ base, procedure })
+    }
+
+    return {
+      ...extendedDoc,
+      ...base,
+    }
+  }
+}

package/src/implementations/http/hono-stream/types.ts

@@ -0,0 +1,20 @@
+import { Context } from 'hono'
+import { TStreamProcedureRegistration } from '../../../index.js'
+import { ExtractConfig, ExtractContext } from '../../types.js'
+
+export type { StreamHttpRouteDoc } from '../../types.js'
+export type { StreamMode } from '../../types.js'
+
+import type { StreamHttpRouteDoc, StreamMode } from '../../types.js'
+
+export type HonoStreamFactoryItem<TFactory = any> = {
+  factory: TFactory
+  factoryContext:
+    | ExtractContext<TFactory>
+    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+  streamMode?: StreamMode
+  extendProcedureDoc?: (params: {
+    base: StreamHttpRouteDoc
+    procedure: TStreamProcedureRegistration<any, ExtractConfig<TFactory>>
+  }) => Record<string, any>
+}

package/src/implementations/types.ts

@@ -0,0 +1,174 @@
+import { Procedures } from '../index.js'
+
+export interface RPCConfig {
+  // Scope or scopes (scope segments) required to access the RPC
+  scope: string | string[]
+  version: number
+}
+
+export type FactoryItem<C> = {
+  factory: ReturnType<typeof Procedures<C, RPCConfig>>
+  factoryContext: (req: Request) => C
+}
+
+export interface RPCHttpRouteDoc extends RPCConfig {
+  kind: 'rpc'
+  name: string // procedure name
+  path: string
+  method: 'post'
+  jsonSchema: {
+    body?: Record<string, unknown>
+    response?: Record<string, unknown>
+  }
+}
+
+export type StreamMode = 'sse' | 'text'
+
+// ================
+// API (REST-style) types
+// ================
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+
+export interface APIConfig {
+  /** HTTP route path (supports Hono path params, e.g., '/users/:id') */
+  path: string
+  /** HTTP method for this endpoint */
+  method: HttpMethod
+  /** HTTP status code on success. Defaults: POST→201, DELETE→204, others→200 */
+  successStatus?: number
+  /** Optional scope for grouping API routes in generated client files */
+  scope?: string
+}
+
+export interface APIHttpRouteDoc extends APIConfig {
+  kind: 'api'
+  name: string
+  /** Full resolved path including pathPrefix */
+  fullPath: string
+  jsonSchema: {
+    pathParams?: Record<string, unknown>
+    query?: Record<string, unknown>
+    body?: Record<string, unknown>
+    headers?: Record<string, unknown>
+    response?: Record<string, unknown>
+  }
+}
+
+/**
+ * Constrains schema.input channel names to valid HTTP input sources.
+ * Use with `satisfies` or as a type annotation to catch typos at compile time:
+ *
+ * @example
+ * schema: {
+ *   input: {
+ *     pathParams: Type.Object({ id: Type.String() }),
+ *     qurey: Type.Object({ ... }), // TS error: 'qurey' not in APIInput
+ *   } satisfies APIInput
+ * }
+ */
+export type APIInput<T extends {
+  pathParams?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+} = {
+  pathParams?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+}> = T
+
+export interface StreamHttpRouteDoc extends RPCConfig {
+  kind: 'stream'
+  name: string // procedure name
+  path: string
+  methods: ('get' | 'post')[]
+  streamMode: StreamMode
+  jsonSchema: {
+    params?: Record<string, unknown>    // Query params (GET) or body (POST)
+    yieldType?: Record<string, unknown> // Schema for each streamed value
+    returnType?: Record<string, unknown> // Final return (optional)
+  }
+}
+
+// ================
+// Utility types
+// ================
+
+/**
+ * Extracts the TContext type from a Procedures factory return type.
+ * Uses the first parameter of the handler function to infer the context type.
+ */
+export type ExtractContext<TFactory> = TFactory extends {
+  getProcedures: () => Array<{ handler: (ctx: infer TContext, ...args: any[]) => any }>
+}
+  ? TContext
+  : never
+
+/**
+ * Extracts the TConfig type from a Procedures factory return type.
+ * Uses the config property of the procedure registration to infer the config type.
+ */
+export type ExtractConfig<TFactory> = TFactory extends {
+  getProcedures: () => Array<{ config: infer TConfig }>
+}
+  ? TConfig
+  : never
+
+/**
+ * Minimal structural type for a Procedures factory.
+ * Uses explicit `any` types to avoid variance issues with generic constraints.
+ */
+export type ProceduresFactory = {
+  getProcedures: () => Array<{
+    name: string
+    isStream?: boolean
+    config: any
+    handler: (ctx: any, params?: any) => Promise<any> | AsyncGenerator<any, any, unknown>
+  }>
+  Create: (...args: any[]) => any
+  CreateStream?: (...args: any[]) => any
+}
+
+// ================
+// DocRegistry types
+// ================
+
+export type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc
+
+export interface DocSource<T = AnyHttpRouteDoc> {
+  readonly docs: T[]
+}
+
+export interface HeaderDoc {
+  name: string
+  description?: string
+  required?: boolean
+  example?: string
+}
+
+export interface ErrorDoc {
+  name: string
+  statusCode: number
+  description: string
+  schema?: Record<string, unknown>
+}
+
+export interface DocRegistryConfig {
+  basePath?: string
+  headers?: HeaderDoc[]
+  errors?: ErrorDoc[]
+}
+
+export interface DocRegistryOutputOptions<TEnvelope = DocEnvelope> {
+  filter?: (route: AnyHttpRouteDoc) => boolean
+  transform?: (envelope: DocEnvelope) => TEnvelope
+}
+
+export interface DocEnvelope {
+  basePath: string
+  headers: HeaderDoc[]
+  errors: ErrorDoc[]
+  routes: AnyHttpRouteDoc[]
+}