nhb-toolbox 4.0.36 → 4.0.44

package/dist/cjs/colors/Color.js

@@ -8,7 +8,7 @@ const hsl = (0, random_1.generateRandomHSLColor)();
 const { hex, rgb } = (0, convert_1.convertColorCode)(hsl);
 /**
  * * Class representing a color and its conversions among `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` and `HSLA` formats.
- * * It has 1 instance method `applyOpacity()` to apply opacity to `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` color.
+ * * It has 13 instance methods to manipulate and play with the color values.
  * * It has 6 static methods that can be used to check if a color is in `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` format.
  *
  * @property hex - The color in `Hex` format.
@@ -41,7 +41,7 @@ class Color {
      * If no color is passed, a random color will be generated.
      *
      * Additionally:
-     * - Use `.applyOpacity(opacity)` to modify or add opacity to the color.
+     * - It has 13 instance methods to manipulate and play with the color values.
      * - Use static methods like `Color.isHex6(color)` to validate color strings.
      *
      * @param toConvert - An optional input color string in any supported format (`Hex`, `Hex8`, `RGB`, `RGBA`, `HSL`, or `HSLA`) to convert in all other (includes the current format) formats.
@@ -118,12 +118,12 @@ class Color {
         yield this.hsla;
     }
     /**
-     * * Applies or modifies the opacity of a color.
-     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity
-     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel
+     * @instance Applies or modifies the opacity of a color. Mutate the original instance.
+     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity.
+     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel.
      *
-     * @param opacity - A number between 0-100 representing the opacity percentage
-     * @returns An object containing all color formats with the applied opacity
+     * @param opacity - A number between 0-100 representing the opacity percentage.
+     * @returns A new instance of `Color` containing all color formats with the applied opacity.
      *
      * @example
      * const color = new Color("#ff0000");
@@ -141,14 +141,168 @@ class Color {
         const alphaDecimal = validOpacity / 100;
         const rgbValues = (0, helpers_1._extractSolidColorValues)(this.rgb);
         const hslValues = (0, helpers_1._extractSolidColorValues)(this.hsl);
-        return {
+        return Color.#fromParts({
             hex: this.hex.slice(0, 7).toUpperCase(),
             hex8: `${this.hex.slice(0, 7)}${alphaHex}`.toUpperCase(),
             rgb: `rgb(${rgbValues[0]}, ${rgbValues[1]}, ${rgbValues[2]})`,
             rgba: `rgba(${rgbValues[0]}, ${rgbValues[1]}, ${rgbValues[2]}, ${alphaDecimal})`,
             hsl: `hsl(${hslValues[0]}, ${hslValues[1]}%, ${hslValues[2]}%)`,
             hsla: `hsla(${hslValues[0]}, ${hslValues[1]}%, ${hslValues[2]}%, ${alphaDecimal})`,
+        });
+    }
+    /**
+     * @instance Darkens the color by reducing the lightness by the given percentage.
+     * @param percent - The percentage to darken (0–100).
+     * @returns A new `Color` instance with the modified darkness.
+     */
+    applyDarkness(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newL = Math.max(0, l - percent);
+        const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Lightens the color by increasing the lightness by the given percentage.
+     * @param percent - The percentage to brighten (0–100).
+     * @returns A new `Color` instance with the modified lightness.
+     */
+    applyBrightness(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newL = Math.min(100, l + percent);
+        const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Reduces the saturation of the color to make it appear duller.
+     * @param percent - The percentage to reduce saturation (0–100).
+     * @returns A new `Color` instance with the modified saturation.
+     */
+    applyDullness(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newS = Math.max(0, s - percent);
+        const newHSL = `hsl(${h}, ${newS}%, ${l}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
+     * - *This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).*
+     * @param percent - Value from 0 to 100 representing how far to push the color toward white.
+     * @returns A new `Color` instance shifted toward white.
+     */
+    applyWhiteShade(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        // Cap values to avoid overshooting
+        const newS = Math.max(0, s - (s * percent) / 100);
+        const newL = Math.min(100, l + ((100 - l) * percent) / 100);
+        const newHSL = `hsl(${h}, ${newS}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Blends the current color with another color based on the given weight.
+     * @param other - The color in any 6 `(Hex, Hex8 RGB, RGBA, HSL or HSLA)` to blend with.
+     * @param weight - A number from 0 to 1 indicating the weight of the other color. Defaults to `0.5`.
+     * 				 - `weight = 0` → only the original color (this)
+     *				 - `weight = 1` → only the other color
+     *				 - `weight = 0.5` → equal blend between the two
+     * @returns A new `Color` instance representing the blended result.
+     */
+    blendWith(other, weight = 0.5) {
+        const w = Math.max(0, Math.min(1, weight));
+        const converted = new Color(other);
+        const rgb1 = (0, helpers_1._extractSolidColorValues)(this.rgb);
+        const rgb2 = (0, helpers_1._extractSolidColorValues)(converted.rgb);
+        const blended = rgb1.map((c, i) => Math.round(c * (1 - w) + rgb2[i] * w));
+        const blendedRGB = `rgb(${blended[0]}, ${blended[1]}, ${blended[2]})`;
+        return new Color(blendedRGB);
+    }
+    /**
+     * @instance Calculates the contrast ratio between this color and another color (WCAG).
+     * @param other - The other color to compare against.
+     * @returns A number representing the contrast ratio (rounded to 2 decimal places).
+     */
+    contrastRatio(other) {
+        const newColor = new Color(other);
+        const luminance = (rgb) => {
+            const [r, g, b] = (0, helpers_1._extractSolidColorValues)(rgb).map((v) => {
+                const c = v / 255;
+                return c <= 0.03928 ?
+                    c / 12.92
+                    : Math.pow((c + 0.055) / 1.055, 2.4);
+            });
+            return 0.2126 * r + 0.7152 * g + 0.0722 * b;
         };
+        const lum1 = luminance(this.rgb);
+        const lum2 = luminance(newColor.rgb);
+        const brighter = Math.max(lum1, lum2);
+        const darker = Math.min(lum1, lum2);
+        const ratio = (brighter + 0.05) / (darker + 0.05);
+        return Math.round(ratio * 100) / 100;
+    }
+    /**
+     * @instance Returns the complementary color by rotating the hue 180 degrees.
+     * @returns A new Color that is the complement of the current color.
+     */
+    getComplementaryColor() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newHue = (h + 180) % 360;
+        const newHSL = `hsl(${newHue}, ${s}%, ${l}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Generates a color scheme of analogous colors, including the base color.
+     * Analogous colors are next to each other on the color wheel (±30°).
+     * @returns An array of three Color instances: [base, left, right].
+     */
+    getAnalogousColors() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const left = `hsl(${(h + 330) % 360}, ${s}%, ${l}%)`;
+        const right = `hsl(${(h + 30) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(left), new Color(right)];
+    }
+    /**
+     * @instance Generates a color triad scheme including the base color.
+     * Triadic colors are evenly spaced (120° apart) on the color wheel.
+     * @returns An array of three Color instances: [base, triad1, triad2].
+     */
+    getTriadColors() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const c1 = `hsl(${(h + 120) % 360}, ${s}%, ${l}%)`;
+        const c2 = `hsl(${(h + 240) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(c1), new Color(c2)];
+    }
+    /**
+     * @instance Generates a tetradic color scheme including the base color.
+     * Tetradic colors form a rectangle on the color wheel (90° apart).
+     * @returns An array of four Color instances: [base, tetrad1, tetrad2, tetrad3].
+     */
+    getTetradColors() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const c1 = `hsl(${(h + 90) % 360}, ${s}%, ${l}%)`;
+        const c2 = `hsl(${(h + 180) % 360}, ${s}%, ${l}%)`;
+        const c3 = `hsl(${(h + 270) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(c1), new Color(c2), new Color(c3)];
+    }
+    /**
+     * @instance Gets the `WCAG` accessibility rating between this and another color.
+     * @param other - The other color to test contrast against.
+     * @returns 'Fail', 'AA', or 'AAA' based on `WCAG 2.1` contrast standards.
+     */
+    getWCAGRating(other) {
+        const ratio = this.contrastRatio(other);
+        if (ratio >= 7)
+            return 'AAA';
+        if (ratio >= 4.5)
+            return 'AA';
+        return 'Fail';
+    }
+    /**
+     * @instance Determines if the color is light based on its perceived brightness.
+     * @returns `true` if light, `false` if dark.
+     */
+    isLightColor() {
+        const [r, g, b] = (0, helpers_1._extractSolidColorValues)(this.rgb);
+        const brightness = (r * 299 + g * 587 + b * 114) / 1000;
+        return brightness > 127.5;
     }
     /**
      * @static Checks if a color is in `Hex6` format.
@@ -169,40 +323,40 @@ class Color {
         return /^#[0-9A-Fa-f]{8}$/.test(color);
     }
     /**
-     * @static Checks if a color is in `RGB` format.
+     * @static Checks if a color is in `RGB` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+     * @returns `true` if it's a `RGB` color, `false` if not.
      */
     static isRGB(color) {
-        return /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/.test(color);
+        return (0, helpers_1._isRGB)(color);
     }
     /**
-     * @static Checks if a color is in `RGBA` format.
+     * @static Checks if a color is in `RGBA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+     * @returns `true` if it's a `RGBA` color, `false` if not.
      */
     static isRGBA(color) {
-        return /^rgba\(\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(0|1|0?\.\d+)\)$/.test(color);
+        return (0, helpers_1._isRGBA)(color);
     }
     /**
-     * @static Checks if a color is in `HSL` format.
+     * @static Checks if a color is in `HSL` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+     * @returns `true` if it's a `HSL` color, `false` if not.
      */
     static isHSL(color) {
-        return /^hsl\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%\)$/.test(color);
+        return (0, helpers_1._isHSL)(color);
     }
     /**
-     * @static Checks if a color is in `HSLA` format.
+     * @static Checks if a color is in `HSLA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+     * @returns `true` if it's a `HSLA` color, `false` if not.
      */
     static isHSLA(color) {
-        return /^hsla\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%,\s*(0|1|0?\.\d+)\)$/.test(color);
+        return (0, helpers_1._isHSLA)(color);
     }
     /**
      * @private Converts the given color to all other formats while preserving the original.
@@ -237,5 +391,20 @@ class Color {
         }
         throw new Error(`Unrecognized color format: ${color}`);
     }
+    /**
+     * @private @static Internal factory to create a Color instance from parsed parts.
+     * @param parts All the color parts as object.
+     * @returns An instance of `Color`.
+     */
+    static #fromParts(parts) {
+        const color = Object.create(Color.prototype);
+        color.hex = parts.hex;
+        color.hex8 = parts.hex8;
+        color.rgb = parts.rgb;
+        color.rgba = parts.rgba;
+        color.hsl = parts.hsl;
+        color.hsla = parts.hsla;
+        return color;
+    }
 }
 exports.Color = Color;

