HTTP Status Map

Common errors

• TypeError: Cannot read properties of undefined (reading 'OK')

  cause Attempting to destructure `NHttpStatuses` (or other named exports) from a CommonJS `require` call using incorrect syntax, often `const NHttpStatuses = require('http-response-status').NHttpStatuses` instead of correct named destructuring.
  fix For CommonJS, use `const { NHttpStatuses } = require('http-response-status');`. Alternatively, switch your project to ES Modules and use `import { NHttpStatuses } from 'http-response-status';`.

• SyntaxError: Named export 'getHttpStatusName' not found. The requested module 'http-response-status' is a CommonJS module, which may not support named exports.

  cause This error occurs when a bundler or runtime attempts to use ESM named `import` syntax (`import { getHttpStatusName } from '...'`) for a module it incorrectly identifies as purely CommonJS, or when the `package.json` `exports` field isn't correctly configured for dual-package usage in a mixed environment.
  fix Verify your project's module type configuration (`"type": "module"` in `package.json` for ESM) and your bundler settings. If targeting older Node.js or CJS, use `const { getHttpStatusName } = require('http-response-status');`.

Warnings

• gotcha As of version 1.1.3, internal module paths were updated in the `package.json`. While this change typically improves module resolution in modern build systems, projects relying on older or non-standard configurations that directly referenced internal file paths (e.g., `http-response-status/dist/index.js`) might experience resolution issues or unexpected errors.
  Fix: Always import directly from the package root: `import { ... } from 'http-response-status'`. Avoid referencing internal file paths to ensure compatibility with future updates.
• gotcha The package primarily uses ES Modules (ESM) for its exports, alongside CommonJS compatibility. Mixing ESM `import` statements with incorrect CommonJS `require()` syntax for named exports can lead to `TypeError` (e.g., 'X is undefined') or `SyntaxError` (e.g., 'Named export not found').
  Fix: Ensure consistent module usage within your project. For Node.js projects, set `"type": "module"` in `package.json` for ESM, or use `const { Name } = require('http-response-status');` for CJS environments.
• gotcha This library is a static map of HTTP response statuses and utility functions based on standard specifications. It does not dynamically fetch or update status definitions from external sources, nor does it provide HTTP client or server functionality. Its scope is strictly limited to providing programmatic access to static HTTP status metadata.
  Fix: Understand that this package is purely for reference and utility around standard HTTP status codes, not for network requests or server-side routing directly. Integrate it with your existing HTTP client/server libraries.

Install

• npm install http-response-status npm
• yarn add http-response-status yarn
• pnpm add http-response-status pnpm

Imports

• NHttpStatuses
  wrong:

  const NHttpStatuses = require('http-response-status').NHttpStatuses

  correct:

  import { NHttpStatuses } from 'http-response-status'

  Provides an enum-like object of standard HTTP status codes (e.g., NHttpStatuses.OK, NHttpStatuses.NOT_FOUND).
• getHttpStatusName
  wrong:

  import getHttpStatusName from 'http-response-status'

  correct:

  import { getHttpStatusName } from 'http-response-status'

  A utility function to retrieve the human-readable string name for a given HTTP status code (e.g., 200 returns 'OK').
• getHttpStatusCategory

  import { getHttpStatusCategory } from 'http-response-status'

  A utility function to categorize an HTTP status code into types like 'SUCCESS', 'CLIENT_ERROR', 'SERVER_ERROR'.
• HTTP_STATUS_SUCCESS
  wrong:

  const HTTP_STATUS_SUCCESS = require('http-response-status').HTTP_STATUS_SUCCESS

  correct:

  import { HTTP_STATUS_SUCCESS } from 'http-response-status'

  A constant string ('SUCCESS') used to compare against the output of getHttpStatusCategory.

Quickstart

Demonstrates how to check specific HTTP status codes, retrieve their human-readable names, and categorize them using the provided constants and utility functions for robust response handling.

import { NHttpStatuses, getHttpStatusName, getHttpStatusCategory, HTTP_STATUS_SUCCESS, HTTP_STATUS_CLIENT_ERROR } from 'http-response-status';

function processHttpResponse(statusCode: number): string {
  if (statusCode === NHttpStatuses.OK) {
    console.log(`Status ${statusCode}: All good, operation successful!`);
    return 'OK';
  }

  const statusName = getHttpStatusName(statusCode);
  if (statusName) {
    console.log(`Status ${statusCode}: ${statusName}`);
  } else {
    console.log(`Status ${statusCode}: Unknown Status Code`);
  }

  const statusCategory = getHttpStatusCategory(statusCode);
  if (statusCategory === HTTP_STATUS_SUCCESS) {
    console.log(`Category for ${statusCode} is Success.`);
    return 'Success';
  } else if (statusCategory === HTTP_STATUS_CLIENT_ERROR) {
    console.log(`Category for ${statusCode} is Client Error.`);
    return 'Client Error';
  } else {
    console.log(`Category for ${statusCode} is ${statusCategory || 'Other'}.`);
    return 'Other';
  }
}

processHttpResponse(200);
processHttpResponse(404);
processHttpResponse(500);
processHttpResponse(201);
processHttpResponse(1000); // Example of an unknown status code