@tstdl/base 0.93.138 → 0.93.140

package/errors/README.md

@@ -0,0 +1,267 @@
+# Errors
+
+A comprehensive collection of custom, robust, and extensible error classes for TypeScript applications. It provides a standardized hierarchy for common failure scenarios, performance optimizations, and built-in localization support.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [The CustomError Base](#the-customerror-base)
+  - [Standardized Error Types](#standardized-error-types)
+  - [Localization](#localization)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Creating Custom Errors](#creating-custom-errors)
+  - [Attaching Details to Errors](#attaching-details-to-errors)
+  - [Aggregating Multiple Errors](#aggregating-multiple-errors)
+  - [Formatting and Serialization](#formatting-and-serialization)
+  - [Performance Optimization (Fast Mode)](#performance-optimization-fast-mode)
+  - [Unwrapping Errors](#unwrapping-errors)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Extensible Base Class:** `CustomError` simplifies creating domain-specific errors with support for causes and stack trace management.
+- **Standard Library:** Includes a rich set of pre-defined errors for HTTP status codes (400, 401, 403, 404, etc.) and common application failures.
+- **Type Safety:** Designed for use with `instanceof` checks to allow precise error handling logic.
+- **Contextual Data:** `DetailsError` allows attaching arbitrary structured data to an error.
+- **Error Aggregation:** `MultiError` groups multiple errors into a single throwable object.
+- **Performance Mode:** Optional `fast` mode skips stack trace generation for high-throughput scenarios.
+- **Localization:** Built-in English and German localization maps for user-facing error messages.
+
+## Core Concepts
+
+### The CustomError Base
+
+All errors in this module inherit from `CustomError`. This abstract class extends the native JavaScript `Error` and adds:
+
+- **Static `errorName`**: A reliable identifier for the error type, safe against code minification.
+- **Options Object**: A constructor argument to set the message, cause, stack, and performance flags.
+
+### Standardized Error Types
+
+The module provides specific classes for common scenarios, such as:
+
+- **Authentication/Authorization**: `UnauthorizedError`, `ForbiddenError`, `InvalidCredentialsError`, `InvalidTokenError`.
+- **Request Handling**: `BadRequestError`, `NotFoundError`, `MethodNotAllowedError`, `UnsupportedMediaTypeError`, `MaxBytesExceededError`.
+- **System State**: `NotImplementedError`, `NotSupportedError`, `TimeoutError`, `AssertionError`.
+
+### Localization
+
+The module exports `englishTstdlErrorsLocalization` and `germanTstdlErrorsLocalization`. These objects map error classes to user-friendly headers and messages, making it easier to display errors in a UI without hardcoding strings.
+
+## 🚀 Basic Usage
+
+The most common use case is throwing standard errors to interrupt control flow when a specific condition is not met.
+
+```ts
+import { NotFoundError, ForbiddenError } from '@tstdl/base/errors';
+
+interface User {
+  id: string;
+  isAdmin: boolean;
+}
+
+function getUser(id: string, currentUser: User): User {
+  // Simulate a database lookup
+  const user = database.find(id);
+
+  if (!user) {
+    throw new NotFoundError(`User with ID "${id}" was not found.`);
+  }
+
+  if (!currentUser.isAdmin && currentUser.id !== user.id) {
+    throw new ForbiddenError('You do not have permission to view this user.');
+  }
+
+  return user;
+}
+
+// Mock database for the example
+const database = {
+  find: (id: string) => (id === '123' ? { id: '123', isAdmin: false } : null),
+};
+```
+
+Handling errors using `instanceof` ensures you only catch and process specific types.
+
+```ts
+import { NotFoundError, ForbiddenError } from '@tstdl/base/errors';
+
+try {
+  getUser('999', { id: '123', isAdmin: false });
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.error('Resource missing:', error.message);
+  } else if (error instanceof ForbiddenError) {
+    console.error('Access denied:', error.message);
+  } else {
+    console.error('Unexpected error:', error);
+    throw error; // Re-throw unknown errors
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Creating Custom Errors
+
+Extend `CustomError` to define domain-specific errors. Define a static `errorName` to ensure the error can be reliably identified even if class names are mangled during build processes.
+
+```ts
+import { CustomError } from '@tstdl/base/errors';
+
+export class InsufficientFundsError extends CustomError {
+  static readonly errorName = 'InsufficientFundsError';
+
+  constructor(accountId: string, required: number, available: number) {
+    super({
+      message: `Account ${accountId} has insufficient funds. Required: ${required}, Available: ${available}.`,
+    });
+  }
+}
+
+// Usage
+throw new InsufficientFundsError('ACC-123', 100.0, 50.0);
+```
+
+### Attaching Details to Errors
+
+Use `DetailsError` when you need to pass structured data along with the error message. This is useful for validation errors or passing context to an error handler.
+
+```ts
+import { DetailsError } from '@tstdl/base/errors';
+
+type ValidationFailure = {
+  field: string;
+  reason: string;
+};
+
+function validateProfile(profile: any): void {
+  const failures: ValidationFailure[] = [];
+
+  if (!profile.username) {
+    failures.push({ field: 'username', reason: 'Required' });
+  }
+
+  if (failures.length > 0) {
+    throw new DetailsError('Validation failed', failures);
+  }
+}
+
+try {
+  validateProfile({});
+} catch (error) {
+  if (error instanceof DetailsError) {
+    console.log('Validation details:', error.details);
+  }
+}
+```
+
+### Aggregating Multiple Errors
+
+`MultiError` is useful when an operation performs multiple independent tasks (like processing a batch of files) and you want to report all failures at the end.
+
+```ts
+import { MultiError } from '@tstdl/base/errors';
+
+function processItems(items: string[]): void {
+  const errors: Error[] = [];
+
+  for (const item of items) {
+    try {
+      // potentially failing operation
+      if (item === 'fail') throw new Error('Failed item');
+    } catch (error) {
+      if (error instanceof Error) {
+        errors.push(error);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new MultiError(errors, `Processed items with ${errors.length} errors.`);
+  }
+}
+```
+
+### Formatting and Serialization
+
+When logging errors or sending them over the wire (e.g., in a REST API response), you often need a structured or stringified representation. The `serializeError` and `formatError` functions handle this, including support for nested causes and `MultiError` aggregation.
+
+```ts
+import { formatError, serializeError, ForbiddenError } from '@tstdl/base/errors';
+
+const error = new ForbiddenError('Access Denied', { cause: new Error('Permission bit 0 not set') });
+
+// Get a structured JSON-cloneable object
+const serialized = serializeError(error);
+
+// Get a formatted string with indentation and causes
+const formatted = formatError(error, { includeStack: true });
+console.log(formatted);
+/*
+ForbiddenError: Access Denied
+Caused by:
+  Error: Permission bit 0 not set
+    at Object.<anonymous> ...
+*/
+```
+
+### Performance Optimization (Fast Mode)
+
+Generating a stack trace is an expensive operation in JavaScript. If you are using exceptions for control flow in a high-performance loop (e.g., a parser) and do not need the stack trace, you can use the `fast: true` option.
+
+```ts
+import { CustomError } from '@tstdl/base/errors';
+
+class ParserError extends CustomError {
+  static readonly errorName = 'ParserError';
+
+  constructor(message: string) {
+    // fast: true skips super() call to Error, avoiding stack trace generation
+    super({ message, fast: true });
+  }
+}
+```
+
+### Unwrapping Errors
+
+Sometimes errors are wrapped in other objects or generic error containers. `unwrapError` helps extract the original underlying error.
+
+```ts
+import { unwrapError } from '@tstdl/base/errors';
+
+const originalError = new Error('Database connection failed');
+const wrappedError = { reason: originalError };
+
+const error = unwrapError(wrappedError);
+console.log(error.message); // "Database connection failed"
+```
+
+## 📚 API
+
+| Class / Function                 | Description                                                                                                     |
+| :------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
+| `CustomError`                    | Abstract base class for all errors. Accepts `CustomErrorOptions` (`name`, `message`, `cause`, `stack`, `fast`). |
+| `ApiError`                       | Wraps an `ErrorResponse` from an API, exposing the `response` and `details`.                                    |
+| `AssertionError`                 | Indicates a failed assertion check.                                                                             |
+| `BadRequestError`                | Indicates a client-side error (HTTP 400). Default message: "bad request".                                       |
+| `DetailsError<T>`                | An error that carries an additional `details` payload of type `T`.                                              |
+| `ForbiddenError`                 | Indicates the client is authenticated but lacks permissions (HTTP 403). Default message: "forbidden".           |
+| `InvalidCredentialsError`        | Indicates authentication failed due to bad credentials. Default message: "Invalid credentials.".                |
+| `InvalidTokenError`              | Indicates an authentication token is invalid or expired. Default message: "invalid token".                      |
+| `MaxBytesExceededError`          | Indicates a size limit was exceeded. Includes static `fromBytes(bytes)` factory.                                |
+| `MethodNotAllowedError`          | Indicates the HTTP method is not supported for the resource (HTTP 405).                                         |
+| `MultiError`                     | Aggregates an array of `Error` objects into a single error.                                                     |
+| `NotFoundError`                  | Indicates a resource could not be found (HTTP 404). Default message: "not found".                               |
+| `NotImplementedError`            | Indicates functionality is not yet implemented (HTTP 501).                                                      |
+| `NotSupportedError`              | Indicates an operation or value is not supported. Includes static `fromEnum(...)` factory.                      |
+| `TimeoutError`                   | Indicates an operation exceeded its time limit.                                                                 |
+| `UnauthorizedError`              | Indicates authentication is required (HTTP 401). Default message: "Unauthorized".                               |
+| `UnsupportedMediaTypeError`      | Indicates the payload format is not supported (HTTP 415).                                                       |
+| `unwrapError(error)`             | Utility function to extract the underlying error from a wrapper object (checks `rejection`, `reason`, `error`). |
+| `serializeError(error, options)`  | Serializes an error into a structured JSON-cloneable `SerializedError` object.                                 |
+| `formatError(error, options)`     | Formats an error into a human-readable string, including causes and sub-errors.                                 |
+| `englishTstdlErrorsLocalization` | Localization object containing English headers and messages for standard errors.                                |
+| `germanTstdlErrorsLocalization`  | Localization object containing German headers and messages for standard errors.                                 |

package/file/README.md

@@ -0,0 +1,191 @@
+# File Module
+
+A utility module for robust MIME type detection and server-side temporary file management. It provides tools to identify file types from various sources and a safe, RAII-style wrapper for handling temporary files in Node.js.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Detecting MIME Types](#detecting-mime-types)
+  - [Getting Extensions](#getting-extensions)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Managing Temporary Files](#managing-temporary-files)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Robust MIME Detection**: Identify file types by checking magic numbers (binary signatures) rather than just file extensions.
+- **Versatile Input**: Supports detection from file paths, `Uint8Array` buffers, and `ReadableStream`s.
+- **Extension Lookup**: Retrieve valid file extensions for a specific MIME type.
+- **Automatic Cleanup**: Server-side `TemporaryFile` class implements `AsyncDisposable` for automatic file deletion when the scope exits.
+- **Stream Support**: seamless integration with Node.js and Web Streams for writing to and reading from temporary files.
+
+## Core Concepts
+
+### MIME Type Detection
+
+The module uses the `file-type` library under the hood to inspect the binary signature of a file. This is more secure and accurate than relying on filenames. It supports a wide range of formats including images, video, audio, and archives.
+
+### Temporary File Management (Server)
+
+When processing file uploads or generating reports, you often need to store data on disk temporarily. The `TemporaryFile` class wraps Node.js filesystem operations. It generates a unique path in the OS's temporary directory and ensures the file is deleted when you are done with it, leveraging TypeScript's `using` keyword (Explicit Resource Management).
+
+## 🚀 Basic Usage
+
+### Detecting MIME Types
+
+You can detect the MIME type of a file using a buffer or a stream.
+
+```typescript
+import { getMimeType } from '@tstdl/base/file';
+import { readFile } from 'node:fs/promises';
+
+async function checkFiles() {
+  // 1. From a Uint8Array / Buffer
+  const buffer = await readFile('/path/to/document.pdf');
+  const mimeFromBuffer = await getMimeType(buffer);
+  console.log(mimeFromBuffer); // 'application/pdf'
+
+  // 2. With a fallback if detection fails
+  const mimeWithFallback = await getMimeType(buffer, 'application/octet-stream');
+  console.log(mimeWithFallback);
+}
+```
+
+To detect MIME types from a file path (Node.js only), use the server-specific module:
+
+```typescript
+import { getMimeTypeFromFile } from '@tstdl/base/file/server';
+
+async function checkPath() {
+  const mimeFromPath = await getMimeTypeFromFile('/path/to/image.png');
+  console.log(mimeFromPath); // 'image/png'
+}
+```
+
+### Getting Extensions
+
+Retrieve the list of known extensions for a given MIME type.
+
+```typescript
+import { getMimeTypeExtensions } from '@tstdl/base/file';
+
+const extensions = getMimeTypeExtensions('image/jpeg');
+console.log(extensions); // ['jpeg', 'jpg', 'jpe']
+
+const pdfExt = getMimeTypeExtensions('application/pdf');
+console.log(pdfExt); // ['pdf']
+```
+
+## 🔧 Advanced Topics
+
+### Managing Temporary Files
+
+The `TemporaryFile` class is located in the `server` submodule. It is designed to be used with the `await using` syntax to guarantee cleanup.
+
+> **Note:** This feature requires a Node.js environment.
+
+#### Basic Usage
+
+The most common way to create a temporary file is from a stream, buffer, or string.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function processUpload(uploadStream: ReadableStream<Uint8Array>) {
+  // Create a temp file from a stream. The file is created in os.tmpdir() with a random UUID name.
+  // Optional: pass an extension as the second argument.
+  await using tempFile = await TemporaryFile.from(uploadStream, '.png');
+
+  console.log(`Processing file at: ${tempFile.path}`);
+  console.log(`File size: ${await tempFile.size()} bytes`);
+
+  // Read content back if needed
+  const content = await tempFile.readText();
+
+  // Perform operations (e.g., virus scan, image processing, parsing)
+  await performHeavyProcessing(tempFile.path);
+} // <--- tempFile.delete() is automatically called here!
+```
+
+#### Manual Control and Extensions
+
+You can create an empty temporary file and specify an extension.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function generateReport() {
+  await using tempFile = TemporaryFile.create('.pdf');
+
+  await tempFile.write('Report Content');
+  // ... do something with tempFile.path
+}
+```
+
+#### Persistent Files
+
+If you want to keep the file even after the scope ends (e.g., if you successfully moved it to a final destination), use `keep()` or `moveTo()`.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function savePermanent(stream: ReadableStream<Uint8Array>, destination: string) {
+  await using tempFile = await TemporaryFile.from(stream);
+
+  // ... validate file ...
+
+  // Move the file and mark it to be kept (not deleted on disposal)
+  await tempFile.moveTo(destination, true);
+}
+```
+
+#### Adopting Existing Files
+
+You can wrap an existing file in `TemporaryFile` to ensure it gets deleted when done.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function processExisting(path: string) {
+  await using tempFile = TemporaryFile.adopt(path);
+  // path will be deleted at the end of the scope
+}
+```
+
+## 📚 API
+
+### `@tstdl/base/file`
+
+| Export                  | Type     | Description                                                                                                           |
+| :---------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `getMimeType`           | Function | Async function to detect MIME type from `Uint8Array` or `ReadableStream`. Accepts an optional fallback.               |
+| `getMimeTypeExtensions` | Function | Returns an array of file extensions associated with a MIME type string.                                               |
+| `mimeTypes`             | Object   | A dictionary mapping MIME types to arrays of file extensions.                                                         |
+| `mimeTypesMap`          | Map      | A `Map` version of the `mimeTypes` object for efficient lookup.                                                       |
+
+### `@tstdl/base/file/server`
+
+| Export                 | Type     | Description                                                   |
+| :--------------------- | :------- | :------------------------------------------------------------ |
+| `getMimeTypeFromFile`  | Function | Async function to detect MIME type from a string file path (Node.js only). |
+| `TemporaryFile`        | Class    | A wrapper for temporary files implementing `AsyncDisposable`. |
+
+#### `TemporaryFile` Class
+
+| Method/Property           | Description                                                                                                  |
+| :------------------------ | :----------------------------------------------------------------------------------------------------------- |
+| `path`                    | Getter for the absolute file path.                                                                                             |
+| `static create(ext?)`     | Creates a new empty `TemporaryFile` instance with an optional extension.                                                       |
+| `static adopt(path)`      | Creates a `TemporaryFile` instance wrapping an existing file path.                                                            |
+| `static from(content, ext?)` | Creates a `TemporaryFile` and writes the provided content (string, Uint8Array, or Stream) to it, with an optional extension. |
+| `read()`                  | Reads the file content as a `Uint8Array`.                                                                                     |
+| `readText()`              | Reads the file content as a UTF-8 string.                                                                                     |
+| `readStream()`            | Returns a `ReadableStream<Uint8Array>` of the file content.                                                                   |
+| `write(content)`          | Overwrites the file with the provided content.                                                                                |
+| `moveTo(path, keep?)`     | Moves the file to a new location. If `keep` is true, it won't be deleted on disposal.                                         |
+| `keep()`                  | Prevents the file from being deleted when the object is disposed.                                                             |
+| `delete()`                | Manually deletes the file.                                                                                                    |
+| `size()`                  | Returns the size of the file in bytes.                                                                                        |
+| `[Symbol.asyncDispose]()` | Automatically calls `delete()` when used with `await using`, unless `keep()` was called.                                     |

package/formats/README.md

@@ -0,0 +1,210 @@
+# @tstdl/base/formats
+
+A comprehensive utility module for locale-aware formatting of numbers, dates, times, currencies, and names. It leverages the standard `Intl` API with aggressive memoization to ensure high performance in rendering-heavy applications.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Locale-Aware**: Defaults to `de-DE` (German) but fully configurable.
+- **High Performance**: Uses memoization to cache `Intl.NumberFormat` and `Intl.DateTimeFormat` instances, avoiding expensive instantiation costs.
+- **Type Safety**: Fully typed in TypeScript.
+- **Rich Set of Formatters**:
+  - Integers, Decimals, Percentages.
+  - Currencies (with and without cents, specific Euro helpers).
+  - Dates (Short, Medium, Long, Numeric) and Times.
+  - Person Names (First/Last name handling).
+- **Numeric Date Support**: Utilities to format dates stored as integers (e.g., `20231231`).
+
+## Core Concepts
+
+### Global Configuration
+
+The module operates with a global locale setting (defaulting to `de-DE`). This is designed for applications that typically run in a single locale context (like a server-side renderer or a client-side SPA). You can configure this once at startup.
+
+### Memoization
+
+Creating `Intl.NumberFormat` or `Intl.DateTimeFormat` instances can be slow. This module creates these formatters once per locale/option combination and reuses them. This makes functions like `formatDecimal` or `formatDate` safe to use inside tight loops or render functions.
+
+## 🚀 Basic Usage
+
+### Configuration
+
+Set the locale at the entry point of your application.
+
+```ts
+import { configureFormats } from '@tstdl/base/formats';
+
+// Set to US English
+configureFormats({ locale: 'en-US' });
+```
+
+### Number Formatting
+
+```ts
+import { formatInteger, formatDecimal, formatPercent } from '@tstdl/base/formats';
+
+// Assuming locale is de-DE
+console.log(formatInteger(12345.67));
+// Output: "12.346" (rounded)
+
+console.log(formatDecimal(12345.6789));
+// Output: "12.345,68" (default 2 fraction digits)
+
+console.log(formatDecimal(12345.6789, { minimumFractionDigits: 3, maximumFractionDigits: 4 }));
+// Output: "12.345,679" (min 3, max 4 fraction digits)
+
+console.log(formatPercent(0.1234));
+// Output: "12,34 %"
+```
+
+### Currency Formatting
+
+```ts
+import { formatEuro, formatCurrency, formatCurrencyWithoutCents } from '@tstdl/base/formats';
+
+console.log(formatEuro(1500.5));
+// Output: "1.500,50 €"
+
+console.log(formatCurrency(1500.5, 'USD'));
+// Output: "1.500,50 $" (Format depends on locale, symbol depends on currency)
+
+console.log(formatCurrencyWithoutCents(1500.5, 'EUR'));
+// Output: "1.501 €" (Rounded)
+```
+
+### Date and Time Formatting
+
+```ts
+import { formatDate, formatDateShort, formatTimeShort } from '@tstdl/base/formats';
+
+const date = new Date('2023-10-05T14:30:00');
+
+console.log(formatDate(date));
+// Output: "05.10.2023" (Standard date format for de-DE)
+
+console.log(formatDateShort(date));
+// Output: "05.10.2023"
+
+// formatTimeShort expects milliseconds for the time portion
+// (Internally often used with durations or specific times of day)
+console.log(formatTimeShort(date));
+// Output: "14:30"
+```
+
+## 🔧 Advanced Topics
+
+### Formatting Person Names
+
+The `formatPersonName` helper handles objects with `firstName` and `lastName` properties, dealing with nulls and formatting preferences.
+
+```ts
+import { formatPersonName } from '@tstdl/base/formats';
+
+const user = { firstName: 'John', lastName: 'Doe' };
+const incompleteUser = { firstName: null, lastName: 'Doe' };
+
+console.log(formatPersonName(user));
+// Output: "John Doe"
+
+console.log(formatPersonName(user, { lastNameFirst: true }));
+// Output: "Doe, John"
+
+console.log(formatPersonName(incompleteUser));
+// Output: "Doe"
+
+console.log(formatPersonName(null, { fallback: 'Anonymous' }));
+// Output: "Anonymous"
+```
+
+### Numeric Dates
+
+Often databases store dates as integers (e.g., `20231231`) for indexing efficiency. The `formatNumericDate` function handles this conversion automatically.
+
+```ts
+import { formatNumericDate } from '@tstdl/base/formats';
+
+// Formats integer 20231231 as a date
+console.log(formatNumericDate(20231231));
+// Output: "31.12.2023"
+```
+
+### Custom Number Formatting
+
+You can pass standard `Intl.NumberFormatOptions` to `formatNumber` for one-off requirements that aren't covered by the standard helpers.
+
+```ts
+import { formatNumber } from '@tstdl/base/formats';
+
+console.log(
+  formatNumber(1234.567, {
+    style: 'unit',
+    unit: 'kilometer',
+    maximumFractionDigits: 1,
+  }),
+);
+// Output: "1.234,6 km"
+```
+
+## 📚 API
+
+### Configuration
+
+| Function                    | Description                                                                              |
+| :-------------------------- | :--------------------------------------------------------------------------------------- |
+| `configureFormats(options)` | Sets the global locale used by all formatters. Default is `de-DE`. Can be a static string or a provider function. |
+
+### Number Formatters
+
+| Function                       | Description                                                     |
+| :----------------------------- | :-------------------------------------------------------------- |
+| `formatNumber(value, format?)`  | Formats a number using optional `Intl.NumberFormatOptions`.     |
+| `formatInteger(value, format?)` | Formats as an integer (0 fraction digits).                      |
+| `formatDecimal(value, format?)` | Formats as a decimal. Default min/max fraction digits is 2.     |
+| `formatPercent(value, format?)` | Formats a ratio (0-1) as a percentage (0-100%).                 |
+
+### Currency Formatters
+
+| Function                                      | Description                                              |
+| :-------------------------------------------- | :------------------------------------------------------- |
+| `formatCurrency(value, currency, format?)`    | Formats value as currency (e.g., 'EUR', 'USD').          |
+| `formatCurrencyWithoutCents(value, currency, format?)` | Formats currency rounded to the nearest integer.         |
+| `formatEuro(value, format?)`                  | Shortcut for `formatCurrency(value, 'EUR')`.             |
+| `formatEuroWithoutCents(value, format?)`      | Shortcut for `formatCurrencyWithoutCents(value, 'EUR')`. |
+
+### Date & Time Formatters
+
+| Function                              | Description                                                                |
+| :------------------------------------ | :------------------------------------------------------------------------- |
+| `formatDateTime(value, format?)`      | Formats a `Date`, timestamp or `DateTime` object using optional `Intl.DateTimeFormatOptions`. |
+| `formatDate(dateOrTimestamp, format?)` | Formats using `dateShort` options (numeric day, month, 2-digit year).      |
+| `formatDateShort(value, format?)`      | Alias for `formatDate`.                                                    |
+| `formatTimeShort(value, format?)`      | Formats a time value to `HH:MM`.                                           |
+| `formatNumericDate(numericDate, options?)` | Converts a `YYYYMMDD` integer to a formatted date string (`dateShort`). |
+| `formatNumericDateShort(numericDate, options?)` | Alias for `formatNumericDate`.                                   |
+| `formatNumericDateLong(numericDate, options?)` | Converts a `YYYYMMDD` integer to a long date format (`dateLong`).     |
+
+### Utilities
+
+| Function                             | Description                                                                                                |
+| :----------------------------------- | :--------------------------------------------------------------------------------------------------------- |
+| `formatPersonName(person, options?)` | Formats a name from an object `{ firstName?, lastName? }`. Options include `lastNameFirst` and `fallback`. |
+
+### Constants (Format Options)
+
+The module exports standard `Intl` configuration objects used internally. These can be useful if you need to instantiate your own formatters with the same styles.
+
+- `integerFormat`
+- `decimalFormat`
+- `decimal1Format`
+- `dateTimeNumeric`, `dateTimeShort`, `dateTimeLong`
+- `dateShort`, `dateMedium`, `dateLong`
+- `timeShort`
+- `currencyFormat`, `currencyFormatWithoutCents`
+- `percentFormat`