@tstdl/base 0.93.139 → 0.93.140

package/image-service/README.md

@@ -0,0 +1,137 @@
+# Image Service
+
+A robust module for generating signed, manipulated image URLs, providing an abstract interface for image processing services with a concrete implementation for [imgproxy](https://imgproxy.net/).
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Image Options](#image-options)
+  - [Manual Instantiation](#manual-instantiation)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Abstract Interface**: `ImageService` base class allows for dependency injection and easy swapping of image providers.
+- **Imgproxy Support**: Full implementation for generating signed imgproxy URLs.
+- **Secure Signing**: Automatically handles HMAC-SHA256 signature generation using your key and salt.
+- **Rich Manipulations**: Supports resizing, cropping (gravity/origin), formatting, quality adjustment, and cache busting.
+- **Type-Safe Options**: Fully typed configuration and options using TypeScript enums and classes.
+
+## Core Concepts
+
+The module revolves around the `ImageService` abstract class. By depending on this abstraction in your application, you decouple your code from the specific image processing backend.
+
+The primary implementation provided is `ImgproxyImageService`. It generates URLs that point to an imgproxy server. These URLs include:
+
+1.  **Processing Options**: Instructions for resizing, formatting, etc.
+2.  **Encoded Source URL**: The original image URL, Base64 encoded.
+3.  **Signature**: A cryptographic signature ensuring the URL parameters haven't been tampered with, preventing denial-of-service attacks via image processing.
+
+## 🚀 Basic Usage
+
+### 1. Configuration
+
+First, configure the service during your application bootstrap. This registers `ImgproxyImageService` as the implementation for `ImageService` in the dependency injection container.
+
+```ts
+import { configureImgproxyImageService } from '@tstdl/base/image-service';
+
+// In your bootstrap or configuration file
+configureImgproxyImageService({
+  endpoint: 'https://images.yourdomain.com',
+  key: 'your-hex-encoded-key',
+  salt: 'your-hex-encoded-salt',
+  signatureSize: 32,
+});
+```
+
+### 2. Generating URLs
+
+Inject the `ImageService` and use `getUrl` to generate signed URLs for your images.
+
+```ts
+import { ImageService, ImageResizeMode } from '@tstdl/base/image-service';
+import { inject } from '@tstdl/base/injector';
+
+class UserProfileController {
+  // Inject the abstract service
+  readonly #imageService = inject(ImageService);
+
+  async getAvatarUrl(originalUrl: string): Promise<string> {
+    // Generate a signed URL
+    const signedUrl = await this.#imageService.getUrl(originalUrl, {
+      width: 150,
+      height: 150,
+      resizeMode: ImageResizeMode.Fill,
+    });
+
+    return signedUrl;
+    // Output example:
+    // https://images.yourdomain.com/SIGNATURE/rs:fill:150:150/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Image Options
+
+The `ImageOptions` class provides granular control over the output image.
+
+```ts
+import { ImageService, ImageResizeMode, ImageOrigin, ImageFormat } from '@tstdl/base/image-service';
+import { inject } from '@tstdl/base/injector';
+
+const imageService = inject(ImageService);
+
+const url = await imageService.getUrl('https://example.com/banner.png', {
+  // Resize strategy
+  resizeMode: ImageResizeMode.Fit, // 'fit' or 'fill'
+  width: 800,
+  height: 400,
+
+  // Gravity / Origin (where to focus when cropping)
+  origin: ImageOrigin.Smart, // Uses smart detection if supported, or center
+
+  // Output format and quality
+  format: ImageFormat.Webp,
+  quality: 80,
+
+  // Cache busting string (appended to processing options)
+  cacheBuster: 'v1.2.3',
+});
+```
+
+### Manual Instantiation
+
+If you need to instantiate `ImgproxyImageService` directly (outside of the DI container) or manage multiple instances with different configurations:
+
+```ts
+import { ImgproxyImageService } from '@tstdl/base/image-service';
+
+const imgproxy = new ImgproxyImageService(
+  'https://img.example.com', // endpoint
+  'aabbcc...', // key (hex)
+  '112233...', // salt (hex)
+  32, // signature size
+);
+
+const url = await imgproxy.getUrl('http://source.com/img.jpg', { width: 100 });
+```
+
+## 📚 API
+
+| Export                          | Type             | Description                                                                                |
+| :------------------------------ | :--------------- | :----------------------------------------------------------------------------------------- |
+| `ImageService`                  | `abstract class` | The base contract for image services. Defines `getUrl`.                                    |
+| `ImgproxyImageService`          | `class`          | Concrete implementation for imgproxy.                                                      |
+| `configureImgproxyImageService` | `function`       | Helper to register the imgproxy service and config in the injector.                        |
+| `ImageOptions`                  | `class`          | Configuration object for image manipulation (width, height, etc.).                         |
+| `ImageResizeMode`               | `enum`           | Resize strategies: `Fit`, `Fill`.                                                          |
+| `ImageFormat`                   | `enum`           | Output formats: `Png`, `Jpg`, `Webp`, `Avif`, etc.                                         |
+| `ImageOrigin`                   | `enum`           | Gravity/Origin for cropping: `Center`, `Smart`, `Top`, `TopLeft`, etc.                     |
+| `IMGPROXY_IMAGE_SERVICE_CONFIG` | `InjectionToken` | Token used to inject the configuration object.                                             |
+| `ImgproxyImageServiceConfig`    | `type`           | Type definition for the configuration object (`endpoint`, `key`, `salt`, `signatureSize`). |

package/injector/README.md

@@ -0,0 +1,491 @@
+# @tstdl/base/injector
+
+A powerful, flexible, and type-safe Dependency Injection (DI) framework for TypeScript. It combines modern ergonomics like property injection with advanced capabilities such as circular dependency resolution, asynchronous initialization, and hierarchical scoping.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Constructor Injection](#constructor-injection)
+  - [Injection Tokens](#injection-tokens)
+  - [Factory Providers](#factory-providers)
+  - [Lifecycle Scopes](#lifecycle-scopes)
+  - [Asynchronous Initialization](#asynchronous-initialization)
+  - [Resource Management & Cleanup](#resource-management--cleanup)
+  - [Optional Dependencies](#optional-dependencies)
+  - [Circular Dependencies](#circular-dependencies)
+  - [Multi-Providers](#multi-providers)
+  - [Resolution Arguments](#resolution-arguments)
+  - [Argument Forwarding](#argument-forwarding)
+  - [Aliases](#aliases)
+  - [Decorator Inheritance](#decorator-inheritance)
+  - [Hierarchical Injectors](#hierarchical-injectors)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type-Safe & Decorator-Driven:** Use decorators like `@Injectable` and `@Singleton` to configure dependencies.
+- **Ergonomic Property Injection:** Clean syntax using `inject()` in field initializers, removing constructor boilerplate.
+- **Flexible Constructor Injection:** Traditional constructor injection is fully supported.
+- **Comprehensive Lifecycles:** `singleton`, `injector`, `resolution`, and `transient` scopes.
+- **Hierarchical Injectors:** Create isolated or inheriting scopes using `injector.fork()`.
+- **Injection Tokens:** Support for interfaces and configuration objects via `injectionToken()`.
+- **Circular Dependency Handling:** Automatic resolution of cycles using `forwardRef`.
+- **Asynchronous Initialization:** Built-in support for async setup via `afterResolve` hooks.
+- **Automatic Cleanup:** Integrated with `AsyncDisposable` and `addDisposeHandler` for resource management.
+- **Decorator Inheritance:** Inherit injection options from base classes automatically.
+- **Context-Aware:** `runInInjectionContext` allows using DI features outside of class instantiation.
+
+## Core Concepts
+
+### Injector
+
+The container that holds provider registrations and manages the creation of instances. Injectors can be nested to create hierarchies.
+
+### Token
+
+A unique identifier for a dependency. This is usually a class constructor, but can be a custom `InjectionToken` for non-class values (like configuration objects or interfaces).
+
+### Provider
+
+Defines _how_ a token is resolved. Supported strategies include:
+
+- **`useClass`**: Creates an instance of a class.
+- **`useValue`**: Returns a specific value.
+- **`useFactory`**: Executes a function to produce the value.
+- **`useToken`**: Aliases one token to another.
+
+### Injection Context
+
+A temporary state active during the instantiation of a class by the Injector. The `inject()` function works only within this context (e.g., field initializers or constructors).
+
+## 🚀 Basic Usage
+
+The most common pattern uses `@Singleton()` or `@Injectable()` decorators and property injection via `inject()`.
+
+```typescript
+import { Injector, Singleton, inject } from '@tstdl/base/injector';
+
+// 1. Define a dependency
+@Singleton()
+export class LoggerService {
+  log(message: string): void {
+    console.log(`[LOG]: ${message}`);
+  }
+}
+
+// 2. Define a consumer
+@Singleton()
+export class UserService {
+  // Property injection: cleaner than constructor parameters
+  private readonly logger = inject(LoggerService);
+
+  getUser(id: number) {
+    this.logger.log(`Fetching user ${id}`);
+    return { id, name: 'Alice' };
+  }
+}
+
+// 3. Create the injector and resolve
+const injector = new Injector('Root');
+const userService = injector.resolve(UserService);
+
+userService.getUser(42);
+// Output: [LOG]: Fetching user 42
+```
+
+### Manual Registration
+
+You can also register providers manually on an injector or globally.
+
+```typescript
+// Global registration (affects all new root injectors)
+Injector.registerSingleton(LoggerService, { useClass: ConsoleLogger });
+
+// Local registration (only for this injector and its children)
+const injector = new Injector('Root');
+injector.register(LoggerService, { useValue: myMockLogger });
+```
+
+## 🔧 Advanced Topics
+
+### Constructor Injection
+
+Traditional constructor injection is fully supported. If you use TypeScript with `emitDecoratorMetadata` enabled, types are inferred automatically. Otherwise, or for interfaces/tokens, use the `@Inject()` decorator.
+
+```typescript
+import { Injectable, Inject } from '@tstdl/base/injector';
+import { LoggerService } from './logger.service.js';
+
+@Injectable()
+export class ProductService {
+  constructor(
+    // Type inferred automatically if metadata is emitted
+    private readonly logger: LoggerService,
+  ) {
+    this.logger.log('ProductService initialized');
+  }
+}
+```
+
+### Injection Tokens
+
+Use `injectionToken` for dependencies that aren't classes, such as configuration objects or primitives.
+
+```typescript
+import { Injector, inject, injectionToken, Injectable } from '@tstdl/base/injector';
+
+interface AppConfig {
+  apiUrl: string;
+}
+
+// Create a typed token
+export const APP_CONFIG = injectionToken<AppConfig>('APP_CONFIG');
+
+@Injectable()
+class ApiClient {
+  private readonly config = inject(APP_CONFIG);
+
+  get url() {
+    return this.config.apiUrl;
+  }
+}
+
+const injector = new Injector('Root');
+
+// Register the value for the token
+injector.register(APP_CONFIG, {
+  useValue: { apiUrl: 'https://api.example.com' },
+});
+
+const client = injector.resolve(ApiClient);
+console.log(client.url); // https://api.example.com
+```
+
+### Factory Providers
+
+Factories allow complex creation logic, capable of using `inject()` internally.
+
+```typescript
+import { Injector, inject, injectionToken } from '@tstdl/base/injector';
+
+class Database {
+  constructor(public connectionString: string) {}
+}
+
+const DB_CONN_STRING = injectionToken<string>('DB_CONN_STRING');
+const DATABASE = injectionToken<Database>('DATABASE');
+
+const injector = new Injector('Root');
+
+injector.register(DB_CONN_STRING, { useValue: 'postgres://localhost:5432' });
+
+injector.register(DATABASE, {
+  useFactory: () => {
+    // Factories run in an injection context
+    const connString = inject(DB_CONN_STRING);
+    return new Database(connString);
+  },
+});
+```
+
+### Lifecycle Scopes
+
+Control instance sharing using the `lifecycle` option in `@Injectable` or `@Scoped`.
+
+```typescript
+import { Singleton, Scoped, Injectable } from '@tstdl/base/injector';
+
+// One instance per root injector (application-wide singleton)
+@Singleton()
+class AuthService {}
+
+// One instance per injector (useful for hierarchical injectors)
+@Scoped('injector')
+class ModuleService {}
+
+// One instance per .resolve() call tree
+@Scoped('resolution')
+class RequestContext {}
+
+// New instance every time it is injected (default for @Injectable)
+@Injectable() // or @Scoped('transient')
+class TransientService {}
+```
+
+### Asynchronous Initialization
+
+Implement the `Resolvable` interface and the `[afterResolve]` symbol to perform asynchronous setup. You must use `resolveAsync` or `injectAsync` to ensure the promise is awaited.
+
+```typescript
+import { Singleton, afterResolve, Resolvable, Injector } from '@tstdl/base/injector';
+
+@Singleton()
+export class DatabaseService implements Resolvable {
+  isConnected = false;
+
+  // Called automatically after instantiation
+  async [afterResolve](): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    this.isConnected = true;
+  }
+}
+
+const injector = new Injector('Root');
+
+// Use resolveAsync to await the [afterResolve] hook
+const db = await injector.resolveAsync(DatabaseService);
+console.log(db.isConnected); // true
+```
+
+### Resource Management & Cleanup
+
+The `Injector` implements `AsyncDisposable`. When an injector is disposed, all instances created within it that implement `Disposable` or `AsyncDisposable` are also disposed. You can also register custom cleanup logic using `addDisposeHandler` in the `afterResolve` hook or within a factory.
+
+```typescript
+import { Singleton, afterResolve, Resolvable, AfterResolveContext } from '@tstdl/base/injector';
+
+@Singleton()
+export class DatabaseConnection implements Resolvable, AsyncDisposable {
+  async [afterResolve](_arg: any, { addDisposeHandler }: AfterResolveContext): Promise<void> {
+    await this.connect();
+
+    // Register a manual cleanup handler
+    addDisposeHandler(async () => await this.disconnect());
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    // This will also be called when the injector is disposed
+  }
+}
+
+const injector = new Injector('Root');
+await injector.resolveAsync(DatabaseConnection);
+await injector.dispose(); // Triggers all cleanup handlers
+```
+
+### Optional Dependencies
+
+Use the `@Optional()` decorator or the `optional: true` option in `inject()` to allow dependencies to be `undefined` if no provider is registered.
+
+```typescript
+import { Injectable, Optional, inject } from '@tstdl/base/injector';
+
+@Injectable()
+class NotificationService {
+  // Using decorator
+  @Optional()
+  private readonly logger?: LoggerService;
+
+  // Using inject()
+  private readonly analytics = inject(AnalyticsService, undefined, { optional: true });
+}
+```
+
+### Circular Dependencies
+
+The injector can handle circular dependencies (A needs B, B needs A) using `forwardRef`.
+
+```typescript
+import { Injectable, inject } from '@tstdl/base/injector';
+// Assume ServiceB is imported here
+
+@Injectable()
+class ServiceA {
+  // Use forwardRef option in inject()
+  private readonly b = inject(ServiceB, undefined, { forwardRef: true });
+}
+
+@Injectable()
+class ServiceB {
+  private readonly a = inject(ServiceA);
+}
+```
+
+### Multi-Providers
+
+Register multiple providers for the same token and inject them as an array using `injectAll`.
+
+```typescript
+import { Injector, injectAll, injectionToken, Injectable } from '@tstdl/base/injector';
+
+interface Plugin {
+  name: string;
+}
+
+const PLUGIN = injectionToken<Plugin>('PLUGIN');
+
+@Injectable()
+class PluginA implements Plugin {
+  name = 'A';
+}
+
+@Injectable()
+class PluginB implements Plugin {
+  name = 'B';
+}
+
+const injector = new Injector('Root');
+
+// Register multiple implementations with multi: true
+injector.register(PLUGIN, { useClass: PluginA }, { multi: true });
+injector.register(PLUGIN, { useClass: PluginB }, { multi: true });
+
+@Injectable()
+class PluginManager {
+  // Injects an array of all registered plugins
+  private readonly plugins = injectAll(PLUGIN);
+
+  list() {
+    return this.plugins.map((p) => p.name);
+  }
+}
+```
+
+### Resolution Arguments
+
+You can pass runtime arguments to `resolve()`, which can be accessed anywhere in the resolution tree via `injectArgument()`.
+
+```typescript
+import { Injector, Injectable, injectArgument } from '@tstdl/base/injector';
+
+type UserContext = { userId: string };
+
+@Injectable()
+class UserProfile {
+  // Access the argument passed to resolve()
+  private readonly context = injectArgument<UserContext>();
+
+  get id() {
+    return this.context.userId;
+  }
+}
+
+const injector = new Injector('Root');
+const profile = injector.resolve(UserProfile, { userId: 'user-123' });
+
+console.log(profile.id); // user-123
+```
+
+### Argument Forwarding
+
+You can forward or map resolution arguments down the injection tree using `@ForwardArg()` or `@InjectArg()`.
+
+```typescript
+import { Injectable, ForwardArg, InjectArg } from '@tstdl/base/injector';
+
+@Injectable()
+class ServiceB {
+  // Injects the entire argument passed to the root .resolve() call
+  @InjectArg()
+  private readonly config: any;
+}
+
+@Injectable()
+class ServiceA {
+  // Forwards a specific property of the argument to ServiceB
+  @ForwardArg((arg: any) => arg.subConfig)
+  private readonly b = inject(ServiceB);
+}
+```
+
+### Aliases
+
+Classes can be registered under multiple tokens using the `alias` option. This is useful for providing multiple implementations of an interface or handling circular dependencies.
+
+```typescript
+import { Singleton } from '@tstdl/base/injector';
+
+export const LOGGER_TOKEN = injectionToken<Logger>('LOGGER');
+
+@Singleton({ alias: LOGGER_TOKEN })
+class ConsoleLogger implements Logger {
+  log(msg: string) { console.log(msg); }
+}
+```
+
+### Decorator Inheritance
+
+By default, `@Injectable` and `@Singleton` options (like `lifecycle`, `alias`, etc.) are inherited from parent classes. You can control this behavior using `inheritOptions`.
+
+```typescript
+@Singleton({ alias: BaseToken })
+class BaseService {}
+
+// Inherits 'singleton' lifecycle and 'alias' from BaseService
+@Injectable()
+class ExtendedService extends BaseService {}
+
+// Disables inheritance
+@Injectable({ inheritOptions: false })
+class IsolatedService extends BaseService {}
+```
+
+### Hierarchical Injectors
+
+Use `fork()` to create child injectors. Child injectors inherit providers from their parent but can override them or register new ones.
+
+```typescript
+const parent = new Injector('Parent');
+parent.register(LoggerService, { useClass: ConsoleLogger });
+
+const child = parent.fork('Child');
+// Child can resolve LoggerService from parent
+const logger = child.resolve(LoggerService);
+```
+
+## 📚 API
+
+### Classes
+
+| Class               | Description                                                                           |
+| :------------------ | :------------------------------------------------------------------------------------ |
+| `Injector`          | The main dependency injection container. implements `AsyncDisposable`.                 |
+| `ResolveChain`      | Represents the path taken during dependency resolution (useful for debugging errors). |
+| `ResolveError`      | Error thrown when resolution fails (e.g., missing provider, circular dependency).     |
+| `RegistrationError` | Error thrown during provider registration (e.g., invalid configuration).              |
+
+### Decorators
+
+| Decorator                           | Description                                                           |
+| :---------------------------------- | :-------------------------------------------------------------------- |
+| `@Injectable(options?)`             | Marks a class as available for injection.                             |
+| `@Singleton(options?)`              | Alias for `@Injectable({ lifecycle: 'singleton' })`.                  |
+| `@Scoped(lifecycle, options?)`      | Alias for `@Injectable` with a specific lifecycle.                    |
+| `@Inject(token?, arg?, mapper?)`    | Manually specifies the token for a constructor parameter or property. |
+| `@InjectAll(token?, arg?, mapper?)` | Injects all providers for a token as an array.                        |
+| `@Optional()`                       | Marks a dependency as optional (injects `undefined` if not found).    |
+| `@ForwardRef(tokenFn)`              | Handles circular dependencies in constructor injection.               |
+| `@InjectArg(mapper?)`               | Injects the resolution argument into a constructor parameter.         |
+| `@ForwardArg(mapper?)`              | Forwards/maps the resolution argument to a dependency.                |
+| `@ReplaceClass(constructor)`        | Replaces a class definition with another (useful for typing).         |
+| `@ResolveArg(value)`                | Provides a static resolution argument for a dependency.               |
+| `@ResolveArgProvider(provider)`     | Provides a dynamic resolution argument for a dependency.              |
+
+### Functions
+
+| Function                                | Description                                                           |
+| :-------------------------------------- | :-------------------------------------------------------------------- |
+| `inject(token, arg?, options?)`         | Injects a dependency. Must be used within an injection context.       |
+| `injectAsync(token, arg?, options?)`    | Asynchronously injects a dependency (awaits `afterResolve`).          |
+| `injectAll(token, arg?, options?)`      | Injects all providers for a token as an array.                        |
+| `injectAllAsync(token, arg?, options?)` | Asynchronously injects all providers for a token.                     |
+| `injectMany(...tokens)`                 | Injects multiple tokens at once, returning a tuple.                   |
+| `injectManyAsync(...tokens)`            | Asynchronously injects multiple tokens at once.                       |
+| `injectArgument()`                      | Retrieves the argument passed to `injector.resolve()`.                |
+| `injectionToken(description)`           | Creates a unique token for non-class dependencies.                    |
+| `provide(token, provider)`              | Helper to create a provider object with a `provide` property.         |
+| `runInInjectionContext(injector, fn)`   | Executes a function within an injection context, enabling `inject()`. |
+| `getCurrentInjector()`                  | Returns the currently active injector instance.                       |
+
+### Interfaces & Types
+
+| Type                | Description                                                                          |
+| :------------------ | :----------------------------------------------------------------------------------- |
+| `Provider<T>`       | Union type for `ClassProvider`, `ValueProvider`, `FactoryProvider`, `TokenProvider`. |
+| `InjectionToken<T>` | Type for a class constructor or a custom token.                                      |
+| `Resolvable<A>`     | Interface for classes that need `afterResolve` hooks or typed resolution arguments.  |
+| `AfterResolve<A>`   | Interface defining the `[afterResolve]` method signature.                            |
+| `Lifecycle`         | `'transient' \| 'singleton' \| 'injector' \| 'resolution'`                           |