ts-procedures 5.4.0 → 5.5.0

package/src/errors.ts

@@ -1,107 +0,0 @@
-import { TSchemaValidationError } from './schema/parser.js'
-import { DefinitionInfo, DefinitionLocation, formatDefinitionInfo } from './stack-utils.js'
-import { kebabCase } from 'es-toolkit/string'
-
-export class ProcedureError extends Error {
-  cause?: unknown
-  readonly definedAt?: DefinitionLocation
-  readonly definitionStack?: string
-
-  constructor(
-    readonly procedureName: string,
-    readonly message: string,
-    readonly meta?: object,
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
-  ) {
-    super(message)
-    this.name = 'ProcedureError'
-
-    if (definitionInfo) {
-      this.definedAt = definitionInfo.definedAt
-      this.definitionStack = definitionInfo.definitionStack
-      this.enhanceStack()
-    }
-
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureError.prototype)
-  }
-
-  /**
-   * Returns a formatted string showing where the procedure was defined.
-   */
-  getDefinitionLocation(): string | undefined {
-    if (!this.definedAt) {
-      return undefined
-    }
-    return `${this.definedAt.file}:${this.definedAt.line}:${this.definedAt.column}`
-  }
-
-  /**
-   * Enhances the error stack with definition location information.
-   */
-  private enhanceStack(): void {
-    if (!this.stack || !this.definedAt) {
-      return
-    }
-
-    const definitionSection = formatDefinitionInfo(
-      { definedAt: this.definedAt, definitionStack: this.definitionStack },
-      this.procedureName
-    )
-
-    if (definitionSection) {
-      this.stack = this.stack + definitionSection
-    }
-  }
-}
-
-export class ProcedureValidationError extends ProcedureError {
-  constructor(
-    readonly procedureName: string,
-    message: string,
-    readonly errors?: TSchemaValidationError[],
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
-  ) {
-    const readableErrors = errors
-      ?.map((err) => `- ${kebabCase(err.instancePath).replace('-', '.')} ${err.message}`)
-      .join(', ')
-    super(procedureName, message + ' ' + readableErrors, { errors }, definitionInfo)
-    this.name = 'ProcedureValidationError'
-
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureValidationError.prototype)
-  }
-}
-
-export class ProcedureRegistrationError extends ProcedureError {
-  constructor(
-    readonly procedureName: string,
-    message: string,
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
-  ) {
-    super(procedureName, message, undefined, definitionInfo)
-    this.name = 'ProcedureRegistrationError'
-
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureRegistrationError.prototype)
-  }
-}
-
-export class ProcedureYieldValidationError extends ProcedureError {
-  constructor(
-    readonly procedureName: string,
-    message: string,
-    readonly errors?: TSchemaValidationError[],
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
-  ) {
-    super(procedureName, message, undefined, definitionInfo)
-    this.name = 'ProcedureYieldValidationError'
-
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureYieldValidationError.prototype)
-  }
-}

package/src/exports.ts

@@ -1,7 +0,0 @@
-export * from './index.js'
-export * from './errors.js'
-export * from './stack-utils.js'
-export * from './schema/extract-json-schema.js'
-export * from './schema/parser.js'
-export * from './schema/resolve-schema-lib.js'
-export * from './schema/types.js'

package/src/implementations/http/README.md

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

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)
-```