toolbox-x 1.0.0

package/dist/pluralizer.d.cts

@@ -0,0 +1,152 @@
+/**
+ * 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 { n as PluralizeOptions } from "./pluralizer-Cb6ZmrDl.cjs";
+
+//#region src/pluralizer/Pluralizer.d.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)
+ */
+declare class Pluralizer {
+  #private;
+  /**
+   * Initializes the Pluralizer with default rules and exceptions.
+   * Automatically loads irregular, pluralization and singular rules along with pre-defined uncountable nouns.
+   */
+  constructor();
+  /**
+   * * 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: RegExp, replacement: string): void;
+  /**
+   * * 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: RegExp, replacement: string): void;
+  /**
+   * * 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: string | RegExp): void;
+  /**
+   * * Add a custom irregular form.
+   * @param single Singular word.
+   * @param plural Plural word.
+   * @example
+   * pluralizer.addIrregular('person', 'people');
+   */
+  addIrregular(single: string, plural: string): void;
+  /**
+   * * 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: string, options?: PluralizeOptions): string;
+  /**
+   * * 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: string): string;
+  /**
+   * * 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: string): string;
+  /**
+   * * 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: string): boolean;
+  /**
+   * * 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: string): boolean;
+}
+/**
+ * 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)
+ */
+declare const pluralizer: Pluralizer;
+//#endregion
+export { Pluralizer, pluralizer };

package/dist/pluralizer.d.mts

@@ -0,0 +1,152 @@
+/**
+ * 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 { n as PluralizeOptions } from "./pluralizer-BjMIc6uT.mjs";
+
+//#region src/pluralizer/Pluralizer.d.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)
+ */
+declare class Pluralizer {
+  #private;
+  /**
+   * Initializes the Pluralizer with default rules and exceptions.
+   * Automatically loads irregular, pluralization and singular rules along with pre-defined uncountable nouns.
+   */
+  constructor();
+  /**
+   * * 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: RegExp, replacement: string): void;
+  /**
+   * * 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: RegExp, replacement: string): void;
+  /**
+   * * 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: string | RegExp): void;
+  /**
+   * * Add a custom irregular form.
+   * @param single Singular word.
+   * @param plural Plural word.
+   * @example
+   * pluralizer.addIrregular('person', 'people');
+   */
+  addIrregular(single: string, plural: string): void;
+  /**
+   * * 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: string, options?: PluralizeOptions): string;
+  /**
+   * * 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: string): string;
+  /**
+   * * 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: string): string;
+  /**
+   * * 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: string): boolean;
+  /**
+   * * 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: string): boolean;
+}
+/**
+ * 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)
+ */
+declare const pluralizer: Pluralizer;
+//#endregion
+export { Pluralizer, pluralizer };