ts-procedures 6.0.0 → 6.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "6.0.0",
+  "version": "6.0.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",

package/src/implementations/http/README.md

@@ -257,8 +257,7 @@ import { DocRegistry } from 'ts-procedures/http-docs'
 
 const docs = new DocRegistry({
   basePath: '/api',
-  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
-  errors: DocRegistry.defaultErrors(),
+  errors: appErrors,  // your ErrorTaxonomy — framework defaults auto-merged and deduped
 })
   .from(rpcBuilder)
   .from(apiBuilder)
@@ -269,7 +268,7 @@ app.get('/docs', (c) => c.json(docs.toJSON()))
 
 - `from()` stores a reference — routes are read lazily at `toJSON()` time
 - `toJSON()` supports optional `filter` and `transform` options
-- `defaultErrors()` returns error schemas for all 4 procedure error types
+- `errors` accepts an `ErrorTaxonomy` or raw `ErrorDoc[]`; framework defaults are auto-merged (opt out via `includeDefaults: false`)
 - All builders satisfy the `DocSource` interface (`{ readonly docs: AnyHttpRouteDoc[] }`)
 
 ### Client Code Generation

package/src/implementations/http/doc-registry.test.ts

@@ -3,6 +3,7 @@ import { v } from 'suretype'
 import { Procedures } from '../../index.js'
 import { HonoRPCAppBuilder } from './hono-rpc/index.js'
 import { DocRegistry } from './doc-registry.js'
