@tstdl/base 0.93.36 → 0.93.38

package/source/application/providers.ts

@@ -1,68 +0,0 @@
-import { CancellationSignal } from '#/cancellation/index.js';
-import { inject, type ProvidersItem } from '#/injector/index.js';
-import { Logger } from '#/logger/index.js';
-import { FunctionModule, Module, type FunctionModuleFunction } from '#/module/index.js';
-import type { Constructor, OneOrMany, Type } from '#/types/index.js';
-import { isFunction } from '#/utils/type-guards.js';
-import { typeExtends } from '#/utils/type/index.js';
-import { Application, APPLICATION_DESTRUCTOR, APPLICATION_INITIALIZER, APPLICATION_MODULE, type DestructorFn, type InitializerFn } from './application.js';
-
-type Signal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGBREAK';
-type QuitEvent = 'uncaughtException' | 'multipleResolves' | 'unhandledRejection' | 'rejectionHandled';
-
-const quitSignals: Signal[] = ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGBREAK'];
-const quitEvents: QuitEvent[] = ['uncaughtException', 'unhandledRejection', 'rejectionHandled'];
-
-export function provideModule(...functionsAndModules: OneOrMany<FunctionModuleFunction | Type<Module>>[]): ProvidersItem[] {
-  return functionsAndModules.flat().map((fnOrModule): ProvidersItem => {
-    if (typeExtends(fnOrModule as Constructor, Module)) {
-      return { provide: APPLICATION_MODULE, useValue: fnOrModule as Type<Module>, multi: true };
-    }
-    else if (isFunction(fnOrModule)) {
-      return { provide: APPLICATION_MODULE, useToken: FunctionModule, defaultArgument: fnOrModule, multi: true };
-    }
-    else {
-      throw new TypeError('Invalid module or function provided to provideModules');
-    }
-  });
-}
-
-export function provideInitializer(fn: InitializerFn): ProvidersItem {
-  return { provide: APPLICATION_INITIALIZER, useValue: fn, multi: true };
-}
-
-export function provideDestructor(fn: DestructorFn): ProvidersItem {
-  return { provide: APPLICATION_DESTRUCTOR, useValue: fn, multi: true };
-}
-
-export function provideShutdownSignal(signal: CancellationSignal): ProvidersItem {
-  return { provide: CancellationSignal, useValue: signal };
-}
-
-export function provideSignalHandler(): ProvidersItem {
-  let signalCounter = 0;
-
-  return provideInitializer(() => {
-    const application = inject(Application);
-    const logger = inject(Logger);
-
-    for (const event of quitEvents) {
-      process.on(event, (...args: any[]) => {
-        logger.error(`QuitEvent occurred: ${event}`, { details: args });
-        application.requestShutdown();
-      });
-    }
-
-    for (const quitSignal of quitSignals) {
-      process.on(quitSignal, (signal) => {
-        logger.info(`${signal} received, quitting.`);
-        application.requestShutdown();
-
-        if (++signalCounter > 1) {
-          logger.warn('Forcefully quitting due to multiple signals...');
-          setTimeout(() => process.exit(1), 1);
-        }
-      });
-    }
-  });
-}

package/source/audit/README.md

