ISA-Frontend/libs/utils/format-name/README.md

@isa/utils/format-name

A utility library for consistently formatting person and organisation names across the ISA-Frontend application.

Overview

This library provides a single utility function formatName that standardizes the display of names by combining first name, last name, and organisation name components according to a consistent business rule. The function handles optional parameters gracefully and filters out empty or undefined values to produce clean, readable name strings.

The formatting follows the convention:

• Personal names are displayed as "LastName FirstName"
• Organisation names are separated from personal names with " - "
• Any combination of components can be provided
• Empty or undefined values are automatically excluded from the output

Installation

import { formatName } from '@isa/utils/format-name';

API Reference

Functions

formatName(params): string

Formats a name by combining first name, last name, and organisation name according to business rules.

Parameters:

Parameter	Type	Required	Description
params	object	Yes	An object containing the name components
params.firstName	string	No	The person's first name
params.lastName	string	No	The person's last name
params.organisationName	string	No	The organisation name

Returns: string - The formatted name string

Formatting Rules:

• Names are formatted as "LastName FirstName"
• Organisation name is separated from the personal name with " - "
• Empty or undefined values are filtered out
• If all values are empty/undefined, returns an empty string

Usage Examples

Format a person with first and last name

const result = formatName({
  firstName: 'John',
  lastName: 'Doe'
});
// Returns: "Doe John"

Format a person with organisation

const result = formatName({
  firstName: 'John',
  lastName: 'Doe',
  organisationName: 'Acme Corp'
});
// Returns: "Acme Corp - Doe John"

Format organisation only

const result = formatName({
  organisationName: 'Acme Corp'
});
// Returns: "Acme Corp"

Format with partial personal name

// Only last name
const result1 = formatName({
  lastName: 'Doe'
});
// Returns: "Doe"

// Only first name
const result2 = formatName({
  firstName: 'John'
});
// Returns: "John"

// Organisation with partial personal name
const result3 = formatName({
  firstName: 'John',
  organisationName: 'Acme Corp'
});
// Returns: "Acme Corp - John"

Handle empty values

// Empty strings are filtered out
const result1 = formatName({
  firstName: '',
  lastName: '',
  organisationName: ''
});
// Returns: ""

// Undefined values are filtered out
const result2 = formatName({});
// Returns: ""

Use Cases

This utility is commonly used in:

• Customer management interfaces (CRM)
• Order processing displays
• User profile presentations
• Report generation
• Any UI component that needs to display person or organisation names consistently

Testing

The library includes comprehensive test coverage for all formatting scenarios. Run tests with:

nx test utils-format-name