@tstdl/base 0.93.139 → 0.93.141

package/decorators/README.md

@@ -0,0 +1,140 @@
+# Decorators
+
+A collection of TypeScript decorators to enhance classes and methods with declarative behavior. Currently provides a robust logging decorator for tracing method execution, arguments, and return values.
+
+## Table of Contents
+
+- [Features](#-features)
+- [Core Concepts](#core-concepts)
+- [Basic Usage](#-basic-usage)
+- [Advanced Topics](#-advanced-topics)
+- [API](#-api)
+
+## ✨ Features
+
+- **Method Logging**: Decorate individual methods to log their execution.
+- **Class Logging**: Decorate an entire class to automatically log all its methods.
+- **Configurable**: Customize what gets logged (arguments, return values, errors, execution time).
+- **Smart Application**: Prevents double-wrapping if a method is decorated individually within a decorated class.
+
+## Core Concepts
+
+This module leverages TypeScript decorators to implement cross-cutting concerns like logging without cluttering your business logic.
+
+### The `@Log` Decorator
+
+The `@Log` decorator wraps the target method(s) using the `wrapLog` utility from the `@tstdl/base/function` module. It intercepts the method call, logs the entry (optionally with arguments), executes the original method, and logs the exit (optionally with the result or error and execution duration).
+
+It supports both:
+
+1.  **Method Decorator**: Wraps a single method.
+2.  **Class Decorator**: Iterates through the class prototype and static properties to wrap all functions found.
+
+## 🚀 Basic Usage
+
+### Decorating a Method
+
+Apply `@Log` to a specific method to trace its execution.
+
+```ts
+import { Log } from '@tstdl/base/decorators';
+
+class Calculator {
+  @Log()
+  add(a: number, b: number): number {
+    return a + b;
+  }
+}
+
+const calc = new Calculator();
+calc.add(5, 3);
+// Logs output similar to:
+// Call: Calculator.add(5, 3)
+// Return: Calculator.add => 8 (took 0.1ms)
+```
+
+### Decorating a Class
+
+Apply `@Log` to a class to automatically wrap all its static and instance methods.
+
+```ts
+import { Log } from '@tstdl/base/decorators';
+
+@Log()
+class UserService {
+  static create(name: string) {
+    console.log(`Creating user ${name}`);
+  }
+
+  getUser(id: string) {
+    return { id, name: 'Alice' };
+  }
+
+  deleteUser(id: string) {
+    // ...
+  }
+}
+
+// All methods above will be logged when called.
+UserService.create('Bob');
+const service = new UserService();
+service.getUser('123');
+```
+
+## 🔧 Advanced Topics
+
+### Configuration Options
+
+The `Log` decorator accepts an options object (passed to `wrapLog`) to control the logging behavior.
+
+```ts
+import { Log } from '@tstdl/base/decorators';
+
+class DataService {
+  @Log({
+    logArgs: true, // Log arguments passed to the function
+    logResult: false, // Do not log the return value (e.g. if it's huge)
+    logError: true, // Log errors if thrown
+    logTime: true, // Log execution duration
+  })
+  async fetchData(query: string): Promise<any> {
+    // ... complex logic
+    return {
+      /* large object */
+    };
+  }
+}
+```
+
+### Mixing Class and Method Decorators
+
+You can apply `@Log` to the class and provide specific configurations for individual methods. The decorator logic ensures methods are not wrapped twice; the method-level decorator takes precedence during the wrapping process.
+
+```ts
+import { Log } from '@tstdl/base/decorators';
+
+@Log({ logResult: false }) // Default: don't log results for methods in this class
+class ReportGenerator {
+  generateSummary() {
+    // Inherits class config: logs execution but not result
+    return 'Summary...';
+  }
+
+  @Log({ logResult: true }) // Override: log result for this specific method
+  generateDetailedReport() {
+    return 'Detailed Report...';
+  }
+}
+```
+
+## 📚 API
+
+| Export                          | Type      | Description                                                                  |
+| :------------------------------ | :-------- | :--------------------------------------------------------------------------- |
+| `Log(options?: WrapLogOptions)` | Decorator | A decorator factory that wraps a class or method with logging functionality. |
+
+### Types
+
+| Type             | Description                                                                          |
+| :--------------- | :----------------------------------------------------------------------------------- |
+| `WrapLogOptions` | Configuration object for the logging wrapper (imported from `@tstdl/base/function`). |

package/distributed-loop/README.md

@@ -0,0 +1,231 @@
+# Distributed Loop
+
+A robust mechanism for running periodic tasks synchronized across distributed systems. It ensures that a specific loop executes on only one instance of your application at a time, preventing race conditions and duplicate processing in clustered environments.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Cancellation with Signals](#cancellation-with-signals)
+  - [Manual Control](#manual-control)
+  - [Error Handling](#error-handling)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Distributed Synchronization**: Uses a `LockProvider` to ensure at most one active execution across a cluster.
+- **Interval Control**: Run tasks at precise intervals (e.g., every 5 seconds).
+- **Flexible Timing**: Distinguishes between execution interval and polling accuracy.
+- **Graceful Shutdown**: Native support for `CancellationSignal` and manual `stop()` via `LoopController`.
+- **Dependency Injection**: Can be resolved via `DistributedLoopProvider` or injected directly with a key.
+
+## Core Concepts
+
+### The Problem
+
+In a microservices or clustered architecture, you often need to run periodic background tasks (e.g., sending emails, cleaning up cache, fetching external data). If you simply use `setInterval` on every instance, the task will run multiple times simultaneously, leading to data corruption or wasted resources.
+
+### The Solution
+
+The `DistributedLoop` solves this by acquiring a distributed lock before executing the task.
+
+1.  **Lock Acquisition**: The loop attempts to acquire a lock (via `LockProvider`) associated with a unique key.
+2.  **Execution**: If the lock is acquired, the task runs.
+3.  **Wait**: If the lock is held by another instance, the current instance waits and retries.
+4.  **Release**: The lock is held only during the execution of the task logic (plus the interval wait time in the current implementation logic).
+
+### Components
+
+- **`DistributedLoopProvider`**: A factory service to create named loops.
+- **`DistributedLoop`**: The class managing the run loop, timing, and locking.
+- **`LoopController`**: An interface returned when starting a loop, allowing you to stop it or await its completion.
+
+## 🚀 Basic Usage
+
+### 1. Configure LockProvider
+
+Ensure you have a `LockProvider` (e.g., `PostgresLockProvider`) configured in your dependency injection container. The `DistributedLoop` uses it to synchronize across instances.
+
+### 2. Inject the Provider
+
+Inject `DistributedLoopProvider` into your service for dynamic loop creation.
+
+```typescript
+import { DistributedLoopProvider } from '@tstdl/base/distributed-loop';
+import { Singleton, inject } from '@tstdl/base/injector';
+
+@Singleton()
+export class BackgroundWorker {
+  private readonly loopProvider = inject(DistributedLoopProvider);
+
+  start() {
+    // Create a named loop. The key 'data-sync' ensures uniqueness across the cluster.
+    const loop = this.loopProvider.get('data-sync');
+
+    // Run the loop
+    // Interval: 5000ms (5 seconds)
+    // Accuracy: 100ms (Check for stop/lock every 100ms)
+    loop.run(5000, 100, async (controller) => {
+      console.log('Running distributed task...');
+      await this.performSync();
+    });
+  }
+
+  private async performSync() {
+    // Your business logic here
+  }
+}
+```
+
+### 3. Direct Injection
+
+If your loop key is static, you can inject `DistributedLoop` directly.
+
+```typescript
+import { DistributedLoop } from '@tstdl/base/distributed-loop';
+import { Singleton, inject } from '@tstdl/base/injector';
+
+@Singleton()
+export class StaticWorker {
+  // Inject with a static key argument
+  private readonly loop = inject(DistributedLoop, 'static-worker-loop');
+
+  start() {
+    this.loop.run(60000, 1000, async () => {
+      console.log('Running static worker task...');
+    });
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Timing and Accuracy
+
+The `run` method takes both an `interval` and an `accuracy`.
+
+- **Interval**: The target time between the start of one iteration and the start of the next.
+- **Accuracy**: The maximum time the application waits between checking for the lock or a stop signal. A smaller accuracy makes the loop more responsive to stops and other instances releasing the lock, but increases the load on the `LockProvider`.
+
+**Note**: To maintain exclusive access between iterations, the loop holds the lock for most of the interval, releasing it only for a short window defined by the accuracy. This ensures that in a cluster, the same instance is likely to keep the lock unless it becomes unavailable.
+
+### Cancellation with Signals
+
+You can pass a `CancellationSignal` to the `run` method to tie the loop's lifecycle to a broader context (like the application shutdown signal).
+
+```typescript
+import { DistributedLoopProvider } from '@tstdl/base/distributed-loop';
+import { Application } from '@tstdl/base/application';
+import { inject } from '@tstdl/base/injector';
+
+async function main() {
+  const app = inject(Application);
+  const loopProvider = inject(DistributedLoopProvider);
+  const loop = loopProvider.get('cleanup-job');
+
+  // Pass the application's shutdown signal
+  loop.run(
+    60000, // Run every minute
+    1000, // 1 second accuracy
+    async () => {
+      console.log('Cleaning up...');
+    },
+    app.shutdownSignal, // Loop stops automatically when app shuts down
+  );
+}
+```
+
+### Manual Control
+
+The `run` method returns a `LoopController` which gives you manual control over the loop instance.
+
+```typescript
+import { DistributedLoopProvider } from '@tstdl/base/distributed-loop';
+import { inject } from '@tstdl/base/injector';
+import { timeout } from '@tstdl/base/utils';
+
+async function testLoop() {
+  const provider = inject(DistributedLoopProvider);
+  const loop = provider.get('test-loop');
+
+  const controller = loop.run(1000, 100, async () => {
+    console.log('Tick');
+  });
+
+  // Let it run for 5 seconds
+  await timeout(5000);
+
+  // Stop the loop manually
+  await controller.stop();
+  console.log('Loop stopped');
+}
+```
+
+### Error Handling
+
+The `DistributedLoop` does not automatically trap errors thrown inside your loop function. If your function throws an unhandled error:
+1. The current iteration stops immediately.
+2. The loop terminates.
+3. The `LoopController.$stopped` promise resolves.
+4. The error propagates as an unhandled rejection.
+
+**Best Practice**: Always wrap your business logic in a `try-catch` block within the loop function to prevent the entire loop from stopping on a single failure.
+
+```typescript
+loop.run(5000, 100, async () => {
+  try {
+    await riskyOperation();
+  } catch (error) {
+    console.error('Error in distributed loop iteration:', error);
+    // Loop continues to next iteration since error is caught
+  }
+});
+```
+
+## 📚 API
+
+### `DistributedLoopProvider`
+
+The factory class for creating distributed loops.
+
+| Method                              | Description                                                               |
+| :---------------------------------- | :------------------------------------------------------------------------ |
+| `get(key: string): DistributedLoop` | Creates and returns a new `DistributedLoop` instance identified by `key`. |
+
+### `DistributedLoop`
+
+The class responsible for executing the synchronized loop.
+
+| Method                                                                                                                 | Description                                                                                                                                                                                                                                   |
+| :--------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constructor(key: string, lockProvider: LockProvider)`                                                                 | Creates a new loop instance. Usually handled by `DistributedLoopProvider` or DI.                                                                                                                                                              |
+| `run(interval: number, accuracy: number, func: LoopFunction, cancellationSignal?: CancellationSignal): LoopController` | Starts the loop. <br>• `interval`: Time in ms between executions.<br>• `accuracy`: Polling interval in ms for lock/stop checks and release window.<br>• `func`: The function to execute.<br>• `cancellationSignal`: Optional signal to stop. |
+
+### `LoopController`
+
+Interface returned by `run()` to control the active loop.
+
+| Property/Method | Type                  | Description                                              |
+| :-------------- | :-------------------- | :------------------------------------------------------- |
+| `$stopped`      | `Promise<void>`       | A promise that resolves when the loop has fully stopped. |
+| `stop()`        | `() => Promise<void>` | Signals the loop to stop and waits for it to finish.     |
+
+### Types
+
+#### `LoopFunction`
+
+Type definition for the function executed by the loop.
+
+```typescript
+type LoopFunction = (controller: LoopController) => any | Promise<any>;
+```
+
+#### `DistributedLoopArgument`
+
+The argument type used for injecting a `DistributedLoop` with a key.
+
+```typescript
+type DistributedLoopArgument = string;
+```

package/distributed-loop/distributed-loop.js

@@ -42,7 +42,7 @@ let DistributedLoop = class DistributedLoop {
      */
     run(interval, accuracy, func, cancellationSignal) {
         const $stopped = new DeferredPromise();
-        const stopToken = cancellationSignal?.createChild() ?? new CancellationToken();
+        const stopToken = new CancellationToken(cancellationSignal);
         const stopFunction = async () => {
             if (!stopToken.isSet) {
                 stopToken.set();