toolbox-x 1.0.0

package/dist/pluralizer.cjs

@@ -0,0 +1,678 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+const require_utilities = require('./utilities-CLUmdQeV.cjs');
+
+//#region src/pluralizer/rules.ts
+/** Irregular singular → plural mappings */
+const irregularRules = /* @__PURE__ */ Object.freeze([
+	["I", "we"],
+	["me", "us"],
+	["he", "they"],
+	["she", "they"],
+	["them", "them"],
+	["myself", "ourselves"],
+	["yourself", "yourselves"],
+	["itself", "themselves"],
+	["herself", "themselves"],
+	["himself", "themselves"],
+	["themself", "themselves"],
+	["this", "these"],
+	["that", "those"],
+	["my", "our"],
+	["its", "their"],
+	["his", "their"],
+	["her", "their"],
+	["is", "are"],
+	["was", "were"],
+	["has", "have"],
+	["analysis", "analyses"],
+	["anathema", "anathemata"],
+	["appendix", "appendices"],
+	["automaton", "automata"],
+	["basis", "bases"],
+	["calf", "calves"],
+	["carve", "carves"],
+	["child", "children"],
+	["codex", "codices"],
+	["criterion", "criteria"],
+	["crisis", "crises"],
+	["datum", "data"],
+	["diagnosis", "diagnoses"],
+	["die", "dice"],
+	["dogma", "dogmata"],
+	["echo", "echoes"],
+	["elf", "elves"],
+	["foot", "feet"],
+	["genus", "genera"],
+	["goose", "geese"],
+	["groove", "grooves"],
+	["half", "halves"],
+	["hedron", "hedra"],
+	["hero", "heroes"],
+	["hoof", "hooves"],
+	["human", "humans"],
+	["honey", "honeys"],
+	["index", "indices"],
+	["leaf", "leaves"],
+	["lemma", "lemmata"],
+	["loaf", "loaves"],
+	["looey", "looies"],
+	["man", "men"],
+	["mango", "mangoes"],
+	["matrix", "matrices"],
+	["medium", "media"],
+	["mouse", "mice"],
+	["neurosis", "neuroses"],
+	["noumenon", "noumena"],
+	["organon", "organa"],
+	["ox", "oxen"],
+	["passerby", "passersby"],
+	["phenomenon", "phenomena"],
+	["pickaxe", "pickaxes"],
+	["potato", "potatoes"],
+	["prolegomenon", "prolegomena"],
+	["proof", "proofs"],
+	["quiz", "quizzes"],
+	["schema", "schemata"],
+	["self", "selves"],
+	["shelf", "shelves"],
+	["stigma", "stigmata"],
+	["stoma", "stomata"],
+	["thief", "thieves"],
+	["tooth", "teeth"],
+	["tomato", "tomatoes"],
+	["torpedo", "torpedoes"],
+	["tornado", "tornadoes"],
+	["valve", "valves"],
+	["vertex", "vertices"],
+	["virus", "viruses"],
+	["viscus", "viscera"],
+	["volcano", "volcanoes"],
+	["woman", "women"],
+	["wolf", "wolves"],
+	["yes", "yeses"]
+]);
+/** Pluralization rules with regex and replacements */
+const pluralRules = /* @__PURE__ */ Object.freeze([
+	[/s?$/i, "s"],
+	[/(pe)(rson|ople)$/i, "$1ople"],
+	[/(child)(?:ren)?$/i, "$1ren"],
+	[/(alumn|alg|vertebr)(?:a|ae)$/i, "$1ae"],
+	[/(apheli|hyperbat|periheli|asyndet|noumen|phenomen|criteri|organ|prolegomen|hedr|automat)a$/i, "$1a"],
+	[/(agend|addend|millenni|dat|extrem|bacteri|desiderat|strat|candelabr|errat|ov|symposi|curricul|quor)um$/i, "$1a"],
+	[/(octop|vir)us$/i, "$1i"],
+	[/(cris|ax|test)is$/i, "$1es"],
+	[/(alias|status)$/i, "$1es"],
+	[/(shoe)$/i, "$1s"],
+	[/(bus)$/i, "$1es"],
+	[/(o)es$/i, "$1es"],
+	[/(x|ch|ss|sh|zz)$/i, "$1es"],
+	[/(her|at|gr)o$/i, "$1oes"],
+	[/sis$/i, "ses"],
+	[/^(chief|chef|belief|roof|cliff|reef)$/i, "$1s"],
+	[/(seraph|cherub)$/i, "$1im"],
+	[/(kni|wi|li)fe$/i, "$1ves"],
+	[/(ar|l|ea|eo|oa|hoo)f$/i, "$1ves"],
+	[/([^aeiouy]|qu)y$/i, "$1ies"],
+	[/(tive)$/i, "$1s"],
+	[/(hive)$/i, "$1s"],
+	[/(quiz)$/i, "$1zes"],
+	[/m[ae]n$/i, "men"],
+	[/eaux$/i, "$0"],
+	[/(alumn|syllab|vir|radi|nucle|fung|cact|stimul|termin|bacill|foc|uter|loc|strat)(?:us|i)$/i, "$1i"]
+]);
+/** Singularization rules with regex and replacements */
+const singularRules = /* @__PURE__ */ Object.freeze([
+	[/s$/i, ""],
+	[/(\P{ASCII})$/u, "$1"],
+	[/(pe)(rson|ople)$/i, "$1rson"],
+	[/(child)ren$/i, "$1"],
+	[/(eau)x?$/i, "$1"],
+	[/men$/i, "man"],
+	[/(matr|append)ices$/i, "$1ix"],
+	[/(cod|mur|sil|vert|ind)ices$/i, "$1ex"],
+	[/(alumn|alg|vertebr)ae$/i, "$1a"],
+	[/(apheli|hyperbat|periheli|asyndet|noumen|phenomen|criteri|organ|prolegomen|hedr|automat)a$/i, "$1on"],
+	[/(agend|addend|millenni|dat|extrem|bacteri|desiderat|strat|candelabr|errat|ov|symposi|curricul|quor)a$/i, "$1um"],
+	[/(test)(?:is|es)$/i, "$1is"],
+	[/(movie|twelve|abuse|e[mn]u)s$/i, "$1"],
+	[/(analy|diagno|parenthe|progno|synop|the|empha|cri|ne)(?:sis|ses)$/i, "$1sis"],
+	[/(x|ch|ss|sh|zz|tto|go|cho|alias|[^aou]us|t[lm]as|gas|(?:her|at|gr)o|[aeiou]ris)(?:es)?$/i, "$1"],
+	[/^(chief|chef|belief|roof|cliff|reef)s$/i, "$1"],
+	[/(seraph|cherub)im$/i, "$1"],
+	[/\b((?:tit)?m|l)ice$/i, "$1ouse"],
+	[/\b(mon|smil)ies$/i, "$1ey"],
+	[/\b([pl]|zomb|(?:neck|cross)?t|coll|faer|food|gen|goon|group|lass|talk|goal|cut)ies$/i, "$1ie"],
+	[/ies$/i, "y"],
+	[/(kni|wi|li)ves$/i, "$1fe"],
+	[/(ar|l|ea|eo|oa|hoo)ves$/i, "$1f"],
+	[/(ar|(?:wo|[ae])l|[eo][ao])ves$/i, "$1f"],
+	[/(wi|kni|(?:after|half|high|low|mid|non|night|[^\w]|^)li)ves$/i, "$1fe"],
+	[/(ss)$/i, "$1"],
+	[/(quiz)zes$/i, "$1"],
+	[/(vert|ind)ices$/i, "$1ex"],
+	[/^(ox)en$/i, "$1"],
+	[/(alias|status)es$/i, "$1"],
+	[/(octop|vir)i$/i, "$1us"],
+	[/(cris|ax|test)es$/i, "$1is"],
+	[/(shoe)s$/i, "$1"],
+	[/(her|at|gr)oes$/i, "$1o"],
+	[/oes$/i, "o"],
+	[/(bus)es$/i, "$1"],
+	[/ices$/i, "ex"],
+	[/(hive)s$/i, "$1"],
+	[/(tive)s$/i, "$1"],
+	[/([^f])ves$/i, "$1fe"],
+	[/([lr])ves$/i, "$1f"],
+	[/(^analy)ses$/i, "$1sis"],
+	[/([ti])a$/i, "$1um"],
+	[/(n)ews$/i, "$1ews"],
+	[/(alumn|syllab|vir|radi|nucle|fung|cact|stimul|termin|bacill|foc|uter|loc|strat)(?:us|i)$/i, "$1us"]
+]);
+/** Uncountable words */
+const uncountables = /* @__PURE__ */ Object.freeze(new Set([
+	"aircraft",
+	"alcohol",
+	"ammo",
+	"analytics",
+	"anime",
+	"athletics",
+	"audio",
+	"bison",
+	"blood",
+	"butter",
+	"cash",
+	"chess",
+	"clothing",
+	"commerce",
+	"corps",
+	"debris",
+	"diabetes",
+	"energy",
+	"equipment",
+	"furniture",
+	"hardware",
+	"headquarters",
+	"health",
+	"homework",
+	"housework",
+	"information",
+	"insurance",
+	"jewelry",
+	"jewellery",
+	"knowledge",
+	"livestock",
+	"luck",
+	"machinery",
+	"metadata",
+	"money",
+	"music",
+	"news",
+	"poetry",
+	"pollution",
+	"research",
+	"rice",
+	"series",
+	"software",
+	"species",
+	"staff",
+	"traffic",
+	"transportation",
+	"weather",
+	"wildlife",
+	"you",
+	"adulthood",
+	"advertising",
+	"anger",
+	"applause",
+	"arithmetic",
+	"bacon",
+	"beef",
+	"biology",
+	"botany",
+	"carbon",
+	"chaos",
+	"cheese",
+	"childhood",
+	"coffee",
+	"compassion",
+	"cotton",
+	"dancing",
+	"delight",
+	"dignity",
+	"dirt",
+	"distribution",
+	"dust",
+	"economics",
+	"education",
+	"electricity",
+	"engineering",
+	"envy",
+	"ethics",
+	"evidence",
+	"evolution",
+	"failure",
+	"faith",
+	"fame",
+	"fiction",
+	"flour",
+	"flu",
+	"freedom",
+	"fuel",
+	"fun",
+	"garbage",
+	"garlic",
+	"genetics",
+	"golf",
+	"gossip",
+	"grammar",
+	"gratitude",
+	"grief",
+	"guilt",
+	"gymnastics",
+	"happiness",
+	"harm",
+	"hate",
+	"hatred",
+	"height",
+	"help",
+	"honesty",
+	"hospitality",
+	"humor",
+	"humour",
+	"hunger",
+	"importance",
+	"inflation",
+	"injustice",
+	"innocence",
+	"intelligence",
+	"irony",
+	"jealousy",
+	"joy",
+	"judo",
+	"justice",
+	"karate",
+	"kindness",
+	"labour",
+	"lack",
+	"laughter",
+	"lava",
+	"leather",
+	"leisure",
+	"lightning",
+	"linguistics",
+	"literature",
+	"litter",
+	"logic",
+	"loneliness",
+	"love",
+	"luggage",
+	"magic",
+	"management",
+	"mankind",
+	"marble",
+	"mathematics",
+	"mayonnaise",
+	"measles",
+	"meat",
+	"methane",
+	"mud",
+	"nature",
+	"nitrogen",
+	"nonsense",
+	"nurture",
+	"nutrition",
+	"obedience",
+	"obesity",
+	"passion",
+	"patience",
+	"permission",
+	"physics",
+	"poverty",
+	"pride",
+	"production",
+	"progress",
+	"pronunciation",
+	"psychology",
+	"publicity",
+	"punctuation",
+	"quality",
+	"quantity",
+	"quartz",
+	"racism",
+	"rain",
+	"recreation",
+	"relaxation",
+	"reliability",
+	"research",
+	"respect",
+	"revenge",
+	"rubbish",
+	"rum",
+	"safety",
+	"salt",
+	"sand",
+	"satire",
+	"scenery",
+	"shame",
+	"shopping",
+	"silence",
+	"sleep",
+	"smoke",
+	"smoking",
+	"snow",
+	"soap",
+	"soil",
+	"sorrow",
+	"speed",
+	"spelling",
+	"steam",
+	"strength",
+	"stuff",
+	"stupidity",
+	"success",
+	"sugar",
+	"sunshine",
+	"symmetry",
+	"tea",
+	"tennis",
+	"thirst",
+	"thunder",
+	"timber",
+	"toast",
+	"tolerance",
+	"trade",
+	"trust",
+	"understanding",
+	"underwear",
+	"unemployment",
+	"unity",
+	"usage",
+	"validity",
+	"veal",
+	"vegetation",
+	"vegetarianism",
+	"vengeance",
+	"violence",
+	"vision",
+	"vitality",
+	"warmth",
+	"wealth",
+	"weight",
+	"welfare",
+	"whiskey",
+	"width",
+	"wisdom",
+	"wool",
+	"yeast",
+	"yoga",
+	"youth",
+	"zinc",
+	"zoology",
+	/pok[eé]mon$/i,
+	/[^aeiou]ese$/i,
+	/deer$/i,
+	/fish$/i,
+	/measles$/i,
+	/o[iu]s$/i,
+	/pox$/i,
+	/sheep$/i,
+	/scissors$/i,
+	/pants$/i,
+	/shorts$/i,
+	/trousers$/i,
+	/jeans$/i
+]));
+
+//#endregion
+//#region src/pluralizer/Pluralizer.ts
+/**
+* @class 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.
+*      - Supports adding custom pluralization and singularization rules, as well as uncountable nouns.
+*      - Automatically handles common irregular forms like "child" to "children"
+*      - 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://toolbox.nazmul-nhb.dev/docs/utilities/string/formatUnitWithPlural formatUnitWithPlural} instead.
+*
+* - For ready to use instance, please refer to {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/pluralizer pluralizer} instead.
+*
+* @example
+* const pluralizer = new Pluralizer();
+* pluralizer.pluralize('child'); // "children"
+* pluralizer.toSingular('geese'); // "goose"
+* pluralizer.isPlural('fish'); // false (uncountable)
+*/
+var Pluralizer = class {
+	#pluralRules = [];
+	#singularRules = [];
+	#uncountables = /* @__PURE__ */ new Set();
+	#irregularSingles = {};
+	#irregularPlurals = {};
+	/**
+	* Initializes the Pluralizer with default rules and exceptions.
+	* Automatically loads irregular, pluralization and singular rules along with pre-defined uncountable nouns.
+	*/
+	constructor() {
+		this.#loadRules();
+	}
+	#loadRules() {
+		irregularRules.forEach(([single, plural]) => {
+			this.addIrregular(single, plural);
+		});
+		pluralRules.forEach(([rule, replacement]) => {
+			this.addPluralRule(rule, replacement);
+		});
+		singularRules.forEach(([rule, replacement]) => {
+			this.addSingularRule(rule, replacement);
+		});
+		uncountables.forEach((word) => {
+			this.addUncountable(word);
+		});
+	}
+	/** Restore case order(s) */
+	#restoreCase(original, transformed) {
+		original = original?.trim();
+		if (original === transformed) return transformed;
+		if (original === original.toLowerCase()) return transformed.toLowerCase();
+		if (original === original.toUpperCase()) return transformed.toUpperCase();
+		if (original[0] === original[0].toUpperCase() && original.slice(1) === original.slice(1).toLowerCase()) return transformed.charAt(0).toUpperCase() + transformed.slice(1).toLowerCase();
+		let result = "";
+		for (let i = 0; i < transformed.length; i++) {
+			const origChar = original[i];
+			if (origChar && origChar === origChar.toUpperCase() && origChar !== origChar.toLowerCase()) result += transformed[i].toUpperCase();
+			else result += transformed[i].toLowerCase();
+		}
+		return result;
+	}
+	/** Apply corresponding rules */
+	#applyRules(word, rules) {
+		if (!require_primitives.isNonEmptyString(word)) return "";
+		if (this.#isUncountable(word)) return word;
+		for (let i = rules.length - 1; i >= 0; i--) {
+			const [rule, replacement] = rules[i];
+			if (rule.test(word)) return word.replace(rule, replacement);
+		}
+		return word;
+	}
+	/**
+	* Check if a word is uncountable.
+	* Supports both `string` and `RegExp` entries.
+	*/
+	#isUncountable(word) {
+		for (const entry of this.#uncountables) if (require_primitives.isString(entry)) {
+			if (entry.toLowerCase() === word) return true;
+		} else if (entry?.test(word)) return true;
+		return false;
+	}
+	/**
+	* * Add a new pluralization rule.
+	* @param rule Pattern to match singular words.
+	* @param replacement Replacement pattern for plural form.
+	* @example
+	* pluralizer.addPluralRule(/(quiz)$/i, '$1zes');
+	*/
+	addPluralRule(rule, replacement) {
+		this.#pluralRules.push([rule, replacement]);
+	}
+	/**
+	* * Add a new singularization rule.
+	* @param rule Pattern to match plural words.
+	* @param replacement Replacement pattern for singular form.
+	* @example
+	* pluralizer.addSingularRule(/(matr)ices$/i, '$1ix');
+	*/
+	addSingularRule(rule, replacement) {
+		this.#singularRules.push([rule, replacement]);
+	}
+	/**
+	* * 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);
+	*/
+	addUncountable(word) {
+		this.#uncountables.add(require_primitives.isString(word) ? word?.toLowerCase() : word);
+	}
+	/**
+	* * Add a custom irregular form.
+	* @param single Singular word.
+	* @param plural Plural word.
+	* @example
+	* pluralizer.addIrregular('person', 'people');
+	*/
+	addIrregular(single, plural) {
+		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 optional count.
+	* @param word Target word to pluralize or singularize.
+	* @param options Optional count and inclusive formatting.
+	* @returns The transformed word.
+	* @example
+	* pluralizer.pluralize('category', { count: 3 }); // "categories"
+	* pluralizer.pluralize('child', { count: 1, inclusive: true }); // "1 child"
+	*/
+	pluralize(word, options = {}) {
+		const count = require_utilities.normalizeNumber(options?.count);
+		if (!require_primitives.isUndefined(count)) {
+			const pluralized = count === 1 ? this.toSingular(word) : this.toPlural(word);
+			return options?.inclusive ? `${count} ${pluralized}` : pluralized;
+		}
+		return this.toPlural(word);
+	}
+	/**
+	* * 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 (!require_primitives.isNonEmptyString(word)) return "";
+		const lower = word?.trim()?.toLowerCase();
+		if (this.#isUncountable(lower)) return word;
+		if (this.#irregularSingles[lower]) return this.#restoreCase(word, this.#irregularSingles[lower]);
+		return this.#restoreCase(word, this.#applyRules(lower, this.#pluralRules));
+	}
+	/**
+	* * 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 (!require_primitives.isNonEmptyString(word)) return "";
+		const lower = word?.trim()?.toLowerCase();
+		if (this.#isUncountable(lower)) return word;
+		if (this.#irregularPlurals[lower]) return this.#restoreCase(word, this.#irregularPlurals[lower]);
+		return this.#restoreCase(word, this.#applyRules(lower, this.#singularRules));
+	}
+	/**
+	* * Check if a given word is plural.
+	* @param word Word to check.
+	* @returns `true` if the word is plural, otherwise `false`.
+	* @remarks Always returns `true` for uncountable nouns.
+	* @example
+	* pluralizer.isPlural('children'); // true
+	* pluralizer.isPlural('water'); // true
+	*/
+	isPlural(word) {
+		if (!require_primitives.isNonEmptyString(word)) return false;
+		const lower = word?.trim()?.toLowerCase();
+		if (this.#isUncountable(lower)) return true;
+		if (this.#irregularPlurals[lower]) return true;
+		if (this.#irregularSingles[lower]) return false;
+		return this.toSingular(lower) !== lower;
+	}
+	/**
+	* * Check if a given word is singular.
+	* @param word Word to check.
+	* @returns True if the word is singular, otherwise false.
+	* @remarks Always returns `true` for uncountable nouns.
+	* @example
+	* pluralizer.isSingular('child'); // true
+	* pluralizer.isPlural('water'); // true
+	*/
+	isSingular(word) {
+		if (!require_primitives.isNonEmptyString(word)) return false;
+		const lower = word?.trim()?.toLowerCase();
+		if (this.#isUncountable(lower)) return true;
+		if (this.#irregularSingles[lower]) return true;
+		if (this.#irregularPlurals[lower]) return false;
+		return this.toSingular(lower) === lower;
+	}
+};
+/**
+* Default shared instance of {@link https://toolbox.nazmul-nhb.dev/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://toolbox.nazmul-nhb.dev/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.
+* - Supports adding custom pluralization and singularization rules, as well as uncountable nouns.
+* - Automatically handles common irregular forms like "child" to "children"
+* - Automatically loads common irregular forms and uncountable nouns.
+* - Supports options for count-based pluralization, allowing for inclusive formatting.
+* - This 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.
+* @example
+* import { pluralizer } from 'nhb-toolbox';
+*
+* pluralizer.pluralize('child'); // "children"
+* pluralizer.toSingular('geese'); // "goose"
+* pluralizer.isPlural('fish'); // false (uncountable)
+*/
+const pluralizer = new Pluralizer();
+
+//#endregion
+exports.Pluralizer = Pluralizer;
+exports.pluralizer = pluralizer;