nhb-toolbox 4.13.0 → 4.13.3

package/CHANGELOG.md

@@ -6,7 +6,16 @@ All notable changes to the package will be documented here.
 
 ---
 
-## [4.13.0] - 2025-07-21
+## [4.13.3] - 2025-07-22
+
+- **Updated** pluralization/uncountable rules, case restoration method and fixed other bugs in `pluralizer`.
+- **Updated** docs for `pluralizer`, `Pluralizer` and `formatUnitWithPlural`.
+
+## [4.13.1] - 2025-07-22
+
+- **Updated** docs in [README](README.md) for `pluralizer`.
+
+## [4.13.0] - 2025-07-22
 
 - **Added** new `Pluralizer` class and utility `pluralizer` (shared instance of `Pluralizer` class) with multiple methods.
 - **Refactored** codes in number utilities, introduced new `normalizeNumber` utility.

package/README.md

@@ -68,7 +68,7 @@ See [Changelog](CHANGELOG.md) for recent updates.
 
 ## Signature Utilities
 
-### 🕰️ **Chronos - Time Mastery**
+### 🕰️ Chronos - Time Mastery
 
 The ultimate date/time manipulation class with 100+ methods for parsing, formatting, calculating, and comparing dates. Handles all edge cases and timezones safely.
 
@@ -82,7 +82,9 @@ chronos('2025-01-01').addDays(3).format('YYYY-MM-DD'); // "2025-01-04"
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/classes/Chronos)
 
-### 🎨 **Color - Professional Color Manipulation**
+---
+
+### 🎨 Color - Professional Color Manipulation
 
 Convert between color formats, generate palettes, check accessibility contrast, and perform advanced color math with perfect type safety.
 
@@ -94,7 +96,9 @@ console.log(darkerBlue.hsl); // "hsl(240, 100%, 40%)" (was 50%)
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/classes/Color)
 
-### 🔍 **Finder - Optimized Array Search**
+---
+
+### 🔍 Finder - Optimized Array Search
 
 Blazing-fast array searching with binary search, fuzzy matching, and smart caching. Perfect for large datasets.
 
