@tstdl/base 0.93.139 → 0.93.141

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/mail/module.d.ts

@@ -1,3 +1,4 @@
+import { Injector } from '../injector/injector.js';
 import { type DatabaseConfig } from '../orm/server/index.js';
 import type { Type } from '../types/index.js';
 import { MailClient, MailClientConfig } from './mail.client.js';
@@ -7,9 +8,12 @@ export declare class MailModuleConfig {
     defaultClientConfig?: MailClientConfig;
     client?: Type<MailClient>;
     defaultData?: DefaultMailData;
+    autoMigrate?: boolean;
 }
 /**
  * configure mail module
  */
-export declare function configureMail(config: MailModuleConfig): void;
+export declare function configureMail({ injector, ...config }: MailModuleConfig & {
+    injector?: Injector;
+}): void;
 export declare function migrateMailSchema(): Promise<void>;

package/mail/module.js

@@ -1,6 +1,6 @@
 import { inject } from '../injector/index.js';
 import { Injector } from '../injector/injector.js';
-import { Database, migrate } from '../orm/server/index.js';
+import { Database, migrate, registerDatabaseMigration } from '../orm/server/index.js';
 import { isDefined } from '../utils/type-guards.js';
 import { MailClient, MailClientConfig } from './mail.client.js';
 import { MAIL_DEFAULT_DATA } from './tokens.js';
@@ -9,20 +9,25 @@ export class MailModuleConfig {
     defaultClientConfig;
     client;
     defaultData;
+    autoMigrate;
 }
 /**
  * configure mail module
  */
-export function configureMail(config) {
-    Injector.register(MailModuleConfig, { useValue: config });
+export function configureMail({ injector, ...config }) {
+    const targetInjector = injector ?? Injector;
+    targetInjector.register(MailModuleConfig, { useValue: config });
     if (isDefined(config.defaultClientConfig)) {
-        Injector.registerSingleton(MailClientConfig, { useValue: config.defaultClientConfig });
+        targetInjector.registerSingleton(MailClientConfig, { useValue: config.defaultClientConfig });
     }
     if (isDefined(config.client)) {
-        Injector.registerSingleton(MailClient, { useToken: config.client });
+        targetInjector.registerSingleton(MailClient, { useToken: config.client });
     }
     if (isDefined(config.defaultData)) {
-        Injector.registerSingleton(MAIL_DEFAULT_DATA, { useValue: config.defaultData });
+        targetInjector.registerSingleton(MAIL_DEFAULT_DATA, { useValue: config.defaultData });
+    }
+    if (config.autoMigrate != false) {
+        registerDatabaseMigration('Mail', migrateMailSchema, { injector });
     }
 }
 export async function migrateMailSchema() {