@tstdl/base 0.93.139 → 0.93.141

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

package/types/README.md

@@ -0,0 +1,311 @@
+# @tstdl/base/types
+
+A comprehensive collection of fundamental, advanced, and specialized TypeScript utility types designed to enhance type safety, improve developer experience, and provide standard definitions for common data structures.
+
+## Table of Contents
+
+- [Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [General Utility Types](#general-utility-types)
+  - [Tagged Types](#tagged-types)
+  - [Enumerations](#enumerations)
+  - [GeoJSON Types](#geojson-types)
+  - [Web Types](#web-types)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Common Utilities](#common-utilities)
+  - [Tagged Types](#tagged-types-usage)
+  - [Enumerations](#enumerations-usage)
+  - [GeoJSON](#geojson)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Deep Selection](#deep-selection)
+  - [Type Paths](#type-paths)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Extensive Utility Belt**: Over 50 utility types for advanced manipulation (`Simplify`, `DeepPartial`, `Writable`, `PickDeep`, `Optionalize`, etc.).
+- **Nominal Typing**: A robust `Tagged` type system to create distinct types from primitives (branding), preventing accidental misuse of semantically different values.
+- **GeoJSON Support**: Complete, RFC 7946 compliant type definitions for geospatial data structures.
+- **Web Standards**: Ready-to-use types for HTML input attributes, modes, and autocomplete values.
+- **JSON & Primitives**: Strict definitions for JSON structures and primitive type mapping.
+
+## Core Concepts
+
+### General Utility Types
+
+TypeScript's built-in utility types (`Partial`, `Pick`, etc.) are excellent, but complex applications often require more granular control. This module provides utilities to:
+
+- **Simplify** complex intersection types into readable object literals (great for IDE tooltips).
+- **Deeply** modify types (make everything writable, optional, or readonly recursively).
+- **Select** or **Omit** nested properties using a structural mask.
+- **Transform** optional properties (`| undefined`) into truly optional keys (`?`).
+
+### Tagged Types
+
+Primitives like `string` are often used for IDs (`UserId`, `OrderId`). However, TypeScript treats all strings as compatible, allowing you to accidentally pass a `UserId` to a function expecting an `OrderId`.
+**Tagged Types** (also known as Branded Types) solve this by attaching a "tag" to the type signature. This makes them structurally unique to the compiler without requiring runtime overhead.
+
+### Enumerations
+
+While TypeScript has native enums, they often suffer from type-safety issues and limited runtime introspection. The library provides a set of types to work with both array-based and object-based enumerations defined via the `#/enumeration` module.
+
+### GeoJSON Types
+
+When working with maps and geospatial data, adhering to the GeoJSON standard is crucial. These types ensure your data structures (`Feature`, `Point`, `Polygon`) match the official specification.
+
+### Web Types
+
+Provides strict typing for HTML `<input>` and `<textarea>` attributes, including comprehensive unions for `autocomplete`, `inputmode`, and `type`.
+
+## 🚀 Basic Usage
+
+### Common Utilities
+
+Use these utilities to clean up and transform your interfaces.
+
+```ts
+import type { Simplify, Writable, Optionalize, OneOrMany } from '@tstdl/base/types';
+
+// 1. Simplify: Flattens intersections for better readability
+type Complex = { a: string } & { b: number };
+type Simple = Simplify<Complex>; // { a: string; b: number; }
+
+// 2. Writable: Removes 'readonly' modifiers
+const config = { endpoint: 'https://api.com', retries: 3 } as const;
+type MutableConfig = Writable<typeof config>;
+// { endpoint: "https://api.com"; retries: 3; } (mutable)
+
+// 3. Optionalize: Converts properties with `undefined` to optional keys `?`
+type RawData = {
+  id: string;
+  description: string | undefined; // Required key, but value can be undefined
+};
+type CleanData = Optionalize<RawData>;
+// { id: string; description?: string; }
+
+// 4. OneOrMany: Handles single items or arrays
+function processItems(items: OneOrMany<string>) {
+  const list = Array.isArray(items) ? items : [items];
+  // ...
+}
+```
+
+### Tagged Types Usage
+
+Create distinct types for different IDs to prevent bugs.
+
+```ts
+import type { Tagged } from '@tstdl/base/types';
+
+// Define distinct types
+type UserId = Tagged<string, 'UserId'>;
+type OrderId = Tagged<string, 'OrderId'>;
+
+function cancelOrder(orderId: OrderId, user: UserId) {
+  console.log(`User ${user} cancelled order ${orderId}`);
+}
+
+// Casting is required to "brand" the primitive
+const myUser = 'user-123' as UserId;
+const myOrder = 'order-abc' as OrderId;
+
+cancelOrder(myOrder, myUser); // ✅ OK
+
+// cancelOrder(myUser, myOrder);
+// ❌ Error: Argument of type 'UserId' is not assignable to parameter of type 'OrderId'.
+```
+
+### Enumerations Usage
+
+Extract types from your enumeration definitions.
+
+```ts
+import type { EnumerationValue, EnumerationKey } from '@tstdl/base/types';
+
+const Colors = {
+  Red: 'red',
+  Green: 'green',
+  Blue: 'blue',
+} as const;
+
+type Color = EnumerationValue<typeof Colors>; // 'red' | 'green' | 'blue'
+type ColorKey = EnumerationKey<typeof Colors>; // 'Red' | 'Green' | 'Blue'
+```
+
+### GeoJSON
+
+Type-safe geospatial data structures.
+
+```ts
+import type { Feature, Point } from '@tstdl/base/types';
+
+type PlaceProperties = {
+  name: string;
+  rating: number;
+};
+
+const cafe: Feature<Point, PlaceProperties> = {
+  type: 'Feature',
+  geometry: {
+    type: 'Point',
+    coordinates: [13.405, 52.52], // [lon, lat]
+  },
+  properties: {
+    name: 'Coffee Shop',
+    rating: 4.5,
+  },
+};
+```
+
+## 🔧 Advanced Topics
+
+### Deep Selection
+
+Use `PickDeep` to select a subset of a deeply nested type structure. This is incredibly useful for defining API responses or GraphQL-like selection sets.
+
+```ts
+import type { PickDeep } from '@tstdl/base/types';
+
+type UserProfile = {
+  id: string;
+  personal: {
+    name: { first: string; last: string };
+    age: number;
+  };
+  settings: {
+    theme: 'dark' | 'light';
+    notifications: boolean;
+  };
+};
+
+// Select only the first name and theme
+type UserPreview = PickDeep<
+  UserProfile,
+  {
+    personal: {
+      name: { first: true };
+    };
+    settings: {
+      theme: true;
+    };
+  }
+>;
+
+// Resulting Type:
+// {
+//   personal: {
+//     name: { first: string };
+//   };
+//   settings: {
+//     theme: 'dark' | 'light';
+//   };
+// }
+```
+
+### Type Paths
+
+Extract valid dot-notation paths from an object, useful for form libraries or property accessors.
+
+```ts
+import type { Path, TypeFromPath } from '@tstdl/base/types';
+
+type Config = {
+  database: {
+    host: string;
+    port: number;
+  };
+  logging: {
+    level: string;
+  };
+};
+
+// Union of all valid paths
+type ConfigPaths = Path<Config>;
+// "database" | "database.host" | "database.port" | "logging" | "logging.level"
+
+// Extract the type at a specific path
+type PortType = TypeFromPath<Config, 'database.port'>; // number
+```
+
+## 📚 API
+
+### General Utility Types
+
+| Type                    | Description                                                                   |
+| :---------------------- | :---------------------------------------------------------------------------- |
+| `Simplify<T>`           | Flattens intersection types into a single object type for better readability. |
+| `SimplifyDeep<T>`       | Recursively simplifies types.                                                 |
+| `Writable<T>`           | Removes `readonly` modifiers from properties.                                 |
+| `DeepWritable<T>`       | Recursively removes `readonly` modifiers.                                     |
+| `DeepReadonly<T>`       | Recursively adds `readonly` modifiers.                                        |
+| `DeepPartial<T>`        | Recursively makes all properties optional.                                    |
+| `DeepNonNullable<T>`    | Recursively removes `null` and `undefined`.                                   |
+| `Optionalize<T>`        | Converts properties that allow `undefined` into optional keys (`?`).          |
+| `OptionalizeDeep<T>`    | Recursively optionalizes properties that allow `undefined`.                   |
+| `OptionalizeNullable<T>`| Converts properties that allow `null` or `undefined` into optional keys (`?`).|
+| `Unoptionalize<T>`      | Converts optional keys (`?`) into required keys that allow `undefined`.       |
+| `PickBy<T, V>`          | Picks properties from `T` whose values are assignable to `V`.                 |
+| `OmitBy<T, V>`          | Omits properties from `T` whose values are assignable to `V`.                 |
+| `PickDeep<T, S>`        | Deeply picks properties based on a selection shape `S`.                       |
+| `OmitDeep<T, S>`        | Deeply omits properties based on a selection shape `S`.                       |
+| `Merge<T1, T2>`         | Merges two types, with `T2` properties overwriting `T1`.                      |
+| `OneOrMany<T>`          | `T | readonly T[]`.                                                          |
+| `Path<T>`               | Union of dot-notation paths for object `T`.                                   |
+| `TypeFromPath<T, P>`    | The type of the property at path `P` within `T`.                              |
+| `Json`                  | Represents any valid JSON value.                                              |
+| `Record<K, V>`          | Shorthand for `Record<K, V>` with default `K=PropertyKey`.                    |
+| `Type<T>`               | Represents a class constructor.                                               |
+| `AbstractType<T>`       | Represents an abstract class constructor.                                     |
+| `ReactiveValue<T>`      | `T | Signal<T> | Observable<T>`.                                            |
+| `PascalCase<V>`         | Converts a string literal to PascalCase.                                      |
+| `Flatten<T>`            | Unwraps a single level of array nesting.                                      |
+| `DeepFlatten<T>`        | Recursively unwraps array nesting.                                            |
+| `ArrayItem<T>`          | Extracts the item type from an array.                                         |
+| `Entries<T>`            | Returns array of `[key, value]` tuples.                                       |
+| `FromEntries<E>`        | Reconstructs an object from entries.                                          |
+
+### Tagged Types
+
+| Type                     | Description                                                |
+| :----------------------- | :--------------------------------------------------------- |
+| `Tagged<Type, TagName>`  | Creates a nominal type by branding `Type` with `TagName`.  |
+| `Untagged<T>`            | Extracts the underlying primitive type from a tagged type. |
+| `UntaggedDeep<T>`        | Recursively extracts underlying primitive types.           |
+| `HasTag<T, Token>`       | Checks if a type has a specific tag.                       |
+| `GetTagMetadata<T, Tag>` | Retrieves metadata associated with a tag.                  |
+
+### Enumerations
+
+| Type                  | Description                                            |
+| :-------------------- | :----------------------------------------------------- |
+| `Enumeration`         | Union of `EnumerationArray` and `EnumerationObject`. |
+| `EnumerationValue<T>` | The union of all values in an enumeration.             |
+| `EnumerationKey<T>`   | The union of all keys (keys for objects, indices for arrays). |
+| `EnumerationMap<T>`   | Maps keys to their normalized values.                  |
+| `EnumerationEntry<T>` | Union of `[key, value]` pairs.                         |
+
+### GeoJSON Types
+
+| Type                 | Description                                             |
+| :------------------- | :------------------------------------------------------ |
+| `Position`           | `[longitude, latitude, elevation?]`                     |
+| `Point`              | GeoJSON Point geometry.                                 |
+| `LineString`         | GeoJSON LineString geometry.                            |
+| `Polygon`            | GeoJSON Polygon geometry.                               |
+| `MultiPoint`         | GeoJSON MultiPoint geometry.                            |
+| `MultiLineString`    | GeoJSON MultiLineString geometry.                       |
+| `MultiPolygon`       | GeoJSON MultiPolygon geometry.                          |
+| `Geometry`           | Union of all geometry types.                            |
+| `GeometryCollection` | A collection of geometries.                             |
+| `Feature<G, P>`      | A GeoJSON Feature with geometry `G` and properties `P`. |
+| `FeatureCollection`  | A collection of Features.                               |
+
+### Web Types
+
+| Type                 | Description                                |
+| :------------------- | :----------------------------------------- |
+| `InputType`          | Union of valid HTML `<input>` type values. |
+| `InputMode`          | Union of valid HTML `inputmode` values.    |
+| `InputAutocomplete`  | Union of valid HTML `autocomplete` values. |
+| `InputAttributes`    | Interface for HTML input attributes.       |
+| `TextAreaAttributes` | Interface for HTML textarea attributes.    |