nhb-toolbox/dist/dts/http-status/HttpStatus.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { Maybe } from '../types/index';
import type { HttpStatusCode, HttpStatusName, StatusCategory, StatusCode, StatusEntry, StatusName } from './types';
/**
 * @class Utility class for retrieving and managing HTTP status codes with rich MDN-based metadata.
 *
 * @remarks
 * - Supports lookup by code or name (both `SOME_NAME` and `Some Name` formats).
 * - Allows adding custom codes and overriding messages for existing ones.
 * - Provides pre-grouped categories for quick filtering (see {@link https://toolbox.nazmul-nhb.dev/docs/classes/HttpStatus#groups-static-property HttpStatus.Groups}).
 * - Intended to be reusable — create multiple instances if you want separate registries.
 *
 * @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/misc/httpStatus httpStatus} for the default preloaded singleton instance.
 *
 * @example
 * // Using the class directly
 * const customStatus = new HttpStatus();
 * customStatus.addCode({
 *   code: 799,
 *   name: 'CUSTOM_ERROR',
 *   readableName: 'Custom Error',
 *   message: 'Something custom happened',
 *   description: 'This is an example of a user-defined HTTP status.',
 *   category: 'clientError'
 * });
 *
 * console.log(customStatus.getByCode(799)?.readableName);
 * // "Custom Error"
 *
 * console.log(customStatus.getByCode(404)?.name);
 * // "NOT_FOUND"
 *
 * console.log(customStatus.getByCode(404)?.message);
 * // "Not Found"
 */
export declare class HttpStatus {
    #private;
    /**
     * * Static category groups for quick reference.
     * @remarks Populated at runtime from default and the provided data.
     */
    static Groups: Record<StatusCategory, StatusCode[]>;
    constructor();
    /**
     * * Get status entry by standard numeric HTTP code.
     * @param code Standard HTTP status code.
     * @returns Matching standard status entry.
     */
    getByCode(code: HttpStatusCode): StatusEntry;
    /**
     * * Get status entry by numeric HTTP code.
     * @param code HTTP status code.
     * @returns Matching status entry or `undefined` if not found.
     */
    getByCode(code: StatusCode): Maybe<StatusEntry>;
    /**
     * * Get status entry by standard name (either as `SOME_NAME` or `Some Name`).
     * @param name Standard status name either as `SOME_NAME` or `Some Name`.
     * @returns Matching standard status entry.
     */
    getByName(name: HttpStatusName): StatusEntry;
    /**
     * * Get status entry by name (either as `SOME_NAME` or `Some Name`).
     * @param name Status name either as `SOME_NAME` or `Some Name`.
     * @returns Matching status entry or `undefined` if not found.
     */
    getByName(name: StatusName): Maybe<StatusEntry>;
    /**
     * * Override the short message of an existing code.
     * @param code HTTP status code.
     * @param newMessage Custom message.
     * @returns `true` if updated, `false` if code not found.
     */
    setMessage(code: StatusCode, newMessage: string): boolean;
    /**
     * * Add one or more new HTTP status code entries.
     *
     * @remarks
     * - New entries are compared **by their `code` value** to determine uniqueness.
     * - If a code already exists, it will be skipped and not overwritten.
     * - Returns `true` if at least one code was successfully added.
     * - Returns `false` if all provided codes already exist.
     *
     * @param entries One or more status entries to add.
     * @returns `true` if at least one code was added, otherwise `false`.
     */
    addCode(...entries: StatusEntry[]): boolean;
    /**
     * * Add/override one or more HTTP status code entries.
     *
     * @remarks New entries use their `code` value as the comparison key and will overwrite existing ones.
     *
     * @param entries One or more status entries to add/override.
     * @returns The modified instance with the newly added/updated entries.
     */
    addOrOverrideCode(...entries: StatusEntry[]): HttpStatus;
    /**
     * * List all codes, optionally filtered by category.
     * @param category Optional category filter.
     * @returns Array of status entries.
     */
    list(category?: StatusCategory): StatusEntry[];
}
/**
 * * Default singleton instance of {@link https://toolbox.nazmul-nhb.dev/docs/classes/HttpStatus HttpStatus} class.
 *
 * @remarks
 * - Preloaded with all MDN-based HTTP status codes.
 * - Useful when you do not need multiple independent registries.
 * - Provides immediate access to lookups, category groupings, and
 *   mutation methods without manual instantiation.
 *
 * @example
 * import { httpStatus } from 'nhb-toolbox';
 *
 * console.log(httpStatus.getByCode(404)?.readableName);
 * // "Not Found"
 *
 * httpStatus.setMessage(404, 'This page is gone');
 * console.log(httpStatus.getByCode(404)?.message);
 * // "This page is gone"
 */
export declare const httpStatus: HttpStatus;