+import { defineErrorTaxonomy } from './error-taxonomy.js'
 import type {
   AnyHttpRouteDoc,
   RPCHttpRouteDoc,
@@ -11,6 +12,7 @@ import type {
   StreamHttpRouteDoc,
   DocSource,
   DocEnvelope,
+  ErrorDoc,
 } from '../types.js'
 
 // ---------------------------------------------------------------------------
@@ -61,7 +63,7 @@ describe('DocRegistry', () => {
   // --------------------------------------------------------------------------
   describe('constructor', () => {
     test('uses defaults when no config provided', () => {
-      const registry = new DocRegistry()
+      const registry = new DocRegistry({ includeDefaults: false })
       const out = registry.toJSON()
       expect(out.basePath).toBe('')
       expect(out.headers).toEqual([])
@@ -69,7 +71,7 @@ describe('DocRegistry', () => {
     })
 
     test('accepts partial config', () => {
-      const registry = new DocRegistry({ basePath: '/v1' })
+      const registry = new DocRegistry({ basePath: '/v1', includeDefaults: false })
       const out = registry.toJSON()
       expect(out.basePath).toBe('/v1')
       expect(out.headers).toEqual([])
@@ -79,7 +81,7 @@ describe('DocRegistry', () => {
     test('accepts full config', () => {
       const headers = [{ name: 'Authorization', description: 'Bearer token', required: true }]
       const errors = [{ name: 'Unauthorized', statusCode: 401, description: 'Missing token' }]
-      const registry = new DocRegistry({ basePath: '/api', headers, errors })
+      const registry = new DocRegistry({ basePath: '/api', headers, errors, includeDefaults: false })
       const out = registry.toJSON()
       expect(out.basePath).toBe('/api')
       expect(out.headers).toEqual(headers)
@@ -175,7 +177,7 @@ describe('DocRegistry', () => {
     test('headers and errors are copies', () => {
       const headers = [{ name: 'X-Custom' }]
       const errors = [{ name: 'E', statusCode: 500, description: 'd' }]
-      const registry = new DocRegistry({ headers, errors })
+      const registry = new DocRegistry({ headers, errors, includeDefaults: false })
       const out = registry.toJSON()
       expect(out.headers).toEqual(headers)
       expect(out.headers).not.toBe(headers)
@@ -298,6 +300,153 @@ describe('DocRegistry', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // taxonomy input + auto-defaults + dedupe (v6.0.1 simplification)
+  // --------------------------------------------------------------------------
+  describe('errors: ErrorTaxonomy (polymorphic constructor input)', () => {
+    test('accepts an ErrorTaxonomy directly and converts to ErrorDoc[]', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: {
+          class: class AuthError extends Error {},
+          statusCode: 401,
+          description: 'unauthenticated',
+        },
+      })
+      const envelope = new DocRegistry({ errors: taxonomy }).toJSON()
+      const auth = envelope.errors.find((e) => e.name === 'AuthError')
+      expect(auth).toBeDefined()
+      expect(auth?.statusCode).toBe(401)
+      expect(auth?.description).toBe('unauthenticated')
+    })
+
+    test('auto-includes framework defaults when errors is a taxonomy', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+      })
+      const names = new DocRegistry({ errors: taxonomy }).toJSON().errors.map((e) => e.name)
+      expect(names).toContain('AuthError')
+      expect(names).toContain('ProcedureValidationError')
+      expect(names).toContain('ProcedureYieldValidationError')
+      expect(names).toContain('ProcedureError')
+      expect(names).toContain('ProcedureRegistrationError')
+    })
+
+    test('auto-includes framework defaults when errors is ErrorDoc[]', () => {
+      const custom: ErrorDoc = { name: 'CustomThing', statusCode: 418, description: 'teapot' }
+      const names = new DocRegistry({ errors: [custom] }).toJSON().errors.map((e) => e.name)
+      expect(names).toContain('CustomThing')
+      expect(names).toContain('ProcedureValidationError')
+    })
+
+    test('includeDefaults: false omits framework defaults', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+      })
+      const names = new DocRegistry({ errors: taxonomy, includeDefaults: false })
+        .toJSON()
+        .errors.map((e) => e.name)
+      expect(names).toEqual(['AuthError'])
+    })
+
+    test('user taxonomy entry with same name as default overrides default (dedupe, user wins)', () => {
+      const taxonomy = defineErrorTaxonomy({
+        ProcedureError: {
+          class: Error,
+          statusCode: 418,
+          description: 'custom override',
+        },
+      })
+      const envelope = new DocRegistry({ errors: taxonomy }).toJSON()
+      const proc = envelope.errors.filter((e) => e.name === 'ProcedureError')
+      expect(proc).toHaveLength(1)
+      expect(proc[0]!.statusCode).toBe(418)
+      expect(proc[0]!.description).toBe('custom override')
+    })
+
+    test('user ErrorDoc with same name as default overrides default (dedupe, user wins)', () => {
+      const custom: ErrorDoc = {
+        name: 'ProcedureError',
+        statusCode: 418,
+        description: 'custom override',
+      }
+      const envelope = new DocRegistry({ errors: [custom] }).toJSON()
+      const proc = envelope.errors.filter((e) => e.name === 'ProcedureError')
+      expect(proc).toHaveLength(1)
+      expect(proc[0]!.statusCode).toBe(418)
+      expect(proc[0]!.description).toBe('custom override')
+    })
+
+    test('empty errors config still returns framework defaults', () => {
+      const names = new DocRegistry().toJSON().errors.map((e) => e.name)
+      expect(names).toContain('ProcedureError')
+      expect(names).toContain('ProcedureValidationError')
+      expect(names).toContain('ProcedureYieldValidationError')
+      expect(names).toContain('ProcedureRegistrationError')
+    })
+
+    test('includeDefaults: false with no errors produces empty error list', () => {
+      const envelope = new DocRegistry({ includeDefaults: false }).toJSON()
+      expect(envelope.errors).toEqual([])
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // .documentError() fluent extension
+  // --------------------------------------------------------------------------
+  describe('.documentError()', () => {
+    test('adds a single ErrorDoc to the envelope', () => {
+      const registry = new DocRegistry({ includeDefaults: false }).documentError({
+        name: 'RateLimitExceeded',
+        statusCode: 429,
+        description: 'too many requests',
+      })
+      const names = registry.toJSON().errors.map((e) => e.name)
+      expect(names).toEqual(['RateLimitExceeded'])
+    })
+
+    test('accepts multiple docs via variadic args', () => {
+      const registry = new DocRegistry({ includeDefaults: false }).documentError(
+        { name: 'A', statusCode: 400, description: 'a' },
+        { name: 'B', statusCode: 500, description: 'b' }
+      )
+      const names = registry.toJSON().errors.map((e) => e.name)
+      expect(names).toEqual(['A', 'B'])
+    })
+
+    test('returns this for chaining', () => {
+      const registry = new DocRegistry()
+      const returned = registry.documentError({
+        name: 'Foo',
+        statusCode: 500,
+        description: 'x',
+      })
+      expect(returned).toBe(registry)
+    })
+
+    test('composes with taxonomy input — extends docs without replacing', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+      })
+      const envelope = new DocRegistry({ errors: taxonomy })
+        .documentError({ name: 'RateLimitExceeded', statusCode: 429, description: 'x' })
+        .toJSON()
+      const names = envelope.errors.map((e) => e.name)
+      expect(names).toContain('AuthError')
+      expect(names).toContain('RateLimitExceeded')
+      expect(names).toContain('ProcedureValidationError')
+    })
+
+    test('dedupes against existing errors (last write wins)', () => {
+      const registry = new DocRegistry({ includeDefaults: false })
+        .documentError({ name: 'Foo', statusCode: 400, description: 'first' })
+        .documentError({ name: 'Foo', statusCode: 500, description: 'second' })
+      const foo = registry.toJSON().errors.filter((e) => e.name === 'Foo')
+      expect(foo).toHaveLength(1)
+      expect(foo[0]!.statusCode).toBe(500)
+      expect(foo[0]!.description).toBe('second')
+    })
+  })
+
   // --------------------------------------------------------------------------
   // kind discriminant
   // --------------------------------------------------------------------------
@@ -333,7 +482,6 @@ describe('DocRegistry', () => {
       const registry = new DocRegistry({
         basePath: '/api',
         headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
-        errors: DocRegistry.defaultErrors(),
       })
         .from(makeSource([rpcDoc]))
         .from(makeSource([apiDoc]))
@@ -347,10 +495,7 @@ describe('DocRegistry', () => {
     })
 
     test('filter + transform combined', () => {
-      const registry = new DocRegistry({
-        basePath: '/api',
-        errors: DocRegistry.defaultErrors(),
-      })
+      const registry = new DocRegistry({ basePath: '/api' })
         .from(makeSource([rpcDoc]))
         .from(makeSource([apiDoc]))
         .from(makeSource([streamDoc]))
@@ -372,7 +517,6 @@ describe('DocRegistry', () => {
       const registry = new DocRegistry({
         basePath: '/api',
         headers: [{ name: 'X-Request-Id', example: 'abc-123' }],
-        errors: DocRegistry.defaultErrors(),
       })
         .from(makeSource([rpcDoc]))
         .from(makeSource([apiDoc]))

package/src/implementations/http/doc-registry.ts

@@ -8,9 +8,10 @@ import type {
   HeaderDoc,
 } from '../types.js'
 import {
-  ErrorTaxonomy,
+  PROCEDURE_REGISTRATION_ERROR_DOC,
   defaultErrorTaxonomy,
   taxonomyToErrorDocs,
+  type ErrorTaxonomy,
 } from './error-taxonomy.js'
 
 export type {
@@ -23,37 +24,44 @@ export type {
   HeaderDoc,
 } from '../types.js'
 
+function isTaxonomy(input: ErrorTaxonomy | ErrorDoc[]): input is ErrorTaxonomy {
+  return !Array.isArray(input)
+}
+
 /**
- * `ProcedureRegistrationError` is thrown at procedure-definition time (never at
- * request time), so it doesn't appear in the runtime taxonomy. It is documented
- * here so consumers still see it in the error catalog.
+ * Dedupes ErrorDocs by `name`, last occurrence wins. Map insertion order
+ * preserves the latest position of each name.
  */
-const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
-  name: 'ProcedureRegistrationError',
-  statusCode: 500,
-  description:
-    'An invalid schema or configuration was detected at procedure registration time.',
-  schema: {
-    type: 'object',
-    properties: {
-      name: { type: 'string', const: 'ProcedureRegistrationError' },
-      procedureName: { type: 'string' },
-      message: { type: 'string' },
-    },
-    required: ['name', 'procedureName', 'message'],
-  },
+function dedupeByName(docs: ErrorDoc[]): ErrorDoc[] {
+  const byName = new Map<string, ErrorDoc>()
+  for (const doc of docs) byName.set(doc.name, doc)
+  return Array.from(byName.values())
 }
 
 export class DocRegistry {
   private readonly basePath: string
   private readonly headers: HeaderDoc[]
-  private readonly errors: ErrorDoc[]
+  private errors: ErrorDoc[]
   private readonly sources: DocSource<AnyHttpRouteDoc>[] = []
 
   constructor(config?: DocRegistryConfig) {
     this.basePath = config?.basePath ?? ''
     this.headers = config?.headers ?? []
-    this.errors = config?.errors ?? []
+
+    const includeDefaults = config?.includeDefaults ?? true
+    const userErrors: ErrorDoc[] = config?.errors
+      ? isTaxonomy(config.errors)
+        ? taxonomyToErrorDocs(config.errors)
+        : config.errors
+      : []
+
+    // Precedence: defaults come first, user errors override via dedupe
+    // (last-write-wins). Matches runtime resolution order.
+    const merged = includeDefaults
+      ? [...DocRegistry.defaultErrors(), ...userErrors]
+      : userErrors
+
+    this.errors = dedupeByName(merged)
   }
 
   from(source: DocSource<AnyHttpRouteDoc>): this {
@@ -61,6 +69,18 @@ export class DocRegistry {
     return this
   }
 
+  /**
+   * Adds one or more {@link ErrorDoc} entries to the envelope. Use for errors
+   * outside your runtime taxonomy — middleware-level errors, infrastructure
+   * errors (502/503/504), or doc-only meta errors.
+   *
+   * Deduped by `name` — last write wins.
+   */
+  documentError(...docs: ErrorDoc[]): this {
+    this.errors = dedupeByName([...this.errors, ...docs])
+    return this
+  }
+
   toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T {
     let routes = this.sources.flatMap((source) => source.docs)
 
@@ -83,11 +103,12 @@ export class DocRegistry {
   }
 
   /**
-   * Framework error defaults for the DocEnvelope — derived from
-   * {@link defaultErrorTaxonomy} so the documented shape cannot drift from what
-   * the HTTP builders actually emit at runtime. `ProcedureRegistrationError` is
-   * appended because it's thrown at registration time (never at request time)
-   * and therefore lives only in the catalog, not the runtime taxonomy.
+   * Framework error defaults — derived from {@link defaultErrorTaxonomy} plus
+   * `ProcedureRegistrationError` (which is thrown only at registration time
+   * and therefore lives in the catalog, not the runtime taxonomy).
+   *
+   * Most consumers do not need to call this directly — the `DocRegistry`
+   * constructor auto-includes these unless `includeDefaults: false` is passed.
    */
   static defaultErrors(): ErrorDoc[] {
     return [
@@ -95,32 +116,4 @@ export class DocRegistry {
       PROCEDURE_REGISTRATION_ERROR_DOC,
     ]
   }
-
-  /**
-   * Convenience constructor that seeds `config.errors` from a taxonomy so the
-   * DocEnvelope automatically documents every error class registered with the
-   * HTTP builders. Framework defaults (including `ProcedureRegistrationError`)
-   * are included unless `includeDefaults: false` is passed.
-   *
-   * @example
-   * const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
-   *   .from(apiApp)
-   */
-  static fromTaxonomy(
-    taxonomy: ErrorTaxonomy,
-    config?: Omit<DocRegistryConfig, 'errors'> & { includeDefaults?: boolean }
-  ): DocRegistry {
-    const { includeDefaults = true, ...rest } = config ?? {}
-    const errors: ErrorDoc[] = [
-      ...taxonomyToErrorDocs(taxonomy),
-      ...(includeDefaults ? DocRegistry.defaultErrors() : []),
-    ]
-    // Dedupe by name — user entries take precedence over defaults with the
-    // same key, matching runtime resolution order.
-    const seen = new Set<string>()
-    const deduped = errors.filter((e) =>
-      seen.has(e.name) ? false : (seen.add(e.name), true)
-    )
-    return new DocRegistry({ ...rest, errors: deduped })
-  }
 }

package/src/implementations/http/error-taxonomy.ts

@@ -182,10 +182,34 @@ export const defaultErrorTaxonomy = defineErrorTaxonomy({
   },
 })
 
+/**
+ * Doc-only entry for `ProcedureRegistrationError`, which is thrown at
+ * procedure-definition time (never at request time) and therefore doesn't
+ * appear in the runtime taxonomy. Consumers still see it in the error catalog
+ * via `DocRegistry.defaultErrors()`.
+ */
+export const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
+  name: 'ProcedureRegistrationError',
+  statusCode: 500,
+  description:
+    'An invalid schema or configuration was detected at procedure registration time.',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', const: 'ProcedureRegistrationError' },
+      procedureName: { type: 'string' },
+      message: { type: 'string' },
+    },
+    required: ['name', 'procedureName', 'message'],
+  },
+}
+
 /**
  * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
- * Single source of truth so the runtime mapping and the documented shape
- * cannot drift apart.
+ *
+ * @internal Used by `DocRegistry` to merge taxonomy entries into the envelope.
+ *   Consumers should pass their taxonomy directly to `new DocRegistry({ errors: taxonomy })`
+ *   rather than calling this helper — the constructor handles the conversion.
  */
 export function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[] {
   return Object.entries(taxonomy).map(([key, entry]) => ({

package/src/implementations/http/express-rpc/README.md

@@ -59,7 +59,7 @@ type ExpressRPCAppBuilderConfig = {
   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
+  onError?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
 }
 ```
 
@@ -70,7 +70,7 @@ type ExpressRPCAppBuilderConfig = {
 | `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                                 |
+| `onError` | `(proc, req, res, err) => void` | Imperative error handler (peer of `errors` taxonomy — see Error Handling) |
 
 ## Context Resolution
 

package/src/implementations/http/hono-rpc/README.md

@@ -64,7 +64,7 @@ type HonoRPCAppBuilderConfig = {
   onRequestStart?: (c: Context) => void
   onRequestEnd?: (c: Context) => void
   onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
-  error?: (
+  onError?: (
     procedure: TProcedureRegistration,
     c: Context,
     error: Error
@@ -79,7 +79,7 @@ type HonoRPCAppBuilderConfig = {
 | `onRequestStart` | `(c) => void`                | Called at start of each request                   |
 | `onRequestEnd`   | `(c) => void`                | Called after handler completes                    |
 | `onSuccess`      | `(proc, c) => void`          | Called on successful handler execution            |
-| `error`          | `(proc, c, err) => Response` | Custom error handler (must return Response)       |
+| `onError`        | `(proc, c, err) => Response` | Imperative error handler (peer of `errors` taxonomy — see Error Handling) |
 
 ## Context Resolution
 

package/src/implementations/http/route-errors.test.ts

@@ -117,9 +117,9 @@ describe('per-route errors declaration', () => {
   })
 })
 
-describe('DocRegistry.fromTaxonomy', () => {
+describe('DocRegistry with taxonomy input', () => {
   test('seeds envelope errors from the taxonomy + framework defaults', () => {
-    const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+    const registry = new DocRegistry({ errors: appErrors, basePath: '/api' })
     const envelope = registry.toJSON()
     const names = envelope.errors.map((e) => e.name)
     expect(names).toContain('UseCaseError')
@@ -130,7 +130,7 @@ describe('DocRegistry.fromTaxonomy', () => {
   })
 
   test('includeDefaults: false omits framework entries', () => {
-    const registry = DocRegistry.fromTaxonomy(appErrors, { includeDefaults: false })
+    const registry = new DocRegistry({ errors: appErrors, includeDefaults: false })
     const names = registry.toJSON().errors.map((e) => e.name)
     expect(names).toEqual(['UseCaseError', 'AuthError'])
   })
@@ -143,11 +143,10 @@ describe('DocRegistry.fromTaxonomy', () => {
         description: 'custom override',
       },
     })
-    const envelope = DocRegistry.fromTaxonomy(overridden).toJSON()
+    const envelope = new DocRegistry({ errors: overridden }).toJSON()
     const proc = envelope.errors.find((e) => e.name === 'ProcedureError')
     expect(proc?.statusCode).toBe(418)
     expect(proc?.description).toBe('custom override')
-    // no duplicates
     const count = envelope.errors.filter((e) => e.name === 'ProcedureError').length
     expect(count).toBe(1)
   })
@@ -170,7 +169,7 @@ describe('DocRegistry.fromTaxonomy', () => {
     const app = new HonoAPIAppBuilder().register(API, () => ({}))
     app.build()
 
-    const envelope = DocRegistry.fromTaxonomy(appErrors).from(app).toJSON()
+    const envelope = new DocRegistry({ errors: appErrors }).from(app).toJSON()
     const route = envelope.routes.find((r) => r.kind === 'api' && r.name === 'GetUser')
     expect(route?.errors).toEqual(['UseCaseError'])
   })

package/src/implementations/types.ts

@@ -1,4 +1,5 @@
 import { Procedures } from '../index.js'
+import type { ErrorTaxonomy } from './http/error-taxonomy.js'
 
 /**
  * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`
@@ -186,7 +187,18 @@ export interface ErrorDoc {
 export interface DocRegistryConfig {
   basePath?: string
   headers?: HeaderDoc[]
-  errors?: ErrorDoc[]
+  /**
+   * Errors to document in the envelope. Accepts either your runtime
+   * {@link ErrorTaxonomy} (from `defineErrorTaxonomy`) — the common case — or
+   * a raw `ErrorDoc[]` for consumers who aren't using a taxonomy.
+   *
+   * Framework defaults (`ProcedureError`, `ProcedureValidationError`,
+   * `ProcedureYieldValidationError`, `ProcedureRegistrationError`) are merged
+   * in automatically and deduped. Opt out via `includeDefaults: false`.
+   */
+  errors?: ErrorTaxonomy | ErrorDoc[]
+  /** Whether to auto-merge framework error defaults. Defaults to `true`. */
+  includeDefaults?: boolean
 }
 
 export interface DocRegistryOutputOptions<TEnvelope = DocEnvelope> {