http-status-lite
ReferenceInstall
Documentation · v2.3.0

From status
to certainty.

Install the package, choose the smallest entry point, and keep exact HTTP status types from input to response.

GET /docs200 OK
content-typeapplication/typescriptdependencies0moduleESM + CommonJSruntimeNode.js + browser

01 / Start

Two commands to typed statuses.

Install the package, then import from the main entry point. There are no runtime dependencies or setup steps.

Shell
npm install http-status-lite
TypeScript
import { Status, getStatus, isSuccess } from 'http-status-lite';

Status.OK; // 200

const status = getStatus(404);
status.name;    // 'NOT_FOUND'
status.message; // 'Not Found'

isSuccess(Status.NO_CONTENT); // true
Literal in, literal out. Calling getStatus(404) preserves 'NOT_FOUND' and 'Not Found' in the returned type—not merely string.

02 / API

Use constants without magic numbers.

Import individual constants or use the complete Status object. Choose /codes when constants are all you need.

TypeScript
import { NOT_FOUND, OK, Status } from 'http-status-lite';

OK;               // 200
NOT_FOUND;        // 404
Status.CREATED;   // 201

// Constants-only entry point
import { BAD_REQUEST } from 'http-status-lite/codes';

03 / API

Translate codes, names, and phrases.

Lookup helpers return exact types for known literal inputs and null when a registry entry is unknown.

TypeScript
import {
  getReasonPhrase,
  getStatus,
  getStatusCode,
  getStatusName,
} from 'http-status-lite';

getStatus(404);              // complete entry
getStatusCode('NOT_FOUND');  // 404
getStatusName(404);          // 'NOT_FOUND'
getReasonPhrase(404);        // 'Not Found'
getStatus(499);              // null

04 / Boundaries

Narrow values you do not control.

Parse environment variables, route parameters, and other external input before using them as known status codes.

TypeScript
import {
  assertStatusCode,
  isStatusCode,
  isStatusName,
  parseStatusCode,
} from 'http-status-lite';

parseStatusCode('404');        // 404
parseStatusCode('499');        // null
isStatusCode(404);             // true; narrows the value
isStatusName('NOT_FOUND');     // true; narrows the value
assertStatusCode(value);       // narrows or throws TypeError

05 / Classification

Ranges and registry entries stay separate.

Predicates classify any integer in the HTTP range. Registry guards answer the stricter question: does this package know the code?

TypeScript
import {
  getCategory,
  isClientError,
  isError,
  isRedirect,
  isServerError,
  isSuccess,
} from 'http-status-lite/predicates';

isClientError(499);  // true: any integer in the 4xx range
isStatusCode(499);   // false: not a represented registry entry
getCategory(499);    // '4xx'

06 / Standards

Load standards data only when needed.

References, categories, and IANA lifecycle states live in the optional metadata entry point, keeping them out of the core bundle.

TypeScript
import { getStatusMetadata } from 'http-status-lite/metadata';

getStatusMetadata(104);
// {
//   code: 104,
//   name: 'UPLOAD_RESUMPTION_SUPPORTED',
//   message: 'Upload Resumption Supported',
//   reference: 'draft-ietf-httpbis-resumable-upload-05',
//   registryStatus: 'temporary',
//   category: '1xx'
// }

Lifecycle values are permanent, temporary, unused, or obsolete.

07 / TypeScript

Bring the registry into your type system.

Use generated unions when an API accepts only represented codes, names, categories, or complete entries.

TypeScript
import type {
  HttpStatusCategory,
  HttpStatusCode,
  HttpStatusEntry,
  HttpStatusName,
} from 'http-status-lite';

const code: HttpStatusCode = 404;
const name: HttpStatusName = 'NOT_FOUND';

const invalid: HttpStatusCode = 499; // TypeScript error

08 / Compatibility

Migrate when you are ready.

The original namespace and legacy RFC names remain supported. New code should prefer current names on Status.

TypeScript
import { httpStatusLite } from 'http-status-lite';

httpStatusLite.OK;                    // 200
httpStatusLite.NOT_FOUND_MESSAGE;     // 'Not Found'
httpStatusLite[404];                  // 'NOT_FOUND'
httpStatusLite.PAYLOAD_TOO_LARGE;     // legacy alias

// Prefer the current RFC 9110 name in new code:
Status.CONTENT_TOO_LARGE;             // 413
Explore all status codes View source