nhb-toolbox 4.24.2 → 4.25.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.25.0] - 2025-11-03
+
+- **Added** new `Chronos` method `durationString(...)` and **Fixed** issues with internal *duration normalization logic*.
+- **Fixed** all *pluralization logic* in `pluralize(...)` method of `Pluralizer` and `formatUnitWithPlural` utility: *Only `1` is considered singular, every other number is plural*.
+
+## [4.24.4] - 2025-10-31
+
+- **Exported** color *checkers/guards* from *main path*. **Reverted** color types (optimized spacing).
+
 ## [4.24.2] - 2025-10-31
 
 - **Fixed** *return type* when no `'colorType'` option is passed in `generateRandomColor`. **Improved** color related *types*.

package/dist/cjs/date/Chronos.js

@@ -205,7 +205,7 @@ class Chronos {
     }
     #normalizeDuration(result, absolute, isFuture) {
         const entries = Object.entries(result);
-        const updated = {};
+        const updated = { ...result };
         if (!absolute && !isFuture) {
             for (const [key, value] of entries) {
                 if (value !== 0) {
@@ -776,6 +776,33 @@ class Chronos {
         };
         return this.#normalizeDuration(result, absolute, isFuture);
     }
+    durationString(options) {
+        const { toTime, absolute = true, maxUnits = 7, separator = ', ', style = 'full', showZero = false, } = options ?? {};
+        const duration = this.duration(toTime, absolute);
+        const units = {
+            years: 'y',
+            months: 'mo',
+            days: 'd',
+            hours: 'h',
+            minutes: 'm',
+            seconds: 's',
+            milliseconds: 'ms',
+        };
+        const _formatUnit = (unit, value) => {
+            if (style === 'short') {
+                return `${value}${units[unit]}`;
+            }
+            const $unit = Math.abs(value) === 1 ? unit.slice(0, -1) : unit;
+            return `${value} ${$unit}`;
+        };
+        const parts = Object.entries(duration)
+            .filter(([_, value]) => showZero || Math.abs(value) > 0)
+            .slice(0, maxUnits)
+            .map(([unit, value]) => _formatUnit(unit, value));
+        return (parts.length ? parts.join(separator)
+            : style === 'short' ? '0s'
+                : '0 seconds');
+    }
     day(index) {
         return constants_1.DAYS[index ?? this.weekDay];
     }

package/dist/cjs/index.js

@@ -3,11 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertToDecimal = exports.calculateLCM = exports.calculateLCD = exports.calculateHCF = exports.calculateGCD = exports.calculateFactorial = exports.calculateAverage = exports.verbalizer = exports.Verbalizer = exports.pluralizer = exports.Pluralizer = exports.VolumeConverter = exports.TimeConverter = exports.TemperatureConverter = exports.MassConverter = exports.LengthConverter = exports.DataConverter = exports.converter = exports.Converter = exports.AreaConverter = exports.wordCount = exports.parseNumbersFromText = exports.levenshteinDistance = exports.getLevenshteinDistance = exports.extractNumbersFromString = exports.extractNumbers = 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.convertRomanToNumeric = exports.convertRomanToInteger = exports.convertRomanToArabic = exports.convertNumberToWordsOrdinal = exports.convertNumberToWords = exports.cardinalWordsToOrdinal = exports.arabicToRoman = exports.isPerfectSquare = exports.isPartOfFibonacciSeries = exports.isPartOfFibonacci = exports.isOddNumber = exports.isOdd = exports.isNumberInvalid = exports.isMultiple = exports.isInvalidNumber = exports.isFibonacci = exports.isEvenNumber = exports.isEven = exports.areNumbersInvalid = exports.areInvalidNumbers = exports.getNthFibonacci = exports.getMemoizedFibonacciSeries = exports.getMemoizedFibonacci = exports.getFibonacciSeriesMemo = exports.getFibonacciSeries = exports.getFibonacciNumbers = exports.getFibonacci = exports.generateFibonacci = exports.fibonacciGenerator = exports.calculatePercentage = exports.UnitConverter = exports.Unit = exports.Currency = exports.sumOfNumbers = exports.sumNumbers = exports.sumDigits = exports.roundToDecimal = exports.roundNumber = exports.reverseNumber = exports.getSumOfNumbers = exports.getRandomNumber = exports.getRandomInt = exports.getFactors = exports.getFactorial = exports.getDivisors = exports.getAverageOfNumbers = exports.getAverage = exports.factorsOf = exports.factorial = exports.convertToFixed = void 0;
 exports.convertHslToHex = exports.convertHslaToRgba = exports.convertHslaToHex8 = exports.convertHexToRgb = exports.convertHexToHsl = exports.convertHex8ToRgba = exports.convertHex8ToHsla = exports.convertColorCode = exports.getRandomHSL = exports.getRandomColor = exports.generateRandomHSLColor = exports.generateRandomHSL = exports.generateRandomColorInHexRGB = exports.generateRandomColor = exports.getColorForInitial = exports.getNumbersInRange = exports.roundToNearestInterval = exports.roundToNearest = exports.roundNumberToNearestInterval = exports.numberToOrdinal = exports.normalizeNumber = 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.wordToNumber = exports.wordsToNumber = exports.toRomanNumeral = exports.toRoman = exports.romanToNumeric = exports.romanToInteger = exports.romanToArabic = exports.numericToRoman = exports.numberToWordsOrdinal = exports.numberToWords = exports.numberToRoman = exports.integerToRoman = exports.convertWordToNumber = exports.convertWordsToNumber = exports.convertToRomanNumerals = void 0;
-exports.getLastArrayElement = exports.flattenArray = exports.filterArrayOfObjects = exports.minutesToUTCOffset = exports.getTotalMinutesFromUTC = exports.getTotalMinutesFromTime = exports.getTotalMinutes = exports.getTimeStringFromUTC = exports.getTimeFromMinutes = exports.getMinutesFromUTC = exports.getHourMinutesFromMinutes = exports.getCurrentTime = exports.getCurrentDateTime = exports.formatUTCOffset = exports.extractTotalMinutesFromTime = exports.extractTimeStringFromUTC = exports.extractTimeFromUTC = exports.extractMinutesFromUTC = exports.extractHourMinute = exports.convertMinutesToUTCOffset = exports.convertMinutesToTime = exports.convertMinutesToHourMinutes = exports.chronusts = exports.chronusjs = exports.chronus = exports.chronosts = exports.chronosjs = exports.chronos = exports.INTERNALS = exports.Chronus = exports.Chronos = exports.isValidUTCOffSet = exports.isValidUTC = exports.isValidTimeString = exports.isValidTime = exports.isLeapYear = exports.isDateLike = exports.greet = exports.getGreeting = exports.generateGreeting = exports.extractSolidColorValues = exports.extractAlphaColorValues = exports.Colour = exports.Color = exports.convertRgbToRgba = exports.convertRgbToHsl = exports.convertRgbToHex = exports.convertRgbaToHsla = exports.convertRgbaToHex8 = exports.convertHslToRgb = void 0;
-exports.extractObjectKeys = exports.extractKeysDeep = exports.extractKeys = exports.countObjectFields = exports.cloneObject = exports.isValidFormData = exports.isOriginFileObj = exports.isFileUpload = exports.isFileOrBlob = 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.splitArrayByProperty = exports.splitArray = exports.rotateArray = exports.removeDuplicatesFromArray = exports.removeDuplicates = exports.moveArrayElement = exports.groupArrayByProperty = exports.getMissingElements = exports.getDuplicatesFromArray = exports.getDuplicates = exports.findMissingElements = exports.extractMissingElements = exports.extractDuplicatesFromArray = exports.extractDuplicates = exports.createOptionsArray = exports.sortAnArray = exports.Finder = exports.totalDeltaByField = exports.sumFieldDifference = exports.sumByField = exports.groupAndSumByField = exports.groupAndAvgByField = exports.groupAndAverageByField = exports.avgByField = exports.averageByField = exports.shuffleArray = exports.isValidEmptyArray = exports.isInvalidOrEmptyArray = void 0;
-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.queryStringToObject = exports.parseQueryStringLiteral = exports.parseQueryString = exports.literalQueryStringToObject = exports.getQueryStringAsObject = exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.removeObjectFields = exports.removeFields = exports.remapObjectFields = exports.remapFields = exports.pickObjectFieldsByCondition = exports.pickObjectFields = exports.pickFieldsByCondition = exports.pickFields = exports.omitObjectFields = exports.omitFields = exports.deleteObjectFields = exports.deleteFields = exports.convertObjectValues = exports.sanitizeData = exports.parseStringifiedObjectValues = exports.parseObjectValues = exports.parseJsonToObject = exports.mergeObjects = exports.mergeAndFlattenObjects = exports.flattenObjectKeyValue = exports.flattenObjectDotNotation = exports.extractUpdatedFields = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.extractObjectKeysDeep = void 0;
-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 = exports.isFunction = exports.isError = exports.isEmptyObjectGuard = exports.isEmptyObject = exports.isDate = 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.isNormalPrimitive = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.isBigInt = exports.Paginator = exports.throttleAction = exports.parsePrimitivesDeep = exports.parseJsonDeep = exports.parseJSON = exports.joinArrayElements = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = 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.httpStatus = exports.HttpStatus = exports.isValidSet = exports.isValidObject = exports.isValidMap = void 0;
+exports.getTotalMinutes = exports.getTimeStringFromUTC = exports.getTimeFromMinutes = exports.getMinutesFromUTC = exports.getHourMinutesFromMinutes = exports.getCurrentTime = exports.getCurrentDateTime = exports.formatUTCOffset = exports.extractTotalMinutesFromTime = exports.extractTimeStringFromUTC = exports.extractTimeFromUTC = exports.extractMinutesFromUTC = exports.extractHourMinute = exports.convertMinutesToUTCOffset = exports.convertMinutesToTime = exports.convertMinutesToHourMinutes = exports.chronusts = exports.chronusjs = exports.chronus = exports.chronosts = exports.chronosjs = exports.chronos = exports.INTERNALS = exports.Chronus = exports.Chronos = exports.isValidUTCOffSet = exports.isValidUTC = exports.isValidTimeString = exports.isValidTime = exports.isLeapYear = exports.isDateLike = exports.greet = exports.getGreeting = exports.generateGreeting = exports.extractSolidColorValues = exports.extractAlphaColorValues = exports.Colour = exports.Color = exports.isRGBA = exports.isRGB = exports.isHSLA = exports.isHSL = exports.isHex8 = exports.isHex6 = exports.convertRgbToRgba = exports.convertRgbToHsl = exports.convertRgbToHex = exports.convertRgbaToHsla = exports.convertRgbaToHex8 = exports.convertHslToRgb = void 0;
+exports.isOriginFileObj = exports.isFileUpload = exports.isFileOrBlob = 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.splitArrayByProperty = exports.splitArray = exports.rotateArray = exports.removeDuplicatesFromArray = exports.removeDuplicates = exports.moveArrayElement = exports.groupArrayByProperty = exports.getMissingElements = exports.getDuplicatesFromArray = exports.getDuplicates = exports.findMissingElements = exports.extractMissingElements = exports.extractDuplicatesFromArray = exports.extractDuplicates = exports.createOptionsArray = exports.sortAnArray = exports.Finder = exports.totalDeltaByField = exports.sumFieldDifference = exports.sumByField = exports.groupAndSumByField = exports.groupAndAvgByField = exports.groupAndAverageByField = exports.avgByField = exports.averageByField = exports.shuffleArray = exports.isValidEmptyArray = exports.isInvalidOrEmptyArray = exports.getLastArrayElement = exports.flattenArray = exports.filterArrayOfObjects = exports.minutesToUTCOffset = exports.getTotalMinutesFromUTC = exports.getTotalMinutesFromTime = void 0;
+exports.saveToSessionStorage = exports.saveToLocalStorage = exports.removeFromSessionStorage = exports.removeFromLocalStorage = exports.getFromSessionStorage = exports.getFromLocalStorage = exports.toggleFullScreen = exports.smoothScrollTo = exports.copyToClipboard = exports.updateQueryParam = exports.queryStringToObject = exports.parseQueryStringLiteral = exports.parseQueryString = exports.literalQueryStringToObject = exports.getQueryStringAsObject = exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.removeObjectFields = exports.removeFields = exports.remapObjectFields = exports.remapFields = exports.pickObjectFieldsByCondition = exports.pickObjectFields = exports.pickFieldsByCondition = exports.pickFields = exports.omitObjectFields = exports.omitFields = exports.deleteObjectFields = exports.deleteFields = exports.convertObjectValues = exports.sanitizeData = exports.parseStringifiedObjectValues = exports.parseObjectValues = exports.parseJsonToObject = exports.mergeObjects = exports.mergeAndFlattenObjects = exports.flattenObjectKeyValue = exports.flattenObjectDotNotation = exports.extractUpdatedFields = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.extractObjectKeysDeep = exports.extractObjectKeys = exports.extractKeysDeep = exports.extractKeys = exports.countObjectFields = exports.cloneObject = exports.isValidFormData = void 0;
+exports.isPromise = exports.isObjectWithKeys = 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.isArrayWithLength = exports.isArrayOfType = exports.isArray = exports.doesReturnPromise = exports.isUndefined = exports.isTruthy = exports.isSymbol = exports.isString = exports.isPrimitive = exports.isPositiveInteger = exports.isNumber = exports.isNull = exports.isNormalPrimitive = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.isBigInt = exports.Paginator = exports.throttleAction = exports.parsePrimitivesDeep = exports.parseJsonDeep = exports.parseJSON = exports.joinArrayElements = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = exports.getClassDetails = exports.deepParsePrimitives = exports.debounceAction = exports.countStaticMethods = exports.countInstanceMethods = exports.convertArrayToString = 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.httpStatus = exports.HttpStatus = exports.isValidSet = exports.isValidObject = exports.isValidMap = exports.isValidJSON = exports.isValidArray = exports.isSet = exports.isReturningPromise = exports.isRegularExpression = exports.isRegExp = void 0;
 var basics_1 = require("./string/basics");
 Object.defineProperty(exports, "capitalizeString", { enumerable: true, get: function () { return basics_1.capitalizeString; } });
 Object.defineProperty(exports, "generateRandomID", { enumerable: true, get: function () { return basics_1.generateRandomID; } });
@@ -186,6 +186,13 @@ Object.defineProperty(exports, "convertRgbaToHsla", { enumerable: true, get: fun
 Object.defineProperty(exports, "convertRgbToHex", { enumerable: true, get: function () { return convert_3.convertRgbToHex; } });
 Object.defineProperty(exports, "convertRgbToHsl", { enumerable: true, get: function () { return convert_3.convertRgbToHsl; } });
 Object.defineProperty(exports, "convertRgbToRgba", { enumerable: true, get: function () { return convert_3.convertRgbToRgba; } });
+var helpers_1 = require("./colors/helpers");
+Object.defineProperty(exports, "isHex6", { enumerable: true, get: function () { return helpers_1._isHex6; } });
+Object.defineProperty(exports, "isHex8", { enumerable: true, get: function () { return helpers_1._isHex8; } });
+Object.defineProperty(exports, "isHSL", { enumerable: true, get: function () { return helpers_1._isHSL; } });
+Object.defineProperty(exports, "isHSLA", { enumerable: true, get: function () { return helpers_1._isHSLA; } });
+Object.defineProperty(exports, "isRGB", { enumerable: true, get: function () { return helpers_1._isRGB; } });
+Object.defineProperty(exports, "isRGBA", { enumerable: true, get: function () { return helpers_1._isRGBA; } });
 var Color_1 = require("./colors/Color");
 Object.defineProperty(exports, "Color", { enumerable: true, get: function () { return Color_1.Color; } });
 Object.defineProperty(exports, "Colour", { enumerable: true, get: function () { return Color_1.Color; } });

package/dist/cjs/pluralizer/Pluralizer.js

@@ -100,8 +100,8 @@ class Pluralizer {
     pluralize(word, options = {}) {
         const count = (0, utilities_1.normalizeNumber)(options?.count);
         if (typeof count === 'number') {
-            const pluralized = count > 1 ? this.toPlural(word) : this.toSingular(word);
-            return options.inclusive ? `${count} ${pluralized}` : pluralized;
+            const pluralized = count === 1 ? this.toSingular(word) : this.toPlural(word);
+            return options?.inclusive ? `${count} ${pluralized}` : pluralized;
         }
         return this.toPlural(word);
     }

package/dist/cjs/string/convert.js

@@ -48,6 +48,6 @@ function extractURLs(str) {
 }
 function formatUnitWithPlural(count, unit, withNumber = true) {
     const abs = Math.abs(count);
-    const pluralized = abs <= 1 ? unit : `${unit}s`;
+    const pluralized = abs === 1 ? unit : `${unit}s`;
     return withNumber ? `${count} ${pluralized}` : pluralized;
 }

package/dist/dts/colors/Color.d.ts

@@ -100,7 +100,7 @@ export declare class Color {
      */
     constructor(color: CSSColor);
     /** - Iterates over the color representations (Hex, RGB, HSL). */
-    [Symbol.iterator](): Generator<Hex8 | `hsl(${number},${number}%,${number}%)` | `hsl(${number},${number}%, ${number}%)` | `hsl(${number}, ${number}%,${number}%)` | `hsl(${number}, ${number}%, ${number}%)` | Hex6 | `rgb(${number},${number},${number})` | `rgb(${number},${number}, ${number})` | `rgb(${number}, ${number},${number})` | `rgb(${number}, ${number}, ${number})` | `rgba(${number},${number},${number},${number})` | `rgba(${number},${number},${number}, ${number})` | `rgba(${number},${number}, ${number},${number})` | `rgba(${number},${number}, ${number}, ${number})` | `rgba(${number}, ${number},${number},${number})` | `rgba(${number}, ${number},${number}, ${number})` | `rgba(${number}, ${number}, ${number},${number})` | `rgba(${number}, ${number}, ${number}, ${number})` | `hsla(${number},${number}%,${number}%,${number})` | `hsla(${number},${number}%,${number}%, ${number})` | `hsla(${number},${number}%, ${number}%,${number})` | `hsla(${number},${number}%, ${number}%, ${number})` | `hsla(${number}, ${number}%,${number}%,${number})` | `hsla(${number}, ${number}%,${number}%, ${number})` | `hsla(${number}, ${number}%, ${number}%,${number})` | `hsla(${number}, ${number}%, ${number}%, ${number})`, void, unknown>;
+    [Symbol.iterator](): Generator<Hex8 | HSL | Hex6 | RGB | RGBA | HSLA, void, unknown>;
     /**
      * @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.

package/dist/dts/colors/types.d.ts

@@ -15,8 +15,6 @@ export type Hex = `#${string}`;
  * * Format: `#3C6945`
  */
 export type Hex6 = Branded<`#${string}`, 'Hex6'>;
-/** Optional space */
-export type $Space = '' | ' ';
 /**
  * * Represents an RGB color string.
  * * Format: `rgb(R, G, B)`
@@ -25,7 +23,7 @@ export type $Space = '' | ' ';
  * - G (Green): 0-255
  * - B (Blue): 0-255
  */
-export type RGB = `rgb(${number},${$Space}${number},${$Space}${number})`;
+export type RGB = `rgb(${number}, ${number}, ${number})` | `rgb(${number},${number},${number})`;
 /**
  * * Represents an HSL color string.
  * * Format: `hsl(H, S%, L%)`
@@ -34,7 +32,7 @@ export type RGB = `rgb(${number},${$Space}${number},${$Space}${number})`;
  * - S (Saturation): 0-100%
  * - L (Lightness): 0-100%
  */
-export type HSL = `hsl(${number},${$Space}${number}%,${$Space}${number}%)`;
+export type HSL = `hsl(${number}, ${number}%, ${number}%)` | `hsl(${number},${number}%,${number}%)`;
 /**
  * * Represents a hexadecimal color code with optional alpha channel.
  * * Format: `#3C6945FF`
@@ -44,12 +42,12 @@ export type Hex8 = Branded<`#${string}`, 'Hex8'>;
  * * Represents an RGBA color string, now includes optional alpha (opacity).
  * * Format: `rgba(R, G, B, A)`
  */
-export type RGBA = `rgba(${number},${$Space}${number},${$Space}${number},${$Space}${number})`;
+export type RGBA = `rgba(${number}, ${number}, ${number}, ${number})` | `rgba(${number},${number},${number},${number})`;
 /**
  * * Represents an HSLA color string with optional alpha channel.
  * * Format: `hsla(H, S%, L%, A)`
  */
-export type HSLA = `hsla(${number},${$Space}${number}%,${$Space}${number}%,${$Space}${number})`;
+export type HSLA = `hsla(${number}, ${number}%, ${number}%, ${number})` | `hsla(${number},${number}%,${number}%,${number})`;
 /** Represents an object with `hex` (`hex6`) and `rgb` color */
 export type RandomHexRGB = {
     /** Represents a hexadecimal color code. */

package/dist/dts/date/Chronos.d.ts

@@ -1,7 +1,7 @@
 import type { Enumerate, LocaleCode, NumberRange } from '../number/types';
 import type { TupleOf } from '../utils/types';
 import { INTERNALS } from './constants';
-import type { $UTCOffset, ChronosInput, ChronosInternals, ChronosMethods, ChronosObject, ChronosPlugin, ChronosWithOptions, DateRangeOptions, FormatOptions, Milliseconds, MonthName, Quarter, RangeWithDates, RelativeDateRange, RelativeRangeOptions, StrictFormat, TimeDuration, TimeParts, TimeUnit, WeekDay } from './types';
+import type { $UTCOffset, ChronosInput, ChronosInternals, ChronosMethods, ChronosObject, ChronosPlugin, ChronosWithOptions, DateRangeOptions, DurationOptions, FormatOptions, Milliseconds, MonthName, Quarter, RangeWithDates, RelativeDateRange, RelativeRangeOptions, StrictFormat, TimeDuration, TimeParts, TimeUnit, WeekDay } from './types';
 /**
  * * Creates a new immutable `Chronos` instance.
  *
@@ -36,7 +36,7 @@ export declare class Chronos {
      * - **NOTE**: It is **HIGHLY** advised *not to rely* on this public property to access native JS `Date`. It's not reliable when timezone and/or UTC related operations are performed. If you really need to use native `Date`, use `toDate` method. This property is purely for developer convenience and sugar.
      */
     native: Date;
-    /** Origin of the `Chronos` instance (Method that created `new Chronos`), useful fo tracking instance. */
+    /** Origin of the `Chronos` instance (Method that created `new Chronos`), useful for tracking instance. */
     origin: ChronosMethods | 'root';
     /**
      * * Creates a new immutable `Chronos` instance.
@@ -493,12 +493,18 @@ export declare class Chronos {
     /** @instance Returns new `Chronos` instance in local time */
     toLocal(): Chronos;
     /**
-     * @instance Returns the full time duration breakdown between current input (start) and another time (to).
-     * @param toTime The time to compare with. Defaults to now.
+     * @instance Returns the full time duration breakdown between current input (start) and another time (to) as object.
+     * @param toTime The time to compare with. Defaults to `now`.
      * @param absolute If true, returns all values as positive numbers. Defaults to `true`.
      * @returns An object of time units: years, months, days, hours, minutes, seconds, milliseconds.
      */
     duration(toTime?: ChronosInput, absolute?: boolean): TimeDuration;
+    /**
+     * @instance Returns a human-readable formatted duration string between the current instance (start) and another time (to).
+     * @param options Options to format duration string, including the time to compare with.
+     * @returns A formatted duration string, e.g. `"2 hours, 5 minutes"` or `"2h 5m"`.
+     */
+    durationString(options?: DurationOptions): string;
     /**
      * @instance Returns the name of the current day or optional day index.
      * @param index Optional day index (`0–6`, where `0` is `Sunday`) to override current day.
@@ -570,7 +576,7 @@ export declare class Chronos {
     /**
      * @static Parses a date string with a given format (limited support only).
      *
-     * * **Supported format tokens**:
+     * **Supported format tokens**:
      * - `YYYY`: Full year (e.g., 2023)
      * - `YY`: Two-digit year (e.g., 23 for 2023, 99 for 1999)
      * - `MM`: Month (01-12)

package/dist/dts/date/types.d.ts

@@ -122,6 +122,23 @@ export interface TimeDuration {
     /** Number of milliseconds remaining after full seconds are counted. */
     milliseconds: number;
 }
+/** Key of {@link TimeDuration} */
+export type DurationKey = keyof TimeDuration;
+/** Options for formatting duration string */
+export interface DurationOptions {
+    /** The time to compare with. Defaults to `now`. */
+    toTime?: ChronosInput;
+    /** If true, returns all values as positive numbers. Defaults to `true`. */
+    absolute?: boolean;
+    /** Maximum number of units to display, e.g. 2 → "1 hour, 20 minutes" */
+    maxUnits?: NumberRange<1, 7>;
+    /** Separator between units (default: `", "`) */
+    separator?: string;
+    /** Display mode: `"full"` (default) → "2 hours", `"short"` → "2h" */
+    style?: 'full' | 'short';
+    /** Whether to include zero values (default: `false`) */
+    showZero?: boolean;
+}
 /** Interface for accessing internal private properties in extended `Chronos` class */
 export interface ChronosInternals {
     /**

package/dist/dts/index.d.ts

@@ -35,6 +35,7 @@ export { getNumbersInRange } from './number/range';
 export { getColorForInitial } from './colors/initials';
 export { generateRandomColor, generateRandomColorInHexRGB, generateRandomHSLColor as generateRandomHSL, generateRandomHSLColor, generateRandomColor as getRandomColor, generateRandomHSLColor as getRandomHSL, } from './colors/random';
 export { convertColorCode, convertHex8ToHsla, convertHex8ToRgba, convertHexToHsl, convertHexToRgb, convertHslaToHex8, convertHslaToRgba, convertHslToHex, convertHslToRgb, convertRgbaToHex8, convertRgbaToHsla, convertRgbToHex, convertRgbToHsl, convertRgbToRgba, } from './colors/convert';
+export { _isHex6 as isHex6, _isHex8 as isHex8, _isHSL as isHSL, _isHSLA as isHSLA, _isRGB as isRGB, _isRGBA as isRGBA, } from './colors/helpers';
 export { Color, Color as Colour } from './colors/Color';
 export { extractAlphaColorValues, extractSolidColorValues } from './colors/utils';
 export { getGreeting as generateGreeting, getGreeting, getGreeting as greet, } from './date/greet';

package/dist/esm/date/Chronos.js

@@ -202,7 +202,7 @@ export class Chronos {
     }
     #normalizeDuration(result, absolute, isFuture) {
         const entries = Object.entries(result);
-        const updated = {};
+        const updated = { ...result };
         if (!absolute && !isFuture) {
             for (const [key, value] of entries) {
                 if (value !== 0) {
@@ -773,6 +773,33 @@ export class Chronos {
         };
         return this.#normalizeDuration(result, absolute, isFuture);
     }
+    durationString(options) {
+        const { toTime, absolute = true, maxUnits = 7, separator = ', ', style = 'full', showZero = false, } = options ?? {};
+        const duration = this.duration(toTime, absolute);
+        const units = {
+            years: 'y',
+            months: 'mo',
+            days: 'd',
+            hours: 'h',
+            minutes: 'm',
+            seconds: 's',
+            milliseconds: 'ms',
+        };
+        const _formatUnit = (unit, value) => {
+            if (style === 'short') {
+                return `${value}${units[unit]}`;
+            }
+            const $unit = Math.abs(value) === 1 ? unit.slice(0, -1) : unit;
+            return `${value} ${$unit}`;
+        };
+        const parts = Object.entries(duration)
+            .filter(([_, value]) => showZero || Math.abs(value) > 0)
+            .slice(0, maxUnits)
+            .map(([unit, value]) => _formatUnit(unit, value));
+        return (parts.length ? parts.join(separator)
+            : style === 'short' ? '0s'
+                : '0 seconds');
+    }
     day(index) {
         return DAYS[index ?? this.weekDay];
     }

package/dist/esm/index.js

@@ -20,6 +20,7 @@ export { getNumbersInRange } from './number/range.js';
 export { getColorForInitial } from './colors/initials.js';
 export { generateRandomColor, generateRandomColorInHexRGB, generateRandomHSLColor as generateRandomHSL, generateRandomHSLColor, generateRandomColor as getRandomColor, generateRandomHSLColor as getRandomHSL, } from './colors/random.js';
 export { convertColorCode, convertHex8ToHsla, convertHex8ToRgba, convertHexToHsl, convertHexToRgb, convertHslaToHex8, convertHslaToRgba, convertHslToHex, convertHslToRgb, convertRgbaToHex8, convertRgbaToHsla, convertRgbToHex, convertRgbToHsl, convertRgbToRgba, } from './colors/convert.js';
+export { _isHex6 as isHex6, _isHex8 as isHex8, _isHSL as isHSL, _isHSLA as isHSLA, _isRGB as isRGB, _isRGBA as isRGBA, } from './colors/helpers.js';
 export { Color, Color as Colour } from './colors/Color.js';
 export { extractAlphaColorValues, extractSolidColorValues } from './colors/utils.js';
 export { getGreeting as generateGreeting, getGreeting, getGreeting as greet, } from './date/greet.js';

package/dist/esm/pluralizer/Pluralizer.js

@@ -97,8 +97,8 @@ export class Pluralizer {
     pluralize(word, options = {}) {
         const count = normalizeNumber(options?.count);
         if (typeof count === 'number') {
-            const pluralized = count > 1 ? this.toPlural(word) : this.toSingular(word);
-            return options.inclusive ? `${count} ${pluralized}` : pluralized;
+            const pluralized = count === 1 ? this.toSingular(word) : this.toPlural(word);
+            return options?.inclusive ? `${count} ${pluralized}` : pluralized;
         }
         return this.toPlural(word);
     }

package/dist/esm/string/convert.js

@@ -37,6 +37,6 @@ export function extractURLs(str) {
 }
 export function formatUnitWithPlural(count, unit, withNumber = true) {
     const abs = Math.abs(count);
-    const pluralized = abs <= 1 ? unit : `${unit}s`;
+    const pluralized = abs === 1 ? unit : `${unit}s`;
     return withNumber ? `${count} ${pluralized}` : pluralized;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.24.2",
+  "version": "4.25.0",
   "description": "A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -39,15 +39,15 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "@eslint/js": "^9.38.0",
+    "@eslint/js": "^9.39.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.9.2",
     "@typescript-eslint/eslint-plugin": "^8.46.2",
     "@typescript-eslint/parser": "^8.46.2",
-    "eslint": "^9.38.0",
+    "eslint": "^9.39.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
-    "globals": "^16.4.0",
+    "globals": "^16.5.0",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
     "lint-staged": "^16.2.6",