ts-procedures 7.3.0 → 8.0.0

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

@@ -1,327 +0,0 @@
-import express from 'express'
-import { kebabCase } from 'es-toolkit/string'
-import { Procedures, 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 { ExpressFactoryItem } from './types.js'
-
-export type { RPCConfig, RPCHttpRouteDoc }
-export { defineErrorTaxonomy }
-export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
-
-export type ExpressRPCAppBuilderConfig = {
-  /**
-   * An existing Express application instance to use.
-   * When provided, ensure to set up necessary middleware (e.g., json/body parser) beforehand.
-   * If not provided, a new instance will be created.
-   */
-  app?: express.Express
-  /** Optional path prefix for all RPC routes. */
-  pathPrefix?: string
-  onRequestStart?: (req: express.Request) => void
-  onRequestEnd?: (req: express.Request, res: express.Response) => void
-  onSuccess?: (
-    procedure: TProcedureRegistration,
-    req: express.Request,
-    res: express.Response
-  ) => void
-  /**
-   * Declarative error-to-response mapping (one of the two peer error modes).
-   * See hono-api for the full taxonomy contract. The `raw` field passed to
-   * taxonomy callbacks is `{ req, res }`.
-   */
-  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 writes the response via `res`. Use this when you want
-   * full control, or alongside `errors` for the tail of errors the taxonomy
-   * doesn't cover.
-   */
-  onError?: (
-    procedure: TProcedureRegistration,
-    req: express.Request,
-    res: express.Response,
-    error: Error
-  ) => void
-  /**
-   * Cross-cutting observer — fires for every caught error, BEFORE dispatch.
-   * Awaited. Cannot write to `res` (observer only — check `res.headersSent`
-   * if you must touch it). Thrown errors inside the observer are swallowed
-   * and logged.
-   */
-  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
-}
-
-/**
- * Context passed to the `onRequestError` observer. `raw` is `{ req, res }`
- * for the in-flight request.
- */
-export type OnRequestErrorContext = {
-  err: unknown
-  procedure: TProcedureRegistration
-  raw: { req: express.Request; res: express.Response }
-}
-
-/**
- * Builder class for creating an Express application with RPC routes.
- *
- * Usage:
- *   const PublicRPC = Procedures<PublicRPCContext, RPCConfig>()
- *   const ProtectedRPC = Procedures<ProtectedRPCContext, RPCConfig>()
- *
- *   const rpcApp = new ExpressRPCAppBuilder()
- *     .register(PublicRPC, (req): Promise<PublicRPCContext> => { /* context resolution logic * / })
- *     .register(ProtectedRPC, (req): Promise<ProtectedRPCContext> => { /* context resolution logic * / })
- *     .build();
- *
- *   const app = rpcApp.app; // Express application
- *   const docs = rpcApp.docs; // RPC route documentation
- */
-export class ExpressRPCAppBuilder {
-  /**
-   * Constructor for ExpressRPCAppBuilder.
-   *
-   * @param config
-   */
-  constructor(readonly config?: ExpressRPCAppBuilderConfig) {
-    if (config?.app) {
-      this._app = config.app
-    } else {
-      // Default middleware if no app is provided
-      this._app.use(express.json())
-    }
-
-    if (config?.onRequestStart) {
-      this._app.use((req, res, next) => {
-        config.onRequestStart!(req)
-        next()
-      })
-    }
-
-    if (config?.onRequestEnd) {
-      this._app.use((req, res, next) => {
-        res.on('finish', () => {
-          config.onRequestEnd!(req, res)
-        })
-        next()
-      })
-    }
-  }
-
-  /**
-   * 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 ExpressRPCAppBuilder.makeRPCHttpRoutePath({
-      name,
-      config,
-      prefix: this.config?.pathPrefix,
-    })
-  }
-
-  private factories: ExpressFactoryItem<any>[] = []
-
-  private _app: express.Express = express()
-  private _docs: (RPCHttpRouteDoc & object)[] = []
-
-  get app(): express.Express {
-    return this._app
-  }
-
-  get docs(): RPCHttpRouteDoc[] {
-    return this._docs
-  }
-
-  /**
-   * 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 (req) => Context, or an async function (req) => 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>
-      | ((req: express.Request) => 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 ExpressFactoryItem<any>)
-    return this
-  }
-
-  /**
-   * Builds and returns the Express application with registered RPC routes.
-   * @return express.Application
-   */
-  build(): express.Application {
-    this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
-      factory.getProcedures().map((procedure: TProcedureRegistration<any, RPCConfig>) => {
-        const route = this.buildRpcHttpRouteDoc(procedure, extendProcedureDoc)
-
-        this._docs.push(route)
-
-        this._app[route.method](route.path, async (req, res) => {
-          try {
-            const context =
-              typeof factoryContext === 'function'
-                ? await factoryContext(req)
-                : (factoryContext as ExtractContext<typeof factory>)
-
-            let ac: AbortController | undefined
-            const ctxWithSignal = Object.defineProperty({ ...context }, 'signal', {
-              get() {
-                if (!ac) {
-                  ac = new AbortController()
-                  req.on('close', () => { if (!res.writableFinished) ac!.abort() })
-                }
-                return ac.signal
-              },
-              enumerable: true,
-            })
-
-            res.json(await procedure.handler(ctxWithSignal, req.body))
-            if (this.config?.onSuccess) {
-              this.config.onSuccess(procedure, req, res)
-            }
-            // if status not set, set to 200
-            if (!res.status) {
-              res.status(200)
-            }
-          } catch (error) {
-            if (this.config?.onRequestError) {
-              try {
-                await this.config.onRequestError({ err: error, procedure, raw: { req, res } })
-              } catch (observerErr) {
-                console.error('[ts-procedures express-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: { req, res },
-              })
-              if (resolved) {
-                await resolved.runOnCatch()
-                if (!res.headersSent) {
-                  res.status(resolved.statusCode).json(resolved.body)
-                }
-                return
-              }
-            }
-            if (this.config?.onError) {
-              this.config.onError(procedure, req, res, error as Error)
-              return
-            }
-            // Hard default — `res.status` is always truthy (it's a method),
-            // so the previous `if (!res.status)` guard never ran. Set status
-            // and body together unconditionally, respecting an already-sent
-            // response.
-            if (!res.headersSent) {
-              res.status(500).json({ error: (error as Error).message })
-            }
-          }
-        })
-      })
-    })
-
-    return this._app
-  }
-
-  /**
-   * Generates the RPC HTTP route for the given procedure.
-   * @param procedure
-   */
-  private buildRpcHttpRouteDoc(
-    procedure: TProcedureRegistration<any, RPCConfig>,
-    extendProcedureDoc: ExpressFactoryItem['extendProcedureDoc']
-  ): RPCHttpRouteDoc {
-    const { config } = procedure
-    const path = ExpressRPCAppBuilder.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/express-rpc/types.ts

@@ -1,16 +0,0 @@
-import { ExtractConfig, ExtractContext, RPCConfig, RPCHttpRouteDoc } from '../../types.js'
-import { Procedures, TProcedureRegistration } from '../../../index.js'
-import express from 'express'
-
-export type ExpressFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
-  factory: TFactory
-  factoryContext:
-    | ExtractContext<TFactory>
-    | ((req: express.Request) => 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>
-}

package/src/implementations/http/hono-api/README.md

@@ -1,284 +0,0 @@
-# Hono API (REST-style) Integration
-
-REST-style HTTP integration for Hono — routes are dispatched by HTTP method with per-channel input validation (`schema.input.pathParams`, `query`, `body`, `headers`). Works with Bun, Deno, Cloudflare Workers, and Node.js.
-
-## Installation
-
-```bash
-npm install ts-procedures hono
-```
-
-## Quick Start
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { HonoAPIAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-api'
-import type { APIConfig } from 'ts-procedures/hono-api'
-import { Type } from 'typebox'
-
-// ─── Procedures ───────────────────────────────────────────
-
-const API = Procedures<{ userId: string }, APIConfig>()
-
-API.Create('GetUser', {
-  path: '/users/:id',
-  method: 'get',
-  schema: {
-    input: {
-      pathParams: Type.Object({ id: Type.String() }),
-    },
-    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
-  },
-}, async (ctx, { pathParams }) => {
-  return { id: pathParams.id, name: 'John Doe' }
-})
-
-API.Create('CreateUser', {
-  path: '/users',
-  method: 'post',                    // → 201 by default
-  schema: {
-    input: { body: Type.Object({ name: Type.String(), email: Type.String() }) },
-    returnType: Type.Object({ id: Type.String() }),
-  },
-}, async (ctx, { body }) => {
-  return { id: await createUser(body) }
-})
-
-// ─── Build ────────────────────────────────────────────────
-
-const app = new HonoAPIAppBuilder({ pathPrefix: '/api' })
-  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
-  .build()
-
-// Routes:
-//   GET  /api/users/:id   → 200
-//   POST /api/users       → 201
-```
-
-## Configuration
-
-```typescript
-export type HonoAPIAppBuilderConfig = {
-  app?: Hono                                     // Reuse an existing Hono instance
-  pathPrefix?: string                            // Prepend to every route
-  queryParser?: QueryParser                      // Custom query-string parser
-  onRequestStart?: (c: Context) => void
-  onRequestEnd?: (c: Context) => void
-  onSuccess?: (procedure, c: Context) => void
-  errors?: ErrorTaxonomy                         // Declarative error-to-response mapping
-  unknownError?: UnknownErrorConfig              // Fallback for unmatched errors
-  onError?: (procedure, c, error) => Response    // Imperative error callback (peer of `errors` above)
-  onRequestError?: (ctx) => void | Promise<void> // Cross-cutting observer for logging/tracing
-}
-```
-
-| Option | Description |
-|---|---|
-| `app` | Existing Hono instance to register routes on. If omitted, a new `Hono()` is created. |
-| `pathPrefix` | Prefix applied to every route (e.g. `/api/v1`). Leading slash is optional. |
-| `queryParser` | Override the default native `URLSearchParams` parser (see *Query Parsing* below). |
-| `onRequestStart` / `onRequestEnd` | Global lifecycle hooks — wrap every registered route. |
-| `onSuccess` | Called after a handler returns successfully, before the response is sent. |
-| `errors` / `unknownError` | Declarative error handling — see *Error Handling* below. |
-| `onError` | Imperative error callback — first-class peer of the declarative taxonomy. |
-| `onRequestError` | Cross-cutting observer — fires for every caught error before dispatch. Awaited; can't mutate the response. For logging / tracing / metrics. |
-
-## schema.input — Multi-Channel Structured Input
-
-REST endpoints carry input via several transport channels. `schema.input` lets you type and validate each independently:
-
-```typescript
-API.Create('UpdatePost', {
-  path: '/posts/:id',
-  method: 'put',
-  schema: {
-    input: {
-      pathParams: Type.Object({ id: Type.String() }),
-      query: Type.Object({ draft: Type.Optional(Type.Boolean()) }),
-      body: Type.Object({ title: Type.String(), body: Type.String() }),
-      headers: Type.Object({ 'if-match': Type.String() }),
-    },
-    returnType: Type.Object({ id: Type.String(), version: Type.Number() }),
-  },
-}, async (ctx, { pathParams, query, body, headers }) => {
-  // All four channels typed independently.
-  // AJV validates each channel; `removeAdditional` strips undeclared keys from headers.
-})
-```
-
-Supported channels: `pathParams`, `query`, `body`, `headers`. `schema.input` is mutually exclusive with `schema.params` — defining both throws `ProcedureRegistrationError` at registration time.
-
-`HonoAPIAppBuilder` performs build-time consistency checks: `:id` in the path template must match a `pathParams.id` entry in the schema, or the builder throws at `.build()`.
-
-### APIInput helper
-
-```typescript
-import type { APIInput } from 'ts-procedures/hono-api'
-
-const schema = {
-  input: {
-    pathParams: Type.Object({ id: Type.String() }),
-    qurey: Type.Object({ /* ... */ }),  // ← TS error: 'qurey' not in APIInput
-  } satisfies APIInput,
-}
-```
-
-`APIInput` constrains channel names so typos become compile errors.
-
-## Default Success Status
-
-| Method | Default status |
-|---|---|
-| `post` | 201 |
-| `delete` | 204 |
-| `get`, `put`, `patch`, `head` | 200 |
-
-Override via `successStatus` on the per-route config:
-
-```typescript
-API.Create('RemoveUser', {
-  path: '/users/:id',
-  method: 'delete',
-  successStatus: 200,  // Override the default 204
-  schema: { input: { pathParams: Type.Object({ id: Type.String() }) } },
-}, async (ctx, { pathParams }) => { /* ... */ })
-```
-
-## Query Parsing
-
-Default: native `URLSearchParams`. Handles flat keys (`?page=2`) and repeated keys (`?tag=a&tag=b → { tag: ['a', 'b'] }`). It does **not** parse bracket objects, bracket arrays, dot paths, or comma-split arrays.
-
-Opt in to richer parsing via `qs`:
-
-```typescript
-import qs from 'qs'
-
-new HonoAPIAppBuilder({
-  queryParser: (raw) => qs.parse(raw) as Record<string, unknown>,
-})
-```
-
-## Context Resolution
-
-The context resolver receives Hono's `Context` object:
-
-```typescript
-builder.register(API, (c) => ({
-  userId: c.req.header('x-user-id') || 'anonymous',
-  requestId: c.req.header('x-request-id') ?? crypto.randomUUID(),
-}))
-
-// Async context resolution — authenticate per request
-builder.register(API, async (c) => {
-  const token = c.req.header('authorization')?.replace('Bearer ', '')
-  const user = await verifyToken(token)
-  return { userId: user.id, roles: user.roles }
-})
-```
-
-## Abort Signal
-
-`HonoAPIAppBuilder` injects `c.req.raw.signal` as `ctx.signal` in every handler so downstream async calls (fetch, DB queries) can cancel when the client disconnects.
-
-```typescript
-API.Create('StreamingQuery', { /* ... */ }, async (ctx) => {
-  const result = await db.query(sql, { signal: ctx.signal })
-  return result
-})
-```
-
-## Error Handling
-
-Declare error classes via `defineErrorTaxonomy` and pass them to the builder's `errors` option. Handlers `throw` their classes; the builder auto-serializes to the configured status + body.
-
-```typescript
-import { defineErrorTaxonomy } from 'ts-procedures/hono-api'
-
-const appErrors = defineErrorTaxonomy({
-  NotFoundError: { class: NotFoundError, statusCode: 404 },
-})
-
-new HonoAPIAppBuilder({
-  errors: appErrors,
-  unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
-})
-```
-
-Full contract (both peer error modes, `onRequestError` observer, per-route narrowing via `APIConfig<keyof typeof appErrors & string>`): see **[docs/http-integrations.md § Error Handling](../../../../docs/http-integrations.md#error-handling)** — the canonical explanation shared across all four HTTP builders.
-
-## Extending Procedure Documentation
-
-Like the other builders, `register()` accepts an optional third argument that extends each route's generated doc object:
-
-```typescript
-builder.register(API, ctxResolver, ({ base, procedure }) => ({
-  summary: procedure.config.description,
-  tags: [base.scope ?? 'default'],
-  deprecated: procedure.config.description?.toLowerCase().includes('deprecated') ?? false,
-}))
-```
-
-The extended doc is spread onto the `APIHttpRouteDoc` before `base`, so base fields (`kind`, `name`, `method`, `path`, `fullPath`, `jsonSchema`, `errors`) always win.
-
-## Using an Existing Hono App
-
-```typescript
-const app = new Hono()
-app.use('*', cors())
-app.get('/health', (c) => c.json({ ok: true }))
-
-new HonoAPIAppBuilder({ app, pathPrefix: '/api' })
-  .register(API, contextResolver)
-  .build()
-
-// API routes added alongside your custom routes.
-```
-
-## Route Documentation
-
-Each registered procedure generates an `APIHttpRouteDoc` accessible via `builder.docs`:
-
-```typescript
-interface APIHttpRouteDoc {
-  kind: 'api'
-  name: string
-  scope?: string
-  path: string
-  fullPath: string                  // path with pathPrefix applied
-  method: HttpMethod
-  successStatus?: number
-  jsonSchema: {
-    pathParams?: Record<string, unknown>
-    query?: Record<string, unknown>
-    body?: Record<string, unknown>
-    headers?: Record<string, unknown>
-    response?: Record<string, unknown>
-  }
-  errors?: string[]                 // Taxonomy keys this route may emit
-}
-```
-
-Feed these into `DocRegistry` to compose a single `/docs` endpoint from multiple builders — see [docs/http-integrations.md § DocRegistry](../../../../docs/http-integrations.md#docregistry--composing-docs-from-multiple-builders).
-
-## Runtime Compatibility
-
-Runs wherever Hono runs: Bun, Deno, Cloudflare Workers, Node.js 18+. Uses standard Fetch API (`c.req.raw.signal`, `Request`, `Response`) — no Node-specific APIs.
-
-## TypeScript Types
-
-```typescript
-import type {
-  APIConfig,
-  APIHttpRouteDoc,
-  APIInput,
-  HttpMethod,
-  HonoAPIAppBuilderConfig,
-  QueryParser,
-  ErrorTaxonomy,
-  ErrorTaxonomyEntry,
-  UnknownErrorConfig,
-  OnRequestErrorContext,
-} from 'ts-procedures/hono-api'
-
-import { HonoAPIAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-api'
-```