ts-procedures 2.1.0 → 3.0.0

package/src/implementations/http/README.md

@@ -0,0 +1,172 @@
+# HTTP-RPC Implementations
+
+HTTP-RPC builders for `ts-procedures` that create type-safe, versioned RPC endpoints with automatic path generation, schema-based validation, and route documentation.
+
+## Available Implementations
+
+| Framework | Package | Description |
+|-----------|---------|-------------|
+| [Express](./express-rpc/README.md) | `express-rpc` | Express.js integration |
+| [Hono](./hono-rpc/README.md) | `hono-rpc` | Hono integration (Bun, Deno, Cloudflare Workers, Node.js) |
+
+## Core Concepts
+
+### RPCConfig Interface
+
+All HTTP-RPC implementations use a shared configuration interface:
+
+```typescript
+interface RPCConfig {
+  scope: string | string[]  // Route path segment(s)
+  version: number           // API version number
+}
+```
+
+### Path Generation
+
+Routes are generated using kebab-case conversion with the formula:
+
+```
+/{pathPrefix}/{scope...}/{procedureName}/{version}
+```
+
+**Conversion Examples:**
+
+| Scope | Procedure Name | Version | Generated Path |
+|-------|----------------|---------|----------------|
+| `'users'` | `'Create'` | `1` | `/users/create/1` |
+| `'users'` | `'GetById'` | `1` | `/users/get-by-id/1` |
+| `['users', 'admin']` | `'List'` | `1` | `/users/admin/list/1` |
+| `['UserModule', 'permissions']` | `'Update'` | `2` | `/user-module/permissions/update/2` |
+
+**With pathPrefix `/api/v1`:**
+
+| Scope | Procedure Name | Version | Generated Path |
+|-------|----------------|---------|----------------|
+| `'users'` | `'Create'` | `1` | `/api/v1/users/create/1` |
+| `['users', 'admin']` | `'Delete'` | `2` | `/api/v1/users/admin/delete/2` |
+
+### Context Resolution Patterns
+
+The `factoryContext` parameter supports three patterns:
+
+```typescript
+// 1. Static object
+builder.register(RPC, { userId: 'static-123' })
+
+// 2. Sync function
+builder.register(RPC, (req) => ({
+  userId: req.headers['x-user-id']
+}))
+
+// 3. Async function
+builder.register(RPC, async (req) => {
+  const user = await validateToken(req.headers.authorization)
+  return { userId: user.id }
+})
+```
+
+### Lifecycle Hooks
+
+Hooks execute in the following order:
+
+```
+onRequestStart → handler → onSuccess → onRequestEnd
+                    ↓
+              (on error)
+                    ↓
+            error handler
+                    ↓
+            onRequestEnd
+```
+
+| Hook | Trigger | Use Case |
+|------|---------|----------|
+| `onRequestStart` | Before route handler | Logging, request tracking |
+| `onSuccess` | After successful handler execution | Metrics, audit logging |
+| `onRequestEnd` | After response sent | Cleanup, timing metrics |
+| `error` | On handler error | Custom error responses |
+
+### Route Documentation
+
+Each registered procedure generates an `RPCHttpRouteDoc`:
+
+```typescript
+interface RPCHttpRouteDoc {
+  path: string           // Generated route path
+  method: 'post'         // Always POST for RPC
+  jsonSchema: {
+    body?: object        // JSON Schema from schema.params
+    response?: object    // JSON Schema from schema.returnType
+  }
+}
+```
+
+Access documentation via `builder.docs` after calling `build()`:
+
+```typescript
+const builder = new ExpressRPCAppBuilder()
+builder.register(RPC, () => ({}))
+builder.build()
+
+// Generate OpenAPI documentation
+const openApiPaths = builder.docs.reduce((acc, doc) => {
+  acc[doc.path] = {
+    post: {
+      requestBody: doc.jsonSchema.body ? {
+        content: { 'application/json': { schema: doc.jsonSchema.body } }
+      } : undefined,
+      responses: {
+        200: doc.jsonSchema.response ? {
+          content: { 'application/json': { schema: doc.jsonSchema.response } }
+        } : undefined
+      }
+    }
+  }
+  return acc
+}, {})
+```
+
+### Builder Pattern
+
+All implementations follow the same builder pattern:
+
+```typescript
+const builder = new RPCAppBuilder(config)
+  .register(PublicRPC, publicContextResolver)
+  .register(ProtectedRPC, protectedContextResolver)
+
+const app = builder.build()
+const docs = builder.docs
+```
+
+**Key methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `register(factory, context)` | `this` | Register a procedure factory with context resolver |
+| `build()` | Framework app | Create routes and return the application |
+| `makeRPCHttpRoutePath(config)` | `string` | Generate path for an RPCConfig |
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `app` | Framework app | The underlying framework application |
+| `docs` | `RPCHttpRouteDoc[]` | Route documentation (populated after `build()`) |
+
+## Framework Comparison
+
+| Aspect | Express | Hono |
+|--------|---------|------|
+| Context param | `req: express.Request` | `c: Context` |
+| Error handler return | `void` (mutates res) | `Response` |
+| Body access | `req.body` | `await c.req.json()` |
+| Header access | `req.headers['x-id']` | `c.req.header('x-id')` |
+| JSON middleware | Auto-added (or manual) | Built-in |
+
+## TypeScript Types
+
+```typescript
+import { RPCConfig, RPCHttpRouteDoc } from 'ts-procedures/implementations/types'
+```

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