package/dist/cjs/colors/helpers.js

@@ -2,12 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._extractAlphaColorValues = exports._extractSolidColorValues = exports._isSimilarToLast = exports._generateRandomHSL = exports._applyOpacity = exports._convertOpacityToHex = void 0;
 exports._isHex6 = _isHex6;
-exports._isRGB = _isRGB;
-exports._isHSL = _isHSL;
 exports._isHex8 = _isHex8;
+exports._isRGB = _isRGB;
 exports._isRGBA = _isRGBA;
+exports._isHSL = _isHSL;
 exports._isHSLA = _isHSLA;
 exports._isValidAlpha = _isValidAlpha;
+exports._isValidRGBComponent = _isValidRGBComponent;
+exports._isValidHue = _isValidHue;
+exports._isValidPercentage = _isValidPercentage;
 /**
  * * Converts opacity percentage (0-100) to a 2-digit hex string.
  *
@@ -97,7 +100,7 @@ const _extractAlphaColorValues = (colorString) => {
 };
 exports._extractAlphaColorValues = _extractAlphaColorValues;
 /**
- * * Checks if a color is in `Hex` format.
+ * @private Checks if a color is in `Hex` format.
  *
  * @param color Color to check.
  * @returns Boolean: `true` if it's a `Hex` color, `false` if not.
@@ -106,58 +109,92 @@ function _isHex6(color) {
     return /^#[0-9A-Fa-f]{6}$/.test(color);
 }
 /**
- * * Checks if a color is in `RGB` format.
+ * @private Checks if a color is in `Hex8` format.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+ * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
  */
