@tstdl/base 0.93.139 → 0.93.140

package/logger/README.md

@@ -0,0 +1,287 @@
+# Logger
+
+A flexible, extensible, and dependency-injection-friendly structured logging module for TypeScript applications. It features granular log level control, hierarchical context, and pluggable transports and formatters.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Configuration](#configuration)
+  - [Injecting and Using the Logger](#injecting-and-using-the-logger)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Structured Context & Interpolation](#structured-context--interpolation)
+  - [Hierarchical Loggers (Forking)](#hierarchical-loggers-forking)
+  - [Managing Log Levels](#managing-log-levels)
+  - [Formatters](#formatters)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Dependency Injection First**: Designed to be configured once and injected anywhere using `@tstdl/base/injector`.
+- **Structured Logging**: Attach arbitrary key-value context to logs for better observability.
+- **Granular Level Control**: Set a global default level and override it for specific modules (e.g., `Database` vs `Http`).
+- **Hierarchical Context**: Create child loggers (`fork`) that inherit or extend the parent's module path and context.
+- **Message Interpolation**: Automatically inject context values into log messages using `{key}` syntax.
+- **Pluggable Transports**: Comes with a `ConsoleLogTransport`, but easily extensible to file, network, or other outputs.
+- **Formatters**: Includes `PrettyPrintLogFormatter` for development and `JsonLogFormatter` for production.
+
+## Core Concepts
+
+### Logger
+
+The primary class used to emit logs. It is usually injected into services. A `Logger` instance holds a **module path** (e.g., `['Api', 'Users']`) and a **context** (key-value pairs).
+
+### LogManager
+
+A singleton service that orchestrates the logging system. It maintains the log level configuration (mapping module paths to levels) and dispatches log entries to all registered transports.
+
+### LogLevel
+
+An enumeration defining the severity of logs:
+
+1.  `Error` (0)
+2.  `Warn` (1)
+3.  `Info` (2)
+4.  `Verbose` (3)
+5.  `Debug` (4)
+6.  `Trace` (5)
+
+### LogTransport
+
+A destination for log entries. The module provides `ConsoleLogTransport`. Transports can have their own minimum log level (e.g., log everything to file, but only warnings to console).
+
+### LogFormatter
+
+Transforms a structured log payload into a string.
+
+- **`PrettyPrintLogFormatter`**: Colorful, human-readable output (great for local dev).
+- **`JsonLogFormatter`**: NDJSON (Newline Delimited JSON) output (standard for log aggregation systems).
+
+## 🚀 Basic Usage
+
+### Configuration
+
+In your application's bootstrap or entry point, configure the `Injector` with the desired log level and transport.
+
+```typescript
+import { Injector } from '@tstdl/base/injector';
+import { DEFAULT_LOG_LEVEL, LogLevel, provideConsoleLogTransport, PrettyPrintLogFormatter } from '@tstdl/base/logger';
+
+// 1. Set the global default log level (optional, defaults to Trace)
+Injector.register(DEFAULT_LOG_LEVEL, { useValue: LogLevel.Info });
+
+// 2. Register the Console Transport
+// Use PrettyPrintLogFormatter for development
+Injector.register(provideConsoleLogTransport(PrettyPrintLogFormatter));
+
+// Alternatively, for production JSON logging:
+// import { JsonLogFormatter } from '@tstdl/base/logger';
+// Injector.register(provideConsoleLogTransport(JsonLogFormatter));
+```
+
+### Injecting and Using the Logger
+
+Inject the `Logger` into your services. You can pass a string or array of strings to the `inject` function to define the **module name**.
+
+```typescript
+import { Injectable, inject } from '@tstdl/base/injector';
+import { Logger } from '@tstdl/base/logger';
+
+@Injectable()
+export class UserService {
+  // Inject logger and tag it with 'UserService' module
+  private readonly logger = inject(Logger, 'UserService');
+
+  async getUser(id: string): Promise<void> {
+    this.logger.info(`Fetching user ${id}`);
+
+    try {
+      // ... logic ...
+      this.logger.debug('User fetched successfully');
+    } catch (error) {
+      // Overload 1: Pass only the error and context
+      this.logger.error(error, { userId: id });
+
+      // Overload 2: Pass a custom message, the error, and context
+      this.logger.error('Failed to fetch user', error, { userId: id });
+    }
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Structured Context & Interpolation
+
+You can pass a context object as the second argument to any log method. Values in the context can be interpolated into the message using `{key}` syntax. It also supports nested property access using dot notation.
+
+```typescript
+const user = { id: 'u-123', profile: { name: 'John Doe' } };
+const duration = 45;
+
+// Context is attached to the log entry
+this.logger.info('Request processed', { user, duration });
+
+// Interpolation: The message will become "User John Doe (u-123) processed in 45ms"
+this.logger.info('User {user.profile.name} ({user.id}) processed in {duration}ms', { user, duration });
+```
+
+You can also create a temporary logger with bound context using `.with()`:
+
+```typescript
+const requestLogger = this.logger.with({ requestId: 'req-abc' });
+
+requestLogger.info('Step 1'); // Context: { requestId: 'req-abc' }
+requestLogger.info('Step 2'); // Context: { requestId: 'req-abc' }
+```
+
+### Hierarchical Loggers (Forking)
+
+Use `.fork()` to create a sub-logger. This appends to the module path and inherits the parent's context. This is useful for passing loggers down to sub-components while maintaining the overall context.
+
+```typescript
+// Parent logger module: ['Database']
+const dbLogger = inject(Logger, 'Database');
+
+// Child logger module: ['Database', 'Connection']
+const connLogger = dbLogger.fork('Connection');
+
+connLogger.info('Connected');
+// Output: ... INFO [Database Connection] Connected
+```
+
+You can also replace or extend context during a fork, or even specify a fixed log level for the new logger:
+
+```typescript
+const taskLogger = this.logger.fork('TaskWorker', {
+  context: { taskId: 1 },
+  replaceContext: false, // merge with parent context (default)
+  level: LogLevel.Debug  // Force this logger to Debug level, ignoring LogManager rules
+});
+```
+
+Using `.with()` is similar to `.fork()`, but it only adds context without changing the module path.
+
+### Advanced Logger Injection
+
+When injecting a `Logger`, you can provide more than just a module name. The injection argument supports an options object:
+
+```typescript
+@Injectable()
+export class DebugService {
+  // Inject with fixed level and initial context
+  private readonly logger = inject(Logger, {
+    module: 'DebugService',
+    level: LogLevel.Trace,
+    context: { environment: 'development' }
+  });
+}
+```
+
+### Managing Log Levels
+
+The `LogManager` allows you to set log levels dynamically for specific modules. This is useful for debugging specific parts of an application without enabling debug logs globally.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { LogManager, LogLevel } from '@tstdl/base/logger';
+
+const logManager = inject(LogManager);
+
+// Set default level for everything
+logManager.setDefaultLevel(LogLevel.Info);
+
+// Enable Debug logs for the 'Database' module and all its sub-modules
+logManager.setModuleLevel('Database', LogLevel.Debug);
+
+// Enable Trace logs specifically for 'Database.Connection'
+logManager.setModuleLevel(['Database', 'Connection'], LogLevel.Trace);
+```
+
+### Formatters
+
+Formatters determine how the log payload is converted to a string.
+
+**PrettyPrintLogFormatter**
+Outputs colorful, human-readable logs.
+
+```text
+2023-10-27T10:00:00.000Z INFO:    [UserService] User created {"id":1}
+```
+
+**JsonLogFormatter**
+Outputs a JSON string for each log line. All context properties are spread into the top-level JSON object.
+
+```json
+{ "timestamp": "2023-10-27T10:00:00.000Z", "level": "info", "module": "UserService", "message": "User created", "id": 1 }
+```
+
+### Custom Transports
+
+To create a custom transport, extend the `LogTransport` class and implement the `log` method.
+
+```typescript
+import { Singleton } from '@tstdl/base/injector';
+import { LogTransport, LogPayload, provideLogTransport, LogLevel } from '@tstdl/base/logger';
+
+@Singleton()
+export class MyCustomTransport extends LogTransport {
+  override log(payload: LogPayload): void {
+    // Implement custom logic (e.g., send to an external API)
+    console.log('Custom transport:', payload.message);
+  }
+}
+
+// Register it in the Injector
+Injector.register(provideLogTransport({ useToken: MyCustomTransport }));
+
+// You can also specify a minimum level for the transport
+Injector.register(provideLogTransport({ useToken: MyCustomTransport, defaultArgument: { level: LogLevel.Error } }));
+```
+
+### Multiple Transports
+
+You can register as many transports as you need. Each log entry will be dispatched to all registered transports whose minimum log level is satisfied.
+
+```typescript
+// Log everything to console in pretty format
+Injector.register(provideConsoleLogTransport(PrettyPrintLogFormatter));
+
+// ALSO log warnings and errors to a custom transport
+Injector.register(provideLogTransport({
+  useToken: MyCustomTransport,
+  defaultArgument: { level: LogLevel.Warn }
+}));
+```
+
+## 📚 API
+
+### Classes
+
+| Class                     | Description                                                                                                            |
+| :------------------------ | :--------------------------------------------------------------------------------------------------------------------- |
+| `Logger`                  | The main logging interface. Supports methods `error`, `warn`, `info`, `verbose`, `debug`, `trace`, `fork`, and `with`. |
+| `LogManager`              | Singleton that manages log levels and dispatches logs to transports.                                                   |
+| `LogTransport`            | Abstract base class for log destinations.                                                                              |
+| `ConsoleLogTransport`     | A transport that writes to `console.log`, `console.error`, etc.                                                        |
+| `LogFormatter`            | Abstract base class for formatting log payloads.                                                                       |
+| `JsonLogFormatter`        | Formats logs as JSON strings.                                                                                          |
+| `PrettyPrintLogFormatter` | Formats logs for human readability with colors.                                                                        |
+
+### Enums & Types
+
+| Name                | Description                                                                                                                        |
+| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------- |
+| `LogLevel`          | Enum: `Error` (0), `Warn` (1), `Info` (2), `Verbose` (3), `Debug` (4), `Trace` (5).                                                |
+| `LogPayload`        | The structured data object passed to formatters and transports. Contains `timestamp`, `level`, `module`, `message`, and `context`. |
+| `LoggerArgument`    | Type for the argument passed to `inject(Logger, argument)`. Can be a string (module name), string array, or options object.        |
+| `LoggerForkOptions` | Options for creating a child logger via `.fork()`.                                                                                 |
+
+### Functions & Tokens
+
+| Name                                            | Description                                                   |
+| :---------------------------------------------- | :------------------------------------------------------------ |
+| `provideLogTransport(provider)`                 | Helper to register any `LogTransport` with `multi: true`.     |
+| `provideConsoleLogTransport(formatter, level?)` | Helper specifically for registering the `ConsoleLogTransport`. |
+| `DEFAULT_LOG_LEVEL`                             | Injection token to configure the default global log level.    |

package/mail/README.md

@@ -0,0 +1,256 @@
+# Mail
+
+A robust module for sending emails with powerful templating capabilities, pluggable mail clients, and automatic database logging.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Configuration](#configuration)
+  - [Sending a Simple Email](#sending-a-simple-email)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Using Templates](#using-templates)
+  - [Per-Request Client Configuration](#per-request-client-configuration)
+  - [Implementing a Custom Mail Client](#implementing-a-custom-mail-client)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Pluggable Mail Clients**: Abstracted `MailClient` allows for different sending backends. A `NodemailerMailClient` is provided out-of-the-box.
+- **Powerful Templating**: Integrates with `@tstdl/base/templates` to generate email subjects, HTML, and text bodies from templates and context data.
+- **Automatic Logging**: Every mail-sending attempt is logged to the database (`mail.log` table), including data, results, and errors, for auditing and debugging.
+- **Flexible Configuration**: Easily configure default clients, connection settings (host, port, auth), and default mail data (e.g., a global `from` address).
+- **Type Safety**: Fully typed API for mail data, templates, and configuration.
+
+## Core Concepts
+
+### MailService
+
+The `MailService` is the central component. It orchestrates the rendering of templates (if used), delegates the actual sending to the configured `MailClient`, and ensures the transaction is logged to the database.
+
+### MailClient
+
+`MailClient` is an abstract class defining the contract for sending emails. The module includes `NodemailerMailClient`, which uses `nodemailer` under the hood. You can implement your own client (e.g., for SendGrid, AWS SES API) by extending this class.
+
+### MailTemplate
+
+A `MailTemplate` defines the structure of an email (subject, html, text) using the `@tstdl/base/templates` system. This allows for dynamic content generation based on a context object.
+
+## 🚀 Basic Usage
+
+### Configuration
+
+To use the mail module, you must configure it during your application's bootstrap phase. This involves registering the configuration and running migrations to create the necessary database tables.
+
+```typescript
+import { configureMail, NodemailerMailClient, migrateMailSchema } from '@tstdl/base/mail';
+import { configureOrm } from '@tstdl/base/orm/server';
+import { inject, Injector } from '@tstdl/base/injector';
+
+async function bootstrap() {
+  // Ensure ORM is configured first as MailService relies on it for logging
+  configureOrm({
+    connection: {
+      host: 'localhost',
+      port: 5432,
+      user: 'db_user',
+      password: 'db_password',
+      database: 'my_app',
+    },
+  });
+
+  // Configure the Mail Module
+  configureMail({
+    // Use the default database connection configured above
+    // You can also pass a specific DatabaseConfig object here
+    database: undefined,
+
+    // Specify the client implementation to use
+    client: NodemailerMailClient,
+
+    // Default SMTP settings
+    defaultClientConfig: {
+      host: 'smtp.example.com',
+      port: 587,
+      secure: false, // true for 465, false for other ports
+      auth: {
+        user: 'user@example.com',
+        password: 'secret-password',
+      },
+    },
+
+    // Default data applied to every email (e.g., global sender)
+    defaultData: {
+      from: { name: 'My App Support', address: 'support@myapp.com' },
+    },
+  });
+
+  // Run migrations to create the 'mail.log' table
+  const injector = inject(Injector);
+  await injector.run(migrateMailSchema);
+}
+```
+
+### Sending a Simple Email
+
+Inject `MailService` and use the `send` method to dispatch an email.
+
+```typescript
+import { Singleton, inject } from '@tstdl/base/injector';
+import { MailService } from '@tstdl/base/mail';
+
+@Singleton()
+export class NotificationService {
+  readonly #mailService = inject(MailService);
+
+  async sendWelcome(email: string, name: string): Promise<void> {
+    await this.#mailService.send({
+      to: { name, address: email },
+      subject: 'Welcome to My App',
+      content: {
+        text: `Hello ${name}, welcome to our platform!`,
+        html: `<p>Hello <strong>${name}</strong>, welcome to our platform!</p>`,
+      },
+    });
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Using Templates
+
+You can define reusable templates for your emails. This requires the `@tstdl/base/templates` module to be configured.
+
+**1. Define the Template**
+
+```typescript
+import { mailTemplate } from '@tstdl/base/mail';
+import { stringTemplateField } from '@tstdl/base/templates/resolvers';
+
+// Define the context type for type safety
+type PasswordResetContext = {
+  name: string;
+  resetLink: string;
+};
+
+export const passwordResetTemplate = mailTemplate<PasswordResetContext>('password-reset', {
+  subject: stringTemplateField({
+    renderer: 'string',
+    template: 'Password Reset Request for {{ name }}',
+  }),
+  text: stringTemplateField({
+    renderer: 'string',
+    template: 'Hi {{ name }},\n\nPlease click here to reset your password: {{ resetLink }}',
+  }),
+  // You can also add an 'html' field here using jsxTemplateField or others
+});
+```
+
+**2. Send using the Template**
+
+```typescript
+import { Singleton, inject } from '@tstdl/base/injector';
+import { MailService } from '@tstdl/base/mail';
+import { passwordResetTemplate } from './mail-templates.js';
+
+@Singleton()
+export class AuthService {
+  readonly #mailService = inject(MailService);
+
+  async requestPasswordReset(email: string, name: string): Promise<void> {
+    const context = {
+      name,
+      resetLink: 'https://myapp.com/reset?token=12345',
+    };
+
+    // sendTemplate automatically renders subject, text, and html
+    await this.#mailService.sendTemplate(
+      passwordResetTemplate,
+      { to: email }, // MailData (excluding content and subject)
+      context,
+    );
+  }
+}
+```
+
+### Per-Request Client Configuration
+
+Sometimes you need to send specific emails using a different SMTP server or credentials (e.g., transactional vs. marketing emails). You can override the default configuration per call.
+
+```typescript
+import { Singleton, inject } from '@tstdl/base/injector';
+import { MailService, type MailClientConfig } from '@tstdl/base/mail';
+
+@Singleton()
+export class MarketingService {
+  readonly #mailService = inject(MailService);
+
+  async sendNewsletter(email: string): Promise<void> {
+    const marketingConfig: MailClientConfig = {
+      host: 'smtp.marketing-provider.com',
+      port: 587,
+      auth: {
+        user: 'marketing',
+        password: 'marketing-password',
+      },
+    };
+
+    await this.#mailService.send(
+      {
+        to: email,
+        subject: 'Weekly Newsletter',
+        content: { text: '...' },
+      },
+      marketingConfig, // Override config
+    );
+  }
+}
+```
+
+### Implementing a Custom Mail Client
+
+To support a different provider (e.g., SendGrid API), extend `MailClient` and register it.
+
+```typescript
+import { Singleton } from '@tstdl/base/injector';
+import { MailClient, type MailData, type MailSendResult, type MailClientConfig } from '@tstdl/base/mail';
+
+@Singleton()
+export class MyCustomMailClient extends MailClient {
+  async send(data: MailData, clientConfig?: MailClientConfig): Promise<MailSendResult> {
+    // Implement sending logic here (e.g., fetch call to API)
+    console.log('Sending mail via custom client', data);
+
+    return {
+      messageId: 'custom-id-123',
+      accepted: [data.to as any],
+      rejected: [],
+      pending: [],
+    };
+  }
+}
+
+// In bootstrap:
+configureMail({
+  client: MyCustomMailClient,
+  // ...
+});
+```
+
+## 📚 API
+
+| Export                 | Type             | Description                                                  |
+| :--------------------- | :--------------- | :----------------------------------------------------------- |
+| `MailService`          | `class`          | Main service for sending emails and logging.                 |
+| `MailClient`           | `abstract class` | Base class for mail sending implementations.                 |
+| `NodemailerMailClient` | `class`          | Implementation of `MailClient` using Nodemailer.             |
+| `configureMail`        | `function`       | Configures the module (database, client, defaults).          |
+| `migrateMailSchema`    | `function`       | Runs database migrations for the `mail` schema.              |
+| `mailTemplate`         | `function`       | Helper to define a type-safe `MailTemplate`.                 |
+| `MailData`             | `type`           | Structure for email data (to, from, subject, content, etc.). |
+| `MailSendResult`       | `type`           | Result returned after sending an email.                      |
+| `MailClientConfig`     | `class`          | Configuration object for mail clients (host, port, auth).    |
+| `MailLog`              | `class`          | Entity representing the database log entry for sent mails.   |
+| `MAIL_DEFAULT_DATA`    | `InjectionToken` | Token for injecting default mail data.                       |

package/memory/README.md

@@ -0,0 +1,144 @@
+# @tstdl/base/memory
+
+Utilities for advanced memory management and garbage collection observation in TypeScript. This module provides enhanced wrappers around the native `FinalizationRegistry` API, enabling multiple cleanup handlers per object and reactive garbage collection events via RxJS.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Multiple Handlers](#multiple-handlers)
+  - [Observable Finalization Registry](#observable-finalization-registry)
+  - [Unregistering Handlers](#unregistering-handlers)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Multiple Finalization Handlers**: Attach multiple independent cleanup callbacks to a single object instance without conflicts.
+- **Reactive GC Events**: Use `ObservableFinalizationRegistry` to receive RxJS notifications when objects are garbage collected.
+- **Type-Safe Context**: Pass strongly-typed data to your finalization handlers to aid in cleanup (e.g., closing handles, logging IDs).
+- **Abstraction**: Hides the complexity of managing `FinalizationRegistry` instances and tokens.
+
+## Core Concepts
+
+JavaScript's `FinalizationRegistry` allows you to request a callback when an object is garbage collected. However, managing these registries can be cumbersome, especially if different parts of your application need to attach different cleanup logic to the same object.
+
+The **Memory** module solves this by:
+
+1.  **Centralizing Registry Management**: `registerFinalization` uses a shared internal registry and a mapping system to allow multiple handlers for one object.
+2.  **Bridging to RxJS**: `ObservableFinalizationRegistry` turns the callback-based API into a stream-based API, making it easier to integrate with reactive architectures.
+
+> **Note**: Garbage collection is non-deterministic. There is no guarantee _when_ or _if_ the cleanup handlers will run. These tools should be used for auxiliary cleanup (like releasing external resources or debugging leaks), not for critical program logic.
+
+## 🚀 Basic Usage
+
+The most common use case is attaching a cleanup function to an object. This function will run after the object has been garbage collected.
+
+```ts
+import { registerFinalization } from '@tstdl/base/memory';
+
+class Resource {
+  id: number;
+
+  constructor(id: number) {
+    this.id = id;
+  }
+}
+
+// 1. Create an object
+let myResource: Resource | null = new Resource(123);
+
+// 2. Register a cleanup handler
+// We pass the ID as data because we can't access 'myResource' inside the handler
+// (it will be gone by then).
+registerFinalization(
+  myResource,
+  (id) => {
+    console.log(`Resource with ID ${id} was garbage collected.`);
+  },
+  123,
+);
+
+// 3. Dereference the object to make it eligible for GC
+myResource = null;
+
+// ... Sometime later, when GC runs:
+// Output: "Resource with ID 123 was garbage collected."
+```
+
+> **Warning**: Never pass the object being registered as the `data` payload, nor any object that holds a strong reference to it. Doing so will create a strong reference cycle and prevent the object from ever being garbage collected.
+
+## 🔧 Advanced Topics
+
+### Multiple Handlers
+
+Unlike the native `FinalizationRegistry`, which only allows one "held value" per registration, `registerFinalization` allows you to attach any number of handlers to the same object.
+
+```ts
+import { registerFinalization } from '@tstdl/base/memory';
+
+const obj = { name: 'MultiHandler' };
+
+registerFinalization(obj, () => console.log('Handler 1: Cleanup successful.'));
+registerFinalization(obj, () => console.log('Handler 2: Notifying external system.'));
+
+// Both handlers will run independently when 'obj' is collected.
+```
+
+### Observable Finalization Registry
+
+If you prefer working with RxJS Observables, `ObservableFinalizationRegistry` emits values to a stream whenever a registered object is reclaimed.
+
+```ts
+import { ObservableFinalizationRegistry } from '@tstdl/base/memory';
+
+// Create a registry that expects a string token
+const registry = new ObservableFinalizationRegistry<string>();
+
+// Subscribe to the stream
+const subscription = registry.finalize$.subscribe((token) => {
+  console.log(`Object associated with token "${token}" was collected.`);
+});
+
+// Register an object
+let tempObject: object | null = {};
+registry.register(tempObject, 'unique-token-abc');
+
+// Dereference
+tempObject = null;
+
+// ... Sometime later:
+// Output: "Object associated with token "unique-token-abc" was collected."
+```
+
+### Unregistering Handlers
+
+You can remove a specific cleanup handler if it is no longer needed (e.g., if the resource was manually closed).
+
+```ts
+import { registerFinalization, unregisterFinalization } from '@tstdl/base/memory';
+
+const data = { value: 'important' };
+
+const cleanup = () => {
+  console.log('Cleanup data');
+};
+
+// Register
+registerFinalization(data, cleanup);
+
+// Unregister specifically this handler
+unregisterFinalization(data, cleanup);
+
+// Even if 'data' is garbage collected now, 'cleanup' will NOT run.
+```
+
+## 📚 API
+
+| Export                           | Type     | Description                                                                                                                                                                 |
+| :------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerFinalization`           | Function | Registers a callback to be invoked after the target object is garbage collected. Supports multiple handlers and a data payload.                                             |
+| `unregisterFinalization`         | Function | Unregisters a specific callback for a target object without affecting other registered handlers for the same object.                                                        |
+| `ObservableFinalizationRegistry` | Class    | Extends native `FinalizationRegistry`. Exposes a `finalize$` Observable that emits the `heldValue` when an object is collected.                                             |
+| `FinalizationHandler<D>`         | Type     | Type definition for the callback function: `(data: D) => any`. `D` defaults to `any` and is inferred when using `registerFinalization`.                                   |