@@ -1,272 +0,0 @@
-# Audit Module
-
-The Audit module provides a robust and flexible system for logging audit events. It is designed to record detailed information about actions performed within an application, which is essential for security analysis, compliance, debugging, and understanding user behavior.
-
-### Table of Contents
-
-1.  [Features](#features)
-2.  [Core Concepts](#core-concepts)
-    - [The Auditor Service](#the-auditor-service)
-    - [Module Hierarchy with `fork()`](#module-hierarchy-with-fork)
-    - [Contextual Logging with `with()`](#contextual-logging-with-with)
-    - [Typed Event Payloads](#typed-event-payloads)
-    - [The `AuditEvent` Model](#the-auditevent-model)
-3.  [Usage](#usage)
-    - [Basic Setup](#basic-setup)
-    - [Basic Logging](#basic-logging)
-    - [Creating Sub-Auditors with `fork()`](#creating-sub-auditors-with-fork)
-    - [Adding Context with `with()`](#adding-context-with-with)
-    - [Using Severity-Based Helpers](#using-severity-based-helpers)
-    - [Logging Data Changes](#logging-data-changes)
-    - [Typed Event Payloads](#typed-event-payloads-1)
-4.  [API Summary](#api-summary)
-
-## Features
-
--   **Structured Logging**: Events are stored in a structured format (`AuditEvent` model) with detailed metadata.
--   **Modular Design**: Create hierarchical auditors for different parts of your application using `fork()`.
--   **Contextual Enrichment**: Enrich logs with contextual data (e.g., tenant ID, user ID, request details) using `with()`.
--   **Typed Payloads**: Define types for event-specific `details` payloads for enhanced type safety.
--   **Severity Levels**: Log events with different severity levels (`Info`, `Warn`, `Error`, `Critical`).
--   **Correlation IDs**: Group related events across different modules with a shared correlation ID.
--   **Database Persistence**: Audit events are stored in a dedicated database schema.
-
-## Core Concepts
-
-### The Auditor Service
-
-The `Auditor` is the central service for logging events. It is an injectable class that you can use anywhere in your application. You can create a root-level auditor and then create more specific auditors for different modules.
-
-### Module Hierarchy with `fork()`
-
-The `auditor.fork()` method allows you to create a new `Auditor` instance for a submodule. The new auditor inherits its parent's context and automatically prefixes its logs with the parent's module path. This helps organize logs and trace event origins easily.
-
-For example, an auditor for `users` can be forked to create an auditor for `users.authentication`.
-
-### Contextual Logging with `with()`
-
-The `auditor.with()` method creates a new auditor instance with additional context that will be applied to all events it logs. This is extremely useful for adding request-scoped information, such as the current user's ID, tenant ID, or network details, without having to pass them to every log call.
-
-### Typed Event Payloads
-
-For improved type safety, you can define an interface or type that maps action names to their `details` payload shape. By providing this type as a generic argument to the `Auditor`, TypeScript will enforce the correct payload structure for each action.
-
-### The `AuditEvent` Model
-
-Every log entry creates an `AuditEvent` record. This model captures comprehensive information:
-
--   **Who**: `actor`, `actorType`, and optional `impersonator`.
--   **What**: `module`, `action`, `outcome`, and `severity`.
--   **When**: `timestamp`.
--   **Target**: `targetId` and `targetType` of the entity being acted upon.
--   **Context**: `tenantId`, `correlationId`, and network details (`ipAddress`, `userAgent`).
--   **Changes**: `changes` field to store the state of data `before` and `after` a modification.
--   **Details**: A flexible `details` JSON field for any other action-specific data.
-
-## Usage
-
-### Basic Setup
-
-First, configure the audit module in your application's bootstrap file.
-
-```typescript
-import { configureAuditServer, migrateAuditSchema } from '@tstdl/base/audit/server';
-import { runInInjectionContext } from '@tstdl/base/injector';
-
-// In your bootstrap function
-configureAuditServer({});
-
-// After ORM is configured, run migrations
-await runInInjectionContext(injector, migrateAuditSchema);
-```
-
-### Basic Logging
-
-Inject the `Auditor` and use its logging methods.
-
-```typescript
-import { inject } from '@tstdl/base/injector';
-import { Auditor, ActorType, AuditOutcome, AuditSeverity } from '@tstdl/base/audit';
-
-class ProductService {
-  private readonly auditor = inject(Auditor, 'products');
-
-  async deleteProduct(productId: string, actorId: string): Promise<void> {
-    // ... deletion logic ...
-
-    await this.auditor.log('delete', {
-      actorId: actorId,
-      actorType: ActorType.User,
-      targetId: productId,
-      targetType: 'Product',
-      outcome: AuditOutcome.Success,
-      severity: AuditSeverity.Info,
-    });
-  }
-}
-```
-
-### Creating Sub-Auditors with `fork()`
-
-Organize your logs by creating specialized auditors for different features.
-
-```typescript
-import { inject } from '@tstdl/base/injector';
-import { Auditor } from '@tstdl/base/audit';
-
-// A base auditor for the entire user management feature
-const userManagementAuditor = inject(Auditor, 'user-management');
-
-// A more specific auditor for authentication-related events
-const authAuditor = userManagementAuditor.fork('authentication');
-
-// This will log with module 'user-management.authentication'
-await authAuditor.info('login', {
-  // ... event data
-});
-```
-
-### Adding Context with `with()`
-
-Create request-scoped auditors to automatically include contextual data.
-
-```typescript
-import { Auditor, ActorType, AuditOutcome, AuditSeverity } from '@tstdl/base/audit';
-import { inject } from '@tstdl/base/injector';
-
-// In your API controller or middleware
-async function handleRequest(request: Request) {
-  const rootAuditor = inject(Auditor);
-  const actorId = 'user-uuid-123';
-  const tenantId = 'tenant-uuid-456';
-
-  // Create an auditor with request-specific context
-  const requestAuditor = rootAuditor.with({
-    actorId,
-    tenantId,
-    actorType: ActorType.User,
-    network: {
-      ipAddress: request.ip,
-      userAgent: request.headers['user-agent'],
-      sessionId: null
-    }
-  });
-
-  // Now, any event logged with `requestAuditor` will include this context.
-  await requestAuditor.info('view-dashboard', {
-    targetId: 'dashboard-uuid',
-    targetType: 'Dashboard'
-  });
-}
-```
-
-### Using Severity-Based Helpers
-
-Use convenient helper methods for different severity levels.
-
-```typescript
-// `info()` sets severity to 'Info' and outcome to 'Success' by default.
-await auditor.info('view-product', {
-  actorId: 'user-1',
-  actorType: ActorType.User,
-  targetId: 'product-123',
-  targetType: 'Product'
-});
-
-// `warn()` sets severity to 'Warn' and outcome to 'Failure' by default.
-await auditor.warn('update-settings', {
-  actorId: 'user-1',
-  actorType: ActorType.User,
-  targetId: 'settings-123',
-  targetType: 'Settings',
-  details: { reason: 'Invalid value for timezone.' }
-});
-
-// `error()` sets severity to 'Error' and outcome to 'Failure' by default.
-await auditor.error('payment-failed', {
-  actorId: 'user-1',
-  actorType: ActorType.User,
-  targetId: 'order-456',
-  targetType: 'Order',
-  details: { gatewayError: 'Insufficient funds' }
-});
-```
-
-### Logging Data Changes
-
-Record the state of an entity before and after a modification.
-
-```typescript
-const productBefore = await productRepository.load(productId);
-
-const productAfter = await productRepository.update(productId, { price: 19.99 });
-
-await auditor.info('update-price', {
-  actorId: 'admin-1',
-  actorType: ActorType.User,
-  targetId: productId,
-  targetType: 'Product',
-  changes: {
-    before: productBefore,
-    after: productAfter
-  }
-});
-```
-
-### Typed Event Payloads
-
-Enforce type safety for your custom `details` payloads.
-
-```typescript
-import { Auditor, ActorType, AuditOutcome } from '@tstdl/base/audit';
-import { inject } from '@tstdl/base/injector';
-
-// 1. Define the types for your event details
-type UserEvents = {
-  'create': { username: string, roles: string[] };
-  'delete': { reason: string };
-  'login': { from: 'web' | 'mobile' };
-};
-
-class UserService {
-  // 2. Use the type with the Auditor
-  private readonly auditor = inject(Auditor, 'users').fork<UserEvents>('management');
-
-  async createUser(username: string, roles: string[]): Promise<void> {
-    // ... user creation logic ...
-
-    // 3. Get full type-safety on the 'details' payload
-    await this.auditor.info('create', {
-      actorId: 'system-uuid',
-      actorType: ActorType.System,
-      targetId: 'new-user-uuid',
-      targetType: 'User',
-      details: {
-        username, // TypeScript knows `username` is a string
-        roles     // and `roles` is a string[]
-      }
-    });
-
-    // This would cause a TypeScript error:
-    // await this.auditor.info('create', { details: { wrongKey: 'value' } });
-  }
-}
-```
-
-## API Summary
-
-| Class / Function              | Description                                                                                               |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `Auditor<Events>`             | The main service for logging audit events. Can be typed with an `Events` map for payload safety.            |
-| `auditor.fork(module)`        | Creates a new `Auditor` for a submodule, inheriting context.                                              |
-| `auditor.with(context)`       | Creates a new `Auditor` with additional context merged into all subsequent events.                        |
-| `auditor.log(action, data)`   | Logs a generic audit event with a specified `action` and `data`.                                          |
-| `auditor.info(action, data)`  | Logs an event with `Info` severity and `Success` outcome.                                                 |
-| `auditor.warn(action, data)`  | Logs an event with `Warn` severity and `Failure` outcome.                                                 |
-| `auditor.error(action, data)` | Logs an event with `Error` severity and `Failure` outcome.                                                |
-| `AuditEvent`                  | The ORM entity representing a single audit log entry in the database.                                     |
-| `configureAuditServer(config)`| Configures the audit module, optionally with a dedicated database connection.                             |
-| `migrateAuditSchema()`        | Applies database migrations for the audit module schema.                                                  |
-| `ActorType` (Enum)            | Defines the type of actor (`User`, `System`, `ApiKey`).                                                   |
-| `AuditOutcome` (Enum)         | Defines the outcome of an action (`Success`, `Failure`, `Denied`, etc.).                                  |
-| `AuditSeverity` (Enum)        | Defines the severity of an event (`Info`, `Warn`, `Error`, `Critical`).                                   |

package/source/audit/audit.model.ts

@@ -1,161 +0,0 @@
-import { type Embedded, EmbeddedProperty, EntityWithoutMetadata, type Json, JsonProperty, Table, type Timestamp, TimestampProperty, type Uuid, UuidProperty } from '#/orm/index.js';
-import { Enumeration, StringProperty } from '#/schema/index.js';
-import type { UndefinableJsonObject } from '#/types/index.js';
-import { ActorType, AuditOutcome, AuditSeverity } from './types.js';
-
-/**
- * Represents the network details of the request that triggered the audit event.
- */
-export class RequestDetails {
-  /**
-   * The path of the request.
-   * @example '/api/v1/users/xyz'
-   */
-  @StringProperty()
-  path: string | null;
-
-  /**
-   * The IP address of the client.
-   * @example '192.168.1.100'
-   */
-  @StringProperty({ nullable: true })
-  ipAddress: string | null;
-
-  /**
-   * The user agent string of the client.
-   * @example 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...'
-   */
-  @StringProperty({ nullable: true })
-  userAgent: string | null;
-
-  /**
-   * The session ID associated with the request, if any.
-   */
-  @UuidProperty({ nullable: true })
-  sessionId: Uuid | null;
-}
-
-/**
- * Represents the state of data before and after a change.
- */
-export class ChangeDetails {
-  /**
-   * The state of the data before the change occurred.
-   */
-  @JsonProperty({ nullable: true })
-  before: Json<unknown> | null;
-
-  /**
-   * The state of the data after the change occurred.
-   */
-  @JsonProperty({ nullable: true })
-  after: Json<unknown> | null;
-}
-
-/**
- * Represents a single audit event record in the database.
- * This entity captures who did what, when, and to what, along with other contextual information.
- *
- * @template Details The type of the `details` JSON object, allowing for custom, action-specific data.
- */
-@Table({ name: 'event' })
-export class AuditEvent<Details extends UndefinableJsonObject = UndefinableJsonObject> extends EntityWithoutMetadata {
-  /**
-   * The timestamp when the event occurred.
-   */
-  @TimestampProperty()
-  timestamp: Timestamp;
-
-  /**
-   * The ID of the tenant in which the event occurred. Can be null for system-level events.
-   */
-  @UuidProperty({ nullable: true })
-  tenantId: Uuid | null;
-
-  /**
-   * A unique identifier to correlate multiple related audit events.
-   */
-  @UuidProperty({ nullable: true })
-  correlationId: Uuid | null;
-
-  /**
-   * The module or feature area where the event originated, in dot-separated format.
-   * @example 'user.authentication'
-   */
-  @StringProperty()
-  module: string;
-
-  /**
-   * The specific action that was performed.
-   * @example 'login'
-   */
-  @StringProperty()
-  action: string;
-
-  /**
-   * The outcome of the action.
-   */
-  @Enumeration(AuditOutcome)
-  outcome: AuditOutcome;
-
-  /**
-   * The severity level of the event.
-   */
-  @Enumeration(AuditSeverity)
-  severity: AuditSeverity;
-
-  /**
-   * The type of the actor.
-   */
-  @Enumeration(ActorType)
-  actorType: ActorType;
-
-  /**
-   * The (if possible unique) identifier of the actor who performed the action.
-   */
-  @StringProperty()
-  actor: string | null;
-
-  /**
-   * The type of the impersonator, if applicable.
-   */
-  @Enumeration(ActorType, { nullable: true })
-  impersonatorType: ActorType | null;
-
-  /**
-   * The (if possible unique) identifier of the user who is impersonating the actor, if applicable.
-   */
-  @StringProperty({ nullable: true })
-  impersonator: string | null;
-
-  /**
-   * The type of the target entity.
-   * @example 'User'
-   */
-  @StringProperty()
-  targetType: string;
-
-  /**
-   * The unique identifier of the primary resource or entity that was the target of the action.
-   */
-  @UuidProperty()
-  targetId: Uuid;
-
-  /**
-   * Network-related details for the request that triggered the event.
-   */
-  @EmbeddedProperty(RequestDetails)
-  network: Embedded<RequestDetails> | null;
-
-  /**
-   * Details about data changes.
-   */
-  @EmbeddedProperty(ChangeDetails)
-  changes: Embedded<ChangeDetails> | null;
-
-  /**
-   * A flexible JSON object for storing additional, action-specific details.
-   */
-  @JsonProperty({ nullable: true })
-  details: Json<Details> | null;
-}