-function _isRGB(color) {
-    return /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/.test(color);
+function _isHex8(color) {
+    return /^#[0-9A-Fa-f]{8}$/.test(color);
 }
 /**
- * * Checks if a color is in `HSL` format.
+ * @private Checks if a color is in `RGB` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+ * @returns `true` if it's a `RGB` color, `false` if not.
  */
-function _isHSL(color) {
-    return /^hsl\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%\)$/.test(color);
+function _isRGB(color) {
+    const match = color.match(/^rgb\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)\s*\)$/);
+    if (!match)
+        return false;
+    const [r, g, b] = match.slice(1).map(Number);
+    return (_isValidRGBComponent(r) &&
+        _isValidRGBComponent(g) &&
+        _isValidRGBComponent(b));
 }
 /**
- * @static
- * Checks if a color is in `Hex8` format.
+ * @private Checks if a color is in `RGBA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
+ * @returns `true` if it's a `RGBA` color, `false` if not.
  */
-function _isHex8(color) {
-    return /^#[0-9A-Fa-f]{8}$/.test(color);
+function _isRGBA(color) {
+    const match = color.match(/^rgba\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(0|1|0?\.\d+)\s*\)$/);
+    if (!match)
+        return false;
+    const [r, g, b, a] = match.slice(1).map(Number);
+    return (_isValidRGBComponent(r) &&
+        _isValidRGBComponent(g) &&
+        _isValidRGBComponent(b) &&
+        _isValidAlpha(a));
 }
 /**
- * @static
- * Checks if a color is in `RGBA` format.
+ * @private Checks if a color is in `HSL` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+ * @returns `true` if it's a `HSL` color, `false` if not.
  */
