node-http-status

http-status is a lightweight TypeScript library that maps HTTP status codes to their names, descriptive messages, and response classes (1xx-5xx), plus the reverse lookup from name to code. Beyond the standard IANA registry, it bundles extra status codes used by IIS, NGINX, and Cloudflare, each importable as an isolated module so consumers only pull in what they need.

Originally an Adaltas project dating back to 2011, version 2 rewrote the library in TypeScript with dual ESM/CommonJS builds via tsup, while preserving the same flat object API that made it a drop-in companion for Express and other Node.js HTTP frameworks.

What You Get

• Full IANA status code table - every HTTP status code from the IANA registry, including the joke 418 I’m a teapot, exposed as named constants.
• Bidirectional lookups - resolve a code to its name (status[500]), or a name to its code (status.INTERNAL_SERVER_ERROR), without maintaining your own mapping table.
• Status classes - _CLASS properties group any code into its 1xx-5xx class, useful for switch-based response handling.
• Vendor extra codes - IIS, NGINX, and Cloudflare-specific codes available as separate importable modules (http-status/nginx, etc.) so they don’t bloat the default import.
• Dual module support - published as both ESM and CommonJS builds from a single TypeScript source, generated with tsup.

Common Use Cases

• Express/Node API responses - use status.OK or status.NOT_FOUND instead of hardcoded numeric literals when calling res.send() or res.status().
• Human-readable error messages - look up status['404_MESSAGE'] to surface a spec-accurate description in logs or API error payloads.
• Response class branching - switch on status['x_CLASS'] to route 4xx vs 5xx responses to different handling logic.
• Reverse proxy/CDN status handling - import the cloudflare or nginx submodule to interpret vendor-specific status codes from upstream infrastructure.

Under The Hood

Architecture The entire library is a single declarative data structure rather than layered code: src/index.ts builds one large status object where each HTTP code contributes a numeric key, a _NAME, a _MESSAGE, and a _CLASS derived from a shared classes map, with named constants (e.g. CREATED) pointing back to the numeric code. Vendor-specific extensions (cloudflare.ts, iis.ts, nginx.ts, unofficial.ts) are separate flat files exported as their own tsup entry points and only merged into the default table when a consumer imports http-status/<category> directly, so extending the vendor set means adding another file and build entry rather than touching shared logic.

Tech Stack Written in TypeScript targeting esnext with strict mode enabled, built via tsup into dual ESM and CommonJS bundles with generated .d.ts declarations and code splitting, and shipped with zero runtime dependencies. Tooling includes ESLint 9’s flat config with typescript-eslint and eslint-plugin-mocha, Prettier enforced through Husky + lint-staged pre-commit hooks, commitlint paired with standard-version for conventional-commit-driven releases, and Mocha with the should assertion library run through ts-node’s ESM loader. GitHub Actions runs the test suite across a Node 16/20/22 matrix before publishing to npm on a version tag.

Code Quality The test suite (test/codes.ts, classes.ts, extra.ts, types.ts) doesn’t just spot-check a handful of codes — it recursively walks the entire exported object and asserts that every numeric status code’s _CLASS value matches its first digit, a structural invariant check that would catch a bad manual edit anywhere in the table. Strict TypeScript, linting, and pre-commit formatting are all enforced project-wide, and combined with the multi-version Node CI matrix this is a well-guarded setup for a project of this size.

What Makes It Unique The core idea, a flat HTTP status-code lookup object, is a well-established pattern with several prior implementations in the ecosystem; this package’s distinguishing choices are namespacing extra non-IANA vendor codes (IIS, NGINX, Cloudflare, plus a general “unofficial” set) into separate importable submodules so consumers only pay for what they use, and completing an ESM/CommonJS dual-publish migration to TypeScript in v2 while preserving the original flat-key API shape from its pre-TypeScript incarnation.