http-status-codes

http-status-codes is a small, dependency-free TypeScript library that enumerates every HTTP status code defined across RFC1945, RFC2616, RFC7231, RFC2518, RFC6585, RFC7538, and RFC8297, pairing each numeric code with its constant name and human-readable reason phrase. It ships a StatusCodes object, a matching ReasonPhrases object, and two lookup helpers, getReasonPhrase and getStatusCode, that convert between codes and phrases at runtime and throw a descriptive error when given something that isn’t a real HTTP status.

Because the whole library is generated from a single codes.json source of truth via a build script, the mapping stays consistent between the modern StatusCodes/ReasonPhrases exports and the legacy flat constants kept for v1 backward compatibility. It has zero runtime dependencies, ships both CJS and ES module builds, and is framework-agnostic, equally at home wired into an Express response, a Fastify handler, or a plain Node HTTP server.

What You Get

• A StatusCodes object covering every status code from 100 Continue through 511 Network Authentication Required, including WebDAV (RFC2518) and rate-limiting (RFC6585) codes
• A matching ReasonPhrases object so status messages are never hardcoded as raw strings
• getReasonPhrase(code) and getStatusCode(phrase) helpers that throw a clear error instead of silently returning undefined for invalid input
• Dual CJS/ESM builds with full TypeScript typings and zero runtime dependencies
• Legacy flat-constant exports (e.g. HttpStatus.OK) preserved for drop-in v1 compatibility

Common Use Cases

• Setting Express/Koa/Fastify response codes with response.status(StatusCodes.OK) instead of a magic number
• Returning consistent error payloads by pairing StatusCodes.NOT_FOUND with ReasonPhrases.NOT_FOUND
• Validating or normalizing an externally-supplied status code via getReasonPhrase()’s thrown error
• Writing HTTP client or test assertions against named constants instead of raw numbers for readability

Under The Hood

Architecture The whole library is a thin, flat module: src/index.ts composes exports from status-codes.ts (a generated TypeScript enum), reason-phrases.ts (a parallel generated enum of phrases), utils.ts (generated lookup maps in each direction), utils-functions.ts (two small wrapper functions that index into those maps and throw on a miss), and legacy.ts (flat, individually-deprecated constants kept for v1 backward compatibility, merged into a default export alongside the two helper functions). There is no runtime layering to speak of, since this is a data-plus-accessor module rather than an application; everything downstream of codes.json is code-generated by a dedicated script, so the meaningful architectural decision is keeping generated data cleanly separated from hand-written accessor and compatibility logic.

Tech Stack Written in TypeScript targeting ES5, built as separate CJS and ESM outputs via two dedicated tsc configs run from a build script. The package has zero runtime dependencies; its devDependencies cover testing (Jest with ts-jest), linting (ESLint with an Airbnb TypeScript config), and a code-generation toolchain (ts-node, ts-morph, markdown-table, fs-extra) that powers a script regenerating the enums and lookup maps, and the README’s status-code table, from a single JSON source file. It publishes to npm as a dual CJS/ESM library consumable from any Node.js runtime or bundler, with a standard GitHub Actions workflow running install-and-test across a Node version matrix.

Code Quality Tests exist and are meaningful rather than incidental: the Jest suite specifically asserts backward compatibility between the legacy v1 constants and the current API for every code in the generated data set, including the one deliberate breaking change in the 500 reason phrase. Error handling is explicit and typed, with the lookup helpers throwing descriptive errors on invalid input instead of returning undefined. Naming is consistent SCREAMING_SNAKE_CASE matching RFC terminology, and the project is authored in strict-mode TypeScript. Linting is configured via ESLint, though the CI workflow only runs the test script, not lint, and the CI Node version matrix is dated relative to the current LTS lineup.

API Design The library’s entire value proposition is developer ergonomics: replace magic numbers like response.status(200) with self-documenting constants, paired with matching reason-phrase constants so status text is never hand-typed either. The surface area is minimal and predictable, just two constant objects and two functions, with zero configuration required beyond installing and importing. It also handles its own migration story explicitly, keeping old flat constants working after the v2 redesign and calling out the one intentional breaking change prominently in the README rather than leaving it as a silent surprise. The underlying idea, typed status-code constants, is a well-trodden pattern across ecosystems (the project itself credits the Java Apache HttpClient API as its model), but the execution is unusually thorough for what is nominally “just a package of constants.”