toolbox-x 1.0.0

package/dist/verbalizer.mjs

@@ -0,0 +1,996 @@
+/**
+ * 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.
+ */
+
+import { a as isNonEmptyString } from "./primitives-KsFUp3kQ.mjs";
+
+//#region src/verbalizer/rules.ts
+/** Irregular verb mappings: base → past → past participle */
+const irregularVerbs = /* @__PURE__ */ Object.freeze([
+	[
+		"am",
+		"was",
+		"been"
+	],
+	[
+		"is",
+		"was",
+		"been"
+	],
+	[
+		"are",
+		"were",
+		"been"
+	],
+	[
+		"be",
+		"were",
+		"been"
+	],
+	[
+		"can",
+		"could",
+		"been able"
+	],
+	[
+		"may",
+		"might",
+		""
+	],
+	[
+		"must",
+		"had to",
+		""
+	],
+	[
+		"will",
+		"would",
+		""
+	],
+	[
+		"shall",
+		"should",
+		""
+	],
+	[
+		"arise",
+		"arose",
+		"arisen"
+	],
+	[
+		"awake",
+		"awoke",
+		"awoken"
+	],
+	[
+		"bear",
+		"bore",
+		"born"
+	],
+	[
+		"bear",
+		"bore",
+		"borne"
+	],
+	[
+		"beat",
+		"beat",
+		"beaten"
+	],
+	[
+		"become",
+		"became",
+		"become"
+	],
+	[
+		"begin",
+		"began",
+		"begun"
+	],
+	[
+		"bend",
+		"bent",
+		"bent"
+	],
+	[
+		"bet",
+		"bet",
+		"bet"
+	],
+	[
+		"bind",
+		"bound",
+		"bound"
+	],
+	[
+		"bite",
+		"bit",
+		"bitten"
+	],
+	[
+		"bleed",
+		"bled",
+		"bled"
+	],
+	[
+		"blow",
+		"blew",
+		"blown"
+	],
+	[
+		"break",
+		"broke",
+		"broken"
+	],
+	[
+		"breed",
+		"bred",
+		"bred"
+	],
+	[
+		"bring",
+		"brought",
+		"brought"
+	],
+	[
+		"broadcast",
+		"broadcast",
+		"broadcast"
+	],
+	[
+		"build",
+		"built",
+		"built"
+	],
+	[
+		"burn",
+		"burnt",
+		"burnt"
+	],
+	[
+		"burst",
+		"burst",
+		"burst"
+	],
+	[
+		"buy",
+		"bought",
+		"bought"
+	],
+	[
+		"catch",
+		"caught",
+		"caught"
+	],
+	[
+		"choose",
+		"chose",
+		"chosen"
+	],
+	[
+		"cling",
+		"clung",
+		"clung"
+	],
+	[
+		"come",
+		"came",
+		"come"
+	],
+	[
+		"cost",
+		"cost",
+		"cost"
+	],
+	[
+		"creep",
+		"crept",
+		"crept"
+	],
+	[
+		"cut",
+		"cut",
+		"cut"
+	],
+	[
+		"deal",
+		"dealt",
+		"dealt"
+	],
+	[
+		"dig",
+		"dug",
+		"dug"
+	],
+	[
+		"do",
+		"did",
+		"done"
+	],
+	[
+		"draw",
+		"drew",
+		"drawn"
+	],
+	[
+		"dream",
+		"dreamt",
+		"dreamt"
+	],
+	[
+		"drink",
+		"drank",
+		"drunk"
+	],
+	[
+		"drive",
+		"drove",
+		"driven"
+	],
+	[
+		"eat",
+		"ate",
+		"eaten"
+	],
+	[
+		"fall",
+		"fell",
+		"fallen"
+	],
+	[
+		"feed",
+		"fed",
+		"fed"
+	],
+	[
+		"feel",
+		"felt",
+		"felt"
+	],
+	[
+		"fight",
+		"fought",
+		"fought"
+	],
+	[
+		"find",
+		"found",
+		"found"
+	],
+	[
+		"fly",
+		"flew",
+		"flown"
+	],
+	[
+		"forbid",
+		"forbade",
+		"forbidden"
+	],
+	[
+		"forget",
+		"forgot",
+		"forgotten"
+	],
+	[
+		"forgive",
+		"forgave",
+		"forgiven"
+	],
+	[
+		"freeze",
+		"froze",
+		"frozen"
+	],
+	[
+		"get",
+		"got",
+		"got"
+	],
+	[
+		"give",
+		"gave",
+		"given"
+	],
+	[
+		"go",
+		"went",
+		"gone"
+	],
+	[
+		"grind",
+		"ground",
+		"ground"
+	],
+	[
+		"grow",
+		"grew",
+		"grown"
+	],
+	[
+		"hang",
+		"hung",
+		"hung"
+	],
+	[
+		"have",
+		"had",
+		"had"
+	],
+	[
+		"hear",
+		"heard",
+		"heard"
+	],
+	[
+		"hide",
+		"hid",
+		"hidden"
+	],
+	[
+		"hit",
+		"hit",
+		"hit"
+	],
+	[
+		"hold",
+		"held",
+		"held"
+	],
+	[
+		"hurt",
+		"hurt",
+		"hurt"
+	],
+	[
+		"keep",
+		"kept",
+		"kept"
+	],
+	[
+		"kneel",
+		"knelt",
+		"knelt"
+	],
+	[
+		"know",
+		"knew",
+		"known"
+	],
+	[
+		"lay",
+		"laid",
+		"laid"
+	],
+	[
+		"lead",
+		"led",
+		"led"
+	],
+	[
+		"lean",
+		"leant",
+		"leant"
+	],
+	[
+		"learn",
+		"learnt",
+		"learnt"
+	],
+	[
+		"leave",
+		"left",
+		"left"
+	],
+	[
+		"lend",
+		"lent",
+		"lent"
+	],
+	[
+		"lie",
+		"lay",
+		"lain"
+	],
+	[
+		"light",
+		"lit",
+		"lit"
+	],
+	[
+		"lose",
+		"lost",
+		"lost"
+	],
+	[
+		"make",
+		"made",
+		"made"
+	],
+	[
+		"mean",
+		"meant",
+		"meant"
+	],
+	[
+		"meet",
+		"met",
+		"met"
+	],
+	[
+		"mow",
+		"mowed",
+		"mown"
+	],
+	[
+		"overtake",
+		"overtook",
+		"overtaken"
+	],
+	[
+		"pay",
+		"paid",
+		"paid"
+	],
+	[
+		"put",
+		"put",
+		"put"
+	],
+	[
+		"read",
+		"read",
+		"read"
+	],
+	[
+		"ride",
+		"rode",
+		"ridden"
+	],
+	[
+		"ring",
+		"rang",
+		"rung"
+	],
+	[
+		"rise",
+		"rose",
+		"risen"
+	],
+	[
+		"run",
+		"ran",
+		"run"
+	],
+	[
+		"saw",
+		"sawed",
+		"sawn"
+	],
+	[
+		"say",
+		"said",
+		"said"
+	],
+	[
+		"see",
+		"saw",
+		"seen"
+	],
+	[
+		"sell",
+		"sold",
+		"sold"
+	],
+	[
+		"send",
+		"sent",
+		"sent"
+	],
+	[
+		"set",
+		"set",
+		"set"
+	],
+	[
+		"sew",
+		"sewed",
+		"sewn"
+	],
+	[
+		"shake",
+		"shook",
+		"shaken"
+	],
+	[
+		"shed",
+		"shed",
+		"shed"
+	],
+	[
+		"shine",
+		"shone",
+		"shone"
+	],
+	[
+		"shoot",
+		"shot",
+		"shot"
+	],
+	[
+		"show",
+		"showed",
+		"shown"
+	],
+	[
+		"shrink",
+		"shrank",
+		"shrunk"
+	],
+	[
+		"shut",
+		"shut",
+		"shut"
+	],
+	[
+		"sing",
+		"sang",
+		"sung"
+	],
+	[
+		"sink",
+		"sank",
+		"sunk"
+	],
+	[
+		"sit",
+		"sat",
+		"sat"
+	],
+	[
+		"sleep",
+		"slept",
+		"slept"
+	],
+	[
+		"slide",
+		"slid",
+		"slid"
+	],
+	[
+		"smell",
+		"smelt",
+		"smelt"
+	],
+	[
+		"sow",
+		"sowed",
+		"sown"
+	],
+	[
+		"speak",
+		"spoke",
+		"spoken"
+	],
+	[
+		"spend",
+		"spent",
+		"spent"
+	],
+	[
+		"spin",
+		"spun",
+		"spun"
+	],
+	[
+		"spit",
+		"spat",
+		"spat"
+	],
+	[
+		"spread",
+		"spread",
+		"spread"
+	],
+	[
+		"stand",
+		"stood",
+		"stood"
+	],
+	[
+		"steal",
+		"stole",
+		"stolen"
+	],
+	[
+		"stick",
+		"stuck",
+		"stuck"
+	],
+	[
+		"sting",
+		"stung",
+		"stung"
+	],
+	[
+		"stink",
+		"stank",
+		"stunk"
+	],
+	[
+		"strike",
+		"struck",
+		"struck"
+	],
+	[
+		"swear",
+		"swore",
+		"sworn"
+	],
+	[
+		"sweep",
+		"swept",
+		"swept"
+	],
+	[
+		"swell",
+		"swelled",
+		"swollen"
+	],
+	[
+		"swim",
+		"swam",
+		"swum"
+	],
+	[
+		"swing",
+		"swung",
+		"swung"
+	],
+	[
+		"take",
+		"took",
+		"taken"
+	],
+	[
+		"teach",
+		"taught",
+		"taught"
+	],
+	[
+		"tear",
+		"tore",
+		"torn"
+	],
+	[
+		"tell",
+		"told",
+		"told"
+	],
+	[
+		"think",
+		"thought",
+		"thought"
+	],
+	[
+		"throw",
+		"threw",
+		"thrown"
+	],
+	[
+		"understand",
+		"understood",
+		"understood"
+	],
+	[
+		"wake",
+		"woke",
+		"woken"
+	],
+	[
+		"wear",
+		"wore",
+		"worn"
+	],
+	[
+		"weep",
+		"wept",
+		"wept"
+	],
+	[
+		"win",
+		"won",
+		"won"
+	],
+	[
+		"wind",
+		"wound",
+		"wound"
+	],
+	[
+		"write",
+		"wrote",
+		"written"
+	]
+]);
+/** Past tense conjugation rules with regex and replacements */
+const pastRules = /* @__PURE__ */ Object.freeze([
+	[/([aeiou])y$/i, "$1yed"],
+	[/e$/i, "ed"],
+	[/([aeiou])lf$/i, "$1lved"],
+	[/([^aeiou])y$/i, "$1ied"],
+	[/([^aeiou])ic$/i, "$1icked"],
+	[/([^aeiou])([aeiou])([^aeiou])$/i, "$1$2$3$3ed"],
+	[/$/i, "ed"]
+]);
+/** Past participle conjugation rules with regex and replacements */
+const pastParticipleRules = /* @__PURE__ */ Object.freeze([
+	[/([aeiou])y$/i, "$1yed"],
+	[/e$/i, "ed"],
+	[/([aeiou])lf$/i, "$1lved"],
+	[/([^aeiou])y$/i, "$1ied"],
+	[/([^aeiou])ic$/i, "$1icked"],
+	[/([^aeiou])([aeiou])([^aeiou])$/i, "$1$2$3$3ed"],
+	[/$/i, "ed"]
+]);
+/** Base form recovery rules (reverse of pastRules) */
+const baseRules = Object.freeze([
+	[/([aeiou])yed$/i, "$1y"],
+	[/^([^aeiouwy])ied$/i, "$1ie"],
+	[/ied$/i, "y"],
+	[/([aeiou])lved$/i, "$1lf"],
+	[/([^aeiou])icked$/i, "$1ic"],
+	[/([bcdfghjklmnpqrstvwxyz])\1ed$/i, "$1"],
+	[/([aeiou])ked$/i, "$1ke"],
+	[/ined$/i, "ine"],
+	[/eted$/i, "ete"],
+	[/gued$/i, "gue"],
+	[/ed$/i, ""]
+]);
+
+//#endregion
+//#region src/verbalizer/Verbalizer.ts
+/**
+* @class Handles English verb conjugation between base, past tense, and past participle forms.
+*
+*      - Provides methods to convert verbs between base, past, and past participle forms, check verb forms, and manage custom conjugation rules.
+*      - Supports adding custom conjugation rules and irregular verbs.
+*      - Automatically handles common irregular verbs like "go" to "went" (past) and "gone" (past participle).
+*      - Automatically loads common irregular verbs and conjugation rules.
+*      - Preserves case sensitivity of input verbs.
+*      - This class is useful for natural language processing tasks, such as chatbots, text analysis, or content generation systems requiring accurate verb conjugation.
+*
+* @remarks
+* For ready to use instance, please refer to {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/verbalizer verbalizer} instead.
+*
+* @example
+* const myVerbalizer = new Verbalizer();
+* myVerbalizer.toPast('run'); // "ran"
+* myVerbalizer.toParticiple('go'); // "gone"
+* myVerbalizer.toBase('went'); // "go"
+*/
+var Verbalizer = class {
+	#baseRules = [];
+	#pastRules = [];
+	#participleRules = [];
+	#irregularVerbs = {};
+	#reverseIrregular = {};
+	/**
+	* Initializes `Verbalizer` with default rules and irregular verbs.
+	* Automatically loads irregular verbs and conjugation rules for base, past and past participle forms.
+	*/
+	constructor() {
+		this.#loadRules();
+	}
+	#loadRules() {
+		irregularVerbs.forEach(([base, past, pastParticiple]) => {
+			this.addIrregular(base, past, pastParticiple);
+		});
+		baseRules.forEach(([rule, replacement]) => {
+			this.addBaseRule(rule, replacement);
+		});
+		pastRules.forEach(([rule, replacement]) => {
+			this.addPastRule(rule, replacement);
+		});
+		pastParticipleRules.forEach(([rule, replacement]) => {
+			this.addParticipleRule(rule, replacement);
+		});
+	}
+	/** 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 base rule to already trimmed and lowercased verb */
+	#applyBaseRule(verb) {
+		return this.#applyRules(verb, this.#baseRules);
+	}
+	/** Apply corresponding rules */
+	#applyRules(verb, rules) {
+		if (!isNonEmptyString(verb)) return "";
+		for (let i = 0; i < rules.length; i++) {
+			const [rule, replacement] = rules[i];
+			if (rule.test(verb)) return verb.replace(rule, replacement);
+		}
+		return verb;
+	}
+	/** Find irregular verb entry */
+	#findIrregularEntry(verb) {
+		const base = this.#irregularVerbs[verb] ? verb : this.#reverseIrregular[verb];
+		return base ? this.#irregularVerbs[base] : void 0;
+	}
+	/**
+	* * Add a new base tense conjugation rule.
+	* @param rule Pattern to match past/participle form of verbs.
+	* @param replacement Replacement pattern for base tense form.
+	* @example
+	* verbalizer.addBaseRule(/ied$/i, 'y');
+	*/
+	addBaseRule(rule, replacement) {
+		this.#baseRules.push([rule, replacement]);
+	}
+	/**
+	* * Add a new past tense conjugation rule.
+	* @param rule Pattern to match base verbs.
+	* @param replacement Replacement pattern for past tense form.
+	* @example
+	* verbalizer.addPastRule(/e$/i, 'ed');
+	*/
+	addPastRule(rule, replacement) {
+		this.#pastRules.push([rule, replacement]);
+	}
+	/**
+	* * Add a new past participle conjugation rule.
+	* @param rule Pattern to match base verbs.
+	* @param replacement Replacement pattern for past participle form.
+	* @example
+	* verbalizer.addParticipleRule(/e$/i, 'ed');
+	*/
+	addParticipleRule(rule, replacement) {
+		this.#participleRules.push([rule, replacement]);
+	}
+	/**
+	* * Add a custom irregular verb.
+	* @param base Base form of the verb.
+	* @param past Past tense form.
+	* @param participle Past participle form.
+	* @example
+	* verbalizer.addIrregular('swim', 'swam', 'swum');
+	*/
+	addIrregular(base, past, participle) {
+		const baseLower = base?.toLowerCase();
+		const pastLower = past?.toLowerCase();
+		const participleLower = participle?.toLowerCase();
+		this.#irregularVerbs[baseLower] = {
+			base: baseLower,
+			past: pastLower,
+			participle: participleLower
+		};
+		this.#reverseIrregular[pastLower] = baseLower;
+		this.#reverseIrregular[participleLower] = baseLower;
+	}
+	/**
+	* * Convert a verb to its past tense form.
+	* @param verb Base form of the verb.
+	* @returns Past tense form of the verb.
+	* @example
+	* verbalizer.toPast('walk'); // "walked"
+	* verbalizer.toPast('run'); // "ran"
+	*/
+	toPast(verb) {
+		if (!isNonEmptyString(verb)) return "";
+		const lower = verb?.trim()?.toLowerCase();
+		const irregularEntry = this.#findIrregularEntry(lower);
+		if (irregularEntry) return this.#restoreCase(verb, irregularEntry.past);
+		return this.#restoreCase(verb, this.#applyRules(this.#applyBaseRule(lower), this.#pastRules));
+	}
+	/**
+	* * Convert a verb to its past participle form.
+	* @param verb Base form of the verb.
+	* @returns Past participle form of the verb.
+	* @example
+	* verbalizer.toParticiple('walk'); // "walked"
+	* verbalizer.toParticiple('go'); // "gone"
+	*/
+	toParticiple(verb) {
+		if (!isNonEmptyString(verb)) return "";
+		const lower = verb?.trim()?.toLowerCase();
+		const irregularEntry = this.#findIrregularEntry(lower);
+		if (irregularEntry) return this.#restoreCase(verb, irregularEntry.participle);
+		return this.#restoreCase(verb, this.#applyRules(this.#applyBaseRule(lower), this.#participleRules));
+	}
+	/**
+	* * Convert a verb to its base form.
+	* @param verb Past or past participle form of the verb.
+	* @returns Base form of the verb.
+	* @example
+	* verbalizer.toBase('went'); // "go"
+	* verbalizer.toBase('walked'); // "walk"
+	*/
+	toBase(verb) {
+		if (!isNonEmptyString(verb)) return "";
+		const lower = verb?.trim()?.toLowerCase();
+		const irregularEntry = this.#findIrregularEntry(lower);
+		if (irregularEntry) return this.#restoreCase(verb, irregularEntry.base);
+		return this.#restoreCase(verb, this.#applyBaseRule(lower));
+	}
+	/**
+	* * Check if a given verb is in its past tense form.
+	* @param verb Verb to check.
+	* @returns True if the verb is in past tense, otherwise false.
+	* @example
+	* verbalizer.isPast('ran'); // true
+	* verbalizer.isPast('run'); // false
+	*/
+	isPast(verb) {
+		if (!isNonEmptyString(verb)) return false;
+		const lower = verb?.trim()?.toLowerCase();
+		return this.toPast(lower) === lower;
+	}
+	/**
+	* * Check if a given verb is in its past participle form.
+	* @param verb Verb to check.
+	* @returns True if the verb is in past participle form, otherwise false.
+	* @example
+	* verbalizer.isParticiple('gone'); // true
+	* verbalizer.isParticiple('go'); // false
+	*/
+	isParticiple(verb) {
+		if (!isNonEmptyString(verb)) return false;
+		const lower = verb?.trim()?.toLowerCase();
+		return this.toParticiple(lower) === lower;
+	}
+	/**
+	* * Check if a given verb is in its base form.
+	* @param verb Verb to check.
+	* @returns True if the verb is in base form, otherwise false.
+	* @example
+	* verbalizer.isBase('run'); // true
+	* verbalizer.isBase('ran'); // false
+	*/
+	isBase(verb) {
+		if (!isNonEmptyString(verb)) return false;
+		const lower = verb?.trim()?.toLowerCase();
+		return this.toBase(lower) === lower;
+	}
+};
+/**
+* Default shared instance of {@link https://toolbox.nazmul-nhb.dev/docs/classes/Verbalizer Verbalizer}.
+*
+* - Use this when you don’t need multiple configurations.
+* - It comes preloaded with standard conjugation rules and irregular verbs.
+* -
+*
+* @example
+* import { verbalizer } from 'nhb-toolbox';
+*
+* verbalizer.toPast('run'); // "ran"
+* verbalizer.toParticiple('go'); // "gone"
+* verbalizer.toBase('went'); // "go"
+*/
+const verbalizer = new Verbalizer();
+
+//#endregion
+export { Verbalizer, verbalizer };