HttpStatus

HttpStatus

The HttpStatus class provides a comprehensive, type-safe API for managing HTTP status codes with rich metadata. It supports lookup by code or name, custom status code registration, message overriding, and category-based filtering.

Features

• Lookup status codes by number or name (both SOME_NAME and Some Name formats).
• Built-in standard HTTP status codes loaded on construction.
• Manage status codes dynamically with addCode(), setMessage(), and addOrOverrideCode().
• Pre-grouped categories for quick filtering.
• Fully typed for TypeScript with comprehensive utility types.
• Isolated instances for different configurations.

Import

import { HttpStatus } from 'toolbox-x';

Basic Usage

Type Definitions

Core Types

type $StatusNameVar = 'name' | 'readableName';
type StatusCategory = 'informational' | 'success' | 'redirection' | 'clientError' | 'serverError';
type StatusCode = LooseLiteral<HttpStatusCode>;
type StatusName = LooseLiteral<HttpStatusName>;
type EntryStatusName = LooseLiteral<HttpStatusName<'name'>>;
type EntryReadableName = LooseLiteral<HttpStatusName<'readableName'>>;

interface StatusEntry {
  code: StatusCode;
  name: EntryStatusName;
  readableName: EntryReadableName;
  link?: string;
  message: string;
  description: string;
  category: StatusCategory;
}

Utility Types

Two key utility types are provided for type-safe operations:

1. HttpStatusCode<Category>
   Extracts standard HTTP status codes filtered by category.

   type SuccessCodes = HttpStatusCode<'success'>; // 200 | 201 | 202 | ...
   type ClientErrors = HttpStatusCode<'clientError'>; // 400 | 401 | 403 | 404 | ...

2. HttpStatusName<Name, Category>
   Extracts standard HTTP status names filtered by variant and category.

   type ConstantNames = HttpStatusName<'name'>; // "OK" | "CREATED" | "NOT_FOUND" | ...
   type ReadableNames = HttpStatusName<'readableName'>; // "OK" | "Created" | "Not Found" | ...

These types enable compile-time validation of status codes and names throughout your application.

Extending Status Codes

You can modify your instance without affecting others:

API Reference

Constructor

Initializes a new HttpStatus instance with all standard HTTP status codes.

getByCode()

Get status entry by numeric HTTP code.

Signatures

getByCode(code: HttpStatusCode): StatusEntry;
getByCode(code: StatusCode): StatusEntry | undefined;

Example

getByName()

Get status entry by name (either SOME_NAME or Some Name format).

Signatures

getByName(name: HttpStatusName): StatusEntry;
getByName(name: StatusName): StatusEntry | undefined;

Example

setMessage()

Override the short message of an existing code.

Signatures

setMessage(code: StatusCode, newMessage: string): boolean

Example

addCode()

Add one or more new HTTP status code entries.

Signatures

addCode(...entries: StatusEntry[]): boolean

Example

addOrOverrideCode()

Add or override one or more HTTP status code entries.

Signatures

addOrOverrideCode(...entries: StatusEntry[]): HttpStatus

Example

list()

List all codes, optionally filtered by category.

Signatures

list(category?: StatusCategory): StatusEntry[]

Example

Groups (Static Property)

Pre-grouped HTTP status codes by category for quick reference:

HttpStatus.Groups: {
  informational: StatusCode[],
  success: StatusCode[],
  redirection: StatusCode[],
  clientError: StatusCode[],
  serverError: StatusCode[]
}

Categories

Example Usage

See Also

• httpStatus (default instance) — shared instance of HttpStatus for standard use cases.
• HTTP Status Codes Reference — MDN documentation.