PosInformatique.Foundations.People

Introduction

This package provides lightweight, strongly-typed value objects to standardize first names and last names across your applications:

• FirstName: normalized, properly cased first names.
• LastName: normalized, fully uppercased last names.

It also includes:

• IPerson: a small interface to represent nominative people with FirstName and LastName.
• Extension methods on IPerson for consistent display/order names and initials.
• NameNormalizer: helper methods when you only have the separated first/last names.

Typical use cases: domain entities (User, Customer, Employee, Contact), consistent UI display (Blazor components, lists), alphabetical ordering (directories), and avatar initials.

Install

You can install the package from NuGet:

dotnet add package PosInformatique.Foundations.People

Features

• Strongly-typed FirstName and LastName with validation and normalization
• Business rules:
  • FirstName: title-cased words; letters only; separators: space, hyphen
  • LastName: fully uppercased; letters only; separators: space, hyphen
  • No consecutive/trailing separators; max length 50
• Acts like read-only char arrays: indexer and Length
• Implements IParsable<T>, IFormattable, IComparable<T>, IEquatable<T>
• Implicit conversions to/from string
• IPerson interface for nominative person abstraction
• PersonExtensions for display name, ordering name, and initials
• NameNormalizer utilities for first/last names without IPerson

Business rules

FirstName

• Max length: 50.
• Allowed characters: letters only; separators: ' ' and '-'.
• Normalization:
  • Each word starts uppercase and continues lowercase (e.g., "John", "John Henri-Smith").
  • No consecutive separators, ths trailing separators are removed.

LastName

• Max length: 50.
• Allowed characters: letters only; separators: ' ' and '-'.
• Normalization:
  • Entire value uppercased (e.g., "DOE", "SMITH-JOHNSON").
  • No consecutive separators, the trailing separators are removed.

FirstName examples

Create / implicit conversion

// Implicit conversion validates and normalizes: FirstName firstName = "john henri-smith"; // -> "John Henri-Smith" // Explicit create: var firstName2 = FirstName.Create(" alice--marie "); // -> "Alice-Marie" // IsValid var ok = FirstName.IsValid("Élodie"); // true var notOk = FirstName.IsValid("John_123"); // false

Parse / TryParse

// Parse (throws on invalid) var firstName = FirstName.Parse("béAtrice", provider: null); // "Béatrice" // TryParse (no exceptions) if (FirstName.TryParse("jeAn - pierre", provider: null, out var firstName)) { Console.WriteLine(firstName); // "Jean-Pierre" }

Length and indexer

var firstName = FirstName.Create("Jean-Pierre"); var len = firstName.Length; // 11 var firstLetter = firstName[0]; // 'J' var dash = firstName[4]; // '-' // Enumerate characters foreach (var c in firstName) { /* ... */ }

Comparisons and equality

var a = FirstName.Create("Alice"); var b = FirstName.Create("ALICE"); // normalized: "Alice" Console.WriteLine(a == b); // true Console.WriteLine(a != b); // false Console.WriteLine(a <= b); // true Console.WriteLine(a.CompareTo(b)); // 0 var list = new List<FirstName> { FirstName.Create("Zoé"), FirstName.Create("Ana") }; list.Sort(); // alphabetical by normalized value

LastName examples

Create / implicit conversion

LastName lastName = "dupond durand"; // -> "DUPOND DURAND" var lastName2 = LastName.Create("le--gall"); // -> "LE GALL" var ok = LastName.IsValid("O'Connor"); // false (apostrophe not allowed)

Parse / TryParse

var parsed = LastName.Parse("martin", provider: null); // "MARTIN" if (LastName.TryParse("van - damme", provider: null, out var lastName)) { Console.WriteLine(lastName); // "VAN DAMME" }

Length and indexer

var lastName = LastName.Create("LE GALL"); var len = lastName.Length; // 7 var firstLetter = lastName[0]; // 'L' var space = lastName[2]; // ' ' // Enumerate characters foreach (var c in lastName) { /* ... */ }

Comparisons and equality

var a = LastName.Create("DURAND"); var b = LastName.Create("durand"); // normalized to "DURAND" Console.WriteLine(a == b); // true Console.WriteLine(a < LastName.Create("MARTIN")); // true var list = new List<LastName> { LastName.Create("ZOLA"), LastName.Create("ABEL") }; list.Sort(); // alphabetical by normalized value

IPerson

IPerson represents a nominative person with a normalized FirstName and LastName. Implement this in domain types like User, Customer, Employee, Contact.

public sealed class User : IPerson { public User(FirstName firstName, LastName lastName) { FirstName = firstName; LastName = lastName; } public FirstName FirstName { get; } public LastName LastName { get; } }

You can also accept string and normalize:

public sealed class Customer : IPerson { public Customer(string firstName, string lastName) { // Implicit conversions validate and normalize FirstName = firstName; LastName = lastName; } public FirstName FirstName { get; } public LastName LastName { get; } }

PersonExtensions

Utilities for consistent display, ordering, and initials on any IPerson.

• GetFullNameForDisplay(): "First-Name LASTNAME" (e.g., "John DOE"). Use in UI display (e.g., Blazor component).
• GetFullNameForOrder(): "LASTNAME First-Name" (e.g., "DOE John"). Use for alphabetical directories by last name.
• GetInitials(): first letter of FirstName + first letter of LastName (e.g., "JD"). Use as fallback when avatar image is not available.

Examples:

var user = new User("jean-paul", "dupont"); var display = user.GetFullNameForDisplay(); // "Jean-Paul DUPONT" var order = user.GetFullNameForOrder(); // "DUPONT Jean-Paul" var initials = user.GetInitials(); // "JD"

Blazor example:

@code { [Parameter] public IPerson Person { get; set; } = default!; } <h3>@Person.GetFullNameForDisplay()</h3> <span class="avatar">@Person.GetInitials()</span>

Sorting by order name:

var people = new List<IPerson> { new User("alice", "martin"), new User("bob", "durand"), new User("Élodie", "zola") }; var ordered = people .OrderBy(p => p.GetFullNameForOrder(), StringComparer.Ordinal) .ToList(); // "DURAND Bob", "MARTIN Alice", "ZOLA Élodie"

NameNormalizer

When you only have separate FirstName and LastName (not an IPerson), use NameNormalizer.

• GetFullNameForDisplay(firstName, lastName) => "First-Name LASTNAME"
• GetFullNameForOrder(firstName, lastName) => "LASTNAME First-Name"

Examples:

var firstName = FirstName.Create("marie-claire"); var lastName = LastName.Create("le gall"); var display = NameNormalizer.GetFullNameForDisplay(firstName, lastName); // "Marie-Claire LE GALL" var order = NameNormalizer.GetFullNameForOrder(firstName, lastName); // "LE GALL Marie-Claire"

Error handling tips

• Use TryParse / TryCreate when you want to avoid exceptions:

if (FirstName.TryParse(inputFirstName, null, out var firstName) && LastName.TryParse(inputLastName, null, out var lastName)) { var user = new User(firstName, lastName); } else { // handle invalid inputs }

Links

• NuGet package: People (core library)
• Source code