@@ -1,6 +1,6 @@
-# Express RPC Integration
+# ExpressRPCAppBuilder
 
-RPC-style HTTP integration for `ts-procedures` using Express. Creates POST routes at `/rpc/{name}/{version}` paths with automatic JSON schema documentation.
+Express.js integration for `ts-procedures` that creates type-safe RPC endpoints as POST routes.
 
 ## Installation
 
@@ -8,25 +8,17 @@ RPC-style HTTP integration for `ts-procedures` using Express. Creates POST route
 npm install ts-procedures express
 ```
 
-## Import
-
-```typescript
-import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
-```
-
 ## Quick Start
 
 ```typescript
+import express from 'express'
 import { Procedures } from 'ts-procedures'
-import { ExpressRPCAppBuilder, RPCConfig } from 'ts-procedures/express-rpc'
+import { ExpressRPCAppBuilder, RPCConfig } from 'ts-procedures/implementations/http/express-rpc'
 import { v } from 'suretype'
 
 // Define your context type
 type AppContext = { userId: string }
 
-// RPC config type
-// type RPCConfig = { name: string | string[]; version: number }
-
 // Create a procedure factory
 const RPC = Procedures<AppContext, RPCConfig>()
 
@@ -34,12 +26,12 @@ const RPC = Procedures<AppContext, RPCConfig>()
 RPC.Create(
   'GetUser',
   {
-    name: ['users', 'get'],
+    scope: ['users', 'profile'],
     version: 1,
     schema: {
       params: v.object({ id: v.string() }),
-      returnType: v.object({ id: v.string(), name: v.string() }),
-    },
+      returnType: v.object({ id: v.string(), name: v.string() })
+    }
   },
   async (ctx, params) => {
     return { id: params.id, name: 'John Doe' }
@@ -47,285 +39,216 @@ RPC.Create(
 )
 
 // Build the Express app
-const builder = new ExpressRPCAppBuilder()
-  .register(RPC, (req) => ({ userId: req.headers['x-user-id'] as string }))
-  .build()
+const builder = new ExpressRPCAppBuilder({ pathPrefix: '/rpc' })
+  .register(RPC, (req) => ({
+    userId: req.headers['x-user-id'] as string
+  }))
 
-// Start the server
-builder.listen(3000, () => {
-  console.log('RPC server running on http://localhost:3000')
-})
+const app = builder.build()
+app.listen(3000)
 
-// Route created: POST /rpc/users/get/1
+// POST /rpc/users/profile/get-user/1 → { id: "123", name: "John Doe" }
 ```
 
-## API Reference
-
-### `ExpressRPCAppBuilder`
-
-Builder class for creating an Express application with RPC routes.
-
-#### Constructor
+## Configuration
 
 ```typescript
-new ExpressRPCAppBuilder(config?: {
-  app?: express.Express
+type ExpressRPCAppBuilderConfig = {
+  app?: express.Express      // Existing Express app (optional)
+  pathPrefix?: string        // Prefix for all routes (e.g., '/rpc/v1')
   onRequestStart?: (req: express.Request) => void
   onRequestEnd?: (req: express.Request, res: express.Response) => void
   onSuccess?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response) => void
   error?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
-})
+}
 ```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `app` | `express.Express` | Existing Express app to use. When provided, you must configure middleware (e.g., `express.json()`) yourself. If omitted, a new app with JSON middleware is created. |
-| `onRequestStart` | `(req) => void` | Called at the start of each request. |
-| `onRequestEnd` | `(req, res) => void` | Called after the response finishes (via `res.on('finish')`). |
-| `onSuccess` | `(procedure, req, res) => void` | Called after successful procedure execution. |
-| `error` | `(procedure, req, res, error) => void` | Custom error handler. When provided, you control the response. |
+| Option | Type | Description                                          |
+|--------|------|------------------------------------------------------|
+| `app` | `express.Express` | Use existing Express app instead of creating new one |
+| `pathPrefix` | `string` | Prefix all routes (e.g., `/rpc/v1`)                  |
+| `onRequestStart` | `(req) => void` | Called at start of each request                      |
+| `onRequestEnd` | `(req, res) => void` | Called after response finishes                       |
+| `onSuccess` | `(proc, req, res) => void` | Called on successful handler execution               |
+| `error` | `(proc, req, res, err) => void` | Custom error handler                                 |
 
-#### Methods
+## Context Resolution
 
-##### `register<C>(factory, factoryContext): this`
-
-Registers a procedure factory with its context.
+The context resolver receives the Express `Request` object:
 
 ```typescript
