HTTP Status Codes Mapper

1.1.4 verified Thu Apr 23 auth: no javascript

http-sts (HTTP Status Codes) is a JavaScript/TypeScript library designed to provide a comprehensive and structured collection of HTTP status codes. It maps each code to an object containing its numeric value, a human-readable name, and a detailed description directly sourced from MDN Web Docs. Currently at version 1.1.4, the package offers a stable and reliable way to access information for a wide range of HTTP responses, from informational (1xx) to server error (5xx) codes. Unlike simpler enumeration libraries, http-sts provides rich, descriptive content for each status code, making it suitable for applications that require more than just the code number or a basic name. Its release cadence is generally stable, with updates primarily reflecting changes or additions to HTTP status codes on MDN. Key differentiators include the depth of information provided and its direct lineage from an authoritative source like MDN, ensuring accuracy and detail.

Common errors

error TypeError: Cannot read properties of undefined (reading 'name') ↓

cause Attempting to access a status code that does not exist or using incorrect property access (e.g., `HTTPStatusCodes.CODE_999` or `HTTPStatusCodes[200].name`).

fix

Ensure you are using a valid CODE_XXX property name from the HTTPStatusCodes object. Verify the status code actually exists in the library. If using a numeric value, ensure it's correctly mapped to its CODE_XXX string representation.

error ReferenceError: require is not defined ↓

cause Attempting to use `require()` syntax in an ESM-only context (e.g., a modern Node.js module with `"type": "module"` in `package.json` or a browser environment).

fix

Switch to ESM import statements: import { HTTPStatusCodes } from 'http-sts';. Ensure your project is configured for ESM if you intend to use it, or stick to CommonJS require if your environment explicitly supports it.

Warnings

gotcha Direct numeric access like `HTTPStatusCodes[200]` will not work as expected. Status codes are exposed as named properties, e.g., `HTTPStatusCodes.CODE_200`. ↓

fix Always access status codes using their `CODE_XXX` property names (e.g., `HTTPStatusCodes.CODE_404`). If you need to map a number to a code, you'll need to create a helper function or map over the `HTTPStatusCodes` object.

gotcha The descriptions provided are direct extracts from MDN Web Docs. While generally stable, they are subject to changes on MDN and are embedded at the time of the package's release. Relying on the *exact* string content for parsing or strict comparisons is not recommended. ↓

fix Use the `code` and `name` properties for programmatic logic. Treat `description` as display-only content. Periodically update the package to get the latest MDN descriptions.

Install

npm install http-sts

yarn add http-sts

pnpm add http-sts

Imports

HTTPStatusCodes
wrong
```
const HTTPStatusCodes = require('http-sts').HTTPStatusCodes;
```
correct
```
import { HTTPStatusCodes } from 'http-sts';
```
This is the main object containing all status code definitions as named properties (e.g., `CODE_200`). Modern projects should prefer ESM imports.
HTTPStatusCodeType
wrong
```
import { HTTPStatusCodeType } from 'http-sts';
```
correct
```
import type { HTTPStatusCodeType } from 'http-sts';
```
Use `import type` for importing only the TypeScript type definition, preventing it from being bundled into JavaScript output.
CODE_200
wrong
```
import HTTPStatusCodes from 'http-sts'; console.log(HTTPStatusCodes.CODE_200);
```
correct
```
import { CODE_200 } from 'http-sts';
```
Individual status code objects can be imported directly if only a few specific codes are needed, improving tree-shaking.

Quickstart

Demonstrates how to import and access individual HTTP status code objects, including their code, name, and description. It also shows how to iterate through all available codes and conceptual usage in a web server context.

import { HTTPStatusCodes, HTTPStatusCodeType } from 'http-sts';

// Access a specific status code object
const okStatus: HTTPStatusCodeType = HTTPStatusCodes.CODE_200;
console.log(`Code: ${okStatus.code}`);
console.log(`Name: ${okStatus.name}`);
console.log(`Description: ${okStatus.description}`);

// Iterate over all available status codes (for documentation or internal mapping)
console.log('\nAll HTTP Status Codes:');
for (const key in HTTPStatusCodes) {
  const statusCode = HTTPStatusCodes[key as keyof typeof HTTPStatusCodes];
  console.log(`- ${statusCode.code}: ${statusCode.name}`);
}

// Example of using a specific code in a response (conceptual, depends on framework)
function sendResponse(res: any, status: HTTPStatusCodeType, message: string) {
  console.log(`
Sending response with status ${status.code} - ${status.name}: ${message}`);
  // In a real scenario: res.status(status.code).send(message);
}

sendResponse({}, HTTPStatusCodes.CODE_404, 'Resource not found.');