# [←](../../../docs/README.md) @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

```ts
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

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

### snake_case object

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

### string

```ts
'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:

```ts
// 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:

```ts
`${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:

```ts
`${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