ts-procedures 7.3.0 → 8.0.0

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

@@ -1,622 +0,0 @@
-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'
-import {
-  ErrorTaxonomy,
-  ErrorTaxonomyEntry,
-  UnknownErrorConfig,
-  defineErrorTaxonomy,
-  resolveErrorResponse,
-} from '../error-taxonomy.js'
-
-export type { StreamHttpRouteDoc, StreamMode }
-export { defineErrorTaxonomy }
-export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
-
-/**
- * Context passed to the `onRequestError` observer. `raw` is the Hono
- * `Context` for the in-flight request — cast at the use site if you need
- * framework-specific fields.
- */
-export type OnRequestErrorContext = {
-  err: unknown
-  procedure: TStreamProcedureRegistration
-  raw: Context
-}
-
-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
-  /**
-   * Declarative error-to-response mapping (one of the two peer error modes).
-   * Thrown error classes map to status codes + bodies declaratively. The
-   * taxonomy applies to BOTH pre-stream errors (where the status code is
-   * honored) AND mid-stream errors (where only the body shape is honored —
-   * the HTTP status is already committed once streaming starts; the body is
-   * written as the SSE `event: 'error'` data, or a JSON line in text mode,
-   * for the client's error registry to dispatch). See hono-api for the full
-   * taxonomy contract.
-   */
-  errors?: ErrorTaxonomy
-  /**
-   * Fallback serializer when a taxonomy is configured but no entry matches.
-   */
-  unknownError?: UnknownErrorConfig
-  /**
-   * Imperative pre-stream error callback — the other peer error mode.
-   * Receives every pre-stream error directly and returns the HTTP response.
-   * Use this instead of `errors` when you want full control over the response
-   * shape, or alongside it for the tail of errors the taxonomy doesn't cover.
-   *
-   * Mid-stream errors always go through `onMidStreamError`.
-   */
-  onError?: (
-    procedure: TStreamProcedureRegistration,
-    c: Context,
-    error: ProcedureValidationError | Error
-  ) => Response | Promise<Response>
-  /**
-   * Cross-cutting observer — fires for every caught pre-stream error, BEFORE
-   * dispatch to the taxonomy or `onError`. Awaited. Cannot mutate the
-   * response. Intended for logging, tracing, and metrics (Sentry, Datadog,
-   * OpenTelemetry). Any error thrown inside the observer is swallowed and
-   * logged so the primary dispatch flow is never disrupted.
-   */
-  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
-  /**
-   * 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)[] = []
-  private _skipped: { name: string; reason: string }[] = []
-
-  get app(): Hono {
-    return this._app
-  }
-
-  get docs(): StreamHttpRouteDoc[] {
-    return this._docs
-  }
-
-  /**
-   * Procedures that were skipped at `build()` time because they don't fit
-   * this builder (e.g. non-streaming procedures registered against the
-   * stream builder). Surfaced via `DocSource.skippedProcedures` so
-   * DocRegistry can warn about coverage gaps.
-   */
-  get skippedProcedures(): { name: string; reason: string }[] {
-    return this._skipped
-  }
-
-  /**
-   * 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. Throw so both the
-        // validation path and the outer-catch (context resolution) path flow
-        // through one dispatch site.
-        if (procedure.config.validation?.params) {
-          const { errors } = procedure.config.validation.params(params)
-          if (errors) {
-            throw new ProcedureValidationError(
-              procedure.name,
-              `Validation error for ${procedure.name}`,
-              errors
-            )
-          }
-        }
-
-        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) {
-        // Observer fires first — cross-cutting, cannot alter dispatch or the
-        // response. Swallow any throw from the observer so the primary flow
-        // never breaks because of instrumentation.
-        if (this.config?.onRequestError) {
-          try {
-            await this.config.onRequestError({ err: error, procedure, raw: c })
-          } catch (observerErr) {
-            console.error('[ts-procedures hono-stream] onRequestError threw — swallowed:', observerErr)
-          }
-        }
-
-        // Dispatch: taxonomy → onError → hard default. The two modes are
-        // peers; developers configure whichever fits their app.
-        if (this.config?.errors || this.config?.unknownError) {
-          const resolved = resolveErrorResponse({
-            err: error,
-            userTaxonomy: this.config.errors,
-            unknownError: this.config.unknownError,
-            procedure,
-            raw: c,
-          })
-          if (resolved) {
-            await resolved.runOnCatch()
-            return c.json(resolved.body, resolved.statusCode as never)
-          }
-        }
-        if (this.config?.onError) {
-          return this.config.onError(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) {
-        // Dispatch order mirrors hono-rpc: taxonomy → onMidStreamError → default.
-        // The HTTP status is already committed (200 OK headers were sent the
-        // moment streaming started), so the taxonomy here only drives the
-        // wire-protocol body shape — clients dispatch through the same error
-        // registry as RPC/API responses by reading `data.name`.
-        let errorData: unknown
-        let sseEventOverride: string | undefined
-        let sseIdOverride: string | undefined
-        let sseRetryOverride: number | undefined
-        let runOnCatch: (() => Promise<void>) | undefined
-
-        if (this.config?.errors || this.config?.unknownError) {
-          const resolved = resolveErrorResponse({
-            err: error,
-            userTaxonomy: this.config.errors,
-            unknownError: this.config.unknownError,
-            procedure,
-            raw: c,
-          })
-          if (resolved) {
-            errorData = resolved.body
-            sseEventOverride = 'error'
-            runOnCatch = resolved.runOnCatch
-          }
-        }
-
-        if (errorData === undefined && this.config?.onMidStreamError) {
-          const errorResult: MidStreamErrorResult<TErrorData> | undefined =
-            this.config.onMidStreamError(procedure, c, error as Error)
-          if (errorResult?.data !== undefined) {
-            errorData = errorResult.data
-            sseEventOverride = procedure.name
-          }
-        }
-
-        if (errorData === undefined) {
-          errorData = { error: (error as Error).message }
-          sseEventOverride = 'error'
-        }
-
-        const sseMeta = getSSEMeta(errorData)
-
-        await stream.writeSSE({
-          data: typeof errorData === 'string' ? errorData : JSON.stringify(errorData),
-          event: sseMeta?.event ?? sseEventOverride ?? 'error',
-          id: sseMeta?.id ?? sseIdOverride ?? String(eventId++),
-          ...((sseMeta?.retry ?? sseRetryOverride) !== undefined && {
-            retry: (sseMeta?.retry ?? sseRetryOverride) as number,
-          }),
-        })
-
-        if (runOnCatch) {
-          await runOnCatch()
-        }
-
-        // 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) {
-        // Same dispatch order as SSE — taxonomy first, onMidStreamError next,
-        // hard default last. Text streams have no event/id metadata, so we
-        // only forward the body bytes.
-        let errorData: unknown
-        let runOnCatch: (() => Promise<void>) | undefined
-
-        if (this.config?.errors || this.config?.unknownError) {
-          const resolved = resolveErrorResponse({
-            err: error,
-            userTaxonomy: this.config.errors,
-            unknownError: this.config.unknownError,
-            procedure,
-            raw: c,
-          })
-          if (resolved) {
-            errorData = resolved.body
-            runOnCatch = resolved.runOnCatch
-          }
-        }
-
-        if (errorData === undefined && this.config?.onMidStreamError) {
-          const errorResult: MidStreamErrorResult<TErrorData> | undefined =
-            this.config.onMidStreamError(procedure, c, error as Error)
-          if (errorResult?.data !== undefined) {
-            errorData = errorResult.data
-          }
-        }
-
-        if (errorData === undefined) {
-          errorData = { error: (error as Error).message }
-        }
-
-        await stream.writeln(JSON.stringify(errorData))
-
-        if (runOnCatch) {
-          await runOnCatch()
-        }
-      } 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'
-
-      const procedures = factory.getProcedures()
-
-      // Track non-streaming procedures so DocRegistry can warn about coverage
-      // gaps (e.g. a regular procedure registered with this builder will get
-      // dropped here and needs to be registered with HonoRPCAppBuilder).
-      for (const p of procedures as { name: string; isStream?: boolean }[]) {
-        if (p.isStream !== true) {
-          const reason =
-            'Non-streaming procedure registered with HonoStreamAppBuilder — register it with HonoRPCAppBuilder (or HonoApiAppBuilder) instead.'
-          this._skipped.push({ name: p.name, reason })
-          console.warn(
-            `[ts-procedures hono-stream] Skipping procedure "${p.name}": ${reason}`
-          )
-        }
-      }
-
-      procedures
-        .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,
-    })
-    // POST first so codegen (which uses `methods[0]`) defaults to POST. POST is
-    // the canonical method for streaming procedures because it can carry a body
-    // for params; GET is the supplementary method for query-string callers.
-    const methods = ['post', 'get'] 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,
-    }
-
-    if (config.errors && config.errors.length > 0) {
-      base.errors = [...config.errors]
-    }
-
-    let extendedDoc: object = {}
-
-    if (extendProcedureDoc) {
-      extendedDoc = extendProcedureDoc({ base, procedure })
-    }
-
-    return {
-      ...extendedDoc,
-      ...base,
-    }
-  }
-}

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

@@ -1,20 +0,0 @@
-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>
-}