HTTP Status Codes for TypeScript

2.0.1 · active · verified Tue Apr 21

http-status-ts is a lightweight, isomorphic utility library designed for convenient access to standard HTTP status codes within TypeScript projects. It provides a comprehensive list of HTTP status codes as a TypeScript enum (`HttpStatus`) and a helper function (`httpStatusTextByCode`) to retrieve the corresponding human-readable text description. Currently stable at version 2.0.1, the library maintains a steady cadence of releases focused on stability and minor enhancements. Its primary differentiation lies in its explicit TypeScript-first design, providing strong type safety out-of-the-box for both Node.js and browser environments, unlike some plain JavaScript alternatives that may require manual type definitions.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'OK')
```
cause The `HttpStatus` enum was not correctly imported or was imported as a default export, leading to it being `undefined` or a malformed object.

fix Ensure `HttpStatus` is imported as a named export: `import { HttpStatus } from 'http-status-ts';`.
```
ReferenceError: httpStatusTextByCode is not defined
```
cause The `httpStatusTextByCode` function was not correctly imported or was not destructuring from the module in a CommonJS context.

fix Use a named import for ESM: `import { httpStatusTextByCode } from 'http-status-ts';`. For CJS: `const { httpStatusTextByCode } = require('http-status-ts');`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ES module `import` syntax in a file that is treated as a CommonJS module (e.g., a `.js` file without `"type": "module"` in `package.json`, or a `.ts` file compiled to CJS without proper transpilation setup).

fix Either convert your project to ES Modules by adding `"type": "module"` to your `package.json` (and renaming `.js` to `.mjs` if needed), or configure your TypeScript compiler to output ES Modules. Alternatively, use CommonJS `require()` syntax if your project is strictly CommonJS.

Warnings

gotcha When using `HttpStatus` enum members, remember that `HttpStatus.OK` directly evaluates to the numeric code `200`. Do not try to access a `.code` property on it, as it is the value itself.
Fix: Use the enum member directly: `const code = HttpStatus.OK;` instead of `const code = HttpStatus.OK.code;`.
gotcha Incorrect module imports, especially mixing CommonJS `require` with ES Modules `import` syntax or not correctly destructuring named exports, can lead to `undefined` module members.
Fix: For ES Modules, always use `import { HttpStatus, httpStatusTextByCode } from 'http-status-ts';`. For CommonJS (if supported, verify `package.json` `type` field), ensure correct destructuring: `const { HttpStatus, httpStatusTextByCode } = require('http-status-ts');`.

Install

npm install http-status-ts npm
yarn add http-status-ts yarn
pnpm add http-status-ts pnpm

Imports

HttpStatus
wrong:
```
import HttpStatus from 'http-status-ts';
const HttpStatus = require('http-status-ts');
```
correct:
```
import { HttpStatus } from 'http-status-ts';
```
HttpStatus is a named export (an enum), not a default export. When using CommonJS, it must be accessed as a property of the required module.
httpStatusTextByCode
wrong:
```
import httpStatusTextByCode from 'http-status-ts';
const httpStatusTextByCode = require('http-status-ts');
```
correct:
```
import { httpStatusTextByCode } from 'http-status-ts';
```
httpStatusTextByCode is a named export (a function). For CommonJS, it requires destructuring or property access from the module object.
All named exports
```
import * as HttpStatusModule from 'http-status-ts';
```
This pattern allows accessing all named exports (e.g., `HttpStatusModule.HttpStatus`, `HttpStatusModule.httpStatusTextByCode`) under a single namespace. Useful if you need many exports from the module.

Quickstart

Demonstrates importing and utilizing both the `HttpStatus` enum to retrieve numeric codes and the `httpStatusTextByCode` function to obtain human-readable descriptions, including a conceptual example of their use in an HTTP response.

import { HttpStatus, httpStatusTextByCode } from 'http-status-ts';

// Get a status code's numeric value from the enum
const notFoundCode = HttpStatus.NOT_FOUND;
console.log(`The numeric code for 'Not Found' is: ${notFoundCode}`); // Output: 404

// Get the text description for a specific status code
const okText = httpStatusTextByCode(HttpStatus.OK);
console.log(`The text description for ${HttpStatus.OK} is: "${okText}"`); // Output: "OK"

// Example: Dynamically getting text for a user-input code (simulated)
const userProvidedCode = 500;
const errorMessage = httpStatusTextByCode(userProvidedCode);
console.log(`For code ${userProvidedCode}, the error message is: "${errorMessage}"`); // Output: "Internal Server Error"

// Example using status codes in a conceptual HTTP response
interface MockResponse {
  status: (code: number) => { send: (message: string) => void };
}

const mockResponse: MockResponse = {
  status: (code: number) => ({
    send: (message: string) => {
      console.log(`[HTTP Response Simulator] Status: ${code}, Body: ${message}`);
    }
  })
};

const createSuccess = HttpStatus.CREATED;
mockResponse.status(createSuccess).send(httpStatusTextByCode(createSuccess));

const clientError = HttpStatus.BAD_REQUEST;
mockResponse.status(clientError).send(httpStatusTextByCode(clientError));

view raw JSON →