boom

@hapi/boom converts ordinary JavaScript errors into HTTP-friendly error objects. Rather than manually constructing a status code, error payload, and headers for every failure path, you call one of its status-specific factories (Boom.badRequest, Boom.notFound, Boom.internal, and dozens more) and get back a Boom-flavored Error whose output property already contains the correctly shaped response.

It originated as part of the hapi web framework’s error-handling layer and still integrates natively with hapi, but has no hard dependency on it — only @hapi/hoek is required at runtime, so any Node.js HTTP server can use it to standardize error responses, wrap unexpected exceptions via boomify(), and keep internal error messages from leaking to clients.

What You Get

• 30+ ready-made functions covering every standard 4xx and 5xx HTTP status code
• A consistent Boom error shape (message, output.statusCode, output.headers, output.payload) usable across any Node HTTP framework
• boomify() and isBoom() helpers for interoperating with plain Error objects and third-party Boom instances
• Hand-authored TypeScript type definitions validated by a dedicated type-test suite

Common Use Cases

• Returning structured HTTP errors from hapi route handlers
• Normalizing caught exceptions into client-safe API error responses
• Building 401 responses with WWW-Authenticate challenge headers
• Redacting internal error details from 500 responses in production

Under The Hood

Architecture Boom is a small, single-module library (src/index.js, ~365 lines) built around one core Boom class extending Error, with a private apply() helper that mutates the error’s output, and per-status-code factory functions (badRequest, notFound, internal, and dozens more) generated by a single statusError() higher-order function. Constructing or calling one of the exported functions invokes new Boom(), which calls apply() to build a BoomOutput instance holding statusCode/headers/payload; reformat() later rebuilds output.payload via a PayloadObject derived from the error’s current message, statusCode, and cause. There’s no external state, I/O, or configuration — the architecture is intentionally flat and minimal for a leaf utility library, though that also means the entire public surface funnels through two small factories, so any change to apply() ripples across every status helper at once.

Tech Stack package.json declares a single runtime dependency, @hapi/hoek (^12.0.0-rc.0), used only for its escapeHeaderAttribute helper. The package ships as native ESM (“type”: “module”), targets Node >=22, and hand-authors its TypeScript surface (src/index.d.ts) under a strict tsconfig with isolatedDeclarations rather than emitting types from a build step. Testing runs on vitest with v8 coverage, and linting/formatting use the Oxc toolchain (oxlint/oxfmt) instead of ESLint/Prettier. CI is configured via .github/workflows/ci-module.yml.

Code Quality test/index.js is an extensive vitest suite covering constructor variants, subclassing, isBoom, boomify, and every individual 4xx/5xx helper, including edge cases like custom headers, error causes, and JSON serialization. A separate typings.ts file exercises the public .d.ts surface with type-level assertions, showing the maintainers test their TypeScript types, not just runtime behavior. Source code throws explicit TypeErrors for invalid statusCode/headers arguments rather than silently coercing them, naming is consistent with HTTP semantics throughout, and lint/format/typecheck are all wired into the check script and CI.

What Makes It Unique Boom’s differentiator is treating HTTP status semantics as first-class: every exported helper directly encodes a status code and produces the correct response envelope, including protocol-specific details like assembling a spec-compliant WWW-Authenticate header for 401 responses and automatically hiding internal error messages behind a generic “An internal server error occurred” unless debug mode is explicitly enabled. It isn’t reinventing error handling broadly — it’s a narrow, well-executed convention library tightly coupled to HTTP response-formatting expectations rather than a novel abstraction.