ts-procedures 2.1.1 → 3.0.1

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

@@ -0,0 +1,293 @@
+# 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 }
+})
+```
+
+## Error Handling
+
+Custom error handler receives the procedure, context, and error. **Must return a Response:**
+
+```typescript
+const builder = new HonoRPCAppBuilder({
+  error: (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): this` | Register procedure factory with context |
+| `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}`),
+  error: (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
+```