-function _isRGBA(color) {
-    return /^rgba\(\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(0|1|0?\.\d+)\)$/.test(color);
+function _isHSL(color) {
+    const match = color.match(/^hsl\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)%,\s*(\d{1,3}(?:\.\d+)?)%\s*\)$/);
+    if (!match)
+        return false;
+    const [h, s, l] = match.slice(1).map(Number);
+    return _isValidHue(h) && _isValidPercentage(s) && _isValidPercentage(l);
 }
 /**
- * @static
- * Checks if a color is in `HSLA` format.
+ * @private Checks if a color is in `HSLA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+ * @returns `true` if it's a `HSLA` color, `false` if not.
  */
 function _isHSLA(color) {
-    return /^hsla\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%,\s*(0|1|0?\.\d+)\)$/.test(color);
+    const match = color.match(/^hsla\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)%,\s*(\d{1,3}(?:\.\d+)?)%,\s*(0|1|0?\.\d+)\s*\)$/);
+    if (!match)
+        return false;
+    const [h, s, l, a] = match.slice(1).map(Number);
+    return (_isValidHue(h) &&
+        _isValidPercentage(s) &&
+        _isValidPercentage(l) &&
+        _isValidAlpha(a));
 }
 /**
- * * Type guard to validate alpha value.
+ * @private Checks if a number is valid alpha value.
+ *
  * @param value Alpha value to check.
- * @returns Boolean: `true` if it's a valid alpha value, `false` if not.
+ * @returns `true` if it's a valid alpha value, `false` if not.
  */
 function _isValidAlpha(value) {
     return value >= 0 && value <= 1 && !isNaN(value);
 }
+/** * @private Validates RGB component (0–255). */
+function _isValidRGBComponent(value) {
+    return value >= 0 && value <= 255;
+}
+/** * @private Validates HSL hue (0–360). */
+function _isValidHue(value) {
+    return value >= 0 && value <= 360;
+}
+/** * @private Validates HSL percentage components (0–100). */
+function _isValidPercentage(value) {
+    return value >= 0 && value <= 100;
+}

package/dist/cjs/dom/query.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateQueryParams = void 0;
+exports.parseQueryString = exports.generateQueryParams = void 0;
 exports.getQueryParams = getQueryParams;
 exports.updateQueryParam = updateQueryParam;
 const objectify_1 = require("../object/objectify");
+const sanitize_1 = require("../object/sanitize");
+const utils_1 = require("../utils");
 /**
  * * Utility to generate query parameters from an object.
  *
@@ -53,3 +55,28 @@ function updateQueryParam(key, value) {
     url.searchParams.set(key, value);
     window.history.replaceState({}, '', url.toString());
 }
+/**
+ * Parses a query string (with optional `?` prefix) into an object.
+ * Supports multiple values for the same key by returning arrays.
+ * Optionally parses primitive string values into actual types (e.g., "1" → 1, "true" → true).
+ *
+ * @param query - The query string to parse.
+ * @param parsePrimitives - Whether to convert stringified primitives into real values (default: true).
+ * @returns An object where keys are strings and values can be string, array, number, boolean, or null.
+ */
+const parseQueryString = (query, parsePrimitives = true) => {
+    const params = new URLSearchParams(query.startsWith('?') ? query.slice(1) : query);
+    const entries = {};
+    for (const [key, value] of params.entries()) {
+        if (key in entries) {
+            const current = entries[key];
+            const array = Array.isArray(current) ? [...current, value] : [current, value];
+            entries[key] = parsePrimitives ? (0, utils_1.deepParsePrimitives)(array) : array;
+        }
+        else {
+            entries[key] = value;
+        }
+    }
+    return parsePrimitives ? (0, sanitize_1.parseObjectValues)(entries) : entries;
+};
+exports.parseQueryString = parseQueryString;

