nhb-toolbox 4.14.0-alpha.6 → 4.14.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.14.0] - 2025-08-11
+
+- **Added** new class `HttpStatus` for retrieving and managing HTTP status codes.
+
 ## [4.13.11] - 2025-08-06
 
 - **Fixed** an issue with `getZodiacSign` method in `Chronos` that could not return correct *Vedic* sign.

package/dist/cjs/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOWERCASED_WORDS = exports.LOCALE_CODES = exports.FRANKFURTER_CURRENCIES = exports.CURRENCY_LOCALES = exports.CURRENCY_CODES = exports.CSS_COLORS = exports.NUMBER_COLOR_PALETTE = exports.ALPHABET_COLOR_PALETTE = exports.WESTERN_SEASONS = exports.US_ACADEMIC_SEASONS = exports.SEASON_PRESETS = exports.PHILIPPINES_SEASONS = exports.JAPAN_SEASONS = exports.INDIA_VEDIC_SEASONS = exports.INDIA_TAMIL_SEASONS = exports.INDIA_IMD_SEASONS = exports.ETHIOPIA_SEASONS = exports.BANGLADESH_SEASONS = exports.AUSTRALIA_SEASONS = exports.WESTERN_ZODIAC_SIGNS = exports.WEEK_DAYS = exports.VEDIC_ZODIAC_SIGNS = exports.TIME_ZONES = exports.TIME_ZONE_LABELS = exports.MONTHS = void 0;
+exports.STATUS_CODES = exports.HTTP_CODES = exports.HTTP_STATUS = exports.HTTP_STATUS_CODES = exports.LOWERCASED_WORDS = exports.LOCALE_CODES = exports.FRANKFURTER_CURRENCIES = exports.CURRENCY_LOCALES = exports.CURRENCY_CODES = exports.CSS_COLORS = exports.NUMBER_COLOR_PALETTE = exports.ALPHABET_COLOR_PALETTE = exports.WESTERN_SEASONS = exports.US_ACADEMIC_SEASONS = exports.SEASON_PRESETS = exports.PHILIPPINES_SEASONS = exports.JAPAN_SEASONS = exports.INDIA_VEDIC_SEASONS = exports.INDIA_TAMIL_SEASONS = exports.INDIA_IMD_SEASONS = exports.ETHIOPIA_SEASONS = exports.BANGLADESH_SEASONS = exports.AUSTRALIA_SEASONS = exports.WESTERN_ZODIAC_SIGNS = exports.WEEK_DAYS = exports.VEDIC_ZODIAC_SIGNS = exports.TIME_ZONES = exports.TIME_ZONE_LABELS = exports.MONTHS = void 0;
 var constants_1 = require("./date/constants");
 Object.defineProperty(exports, "MONTHS", { enumerable: true, get: function () { return constants_1.MONTHS; } });
 Object.defineProperty(exports, "TIME_ZONE_LABELS", { enumerable: true, get: function () { return constants_1.TIME_ZONE_LABELS; } });
@@ -32,3 +32,8 @@ Object.defineProperty(exports, "FRANKFURTER_CURRENCIES", { enumerable: true, get
 Object.defineProperty(exports, "LOCALE_CODES", { enumerable: true, get: function () { return constants_3.LOCALE_CODES; } });
 var constants_4 = require("./string/constants");
 Object.defineProperty(exports, "LOWERCASED_WORDS", { enumerable: true, get: function () { return constants_4.LOWERCASE; } });
+var constants_5 = require("./http-status/constants");
+Object.defineProperty(exports, "HTTP_STATUS_CODES", { enumerable: true, get: function () { return constants_5.HTTP_STATUS_CODES; } });
+Object.defineProperty(exports, "HTTP_STATUS", { enumerable: true, get: function () { return constants_5.HTTP_STATUS_CODES; } });
+Object.defineProperty(exports, "HTTP_CODES", { enumerable: true, get: function () { return constants_5.HTTP_STATUS_CODES; } });
+Object.defineProperty(exports, "STATUS_CODES", { enumerable: true, get: function () { return constants_5.HTTP_STATUS_CODES; } });

package/dist/cjs/http-status/HttpStatus.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpStatus = exports.HttpStatus = void 0;
+const constants_1 = require("./constants");
+/**
+ * * 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 HttpStatus.Groups}).
+ * - Intended to be reusable — create multiple instances if you want separate registries.
+ *
+ * @see {@link httpStatus} for the default preloaded singleton instance.
+ *
+ * @example
+ * ```ts
+ * // 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"
+ * ```
+ */
+class HttpStatus {
+    #codesByNumber;
+    #codesByName;
+    /**
+     * * Static category groups for quick reference.
+     * * Populated at runtime from the provided data.
+     */
+    static Groups = {
+        informational: [],
+        success: [],
+        redirection: [],
+        clientError: [],
+        serverError: [],
+    };
+    constructor() {
+        this.#codesByNumber = new Map();
+        this.#codesByName = new Map();
+        // Initialize status code data
+        for (const entry of constants_1.HTTP_STATUS_DATA) {
+            this.#storeEntry(entry);
+            HttpStatus.Groups[entry.category].push(entry.code);
+        }
+    }
+    /**
+     * * Get status entry by numeric HTTP code.
+     * @param code HTTP status code.
+     * @returns Matching status entry or `undefined` if not found.
+     */
+    getByCode(code) {
+        return this.#codesByNumber.get(code);
+    }
+    /**
+     * * Get status entry by name (either SOME_NAME or "Some Name").
+     * @param name Status name.
+     * @returns Matching status entry or `undefined` if not found.
+     */
+    getByName(name) {
+        return this.#codesByName.get(name);
+    }
+    /**
+     * * 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, newMessage) {
+        const entry = this.#codesByNumber.get(code);
+        if (!entry) {
+            return false;
+        }
+        else {
+            entry.message = newMessage;
+            return true;
+        }
+    }
+    /**
+     * * Add one or more new HTTP status code entries.
+     *
+     * @remarks
+     * - 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) {
+        let added = false;
+        for (const entry of entries) {
+            if (!this.#codesByNumber.has(entry.code)) {
+                this.#storeEntry(entry);
+                HttpStatus.Groups[entry.category].push(entry.code);
+                added = true;
+            }
+        }
+        return added;
+    }
+    /**
+     * * List all codes, optionally filtered by category.
+     * @param category Optional category filter.
+     * @returns Array of status entries.
+     */
+    list(category) {
+        if (!category) {
+            return [...this.#codesByNumber.values()];
+        }
+        else {
+            return [...this.#codesByNumber.values()].filter((entry) => entry.category === category);
+        }
+    }
+    /** * Internal helper to store an entry in all lookup maps. */
+    #storeEntry(entry) {
+        this.#codesByNumber.set(entry.code, { ...entry });
+        this.#codesByName.set(entry.name, { ...entry });
+        this.#codesByName.set(entry.readableName, { ...entry });
+    }
+}
+exports.HttpStatus = HttpStatus;
+/**
+ * * Default singleton instance of {@link 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
+ * ```ts
+ * 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"
+ * ```
+ */
+exports.httpStatus = new HttpStatus();