-// Direct value
-builder.register(RPC, { userId: 'system' })
-
-// Sync function
-builder.register(RPC, (req) => ({ userId: req.user.id }))
+builder.register(RPC, (req: express.Request) => ({
+  userId: req.headers['x-user-id'] as string,
+  sessionId: req.cookies?.sessionId,
+  ip: req.ip
+}))
 
-// Async function
+// Async context resolution
 builder.register(RPC, async (req) => {
-  const user = await getUser(req.headers.authorization)
-  return { userId: user.id }
+  const token = req.headers.authorization?.replace('Bearer ', '')
+  const user = await verifyToken(token)
+  return { userId: user.id, roles: user.roles }
 })
 ```
 
-- **factory**: The procedure factory created by `Procedures<Context, RPCConfig>()`
-- **factoryContext**: The context for procedure handlers. Can be:
-  - A direct value matching the factory's context type
-  - A sync function `(req: express.Request) => Context`
-  - An async function `(req: express.Request) => Promise<Context>`
-- **Returns**: `this` for method chaining
-
-##### `build(): express.Application`
+## Error Handling
 
-Builds and returns the Express application with all registered RPC routes.
+Custom error handler receives the procedure, request, response, and error:
 
 ```typescript
-const app = builder.build()
-app.listen(3000)
-```
-
-#### Properties
-
-##### `app: express.Express`
-
-The underlying Express application instance.
+const builder = new ExpressRPCAppBuilder({
+  error: (procedure, req, res, error) => {
+    console.error(`Error in ${procedure.name}:`, error)
 
-##### `docs: RPCHttpRouteDoc[]`
+    if (error instanceof ValidationError) {
+      res.status(400).json({ error: error.message, code: 'VALIDATION_ERROR' })
+      return
+    }
 
-Array of route documentation objects, populated after `build()` is called.
+    if (error instanceof AuthError) {
+      res.status(401).json({ error: 'Unauthorized', code: 'AUTH_ERROR' })
+      return
+    }
 
-```typescript
-interface RPCHttpRouteDoc {
-  path: string           // e.g., '/rpc/users/get/1'
-  method: 'post'
-  jsonSchema: {
-    body?: object        // JSON Schema for request params
-    response?: object    // JSON Schema for return type
+    res.status(500).json({ error: 'Internal server error' })
   }
-}
+})
 ```
 
-### `makeRPCHttpRoutePath(config: RPCConfig): string`
-
-Generates the RPC route path from config. Exposed for testing/utilities.
-
-### `buildRpcHttpRouteDoc(procedure): RPCHttpRouteDoc`
-
-Generates route documentation for a procedure. Exposed for testing/utilities.
-
-## Route Path Generation
-
-Routes are generated at `/rpc/{name-segments}/{version}`:
+**Default error handling:** Returns `{ error: message }` with status 500.
 
-| Config Name | Version | Generated Path |
-|-------------|---------|----------------|
-| `'users'` | `1` | `/rpc/users/1` |
-| `['users', 'get-by-id']` | `1` | `/rpc/users/get-by-id/1` |
-| `'getUserById'` | `2` | `/rpc/get-user-by-id/2` |
-| `'GetUserById'` | `1` | `/rpc/get-user-by-id/1` |
+## Using Existing Express App
 
-- Names are converted to kebab-case
-- Array names create nested path segments
-- Version is appended as the final segment (raw number, not `v1`)
-
-## Multiple Factories
-
-Register multiple factories with different contexts:
+When providing an existing Express app, **you must set up JSON parsing middleware**:
 
 ```typescript
