ts-procedures 3.1.0 → 3.3.0

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

@@ -0,0 +1,327 @@
+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'
+
+export type { StreamHttpRouteDoc, StreamMode }
+
+export type HonoStreamAppBuilderConfig = {
+  /**
+   * 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) => void
+  onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context) => void
+  /**
+   * Error handler called when a streaming procedure throws an error.
+   */
+  onStreamError?: (
+    procedure: TStreamProcedureRegistration,
+    c: Context,
+    error: Error
+  ) => Response | Promise<Response>
+}
+
+/**
+ * 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 {
+  /**
+   * Constructor for HonoStreamAppBuilder.
+   */
+  constructor(readonly config?: HonoStreamAppBuilderConfig) {
+    if (config?.app) {
+      this._app = config.app
+    }
+
+    if (config?.onRequestStart) {
+      this._app.use('*', async (c, next) => {
+        config.onRequestStart!(c)
+        await next()
+      })
+    }
+
+    if (config?.onRequestEnd) {
+      this._app.use('*', async (c, next) => {
+        await next()
+        config.onRequestEnd!(c)
+      })
+    }
+  }
+
+  /**
+   * 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(() => ({}))
+
+        if (this.config?.onStreamStart) {
+          this.config.onStreamStart(procedure, c)
+        }
+
+        if (streamMode === 'sse') {
+          return this.handleSSEStream(procedure, context, params, c)
+        } else {
+          return this.handleTextStream(procedure, context, params, c)
+        }
+      } catch (error) {
+        if (this.config?.onStreamError) {
+          return this.config.onStreamError(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) => {
+      const generator = procedure.handler(context, params)
+
+      stream.onAbort(async () => {
+        await generator.return(undefined)
+      })
+
+      try {
+        let eventId = 0
+        for await (const value of generator) {
+          await stream.writeSSE({
+            data: JSON.stringify(value),
+            event: procedure.name,
+            id: String(eventId++),
+          })
+        }
+      } catch (error) {
+        // Write error as SSE event before closing
+        await stream.writeSSE({
+          data: JSON.stringify({ error: (error as Error).message }),
+          event: 'error',
+        })
+      } finally {
+        if (this.config?.onStreamEnd) {
+          this.config.onStreamEnd(procedure, c)
+        }
+      }
+    })
+  }
+
+  /**
+   * Handles text streaming mode.
+   */
+  private handleTextStream(
+    procedure: TStreamProcedureRegistration,
+    context: any,
+    params: any,
+    c: Context
+  ) {
+    return streamText(c, async (stream) => {
+      const generator = procedure.handler(context, params)
+
+      stream.onAbort(async () => {
+        await generator.return(undefined)
+      })
+
+      try {
+        for await (const value of generator) {
+          await stream.writeln(JSON.stringify(value))
+        }
+      } catch (error) {
+        // Write error as JSON line before closing
+        await stream.writeln(JSON.stringify({ error: (error as Error).message }))
+      } finally {
+        if (this.config?.onStreamEnd) {
+          this.config.onStreamEnd(procedure, 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?: object; yieldType?: object; returnType?: object } = {}
+
+    if (config.schema?.params) {
+      jsonSchema.params = config.schema.params
+    }
+    if (config.schema?.yieldType) {
+      jsonSchema.yieldType = config.schema.yieldType
+    }
+    if (config.schema?.returnType) {
+      jsonSchema.returnType = config.schema.returnType
+    }
+
+    const base: StreamHttpRouteDoc = {
+      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,29 @@
+import { Context } from 'hono'
+import { TStreamProcedureRegistration } from '../../../index.js'
+import { ExtractConfig, ExtractContext, RPCConfig } from '../../types.js'
+
+export type StreamMode = 'sse' | 'text'
+
+export interface StreamHttpRouteDoc extends RPCConfig {
+  name: string
+  path: string
+  methods: ('get' | 'post')[]
+  streamMode: StreamMode
+  jsonSchema: {
+    params?: object
+    yieldType?: object
+    returnType?: object
+  }
+}
+
+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

@@ -21,6 +21,20 @@ export interface RPCHttpRouteDoc extends RPCConfig {
   }
 }
 
+export type StreamMode = 'sse' | 'text'
+
+export interface StreamHttpRouteDoc extends RPCConfig {
+  name: string // procedure name
+  path: string
+  methods: ('get' | 'post')[]
+  streamMode: StreamMode
+  jsonSchema: {
+    params?: object    // Query params (GET) or body (POST)
+    yieldType?: object // Schema for each streamed value
+    returnType?: object // Final return (optional)
+  }
+}
+
 // ================
 // Utility types
 // ================
@@ -52,8 +66,10 @@ export type ExtractConfig<TFactory> = TFactory extends {
 export type ProceduresFactory = {
   getProcedures: () => Array<{
     name: string
+    isStream?: boolean
     config: any
-    handler: (ctx: any, params?: any) => Promise<any>
+    handler: (ctx: any, params?: any) => Promise<any> | AsyncGenerator<any, any, unknown>
   }>
   Create: (...args: any[]) => any
+  CreateStream?: (...args: any[]) => any
 }