@ebec/http

@ebec/http 🌐

HTTP error classes for TypeScript, extending @ebec/core. Provides 43 pre-built error classes for HTTP 4xx and 5xx status codes with @instanceof-chain-based type guards.

Table of Contents

• Installation
• Quick Start
• Custom Subclasses
• Type Guards
• Error Classes
• API Reference
• License

Installation

npm install @ebec/http

This installs @ebec/core as a dependency automatically.

Quick Start

import { NotFoundError, InternalServerError } from '@ebec/http';

// String message
const error = new NotFoundError('user not found');
console.log(error.status);        // 404
console.log(error.code);          // "NOT_FOUND"
console.log(error.message);       // "user not found"

// Options input
const error = new InternalServerError({
    message: 'database connection lost',
    code: 'DB_CONN_LOST',
});
console.log(error.status); // 500
console.log(error.code);   // "DB_CONN_LOST"

Use in an Express-style error handler:

import { isHTTPError } from '@ebec/http';

app.use((err, req, res, next) => {
    if (isHTTPError(err)) {
        res.status(err.status).json(err.toJSON());
    } else {
        res.status(500).json({ message: 'Internal Server Error' });
    }
});

Custom Subclasses

Extend any error class with your own defaults:

import { NotFoundError } from '@ebec/http';

class UserNotFoundError extends NotFoundError {
    constructor(userId: number) {
        super({
            message: `User ${userId} not found`,
            code: 'USER_NOT_FOUND',
        });
    }
}

throw new UserNotFoundError(42);
// status: 404, code: "USER_NOT_FOUND", message: "User 42 not found"

Type Guards

Type guards check the @instanceof class-marker chain and return interface types (IHTTPError, IClientError, IServerError). Identity is chain-only — there is no duck-typing shape fallback. An object that merely has the right shape (a status field, a code, even one carried over from another HTTP error library) is not recognised; only errors that actually carry the @ebec/http marker chain are.

isHTTPError matches via matchesInstanceof — as a Symbol.for(...) marker on in-process instances, or as the string list that toJSON() emits under the @instanceof key — so the match survives a JSON round-trip. isClientError and isServerError are status-range refinements, not separate identity checks: each first matches its own chain marker (so a NotFoundError matches isClientError outright), and otherwise delegates identity to isHTTPError and decides by status range from there. That's why a bare new HTTPError({ status: 404 }) — which never marks itself as a ClientError — still matches isClientError: it's a confirmed HTTPError by chain, refined by status.

import {
    isHTTPError,
    isClientError,
    isServerError,
} from '@ebec/http';

if (isHTTPError(error)) {
    // error has status (400-599)
    console.log(error.status);
}

if (isClientError(error)) {
    // error has status 400-499
}

if (isServerError(error)) {
    // error has status 500-599
}

Accessing Core Exports

Everything from @ebec/core is available via the ./core subpath:

import { BaseError, isBaseError } from '@ebec/http/core';

Error Classes

Base

Class	Description
HTTPError	Base HTTP error, extends BaseError. Defaults to status 500.
ClientError	Base for 4xx errors, extends HTTPError.
ServerError	Base for 5xx errors, extends HTTPError.

Client (4xx)

Status	Class	Code
400	BadRequestError	BAD_REQUEST
401	UnauthorizedError	UNAUTHORIZED
403	ForbiddenError	FORBIDDEN
404	NotFoundError	NOT_FOUND
405	MethodNotAllowedError	METHOD_NOT_ALLOWED
406	NotAcceptableError	NOT_ACCEPTABLE
407	ProxyAuthenticationRequiredError	PROXY_AUTHENTICATION_REQUIRED
408	RequestTimeoutError	REQUEST_TIMEOUT
409	ConflictError	CONFLICT
410	GoneError	GONE
411	LengthRequiredError	LENGTH_REQUIRED
412	PreconditionFailedError	PRECONDITION_FAILED
413	RequestEntityTooLargeError	REQUEST_ENTITY_TOO_LARGE
414	RequestURITooLongError	REQUEST_URI_TOO_LONG
415	UnsupportedMediaTypeError	UNSUPPORTED_MEDIA_TYPE
416	RequestedRangeNotSatisfiableError	REQUESTED_RANGE_NOT_SATISFIABLE
417	ExpectationFailedError	EXPECTATION_FAILED
418	ImATeapotError	IM_A_TEAPOT
420	EnhanceYourCalmError	ENHANCE_YOUR_CALM
422	UnprocessableEntityError	UNPROCESSABLE_ENTITY
423	LockedError	LOCKED
424	FailedDependencyError	FAILED_DEPENDENCY
425	UnorderedCollectionError	UNORDERED_COLLECTION
426	UpgradeRequiredError	UPGRADE_REQUIRED
428	PreconditionRequiredError	PRECONDITION_REQUIRED
429	TooManyRequestsError	TOO_MANY_REQUESTS
431	RequestHeaderFieldsTooLargeError	REQUEST_HEADER_FIELDS_TOO_LARGE
444	NoResponseError	NO_RESPONSE
449	RetryWithError	RETRY_WITH
450	BlockedByWindowsParentalControlsError	BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS
499	ClientClosedRequestError	CLIENT_CLOSED_REQUEST

Server (5xx)

Status	Class	Code
500	InternalServerError	INTERNAL_SERVER_ERROR
501	NotImplementedError	NOT_IMPLEMENTED
502	BadGatewayError	BAD_GATEWAY
503	ServiceUnavailableError	SERVICE_UNAVAILABLE
504	GatewayTimeoutError	GATEWAY_TIMEOUT
505	HTTPVersionNotSupportedError	HTTP_VERSION_NOT_SUPPORTED
506	VariantAlsoNegotiatesError	VARIANT_ALSO_NEGOTIATES
507	InsufficientStorageError	INSUFFICIENT_STORAGE
508	LoopDetectedError	LOOP_DETECTED
509	BandwidthLimitExceededError	BANDWIDTH_LIMIT_EXCEEDED
510	NotExtendedError	NOT_EXTENDED
511	NetworkAuthenticationRequiredError	NETWORK_AUTHENTICATION_REQUIRED

API Reference

HTTPError

class HTTPError extends BaseError {
    readonly status: number;           // defaults to 500
    readonly redirectURL?: string;

    get statusCode(): number;          // @deprecated — alias for `status`

    constructor(input?: string | ErrorOptions);
}

ErrorOptions

Extends core ErrorOptions with HTTP-specific fields:

Property	Type	Description
status	number | string	HTTP status code (400-599). Invalid values default to 500.
statusCode	number | string	Deprecated. Alias for status.
redirectURL	string	Redirect URL for 3xx-style responses.

Plus all fields from @ebec/core ErrorOptions.

Type Guards

Function	Returns	Checks
isHTTPError(input)	input is IHTTPError	Chain-only: true iff the @instanceof chain carries the HTTPError marker. No shape/status fallback
isClientError(input)	input is IClientError	Own chain marker match; otherwise delegates identity to isHTTPError (chain-confirmed) + status 400-499
isServerError(input)	input is IServerError	Own chain marker match; otherwise delegates identity to isHTTPError (chain-confirmed) + status 500-599
isErrorOptions(input)	input is ErrorOptions	Validates HTTP options shape

Utilities

Function	Description
getStatusText(statusCode)	Returns the reason phrase for a given status code, or undefined if not found
sanitizeStatusCode(input)	Parses and validates (400-599), defaults to 500
STATUS_TEXTS	Map of status codes to reason phrases (e.g. 400 → "Bad Request")

License

Made with 💚

Published under MIT License.