ts-procedures 5.16.0 → 6.0.1

package/build/implementations/http/error-taxonomy.js

@@ -0,0 +1,252 @@
+import { ProcedureError, ProcedureValidationError, ProcedureYieldValidationError, } from '../../errors.js';
+/**
+ * Identity helper that preserves literal inference and:
+ * 1. validates each entry has exactly one discriminator (`class` xor `match`);
+ * 2. topologically sorts `class:` entries so subclasses precede base classes.
+ *
+ * The sort is stable — entries unrelated by inheritance keep their declared
+ * order. Predicate entries (with `match:`) always keep declared order relative
+ * to class entries, so a predicate that's intentionally narrower can be placed
+ * before a class entry to take precedence.
+ */
+export function defineErrorTaxonomy(entries) {
+    const pairs = Object.entries(entries);
+    for (const [key, entry] of pairs) {
+        const hasClass = entry.class !== undefined;
+        const hasMatch = entry.match !== undefined;
+        if (hasClass === hasMatch) {
+            throw new Error(`Error taxonomy entry "${key}" must define exactly one of { class, match }.`);
+        }
+    }
+    // Stable sort: subclass-of-the-other → -1, other-subclass-of-this → 1, else 0.
+    pairs.sort(([, a], [, b]) => {
+        if (!a.class || !b.class)
+            return 0;
+        if (a.class === b.class)
+            return 0;
+        if (a.class.prototype instanceof b.class)
+            return -1;
+        if (b.class.prototype instanceof a.class)
+            return 1;
+        return 0;
+    });
+    return Object.fromEntries(pairs);
+}
+/**
+ * Default taxonomy covering framework error classes that can be thrown by a
+ * handler at request time. Layered after the user taxonomy during resolution.
+ *
+ * `ProcedureError` uses `match:` rather than `class:` so it matches only
+ * direct throws (e.g. from `ctx.error()`). When the core wraps a non-ProcedureError
+ * into a ProcedureError with `cause`, that wrapper falls through — the
+ * resolver unwraps the cause and the user taxonomy / `unknownError` sees the
+ * real thrown value.
+ */
+export const defaultErrorTaxonomy = defineErrorTaxonomy({
+    ProcedureValidationError: {
+        class: ProcedureValidationError,
+        statusCode: 400,
+        description: 'Schema validation failed for the procedure input parameters.',
+        toResponse: (err) => ({
+            name: 'ProcedureValidationError',
+            procedureName: err.procedureName,
+            message: err.message,
+            errors: err.errors,
+        }),
+        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'],
+        },
+    },
+    ProcedureYieldValidationError: {
+        class: ProcedureYieldValidationError,
+        statusCode: 500,
+        description: 'Schema validation failed for a yielded value in a streaming procedure.',
+        toResponse: (err) => ({
+            name: 'ProcedureYieldValidationError',
+            procedureName: err.procedureName,
+            message: err.message,
+            errors: err.errors,
+        }),
+        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'],
+        },
+    },
+    ProcedureError: {
+        match: (err) => err instanceof ProcedureError && err.cause === undefined,
+        statusCode: 500,
+        description: 'An error thrown from within a procedure handler via ctx.error().',
+        toResponse: (err) => ({
+            name: 'ProcedureError',
+            procedureName: err.procedureName,
+            message: err.message,
+            meta: err.meta,
+        }),
+        schema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', const: 'ProcedureError' },
+                procedureName: { type: 'string' },
+                message: { type: 'string' },
+                meta: { type: 'object' },
+            },
+            required: ['name', 'procedureName', 'message'],
+        },
+    },
+});
+/**
+ * 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 = {
+    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.
+ *
+ * @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) {
+    return Object.entries(taxonomy).map(([key, entry]) => ({
+        name: key,
+        statusCode: entry.statusCode,
+        description: entry.description ?? '',
+        schema: entry.schema,
+    }));
+}
+/**
+ * Injects `{ name: key }` when `rawBody` is an object without a `name` field.
+ * Guarantees wire-protocol consistency (client dispatchers discriminate on
+ * `body.name`) without forcing every `toResponse` to repeat it.
+ */
+function ensureName(rawBody, key) {
+    if (rawBody && typeof rawBody === 'object' && !('name' in rawBody)) {
+        return { name: key, ...rawBody };
+    }
+    return rawBody;
+}
+/**
+ * Matches a thrown value against the user taxonomy, then (if `includeDefaults`)
+ * the default taxonomy, then the `unknownError` config. Returns `null` when
+ * nothing matches — callers fall through to their builder's imperative
+ * `onError` callback and the hard default.
+ *
+ * The core wraps any non-ProcedureError thrown by a handler into a
+ * ProcedureError with `cause` set to the original. This resolver unwraps that:
+ * candidates are checked in the order `[cause, outer]` so a user taxonomy sees
+ * its own error classes rather than the wrapper. The default `ProcedureError`
+ * entry uses a `match:` predicate that excludes wrappers so they reach
+ * `unknownError` instead.
+ *
+ * Side effects (`onCatch`) are deferred into `runOnCatch` so the caller decides
+ * when to execute them relative to writing the response.
+ */
+export function resolveErrorResponse(params) {
+    const { err, userTaxonomy, includeDefaults = true, unknownError, procedure, raw, } = params;
+    const wrappedCause = err instanceof ProcedureError && err.cause !== undefined
+        ? err.cause
+        : undefined;
+    // Most-specific candidate first so a matching user entry on `cause` wins over
+    // a matching entry on the outer wrapper.
+    const candidates = wrappedCause !== undefined ? [wrappedCause, err] : [err];
+    const tryMatch = (tax) => {
+        for (const [key, entry] of Object.entries(tax)) {
+            for (const candidate of candidates) {
+                const matched = entry.class
+                    ? candidate instanceof entry.class
+                    : entry.match
+                        ? entry.match(candidate)
+                        : false;
+                if (!matched)
+                    continue;
+                const rawBody = entry.toResponse
+                    ? entry.toResponse(candidate, { key })
+                    : {
+                        name: key,
+                        message: candidate instanceof Error ? candidate.message : String(candidate),
+                    };
+                const body = ensureName(rawBody, key);
+                return {
+                    statusCode: entry.statusCode,
+                    body,
+                    runOnCatch: async () => {
+                        if (entry.onCatch) {
+                            await entry.onCatch(candidate, { procedure, key, raw });
+                        }
+                    },
+                };
+            }
+        }
+        return null;
+    };
+    if (userTaxonomy) {
+        const hit = tryMatch(userTaxonomy);
+        if (hit)
+            return hit;
+    }
+    if (includeDefaults) {
+        const hit = tryMatch(defaultErrorTaxonomy);
+        if (hit)
+            return hit;
+    }
+    if (unknownError) {
+        const mostSpecific = candidates[0];
+        return {
+            statusCode: unknownError.statusCode ?? 500,
+            body: unknownError.toResponse(mostSpecific),
+            runOnCatch: async () => {
+                if (unknownError.onCatch) {
+                    await unknownError.onCatch(mostSpecific, { procedure, raw });
+                }
+            },
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=error-taxonomy.js.map

package/build/implementations/http/error-taxonomy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-taxonomy.js","sourceRoot":"","sources":["../../../src/implementations/http/error-taxonomy.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/error-taxonomy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/implementations/http/error-taxonomy.test.js

@@ -0,0 +1,399 @@
+import { describe, expect, test } from 'vitest';
+import { ProcedureError, ProcedureValidationError, ProcedureYieldValidationError, } from '../../errors.js';
+import { defineErrorTaxonomy, resolveErrorResponse, defaultErrorTaxonomy, } from './error-taxonomy.js';
+class UseCaseError extends Error {
+    externalMsg;
+    internalMsg;
+    constructor(externalMsg, internalMsg) {
+        super(externalMsg);
+        this.externalMsg = externalMsg;
+        this.internalMsg = internalMsg;
+        this.name = 'UseCaseError';
+        Object.setPrototypeOf(this, UseCaseError.prototype);
+    }
+}
+class AuthError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = 'AuthError';
+        Object.setPrototypeOf(this, AuthError.prototype);
+    }
+}
+const fakeProcedure = { name: 'Test', config: {}, handler: async () => { } };
+describe('defineErrorTaxonomy', () => {
+    test('validates exactly one discriminator per entry', () => {
+        expect(() => defineErrorTaxonomy({
+            Bad: { statusCode: 400 },
+        })).toThrow(/exactly one of/);
+        expect(() => defineErrorTaxonomy({
+            Bad: {
+                class: Error,
+                match: (e) => e instanceof Error,
+                statusCode: 400,
+            },
+        })).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 instanceof Error && e.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).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).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 = [];
+        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 = [];
+        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].message).toBe('boom');
+    });
+    test('onCatch receives procedure, key and raw', async () => {
+        let received;
+        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.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.cause = original;
+        const resolved = resolveErrorResponse({
+            err: wrapped,
+            unknownError: {
+                statusCode: 500,
+                toResponse: (err) => ({ name: 'InternalServerError', type: err.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).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).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']);
+    });
+});
+//# sourceMappingURL=error-taxonomy.test.js.map