@tstdl/base 0.93.139 → 0.93.141

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

package/intl/README.md

@@ -0,0 +1,113 @@
+# @tstdl/base/intl
+
+The `intl` module provides utilities for handling internationalization tasks, specifically focusing on robust, locale-aware number parsing. It allows you to convert formatted number strings (e.g., "1.234,56" in German) back into standard JavaScript numbers by correctly identifying decimal and group separators based on the locale.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Loose Parsing](#loose-parsing)
+  - [Non-Latin Numerals](#non-latin-numerals)
+  - [Performance & Memoization](#performance--memoization)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Locale-Aware Parsing**: Handles `,`, `.`, and spaces as separators depending on the locale.
+- **Group Separator Support**: Automatically handles thousands separators (e.g., `1,000` vs `1.000`).
+- **Loose Mode**: Strips non-numeric characters (like currency symbols or units) before parsing.
+- **Numeral System Support**: Automatically maps non-Latin numerals (e.g., Arabic-Indic `١٢٣`) to standard digits.
+- **Memoization**: Optimized performance through cached parser instances.
+
+## Core Concepts
+
+Standard JavaScript functions like `parseFloat()` or `Number()` are designed for machine-readable formats (usually English-based, using `.` for decimals and no thousands separators). They often fail or produce incorrect results when dealing with user input in other locales (e.g., `parseFloat('1.234,56')` results in `1.234` instead of `1234.56`).
+
+The `NumberParser` class uses the native `Intl.NumberFormat` API to inspect the formatting rules of a given locale. It normalizes the input string by removing group separators and converting decimal separators to `.` before using the standard `Number()` constructor.
+
+## 🚀 Basic Usage
+
+The most common way to use this module is via the `parseNumber` helper function.
+
+```typescript
+import { parseNumber } from '@tstdl/base/intl';
+
+// US English: Comma for thousands, Dot for decimals
+const usValue = parseNumber('en-US', '12,345.67');
+console.log(usValue); // 12345.67
+
+// German: Dot for thousands, Comma for decimals
+const deValue = parseNumber('de-DE', '12.345,67');
+console.log(deValue); // 12345.67
+
+// French: Space for thousands, Comma for decimals
+const frValue = parseNumber('fr-FR', '12 345,67');
+console.log(frValue); // 12345.67
+```
+
+## 🔧 Advanced Topics
+
+### Loose Parsing
+
+When dealing with user input or scraped data, strings often contain currency symbols, units, or other text. The `loose` parameter (default `false`) instructs the parser to strip out any characters that are not valid numerals or separators for the target locale before parsing.
+
+```typescript
+import { parseNumber } from '@tstdl/base/intl';
+
+// Standard parsing fails on non-numeric characters
+const strict = parseNumber('en-US', '$1,234.56 USD');
+console.log(strict); // NaN
+
+// Loose parsing strips the currency symbol and text
+const loose = parseNumber('en-US', '$1,234.56 USD', true);
+console.log(loose); // 1234.56
+
+// Works with locale-specific formatting
+const looseDe = parseNumber('de-DE', '1.234,56 €', true);
+console.log(looseDe); // 1234.56
+```
+
+### Non-Latin Numerals
+
+The module automatically handles locales that use non-Latin numeral systems by mapping them back to standard digits.
+
+```typescript
+import { parseNumber } from '@tstdl/base/intl';
+
+// Arabic (Egypt): Uses Arabic-Indic numerals
+const arValue = parseNumber('ar-EG', '١٢٬٣٤٥٫٦٧');
+console.log(arValue); // 12345.67
+```
+
+### Performance & Memoization
+
+Creating a `NumberParser` instance involves some overhead. To mitigate this, the module exports `getNumberParser`, which memoizes instances based on the locale string. The `parseNumber` helper uses this internally.
+
+```typescript
+import { getNumberParser } from '@tstdl/base/intl';
+
+// Uses the memoized instance (Recommended)
+const parser = getNumberParser('en-GB');
+const value = parser.parse('10,000.50');
+```
+
+## 📚 API
+
+### Functions
+
+| Function | Description |
+| :--- | :--- |
+| `parseNumber(locale: string, value: string, loose?: boolean): number` | Parses a localized string into a number. |
+| `getNumberParser(locale: string): NumberParser` | Returns a memoized `NumberParser` instance for the specified locale. |
+
+### Classes
+
+#### `NumberParser`
+
+| Method / Property | Type | Description |
+| :--- | :--- | :--- |
+| `constructor(locale: string)` | `void` | Creates a new parser for the given locale. |
+| `locale` | `string` | The locale string this parser was initialized with. |
+| `parse(value: string, loose?: boolean): number` | `number` | Parses the string. If `loose` is true, strips invalid characters first. |