-type PublicContext = { source: 'public' }
-type AuthContext = { source: 'auth'; userId: string }
-
-const PublicRPC = Procedures<PublicContext, RPCConfig>()
-const AuthRPC = Procedures<AuthContext, RPCConfig>()
-
-// Define public procedures
-PublicRPC.Create('HealthCheck', { name: 'health', version: 1 }, async () => ({ status: 'ok' }))
+const app = express()
+app.use(express.json())  // Required!
+app.use(cors())
+app.use(helmet())
 
-// Define authenticated procedures
-AuthRPC.Create('GetProfile', { name: ['users', 'profile'], version: 1 }, async (ctx) => ({
-  userId: ctx.userId,
-}))
+const builder = new ExpressRPCAppBuilder({ app })
+  .register(RPC, contextResolver)
 
-// Build with different factoryContext forms
-const app = new ExpressRPCAppBuilder()
-  .register(PublicRPC, { source: 'public' }) // Direct value
-  .register(AuthRPC, (req) => ({             // Sync function
-    source: 'auth',
-    userId: req.headers['x-user-id'] as string,
-  }))
-  .build()
+builder.build()  // Adds RPC routes to existing app
 ```
 
-## Lifecycle Hooks
+When no `app` is provided, `express.json()` middleware is added automatically.
 
-```typescript
-const app = new ExpressRPCAppBuilder({
-  onRequestStart: (req) => {
-    console.log(`[${req.method}] ${req.path}`)
-  },
+## API Reference
 
-  onRequestEnd: (req, res) => {
-    console.log(`Response: ${res.statusCode}`)
-  },
+### Constructor
 
-  onSuccess: (procedure, req, res) => {
-    console.log(`Procedure ${procedure.name} succeeded`)
-  },
-})
+```typescript
+new ExpressRPCAppBuilder(config?: ExpressRPCAppBuilderConfig)
 ```
 
-**Execution order:** `onRequestStart` → handler → `onSuccess` → `onRequestEnd`
+### Methods
 
-Note: `onSuccess` is only called on successful execution. It is NOT called when the handler throws.
-
-## Error Handling
-
-### Custom Error Handler
-
-```typescript
-const app = new ExpressRPCAppBuilder({
-  error: (procedure, req, res, error) => {
-    console.error(`Error in ${procedure.name}:`, error.message)
-
-    if (error instanceof ProcedureValidationError) {
-      res.status(400).json({ error: 'Validation failed', details: error.errors })
-    } else if (error instanceof ProcedureError) {
-      res.status(422).json({ error: error.message })
-    } else {
-      res.status(500).json({ error: 'Internal server error' })
-    }
-  },
-})
-```
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `register` | `register<T>(factory, context): this` | Register procedure factory with context |
+| `build` | `build(): express.Application` | Build routes and return app |
+| `makeRPCHttpRoutePath` | `makeRPCHttpRoutePath(config: RPCConfig): string` | Generate route path |
 
-### Default Error Handling
+### Static Methods
 
-Without a custom error handler, errors return a JSON response with the error message:
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `makeRPCHttpRoutePath` | `static makeRPCHttpRoutePath({ config, prefix }): string` | Generate route path with custom prefix |
 
-```json
-{ "error": "Error message here" }
-```
+### Properties
 
-## Route Documentation
+| Property | Type | Description |
+|----------|------|-------------|
+| `app` | `express.Express` | The Express application instance |
+| `docs` | `RPCHttpRouteDoc[]` | Route documentation (after `build()`) |
+| `config` | `ExpressRPCAppBuilderConfig` | The configuration object |
 
