ts-procedures 7.3.0 → 8.1.0

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

@@ -1,357 +0,0 @@
-# HonoRPCAppBuilder
-
-Hono integration for `ts-procedures` that creates type-safe RPC endpoints as POST routes. Works with Bun, Deno, Cloudflare Workers, and Node.js.
-
-## Installation
-
-```bash
-npm install ts-procedures hono
-```
-
-## Quick Start
-
-```typescript
-import { Hono } from 'hono'
-import { Procedures } from 'ts-procedures'
-import { HonoRPCAppBuilder, RPCConfig } from 'ts-procedures/hono-rpc'
-import { Type } from 'typebox'
-
-// Define your context type
-type AppContext = { userId: string }
-
-// Create a procedure factory
-const RPC = Procedures<AppContext, RPCConfig>()
-
-// Define procedures
-RPC.Create(
-  'GetUser',
-  {
-    scope: ['users', 'profile'],
-    version: 1,
-    schema: {
-      params: Type.Object({ id: Type.String() }),
-      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
-    },
-  },
-  async (ctx, params) => {
-    return { id: params.id, name: 'John Doe' }
-  }
-)
-
-// Build the Hono app
-const builder = new HonoRPCAppBuilder({ pathPrefix: '/rpc' }).register(RPC, (c) => ({
-  userId: c.req.header('x-user-id') || 'anonymous',
-}))
-
-const app = builder.build()
-
-// Bun
-export default app
-
-// Node.js
-// import { serve } from '@hono/node-server'
-// serve(app)
-
-// POST /rpc/users/profile/get-user/1 → { id: "123", name: "John Doe" }
-```
-
-## Configuration
-
-```typescript
-type HonoRPCAppBuilderConfig = {
-  app?: Hono // Existing Hono app (optional)
-  pathPrefix?: string // Prefix for all routes (e.g., '/rpc/v1')
-  onRequestStart?: (c: Context) => void
-  onRequestEnd?: (c: Context) => void
-  onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
-  onError?: (
-    procedure: TProcedureRegistration,
-    c: Context,
-    error: Error
-  ) => Response | Promise<Response>
-}
-```
-
-| Option           | Type                         | Description                                       |
-| ---------------- | ---------------------------- | ------------------------------------------------- |
-| `app`            | `Hono`                       | Use existing Hono app instead of creating new one |
-| `pathPrefix`     | `string`                     | Prefix all routes (e.g., `/rpc/v1`)               |
-| `onRequestStart` | `(c) => void`                | Called at start of each request                   |
-| `onRequestEnd`   | `(c) => void`                | Called after handler completes                    |
-| `onSuccess`      | `(proc, c) => void`          | Called on successful handler execution            |
-| `onError`        | `(proc, c, err) => Response` | Imperative error handler (peer of `errors` taxonomy — see Error Handling) |
-
-## Context Resolution
-
-The context resolver receives the Hono `Context` object:
-
-```typescript
-builder.register(RPC, (c: Context) => ({
-  userId: c.req.header('x-user-id') || 'anonymous',
-  userAgent: c.req.header('user-agent'),
-  ip: c.req.raw.headers.get('cf-connecting-ip'), // Cloudflare
-}))
-
-// Async context resolution
-builder.register(RPC, async (c) => {
-  const token = c.req.header('authorization')?.replace('Bearer ', '')
-  const user = await verifyToken(token)
-  return { userId: user.id, roles: user.roles }
-})
-```
-
-## Extending Procedure Documentation
-
-The `register` method accepts an optional third parameter `extendProcedureDoc` that allows you to add custom fields to each procedure's documentation. This is useful for adding metadata like descriptions, tags, or custom fields for API documentation generators.
-
-```typescript
-// Example of a factory extending the procedure config:
-type ExtendedRPCConfig = {
-  description: string
-  tags: string[]
-}
-
-builder.register(RPC, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }), {
-  extendProcedureDoc: ({ base, procedure }, { base: RPCHttpRouteDoc, procedure }) =>
-    ({
-      description: `Procedure: ${procedure.name}`,
-      tags: Array.isArray(procedure.config.scope)
-        ? procedure.config.scope
-        : [procedure.config.scope],
-    }),
-})
-
-// Access extended docs after build()
-const app = builder.build()
-console.log(builder.docs) // Each doc now includes description and tags
-```
-
-The `extendProcedureDoc` callback receives:
-
-| Parameter   | Type                     | Description                                                                                |
-| ----------- | ------------------------ | ------------------------------------------------------------------------------------------ |
-| `base`      | `RPCHttpRouteDoc`        | The base documentation with `name`, `path`, `method`, `scope`, `version`, and `jsonSchema` |
-| `procedure` | `TProcedureRegistration` | The full procedure registration including `name`, `config`, and `handler`                  |
-
-This allows you to derive documentation fields from procedure config or add static metadata per factory registration.
-
-## Abort Signal
-
-`HonoRPCAppBuilder` automatically injects the HTTP request's `AbortSignal` (`c.req.raw.signal`) into the handler context. When a client disconnects mid-request, `ctx.signal` aborts, cancelling any signal-aware operations:
-
-```typescript
-RPC.Create(
-  'SlowQuery',
-  { scope: 'data', version: 1 },
-  async (ctx, params) => {
-    // Automatically cancelled if client disconnects
-    const response = await fetch('https://slow-api.example.com/data', {
-      signal: ctx.signal,
-    })
-    return response.json()
-  }
-)
-```
-
-To use `ctx.signal` with type safety, include `signal: AbortSignal` in your context type:
-
-```typescript
-type AppContext = { userId: string; signal: AbortSignal }
-const RPC = Procedures<AppContext, RPCConfig>()
-```
-
-## 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-rpc'
-
-const appErrors = defineErrorTaxonomy({
-  AuthError: { class: AuthError, statusCode: 401 },
-})
-
-new HonoRPCAppBuilder({
-  errors: appErrors,
-  unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
-})
-```
-
-Full contract (both peer error modes, `onRequestError` observer, per-route narrowing via `RPCConfig<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.
-
-## Using Existing Hono App
-
-You can add RPC routes to an existing Hono application:
-
-```typescript
-const app = new Hono()
-
-// Add custom middleware and routes
-app.use('*', cors())
-app.get('/custom', (c) => c.json({ custom: true }))
-
-const builder = new HonoRPCAppBuilder({ app }).register(RPC, contextResolver)
-
-builder.build() // Adds RPC routes to existing app
-```
-
-## Runtime Compatibility
-
-HonoRPCAppBuilder works across all Hono-supported runtimes:
-
-### Bun
-
-```typescript
-const app = builder.build()
-export default app
-```
-
-### Node.js
-
-```typescript
-import { serve } from '@hono/node-server'
-
-const app = builder.build()
-serve(app)
-```
-
-### Deno
-
-```typescript
-import { serve } from 'https://deno.land/std/http/server.ts'
-
-const app = builder.build()
-serve(app.fetch)
-```
-
-### Cloudflare Workers
-
-```typescript
-const app = builder.build()
-export default app
-```
-
-## API Reference
-
-### Constructor
-
-```typescript
-new HonoRPCAppBuilder(config?: HonoRPCAppBuilderConfig)
-```
-
-### Methods
-
-| Method                 | Signature                                         | Description                                                        |
-| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
-| `register`             | `register<T>(factory, context, options?): this`   | Register procedure factory with context and optional doc extension |
-| `build`                | `build(): Hono`                                   | Build routes and return app                                        |
-| `makeRPCHttpRoutePath` | `makeRPCHttpRoutePath(config: RPCConfig): string` | Generate route path                                                |
-
-### Static Methods
-
-| Method                 | Signature                                                 | Description                            |
-| ---------------------- | --------------------------------------------------------- | -------------------------------------- |
-| `makeRPCHttpRoutePath` | `static makeRPCHttpRoutePath({ config, prefix }): string` | Generate route path with custom prefix |
-
-### Properties
-
-| Property | Type                      | Description                           |
-| -------- | ------------------------- | ------------------------------------- |
-| `app`    | `Hono`                    | The Hono application instance         |
-| `docs`   | `RPCHttpRouteDoc[]`       | Route documentation (after `build()`) |
-| `config` | `HonoRPCAppBuilderConfig` | The configuration object              |
-
-## TypeScript Types
-
-```typescript
-import { HonoRPCAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-rpc'
-import type {
-  HonoRPCAppBuilderConfig,
-  RPCConfig,
-  RPCHttpRouteDoc,
-  ErrorTaxonomy,
-  ErrorTaxonomyEntry,
-  UnknownErrorConfig,
-  OnRequestErrorContext,
-} from 'ts-procedures/hono-rpc'
-```
-
-## Full Example
-
-```typescript
-import { Hono, Context } from 'hono'
-import { Procedures } from 'ts-procedures'
-import { HonoRPCAppBuilder, RPCConfig } from 'ts-procedures/hono-rpc'
-import { Type } from 'typebox'
-
-// Context types
-type PublicContext = { source: 'public' }
-type AuthContext = { source: 'auth'; userId: string }
-
-// Create factories
-const PublicRPC = Procedures<PublicContext, RPCConfig>()
-const AuthRPC = Procedures<AuthContext, RPCConfig>()
-
-// Public procedures
-PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({
-  status: 'ok',
-}))
-
-PublicRPC.Create('GetVersion', { scope: ['system', 'version'], version: 1 }, async () => ({
-  version: '1.0.0',
-}))
-
-// Authenticated procedures
-AuthRPC.Create(
-  'GetProfile',
-  {
-    scope: ['users', 'profile'],
-    version: 1,
-    schema: { returnType: Type.Object({ userId: Type.String() }) },
-  },
-  async (ctx) => ({ userId: ctx.userId })
-)
-
-AuthRPC.Create(
-  'UpdateProfile',
-  {
-    scope: ['users', 'profile'],
-    version: 2,
-    schema: { params: Type.Object({ name: Type.String() }) },
-  },
-  async (ctx, params) => ({ userId: ctx.userId, name: params.name })
-)
-
-// Build app
-const builder = new HonoRPCAppBuilder({
-  pathPrefix: '/rpc',
-  onRequestStart: (c) => console.log(`→ ${c.req.method} ${c.req.path}`),
-  onRequestEnd: (c) => console.log(`← completed`),
-  onSuccess: (proc) => console.log(`✓ ${proc.name}`),
-  onError: (proc, c, err) => {
-    console.error(`✗ ${proc.name}:`, err.message)
-    return c.json({ error: err.message }, 500)
-  },
-})
-
-builder
-  .register(PublicRPC, () => ({ source: 'public' as const }))
-  .register(AuthRPC, (c) => ({
-    source: 'auth' as const,
-    userId: c.req.header('x-user-id') || 'anonymous',
-  }))
-
-const app = builder.build()
-
-// Generated routes:
-// POST /rpc/health/health-check/1
-// POST /rpc/system/version/get-version/1
-// POST /rpc/users/profile/get-profile/1
-// POST /rpc/users/profile/update-profile/2
-
-console.log(
-  'Routes:',
-  builder.docs.map((d) => d.path)
-)
-export default app
-```

