ts-procedures 5.7.2 → 5.9.0

package/docs/core.md

@@ -0,0 +1,473 @@
+[Home](../README.md) | **Core** | [Streaming](./streaming.md) | [HTTP Integrations](./http-integrations.md) | [Client & Codegen](./client-and-codegen.md) | [AI Agent Setup](./ai-agent-setup.md)
+
+# Core Procedures
+
+ts-procedures creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and procedure documentation/configuration.
+
+## Procedures Factory
+
+The `Procedures()` function creates a factory for defining procedures. It accepts two generic type parameters:
+
+```typescript
+Procedures<TContext, TExtendedConfig>(builder?: {
+    onCreate?: (procedure: TProcedureRegistration<TContext, TExtendedConfig>) => void
+})
+```
+
+| Parameter | Description                                                                |
+|-----------|----------------------------------------------------------------------------|
+| `TContext` | The base context type passed to all handlers as the first parameter        |
+| `TExtendedConfig` | Additional configuration properties for all procedures `config` properties |
+| `builder.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
+
+## Create Function
+
+The `Create` function defines individual procedures:
+
+```typescript
+Create(name, config, handler)
+```
+
+**Returns:**
+- `{ [name]: handler }` - Named export for the handler
+- `procedure` - Generic reference to the handler
+- `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
+
+## Structured Input with schema.input
+
+For HTTP APIs and other multi-channel transports, `schema.input` provides per-channel type safety. Each key is an independently validated input channel:
+
+```typescript
+const { Create } = Procedures<AppContext, APIConfig>()
+
+const { UpdateUser } = Create(
+  'UpdateUser',
+  {
+    path: '/users/:id',
+    method: 'put',
+    schema: {
+      input: {
+        pathParams: Type.Object({ id: Type.String() }),
+        query: Type.Object({ notify: Type.Optional(Type.Boolean()) }),
+        body: Type.Object({ name: Type.String(), email: Type.String() }),
+      },
+      returnType: Type.Object({ ok: Type.Boolean() }),
+    },
+  },
+  async (ctx, { pathParams, query, body }) => {
+    // Each channel is independently typed and validated
+    await updateUser(pathParams.id, body)
+    if (query.notify) await sendNotification(pathParams.id)
+    return { ok: true }
+  }
+)
+```
+
+**Rules:**
+- `schema.input` and `schema.params` are **mutually exclusive** — defining both throws `ProcedureRegistrationError`
+- Each channel is validated independently with per-channel error messages
+- Works with both `Create` and `CreateStream`
+
+## CreateStream Function
+
+The `CreateStream` function defines streaming procedures that yield values over time using async generators:
+
+```typescript
+CreateStream(name, config, handler)
+```
+
+**Config Options:**
+- `schema.params` - Input parameter schema (validated at runtime)
+- `schema.yieldType` - Schema for each yielded value (validated if `validateYields: true`)
+- `schema.returnType` - Schema for final return value (documentation only)
+- `validateYields` - Enable runtime validation of yielded values (default: `false`)
+
+**Handler Signature:**
+```typescript
+async function* (ctx, params) => AsyncGenerator<TYield, TReturn | void>
+```
+
+**Context Extensions (all handlers):**
+- `ctx.error(message, meta?)` - Create a ProcedureError
+- `ctx.signal?` - AbortSignal for cancellation support (optional for `Create`, always present for `CreateStream`)
+
+When using the built-in HTTP implementations (Hono, Express), `ctx.signal` is automatically injected from the HTTP request, so handlers can detect client disconnection. For direct usage without a server, `signal` is `undefined` unless you pass one in context.
+
+**Returns:**
+- `{ [name]: handler }` - Named generator export
+- `procedure` - Generic reference to the generator
+- `info` - Procedure meta with `isStream: true`
+
+For detailed streaming documentation (yield validation, abort signals, SSE integration), see [Streaming Procedures](./streaming.md).
+
+## Using Generics
+
+### Base Context
+
+Define a shared context type for all procedures in your application:
+
+```typescript
+interface AppContext {
+  authToken: string
+  requestId: string
+  logger: Logger
+}
+
+const { Create } = Procedures<AppContext>()
+
+const { SecureEndpoint } = Create(
+  'SecureEndpoint',
+  {},
+  async (ctx, params) => {
+    // ctx.authToken is typed as string
+    // ctx.requestId is typed as string
+    // ctx.logger is typed as Logger
+    return { token: ctx.authToken }
+  },
+)
+
+// When calling, you must provide the context
+await SecureEndpoint({ authToken: 'abc', requestId: '123', logger: myLogger }, {})
+```
+
+### Extended Configuration
+
+Add custom properties to all procedure configs:
+
+```typescript
+interface ExtendedConfig {
+  permissions: string[]
+  rateLimit?: number
+  cacheTTL?: number
+}
+
+const { Create } = Procedures<AppContext, ExtendedConfig>()
+
+const { AdminOnly } = Create(
+  'AdminOnly',
+  {
+    permissions: ['admin'],  // Required by ExtendedConfig
+    rateLimit: 100,          // Optional
+    description: 'Admin-only endpoint',
+  },
+  async (ctx, params) => {
+    return { admin: true }
+  },
+)
+
+// Access extended config via info
+console.log(AdminOnly.info.permissions) // ['admin']
+```
+
+### Combined Example
+
+```typescript
+interface CustomContext {
+  authToken: string
+  tenantId: string
+}
+
+interface ExtendedConfig {
+  requiresAuth: boolean
+  auditLog?: boolean
+}
+
+const { Create, getProcedures } = Procedures<CustomContext, ExtendedConfig>({
+  onCreate: (procedure) => {
+    // Register with your framework
+    console.log(`Registered: ${procedure.name}`)
+    console.log(`Requires Auth: ${procedure.config.requiresAuth}`)
+  },
+})
+
+const { CreateUser } = Create(
+  'CreateUser',
+  {
+    requiresAuth: true,
+    auditLog: true,
+    description: 'Creates a new user',
+    schema: {
+      params: Type.Object({
+        email: Type.String(),
+        name: Type.String(),
+      }),
+      returnType: Type.Object({ id: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    // Both context and params are fully typed
+    return { id: 'user-123' }
+  },
+)
+```
+
+## Schema Validation
+
+ts-procedures supports two schema libraries — **TypeBox** (recommended) and **Suretype**. The library is auto-detected from the schema object. Both work identically at runtime; choose whichever you prefer:
+
+```typescript
+// TypeBox
+import { Type } from 'typebox'
+schema: { params: Type.Object({ title: Type.String() }) }
+
+// Suretype
+import { v } from 'suretype'
+schema: { params: v.object({ title: v.string().required() }) }
+```
+
+### Validation Behavior
+
+AJV is configured with:
+- `allErrors: true` - Report all validation errors
+- `coerceTypes: true` - Automatically coerce types when possible
+- `removeAdditional: true` - Strip properties not in schema
+
+**Note:** `schema.params` is validated at runtime. `schema.returnType` is for documentation/introspection only.
+
+## Error Handling
+
+### Using ctx.error()
+
+The `error()` function is injected into both hooks and handlers:
+
+```typescript
+Create(
+  'GetResource',
+  {},
+  async (ctx, params) => {
+    const resource = await db.find(params.id)
+    if (!resource) {
+      throw ctx.error(404, 'Resource not found', { id: params.id })
+    }
+    return resource
+  },
+)
+```
+
+### Error Classes
+
+| Error Class | Trigger |
+|-------------|---------|
+| ProcedureError | `ctx.error()` in handlers |
+| ProcedureValidationError | Schema validation failure (params) |
+| ProcedureYieldValidationError | Yield validation failure (streaming with `validateYields: true`) |
+| ProcedureRegistrationError | Invalid schema at registration |
+
+### Error Properties
+
+```typescript
+try {
+  await MyProcedure(ctx, params)
+} catch (e) {
+  if (e instanceof ProcedureError) {
+    console.log(e.procedureName) // 'MyProcedure'
+    console.log(e.message)       // 'Resource not found'
+    console.log(e.meta)          // { id: '123' }
+  }
+}
+```
+
+## Abort Signal
+
+For regular procedures, `ctx.signal` is available when the server implementation provides it. The built-in HTTP integrations (Hono RPC, Express RPC) inject the request's abort signal automatically:
+
+```typescript
+const { Create } = Procedures<{ signal: AbortSignal }>()
+
+const { LongQuery } = Create(
+  'LongQuery',
+  {},
+  async (ctx, params) => {
+    // Pass signal to downstream operations
+    const result = await fetch('https://api.example.com/data', {
+      signal: ctx.signal,
+    })
+    return result.json()
+  },
+)
+```
+
+When using the Hono or Express implementations, `ctx.signal` aborts when the client disconnects, automatically cancelling in-flight `fetch()` calls, database queries, or any other signal-aware operation.
+
+For streaming abort signal behavior (including `signal.reason` and consumer break detection), see [Streaming Procedures](./streaming.md#abort-signal-integration).
+
+## Framework Integration
+
+### onCreate Callback
+
+Register procedures with your framework (Express, Fastify, etc.):
+
+```typescript
+import express from 'express'
+
+const app = express()
+const routes: Map<string, Function> = new Map()
+
+const { Create } = Procedures<{ req: Request; res: Response }>({
+  onCreate: ({ name, handler, config }) => {
+    // Register as Express route
+    app.post(`/rpc/${name}`, async (req, res) => {
+      try {
+        const result = await handler({ req, res }, req.body)
+        res.json(result)
+      } catch (e) {
+        if (e instanceof ProcedureError) {
+          res.status(500).json({ error: e.message })
+        } else {
+          res.status(500).json({ error: 'Internal error' })
+        }
+      }
+    })
+  },
+})
+
+// Procedures are automatically registered as /rpc/GetUser, /rpc/CreateUser, etc.
+```
+
+For built-in HTTP framework integrations (Express RPC, Hono RPC, Hono API, Hono Stream), see [HTTP Integrations](./http-integrations.md).
+
+### Introspection with getProcedures()
+
+Access all registered procedures for documentation or routing:
+
+```typescript
+const { Create, getProcedures } = Procedures()
+
+Create('GetUser', { schema: { params: Type.Object({ id: Type.String() }) } }, async () => {})
+Create('ListUsers', { schema: { params: Type.Object({}) } }, async () => {})
+
+// Get all registered procedures
+const procedures = getProcedures()
+
+// Generate OpenAPI spec
+for (const config of procedures) {
+  console.log(`${config.name}:`, config.schema)
+}
+```
+
+## Testing
+
+Procedures return handlers that can be called directly in tests:
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+interface MyCustomContext {
+  userId?: string
+  userName?: string
+}
+
+const { Create } = Procedures<MyCustomContext>()
+
+const { GetUser, info } = Create(
+  'GetUser',
+  {
+    schema: {
+      params: Type.Object({ hideName: Type.Optional(Type.Boolean()) }),
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    if (!params.userName || !ctx.userId) {
+      throw ctx.error('User is not authenticated')
+    }
+    
+    return { 
+      id: params.userId, 
+      name: params?.hideName ? '*******' : params.userName 
+    }
+  },
+)
+
+describe('GetUser', () => {
+  test('returns user', async () => {
+    const result = await GetUser({userId:'123',userName:'Ray'}, { hideName: false })
+    expect(result).toEqual({ id: '123', name: 'Ray' })
+  })
+  
+  test('hides user name', async () => {
+    const result = await GetUser({userId:'123',userName:'Ray'}, { hideName: true })
+    expect(result).toEqual({ id: '123', name: '*******' })
+  })
+
+  test('validates params', async () => {
+    await expect(GetUser({}, {})).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('has correct schema', () => {
+    expect(info.schema.params).toEqual({
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    })
+  })
+})
+```
+
+## API Reference
+
+### Procedures(builder?)
+
+Creates a procedure factory.
+
+**Parameters:**
+- `builder.onCreate` - Callback invoked when each procedure is registered
+
+**Returns:**
+- `Create` - Function to define procedures
+- `getProcedures()` - Returns `Array` of all registered procedures
+
+### Create(name, config, handler)
+
+Defines a procedure.
+
+**Parameters:**
+- `name` - Unique procedure name (becomes named export)
+- `config.description` - Optional description
+- `config.schema.params` - Suretype or TypeBox schema for params (validated at runtime)
+- `config.schema.returnType` - Suretype or TypeBox schema for return returnType (documentation only)
+- Additional properties from `TExtendedConfig`
+- `handler` - Async function `(ctx, params) => Promise<returnType>`
+
+**Returns:**
+- `{ [name]: handler }` - Named handler export
+- `procedure` - Generic handler reference
+- `info` - Procedure metareturnType
+
+### Type Exports
+
+```typescript
+import {
+  // Core
+  Procedures,
+
+  // Errors
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureRegistrationError,
+  ProcedureYieldValidationError,  // For streaming yield validation
+
+  // Types
+  TLocalContext,
+  TStreamContext,               // Streaming context (AbortSignal always present)
+  TProcedureRegistration,
+  TStreamProcedureRegistration, // Streaming procedure registration
+  TNoContextProvided,
+
+  // Schema utilities
+  extractJsonSchema,
+  schemaParser,
+  isTypeboxSchema,
+  isSuretypeSchema,
+
+  // Schema types
+  TJSONSchema,
+  TSchemaLib,
+  TSchemaLibGenerator,          // AsyncGenerator type utility
+  TSchemaParsed,
+  TSchemaValidationError,
+  Prettify,
+} from 'ts-procedures'
+```

package/docs/http-integrations.md

@@ -0,0 +1,183 @@
+[Home](../README.md) | [Core](./core.md) | [Streaming](./streaming.md) | **HTTP Integrations** | [Client & Codegen](./client-and-codegen.md) | [AI Agent Setup](./ai-agent-setup.md)
+
+# HTTP Framework Integrations
+
+ts-procedures includes built-in HTTP builders for Express and Hono that handle routing, context resolution, lifecycle hooks, abort signals, and automatic route documentation. Each builder uses the `onCreate` callback internally to register procedures as HTTP endpoints.
+
+For a full cross-framework comparison (config interfaces, path generation, context resolution, abort signal, lifecycle hooks, route documentation), see the [HTTP implementations overview](../src/implementations/http/README.md).
+
+## Integrations at a Glance
+
+| Integration | Export | Style | Guide |
+|-------------|--------|-------|-------|
+| Express RPC | `ts-procedures/express-rpc` | RPC (POST routes) | [README](../src/implementations/http/express-rpc/README.md) |
+| Hono RPC | `ts-procedures/hono-rpc` | RPC (POST routes) | [README](../src/implementations/http/hono-rpc/README.md) |
+| Hono Stream | `ts-procedures/hono-stream` | SSE/text streaming | [README](../src/implementations/http/hono-stream/README.md) |
+| Hono API | `ts-procedures/hono-api` | REST (method-based) | [Below](#hono-api-integration) |
+
+## Express RPC
+
+RPC-style HTTP integration for Express that creates POST routes at `/rpc/{name}/{version}` paths with automatic JSON schema documentation.
+
+```typescript
+import { ExpressRPCAppBuilder, RPCConfig } from 'ts-procedures/express-rpc'
+
+const RPC = Procedures<AppContext, RPCConfig>()
+
+RPC.Create(
+  'GetUser',
+  {
+    name: ['users', 'get'],
+    version: 1,
+    schema: {
+      params: Type.Object({ id: Type.String() }),
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    return { id: params.id, name: 'John Doe' }
+  }
+)
+
+const app = new ExpressRPCAppBuilder()
+  .register(RPC, (req) => ({ userId: req.headers['x-user-id'] as string }))
+  .build()
+
+app.listen(3000)
+// Route created: POST /rpc/users/get/1
+```
+
+See the [Express RPC Integration Guide](../src/implementations/http/express-rpc/README.md) for complete setup including lifecycle hooks, error handling, and route documentation.
+
+## Hono RPC
+
+RPC-style HTTP integration for Hono with the same routing pattern as Express RPC. Works with Bun, Deno, Cloudflare Workers, and Node.js.
+
+```typescript
+import { HonoRPCAppBuilder, RPCConfig } from 'ts-procedures/hono-rpc'
+
+const RPC = Procedures<AppContext, RPCConfig>()
+
+RPC.Create('GetUser', {
+  scope: ['users', 'profile'],
+  version: 1,
+  schema: { params: Type.Object({ id: Type.String() }) },
+}, async (ctx, params) => {
+  return { id: params.id, name: 'John Doe' }
+})
+
+const app = new HonoRPCAppBuilder({ pathPrefix: '/rpc' })
+  .register(RPC, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
+  .build()
+
+// POST /rpc/users/profile/get-user/1
+```
+
+See the [Hono RPC Integration Guide](../src/implementations/http/hono-rpc/README.md) for complete setup including context resolution, doc extension, abort signal, error handling, and runtime compatibility.
+
+## Hono Stream
+
+Streaming/SSE integration for Hono that supports both SSE and text streaming modes with yield validation, lifecycle hooks, and client disconnect detection.
+
+```typescript
+import { HonoStreamAppBuilder } from 'ts-procedures/hono-stream'
+
+const StreamRPC = Procedures<AppContext, RPCConfig>()
+
+StreamRPC.CreateStream('WatchNotifications', {
+  scope: ['user', 'notifications'],
+  version: 1,
+  schema: { yieldType: Type.Object({ id: Type.Number(), message: Type.String() }) },
+}, async function* (ctx) {
+  for (let i = 1; i <= 10; i++) {
+    yield { id: i, message: `Notification ${i}` }
+    await new Promise((r) => setTimeout(r, 1000))
+  }
+})
+
+const app = new HonoStreamAppBuilder()
+  .register(StreamRPC, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
+  .build()
+```
+
+See the [Hono Stream Integration Guide](../src/implementations/http/hono-stream/README.md) for complete setup including SSE/text modes, the `sse()` helper, validation, error handling, and migration notes.
+
+## Hono API Integration
+
+REST-style HTTP integration for Hono that routes by HTTP method with per-channel input validation via `schema.input`.
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+const API = Procedures<{ userId: string }, APIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+    },
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, { pathParams }) => {
+  return await fetchUser(pathParams.id)
+})
+
+API.Create('CreateUser', {
+  path: '/users',
+  method: 'post',
+  schema: {
+    input: {
+      body: Type.Object({ name: Type.String(), email: Type.String() }),
+    },
+  },
+}, async (ctx, { body }) => {
+  return await createUser(body)
+})
+
+const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
+  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
+  .build()
+
+// Routes:
+// GET  /api/users/:id  -> 200
+// POST /api/users      -> 201
+```
+
+## DocRegistry — Composing Docs from Multiple Builders
+
+Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope:
+
+```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, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
+
+The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
+
+## Type Exports
+
+```typescript
+// HTTP types
+import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
+
+// Hono API (REST-style)
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod, QueryParser } from 'ts-procedures/hono-api'
+```