@@ -109,9 +113,11 @@ const laptop = productFinder.findOne('laptop', 'category', {
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/classes/Finder)
 
-### 🆔 **Random ID Generation**
+---
 
-**`generateRandomID`** - Enterprise-grade unique ID generation with prefixes, timestamps, and formatting
+### 🆔 Random ID Generation
+
+**`generateRandomID`** - Enterprise-grade unique ID generation with prefixes, timestamps, and formatting.
 
 ```typescript
 generateRandomID({
@@ -124,7 +130,32 @@ generateRandomID({
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/string/generateRandomID)
 
-### 🎨 **Color System Utilities**
+---
+
+### 🔢 Pluralize Strings and More
+
+**`pluralizer`** - Handles English word pluralization and singularization with support for irregular forms and uncountable nouns.
+
+```ts
+import { pluralizer } from 'nhb-toolbox';
+
+pluralizer.pluralize('child'); // "children"
+pluralizer.pluralize('category', { count: 3 }); // "categories"
+pluralizer.pluralize('child', { count: 1, inclusive: true }); // "1 child"
+
+pluralizer.toSingular('geese'); // "goose"
+pluralizer.toSingular('children'); // "child"
+
+pluralizer.isPlural('children'); // true
+pluralizer.isSingular('child'); // true
+pluralizer.isPlural('fish'); // false (uncountable)
+```
+
+[Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/string/pluralizer)
+
+---
+
+### 🎨 Color System Utilities
 
 **`getColorForInitial`** - Deterministic color mapping system for consistent UI theming
 
@@ -138,6 +169,8 @@ getColorForInitial('Banana', 50); // '#00376E80' (50% opacity)
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/color/getColorForInitial)
 
+---
+
 ### FormData Preparation
 
 Convert JavaScript objects into `FormData` with extensive configuration options for handling nested structures, files, and data transformations.
@@ -169,7 +202,9 @@ const formData = createFormData({
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/form/createFormData)
 
-### 🛡️ **Sanitize Data**
+---
+
+### 🛡️ Data Sanitization
 
 Clean and normalize strings/objects by trimming whitespace, removing empty values, and applying customizable filters.
 
@@ -192,7 +227,9 @@ sanitizeData(user, { ignoreNullish: true }, 'partial');
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/object/sanitizeData)
 
-### 🔄 **JSON Hydration**
+---
+
+### 🔄 JSON Hydration
 
 **`parseJSON`** - Bulletproof JSON parsing with primitive conversion
 
@@ -202,19 +239,9 @@ parseJSON('{"value":"42"}'); // { value: 42 } (auto-converts numbers)
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/misc/parseJSON)
 
-### 💰 **Format Currency**
-
-Intelligent currency formatting with automatic locale detection and 150+ supported currencies.
-
-```typescript
-console.log(formatCurrency(99.99, 'EUR')); // "99,99 €"
-console.log(formatCurrency('5000', 'JPY')); // "￥5,000" (ja-JP locale)
-console.log(formatCurrency('5000', 'BDT')); // "৫,০০০.০০৳" (bn-BD locale)
-```
-
-[Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/number/formatCurrency)
+---
 
-### 🔢 **Number to Words**
+### 🔢 Number to Words
 
 Convert numbers to human-readable words (supports up to 100 quintillion).
 
@@ -224,7 +251,9 @@ numberToWords(125); // "one hundred twenty-five"
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/number/numberToWords)
 
-### 🔢 **Advanced Number Operations**
+---
+
+### 🔢 Advanced Number Operations
 
 **`getNumbersInRange`** - Generate intelligent number sequences with prime, even/odd, and custom filtering capabilities
 
@@ -249,7 +278,9 @@ calculatePercentage({
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/number/calculatePercentage)
 
-### 🔄 **Extract Updated Fields**
+---
+
+### 🔄 Extract Updated Fields
 
 Detect exactly what changed between two objects (including deep nested changes).
 
@@ -262,7 +293,9 @@ extractUpdatedFields(dbRecord, update);
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/object/extractUpdatedFields)
 
-### ⚡ **Performance Optimizers**
+---
+
+### ⚡ Performance Optimizers
 
 **`throttleAction`** - Precision control for high-frequency events
 

package/dist/cjs/pluralize/Pluralizer.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluralizer = exports.Pluralizer = void 0;
+const primitives_1 = require("../guards/primitives");
 const utilities_1 = require("../number/utilities");
 const rules_1 = require("./rules");
 /**
@@ -12,6 +13,11 @@ const rules_1 = require("./rules");
  * - Automatically loads common irregular forms and uncountable nouns.
  * - Supports options for count-based pluralization, allowing for inclusive formatting.
  * - This class is useful for applications that need to handle natural language processing, such as chatbots, content management systems, or any text processing tasks that require accurate pluralization.
+ *
+ * @remarks For simpler pluralization (plural with only 's'), please refer to {@link https://nhb-toolbox.vercel.app/docs/utilities/string/formatUnitWithPlural formatUnitWithPlural} instead.
+ *
+ * @remarks For ready to use instance, please refer to {@link https://nhb-toolbox.vercel.app/docs/utilities/string/pluralizer pluralizer} instead.
+ *
  * @example
  * const pluralizer = new Pluralizer();
  * pluralizer.pluralize('child'); // "children"
@@ -26,7 +32,7 @@ class Pluralizer {
     #irregularPlurals = {};
     /**
      * Initializes the Pluralizer with default rules and exceptions.
-     * Automatically loads irregular rules, pluralization rules, and uncountable nouns.
+     * Automatically loads irregular, pluralization and singular rules along with pre-defined uncountable nouns.
      */
     constructor() {
         this.#loadRules();
@@ -40,21 +46,38 @@ class Pluralizer {
         rules_1.pluralRules.forEach(([rule, replacement]) => {
             this.addPluralRule(rule, replacement);
         });
+        // ! Load singular rules
+        rules_1.singularRules.forEach(([rule, replacement]) => {
+            this.addSingularRule(rule, replacement);
+        });
         // ! Load uncountables
         rules_1.uncountables.forEach((word) => {
             this.addUncountable(word);
         });
     }
-    #restoreCase(word, token) {
-        if (word === word.toUpperCase())
-            return token.toUpperCase();
-        if (word[0] === word[0].toUpperCase()) {
-            return token.charAt(0).toUpperCase() + token.slice(1).toLowerCase();
+    #restoreCase(original, transformed) {
+        let result = '';
+        for (let i = 0; i < transformed.length; i++) {
+            const origChar = original[i];
+            if (origChar) {
+                if (origChar.toUpperCase() === origChar &&
+                    origChar.toLowerCase() !== origChar) {
+                    result += transformed[i].toUpperCase();
+                }
+                else {
+                    result += transformed[i].toLowerCase();
+                }
+            }
+            else {
+                result += transformed[i].toLowerCase();
+            }
         }
-        return token.toLowerCase();
+        return result;
     }
     #sanitizeWord(word, rules) {
-        if (!word.length || this.#isUncountable(word)) {
+        if (!(0, primitives_1.isNonEmptyString)(word))
+            return '';
+        if (this.#isUncountable(word)) {
             return word;
         }
         for (let i = rules.length - 1; i >= 0; i--) {
@@ -70,7 +93,7 @@ class Pluralizer {
      * Supports both string and RegExp entries.
      */
     #isUncountable(word) {
-        const lower = word.toLowerCase();
+        const lower = word?.toLowerCase();
         for (const entry of this.#uncountables) {
             if (typeof entry === 'string') {
                 if (entry === lower)
@@ -94,7 +117,7 @@ class Pluralizer {
         this.#pluralRules.push([rule, replacement]);
     }
     /**
-     * Add a new singularization rule.
+     * * Add a new singularization rule.
      * @param rule Pattern to match plural words.
      * @param replacement Replacement pattern for singular form.
      * @example
@@ -104,23 +127,23 @@ class Pluralizer {
         this.#singularRules.push([rule, replacement]);
     }
     addUncountable(word) {
-        this.#uncountables.add(typeof word === 'string' ? word.toLowerCase() : word);
+        this.#uncountables.add(typeof word === 'string' ? word?.toLowerCase() : word);
     }
     /**
-     * Add a word or pattern that should never change between singular and plural.
+     * * Add a word or pattern that should never change between singular and plural.
      * @param word A word or regex pattern.
      * @example
      * pluralizer.addUncountable('fish');
      * pluralizer.addUncountable(/pok[eé]mon$/i);
      */
     addIrregular(single, plural) {
-        const singleLower = single.toLowerCase();
-        const pluralLower = plural.toLowerCase();
+        const singleLower = single?.toLowerCase();
+        const pluralLower = plural?.toLowerCase();
         this.#irregularSingles[singleLower] = pluralLower;
         this.#irregularPlurals[pluralLower] = singleLower;
     }
     /**
-     * Get the proper singular or plural form based on count.
+     * * Get the proper singular or plural form based on optional count.
      * @param word Target word to pluralize or singularize.
      * @param options Optional count and inclusive formatting.
      * @returns The transformed word.
@@ -137,14 +160,14 @@ class Pluralizer {
         return this.toPlural(word);
     }
     /**
-     * Convert a word to its plural form.
+     * * Convert a word to its plural form.
      * @param word Singular form of the word.
      * @returns Plural form of the word.
      * @example
      * pluralizer.toPlural('analysis'); // "analyses"
      */
     toPlural(word) {
-        if (!word)
+        if (!(0, primitives_1.isNonEmptyString)(word))
             return '';
         const lower = word.toLowerCase();
         if (this.#isUncountable(word))
@@ -155,14 +178,14 @@ class Pluralizer {
         return this.#restoreCase(word, this.#sanitizeWord(lower, this.#pluralRules));
     }
     /**
-     * Convert a word to its singular form.
+     * * Convert a word to its singular form.
      * @param word Plural form of the word.
      * @returns Singular form of the word.
      * @example
      * pluralizer.toSingular('geese'); // "goose"
      */
     toSingular(word) {
-        if (!word)
+        if (!(0, primitives_1.isNonEmptyString)(word))
             return '';
         const lower = word.toLowerCase();
         if (this.#isUncountable(word))
@@ -173,7 +196,7 @@ class Pluralizer {
         return this.#restoreCase(word, this.#sanitizeWord(lower, this.#singularRules));
     }
     /**
-     * Check if a given word is plural.
+     * * Check if a given word is plural.
      * @param word Word to check.
      * @returns True if the word is plural, otherwise false.
      * @example
@@ -188,7 +211,7 @@ class Pluralizer {
         return this.toSingular(lower) !== lower;
     }
     /**
-     * Check if a given word is singular.
+     * * Check if a given word is singular.
      * @param word Word to check.
      * @returns True if the word is singular, otherwise false.
      * @example
@@ -205,11 +228,13 @@ class Pluralizer {
 }
 exports.Pluralizer = Pluralizer;
 /**
- * Default shared instance of {@link Pluralizer}.
+ * Default shared instance of {@link https://nhb-toolbox.vercel.app/docs/classes/Pluralizer Pluralizer}.
  *
  * - _Use this when you don’t need multiple configurations._
  * - _It comes preloaded with standard pluralization rules, irregular forms, and uncountable nouns._
  *
+ * @remarks For simpler pluralization (plural with only 's'), please refer to {@link https://nhb-toolbox.vercel.app/docs/utilities/string/formatUnitWithPlural formatUnitWithPlural} instead.
+ *
  * * Handles English word pluralization and singularization with support for irregular forms and uncountable nouns.
  *
  * - Provides methods to convert words between singular and plural forms, check if a word is plural or singular, and manage custom pluralization rules.