-Access generated documentation after building:
+## TypeScript Types
 
 ```typescript
-const builder = new ExpressRPCAppBuilder()
-builder.register(RPC, factoryContext)
-builder.build()
-
-// Documentation is now available
-console.log(builder.docs)
-// [
-//   {
-//     path: '/rpc/users/get/1',
-//     method: 'post',
-//     jsonSchema: {
-//       body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-//       response: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' } } }
-//     }
-//   }
-// ]
+import {
+  ExpressRPCAppBuilder,
+  ExpressRPCAppBuilderConfig,
+  RPCConfig,
+  RPCHttpRouteDoc
+} from 'ts-procedures/implementations/http/express-rpc'
 ```
 
-Use `docs` to generate OpenAPI specs, API documentation, or client SDKs.
-
-## Using an Existing Express App
+## Full Example
 
 ```typescript
 import express from 'express'
+import { Procedures } from 'ts-procedures'
+import { ExpressRPCAppBuilder, RPCConfig } from 'ts-procedures/implementations/http/express-rpc'
+import { v } from 'suretype'
 
-const app = express()
-
-// Add your own middleware
-app.use(express.json())
-app.use(cors())
-app.use(helmet())
-
-// Mount RPC routes
-const rpcApp = new ExpressRPCAppBuilder({ app })
-  .register(RPC, factoryContext)
-  .build()
-
-// Add other routes
-app.get('/health', (req, res) => res.json({ status: 'ok' }))
+// Context types
+type PublicContext = { source: 'public' }
+type AuthContext = { source: 'auth'; userId: string }
 
-app.listen(3000)
-```
+// Create factories
+const PublicRPC = Procedures<PublicContext, RPCConfig>()
+const AuthRPC = Procedures<AuthContext, RPCConfig>()
 
-**Important:** When providing your own Express app, you must set up middleware like `express.json()` yourself.
+// Public procedures
+PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({
+  status: 'ok'
+}))
 
-## Types
+PublicRPC.Create('GetVersion', { scope: ['system', 'version'], version: 1 }, async () => ({
+  version: '1.0.0'
+}))
 
-```typescript
-import type { RPCConfig, RPCHttpRouteDoc } from 'ts-procedures/express-rpc'
+// Authenticated procedures
+AuthRPC.Create(
+  'GetProfile',
+  {
+    scope: ['users', 'profile'],
+    version: 1,
+    schema: { returnType: v.object({ userId: v.string() }) }
+  },
+  async (ctx) => ({ userId: ctx.userId })
+)
 
-// RPCConfig - Required config shape for procedures
-interface RPCConfig {
-  name: string | string[]
-  version: number
-}
+AuthRPC.Create(
+  'UpdateProfile',
+  {
+    scope: ['users', 'profile'],
+    version: 2,
+    schema: { params: v.object({ name: v.string() }) }
+  },
+  async (ctx, params) => ({ userId: ctx.userId, name: params.name })
+)
 
-// RPCHttpRouteDoc - Route documentation
-interface RPCHttpRouteDoc {
-  path: string
-  method: 'post'
-  jsonSchema: {
-    body?: object
-    response?: object
+// Build app
+const builder = new ExpressRPCAppBuilder({
+  pathPrefix: '/rpc',
+  onRequestStart: (req) => console.log(`→ ${req.method} ${req.path}`),
+  onRequestEnd: (req, res) => console.log(`← ${res.statusCode}`),
+  onSuccess: (proc) => console.log(`✓ ${proc.name}`),
+  error: (proc, req, res, err) => {
+    console.error(`✗ ${proc.name}:`, err.message)
+    res.status(500).json({ error: err.message })
   }
-}
-```
+})
 
-## HTTP Method
+builder
+  .register(PublicRPC, () => ({ source: 'public' as const }))
+  .register(AuthRPC, (req) => ({
+    source: 'auth' as const,
+    userId: req.headers['x-user-id'] as string || 'anonymous'
+  }))
 
-All RPC routes use **POST** method only. GET requests to RPC paths return 404.
+const app = builder.build()
 
-```bash
-# Works
-curl -X POST http://localhost:3000/rpc/users/get/1 \
-  -H "Content-Type: application/json" \
-  -d '{"id": "123"}'
+// 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
 
-# Returns 404
-curl http://localhost:3000/rpc/users/get/1
+console.log('Routes:', builder.docs.map(d => d.path))
+app.listen(3000)
 ```