ts-procedures 5.2.0 → 5.3.0

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

@@ -0,0 +1,550 @@
+# 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 } 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'
+```
+
+---
+
+## 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
+
+### 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).
+
+```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 },
+  onParseError: (errors: { params?: string; returnType?: string; yieldType?: 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`.
+
+---
+
+## 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>
+  }
+}
+```
+
+---
+
+## 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
+}
+```