ts-procedures 5.7.2 → 5.9.0

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

@@ -0,0 +1,358 @@
+# 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 { v } from 'suretype'
+
+// 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: v.object({ id: v.string() }),
+      returnType: v.object({ id: v.string(), name: v.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
+  error?: (
+    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            |
+| `error`          | `(proc, c, err) => Response` | Custom error handler (must return Response)       |
+
+## 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
+
+Custom error handler receives the procedure, context, and error. **Must return a Response:**
+
+```typescript
+const builder = new HonoRPCAppBuilder({
+  onError: (procedure, c, error) => {
+    console.error(`Error in ${procedure.name}:`, error)
+
+    if (error instanceof ValidationError) {
+      return c.json({ error: error.message, code: 'VALIDATION_ERROR' }, 400)
+    }
+
+    if (error instanceof AuthError) {
+      return c.json({ error: 'Unauthorized', code: 'AUTH_ERROR' }, 401)
+    }
+
+    return c.json({ error: 'Internal server error' }, 500)
+  },
+})
+```
+
+**Default error handling:** Returns `{ error: message }` with status 500.
+
+## 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,
+  HonoRPCAppBuilderConfig,
+  RPCConfig,
+  RPCHttpRouteDoc,
+} 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 { v } from 'suretype'
+
+// 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: v.object({ userId: v.string() }) },
+  },
+  async (ctx) => ({ userId: ctx.userId })
+)
+
+AuthRPC.Create(
+  'UpdateProfile',
+  {
+    scope: ['users', 'profile'],
+    version: 2,
+    schema: { params: v.object({ name: v.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/1
+// POST /rpc/system/version/get-version/1
+// POST /rpc/users/profile/get-user/1
+// POST /rpc/users/profile/get-user/2
+
+console.log(
+  'Routes:',
+  builder.docs.map((d) => d.path)
+)
+export default app
+```