package/dist/cjs/index.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMemoizedFibonacci = exports.getFibonacciSeriesMemo = exports.getFibonacciSeries = exports.getFibonacciNumbers = exports.getFibonacci = exports.generateFibonacci = exports.fibonacciGenerator = exports.calculatePercentage = exports.sumOfNumbers = exports.sumNumbers = exports.sumDigits = exports.reverseNumber = exports.getSumOfNumbers = exports.getRandomNumber = exports.getAverageOfNumbers = exports.getAverage = exports.convertToDecimal = exports.calculateLCM = exports.calculateLCD = exports.calculateHCF = exports.calculateGCD = exports.calculateAverage = exports.countWordsInString = exports.wordCount = exports.countWords = exports.levenshteinDistance = exports.getLevenshteinDistance = exports.extractNumbersFromString = exports.slugifyString = exports.reverseString = exports.replaceAllInString = exports.normalizeString = exports.maskString = exports.formatWithPlural = exports.formatUnitWithPlural = exports.formatNumberWithPluralUnit = exports.extractURLs = exports.extractEmails = exports.convertStringCase = exports.isSnakeCase = exports.isPascalCase = exports.isPalindrome = exports.isKebabCase = exports.isEmojiOnly = exports.isCamelCase = exports.generateAnagrams = exports.truncateString = exports.trimString = exports.generateRandomID = exports.capitalizeString = void 0;
+exports.getMemoizedFibonacci = exports.getFibonacciSeriesMemo = exports.getFibonacciSeries = exports.getFibonacciNumbers = exports.getFibonacci = exports.generateFibonacci = exports.fibonacciGenerator = exports.calculatePercentage = exports.sumOfNumbers = exports.sumNumbers = exports.sumDigits = exports.reverseNumber = exports.getSumOfNumbers = exports.getRandomNumber = exports.getAverageOfNumbers = exports.getAverage = exports.convertToDecimal = exports.calculateLCM = exports.calculateLCD = exports.calculateHCF = exports.calculateGCD = exports.calculateAverage = exports.wordCount = exports.levenshteinDistance = exports.getLevenshteinDistance = exports.extractNumbersFromString = exports.countWordsInString = exports.countWords = exports.slugifyString = exports.reverseString = exports.replaceAllInString = exports.normalizeString = exports.maskString = exports.formatWithPlural = exports.formatUnitWithPlural = exports.formatNumberWithPluralUnit = exports.extractURLs = exports.extractEmails = exports.convertStringCase = exports.isSnakeCase = exports.isPascalCase = exports.isPalindrome = exports.isKebabCase = exports.isEmojiOnly = exports.isCamelCase = exports.generateAnagrams = exports.truncateString = exports.trimString = exports.generateRandomID = exports.capitalizeString = void 0;
 exports.convertRgbaToHsla = exports.convertRgbaToHex8 = exports.convertHslToRgb = exports.convertHslToHex = exports.convertHslaToRgba = exports.convertHslaToHex8 = exports.convertHexToRgb = exports.convertHexToHsl = exports.convertHex8ToRgba = exports.convertHex8ToHsla = exports.convertColorCode = exports.generateRandomHSLColor = exports.generateRandomColorInHexRGB = exports.getColorForInitial = exports.getNumbersInRange = exports.roundToNearestInterval = exports.roundToNearest = exports.roundNumberToNearestInterval = exports.roundNumber = exports.numberToOrdinal = exports.getRandomFloat = exports.getRandomDecimal = exports.getOrdinalNumber = exports.getOrdinal = exports.formatCurrency = exports.convertToOrdinal = exports.convertNumberToOrdinal = exports.convertNumberToCurrency = exports.clampNumber = exports.cardinalToOrdinal = exports.isPrimeNumber = exports.isPrime = exports.getPrimeNumbers = exports.findPrimeNumbers = exports.numberToWords = exports.convertToRomanNumerals = exports.convertNumberToWords = exports.isPerfectSquare = exports.isParOfFibonacciSeries = exports.isParOfFibonacci = exports.isOddNumber = exports.isOdd = exports.isMultiple = exports.isInvalidNumbers = exports.isFibonacci = exports.isEvenNumber = exports.isEven = exports.areInvalidNumbers = exports.getNthFibonacci = exports.getMemoizedFibonacciSeries = void 0;
 exports.getDuplicatesFromArray = exports.getDuplicates = exports.findMissingElements = exports.extractMissingElements = exports.extractDuplicatesFromArray = exports.extractDuplicates = exports.createOptionsArray = exports.sortAnArray = exports.shuffleArray = exports.isValidEmptyArray = exports.isInvalidOrEmptyArray = exports.getLastArrayElement = exports.flattenArray = exports.filterArrayOfObjects = exports.minutesToUTCOffset = exports.getTotalMinutesFromUTC = exports.getTotalMinutesFromTime = exports.getTotalMinutes = exports.getTimeStringFromUTC = exports.getMinutesFromUTC = exports.getCurrentTime = exports.getCurrentDateTime = exports.formatUTCOffset = exports.extractTotalMinutesFromTime = exports.extractTimeStringFromUTC = exports.extractTimeFromUTC = exports.extractMinutesFromUTC = exports.extractHourMinute = exports.convertMinutesToUTCOffset = exports.chronusts = exports.chronusjs = exports.chronus = exports.chronosts = exports.chronosjs = exports.chronos = exports.Chronus = exports.Chronos = exports.isValidUTCOffSet = exports.isValidUTC = exports.isValidTimeString = exports.isValidTime = exports.isLeapYear = exports.greet = exports.getGreeting = exports.generateGreeting = exports.Colour = exports.Color = exports.convertRgbToRgba = exports.convertRgbToHsl = exports.convertRgbToHex = void 0;
