ts-procedures 7.3.0 → 8.0.0

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

@@ -1,320 +0,0 @@
-import { Hono, Context } from 'hono'
-import { kebabCase } from 'es-toolkit/string'
-import { TProcedureRegistration } from '../../../index.js'
-import {
-  ExtractConfig,
-  ExtractContext,
-  ProceduresFactory,
-  RPCConfig,
-  RPCHttpRouteDoc,
-} from '../../types.js'
-import {
-  ErrorTaxonomy,
-  ErrorTaxonomyEntry,
-  UnknownErrorConfig,
-  defineErrorTaxonomy,
-  resolveErrorResponse,
-} from '../error-taxonomy.js'
-import { castArray } from 'es-toolkit/compat'
-import { HonoFactoryItem } from './types.js'
-
-export type { RPCConfig, RPCHttpRouteDoc }
-export { defineErrorTaxonomy }
-export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
-
-export type HonoRPCAppBuilderConfig = {
-  /**
-   * An existing Hono application instance to use.
-   * If not provided, a new instance will be created.
-   */
-  app?: Hono
-  /** Optional path prefix for all RPC routes. */
-  pathPrefix?: string
-  onRequestStart?: (c: Context) => void
-  onRequestEnd?: (c: Context) => void
-  onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
-  /**
-   * Declarative error-to-response mapping (one of the two peer error modes).
-   * See hono-api for the full taxonomy contract. User entries take precedence
-   * over the framework default taxonomy.
-   */
-  errors?: ErrorTaxonomy
-  /** Fallback serializer for errors not matched by the taxonomy. */
-  unknownError?: UnknownErrorConfig
-  /**
-   * Imperative error callback — the other peer error mode. Receives every
-   * error directly and returns the HTTP response. Use this when you want full
-   * control over the response shape, or alongside `errors` for the tail of
-   * errors the taxonomy doesn't cover.
-   */
-  onError?: (
-    procedure: TProcedureRegistration,
-    c: Context,
-    error: Error
-  ) => Response | Promise<Response>
-  /**
-   * Cross-cutting observer — fires for every caught error, BEFORE dispatch.
-   * Awaited. Cannot mutate the response. Intended for logging, tracing, and
-   * metrics. Thrown errors inside the observer are swallowed and logged.
-   */
-  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
-}
-
-/**
- * Context passed to the `onRequestError` observer.
- */
-export type OnRequestErrorContext = {
-  err: unknown
-  procedure: TProcedureRegistration
-  raw: Context
-}
-
-/**
- * Builder class for creating a Hono application with RPC routes.
- *
- * Usage:
- *   const PublicRPC = Procedures<PublicRPCContext, RPCConfig>()
- *   const ProtectedRPC = Procedures<ProtectedRPCContext, RPCConfig>()
- *
- *   const rpcApp = new HonoRPCAppBuilder()
- *     .register(PublicRPC, (c): Promise<PublicRPCContext> => { /* context resolution logic * / })
- *     .register(ProtectedRPC, (c): Promise<ProtectedRPCContext> => { /* context resolution logic * / })
- *     .build();
- *
- *   const app = rpcApp.app; // Hono application
- *   const docs = rpcApp.docs; // RPC route documentation
- */
-export class HonoRPCAppBuilder {
-  /**
-   * Constructor for HonoRPCAppBuilder.
-   *
-   * @param config
-   */
-  constructor(readonly config?: HonoRPCAppBuilderConfig) {
-    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 RPC route path based on the RPC configuration.
-   * `RPCConfig.scope` can be a string or an array of strings to form nested paths.
-   *
-   * Example
-   *  name:  'GetUser'
-   *  scope: ['users', 'profile']
-   *  version: 1
-   *  path: /users/profile/get-user/1
-   * @param config
-   */
-  static makeRPCHttpRoutePath({
-    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 makeRPCHttpRoutePath that uses the builder's pathPrefix.
-   * @param config - The RPC configuration
-   */
-  makeRPCHttpRoutePath(name: string, config: RPCConfig): string {
-    return HonoRPCAppBuilder.makeRPCHttpRoutePath({
-      name,
-      config,
-      prefix: this.config?.pathPrefix,
-    })
-  }
-
-  private factories: HonoFactoryItem<any>[] = []
-
-  private _app: Hono = new Hono()
-  private _docs: (RPCHttpRouteDoc & object)[] = []
-  private _skipped: { name: string; reason: string }[] = []
-
-  get app(): Hono {
-    return this._app
-  }
-
-  get docs(): RPCHttpRouteDoc[] {
-    return this._docs
-  }
-
-  /**
-   * Procedures that were skipped at `build()` time because they don't fit
-   * this builder (e.g. streaming procedures registered against an RPC
-   * 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.
-   * @param factory - The procedure factory created by Procedures<Context, RPCConfig>()
-   * @param factoryContext - The context for procedure handlers. Can be a direct value,
-   *                         a sync function (c) => Context, or an async function (c) => Promise<Context>
-   * @param extendProcedureDoc - A custom function to extend the generated RPC route documentation for each procedure.
-   */
-  register<TFactory extends ProceduresFactory>(
-    factory: TFactory,
-    factoryContext:
-      | ExtractContext<TFactory>
-      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
-    extendProcedureDoc?: (params: {
-      /* RPC App builder base http route doc */
-      base: RPCHttpRouteDoc
-      /* Procedure registration */
-      procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
-    }) => Record<string, any>
-  ): this {
-    this.factories.push({ factory, factoryContext, extendProcedureDoc } as HonoFactoryItem<any>)
-    return this
-  }
-
-  /**
-   * Builds and returns the Hono application with registered RPC routes.
-   * @return Hono
-   */
-  build(): Hono {
-    this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
-      factory.getProcedures().forEach((procedure: TProcedureRegistration<any, RPCConfig>) => {
-        // Skip streaming procedures — RPC builder cannot serve them. Without
-        // this guard, the procedure would silently get a POST route that
-        // returns its async generator object as a JSON response, which is not
-        // a useful failure mode. Procedures meant to stream should be
-        // registered with HonoStreamAppBuilder.
-        if ((procedure as { isStream?: boolean }).isStream === true) {
-          const reason =
-            'Streaming procedure registered with HonoRPCAppBuilder — register it with HonoStreamAppBuilder instead.'
-          this._skipped.push({ name: procedure.name, reason })
-          console.warn(
-            `[ts-procedures hono-rpc] Skipping procedure "${procedure.name}": ${reason}`
-          )
-          return
-        }
-
-        const route = this.buildRpcHttpRouteDoc(procedure, extendProcedureDoc)
-
-        this._docs.push(route)
-
-        this._app.post(route.path, async (c) => {
-          try {
-            const context =
-              typeof factoryContext === 'function'
-                ? await factoryContext(c)
-                : (factoryContext as ExtractContext<typeof factory>)
-
-            // Hono uses c.req.json() for body parsing
-            const body = await c.req.json().catch(() => ({}))
-            const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, body)
-
-            if (this.config?.onSuccess) {
-              this.config.onSuccess(procedure, c)
-            }
-
-            // Hono returns Response objects via c.json()
-            return c.json(result)
-          } catch (error) {
-            if (this.config?.onRequestError) {
-              try {
-                await this.config.onRequestError({ err: error, procedure, raw: c })
-              } catch (observerErr) {
-                console.error('[ts-procedures hono-rpc] onRequestError threw — swallowed:', observerErr)
-              }
-            }
-            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)
-          }
-        })
-      })
-    })
-
-    return this._app
-  }
-
-  /**
-   * Generates the RPC HTTP route for the given procedure.
-   * @param procedure
-   */
-  private buildRpcHttpRouteDoc(
-    procedure: TProcedureRegistration<any, RPCConfig>,
-    extendProcedureDoc: HonoFactoryItem['extendProcedureDoc']
-  ): RPCHttpRouteDoc {
-    const { config } = procedure
-    const path = HonoRPCAppBuilder.makeRPCHttpRoutePath({
-      name: procedure.name,
-      config,
-      prefix: this.config?.pathPrefix,
-    })
-    const method = 'post' as const // RPCs use POST method
-    const jsonSchema: { body?: Record<string, unknown>; response?: Record<string, unknown> } = {}
-
-    if (config.schema?.params) {
-      jsonSchema.body = config.schema.params
-    }
-    if (config.schema?.returnType) {
-      jsonSchema.response = config.schema.returnType
-    }
-
-    const base: RPCHttpRouteDoc = {
-      kind: 'rpc' as const,
-      name: procedure.name,
-      version: config.version,
-      scope: config.scope,
-      path,
-      method,
-      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-rpc/types.ts

@@ -1,16 +0,0 @@
-import { ExtractConfig, ExtractContext, RPCConfig, RPCHttpRouteDoc } from '../../types.js'
-import { Procedures, TProcedureRegistration } from '../../../index.js'
-import { Context } from 'hono'
-
-export type HonoFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
-  factory: TFactory
-  factoryContext:
-    | ExtractContext<TFactory>
-    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
-  extendProcedureDoc?: (params: {
-    /* RPC App builder base http route doc */
-    base: RPCHttpRouteDoc
-    /* Procedure registration */
-    procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
-  }) => Record<string, any>
-}