ts-procedures 5.16.0 → 6.0.0

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

@@ -7,6 +7,11 @@ import type {
   ErrorDoc,
   HeaderDoc,
 } from '../types.js'
+import {
+  ErrorTaxonomy,
+  defaultErrorTaxonomy,
+  taxonomyToErrorDocs,
+} from './error-taxonomy.js'
 
 export type {
   AnyHttpRouteDoc,
@@ -18,6 +23,27 @@ export type {
   HeaderDoc,
 } from '../types.js'
 
+/**
+ * `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.
+ */
+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'],
+  },
+}
+
 export class DocRegistry {
   private readonly basePath: string
   private readonly headers: HeaderDoc[]
@@ -56,88 +82,45 @@ export class DocRegistry {
     return envelope as T
   }
 
-  // Keep in sync with src/errors.ts
+  /**
+   * 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.
+   */
   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,
+    ]
+  }
+
+  /**
+   * 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.test.ts

@@ -0,0 +1,438 @@
+import { describe, expect, test } from 'vitest'
+import {
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureYieldValidationError,
+} from '../../errors.js'
+import type { TProcedureRegistration } from '../../index.js'
+import {
+  defineErrorTaxonomy,
+  resolveErrorResponse,
+  defaultErrorTaxonomy,
+} from './error-taxonomy.js'
+
+class UseCaseError extends Error {
+  constructor(
+    readonly externalMsg: string,
+    readonly internalMsg: string
+  ) {
+    super(externalMsg)
+    this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+class AuthError extends Error {
+  constructor(readonly reason: 'unauthenticated' | 'forbidden') {
+    super(reason)
+    this.name = 'AuthError'
+    Object.setPrototypeOf(this, AuthError.prototype)
+  }
+}
+
+const fakeProcedure = { name: 'Test', config: {}, handler: async () => {} } as unknown as TProcedureRegistration
+
+describe('defineErrorTaxonomy', () => {
+  test('validates exactly one discriminator per entry', () => {
+    expect(() =>
+      defineErrorTaxonomy({
+        Bad: { statusCode: 400 } as any,
+      })
+    ).toThrow(/exactly one of/)
+
+    expect(() =>
+      defineErrorTaxonomy({
+        Bad: {
+          class: Error,
+          match: (e: unknown): e is Error => e instanceof Error,
+          statusCode: 400,
+        } as any,
+      })
+    ).toThrow(/exactly one of/)
+  })
+
+  test('accepts a valid entry', () => {
+    const t = defineErrorTaxonomy({
+      UseCaseError: { class: UseCaseError, statusCode: 422 },
+    })
+    expect(t.UseCaseError.statusCode).toBe(422)
+  })
+})
+
+describe('resolveErrorResponse', () => {
+  test('class match uses toResponse output', () => {
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: new UseCaseError('external', 'internal'),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(422)
+    expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'external' })
+  })
+
+  test('match predicate catches 3rd-party errors', () => {
+    const mongoLike = Object.assign(new Error('dup'), { name: 'MongoServerError', code: 11000 })
+    const taxonomy = defineErrorTaxonomy({
+      MongoDuplicateKey: {
+        match: (e): e is Error => e instanceof Error && (e as any).code === 11000,
+        statusCode: 409,
+        toResponse: () => ({ name: 'Conflict' }),
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: mongoLike,
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(409)
+    expect(resolved?.body).toEqual({ name: 'Conflict' })
+  })
+
+  test('default toResponse emits { name, message } from entry key', () => {
+    const taxonomy = defineErrorTaxonomy({
+      AuthError: { class: AuthError, statusCode: 401 },
+    })
+    const resolved = resolveErrorResponse({
+      err: new AuthError('unauthenticated'),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.body).toEqual({ name: 'AuthError', message: 'unauthenticated' })
+  })
+
+  test('first matching entry wins — subclass declared before base', () => {
+    const taxonomy = defineErrorTaxonomy({
+      ProcedureValidationError: {
+        class: ProcedureValidationError,
+        statusCode: 400,
+        toResponse: () => ({ kind: 'validation' }),
+      },
+      ProcedureError: {
+        class: ProcedureError,
+        statusCode: 500,
+        toResponse: () => ({ kind: 'base' }),
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: new ProcedureValidationError('Test', 'bad', []),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      includeDefaults: false,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(400)
+    expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' })
+  })
+
+  test('topological sort fixes a subclass that was declared after its base', () => {
+    // Under first-match-wins without sorting, the base would catch the
+    // subclass. defineErrorTaxonomy reorders to keep the subclass entry first.
+    const taxonomy = defineErrorTaxonomy({
+      ProcedureError: {
+        class: ProcedureError,
+        statusCode: 500,
+        toResponse: () => ({ kind: 'base' }),
+      },
+      ProcedureValidationError: {
+        class: ProcedureValidationError,
+        statusCode: 400,
+        toResponse: () => ({ kind: 'validation' }),
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: new ProcedureValidationError('Test', 'bad', []),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      includeDefaults: false,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(400)
+    expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' })
+  })
+
+  test('falls through to unknownError when nothing matches', () => {
+    const resolved = resolveErrorResponse({
+      err: new Error('boom'),
+      userTaxonomy: defineErrorTaxonomy({
+        AuthError: { class: AuthError, statusCode: 401 },
+      }),
+      includeDefaults: false,
+      unknownError: {
+        statusCode: 500,
+        toResponse: () => ({ name: 'InternalServerError' }),
+      },
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(500)
+    expect(resolved?.body).toEqual({ name: 'InternalServerError' })
+  })
+
+  test('returns null when nothing matches and no unknownError', () => {
+    const resolved = resolveErrorResponse({
+      err: new Error('boom'),
+      userTaxonomy: defineErrorTaxonomy({
+        AuthError: { class: AuthError, statusCode: 401 },
+      }),
+      includeDefaults: false,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved).toBeNull()
+  })
+
+  test('default taxonomy catches ProcedureValidationError with status 400', () => {
+    const resolved = resolveErrorResponse({
+      err: new ProcedureValidationError('Test', 'bad', []),
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(400)
+    expect((resolved?.body as any).name).toBe('ProcedureValidationError')
+  })
+
+  test('default taxonomy catches ProcedureYieldValidationError with status 500', () => {
+    const resolved = resolveErrorResponse({
+      err: new ProcedureYieldValidationError('Test', 'bad yield', []),
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(500)
+    expect((resolved?.body as any).name).toBe('ProcedureYieldValidationError')
+  })
+
+  test('includeDefaults: false disables the default taxonomy', () => {
+    const resolved = resolveErrorResponse({
+      err: new ProcedureValidationError('Test', 'bad', []),
+      includeDefaults: false,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved).toBeNull()
+  })
+
+  test('user entry overrides default for the same class', () => {
+    const resolved = resolveErrorResponse({
+      err: new ProcedureValidationError('Test', 'bad', []),
+      userTaxonomy: defineErrorTaxonomy({
+        ProcedureValidationError: {
+          class: ProcedureValidationError,
+          statusCode: 418,
+          toResponse: () => ({ overridden: true }),
+        },
+      }),
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(418)
+    expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', overridden: true })
+  })
+
+  test('onCatch is awaited via runOnCatch', async () => {
+    const calls: string[] = []
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        onCatch: async (err) => {
+          await new Promise((r) => setTimeout(r, 5))
+          calls.push(err.internalMsg)
+        },
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: new UseCaseError('ext', 'internal-log'),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(calls).toEqual([])
+    await resolved!.runOnCatch()
+    expect(calls).toEqual(['internal-log'])
+  })
+
+  test('unknownError onCatch is awaited', async () => {
+    const calls: unknown[] = []
+    const resolved = resolveErrorResponse({
+      err: new Error('boom'),
+      includeDefaults: false,
+      unknownError: {
+        toResponse: () => ({}),
+        onCatch: async (err) => {
+          await Promise.resolve()
+          calls.push(err)
+        },
+      },
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    await resolved!.runOnCatch()
+    expect(calls).toHaveLength(1)
+    expect((calls[0] as Error).message).toBe('boom')
+  })
+
+  test('onCatch receives procedure, key and raw', async () => {
+    let received: any
+    const taxonomy = defineErrorTaxonomy({
+      AuthError: {
+        class: AuthError,
+        statusCode: 401,
+        onCatch: (_err, ctx) => {
+          received = ctx
+        },
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: new AuthError('forbidden'),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: { marker: 'hono-context' },
+    })
+    await resolved!.runOnCatch()
+    expect(received.procedure).toBe(fakeProcedure)
+    expect(received.key).toBe('AuthError')
+    expect(received.raw).toEqual({ marker: 'hono-context' })
+  })
+
+  test('defaultErrorTaxonomy exposes all four framework error mappings', () => {
+    expect(defaultErrorTaxonomy.ProcedureValidationError.statusCode).toBe(400)
+    expect(defaultErrorTaxonomy.ProcedureYieldValidationError.statusCode).toBe(500)
+    expect(defaultErrorTaxonomy.ProcedureError.statusCode).toBe(500)
+  })
+
+  test('user taxonomy matches cause inside a ProcedureError wrapper', () => {
+    // Simulates what the core does when a non-ProcedureError is thrown: wraps
+    // into ProcedureError with `cause` preserved.
+    const original = new UseCaseError('public', 'private')
+    const wrapped = new ProcedureError('Test', 'wrapped')
+    ;(wrapped as any).cause = original
+
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+
+    const resolved = resolveErrorResponse({
+      err: wrapped,
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(422)
+    expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'public' })
+  })
+
+  test('wrapped ProcedureError falls through default taxonomy to unknownError', () => {
+    const original = new TypeError('db-broke')
+    const wrapped = new ProcedureError('Test', 'wrapped')
+    ;(wrapped as any).cause = original
+
+    const resolved = resolveErrorResponse({
+      err: wrapped,
+      unknownError: {
+        statusCode: 500,
+        toResponse: (err) => ({ name: 'InternalServerError', type: (err as Error).constructor.name }),
+      },
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(500)
+    expect(resolved?.body).toEqual({ name: 'InternalServerError', type: 'TypeError' })
+  })
+
+  test('direct ProcedureError (no cause) still caught by default entry', () => {
+    const direct = new ProcedureError('Test', 'from ctx.error')
+    const resolved = resolveErrorResponse({
+      err: direct,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(500)
+    expect((resolved?.body as any).name).toBe('ProcedureError')
+  })
+
+  test('auto-injects name when toResponse omits it', () => {
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        // Returns a body without `name` — resolver should add one.
+        toResponse: (err) => ({ message: err.externalMsg, detail: err.internalMsg }),
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: new UseCaseError('ext', 'int'),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'ext', detail: 'int' })
+  })
+
+  test('preserves explicit name in toResponse output', () => {
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: () => ({ name: 'CustomAlias', reason: 'x' }),
+      },
+    })
+    const resolved = resolveErrorResponse({
+      err: new UseCaseError('ext', 'int'),
+      userTaxonomy: taxonomy,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect((resolved?.body as any).name).toBe('CustomAlias')
+  })
+
+  test('defineErrorTaxonomy topologically sorts class entries (subclass before base)', () => {
+    // Declared base-before-subclass on purpose — sort must swap them.
+    const taxonomy = defineErrorTaxonomy({
+      ProcedureError: {
+        class: ProcedureError,
+        statusCode: 500,
+        toResponse: () => ({ kind: 'base' }),
+      },
+      ProcedureValidationError: {
+        class: ProcedureValidationError,
+        statusCode: 400,
+        toResponse: () => ({ kind: 'validation' }),
+      },
+    })
+    const keys = Object.keys(taxonomy)
+    expect(keys).toEqual(['ProcedureValidationError', 'ProcedureError'])
+
+    const resolved = resolveErrorResponse({
+      err: new ProcedureValidationError('Test', 'bad', []),
+      userTaxonomy: taxonomy,
+      includeDefaults: false,
+      procedure: fakeProcedure,
+      raw: {},
+    })
+    expect(resolved?.statusCode).toBe(400)
+  })
+
+  test('topological sort preserves declared order for unrelated classes', () => {
+    class A extends Error {}
+    class B extends Error {}
+    const taxonomy = defineErrorTaxonomy({
+      B: { class: B, statusCode: 400 },
+      A: { class: A, statusCode: 400 },
+    })
+    expect(Object.keys(taxonomy)).toEqual(['B', 'A'])
+  })
+})