ts-procedures 5.3.0 → 5.4.1

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

@@ -1,435 +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'
-
-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 {
-        for await (const value of generator) {
-          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 }),
-          })
-        }
-      } 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 = {
-      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

@@ -1,29 +0,0 @@
-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?: Record<string, unknown>
-    yieldType?: Record<string, unknown>
-    returnType?: Record<string, unknown>
-  }
-}
-
-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

@@ -1,75 +0,0 @@
-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 {
-  name: string // procedure name
-  path: string
-  method: 'post'
-  jsonSchema: {
-    body?: Record<string, unknown>
-    response?: Record<string, unknown>
-  }
-}
-
-export type StreamMode = 'sse' | 'text'
-
-export interface StreamHttpRouteDoc extends RPCConfig {
-  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
-}