ts-procedures 5.4.0 → 5.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "5.4.0",
+  "version": "5.4.1",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
@@ -46,7 +46,6 @@
   "files": [
     "assets",
     "build",
-    "src",
     "agent_config"
   ],
   "keywords": [

package/src/errors.test.ts

@@ -1,163 +0,0 @@
-import { describe, expect, test } from 'vitest'
-import {
-  ProcedureError,
-  ProcedureValidationError,
-  ProcedureRegistrationError,
-} from './errors.js'
-import { DefinitionInfo } from './stack-utils.js'
-
-describe('Error Classes', () => {
-  test('ProcedureError has correct properties', () => {
-    const err = new ProcedureError('TestProc', 'Something failed', { code: 123 })
-
-    expect(err.name).toBe('ProcedureError')
-    expect(err.procedureName).toBe('TestProc')
-    expect(err.message).toBe('Something failed')
-    expect(err.meta).toEqual({ code: 123 })
-    expect(err instanceof Error).toBe(true)
-  })
-
-  test('ProcedureValidationError extends ProcedureError', () => {
-    const err = new ProcedureValidationError('TestProc', 'Validation failed', [])
-
-    expect(err instanceof ProcedureError).toBe(true)
-    expect(err instanceof Error).toBe(true)
-    expect(err.name).toBe('ProcedureValidationError')
-  })
-
-  test('ProcedureRegistrationError extends ProcedureError', () => {
-    const err = new ProcedureRegistrationError('TestProc', 'Registration failed')
-
-    expect(err instanceof ProcedureError).toBe(true)
-    expect(err instanceof Error).toBe(true)
-    expect(err.name).toBe('ProcedureRegistrationError')
-    expect(err.procedureName).toBe('TestProc')
-  })
-
-  test('ProcedureError supports cause property', () => {
-    const cause = new Error('Original error')
-    const err = new ProcedureError('TestProc', 'Wrapped error')
-    err.cause = cause
-
-    expect(err.cause).toBe(cause)
-  })
-
-  test('All error types have consistent procedureName property', () => {
-    const baseErr = new ProcedureError('Proc1', 'message')
-    const validationErr = new ProcedureValidationError('Proc2', 'message', [])
-    const registrationErr = new ProcedureRegistrationError('Proc3', 'message')
-
-    expect(baseErr.procedureName).toBe('Proc1')
-    expect(validationErr.procedureName).toBe('Proc2')
-    expect(registrationErr.procedureName).toBe('Proc3')
-  })
-})
-
-describe('Error Classes - Definition Info', () => {
-  const mockDefinitionInfo: DefinitionInfo = {
-    definedAt: {
-      file: '/app/procedures/user.ts',
-      line: 25,
-      column: 3,
-      raw: 'at Object.<anonymous> (/app/procedures/user.ts:25:3)',
-    },
-    definitionStack: 'Error\n    at Object.<anonymous> (/app/procedures/user.ts:25:3)',
-  }
-
-  test('ProcedureError includes definedAt when provided', () => {
-    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
-
-    expect(err.definedAt).toBeDefined()
-    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
-    expect(err.definedAt?.line).toBe(25)
-    expect(err.definedAt?.column).toBe(3)
-  })
-
-  test('ProcedureError includes definitionStack when provided', () => {
-    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
-
-    expect(err.definitionStack).toBeDefined()
-    expect(err.definitionStack).toContain('/app/procedures/user.ts')
-  })
-
-  test('ProcedureError works without definitionInfo (backward compat)', () => {
-    const err = new ProcedureError('TestProc', 'Something failed', { code: 123 })
-
-    expect(err.definedAt).toBeUndefined()
-    expect(err.definitionStack).toBeUndefined()
-    expect(err.procedureName).toBe('TestProc')
-    expect(err.message).toBe('Something failed')
-    expect(err.meta).toEqual({ code: 123 })
-  })
-
-  test('ProcedureValidationError includes definedAt when provided', () => {
-    const err = new ProcedureValidationError('TestProc', 'Validation failed', [], mockDefinitionInfo)
-
-    expect(err.definedAt).toBeDefined()
-    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
-    expect(err.definedAt?.line).toBe(25)
-  })
-
-  test('ProcedureValidationError works without definitionInfo (backward compat)', () => {
-    const err = new ProcedureValidationError('TestProc', 'Validation failed', [])
-
-    expect(err.definedAt).toBeUndefined()
-    expect(err.definitionStack).toBeUndefined()
-    expect(err.name).toBe('ProcedureValidationError')
-  })
-
-  test('ProcedureRegistrationError includes definedAt when provided', () => {
-    const err = new ProcedureRegistrationError('TestProc', 'Registration failed', mockDefinitionInfo)
-
-    expect(err.definedAt).toBeDefined()
-    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
-  })
-
-  test('ProcedureRegistrationError works without definitionInfo (backward compat)', () => {
-    const err = new ProcedureRegistrationError('TestProc', 'Registration failed')
-
-    expect(err.definedAt).toBeUndefined()
-    expect(err.definitionStack).toBeUndefined()
-    expect(err.name).toBe('ProcedureRegistrationError')
-  })
-
-  test('getDefinitionLocation returns formatted location string', () => {
-    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
-
-    const location = err.getDefinitionLocation()
-
-    expect(location).toBe('/app/procedures/user.ts:25:3')
-  })
-
-  test('getDefinitionLocation returns undefined when no definedAt', () => {
-    const err = new ProcedureError('TestProc', 'Something failed')
-
-    const location = err.getDefinitionLocation()
-
-    expect(location).toBeUndefined()
-  })
-
-  test('enhanced stack contains definition location', () => {
-    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
-
-    expect(err.stack).toContain('--- Procedure "TestProc" defined at ---')
-    expect(err.stack).toContain('/app/procedures/user.ts:25:3')
-  })
-
-  test('stack is not modified when no definitionInfo', () => {
-    const err = new ProcedureError('TestProc', 'Something failed')
-
-    expect(err.stack).toBeDefined()
-    expect(err.stack).not.toContain('--- Procedure')
-  })
-
-  test('all error types enhance stack with definition location', () => {
-    const baseErr = new ProcedureError('Proc1', 'message', undefined, mockDefinitionInfo)
-    const validationErr = new ProcedureValidationError('Proc2', 'message', [], mockDefinitionInfo)
-    const registrationErr = new ProcedureRegistrationError('Proc3', 'message', mockDefinitionInfo)
-
-    expect(baseErr.stack).toContain('--- Procedure "Proc1" defined at ---')
-    expect(validationErr.stack).toContain('--- Procedure "Proc2" defined at ---')
-    expect(registrationErr.stack).toContain('--- Procedure "Proc3" defined at ---')
-  })
-})

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