ts-procedures 5.16.0 → 6.0.1

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)
@@ -263,20 +265,24 @@ describe('DocRegistry', () => {
 
     test('has correct error names', () => {
       const names = DocRegistry.defaultErrors().map((e) => e.name)
+      // Runtime errors come from the taxonomy (topologically sorted —
+      // subclasses first), followed by the doc-only registration error.
       expect(names).toEqual([
-        'ProcedureError',
         'ProcedureValidationError',
         'ProcedureYieldValidationError',
+        'ProcedureError',
         'ProcedureRegistrationError',
       ])
     })
 
     test('has correct status codes', () => {
-      const errors = DocRegistry.defaultErrors()
-      expect(errors[0]!.statusCode).toBe(500) // ProcedureError
-      expect(errors[1]!.statusCode).toBe(400) // ProcedureValidationError
-      expect(errors[2]!.statusCode).toBe(500) // ProcedureYieldValidationError
-      expect(errors[3]!.statusCode).toBe(500) // ProcedureRegistrationError
+      const byName = Object.fromEntries(
+        DocRegistry.defaultErrors().map((e) => [e.name, e.statusCode])
+      )
+      expect(byName.ProcedureError).toBe(500)
+      expect(byName.ProcedureValidationError).toBe(400)
+      expect(byName.ProcedureYieldValidationError).toBe(500)
+      expect(byName.ProcedureRegistrationError).toBe(500)
     })
 
     test('each entry has schema', () => {
@@ -294,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
   // --------------------------------------------------------------------------
@@ -329,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]))
@@ -343,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]))
@@ -368,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

@@ -7,6 +7,12 @@ import type {
   ErrorDoc,
   HeaderDoc,
 } from '../types.js'
+import {
+  PROCEDURE_REGISTRATION_ERROR_DOC,
+  defaultErrorTaxonomy,
+  taxonomyToErrorDocs,
+  type ErrorTaxonomy,
+} from './error-taxonomy.js'
 
 export type {
   AnyHttpRouteDoc,
@@ -18,16 +24,44 @@ export type {
   HeaderDoc,
 } from '../types.js'
 
+function isTaxonomy(input: ErrorTaxonomy | ErrorDoc[]): input is ErrorTaxonomy {
+  return !Array.isArray(input)
+}
+
+/**
+ * Dedupes ErrorDocs by `name`, last occurrence wins. Map insertion order
+ * preserves the latest position of each name.
+ */
+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 {
@@ -35,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)
 
@@ -56,88 +102,18 @@ export class DocRegistry {
     return envelope as T
   }
 
-  // Keep in sync with src/errors.ts
+  /**
+   * 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 [
-      {
-        name: 'ProcedureError',
-        statusCode: 500,
-        description: 'An error thrown from within a procedure handler via ctx.error().',
-        schema: {
-          type: 'object',
-          properties: {
-            name: { type: 'string', const: 'ProcedureError' },
-            procedureName: { type: 'string' },
-            message: { type: 'string' },
-            meta: { type: 'object' },
-          },
-          required: ['name', 'procedureName', 'message'],
-        },
-      },
-      {
-        name: 'ProcedureValidationError',
-        statusCode: 400,
-        description: 'Schema validation failed for the procedure input parameters.',
-        schema: {
-          type: 'object',
-          properties: {
-            name: { type: 'string', const: 'ProcedureValidationError' },
-            procedureName: { type: 'string' },
-            message: { type: 'string' },
-            errors: {
-              type: 'array',
-              items: {
-                type: 'object',
-                properties: {
-                  instancePath: { type: 'string' },
-                  message: { type: 'string' },
-                },
-              },
-            },
-          },
-          required: ['name', 'procedureName', 'message'],
-        },
-      },
-      {
-        name: 'ProcedureYieldValidationError',
-        statusCode: 500,
-        description:
-          'Schema validation failed for a yielded value in a streaming procedure.',
-        schema: {
-          type: 'object',
-          properties: {
-            name: { type: 'string', const: 'ProcedureYieldValidationError' },
-            procedureName: { type: 'string' },
-            message: { type: 'string' },
-            errors: {
-              type: 'array',
-              items: {
-                type: 'object',
-                properties: {
-                  instancePath: { type: 'string' },
-                  message: { type: 'string' },
-                },
-              },
-            },
-          },
-          required: ['name', 'procedureName', 'message'],
-        },
-      },
-      {
-        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'],
-        },
-      },
+      ...taxonomyToErrorDocs(defaultErrorTaxonomy),
+      PROCEDURE_REGISTRATION_ERROR_DOC,
     ]
   }
 }