ts-procedures 5.2.0 → 5.4.0

package/agent_config/claude-code/skills/guide/api-reference.md

@@ -0,0 +1,696 @@
+# ts-procedures API Reference
+
+## Imports
+
+```typescript
+// Core
+import { Procedures } from 'ts-procedures'
+import type {
+  TLocalContext,
+  TStreamContext,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+} from 'ts-procedures'
+
+// Errors
+import {
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureYieldValidationError,
+  ProcedureRegistrationError,
+} from 'ts-procedures'
+
+// Schema utilities
+import { extractJsonSchema } from 'ts-procedures'
+import { schemaParser } from 'ts-procedures'
+import { isTypeboxSchema } from 'ts-procedures'
+import type { TSchemaLib, TSchemaLibGenerator, TJSONSchema, TSchemaParsed, TSchemaValidationError } from 'ts-procedures'
+
+// Stack utilities
+import { captureDefinitionInfo, formatDefinitionInfo } from 'ts-procedures'
+import type { DefinitionLocation, DefinitionInfo } from 'ts-procedures'
+
+// HTTP types (types only, no runtime)
+import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
+
+// Express RPC
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+
+// Hono RPC
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+
+// Hono Streaming
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+
+// Hono API (REST-style)
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/hono-api'
+```
+
+---
+
+## Procedures\<TContext, TExtendedConfig\>(builder?)
+
+Factory function that creates a scoped procedure registration system.
+
+```typescript
+function Procedures<TContext = unknown, TExtendedConfig = unknown>(
+  builder?: {
+    onCreate?: (procedure: {
+      name: string
+      isStream?: boolean
+      handler: Function
+      config: { description?: string; schema?: object } & TExtendedConfig
+    }) => void
+  }
+): {
+  Create: CreateFunction
+  CreateStream: CreateStreamFunction
+  getProcedures(): Array<TProcedureRegistration | TStreamProcedureRegistration>
+  getProcedure(name: string): TProcedureRegistration | TStreamProcedureRegistration | undefined
+  removeProcedure(name: string): boolean
+  clear(): void
+}
+```
+
+### Parameters
+
+- `builder.onCreate` — Called each time a procedure is registered. Use for framework integration, route registration, or logging.
+
+### Return Value
+
+| Method | Description |
+|--------|-------------|
+| `Create(name, config, handler)` | Register a standard async procedure |
+| `CreateStream(name, config, handler)` | Register a streaming async generator procedure |
+| `getProcedures()` | Returns array of all registered procedure metadata |
+| `getProcedure(name)` | Returns single procedure by name, or `undefined` |
+| `removeProcedure(name)` | Removes procedure, returns `true` if found |
+| `clear()` | Removes all registered procedures |
+
+### Type Parameters
+
+- `TContext` — Base context type injected into every handler. Merged with `TLocalContext` (adds `error()` and optional `signal`).
+- `TExtendedConfig` — Additional config fields required on every procedure's config object (e.g., `RPCConfig` adds `scope` and `version`).
+
+---
+
+## Create\<TName, TParams, TReturnType\>(name, config, handler)
+
+Registers a standard async procedure.
+
+```typescript
+function Create<TName extends string, TParams, TReturnType>(
+  name: TName,
+  config: {
+    description?: string
+    schema?: {
+      params?: TParams      // TypeBox schema — validated at runtime
+      returnType?: TReturnType  // Documentation only — NOT validated
+    }
+  } & TExtendedConfig,
+  handler: (
+    ctx: TContext & TLocalContext & { isPrevalidated?: boolean },
+    params: TSchemaLib<TParams>
+  ) => Promise<TSchemaLib<TReturnType>>
+): {
+  [K in TName]: (ctx: TContext, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
+  procedure: (ctx: TContext, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
+  info: {
+    name: TName
+    description?: string
+    schema: { params?: TJSONSchema; returnType?: TJSONSchema }
+    validation?: { params?: (params: any) => { errors?: TSchemaValidationError[] } }
+  } & TExtendedConfig
+}
+```
+
+### Parameters
+
+- `name` — Unique procedure name. Becomes a dynamic property on the return object.
+- `config.description` — Human-readable description.
+- `config.schema.params` — Input schema. Validated at runtime using AJV.
+- `config.schema.returnType` — Return type schema. Documentation only.
+- `handler` — Async function `(ctx, params) => Promise<result>`.
+
+### Handler Context
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `...TContext` | varies | All base context fields |
+| `error(message, meta?)` | `Function` | Creates `ProcedureError` — throw this for business logic errors |
+| `signal?` | `AbortSignal` | Present when HTTP implementation injects it (Express/Hono do this automatically) |
+| `isPrevalidated?` | `boolean` | `true` when HTTP impl already validated params — skips AJV validation |
+
+### Return Value
+
+- `{ [name]: handler }` — Dynamically named property (e.g., `{ GetUser: fn }`)
+- `{ procedure: handler }` — Same handler under a fixed key
+- `{ info: metadata }` — Registration metadata with computed JSON schemas and validation functions
+
+### schema.input (Structured Multi-Channel Input)
+
+`schema.input` is an alternative to `schema.params` for multi-channel input. Mutually exclusive with `schema.params`.
+
+```typescript
+Create('UpdateUser', {
+  path: '/users/:id',
+  method: 'put',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+      body: Type.Object({ name: Type.String() }),
+    },
+    returnType: Type.Object({ ok: Type.Boolean() }),
+  },
+}, async (ctx, { pathParams, body }) => {
+  // Each channel independently typed via TInput generic
+  return { ok: true }
+})
+```
+
+- Each key in `input` is independently validated with per-channel error messages
+- `ProcedureRegistrationError` thrown at registration if both `params` and `input` defined
+- `TInput` generic inferred from `schema.input` — handler params type computed as `{ [K in keyof TInput]: TSchemaLib<TInput[K]> }`
+
+### Throws
+
+- `ProcedureRegistrationError` — If schema extraction/compilation fails, or duplicate name
+- `ProcedureValidationError` — At call time if params fail validation
+- `ProcedureError` — At call time if handler throws (wraps original error in `cause`)
+
+---
+
+## CreateStream\<TName, TParams, TYieldType, TReturnType\>(name, config, handler)
+
+Registers a streaming procedure (async generator).
+
+```typescript
+function CreateStream<TName extends string, TParams, TYieldType, TReturnType = void>(
+  name: TName,
+  config: {
+    description?: string
+    schema?: {
+      params?: TParams       // Validated at runtime
+      yieldType?: TYieldType // Validated per-yield only if validateYields: true
+      returnType?: TReturnType  // Documentation only
+    }
+    validateYields?: boolean  // Default: false
+  } & TExtendedConfig,
+  handler: (
+    ctx: TContext & TStreamContext & { isPrevalidated?: boolean },
+    params: TSchemaLib<TParams>
+  ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
+): {
+  [K in TName]: (ctx: TContext, params: TSchemaLib<TParams>) => AsyncGenerator<...>
+  procedure: (ctx: TContext, params: TSchemaLib<TParams>) => AsyncGenerator<...>
+  info: {
+    name: TName
+    isStream: true
+    description?: string
+    schema: { params?: TJSONSchema; yieldType?: TJSONSchema; returnType?: TJSONSchema }
+    validation?: {
+      params?: (params: any) => { errors?: TSchemaValidationError[] }
+      yield?: (value: any) => { errors?: TSchemaValidationError[] }
+    }
+  } & TExtendedConfig
+}
+```
+
+### Handler Context
+
+Same as Create, except:
+
+- `ctx.signal` — **Always present** (guaranteed `AbortSignal`)
+- On normal stream completion: `signal.reason === 'stream-completed'`
+- On client disconnect: `signal.aborted === true`, `signal.reason` is the abort reason
+
+### Signal Lifecycle
+
+```
+Stream starts    → signal.aborted = false
+Client aborts    → signal.aborted = true, reason = external reason
+Stream completes → signal.aborted = true, reason = 'stream-completed'
+```
+
+Handlers can distinguish normal completion from client disconnection by checking `signal.reason`.
+
+### Yield Validation
+
+When `validateYields: true`:
+- Each yielded value is validated against `schema.yieldType`
+- Failures throw `ProcedureYieldValidationError`
+- Default is `false` (no yield validation)
+
+---
+
+## Error Classes
+
+### ProcedureError
+
+Base error class for all procedure errors.
+
+```typescript
+class ProcedureError extends Error {
+  readonly procedureName: string
+  readonly message: string
+  readonly meta?: object
+  readonly cause?: unknown
+  readonly definedAt?: DefinitionLocation
+  readonly definitionStack?: string
+
+  constructor(procedureName: string, message: string, meta?: object, definitionInfo?: DefinitionInfo)
+  getDefinitionLocation(): string | undefined
+}
+```
+
+- Created via `ctx.error(message, meta?)` in handlers
+- Unhandled handler exceptions are wrapped: original error in `cause`
+- Stack trace enhanced with procedure definition location
+
+### ProcedureValidationError extends ProcedureError
+
+Thrown when params schema validation fails.
+
+```typescript
+class ProcedureValidationError extends ProcedureError {
+  readonly errors?: TSchemaValidationError[]
+  constructor(procedureName: string, message: string, errors?: TSchemaValidationError[], definitionInfo?: DefinitionInfo)
+}
+```
+
+- `errors` — Array of AJV error objects with `keyword`, `instancePath`, `message`, `params`
+- Message format: `"Validation error message - field.path validation message, ..."`
+
+### ProcedureYieldValidationError extends ProcedureError
+
+Thrown when yield validation fails in CreateStream (when `validateYields: true`).
+
+```typescript
+class ProcedureYieldValidationError extends ProcedureError {
+  readonly errors?: TSchemaValidationError[]
+  constructor(procedureName: string, message: string, errors?: TSchemaValidationError[], definitionInfo?: DefinitionInfo)
+}
+```
+
+### ProcedureRegistrationError extends ProcedureError
+
+Thrown at registration time (schema extraction/compilation failure, duplicate name, or `schema.params` and `schema.input` both defined).
+
+```typescript
+class ProcedureRegistrationError extends ProcedureError {
+  constructor(procedureName: string, message: string, definitionInfo?: DefinitionInfo)
+}
+```
+
+---
+
+## Schema Utilities
+
+### extractJsonSchema(libSchema)
+
+Converts a TypeBox schema to JSON Schema.
+
+```typescript
+function extractJsonSchema(libSchema: unknown): TJSONSchema | undefined
+```
+
+- TypeBox schemas are valid JSON Schema — returned as-is
+- Returns `undefined` if schema type not recognized
+
+### schemaParser(schema, onParseError)
+
+Compiles schemas into AJV validator functions.
+
+```typescript
+function schemaParser(
+  schema: { params?: unknown; returnType?: unknown; yieldType?: unknown; input?: Record<string, unknown> },
+  onParseError: (errors: Record<string, string>) => void
+): TSchemaParsed
+```
+
+### isTypeboxSchema(schema)
+
+Type guard for TypeBox schema detection.
+
+```typescript
+function isTypeboxSchema(schema: any): schema is TSchema
+```
+
+### TSchemaLib\<SchemaLibType\>
+
+Maps schema type to inferred TypeScript type:
+- TypeBox `TSchema` → `Static<T>`
+- Otherwise → `unknown`
+
+---
+
+## ExpressRPCAppBuilder
+
+HTTP implementation for Express.
+
+```typescript
+class ExpressRPCAppBuilder {
+  constructor(config?: {
+    app?: express.Express
+    pathPrefix?: string
+    onRequestStart?: (req: express.Request) => void
+    onRequestEnd?: (req: express.Request, res: express.Response) => void
+    onSuccess?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response) => void
+    onError?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
+  })
+
+  register<TFactory>(
+    factory: TFactory,
+    factoryContext: Context | ((req: Request) => Context | Promise<Context>),
+    extendProcedureDoc?: ({ base, procedure }) => Record<string, any>
+  ): this
+
+  build(): express.Application
+
+  static makeRPCHttpRoutePath(params: { name: string; config: RPCConfig; prefix?: string }): string
+
+  get app(): express.Express
+  get docs(): RPCHttpRouteDoc[]
+}
+```
+
+### Route Path
+
+`POST {pathPrefix}/{scope}/{kebab-name}/{version}`
+
+- `scope` can be string or string array (joined as path segments)
+- Procedure name is converted to kebab-case
+
+### Context Resolution
+
+- Static object: `builder.register(factory, { userId: 'system' })`
+- Sync function: `builder.register(factory, (req) => ({ auth: req.headers.authorization }))`
+- Async function: `builder.register(factory, async (req) => ({ user: await getUser(req) }))`
+
+### Signal Injection
+
+Express builder creates a lazy AbortController and aborts on request close. The `signal` is injected into handler context automatically.
+
+---
+
+## HonoRPCAppBuilder
+
+HTTP implementation for Hono. Same API as ExpressRPCAppBuilder but receives Hono `Context` instead of Express `Request`.
+
+```typescript
+class HonoRPCAppBuilder {
+  constructor(config?: {
+    app?: Hono
+    pathPrefix?: string
+    onRequestStart?: (c: Context) => void
+    onRequestEnd?: (c: Context) => void
+    onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+    onError?: (procedure: TProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+  })
+
+  register<TFactory>(
+    factory: TFactory,
+    factoryContext: Context | ((c: HonoContext) => Context | Promise<Context>),
+    extendProcedureDoc?: ({ base, procedure }) => Record<string, any>
+  ): this
+
+  build(): Hono
+  get app(): Hono
+  get docs(): RPCHttpRouteDoc[]
+}
+```
+
+### Signal Injection
+
+Uses `c.req.raw.signal` — the native Request signal from the Hono context.
+
+---
+
+## HonoStreamAppBuilder\<TErrorData\>
+
+Streaming HTTP implementation for Hono. Supports SSE and text streaming modes.
+
+```typescript
+class HonoStreamAppBuilder<TErrorData = unknown> {
+  constructor(config?: {
+    app?: Hono
+    pathPrefix?: string
+    defaultStreamMode?: StreamMode              // 'sse' | 'text', default 'sse'
+    onRequestStart?: (c: Context) => void
+    onRequestEnd?: (c: Context) => void
+    onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
+    onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
+    onPreStreamError?: (procedure: TStreamProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+    onMidStreamError?: (procedure: TStreamProcedureRegistration, c: Context, error: Error) => MidStreamErrorResult<TErrorData> | undefined
+  })
+
+  register<TFactory>(
+    factory: TFactory,
+    factoryContext: Context | ((c: HonoContext) => Context | Promise<Context>),
+    options?: {
+      streamMode?: StreamMode
+      extendProcedureDoc?: ({ base, procedure }) => Record<string, any>
+    }
+  ): this
+
+  build(): Hono
+  get app(): Hono
+  get docs(): StreamHttpRouteDoc[]
+}
+```
+
+### Stream Modes
+
+**SSE mode** (`'sse'`):
+- Content-Type: `text/event-stream`
+- Each yield → `event: {name}\nid: {counter}\ndata: {json}\n\n`
+- Supports custom event/id/retry via `sse()` helper
+
+**Text mode** (`'text'`):
+- Content-Type: `text/plain`
+- Each yield → `{json}\n`
+
+### sse(data, options?)
+
+Attaches SSE metadata to a yielded value.
+
+```typescript
+function sse<T extends object>(data: T, options?: {
+  event?: string   // SSE event type (default: procedure name)
+  id?: string      // SSE event ID (default: sequential counter)
+  retry?: number   // Reconnection interval in ms
+}): T
+```
+
+### HTTP Methods
+
+Both GET and POST are registered for each streaming procedure:
+- **GET**: params extracted from query string
+- **POST**: params extracted from JSON body
+
+### MidStreamErrorResult
+
+```typescript
+type MidStreamErrorResult<TErrorData = unknown> = {
+  data: TErrorData       // Data to yield as final event
+  closeStream?: boolean  // Close stream after? (default: true)
+}
+```
+
+### Error Handling
+
+- **Pre-stream errors** (validation, context): Returns JSON error response (no streaming started). Custom handling via `onPreStreamError`.
+- **Mid-stream errors** (generator throws): Yields error as final event, closes stream. Custom handling via `onMidStreamError`.
+
+---
+
+## HonoAPIAppBuilder
+
+REST-style HTTP implementation for Hono. Routes by HTTP method with `schema.input` per-channel validation.
+
+```typescript
+class HonoAPIAppBuilder {
+  constructor(config?: {
+    app?: Hono
+    pathPrefix?: string
+    queryParser?: (queryString: string) => Record<string, unknown>
+    onRequestStart?: (c: Context) => void
+    onRequestEnd?: (c: Context) => void
+    onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+    onError?: (procedure: TProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+  })
+
+  register<TFactory>(
+    factory: TFactory,
+    factoryContext: Context | ((c: HonoContext) => Context | Promise<Context>),
+    extendProcedureDoc?: ({ base, procedure }) => Record<string, any>
+  ): this
+
+  async build(): Promise<Hono>
+  get app(): Hono
+  get docs(): APIHttpRouteDoc[]
+}
+```
+
+### Route Path
+
+Developer-defined via `APIConfig.path` — no auto-generation. Supports Hono path params (`:id`).
+
+`{pathPrefix}{path}` — e.g., `/api/users/:id`
+
+### Input Channel Extraction
+
+| Channel | HTTP Source | Used For |
+|---------|-----------|----------|
+| `pathParams` | URL path parameters (`c.req.param()`) | `/users/:id` → `{ id: '...' }` |
+| `query` | Query string (parsed via `qs` or native) | `?page=2` → `{ page: 2 }` |
+| `body` | JSON request body (POST/PUT/PATCH only) | `{ name: 'John' }` |
+| `headers` | Request headers (AJV strips non-declared) | `{ 'x-api-key': '...' }` |
+
+### Default Success Status
+
+| Method | Default Status |
+|--------|---------------|
+| POST | 201 |
+| DELETE | 204 (no body) |
+| Others | 200 |
+
+Override with `APIConfig.successStatus`.
+
+### Build-Time Validation
+
+- Path param names in path template must match `schema.input.pathParams` property names
+- `schema.input.pathParams` defined but path has no `:param` segments → error
+- Path has `:param` but `schema.input.pathParams` missing → error
+- Property name mismatch → error with clear message
+
+### Query Parsing
+
+Priority: custom `queryParser` > `qs` (optional peer dep, lazy-loaded) > native `URLSearchParams`.
+
+Query parser resolved once at `build()` time — handlers use it synchronously.
+
+### Signal Injection
+
+Uses `c.req.raw.signal` — native Request signal from Hono context.
+
+---
+
+## HTTP Types
+
+### RPCConfig
+
+```typescript
+interface RPCConfig {
+  scope: string | string[]
+  version: number
+}
+```
+
+### RPCHttpRouteDoc
+
+```typescript
+interface RPCHttpRouteDoc extends RPCConfig {
+  name: string
+  path: string
+  method: 'post'
+  jsonSchema: {
+    body?: Record<string, unknown>
+    response?: Record<string, unknown>
+  }
+}
+```
+
+### StreamHttpRouteDoc
+
+```typescript
+interface StreamHttpRouteDoc extends RPCConfig {
+  name: string
+  path: string
+  methods: ('get' | 'post')[]
+  streamMode: StreamMode
+  jsonSchema: {
+    params?: Record<string, unknown>
+    yieldType?: Record<string, unknown>
+    returnType?: Record<string, unknown>
+  }
+}
+```
+
+### APIConfig
+
+```typescript
+interface APIConfig {
+  path: string
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+  successStatus?: number
+}
+```
+
+### APIHttpRouteDoc
+
+```typescript
+interface APIHttpRouteDoc extends APIConfig {
+  name: string
+  fullPath: string
+  jsonSchema: {
+    pathParams?: Record<string, unknown>
+    query?: Record<string, unknown>
+    body?: Record<string, unknown>
+    headers?: Record<string, unknown>
+    response?: Record<string, unknown>
+  }
+}
+```
+
+### APIInput
+
+Channel constraint helper type. Use with `satisfies` for compile-time validation of channel names.
+
+```typescript
+type APIInput<T extends {
+  pathParams?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+}> = T
+```
+
+### HttpMethod
+
+```typescript
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+```
+
+---
+
+## Stack Utilities
+
+### captureDefinitionInfo()
+
+Captures stack trace and extracts first user-code frame location. Used internally to enhance error messages.
+
+```typescript
+function captureDefinitionInfo(): DefinitionInfo
+```
+
+### DefinitionLocation
+
+```typescript
+type DefinitionLocation = {
+  file: string
+  line: number
+  column: number
+  raw: string
+}
+```
+
+### DefinitionInfo
+
+```typescript
+type DefinitionInfo = {
+  definedAt?: DefinitionLocation
+  definitionStack?: string
+}
+```