ts-procedures 5.7.2 → 5.9.0

package/src/implementations/http/README.md

@@ -0,0 +1,324 @@
+# HTTP Implementations
+
+HTTP implementation builders for `ts-procedures` that create type-safe, versioned endpoints with automatic path generation, schema-based validation, and route documentation.
+
+## Available Implementations
+
+### RPC (Request/Response)
+
+For procedures created with `Create()` - standard request/response pattern using POST.
+
+| Framework | Package | Description |
+|-----------|---------|-------------|
+| [Express RPC](./express-rpc/README.md) | `express-rpc` | Express.js integration |
+| [Hono RPC](./hono-rpc/README.md) | `hono-rpc` | Hono integration (Bun, Deno, Cloudflare Workers, Node.js) |
+
+### Streaming
+
+For procedures created with `CreateStream()` - server-sent events and streaming responses.
+
+| Framework | Package | Description |
+|-----------|---------|-------------|
+| [Hono Stream](./hono-stream/README.md) | `hono-stream` | SSE and text streaming for async generators |
+
+### API (REST-style)
+
+For procedures using `schema.input` — per-channel input validation with standard HTTP methods.
+
+| Framework | Package | Description |
+|-----------|---------|-------------|
+| [Hono API](./hono-api/) | `hono-api` | REST-style routing by HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD) |
+
+## Procedure Types
+
+| Type | Created With | Handler Return | HTTP Methods | Use Case |
+|------|--------------|----------------|--------------|----------|
+| RPC | `Create()` | `Promise<T>` | POST | Standard request/response |
+| Stream | `CreateStream()` | `AsyncGenerator<T>` | GET, POST | Real-time updates, SSE |
+| API | `Create()` | `Promise<T>` | GET, POST, PUT, DELETE, PATCH, HEAD | REST-style endpoints with per-channel input |
+
+## Core Concepts
+
+### Config Interface
+
+All HTTP implementations use a shared configuration interface:
+
+```typescript
+interface RPCConfig {
+  scope: string | string[]  // Route path segment(s)
+  version: number           // API version number
+}
+```
+
+#### APIConfig (REST-style)
+
+```typescript
+interface APIConfig {
+  path: string              // Route path with Hono params (e.g., '/users/:id')
+  method: HttpMethod        // 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+  successStatus?: number    // Default: POST→201, DELETE→204, others→200
+}
+```
+
+API routes use developer-defined paths — no auto-generation from scope/version.
+
+### Path Generation
+
+Routes are generated using kebab-case conversion:
+
+```
+/{pathPrefix}/{scope...}/{procedureName}/{version}
+```
+
+**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
+
+The `factoryContext` parameter supports three patterns:
+
+```typescript
+// 1. Static object
+builder.register(Factory, { userId: 'static-123' })
+
+// 2. Sync function
+builder.register(Factory, (c) => ({
+  userId: c.req.header('x-user-id')
+}))
+
+// 3. Async function
+builder.register(Factory, async (c) => {
+  const user = await validateToken(c.req.header('authorization'))
+  return { userId: user.id }
+})
+```
+
+### Abort Signal
+
+All HTTP implementations automatically inject an `AbortSignal` into the handler context as `ctx.signal`. This signal aborts when the client disconnects, enabling handlers to cancel in-flight work (fetch calls, database queries, etc.).
+
+| Framework | Signal Source | Behavior |
+|-----------|-------------|----------|
+| Hono RPC | `c.req.raw.signal` | Web standard Request signal |
+| Hono Stream | `c.req.raw.signal` | Combined with internal stream AbortController via `AbortSignal.any()` |
+| Express RPC | Lazy `AbortController` | Created on first `ctx.signal` access, wired to `req.on('close')` |
+
+For streaming procedures, `signal.reason` is `'stream-completed'` on normal completion, allowing handlers to distinguish from client disconnection.
+
+### Lifecycle Hooks
+
+**RPC Implementations:**
+
+```
+onRequestStart → handler → onSuccess → onRequestEnd
+                    ↓
+              (on error)
+                    ↓
+              onError handler
+                    ↓
+              onRequestEnd
+```
+
+**Stream Implementations:**
+
+```
+onRequestStart → onStreamStart → [yields...] → onStreamEnd → onRequestEnd
+                      ↓
+                 (on error)
+                      ↓
+               error in stream
+                      ↓
+                onStreamEnd
+```
+
+| Hook | Available In | Trigger |
+|------|--------------|---------|
+| `onRequestStart` | Both | Before route handler |
+| `onRequestEnd` | Both | After response sent |
+| `onSuccess` | RPC, API | After successful handler |
+| `onError` | RPC, API | On handler error |
+| `onStreamStart` | Stream | Before first yield |
+| `onStreamEnd` | Stream | After stream completes |
+| `onPreStreamError` | Stream | On pre-stream error (validation, auth) |
+| `onMidStreamError` | Stream | On mid-stream error (generator throws) |
+
+### Route Documentation
+
+Each registered procedure generates documentation accessible via `builder.docs`.
+
+**RPC Documentation (`RPCHttpRouteDoc`):**
+
+```typescript
+interface RPCHttpRouteDoc {
+  name: string
+  path: string
+  method: 'post'
+  scope: string | string[]
+  version: number
+  jsonSchema: {
+    body?: object      // From schema.params
+    response?: object  // From schema.returnType
+  }
+}
+```
+
+**Stream Documentation (`StreamHttpRouteDoc`):**
+
+```typescript
+interface StreamHttpRouteDoc {
+  name: string
+  path: string
+  methods: ('get' | 'post')[]
+  streamMode: 'sse' | 'text'
+  scope: string | string[]
+  version: number
+  jsonSchema: {
+    params?: object     // From schema.params
+    yieldType?: object  // From schema.yieldType
+    returnType?: object // From schema.returnType
+  }
+}
+```
+
+**API Documentation (`APIHttpRouteDoc`):**
+
+```typescript
+interface APIHttpRouteDoc {
+  name: string
+  path: string
+  method: HttpMethod
+  fullPath: string
+  successStatus?: number
+  jsonSchema: {
+    pathParams?: object    // From schema.input.pathParams
+    query?: object         // From schema.input.query
+    body?: object          // From schema.input.body
+    headers?: object       // From schema.input.headers
+    response?: object      // From schema.returnType
+  }
+}
+```
+
+### Builder Pattern
+
+All implementations follow the same builder pattern:
+
+```typescript
+const builder = new AppBuilder(config)
+  .register(PublicFactory, publicContextResolver)
+  .register(ProtectedFactory, protectedContextResolver)
+
+const app = builder.build()
+const docs = builder.docs
+```
+
+**Note:** `HonoAPIAppBuilder.build()` is async (resolves query parser on first call).
+
+**Key methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `register(factory, context, options?)` | `this` | Register a procedure factory |
+| `build()` | Framework app | Create routes and return the application |
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `app` | Framework app | The underlying framework application |
+| `docs` | Route doc array | Route documentation (populated after `build()`) |
+
+### DocRegistry
+
+Composes route documentation from multiple builders into a typed envelope, replacing manual `/docs` endpoint assembly.
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+  errors: DocRegistry.defaultErrors(),
+})
+  .from(rpcBuilder)
+  .from(apiBuilder)
+  .from(streamBuilder)
+
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+- `from()` stores a reference — routes are read lazily at `toJSON()` time
+- `toJSON()` supports optional `filter` and `transform` options
+- `defaultErrors()` returns error schemas for all 4 procedure error types
+- All builders satisfy the `DocSource` interface (`{ readonly docs: AnyHttpRouteDoc[] }`)
+
+### Client Code Generation
+
+Generate type-safe client SDKs from your DocRegistry output. The codegen reads the `DocEnvelope` JSON and produces per-scope TypeScript files with typed params, response types, and callable functions.
+
+**Requirements:** All routes need a `scope` field for file grouping. RPC and Stream routes already have `scope` via `RPCConfig`. API routes support optional `scope` on `APIConfig`:
+
+```typescript
+const apiBuilder = new HonoAPIAppBuilder()
+apiBuilder.register(factory, (c) => ctx, {
+  scope: 'users', // Used for codegen file grouping
+})
+```
+
+**Route type handling in generated code:**
+
+| Builder | Route Kind | Params Source | Generated Callable |
+|---------|-----------|---------------|-------------------|
+| HonoRPCAppBuilder | `rpc` | `jsonSchema.body` → flat params | `client.call()` |
+| HonoAPIAppBuilder | `api` | `jsonSchema.pathParams/query/body/headers` → structured params | `client.call()` |
+| HonoStreamAppBuilder | `stream` | `jsonSchema.params` → flat params | `client.stream()` |
+
+**SSE return values:** Stream procedures that return a value have it sent as `event: 'return'` SSE message. The client's `TypedStream.result` promise resolves with this value.
+
+**SSE yieldType unwrapping:** Codegen detects the SSE envelope in `yieldType` and uses the inner `data` schema for the generated `Yield` type.
+
+**Kind discriminant:** All route docs include a `kind` field (`'rpc' | 'api' | 'stream'`) for reliable type narrowing in the codegen pipeline and consumer code.
+
+**Namespace types:** Use `--namespace-types` to wrap generated types in nested TS namespaces (`Scope.Route.Params`) instead of flat prefixed exports (`RouteParams`).
+
+**ajsc options:** `--enum-style`, `--depluralize`, `--array-item-naming`, `--uncountable-words` are passed through to the ajsc TypescriptConverter for JSON Schema → TypeScript conversion.
+
+**Self-contained mode:** Use `--self-contained` to emit `_types.ts` (all client type definitions) and `_client.ts` (runtime: `createClient`, `createFetchAdapter`, hooks, errors) into the output directory. All scope files and `index.ts` will import from `./_types` instead of `ts-procedures/client`, so consumers have no runtime dependency on `ts-procedures`. With this flag, `ts-procedures` can be a devDependency only.
+
+## 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 |
+| Streaming support | Not yet | `hono-stream` |
+
+## TypeScript Types
+
+```typescript
+import { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode } from 'ts-procedures/implementations/types'
+import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
+
+// Client Runtime
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
+
+// Code Generation (build-time only)
+import { generateClient } from 'ts-procedures/codegen'
+```

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

@@ -0,0 +1,281 @@
+# 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)
+```