-exports.updateQueryParam = exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.remapObjectFields = exports.remapFields = exports.pickObjectFieldsByCondition = exports.pickObjectFields = exports.pickFieldsByCondition = exports.pickFields = exports.convertObjectValues = exports.sanitizeData = exports.parseStringifiedValues = exports.parseStringifiedPrimitives = exports.parseStringifiedObjectValues = exports.parsePrimitives = exports.parsePrimitiveData = exports.parseObjectValues = exports.mergeObjects = exports.mergeAndFlattenObjects = exports.flattenObjectKeyValue = exports.flattenObjectDotNotation = exports.extractUpdatedFields = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.countObjectFields = exports.cloneObject = exports.isValidFormData = exports.isOriginFileObj = exports.isFileUpload = exports.isFileList = exports.isFileArray = exports.isCustomFileArray = exports.isCustomFile = exports.serializeForm = exports.parseFormData = exports.createFormData = exports.createControlledFormData = exports.convertIntoFormData = exports.naturalSortForString = exports.naturalSort = exports.compareSorter = exports.compareNaturally = exports.splitArray = exports.rotateArray = exports.removeDuplicatesFromArray = exports.removeDuplicates = exports.moveArrayElement = exports.getMissingElements = void 0;
-exports.isObjectEmpty = exports.isObject = exports.isNotEmptyObject = exports.isMethodDescriptor = exports.isMethod = exports.isMap = exports.isJSONObject = exports.isJSON = exports.isFunction = exports.isError = exports.isEmptyObjectGuard = exports.isEmptyObject = exports.isDate = exports.isBigInt = exports.isArrayWithLength = exports.isArrayOfType = exports.isArray = exports.doesReturnPromise = exports.isUndefined = exports.isTruthy = exports.isSymbol = exports.isString = exports.isPrimitive = exports.isPositiveInteger = exports.isNumber = exports.isNull = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.throttleAction = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = exports.getClassDetails = exports.debounceAction = exports.countStaticMethods = exports.countInstanceMethods = exports.convertArrayToString = exports.saveToSessionStorage = exports.saveToLocalStorage = exports.removeFromSessionStorage = exports.removeFromLocalStorage = exports.getFromSessionStorage = exports.getFromLocalStorage = exports.toggleFullScreen = exports.smoothScrollTo = exports.copyToClipboard = void 0;
-exports.isValidURL = exports.isValidEmail = exports.isUUID = exports.isURL = exports.isPhoneNumber = exports.isNumericString = exports.isNodeEnvironment = exports.isNodeENV = exports.isNode = exports.isIPAddress = exports.isExpectedNodeENV = exports.isEnvironment = exports.isEmailArray = exports.isEmail = exports.isDateString = exports.isBrowser = exports.isBase64 = exports.isValidSet = exports.isValidObject = exports.isValidMap = exports.isValidJSON = exports.isValidArray = exports.isSet = exports.isReturningPromise = exports.isRegularExpression = exports.isRegExp = exports.isPromise = exports.isObjectWithKeys = void 0;
+exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.remapObjectFields = exports.remapFields = exports.pickObjectFieldsByCondition = exports.pickObjectFields = exports.pickFieldsByCondition = exports.pickFields = exports.convertObjectValues = exports.sanitizeData = exports.parseStringifiedValues = exports.parseStringifiedPrimitives = exports.parseStringifiedObjectValues = exports.parsePrimitives = exports.parsePrimitiveData = exports.parseObjectValues = exports.parseJsonToObject = exports.mergeObjects = exports.mergeAndFlattenObjects = exports.flattenObjectKeyValue = exports.flattenObjectDotNotation = exports.extractUpdatedFields = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.countObjectFields = exports.cloneObject = exports.isValidFormData = exports.isOriginFileObj = exports.isFileUpload = exports.isFileList = exports.isFileArray = exports.isCustomFileArray = exports.isCustomFile = exports.serializeForm = exports.parseFormData = exports.createFormData = exports.createControlledFormData = exports.convertIntoFormData = exports.naturalSortForString = exports.naturalSort = exports.compareSorter = exports.compareNaturally = exports.splitArray = exports.rotateArray = exports.removeDuplicatesFromArray = exports.removeDuplicates = exports.moveArrayElement = exports.getMissingElements = void 0;
+exports.isFunction = exports.isError = exports.isEmptyObjectGuard = exports.isEmptyObject = exports.isDate = exports.isBigInt = exports.isArrayWithLength = exports.isArrayOfType = exports.isArray = exports.doesReturnPromise = exports.isUndefined = exports.isTruthy = exports.isSymbol = exports.isString = exports.isPrimitive = exports.isPositiveInteger = exports.isNumber = exports.isNull = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.throttleAction = exports.parsePrimitivesDeep = exports.parseJsonDeep = exports.parseJSON = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = exports.getClassDetails = exports.deepParsePrimitives = exports.debounceAction = exports.countStaticMethods = exports.countInstanceMethods = exports.convertArrayToString = exports.saveToSessionStorage = exports.saveToLocalStorage = exports.removeFromSessionStorage = exports.removeFromLocalStorage = exports.getFromSessionStorage = exports.getFromLocalStorage = exports.toggleFullScreen = exports.smoothScrollTo = exports.copyToClipboard = exports.updateQueryParam = exports.getQueryStringAsObject = exports.queryStringToObject = exports.parseQueryString = void 0;
+exports.isValidURL = exports.isValidEmail = exports.isUUID = exports.isURL = exports.isPhoneNumber = exports.isNumericString = exports.isNodeEnvironment = exports.isNodeENV = exports.isNode = exports.isIPAddress = exports.isExpectedNodeENV = exports.isEnvironment = exports.isEmailArray = exports.isEmail = exports.isDateString = exports.isBrowser = exports.isBase64 = exports.isValidSet = exports.isValidObject = exports.isValidMap = exports.isValidJSON = exports.isValidArray = exports.isSet = exports.isReturningPromise = exports.isRegularExpression = exports.isRegExp = exports.isPromise = exports.isObjectWithKeys = exports.isObjectEmpty = exports.isObject = exports.isNotEmptyObject = exports.isMethodDescriptor = exports.isMethod = exports.isMap = exports.isJSONObject = exports.isJSON = void 0;
 // ! String Utilities
 var basics_1 = require("./string/basics");
 Object.defineProperty(exports, "capitalizeString", { enumerable: true, get: function () { return basics_1.capitalizeString; } });
