@tstdl/base 0.93.139 → 0.93.141

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`.                                   |

package/message-bus/README.md

@@ -0,0 +1,244 @@
+# Message Bus
+
+A flexible, RxJS-based message bus module for decoupled in-process and cross-context communication, designed for seamless integration with dependency injection.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Implementations](#implementations)
+  - [Message Observables](#message-observables)
+- [🚀 Basic Usage](#-basic-usage)
+  - [1. Configuration](#1-configuration)
+  - [2. Injection & Usage](#2-injection--usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Cross-Context Communication (BroadcastChannel)](#cross-context-communication-broadcastchannel)
+  - [Fire and Forget](#fire-and-forget)
+  - [Resource Management](#resource-management)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Decoupled Communication**: Enables components to communicate via named channels without direct references.
+- **Reactive Architecture**: Built on **RxJS**, providing powerful operators for filtering and transforming message streams.
+- **Dual Modes & Cross-Platform**:
+  - **Local**: High-performance in-memory communication using RxJS Subjects.
+  - **BroadcastChannel**: Cross-context communication (tabs, windows, workers) using the standard Web API.
+- **DI Integration**: Implements `Resolvable`, allowing direct injection with channel names as arguments.
+- **Type Safety**: Fully supports generic types for message payloads.
+- **Smart Filtering**: Distinguishes between messages from _other_ instances and _all_ messages (including self).
+- **Memory Safe**: Implements `AsyncDisposable` for proper cleanup of subscriptions and channels. Uses `WeakRefMap` internally to prevent memory leaks on unused channels.
+
+## Core Concepts
+
+### Implementations
+
+The module provides two strategies, selectable via configuration at application startup:
+
+1.  **`LocalMessageBus`**:
+    - **Scope**: Single JavaScript environment (e.g., one browser tab, one Node.js process).
+    - **Mechanism**: Shared RxJS `Subject`.
+    - **Use Case**: Component-to-component communication, global event bus within an app.
+
+2.  **`BroadcastChannelMessageBus`**:
+    - **Scope**: Same-origin browsing contexts (e.g., multiple tabs, iframes, workers).
+    - **Mechanism**: Wraps the `BroadcastChannel` API.
+    - **Use Case**: Synchronizing state across tabs (e.g., logout in one tab affects all others).
+
+### Message Observables
+
+Every `MessageBus` instance exposes two streams to handle different scenarios:
+
+- **`messages$`**: Emits messages published by **other** instances on the same channel. It filters out messages sent by _this_ specific instance. Use this to react to external events.
+- **`allMessages$`**: Emits **every** message on the channel, including those published by _this_ instance. Use this for logging, global state updates, or UI synchronization that must reflect local actions immediately.
+
+## 🚀 Basic Usage
+
+### 1. Configuration
+
+Register the desired implementation provider in your application bootstrap.
+
+**For in-process communication (Local):**
+
+```typescript
+import { configureLocalMessageBus } from '@tstdl/base/message-bus';
+
+// In your bootstrap/main file
+configureLocalMessageBus();
+```
+
+### 2. Injection & Usage
+
+Inject the `MessageBus` by passing the channel name as the argument.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { MessageBus } from '@tstdl/base/message-bus';
+
+// 1. Define your message type
+type UserCreatedEvent = { id: string; email: string };
+
+export class UserService {
+  // 2. Inject the bus for a specific channel ('user-events')
+  private readonly userBus = inject(MessageBus<UserCreatedEvent>, 'user-events');
+
+  async createUser(email: string) {
+    const id = '123';
+    // ... creation logic ...
+
+    // 3. Publish a message
+    await this.userBus.publish({ id, email });
+  }
+}
+
+export class NotificationService {
+  private readonly userBus = inject(MessageBus<UserCreatedEvent>, 'user-events');
+
+  constructor() {
+    // 4. Subscribe to messages
+    this.userBus.messages$.subscribe((event) => {
+      console.log(`New user created: ${event.email}`);
+    });
+  }
+}
+```
+
+### 3. Alternative: Manual Resolution
+
+If you're not using dependency injection for a specific class or need to resolve a channel dynamically, use the `MessageBusProvider`.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { MessageBusProvider } from '@tstdl/base/message-bus';
+
+const provider = inject(MessageBusProvider);
+const bus = provider.get<string>('dynamic-channel');
+
+await bus.publish('Hello world');
+```
+
+## 🔧 Advanced Topics
+
+### Reactive Patterns
+
+Since `MessageBus` is built on RxJS, you can use any operators to handle your message streams.
+
+```typescript
+import { filter, bufferTime } from 'rxjs';
+
+// Only handle specific events
+this.userBus.messages$.pipe(
+  filter(event => event.email.endsWith('@example.com'))
+).subscribe(event => { ... });
+
+// Batch events for processing
+this.userBus.messages$.pipe(
+  bufferTime(1000),
+  filter(batch => batch.length > 0)
+).subscribe(batch => {
+  console.log(`Processed ${batch.length} events this second.`);
+});
+```
+
+### Cross-Context Communication (BroadcastChannel)
+
+To enable communication between different tabs or windows (browsers) or between multiple workers/processes (Node.js), use the `BroadcastChannel` configuration.
+
+```typescript
+import { configureBroadcastChannelMessageBus } from '@tstdl/base/message-bus';
+
+// Use this instead of configureLocalMessageBus
+configureBroadcastChannelMessageBus();
+```
+
+> **Note:** `BroadcastChannel` is natively supported in modern browsers and Node.js 18+. For older environments, a polyfill may be required.
+
+### Custom Injector Configuration
+
+When configuring the `LocalMessageBus`, you can optionally specify which injector to use. This is useful in complex setups or when using multiple containers.
+
+```typescript
+import { configureLocalMessageBus } from '@tstdl/base/message-bus';
+import { myCustomInjector } from './my-context';
+
+configureLocalMessageBus({ injector: myCustomInjector });
+```
+
+**Example: Logout Synchronization**
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { MessageBus } from '@tstdl/base/message-bus';
+
+type AuthEvent = { type: 'logout' };
+
+class AuthService {
+  private readonly authBus = inject(MessageBus<AuthEvent>, 'auth');
+
+  async logout() {
+    // Perform logout
+    await this.authBus.publish({ type: 'logout' });
+    window.location.reload();
+  }
+
+  listenForExternalLogout() {
+    // 'messages$' only emits if *another* tab publishes the event
+    this.authBus.messages$.subscribe((event) => {
+      if (event.type === 'logout') {
+        console.log('Logout triggered in another tab.');
+        window.location.reload();
+      }
+    });
+  }
+}
+```
+
+### Fire and Forget
+
+The standard `publish` method returns a `Promise` that resolves when the message has been dispatched (e.g., posted to the BroadcastChannel). If you do not need to wait for this, use `publishAndForget`.
+
+```typescript
+// Non-blocking publish
+this.messageBus.publishAndForget({ type: 'ping' });
+```
+
+### Resource Management
+
+`MessageBus` implements `AsyncDisposable`. When a bus is no longer needed, it should be disposed to close underlying channels (like `BroadcastChannel`) and complete internal subjects.
+
+If you are using the dependency injection system with scoped providers, this is handled automatically. If you create instances manually or hold them in long-lived services, ensure you dispose of them.
+
+```typescript
+await bus[Symbol.asyncDispose]();
+```
+
+## 📚 API
+
+### Classes & Interfaces
+
+| Name                                  | Description                                           |
+| :------------------------------------ | :---------------------------------------------------- |
+| `MessageBus<T>`                       | Abstract base class for a message bus instance.       |
+| `MessageBusBase<T>`                   | Helper class for implementing custom message buses.   |
+| `MessageBusProvider`                  | Abstract factory for creating `MessageBus` instances. |
+| `LocalMessageBus<T>`                  | Implementation for in-process communication.          |
+| `LocalMessageBusProvider`             | Provider implementation for `LocalMessageBus`.        |
+| `BroadcastChannelMessageBus<T>`       | Implementation for cross-context communication.       |
+| `BroadcastChannelMessageBusProvider` | Provider implementation for `BroadcastChannelMessageBus`. |
+
+### `MessageBus<T>` Members
+
+| Member                      | Type            | Description                                  |
+| :-------------------------- | :-------------- | :------------------------------------------- |
+| `messages$`                 | `Observable<T>` | Stream of messages from **other** instances. |
+| `allMessages$`              | `Observable<T>` | Stream of **all** messages (including self). |
+| `publish(message)`          | `Promise<void>` | Publishes a message asynchronously.          |
+| `publishAndForget(message)` | `void`          | Publishes a message without waiting.         |
+| `dispose()`                 | `Promise<void>` | Manually disposes the bus.                   |
+
+### Configuration Functions
+
+| Function                                | Description                                                           |
+| :-------------------------------------- | :-------------------------------------------------------------------- |
+| `configureLocalMessageBus()`            | Registers `LocalMessageBus` as the default implementation.            |
+| `configureBroadcastChannelMessageBus()` | Registers `BroadcastChannelMessageBus` as the default implementation. |

