@tstdl/base 0.93.138 → 0.93.140

package/text/README.md

@@ -0,0 +1,346 @@
+# @tstdl/base/text
+
+A powerful, reactive, and type-safe text localization module for TypeScript applications, built on signals. It provides seamless integration for internationalization (i18n) with automatic UI updates, parameter interpolation, and strong compile-time safety.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [LocalizationService](#localizationservice)
+  - [Localization Definitions](#localization-definitions)
+  - [DynamicText](#dynamictext)
+  - [Type-Safe Keys](#type-safe-keys)
+- [🚀 Basic Usage](#-basic-usage)
+  - [1. Define Localization Structure](#1-define-localization-structure)
+  - [2. Create Localization Data](#2-create-localization-data)
+  - [3. Register and Use](#3-register-and-use)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Reactive Localization with Signals](#reactive-localization-with-signals)
+  - [Parameterized Text](#parameterized-text)
+  - [Localization Functions](#localization-functions)
+  - [Localizing Enums](#localizing-enums)
+  - [Resolving Nested Dynamic Text](#resolving-nested-dynamic-text)
+  - [Common Localizations](#common-localizations)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type-Safe Keys**: Leverage TypeScript proxies to provide compile-time safety and autocompletion for localization keys, eliminating magic strings.
+- **Reactive Architecture**: Built on Signals, allowing text to automatically update whenever the active language changes without manual subscription management.
+- **Dynamic Text Support**: Uniformly handle static strings, Signals, and Observables as localizable content.
+- **Parameter Interpolation**: Easily inject values into translation strings (e.g., `Hello {{name}}`).
+- **Functional Localization**: Use functions for complex logic like pluralization or conditional formatting.
+- **Enum Support**: First-class utilities for localizing TypeScript enums.
+- **RxJS Compatibility**: Includes Observable-based alternatives for all reactive methods.
+
+## Core Concepts
+
+### LocalizationService
+
+The `LocalizationService` is the singleton central hub. It manages the active language, stores translation data, and performs the actual text resolution. It exposes reactive signals for the current language and available languages.
+
+### Localization Definitions
+
+A `Localization` object defines the translations for a specific language. It consists of:
+
+- **`language`**: Metadata like code (`en`) and name (`English`).
+- **`keys`**: A nested object structure containing the translation strings or functions.
+- **`enums`**: Definitions for translating TypeScript enums.
+
+### DynamicText
+
+`DynamicText` is a type alias for `ReactiveValue<LocalizableText>`. It represents a piece of text that might be:
+
+1. A static string or localization key.
+2. A `Signal` emitting localization keys.
+3. An `Observable` emitting localization keys.
+
+The module provides utilities to "resolve" a `DynamicText` into a `Signal<string>` that updates if either the source value changes _or_ the active language changes.
+
+### Type-Safe Keys
+
+Instead of using dot-notation strings (e.g., `'home.welcome'`), this module uses a proxy object generated by `getLocalizationKeys()`. This allows you to pass around references to keys (e.g., `keys.home.welcome`) that TypeScript understands, enabling refactoring support and compile-time checks.
+
+## 🚀 Basic Usage
+
+### 1. Define Localization Structure
+
+Define the shape of your localization keys using TypeScript types. This ensures all languages implement the same keys.
+
+```typescript
+import { type Localization, type LocalizeItem, getLocalizationKeys } from '@tstdl/base/text';
+
+// Define the structure
+type AppLocalization = Localization<{
+  app: {
+    title: LocalizeItem;
+    greeting: LocalizeItem;
+  };
+}>;
+
+// Create the type-safe key proxy
+export const keys = getLocalizationKeys<AppLocalization>();
+```
+
+### 2. Create Localization Data
+
+Implement the localization for your supported languages.
+
+```typescript
+import { type AppLocalization } from './localization-types'; // from step 1
+
+export const english: AppLocalization = {
+  language: { code: 'en', name: 'English' },
+  keys: {
+    app: {
+      title: 'My Awesome App',
+      greeting: 'Hello World',
+    },
+  },
+  enums: [],
+};
+
+export const german: AppLocalization = {
+  language: { code: 'de', name: 'Deutsch' },
+  keys: {
+    app: {
+      title: 'Meine Tolle App',
+      greeting: 'Hallo Welt',
+    },
+  },
+  enums: [],
+};
+```
+
+### 3. Register and Use
+
+Inject the service, register the languages, and resolve text.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { LocalizationService } from '@tstdl/base/text';
+import { keys } from './localization-types';
+import { english, german } from './localizations';
+
+const localizationService = inject(LocalizationService);
+
+// Register languages
+localizationService.registerLocalization(english, german);
+
+// Set active language
+localizationService.setLanguage('en');
+
+// Resolve text reactively (returns a Signal)
+const titleSignal = localizationService.localize(keys.app.title);
+
+console.log(titleSignal()); // "My Awesome App"
+
+// Switch language
+localizationService.setLanguage('de');
+
+// Signal updates automatically
+console.log(titleSignal()); // "Meine Tolle App"
+```
+
+### Modular Localizations
+
+`registerLocalization` automatically merges new keys and enums into existing language definitions if the language code matches. This allows different parts of your application or different modules to contribute translations to the same language incrementally.
+
+### Handling Missing Keys and Parameters
+
+- **Missing Key**: If a localization key is missing for the active language, the service returns the key wrapped in double underscores (e.g., `__app.title__`) and logs a warning.
+- **Missing Parameter**: If a parameter is missing in the data object but required by the template string, it is replaced by the parameter name wrapped in double underscores (e.g., `Hello, __name__!`).
+- **Missing Observable Value**: When resolving an `Observable` based `DynamicText` using `resolveDynamicText`, the initial value before the first emission is `[MISSING LOCALIZATION KEY]`.
+
+## 🔧 Advanced Topics
+
+### Reactive Localization with Signals
+
+The `resolveDynamicText` function is the primary tool for handling text in reactive applications. It accepts static values, Signals, or Observables.
+
+```typescript
+import { signal } from '@tstdl/base/signals';
+import { resolveDynamicText } from '@tstdl/base/text';
+import { keys } from './localization-types';
+
+// A signal that determines which key to show
+const statusSignal = signal(keys.status.online);
+
+// Result is a signal that updates if statusSignal changes OR language changes
+const textSignal = resolveDynamicText(statusSignal);
+```
+
+### Parameterized Text
+
+You can define parameters in your strings using `{{ paramName }}` syntax. Use `localizationData` to bind values to these parameters.
+
+**Definition:**
+
+```typescript
+type AppLocalization = Localization<{
+  messages: {
+    welcome: LocalizeItem<{ name: string }>;
+  };
+}>;
+
+const en: AppLocalization = {
+  // ...
+  keys: {
+    messages: {
+      welcome: 'Welcome, {{name}}!',
+    },
+  },
+  // ...
+};
+```
+
+**Usage:**
+
+```typescript
+import { localizationData, resolveDynamicText } from '@tstdl/base/text';
+import { keys } from './localization-types';
+
+// Create a data object binding the key and parameters
+const data = localizationData(keys.messages.welcome, { name: 'Alice' });
+
+const text = resolveDynamicText(data);
+console.log(text()); // "Welcome, Alice!"
+```
+
+### Localization Functions
+
+For complex logic (like pluralization or conditional formatting), use a function instead of a string. Functions receive the parameters and a context object containing the `LocalizationService`.
+
+```typescript
+const en: AppLocalization = {
+  // ...
+  keys: {
+    items: {
+      count: ({ count }, { localizationService }) => (count === 1 ? '1 Item' : `${count} Items`),
+    },
+  },
+  // ...
+};
+
+// Usage
+const text = resolveDynamicText(localizationData(keys.items.count, { count: 5 }));
+console.log(text()); // "5 Items"
+```
+
+### Localizing Enums
+
+The module provides specific helpers for `enum` types to ensure type safety and ease of use.
+
+```typescript
+import { defineEnum, type EnumType } from '@tstdl/base/enumeration';
+import { enumerationLocalization, localizeEnum } from '@tstdl/base/text';
+
+// 1. Define Enum
+const Status = defineEnum('Status', {
+  Active: 'active',
+  Inactive: 'inactive',
+});
+type Status = EnumType<typeof Status>;
+
+// 2. Add to Localization Type
+type AppLocalization = Localization<
+  {
+    /* ... keys ... */
+  },
+  [typeof Status] // Add enum type here
+>;
+
+// 3. Define Translations
+const en: AppLocalization = {
+  // ...
+  enums: [
+    enumerationLocalization(Status, 'Status', {
+      [Status.Active]: 'Active User',
+      [Status.Inactive]: 'Inactive User',
+    }),
+  ],
+};
+
+// 4. Usage
+const statusText = localizationService.localizeEnum(Status, Status.Active);
+console.log(statusText()); // "Active User"
+```
+
+### Resolving Nested Dynamic Text
+
+When working with lists of objects where one property is a `DynamicText` (e.g., a navigation menu or a list of options), `resolveNestedDynamicTexts` helps transform the entire array efficiently.
+
+```typescript
+import { resolveNestedDynamicTexts, type DynamicText } from '@tstdl/base/text';
+
+type MenuItem = {
+  id: string;
+  label: DynamicText; // Can be a string, key, or localizationData
+};
+
+const menuItems: MenuItem[] = [
+  { id: 'home', label: keys.nav.home },
+  { id: 'settings', label: keys.nav.settings },
+];
+
+// Returns a Signal<Array<{ id: string, label: string }>>
+// The 'label' property is now the resolved string
+const resolvedMenu = resolveNestedDynamicTexts(menuItems, 'label');
+```
+
+### Common Localizations
+
+The module includes a set of common localizations (Yes, No, Ok, Cancel, etc.) that you can merge into your application to avoid repetition.
+
+```typescript
+import { englishTstdlCommonLocalization, germanTstdlCommonLocalization } from '@tstdl/base/text';
+
+localizationService.registerLocalization(englishTstdlCommonLocalization, germanTstdlCommonLocalization);
+```
+
+## 📚 API
+
+### LocalizationService
+
+| Method                                   | Description                                                                 |
+| :--------------------------------------- | :-------------------------------------------------------------------------- |
+| `registerLocalization(...localizations)` | Registers one or more localization definitions. Merges if language exists.  |
+| `setLanguage(code)`                      | Sets the active language by code or `Language` object.                      |
+| `getLanguage(code)`                      | Retrieves a registered `Language` by its code.                              |
+| `hasLanguage(code)`                      | Checks if a language is registered.                                         |
+| `localize(data)`                         | Returns a `Signal<string>` for the given key/data.                          |
+| `localize$(data)`                        | Returns an `Observable<string>` for the given key/data.                     |
+| `localizeOnce(data)`                     | Returns a `string` (non-reactive) for the current language.                 |
+| `localizeEnum(enum, value)`              | Returns a `Signal<string>` for the enum value.                              |
+| `localizeEnum$(enum, value)`             | Returns an `Observable<string>` for the enum value.                         |
+| `localizeEnumOnce(enum, value)`          | Returns a `string` (non-reactive) for the enum value.                       |
+| `activeLanguage`                         | Read-only signal of the currently active `Language`.                        |
+| `availableLanguages`                     | Read-only signal of all registered `Language`s.                             |
+
+### Utilities
+
+| Function                              | Description                                                                 |
+| :------------------------------------ | :-------------------------------------------------------------------------- |
+| `getLocalizationKeys<T>()`            | Returns a proxy object for type-safe access to localization keys.           |
+| `localizationData(key, params)`       | Creates a typed object containing a key and its parameters.                 |
+| `resolveDynamicText(text)`            | Converts a `DynamicText` into a `Signal<string>`.                           |
+| `resolveDynamicText$(text)`           | Converts a `DynamicText` into an `Observable<string>`.                      |
+| `resolveDynamicTexts(texts)`          | Converts an array of `DynamicText` into a `Signal<string[]>`.               |
+| `resolveDynamicTexts$(texts)`         | Converts an array of `DynamicText` into an `Observable<string[]>`.          |
+| `resolveNestedDynamicText(obj, key)`  | Resolves a `DynamicText` property within an object (Signal).                |
+| `resolveNestedDynamicText$(obj, key)` | Resolves a `DynamicText` property within an object (Observable).            |
+| `resolveNestedDynamicTexts(arr, key)` | Resolves a `DynamicText` property within an array of objects (Signal).      |
+| `resolveNestedDynamicTexts$(arr, key)`| Resolves a `DynamicText` property within an array of objects (Observable).  |
+| `enumerationLocalization(...)`        | Helper to define enum translations in a `Localization` object.              |
+| `autoEnumerationLocalization(enum)`   | Generates default translations using enum key names as values.              |
+
+### Types
+
+| Type                   | Description                                                                        |
+| :--------------------- | :--------------------------------------------------------------------------------- |
+| `Localization`         | The structure for defining translations (language, keys, enums).                   |
+| `LocalizeItem<Params>` | A translation value: either a string or a `LocalizeFunction`.                      |
+| `LocalizeFunction<P>`  | A function returning a string, receiving parameters and `LocalizeFunctionContext`. |
+| `DynamicText`          | `ReactiveValue<LocalizableText>`. The standard input type for localizable content. |
+| `LocalizableText`      | `string | LocalizationData`.                                                       |
+| `LocalizationData`     | Key, `LocalizationDataObject`, or `EnumLocalizationKey`.                           |

package/threading/README.md

@@ -0,0 +1,238 @@
+# @tstdl/base/threading
+
+The `threading` module provides a unified, type-safe abstraction for multi-threading in both Node.js and browser environments. It utilizes a managed thread pool and an RPC mechanism to easily offload CPU-intensive tasks to worker threads without manually managing message passing.
+
+## Table of Contents
+
+1.  [✨ Features](#-features)
+2.  [Core Concepts](#core-concepts)
+3.  [🚀 Basic Usage](#-basic-usage)
+4.  [🔧 Advanced Topics](#-advanced-topics)
+    - [Named Workers (Multiple Functions)](#named-workers-multiple-functions)
+    - [Configuration](#configuration)
+5.  [📚 API](#-api)
+
+## ✨ Features
+
+- **Cross-Platform:** Works seamlessly in Node.js (using `worker_threads`) and Browsers (using `Web Workers`).
+- **Thread Pooling:** Automatically manages a pool of workers to reuse resources and limit concurrency.
+- **RPC Communication:** Call worker functions directly as if they were local asynchronous functions, handling argument and return value serialization automatically.
+- **Type Safety:** leveraging TypeScript to ensure the main thread invokes worker functions with correct arguments and return types.
+- **Resource Management:** Implements `AsyncDisposable` for clean teardown of thread pools.
+
+## Core Concepts
+
+### Thread Pool
+
+The `ThreadPool` is the main orchestrator running on the main thread. It spawns a specified number of worker threads based on a provided script URL. It manages the lifecycle of these workers and distributes tasks to them.
+
+### RPC (Remote Procedure Call)
+
+Instead of manually posting messages (`postMessage`) and listening for events, this module uses an RPC layer. You "expose" a function inside the worker, and the `ThreadPool` creates a "remote" proxy for that function. When you call the proxy, arguments are sent to the worker, the function executes, and the result is sent back.
+
+### Worker Script
+
+This is the separate entry point file that runs inside the thread. It imports `exposeThreadWorker` to make specific functions available to the pool.
+
+## 🚀 Basic Usage
+
+To use the threading module, you need two parts: the worker script (the code running in the thread) and the main application code (which creates the pool).
+
+### 1. Create the Worker (`worker.ts`)
+
+Define your CPU-intensive function, export its type (for type safety in the main thread), and expose it.
+
+```ts
+import { exposeThreadWorker } from '@tstdl/base/threading';
+
+// 1. Define the function to run in the thread
+function heavyComputation(input: number): number {
+  // Simulate heavy work
+  const start = Date.now();
+  while (Date.now() - start < 500);
+  return input * 2;
+}
+
+// 2. Export the type so the main thread knows the signature
+export type HeavyComputation = typeof heavyComputation;
+
+// 3. Expose the function as the default handler
+exposeThreadWorker(heavyComputation);
+```
+
+### 2. Use the Pool (`main.ts`)
+
+Instantiate the `ThreadPool` pointing to the compiled worker script.
+
+```ts
+import { ThreadPool } from '@tstdl/base/threading';
+import { Logger } from '@tstdl/base/logger';
+import type { HeavyComputation } from './worker.js'; // Import type only
+
+async function main() {
+  const logger = new Logger('App');
+
+  // Point to the compiled JS file of the worker
+  const workerUrl = new URL('./worker.js', import.meta.url);
+
+  // Create the pool
+  const pool = new ThreadPool(workerUrl, logger);
+
+  try {
+    // Get a type-safe processor function
+    // The generic argument <HeavyComputation> ensures type safety
+    const process = pool.getProcessor<HeavyComputation>();
+
+    // Run the task
+    const result = await process(21);
+    console.log(`Result: ${result}`); // Result: 42
+  } finally {
+    // Clean up threads
+    await pool.dispose();
+  }
+}
+
+main();
+```
+
+## 🔧 Advanced Topics
+
+### Named Workers (Multiple Functions)
+
+You can expose multiple functions from a single worker script by giving them unique names.
+
+**Worker (`multi-worker.ts`):**
+
+```ts
+import { exposeThreadWorker } from '@tstdl/base/threading';
+
+function add(a: number, b: number): number {
+  return a + b;
+}
+
+function subtract(a: number, b: number): number {
+  return a - b;
+}
+
+export type Add = typeof add;
+export type Subtract = typeof subtract;
+
+// Expose with specific names
+exposeThreadWorker(add, 'add');
+exposeThreadWorker(subtract, 'subtract');
+```
+
+**Main (`main.ts`):**
+
+```ts
+import { ThreadPool } from '@tstdl/base/threading';
+import { Logger } from '@tstdl/base/logger';
+import type { Add, Subtract } from './multi-worker.js';
+
+async function main() {
+  const logger = new Logger('App');
+  const pool = new ThreadPool(new URL('./multi-worker.js', import.meta.url), logger);
+
+  // Get processors by name
+  const addRemote = pool.getProcessor<Add>('add');
+  const subtractRemote = pool.getProcessor<Subtract>('subtract');
+
+  const sum = await addRemote(5, 3);
+  const diff = await subtractRemote(10, 4);
+
+  console.log({ sum, diff }); // { sum: 8, diff: 6 }
+
+  await pool.dispose();
+}
+```
+
+### Best Practices
+
+- **Offload CPU-Intensive Work Only:** Threading has overhead due to serialization and communication. Use it for heavy computations (e.g., image processing, complex math, large data parsing) rather than simple asynchronous I/O.
+- **Minimize Data Transfer:** Arguments and return values are serialized (using the Structured Clone algorithm). Large objects can slow down communication.
+- **Clean Up Resources:** Always call `dispose()` or use `[Symbol.asyncDispose]` (e.g., via `await using`) to ensure worker threads are terminated when they are no longer needed.
+- **Worker Script Paths:** In Node.js, ensure the worker URL points to the _compiled_ `.js` file, especially when using TypeScript.
+
+### Configuration
+
+You can configure the underlying worker options and the number of threads in the pool.
+
+```ts
+import { ThreadPool } from '@tstdl/base/threading';
+import { Logger } from '@tstdl/base/logger';
+
+const pool = new ThreadPool(new URL('./worker.js', import.meta.url), new Logger('Pool'), {
+  // Number of workers to spawn.
+  // Defaults to half of CPU cores (via hardwareConcurrency / 2) or 4.
+  threadCount: 4,
+
+  // Node.js specific options (passed to node:worker_threads Worker constructor)
+  workerData: { some: 'data' },
+
+  // Browser specific options (passed to Web Worker constructor)
+  type: 'module',
+});
+```
+
+## 📚 API
+
+### Classes
+
+| Class        | Description                                                                                                                              |
+| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| `ThreadPool` | Manages a pool of worker threads. Implements `AsyncDisposable` for clean resource cleanup. Provides type-safe access to worker functions. |
+
+#### `ThreadPool`
+
+```ts
+class ThreadPool implements AsyncDisposable {
+  /** The URL or path to the worker script. */
+  readonly url: string | URL;
+
+  /** Configuration options used for this pool. */
+  readonly options: ThreadOptions | undefined;
+
+  constructor(url: string | URL, logger: Logger, options?: ThreadOptions);
+
+  /**
+   * Returns a type-safe function that, when called, executes the task on an available worker.
+   * This is the preferred way to interact with the pool.
+   * @param name The name of the exposed function in the worker (default: 'default').
+   */
+  getProcessor<T extends ThreadWorker>(name?: string): (...args: Parameters<T>) => Promise<ReturnType<T>>;
+
+  /**
+   * Directly executes a task on an available worker.
+   * @param name The name of the exposed function in the worker.
+   * @param args Arguments to pass to the worker function.
+   */
+  process<T extends ThreadWorker>(name: string, ...args: Parameters<T>): Promise<ReturnType<T>>;
+
+  /**
+   * Terminates all workers in the pool and releases resources.
+   */
+  dispose(): Promise<void>;
+}
+```
+
+### Functions
+
+| Function             | Description                                                                        |
+| :------------------- | :--------------------------------------------------------------------------------- |
+| `exposeThreadWorker` | Exposes a function inside a worker script so it can be called by the `ThreadPool`. |
+
+#### `exposeThreadWorker`
+
+```ts
+function exposeThreadWorker<T extends ThreadWorker>(worker: T, name?: string): void;
+```
+
+- `worker`: The function (synchronous or asynchronous) to expose.
+- `name`: An optional name for the function. Defaults to `'default'`.
+
+### Types
+
+| Type            | Definition                                                                         | Description                                                 |
+| :-------------- | :--------------------------------------------------------------------------------- | :---------------------------------------------------------- |
+| `ThreadWorker`  | `(...args: any[]) => any \| Promise<any>`                                        | Represents the signature of a function running in a thread. |
+| `ThreadOptions` | `(WorkerOptions \| NodeWorkerThreads.WorkerOptions) & { threadCount?: number }` | Configuration options for the `ThreadPool`.                 |