ts-procedures 5.16.0 → 6.0.1

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'])
+  })
+})