package/message-bus/message-bus-base.js

@@ -13,7 +13,7 @@ export class MessageBusBase extends MessageBus {
         this.logger = logger;
         this.publishSubject = new Subject();
         this.disposeToken = new CancellationToken();
-        this.messages$ = defer(() => this._messages$).pipe(takeUntil(this.disposeToken.set$), share());
+        this.messages$ = defer(() => this._messages$).pipe(takeUntil(this.disposeToken), share());
         this.allMessages$ = merge(this.messages$, this.publishSubject);
     }
     publishAndForget(message) {

package/module/README.md

@@ -0,0 +1,182 @@
+# Application Modules
+
+The `@tstdl/base/module` library provides a robust framework for building modular applications with managed lifecycles. It defines a standard contract for components that need to be started, monitored, and gracefully stopped, such as background workers, API servers, or custom services.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [The Module Class](#the-module-class)
+  - [Lifecycle States](#lifecycle-states)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Creating a Custom Module](#creating-a-custom-module)
+  - [Manual Execution](#manual-execution)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [FunctionModule](#functionmodule)
+  - [WebServerModule](#webservermodule)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Standardized Lifecycle**: Uniform `run()` and `stop()` methods for all application components.
+- **State Management**: Built-in tracking of module states (`Running`, `Stopping`, `Stopped`, `Erroneous`).
+- **Graceful Shutdown**: Integrated `CancellationSignal` support for clean resource cleanup.
+- **Resource Management**: Implemented `AsyncDisposable` for automatic cleanup when using the `using` keyword.
+- **Ready-to-Use Modules**: Includes pre-built modules for common tasks like running functions or web servers.
+- **Type Safety**: Fully typed with TypeScript for reliable development.
+
+## Core Concepts
+
+### The Module Class
+
+The abstract `Module` class is the foundation of this library. It handles the internal state machine and synchronization required to start and stop services safely.
+
+When you extend `Module`, you implement a single protected method: `_run(cancellationSignal)`. This method contains your main logic. The base class ensures that `_run` is called only when the module is stopped and handles the propagation of the cancellation signal when `stop()` is called.
+
+### Lifecycle States
+
+A module is always in one of the following states, defined by the `ModuleState` enum:
+
+1.  **Stopped**: The initial state. The module is ready to run.
+2.  **Running**: The `_run` method is currently executing.
+3.  **Stopping**: A stop has been requested, and the cancellation signal has been triggered, but the `_run` promise has not yet resolved.
+4.  **Erroneous**: The module threw an unhandled exception during execution.
+
+## 🚀 Basic Usage
+
+### Creating a Custom Module
+
+To create a module, extend the `Module` class and implement the `_run` method. Use the provided `CancellationSignal` to detect when the module should stop.
+
+```typescript
+import { CancellationSignal } from '@tstdl/base/cancellation';
+import { Module } from '@tstdl/base/module';
+import { cancelableTimeout } from '@tstdl/base/utils';
+
+export class DataProcessorModule extends Module {
+  constructor() {
+    super('DataProcessor');
+  }
+
+  protected async _run(cancellationSignal: CancellationSignal): Promise<void> {
+    console.log('DataProcessor started.');
+
+    // Run a loop until the signal is set (stop requested)
+    while (cancellationSignal.isUnset) {
+      console.log('Processing data batch...');
+
+      // Simulate work that can be cancelled
+      await cancelableTimeout(1000, cancellationSignal);
+    }
+
+    console.log('DataProcessor stopping gracefully.');
+  }
+}
+```
+
+### Manual Execution
+
+While modules are often managed by an `Application` runner (from `@tstdl/base/application`), you can run them manually.
+
+```typescript
+import { DataProcessorModule } from './data-processor.module.js';
+import { timeout } from '@tstdl/base/utils';
+
+async function main() {
+  const module = new DataProcessorModule();
+
+  // Start the module (non-blocking)
+  const runPromise = module.run();
+
+  console.log(`Module state: ${module.state}`); // Running
+
+  // Let it run for a bit
+  await timeout(3000);
+
+  // Stop the module
+  console.log('Stopping module...');
+  await module.stop();
+
+  // Wait for the run promise to complete to ensure cleanup is done
+  await runPromise;
+
+  console.log(`Module state: ${module.state}`); // Stopped
+}
+
+main();
+```
+
+## 🔧 Advanced Topics
+
+### FunctionModule
+
+The `FunctionModule` is a generic wrapper that allows you to treat a simple asynchronous function as a full-fledged module. This is useful for simple background tasks or scripts that don't require a dedicated class.
+
+It is typically used in conjunction with the dependency injection system or the `Application` runner (from `@tstdl/base/application`), which handles the instantiation and argument injection.
+
+```typescript
+import { Application, provideModule } from '@tstdl/base/application';
+import { CancellationSignal } from '@tstdl/base/cancellation';
+
+async function myTask(signal: CancellationSignal) {
+  console.log('Function module running');
+
+  while (signal.isUnset) {
+    // ... logic
+    await timeout(1000);
+  }
+}
+
+// Run the task as a module within an application
+Application.run('MyApplication', [
+  provideModule(myTask)
+]);
+```
+
+### WebServerModule
+
+The `WebServerModule` is a specialized module that integrates with `@tstdl/base/http` and `@tstdl/base/api` to run an HTTP server. It automatically registers API controllers and handles the server lifecycle.
+
+It is designed to be used with the Dependency Injection system.
+
+**Configuration:**
+
+You can configure the port using `configureWebServerModule`.
+
+```typescript
+import { configureWebServerModule, WebServerModule } from '@tstdl/base/module';
+import { Application, provideModule } from '@tstdl/base/application';
+import { configureNodeHttpServer } from '@tstdl/base/http/node';
+import { configureApiServer } from '@tstdl/base/api/server';
+
+// 1. Configure the environment
+function bootstrap() {
+  configureNodeHttpServer(); // Select Node.js HTTP implementation
+  configureApiServer({
+    controllers: [
+      /* ... your controllers ... */
+    ],
+  });
+
+  // Configure the WebServerModule specific settings
+  configureWebServerModule({ port: 8080 });
+}
+
+// 2. Run the application with the WebServerModule
+Application.run('MyApiServer', [
+  provideModule(WebServerModule),
+  // ... other providers
+]);
+```
+
+## 📚 API
+
+| Type         | Name                           | Description                                                                                                  |
+| :----------- | :----------------------------- | :----------------------------------------------------------------------------------------------------------- |
+| **Class**    | `Module`                       | Abstract base class for all modules. Handles state transitions and cancellation signals. Also implements `AsyncDisposable`. |
+| **Enum**     | `ModuleState`                  | Enumeration of module states: `Running`, `Stopping`, `Stopped`, `Erroneous`.                                 |
+| **Class**    | `FunctionModule`               | A generic module implementation that executes a provided function.                                           |
+| **Type**     | `FunctionModuleFunction`       | Signature for functions used with `FunctionModule`: `(signal: CancellationSignal) => void \| Promise<void>`. |
+| **Class**    | `WebServerModule`              | A module that runs an HTTP server and serves registered API controllers.                                     |
+| **Type**     | `WebServerModuleConfiguration` | Configuration object for `WebServerModule` (e.g., `{ port: number }`).                                       |
+| **Function** | `configureWebServerModule`     | Helper function to set the global configuration for the `WebServerModule`.                                   |

package/module/module.d.ts

@@ -11,7 +11,7 @@ export type ModuleState = EnumType<typeof ModuleState>;
 export declare abstract class Module implements AsyncDisposable {
     private runPromise;
     private _state;
-    protected readonly cancellationToken: CancellationToken;
+    protected cancellationToken: CancellationToken;
     readonly name: string;
     get state(): ModuleState;
     private get stateString();