@tstdl/base 0.93.139 → 0.93.140

package/api/types.d.ts

@@ -1,6 +1,7 @@
 import type { Observable } from 'rxjs';
 import type { Auditor } from '../audit/index.js';
 import type { Token } from '../authentication/index.js';
+import type { CancellationSource } from '../cancellation/token.js';
 import type { HttpHeaders, HttpHeadersObject, HttpRequestAuthorization } from '../http/index.js';
 import type { HttpServerRequest, HttpServerResponse } from '../http/server/index.js';
 import type { HttpMethod } from '../http/types.js';
@@ -132,9 +133,9 @@ export type ApiRequestContext<T extends ApiDefinition = ApiDefinition, K extends
 export type ApiEndpointServerImplementation<T extends ApiDefinition = ApiDefinition, K extends ApiEndpointKeys<T> = ApiEndpointKeys<T>> = (context: ApiRequestContext<T, K>) => ApiServerResult<T, K> | Promise<ApiServerResult<T, K>>;
 export type ApiClientRequestOptions = {
     /**
-     * AbortSignal to cancel the request.
+     * CancellationSignal to cancel the request.
      */
-    abortSignal?: AbortSignal;
+    cancellationSignal?: CancellationSource;
     /**
      * Request timeout in milliseconds.
      * @default 30000

package/application/README.md

@@ -0,0 +1,240 @@
+# Application Module
+
+A robust framework for bootstrapping, managing lifecycle, and handling graceful shutdown of TypeScript applications. It integrates seamlessly with dependency injection to orchestrate modules, services, and startup/cleanup routines.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [The Application Container](#the-application-container)
+  - [Modules](#modules)
+  - [Lifecycle Hooks](#lifecycle-hooks)
+  - [Graceful Shutdown](#graceful-shutdown)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Class-Based Modules](#class-based-modules)
+  - [Initializers and Destructors](#initializers-and-destructors)
+  - [Programmatic Shutdown](#programmatic-shutdown)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Modular Architecture**: Organize application logic into reusable, independent modules.
+- **Dependency Injection**: Built on top of `@tstdl/base/injector` for robust service resolution.
+- **Lifecycle Management**: Orchestrates the startup and shutdown sequence of all registered modules.
+- **Graceful Shutdown**: Built-in handling of process signals (like `SIGINT` and `SIGTERM`) to ensure resources are released properly.
+- **Async Hooks**: Supports asynchronous initializers and destructors for database connections or external service setup.
+- **Cancellation Propagation**: Provides a `CancellationSignal` to all modules to coordinate termination of long-running tasks.
+
+## Core Concepts
+
+### The Application Container
+
+The `Application` class is the entry point. It creates a dependency injection container, resolves all registered modules, and manages their execution state. It acts as the central hub for the application's lifecycle.
+
+### Modules
+
+A module is a unit of execution. It can be:
+
+- **A simple function**: Useful for scripts or simple entry points.
+- **A class extending `Module`**: Useful for complex, stateful services that need to handle startup and shutdown logic explicitly.
+
+### Lifecycle Hooks
+
+- **Initializers**: Functions that run _before_ any module is started. Used for configuration, database connections, or pre-flight checks.
+- **Destructors**: Functions that run _after_ all modules have stopped. Used for closing connections, flushing logs, or cleaning up resources.
+
+### Graceful Shutdown
+
+When configured with `provideSignalHandler()`, the application listens for termination signals. Upon receiving one:
+
+1.  The global `shutdownSignal` is triggered.
+2.  All running modules are requested to stop.
+3.  The application waits for modules to finish their cleanup.
+4.  Destructors are executed.
+5.  The process exits.
+
+## 🚀 Basic Usage
+
+The simplest way to start an application is using a function as a module.
+
+```ts
+import { Application, provideModule, provideSignalHandler } from '@tstdl/base/application';
+import { inject } from '@tstdl/base/injector';
+import { Logger } from '@tstdl/base/logger';
+import { timeout } from '@tstdl/base/utils';
+
+// 1. Define your main logic
+async function main(): Promise<void> {
+  const logger = inject(Logger);
+  const app = inject(Application);
+
+  logger.info('Application started!');
+
+  // Simulate some work
+  await timeout(1000);
+
+  logger.info('Work done.');
+
+  // Request shutdown if the task is finite
+  app.requestShutdown();
+}
+
+// 2. Bootstrap the application
+Application.run('MyBasicApp', [
+  provideModule(main),
+  provideSignalHandler(), // Handles Ctrl+C (SIGINT) automatically
+]);
+```
+
+## 🔧 Advanced Topics
+
+### Class-Based Modules
+
+For long-running services or complex logic, define a class extending `Module`. This allows you to access the `CancellationSignal` to handle shutdown requests gracefully within your loops.
+
+```ts
+import { Application, provideModule, provideSignalHandler } from '@tstdl/base/application';
+import { CancellationSignal } from '@tstdl/base/cancellation';
+import { inject, Singleton } from '@tstdl/base/injector';
+import { Logger } from '@tstdl/base/logger';
+import { Module } from '@tstdl/base/module';
+import { cancelableTimeout } from '@tstdl/base/utils';
+
+@Singleton()
+export class WorkerModule extends Module {
+  readonly #logger = inject(Logger, WorkerModule.name);
+
+  constructor() {
+    super('Worker');
+  }
+
+  // The _run method is called when the application starts
+  protected override async _run(cancellationSignal: CancellationSignal): Promise<void> {
+    this.#logger.info('Worker started.');
+
+    // Loop until shutdown is requested
+    while (cancellationSignal.isUnset) {
+      this.#logger.info('Processing job...');
+
+      // Use cancelableTimeout to respect shutdown signals immediately during waits
+      const result = await cancelableTimeout(2000, cancellationSignal);
+
+      if (result == 'canceled') {
+        break;
+      }
+    }
+
+    this.#logger.info('Worker stopped gracefully.');
+  }
+}
+
+Application.run('WorkerApp', [provideModule(WorkerModule), provideSignalHandler()]);
+```
+
+### Initializers and Destructors
+
+Use these hooks to manage global resources like database connections.
+
+```ts
+import { Application, provideInitializer, provideDestructor, provideModule, provideSignalHandler } from '@tstdl/base/application';
+import { inject, injectAsync, Singleton } from '@tstdl/base/injector';
+import { Logger } from '@tstdl/base/logger';
+
+@Singleton()
+class DatabaseService {
+  readonly #logger = inject(Logger, 'Database');
+
+  async connect() {
+    this.#logger.info('Connected to DB');
+  }
+  async disconnect() {
+    this.#logger.info('Disconnected from DB');
+  }
+}
+
+// Initializer: Runs BEFORE modules start
+const initDb = async () => {
+  const db = await injectAsync(DatabaseService);
+  await db.connect();
+};
+
+// Destructor: Runs AFTER modules stop
+const closeDb = async () => {
+  const db = await injectAsync(DatabaseService);
+  await db.disconnect();
+};
+
+async function main() {
+  const logger = inject(Logger);
+  logger.info('App logic running with DB connection available.');
+}
+
+Application.run('DbApp', [provideInitializer(initDb), provideModule(main), provideDestructor(closeDb), provideSignalHandler()]);
+```
+
+### Programmatic Shutdown
+
+You can trigger the shutdown sequence from anywhere in your application by injecting the `Application` instance.
+
+```ts
+import { Application, provideModule } from '@tstdl/base/application';
+import { inject } from '@tstdl/base/injector';
+
+async function main() {
+  const app = inject(Application);
+
+  try {
+    // ... do critical work
+    throw new Error('Critical failure');
+  } catch (error) {
+    console.error(error);
+    // Trigger graceful shutdown
+    app.requestShutdown();
+  }
+}
+
+Application.run('ShutdownApp', [provideModule(main)]);
+```
+
+## 📚 API
+
+### Application Class
+
+The singleton instance managing the application lifecycle.
+
+| Property / Method   | Type                                                                   | Description                                                                                 |
+| :------------------ | :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
+| `static create()`   | `(name: string, providers: (ProvidersItem \| ProvidersItem[])[]) => Application` | Creates an application instance without starting it.                                        |
+| `static run()`      | `(name: string, providers: (ProvidersItem \| ProvidersItem[])[]) => Application` | Creates and immediately runs the application.                                               |
+| `shutdownSignal`    | `CancellationSignal`                                                   | The signal that indicates if the application is shutting down.                              |
+| `run()`             | `() => void`                                                  | Starts the application lifecycle (initializers -> modules).                                 |
+| `runAndWait()`      | `() => Promise<void>`                                         | Starts the application and returns a promise that resolves only after shutdown is complete. |
+| `requestShutdown()` | `() => void`                                                  | Signals the application to stop. Sets `shutdownSignal` and begins stopping modules.         |
+| `shutdown()`        | `() => Promise<void>`                                         | Requests shutdown and waits for the entire teardown process to complete.                    |
+| `waitForShutdown()` | `() => Promise<void>`                                         | Returns a promise that resolves when the application has fully stopped.                     |
+| `registerModule()`  | `(moduleType: Module \| Type<Module>) => void`                | Dynamically registers a module (mostly used internally or for advanced use cases).          |
+
+### Provider Functions
+
+Helper functions to configure the application in `Application.run()`.
+
+| Function                        | Description                                                                       |
+| :------------------------------ | :-------------------------------------------------------------------------------- |
+| `provideModule(...modules)`     | Registers one or more modules (functions or classes) to be run.                   |
+| `provideInitializer(fn)`        | Registers a function to run before modules start.                                 |
+| `provideDestructor(fn)`         | Registers a function to run after modules stop.                                   |
+| `provideSignalHandler()`        | Registers listeners for `SIGINT`, `SIGTERM`, etc., to trigger graceful shutdown.  |
+| `provideShutdownSignal(signal)` | Provides an external `CancellationSignal` to control the application's lifecycle. |
+
+### Injection Tokens
+
+Tokens used to resolve application-specific values.
+
+| Token                     | Type            | Description                                         |
+| :------------------------ | :-------------- | :-------------------------------------------------- |
+| `APPLICATION_NAME`        | `string`        | The name of the application passed to `run()`.      |
+| `APPLICATION_INSTANCE_ID` | `string`        | A unique UUID for the running application instance. |
+| `APPLICATION_MODULE`      | `Module`        | Used internally to collect registered modules.      |
+| `APPLICATION_INITIALIZER` | `InitializerFn` | Used internally to collect initializers.            |
+| `APPLICATION_DESTRUCTOR`  | `DestructorFn`  | Used internally to collect destructors.             |

package/application/application.js

@@ -27,7 +27,7 @@ let Application = Application_1 = class Application {
     #logger = inject(Logger, this.#name);
     #moduleTypesAndInstances = new Set(injectAll(APPLICATION_MODULE, undefined, { optional: true }));
     #shutdownPromise = new DeferredPromise();
-    #shutdownToken = inject(CancellationSignal, undefined, { optional: true })?.createChild() ?? new CancellationToken();
+    #shutdownToken = new CancellationToken(inject(CancellationSignal, undefined, { optional: true }));
     get injector() {
         return this.#injector;
     }
@@ -84,7 +84,7 @@ let Application = Application_1 = class Application {
             modules = await toArrayAsync(mapAsync(this.#moduleTypesAndInstances, async (instanceOrType) => (isFunction(instanceOrType) ? await this.#injector.resolveAsync(instanceOrType) : instanceOrType)));
             await Promise.race([
                 this.runModules(modules),
-                this.shutdownSignal,
+                this.shutdownSignal.wait(),
             ]);
         }
         catch (error) {

package/audit/README.md

@@ -0,0 +1,267 @@
+# Audit Module
+
+The Audit module provides a robust, structured, and type-safe system for logging audit events to a database. It is designed to record detailed information about actions performed within an application, supporting hierarchical module structures, contextual data enrichment, and change tracking.
+
+## Table of Contents
+
+1.  [✨ Features](#-features)
+2.  [Core Concepts](#core-concepts)
+    - [The Auditor Service](#the-auditor-service)
+    - [Module Hierarchy](#module-hierarchy)
+    - [Contextual Enrichment](#contextual-enrichment)
+    - [The Audit Event Model](#the-audit-event-model)
+3.  [🚀 Basic Usage](#-basic-usage)
+    - [Configuration](#configuration)
+    - [Logging Events](#logging-events)
+4.  [🔧 Advanced Topics](#-advanced-topics)
+    - [Hierarchical Auditors with `fork()`](#hierarchical-auditors-with-fork)
+    - [Contextual Logging with `with()`](#contextual-logging-with-with)
+    - [Correlation IDs](#correlation-ids)
+    - [Type-Safe Event Payloads](#type-safe-event-payloads)
+    - [Logging Data Changes](#logging-data-changes)
+5.  [📚 API](#-api)
+
+## ✨ Features
+
+- **Structured Persistence**: Events are stored in a dedicated database table with a standardized schema (`AuditEvent`).
+- **Modular Architecture**: Create hierarchical auditors (e.g., `user.auth.login`) to organize logs logically.
+- **Context Propagation**: Enrich auditors with context (Tenant ID, User ID, Request Info) that applies to all subsequent logs.
+- **Type Safety**: Define strict TypeScript interfaces for event payloads to ensure data consistency.
+- **Change Tracking**: Built-in support for recording `before` and `after` states of modified data.
+- **Correlation**: Trace related events across different services or modules using correlation IDs.
+- **Severity Levels**: Categorize events by severity (`Info`, `Warn`, `Error`, `Critical`) with automatic outcome handling.
+
+## Core Concepts
+
+### The Auditor Service
+
+The `Auditor` is the central injectable service. It is responsible for constructing the log entry and persisting it to the database.
+
+**Key Characteristics:**
+- **Immutability**: Methods like `fork()` or `with()` return new instances, allowing for safe concurrent usage in different contexts.
+- **Dependency Injection**: Can be injected with a module name string, a module path array, or a configuration object.
+- **Dual Logging**: Automatically writes to both the registered `Logger` and the database.
+
+```typescript
+// Injection examples
+const genericAuditor = inject(Auditor);
+const moduleAuditor = inject(Auditor, 'products');
+const pathAuditor = inject(Auditor, ['orders', 'shipping']);
+const configAuditor = inject(Auditor, { module: 'users', context: { tenantId: '...' } });
+```
+
+### Module Hierarchy
+
+Audit logs are organized by "modules". A module is a dot-separated string (e.g., `order-service.payment`). You can inject a root auditor and `fork` it to create sub-auditors, automatically appending to the module path.
+
+### Contextual Enrichment
+
+An `Auditor` can carry context—such as the current actor, tenant, or network details. When you call `auditor.with(context)`, you get a new auditor where that context is merged into every log entry. This removes the need to pass repetitive metadata to every log call.
+
+### The Audit Event Model
+
+Every log entry creates an `AuditEvent` record. This entity is stored in the `audit.event` table and captures:
+
+- **Identity**: `id` (UUID), `timestamp`, `tenantId`.
+- **Context**: `correlationId`, `module` (dot-separated path), `action`.
+- **Outcome & Severity**: `outcome` (Success, Failure, etc.) and `severity` (Info, Warn, etc.).
+- **Who**: `actorType`, `actor` (UUID), `impersonatorType`, `impersonator` (UUID).
+- **Target**: `targetType`, `targetId`.
+- **Environment**: `network` (embedded `RequestDetails` with IP, User Agent, Path, Session ID).
+- **Payload**: `changes` (embedded `ChangeDetails` with before/after state) and `details` (action-specific JSON data).
+
+## 🚀 Basic Usage
+
+### Configuration
+
+First, configure the audit module in your application's bootstrap phase. This sets up the database connection and runs necessary migrations.
+
+```typescript
+import { configureAudit, migrateAuditSchema } from '@tstdl/base/audit';
+import { runInInjectionContext } from '@tstdl/base/injector';
+import { DatabaseConfig } from '@tstdl/base/orm/server';
+
+// In your bootstrap function
+export async function bootstrap() {
+  // Configure the module
+  configureAudit({
+    // Optional: Provide specific DB config if different from global
+    database: new DatabaseConfig({ ... })
+  });
+
+  // Run migrations to create the 'audit.event' table
+  await runInInjectionContext(injector, migrateAuditSchema);
+}
+```
+
+### Logging Events
+
+Inject the `Auditor` and use the helper methods (`info`, `warn`, `error`) to log events.
+
+```typescript
+import { Auditor, ActorType } from '@tstdl/base/audit';
+import { inject, Singleton } from '@tstdl/base/injector';
+
+@Singleton()
+export class ProductService {
+  // Inject an auditor specifically for the 'products' module
+  private readonly auditor = inject(Auditor, 'products');
+
+  async deleteProduct(productId: string, userId: string): Promise<void> {
+    // ... business logic ...
+
+    // Log the action
+    await this.auditor.info('delete', {
+      actor: userId,
+      actorType: ActorType.Subject,
+      targetId: productId,
+      targetType: 'Product',
+      details: {
+        reason: 'User requested deletion',
+      },
+    });
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Hierarchical Auditors with `fork()`
+
+Use `fork()` to create specialized auditors for sub-features. This keeps your logs organized and traceable.
+
+```typescript
+import { Auditor } from '@tstdl/base/audit';
+import { inject } from '@tstdl/base/injector';
+
+const userAuditor = inject(Auditor, 'user-management');
+
+// Creates an auditor with module 'user-management.authentication'
+const authAuditor = userAuditor.fork('authentication');
+
+await authAuditor.info('login', {
+  /* ... */
+});
+```
+
+### Contextual Logging with `with()`
+
+In a request-handling context (like an API controller), create a scoped auditor that already knows _who_ is acting.
+
+```typescript
+import { Auditor, ActorType } from '@tstdl/base/audit';
+import { inject } from '@tstdl/base/injector';
+
+async function handleRequest(request: Request, user: User) {
+  const baseAuditor = inject(Auditor);
+
+  // Create a context-aware auditor
+  const requestAuditor = baseAuditor.with({
+    tenantId: user.tenantId,
+    actor: user.id,
+    actorType: ActorType.Subject,
+    network: {
+      ipAddress: request.ip,
+      userAgent: request.headers['user-agent'],
+      path: request.url,
+    },
+  });
+
+  // Now logs are clean and automatically enriched
+  await requestAuditor.info('view-dashboard', {
+    targetId: 'dashboard-1',
+    targetType: 'Dashboard',
+  });
+}
+```
+
+### Correlation IDs
+
+To trace a single logical operation across multiple services or modules, use `withCorrelation()`. If a correlation ID exists in the context, it is preserved; otherwise, a new one is generated.
+
+```typescript
+const traceAuditor = auditor.withCorrelation();
+
+await traceAuditor.info('step-1');
+// ... some operation ...
+await traceAuditor.info('step-2');
+// Both logs share the same correlationId
+```
+
+### Type-Safe Event Payloads
+
+You can enforce the structure of the `details` object for specific actions by providing a type definition to the `Auditor`.
+
+```typescript
+import { Auditor, ActorType } from '@tstdl/base/audit';
+
+// Define the contract: Action Name -> Details Object
+type UserEvents = {
+  create: { username: string; roles: string[] };
+  'update-password': { method: 'email' | 'sms' };
+};
+
+class UserService {
+  // Apply the type to the auditor
+  private readonly auditor = inject(Auditor, 'users').fork<UserEvents>('management');
+
+  async createUser(username: string, roles: string[]) {
+    await this.auditor.info('create', {
+      actorType: ActorType.System,
+      targetId: 'new-uuid',
+      targetType: 'User',
+      details: {
+        username,
+        roles,
+        // TypeScript enforces that 'username' and 'roles' are present and correct
+      },
+    });
+  }
+}
+```
+
+### Logging Data Changes
+
+The `changes` property allows you to persist the state of an entity before and after a modification.
+
+```typescript
+const oldProduct = await repo.load(id);
+const newProduct = { ...oldProduct, price: 200 };
+
+await auditor.info('update-price', {
+  targetId: id,
+  targetType: 'Product',
+  changes: {
+    before: oldProduct,
+    after: newProduct,
+  },
+});
+```
+
+## 📚 API
+
+| Export               | Type     | Description                                                        |
+| :------------------- | :------- | :----------------------------------------------------------------- |
+| `Auditor`            | Class    | The main service for logging. Can be typed with `Auditor<Events>`. |
+| `AuditEvent`         | Entity   | The ORM entity representing a single audit log record.             |
+| `AuditModuleConfig`  | Class    | Configuration class for the audit module (database settings).      |
+| `configureAudit`     | Function | Configures the audit module providers and settings.                |
+| `migrateAuditSchema` | Function | Runs database migrations for the audit schema.                     |
+| `ActorType`          | Enum     | `Anonymous`, `System`, `ApiKey`, `Subject`.                        |
+| `AuditOutcome`       | Enum     | `Pending`, `Success`, `Cancelled`, `Failure`, `Denied`.            |
+| `AuditSeverity`      | Enum     | `Info`, `Warn`, `Error`, `Critical`.                               |
+| `RequestDetails`     | Class    | Model for embedded network details (IP, Agent, Path, Session).     |
+| `ChangeDetails`      | Class    | Model for embedded `before` and `after` data snapshots.           |
+
+### Auditor Methods
+
+| Method                   | Description                                                                      |
+| :----------------------- | :------------------------------------------------------------------------------- |
+| `fork(subModule)`        | Returns a new `Auditor` with the sub-module appended to the current module path. |
+| `with(context)`          | Returns a new `Auditor` with the provided context merged.                        |
+| `withCorrelation()`      | Returns a new `Auditor` with a correlation ID set (generates one if missing).    |
+| `log(action, data)`      | Logs an event. Requires explicit `severity` and `outcome` in `data`.             |
+| `info(action, data)`     | Logs with `Severity.Info` and defaults outcome to `Success`.                     |
+| `warn(action, data)`     | Logs with `Severity.Warn` and defaults outcome to `Failure`.                     |
+| `error(action, data)`    | Logs with `Severity.Error` and defaults outcome to `Failure`.                    |
+| `critical(action, data)` | Logs with `Severity.Critical` and defaults outcome to `Failure`.                 |