@@ -34,12 +34,12 @@ Object.defineProperty(exports, "replaceAllInString", { enumerable: true, get: fu
 Object.defineProperty(exports, "reverseString", { enumerable: true, get: function () { return convert_1.reverseString; } });
 Object.defineProperty(exports, "slugifyString", { enumerable: true, get: function () { return convert_1.slugifyString; } });
 var utilities_1 = require("./string/utilities");
+Object.defineProperty(exports, "countWords", { enumerable: true, get: function () { return utilities_1.countWords; } });
+Object.defineProperty(exports, "countWordsInString", { enumerable: true, get: function () { return utilities_1.countWords; } });
 Object.defineProperty(exports, "extractNumbersFromString", { enumerable: true, get: function () { return utilities_1.extractNumbersFromString; } });
 Object.defineProperty(exports, "getLevenshteinDistance", { enumerable: true, get: function () { return utilities_1.getLevenshteinDistance; } });
 Object.defineProperty(exports, "levenshteinDistance", { enumerable: true, get: function () { return utilities_1.getLevenshteinDistance; } });
-Object.defineProperty(exports, "countWords", { enumerable: true, get: function () { return utilities_1.countWords; } });
 Object.defineProperty(exports, "wordCount", { enumerable: true, get: function () { return utilities_1.countWords; } });
-Object.defineProperty(exports, "countWordsInString", { enumerable: true, get: function () { return utilities_1.countWords; } });
 // ! Number Utilities
 var basics_2 = require("./number/basics");
 Object.defineProperty(exports, "calculateAverage", { enumerable: true, get: function () { return basics_2.getAverage; } });
@@ -225,6 +225,7 @@ Object.defineProperty(exports, "flattenObjectDotNotation", { enumerable: true, g
 Object.defineProperty(exports, "flattenObjectKeyValue", { enumerable: true, get: function () { return objectify_1.flattenObjectKeyValue; } });
 Object.defineProperty(exports, "mergeAndFlattenObjects", { enumerable: true, get: function () { return objectify_1.mergeAndFlattenObjects; } });
 Object.defineProperty(exports, "mergeObjects", { enumerable: true, get: function () { return objectify_1.mergeObjects; } });
+Object.defineProperty(exports, "parseJsonToObject", { enumerable: true, get: function () { return objectify_1.parseJsonToObject; } });
 var sanitize_1 = require("./object/sanitize");
 Object.defineProperty(exports, "parseObjectValues", { enumerable: true, get: function () { return sanitize_1.parseObjectValues; } });
 Object.defineProperty(exports, "parsePrimitiveData", { enumerable: true, get: function () { return sanitize_1.parseObjectValues; } });
@@ -247,6 +248,9 @@ Object.defineProperty(exports, "createQueryParams", { enumerable: true, get: fun
 Object.defineProperty(exports, "formatQueryParams", { enumerable: true, get: function () { return query_1.generateQueryParams; } });
 Object.defineProperty(exports, "generateQueryParams", { enumerable: true, get: function () { return query_1.generateQueryParams; } });
 Object.defineProperty(exports, "getQueryParams", { enumerable: true, get: function () { return query_1.getQueryParams; } });
+Object.defineProperty(exports, "parseQueryString", { enumerable: true, get: function () { return query_1.parseQueryString; } });
+Object.defineProperty(exports, "queryStringToObject", { enumerable: true, get: function () { return query_1.parseQueryString; } });
+Object.defineProperty(exports, "getQueryStringAsObject", { enumerable: true, get: function () { return query_1.parseQueryString; } });
 Object.defineProperty(exports, "updateQueryParam", { enumerable: true, get: function () { return query_1.updateQueryParam; } });
 var utils_3 = require("./dom/utils");
 Object.defineProperty(exports, "copyToClipboard", { enumerable: true, get: function () { return utils_3.copyToClipboard; } });
@@ -265,12 +269,16 @@ Object.defineProperty(exports, "convertArrayToString", { enumerable: true, get:
 Object.defineProperty(exports, "countInstanceMethods", { enumerable: true, get: function () { return utils_4.countInstanceMethods; } });
 Object.defineProperty(exports, "countStaticMethods", { enumerable: true, get: function () { return utils_4.countStaticMethods; } });
 Object.defineProperty(exports, "debounceAction", { enumerable: true, get: function () { return utils_4.debounceAction; } });
+Object.defineProperty(exports, "deepParsePrimitives", { enumerable: true, get: function () { return utils_4.deepParsePrimitives; } });
 Object.defineProperty(exports, "getClassDetails", { enumerable: true, get: function () { return utils_4.getClassDetails; } });
 Object.defineProperty(exports, "getInstanceMethodNames", { enumerable: true, get: function () { return utils_4.getInstanceMethodNames; } });
 Object.defineProperty(exports, "getInstanceMethodsCount", { enumerable: true, get: function () { return utils_4.countInstanceMethods; } });
 Object.defineProperty(exports, "getStaticMethodNames", { enumerable: true, get: function () { return utils_4.getStaticMethodNames; } });
 Object.defineProperty(exports, "getStaticMethodsCount", { enumerable: true, get: function () { return utils_4.countStaticMethods; } });
 Object.defineProperty(exports, "isDeepEqual", { enumerable: true, get: function () { return utils_4.isDeepEqual; } });
+Object.defineProperty(exports, "parseJSON", { enumerable: true, get: function () { return utils_4.parseJSON; } });
+Object.defineProperty(exports, "parseJsonDeep", { enumerable: true, get: function () { return utils_4.parseJSON; } });
+Object.defineProperty(exports, "parsePrimitivesDeep", { enumerable: true, get: function () { return utils_4.deepParsePrimitives; } });
 Object.defineProperty(exports, "throttleAction", { enumerable: true, get: function () { return utils_4.throttleAction; } });
 // ! Primitive Type Guards
 var primitives_1 = require("./guards/primitives");

package/dist/cjs/object/objectify.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.extractUpdatedFields = exports.flattenObjectDotNotation = exports.flattenObjectKeyValue = exports.mergeAndFlattenObjects = exports.mergeObjects = void 0;
+exports.parseJsonToObject = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.extractUpdatedFields = exports.flattenObjectDotNotation = exports.flattenObjectKeyValue = exports.mergeAndFlattenObjects = exports.mergeObjects = void 0;
 const non_primitives_1 = require("../guards/non-primitives");
 const utils_1 = require("../utils");
+const sanitize_1 = require("./sanitize");
 /**
  * * Deeply merge two or more objects using `Map`.
  *
@@ -213,3 +214,25 @@ const extractUpdatedAndNewFields = (baseObject, updatedObject) => {
     return { ...updatedFields, ...newFields };
 };
 exports.extractUpdatedAndNewFields = extractUpdatedAndNewFields;
+/**
+ * * Safely parses a JSON string into an object.
+ *
+ * *Optionally converts stringified primitive values inside the object (e.g., `"0"` → `0`, `"true"` → `true`, `"null"` → `null`).*
+ *
+ * @param value - The JSON string to parse.
+ * @param parsePrimitives - Whether to convert stringified primitives into real values (default: `true`).
+ * @returns A parsed object with primitive conversions, or an empty object on failure or if the root is not a valid object.
+ */
+const parseJsonToObject = (value, parsePrimitives = true) => {
+    try {
+        const data = JSON.parse(value);
+        if (!(0, non_primitives_1.isObject)(data)) {
+            return {};
+        }
+        return parsePrimitives ? (0, sanitize_1.parseObjectValues)(data) : data;
+    }
+    catch {
+        return {};
+    }
+};
+exports.parseJsonToObject = parseJsonToObject;

package/dist/cjs/object/sanitize.js

@@ -105,6 +105,12 @@ function parseObjectValues(object) {
                 else if (!isNaN(Number(value))) {
                     parsedBody[key] = Number(value);
                 }
+                else if (value === 'undefined') {
+                    parsedBody[key] = undefined;
+                }
+                else if (value === 'null') {
+                    parsedBody[key] = null;
+                }
                 else {
                     parsedBody[key] = value;
                 }