@boringnode/pluralize is a TypeScript port of the pluralization features from Doctrine Inflector.

Built-in support for:

• English (en, english)
• French (fr, french)

[!NOTE] Changes to inflection rules (adding, removing, or modifying rules) will not be considered as breaking changes.

Installation

npm install @boringnode/pluralize

Usage

Simple Functions

The easiest way to use the library is with the simple functions.

import { pluralize, singularize } from '@boringnode/pluralize'

pluralize('word') // 'words'
pluralize('person') // 'people'
pluralize('child') // 'children'

singularize('words') // 'word'
singularize('people') // 'person'
singularize('children') // 'child'

Using a Different Locale

You can create an Inflector instance with a different locale.

import { Inflector } from '@boringnode/pluralize'

const inflector = new Inflector('fr')

inflector.pluralize('cheval')   // 'chevaux'
inflector.pluralize('bijou')    // 'bijoux'
inflector.singularize('chevaux') // 'cheval'

Custom Rules with Inflector Class

You can create an Inflector instance to add custom rules.

import { Inflector } from '@boringnode/pluralize'

const inflector = new Inflector()
  .addIrregular('gex', 'gexes')
  .addUninflected('pokemon')
  .addPluralRule(/(.*)gon$/i, '$1gons')
  .addSingularRule(/(.*)gons$/i, '$1gon')

inflector.pluralize('gex') // 'gexes'
inflector.pluralize('pokemon') // 'pokemon'
inflector.singularize('dragons') // 'dragon'

Creating a Custom Language Ruleset

You can create and register custom language rulesets for other languages.

import { Inflector, type LanguageRuleset } from '@boringnode/pluralize'
import {
  pattern,
  Patterns,
  Substitutions,
  Transformations,
} from '@boringnode/pluralize/builder'

const SpanishRuleset: LanguageRuleset = {
  getSingularRuleset: () => ({
    regular: new Transformations([
      { pattern: pattern('es$'), replacement: '' },
      { pattern: pattern('s$'), replacement: '' },
    ]),
    uninflected: new Patterns([pattern('lunes'), pattern('martes')]),
    irregular: new Substitutions([{ from: 'hombres', to: 'hombre' }]),
  }),
  getPluralRuleset: () => ({
    regular: new Transformations([
      { pattern: pattern('[aeiou]$'), replacement: '$&s' },
      { pattern: pattern('$'), replacement: 'es' },
    ]),
    uninflected: new Patterns([pattern('lunes'), pattern('martes')]),
    irregular: new Substitutions([{ from: 'hombre', to: 'hombres' }]),
  }),
}

// Register the ruleset
Inflector.register('es', SpanishRuleset)

// Use it
const inflector = new Inflector('es')
inflector.pluralize('gato') // 'gatos'

API

Functions

• pluralize(word: string): string - Returns the plural form of a word
• singularize(word: string): string - Returns the singular form of a word

Inflector Class

| Method | Description | | --------------------------------------- | ----------------------------------------------------------- | | new Inflector(locale?: string) | Creates a new inflector instance (defaults to 'en') | | Inflector.register(locale, ruleset) | Registers a custom language ruleset | | pluralize(word) | Returns the plural form of a word | | singularize(word) | Returns the singular form of a word | | addIrregular(singular, plural) | Adds an irregular word mapping | | addUninflected(word) | Adds a word that doesn't change between singular and plural | | addPluralRule(pattern, replacement) | Adds a custom pluralization rule | | addSingularRule(pattern, replacement) | Adds a custom singularization rule |

Builder Exports (@boringnode/pluralize/builder)

For creating custom language rulesets:

| Export | Description | | ----------------- | -------------------------------------------------------- | | pattern | Helper function to create a case-insensitive regex | | Patterns | A collection of patterns for uninflected words | | Transformation | Interface: { pattern: RegExp, replacement: string } | | Transformations | A collection of transformations | | Substitution | Interface: { from: string, to: string } | | Substitutions | A collection of substitutions | | Ruleset | Interface: { regular, uninflected, irregular } |