ts-procedures 1.1.1 → 2.0.0

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

@@ -0,0 +1,321 @@
+# Express RPC Integration
+
+RPC-style HTTP integration for `ts-procedures` using Express. Creates POST routes at `/rpc/{name}/{version}` paths with automatic JSON schema documentation.
+
+## Installation
+
+```bash
+npm install ts-procedures express
+```
+
+## Import
+
+```typescript
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+```
+
+## Quick Start
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { ExpressRPCAppBuilder, RPCConfig } from 'ts-procedures/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>()
+
+// Define procedures
+RPC.Create(
+  'GetUser',
+  {
+    name: ['users', 'get'],
+    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 Express app
+const builder = new ExpressRPCAppBuilder()
+  .register(RPC, (req) => ({ userId: req.headers['x-user-id'] as string }))
+  .build()
+
+// Start the server
+builder.listen(3000, () => {
+  console.log('RPC server running on http://localhost:3000')
+})
+
+// Route created: POST /rpc/users/get/1
+```
+
+## API Reference
+
+### `ExpressRPCAppBuilder`
+
+Builder class for creating an Express application with RPC routes.
+
+#### Constructor
+
+```typescript
+new ExpressRPCAppBuilder(config?: {
+  app?: express.Express
+  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. |
+
+#### Methods
+
+##### `register<C>(factory, contextResolver): this`
+
+Registers a procedure factory with its context resolver.
+
+```typescript
+builder.register(
+  RPC,                              // Procedure factory
+  (req) => ({ userId: req.user.id }) // Context resolver
+)
+```
+
+- **factory**: The procedure factory created by `Procedures<Context, RPCConfig>()`
+- **contextResolver**: Synchronous function `(req: express.Request) => Context`
+- **Returns**: `this` for method chaining
+
+##### `build(): express.Application`
+
+Builds and returns the Express application with all registered RPC routes.
+
+```typescript
+const app = builder.build()
+app.listen(3000)
+```
+
+#### Properties
+
+##### `app: express.Express`
+
+The underlying Express application instance.
+
+##### `docs: RPCHttpRouteDoc[]`
+
+Array of route documentation objects, populated after `build()` is called.
+
+```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
+  }
+}
+```
+
+### `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}`:
+
+| 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` |
+
+- 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:
+
+```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' }))
+
+// Define authenticated procedures
+AuthRPC.Create('GetProfile', { name: ['users', 'profile'], version: 1 }, async (ctx) => ({
+  userId: ctx.userId,
+}))
+
+// Build with different context resolvers
+const app = new ExpressRPCAppBuilder()
+  .register(PublicRPC, () => ({ source: 'public' }))
+  .register(AuthRPC, (req) => ({
+    source: 'auth',
+    userId: req.headers['x-user-id'] as string,
+  }))
+  .build()
+```
+
+## Lifecycle Hooks
+
+```typescript
+const app = new ExpressRPCAppBuilder({
+  onRequestStart: (req) => {
+    console.log(`[${req.method}] ${req.path}`)
+  },
+
+  onRequestEnd: (req, res) => {
+    console.log(`Response: ${res.statusCode}`)
+  },
+
+  onSuccess: (procedure, req, res) => {
+    console.log(`Procedure ${procedure.name} succeeded`)
+  },
+})
+```
+
+**Execution order:** `onRequestStart` → handler → `onSuccess` → `onRequestEnd`
+
+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' })
+    }
+  },
+})
+```
+
+### Default Error Handling
+
+Without a custom error handler, errors return a JSON response with the error message:
+
+```json
+{ "error": "Error message here" }
+```
+
+## Route Documentation
+
+Access generated documentation after building:
+
+```typescript
+const builder = new ExpressRPCAppBuilder()
+builder.register(RPC, contextResolver)
+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' } } }
+//     }
+//   }
+// ]
+```
+
+Use `docs` to generate OpenAPI specs, API documentation, or client SDKs.
+
+## Using an Existing Express App
+
+```typescript
+import express from 'express'
+
+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, contextResolver)
+  .build()
+
+// Add other routes
+app.get('/health', (req, res) => res.json({ status: 'ok' }))
+
+app.listen(3000)
+```
+
+**Important:** When providing your own Express app, you must set up middleware like `express.json()` yourself.
+
+## Types
+
+```typescript
+import type { RPCConfig, RPCHttpRouteDoc } from 'ts-procedures/express-rpc'
+
+// RPCConfig - Required config shape for procedures
+interface RPCConfig {
+  name: string | string[]
+  version: number
+}
+
+// RPCHttpRouteDoc - Route documentation
+interface RPCHttpRouteDoc {
+  path: string
+  method: 'post'
+  jsonSchema: {
+    body?: object
+    response?: object
+  }
+}
+```
+
+## HTTP Method
+
+All RPC routes use **POST** method only. GET requests to RPC paths return 404.
+
+```bash
+# Works
+curl -X POST http://localhost:3000/rpc/users/get/1 \
+  -H "Content-Type: application/json" \
+  -d '{"id": "123"}'
+
+# Returns 404
+curl http://localhost:3000/rpc/users/get/1
+```