admin/packages/services/intl-name

← @crux-kit/intl-name

A lightweight TypeScript service for formatting personal names into display-ready strings with locale support.

The service accepts multiple input formats (objects or strings), normalizes them into a canonical structure, and formats the output according to language-specific patterns.

---

Quick Start

import { intlNameService, INTL_NAME_TOKENS } from 'intl-name';

const IntlName = intlNameService(
  {
    language: 'uk',
    fallbackLanguage: 'uk',
    localeMap: {
      uk: {
        formats: {
          SURNAME_NAME: `${INTL_NAME_TOKENS.LAST.FULL} ${INTL_NAME_TOKENS.FIRST.FULL}`,
          INITIALS_LF: `${INTL_NAME_TOKENS.LAST.INITIAL}${INTL_NAME_TOKENS.FIRST.INITIAL}`,
        },
      },
      en: {
        formats: {
          SURNAME_NAME: `${INTL_NAME_TOKENS.LAST.FULL} ${INTL_NAME_TOKENS.FIRST.FULL}`,
          INITIALS_LF: `${INTL_NAME_TOKENS.LAST.INITIAL}${INTL_NAME_TOKENS.FIRST.INITIAL}`,
        },
      },
    },
  },
  console,
);

IntlName.formatToDisplay({ firstName: 'John', lastName: 'Smith' }, 'SURNAME_NAME');
// → "Smith John"

---

Supported Input Formats

The service accepts names in three formats:

camelCase object

{ firstName, lastName, patronymic?, middleName?, prefix?, suffix? }

snake_case object

{ first_name, last_name, patronymic?, middle_name?, prefix?, suffix? }

string

'First Last Patronymic';

All input formats are automatically normalized into a canonical internal representation.

---

Formatting Patterns & Tokens

Name formatting is driven by patterns defined in the localeMap.

Patterns are plain strings composed of tokens that represent different parts of a person’s name. At runtime, these tokens are replaced with actual values from the input.

If a token has no value, it is replaced with an empty string.

---

Conditional Blocks { ... }

Conditional blocks are optional helpers mainly intended to control punctuation, separators, and surrounding spaces.

Tokens work without conditional blocks.
Missing values are simply replaced with an empty string.

Why conditional blocks matter

Without conditional blocks, punctuation remains even when a value is missing:

// Pattern without a conditional block
`${INTL_NAME_TOKENS.LAST.FULL}, ${INTL_NAME_TOKENS.FIRST.FULL}`;

// Input: { lastName: "Smith" }
// Output: "Smith, "

Using a conditional block removes the separator entirely:

`${INTL_NAME_TOKENS.LAST.FULL}{, ${INTL_NAME_TOKENS.FIRST.FULL}}`;

// Input: { lastName: "Smith" }
// Output: "Smith"

The whole block (including commas, dots, or spaces) is rendered only if at least one token inside has a value.

Typical use cases

• Commas and dots (", ", ".")
• Extra spaces around optional parts
• Optional patronymic or middle name

Example:

`${INTL_NAME_TOKENS.LAST.FULL} ${INTL_NAME_TOKENS.FIRST.FULL}{ ${INTL_NAME_TOKENS.PATRONYMIC.FULL}}`;

• With patronymic → "Smith John Ivanovich"
• Without patronymic → "Smith John"

Conditional blocks help keep formatting clean without manual string checks.

---

API

intlNameService(config, logger?)

Creates a service instance.

Returns:

• formatToDisplay(input, formatKey) — formats the name for display
• toObject(input) — converts input into a canonical object
• setLanguage(lang) — changes the active language
• setSupportedLanguages(map) — replaces the supported locale map