package/src/implementations/http/hono-rpc/error-taxonomy.test.ts

@@ -1,82 +0,0 @@
-import { describe, expect, test, vi } from 'vitest'
-import { Type } from 'typebox'
-import { Procedures } from '../../../index.js'
-import { RPCConfig } from '../../types.js'
-import { HonoRPCAppBuilder, defineErrorTaxonomy } from './index.js'
-
-class UseCaseError extends Error {
-  constructor(
-    readonly externalMsg: string,
-    readonly internalMsg: string
-  ) {
-    super(externalMsg)
-    this.name = 'UseCaseError'
-    Object.setPrototypeOf(this, UseCaseError.prototype)
-  }
-}
-
-describe('HonoRPCAppBuilder — error taxonomy', () => {
-  test('taxonomy catches user error thrown from RPC handler', async () => {
-    const errors = defineErrorTaxonomy({
-      UseCaseError: {
-        class: UseCaseError,
-        statusCode: 422,
-        toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
-      },
-    })
-
-    const RPC = Procedures<{}, RPCConfig>()
-    RPC.Create(
-      'Boom',
-      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
-      async () => {
-        throw new UseCaseError('ext', 'int')
-      }
-    )
-
-    const app = new HonoRPCAppBuilder({ errors }).register(RPC, () => ({})).build()
-    const res = await app.request('/test/boom/1', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: '{}',
-    })
-    expect(res.status).toBe(422)
-    expect(await res.json()).toEqual({ name: 'UseCaseError', message: 'ext' })
-  })
-
-  test('unknownError catches unmapped errors', async () => {
-    const RPC = Procedures<{}, RPCConfig>()
-    RPC.Create(
-      'Boom',
-      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
-      async () => {
-        throw new TypeError('db down')
-      }
-    )
-    const app = new HonoRPCAppBuilder({
-      unknownError: { statusCode: 503, toResponse: () => ({ name: 'ServiceUnavailable' }) },
-    })
-      .register(RPC, () => ({}))
-      .build()
-
-    const res = await app.request('/test/boom/1', { method: 'POST', body: '{}' })
-    expect(res.status).toBe(503)
-    expect(await res.json()).toEqual({ name: 'ServiceUnavailable' })
-  })
-
-  test('onError callback runs when taxonomy does not match', async () => {
-    const onError = vi.fn(async (_p: any, c: any) => c.json({ legacy: true }, 418))
-    const RPC = Procedures<{}, RPCConfig>()
-    RPC.Create(
-      'Boom',
-      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
-      async () => {
-        throw new TypeError('legacy')
-      }
-    )
-    const app = new HonoRPCAppBuilder({ onError }).register(RPC, () => ({})).build()
-    const res = await app.request('/test/boom/1', { method: 'POST', body: '{}' })
-    expect(res.status).toBe(418)
-    expect(onError).toHaveBeenCalledOnce()
-  })
-})