142 lines
3.4 KiB
Markdown
142 lines
3.4 KiB
Markdown
# [←](../../../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
|