ts-procedures 5.4.0 → 5.4.1

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

@@ -1,281 +0,0 @@
-# ExpressRPCAppBuilder
-
-Express.js integration for `ts-procedures` that creates type-safe RPC endpoints as POST routes.
-
-## Installation
-
-```bash
-npm install ts-procedures express
-```
-
-## Quick Start
-
-```typescript
-import express from 'express'
-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 }
-
-// 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 Express app
-const builder = new ExpressRPCAppBuilder({ pathPrefix: '/rpc' })
-  .register(RPC, (req) => ({
-    userId: req.headers['x-user-id'] as string
-  }))
-
-const app = builder.build()
-app.listen(3000)
-
-// POST /rpc/users/profile/get-user/1 → { id: "123", name: "John Doe" }
-```
-
-## Configuration
-
-```typescript
-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` | 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                                 |
-
-## Context Resolution
-
-The context resolver receives the Express `Request` object:
-
-```typescript
-builder.register(RPC, (req: express.Request) => ({
-  userId: req.headers['x-user-id'] as string,
-  sessionId: req.cookies?.sessionId,
-  ip: req.ip
-}))
-
-// Async context resolution
-builder.register(RPC, async (req) => {
-  const token = req.headers.authorization?.replace('Bearer ', '')
-  const user = await verifyToken(token)
-  return { userId: user.id, roles: user.roles }
-})
-```
-
-## Abort Signal
-
-`ExpressRPCAppBuilder` provides a lazy `AbortSignal` on `ctx.signal`. The underlying `AbortController` and `req.on('close')` listener are only created when `ctx.signal` is first accessed, so handlers that don't use it pay no overhead.
-
-The signal aborts when the client disconnects before the response finishes (premature close). Normal response completion does not trigger an abort.
-
-```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, request, response, and error:
-
-```typescript
-const builder = new ExpressRPCAppBuilder({
-  onError: (procedure, req, res, error) => {
-    console.error(`Error in ${procedure.name}:`, error)
-
-    if (error instanceof ValidationError) {
-      res.status(400).json({ error: error.message, code: 'VALIDATION_ERROR' })
-      return
-    }
-
-    if (error instanceof AuthError) {
-      res.status(401).json({ error: 'Unauthorized', code: 'AUTH_ERROR' })
-      return
-    }
-
-    res.status(500).json({ error: 'Internal server error' })
-  }
-})
-```
-
-**Default error handling:** Returns `{ error: message }` with status 500.
-
-## Using Existing Express App
-
-When providing an existing Express app, **you must set up JSON parsing middleware**:
-
-```typescript
-const app = express()
-app.use(express.json())  // Required!
-app.use(cors())
-app.use(helmet())
-
-const builder = new ExpressRPCAppBuilder({ app })
-  .register(RPC, contextResolver)
-
-builder.build()  // Adds RPC routes to existing app
-```
-
-When no `app` is provided, `express.json()` middleware is added automatically.
-
-## API Reference
-
-### Constructor
-
-```typescript
-new ExpressRPCAppBuilder(config?: ExpressRPCAppBuilderConfig)
-```
-
-### Methods
-
-| 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 |
-
-### Static Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `makeRPCHttpRoutePath` | `static makeRPCHttpRoutePath({ config, prefix }): string` | Generate route path with custom prefix |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `app` | `express.Express` | The Express application instance |
-| `docs` | `RPCHttpRouteDoc[]` | Route documentation (after `build()`) |
-| `config` | `ExpressRPCAppBuilderConfig` | The configuration object |
-
-## TypeScript Types
-
-```typescript
-import {
-  ExpressRPCAppBuilder,
-  ExpressRPCAppBuilderConfig,
-  RPCConfig,
-  RPCHttpRouteDoc
-} from 'ts-procedures/express-rpc'
-```
-
-## Full Example
-
-```typescript
-import express from 'express'
-import { Procedures } from 'ts-procedures'
-import { ExpressRPCAppBuilder, RPCConfig } from 'ts-procedures/express-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 ExpressRPCAppBuilder({
-  pathPrefix: '/rpc',
-  onRequestStart: (req) => console.log(`→ ${req.method} ${req.path}`),
-  onRequestEnd: (req, res) => console.log(`← ${res.statusCode}`),
-  onSuccess: (proc) => console.log(`✓ ${proc.name}`),
-  onError: (proc, req, res, err) => {
-    console.error(`✗ ${proc.name}:`, err.message)
-    res.status(500).json({ error: err.message })
-  }
-})
-
-builder
-  .register(PublicRPC, () => ({ source: 'public' as const }))
-  .register(AuthRPC, (req) => ({
-    source: 'auth' as const,
-    userId: req.headers['x-user-id'] as string || '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))
-app.listen(3000)
-```