@tstdl/base 0.93.138 → 0.93.140

package/promise/README.md

@@ -0,0 +1,252 @@
+# Promise
+
+This module provides advanced Promise implementations to handle complex asynchronous patterns such as cancellation, deferred resolution, and lazy execution. It extends standard Promise capabilities to offer more control over asynchronous flows.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [CustomPromise](#custompromise)
+  - [DeferredPromise](#deferredpromise)
+  - [CancelablePromise](#cancelablepromise)
+  - [LazyPromise](#lazypromise)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Using DeferredPromise](#using-deferredpromise)
+  - [Using CancelablePromise](#using-cancelablepromise)
+  - [Using LazyPromise](#using-lazypromise)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Resetting a DeferredPromise](#resetting-a-deferredpromise)
+  - [Handling Cancellation Signals](#handling-cancellation-signals)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Deferred Resolution**: Control the resolution or rejection of a promise from outside its executor scope.
+- **Cancellation Support**: Create promises that can be explicitly canceled, returning a specific result state.
+- **Lazy Execution**: Define asynchronous logic that only executes when the promise is actually awaited or subscribed to.
+- **State Inspection**: Synchronously check if a promise is pending, resolved, or rejected (specifically for `DeferredPromise`).
+
+## Core Concepts
+
+### CustomPromise
+
+`CustomPromise` is a base class that extends the native `Promise`. It simplifies creating custom promise implementations by exposing the `resolve` and `reject` functions as protected fields to its subclasses. It also ensures that chained promises (via `then`, `catch`, etc.) return a standard `Promise` by overriding `Symbol.species`.
+
+### DeferredPromise
+
+A `DeferredPromise` is a Promise where the `resolve` and `reject` functions are exposed as public methods on the instance. This allows you to create a promise in one part of your application and settle it from another, effectively acting as a one-time signal or latch. It also supports being `reset()` to a pending state, allowing the same instance to be reused for sequential events.
+
+### CancelablePromise
+
+A `CancelablePromise` wraps an asynchronous operation that might need to be aborted. Unlike standard promises, it resolves to a result object that indicates whether the operation finished successfully or was canceled. It provides a `cancellationSignal` to the executor, which can be passed down to other cancelable operations (like `fetch` or timers).
+
+### LazyPromise
+
+A `LazyPromise` holds an executor function but does not run it immediately upon instantiation. The executor is only invoked when `then`, `catch`, or `finally` is called on the promise (usually when it is `await`ed). This is useful for defining expensive operations or network requests that should only occur if their result is strictly needed.
+
+## 🚀 Basic Usage
+
+### Using DeferredPromise
+
+Use `DeferredPromise` when you need to wait for an event that happens elsewhere.
+
+```ts
+import { DeferredPromise } from '@tstdl/base/promise';
+import { timeout } from '@tstdl/base/utils';
+
+async function main() {
+  const signal = new DeferredPromise<string>();
+
+  // Simulate an async process that will trigger the signal
+  void (async () => {
+    console.log('Process started...');
+    await timeout(1000);
+    console.log('Process finished, resolving signal.');
+    signal.resolve('Operation Complete');
+  })();
+
+  console.log('Waiting for signal...');
+  const result = await signal;
+  console.log('Received:', result);
+}
+
+main();
+```
+
+### Using CancelablePromise
+
+Use `CancelablePromise` for operations that users might want to abort, such as a long-running calculation or a network request.
+
+```ts
+import { CancelablePromise } from '@tstdl/base/promise';
+import { cancelableTimeout } from '@tstdl/base/utils';
+
+const longOperation = new CancelablePromise<string, string>((resolve, reject, signal) => {
+  // Pass the signal to other cancelable utilities
+  cancelableTimeout(2000, signal)
+    .then(() => resolve('Finished successfully'))
+    .catch((error) => reject(error));
+});
+
+async function run() {
+  // Cancel the operation before it finishes
+  setTimeout(() => {
+    longOperation.cancel('User aborted');
+  }, 500);
+
+  const result = await longOperation;
+
+  if (result.canceled) {
+    console.log('Operation canceled:', result.reason);
+  } else {
+    console.log('Operation success:', result.value);
+  }
+}
+
+run();
+```
+
+### Using LazyPromise
+
+Use `LazyPromise` to define a task without starting it immediately. You can provide either a standard executor or an asynchronous promise provider function.
+
+```ts
+import { LazyPromise } from '@tstdl/base/promise';
+
+// Using an executor
+const expensiveTask = new LazyPromise<number>((resolve) => {
+  console.log('Expensive task starting now...');
+  resolve(42);
+});
+
+// Using a promise provider
+const lazyProvider = new LazyPromise(async () => {
+  console.log('Lazy provider starting now...');
+  return 'result';
+});
+
+async function main() {
+  console.log('Promises created, but tasks have not started.');
+
+  // The executor runs here, when we await
+  const value = await expensiveTask;
+  console.log('Result:', value);
+
+  const providerValue = await lazyProvider;
+  console.log('Provider Result:', providerValue);
+}
+
+main();
+```
+
+## 🔧 Advanced Topics
+
+### Resetting a DeferredPromise
+
+A `DeferredPromise` can be reused by calling `reset()`. This puts the promise back into a `Pending` state with a new underlying promise. Note that any previous awaiters will have already resolved with the previous value; `reset()` applies to future awaiters.
+
+```ts
+import { DeferredPromise } from '@tstdl/base/promise';
+
+const gate = new DeferredPromise<void>();
+
+async function worker(id: number) {
+  console.log(`Worker ${id} waiting at gate...`);
+  await gate;
+  console.log(`Worker ${id} passed.`);
+}
+
+async function main() {
+  // First batch
+  const w1 = worker(1);
+  const w2 = worker(2);
+
+  gate.resolve();
+  await Promise.all([w1, w2]);
+
+  // Reset for next batch
+  gate.reset();
+
+  // Second batch
+  const w3 = worker(3);
+
+  setTimeout(() => {
+    console.log('Opening gate again...');
+    gate.resolve();
+  }, 500);
+
+  await w3;
+}
+
+main();
+```
+
+### Handling Cancellation Signals
+
+When implementing a `CancelablePromise`, it is crucial to respect the `cancellationSignal`. This signal is an instance of `CancellationSignal` from the `@tstdl/base/cancellation` module.
+
+```ts
+import { CancelablePromise } from '@tstdl/base/promise';
+import { CancellationToken } from '@tstdl/base/cancellation';
+
+function doWork(token: CancellationToken) {
+  return new CancelablePromise<void, string>((resolve, _, signal) => {
+    // Link the external token to the internal signal
+    const unregister = token.register(() => {
+      // If the external token is cancelled, we cancel this promise
+      // Note: In a real scenario, you might just pass 'signal' down directly
+    });
+
+    const timer = setTimeout(() => {
+      resolve();
+    }, 5000);
+
+    // Listen for cancellation on this specific promise
+    signal.register(() => {
+      clearTimeout(timer);
+      unregister();
+      console.log('Cleaned up resources due to cancellation');
+    });
+  });
+}
+```
+
+## 📚 API
+
+### Classes
+
+| Class                     | Description                                                                                                                         |
+| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |
+| `CustomPromise<T>`        | A base class extending `Promise` that exposes `resolve` and `reject` to subclasses.                                                 |
+| `DeferredPromise<T>`      | A Promise that can be resolved or rejected externally. Supports state inspection (`pending`, `resolved`, `rejected`) and resetting. |
+| `CancelablePromise<T, R>` | A Promise that wraps an operation which can be canceled. Resolves to a `CancelablePromiseResult`.                                   |
+| `LazyPromise<T>`          | A Promise that executes its logic only when awaited or when `then`/`catch`/`finally` is called.                                     |
+
+### Types & Interfaces
+
+| Type                            | Description                                                                                            |
+| :------------------------------ | :----------------------------------------------------------------------------------------------------- |
+| `PromiseExecutor<T>`            | Standard executor function signature for Promises.                                                     |
+| `CancelablePromiseExecutor<T>`  | Executor signature for `CancelablePromise`, receiving `resolve`, `reject`, and a `CancellationSignal`. |
+| `CancelablePromiseResult<T, R>` | Discriminated union result: `{ canceled: true, reason: R }` or `{ canceled: false, value: T }`.        |
+| `PromiseState`                  | Enum representing the state of a `DeferredPromise`: `Pending`, `Resolved`, `Rejected`.                 |
+
+### DeferredPromise Methods
+
+| Method                       | Description                                                                       |
+| :--------------------------- | :-------------------------------------------------------------------------------- |
+| `resolve(value: T)`          | Resolves the promise. Throws if already settled.                                  |
+| `reject(reason?: any)`       | Rejects the promise. Throws if already settled.                                   |
+| `resolveIfPending(value: T)` | Resolves the promise only if it is currently pending.                             |
+| `resolveAndReset(value: T)`  | Resolves the current promise and immediately resets it to pending for future use. |
+| `reset()`                    | Resets the promise to a pending state.                                            |
+| `pending`                    | Getter. Returns `true` if the promise is pending.                                 |
+| `resolved`                   | Getter. Returns `true` if the promise has been resolved.                          |
+| `rejected`                   | Getter. Returns `true` if the promise has been rejected.                          |
+| `settled`                    | Getter. Returns `true` if the promise is either resolved or rejected.             |
+
+### CancelablePromise Methods
+
+| Method              | Description                                                                  |
+| :------------------ | :--------------------------------------------------------------------------- |
+| `cancel(reason: R)` | Cancels the promise. The promise resolves with `{ canceled: true, reason }`. |

package/promise/cancelable-promise.js

@@ -20,7 +20,7 @@ export class CancelablePromise extends CustomPromise {
                 this.#pending = false;
             }
         };
-        executor((value) => this.#resolve(Promise.resolve(value).then((result) => ({ canceled: false, value: result }))), this.#reject, this.#cancellationToken.signal);
+        executor((value) => this.#resolve(Promise.resolve(value).then((result) => ({ canceled: false, value: result }))), this.#reject, this.#cancellationToken);
     }
     cancel(reason) {
         this.#cancellationToken.set();

package/random/README.md

@@ -0,0 +1,193 @@
+# Random
+
+A comprehensive module for deterministic, seeded random number generation and simulation of random data series. It provides high-performance algorithms like Mulberry32 and SFC32, along with utilities for generating complex, bounded random walks.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Seeded Random Number Generators](#seeded-random-number-generators)
+  - [Random Series Simulation](#random-series-simulation)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Using Mulberry32](#using-mulberry32)
+  - [Using SFC32](#using-sfc32)
+  - [Generating a Simple Series](#generating-a-simple-series)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Forking and Cloning Generators](#forking-and-cloning-generators)
+  - [Simulating Stock Charts (Complex Series)](#simulating-stock-charts-complex-series)
+  - [Cryptographically Secure Seeds](#cryptographically-secure-seeds)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Seeded RNGs**: Deterministic number generation using seeds, essential for reproducible tests and simulations.
+- **High Performance Algorithms**: Includes implementations of **Mulberry32** (fast, 32-bit state) and **SFC32** (Small Fast Counter, 128-bit state).
+- **State Management**: Capabilities to **fork** (create a new independent stream from current state) and **clone** (duplicate current state) generators.
+- **Random Series Generator**: A powerful iterator for creating random walks, stock market simulations, or sensor data with configurable volatility, bounds, and regression to the mean.
+- **Type Safety**: Fully typed TypeScript implementation.
+
+## Core Concepts
+
+### Seeded Random Number Generators
+
+Standard `Math.random()` is not seedable, making it unsuitable for scenarios where you need reproducible results (e.g., procedural generation, testing, simulations). This module provides classes extending `SeededRandomNumberGenerator` that accept initial seeds. If initialized with the same seed, they produce the exact same sequence of numbers.
+
+### Random Series Simulation
+
+The `randomSeries` function is a generator that produces a stream of numbers. It models a "random walk" where the next value depends on the previous one, modified by volatility. It supports:
+
+- **Bounds**: Keeping values within a specific range.
+- **Regression**: Automatically pulling values back towards the mean when they approach bounds.
+- **Dynamic Volatility**: Changing how erratic the series is over time.
+
+## 🚀 Basic Usage
+
+### Using Mulberry32
+
+Mulberry32 is a very fast generator with a 32-bit state. It is excellent for most non-cryptographic use cases.
+
+```ts
+import { mulberry32 } from '@tstdl/base/random';
+
+// Initialize with a specific seed for reproducibility
+const rng = mulberry32(12345);
+
+console.log(rng.next()); // Returns a float between 0 and 1
+console.log(rng.nextInt()); // Returns a 32-bit integer
+console.log(rng.next()); // Next value in the sequence
+```
+
+### Using SFC32
+
+SFC32 (Small Fast Counter) has a 128-bit state, making it suitable when a longer period is required.
+
+```ts
+import { sfc32 } from '@tstdl/base/random';
+
+// Initialize with up to 4 seeds
+const rng = sfc32(0x9e3779b9, 0x243f6a88, 0xb7e15162, 1);
+
+console.log(rng.next());
+console.log(rng.nextInt());
+```
+
+### Generating a Simple Series
+
+Generate a random walk starting at 0.
+
+```ts
+import { randomSeries } from '@tstdl/base/random';
+
+const series = randomSeries({
+  initial: 0,
+  volatility: 0.1, // 10% change per step
+});
+
+for (let i = 0; i < 5; i++) {
+  console.log(series.next().value);
+}
+// Output example: 0, 0.05, 0.048, 0.055, ...
+```
+
+## 🔧 Advanced Topics
+
+### Forking and Cloning Generators
+
+You can branch RNGs to create independent streams or save state to retry a sequence.
+
+```ts
+import { mulberry32 } from '@tstdl/base/random';
+
+const rootRng = mulberry32(500);
+
+// Fork: Creates a new RNG derived from the current state of rootRng.
+// Useful for creating separate RNGs for different game entities or threads.
+const entityRng = rootRng.fork();
+
+// Clone: Creates an exact copy of the current state.
+const savedStateRng = rootRng.clone();
+
+console.log(rootRng.next()); // 0.123...
+console.log(savedStateRng.next()); // 0.123... (Same as rootRng)
+console.log(entityRng.next()); // 0.876... (Different sequence)
+```
+
+### Simulating Stock Charts (Complex Series)
+
+You can simulate complex data like stock prices by combining bounds, regression, and dynamic volatility.
+
+```ts
+import { randomSeries } from '@tstdl/base/random';
+
+// Create a volatility provider that changes over time (e.g., market becomes more volatile)
+const volatilitySeries = randomSeries({
+  bounds: [0.01, 0.05], // Volatility between 1% and 5%
+  initial: 0.02,
+  regressionExponent: 2,
+});
+
+// Create the price series
+const stockPrice = randomSeries({
+  initial: 100,
+  bounds: [50, 150], // Price stays roughly between 50 and 150
+  volatility: volatilitySeries, // Use the dynamic volatility
+  relativeTo: 'current', // Changes are relative to the last price
+  regressionExponent: 5, // Strong pull back to mean (100) when near bounds
+});
+
+// Generate 10 data points
+for (let i = 0; i < 10; i++) {
+  console.log(`Price: ${stockPrice.next().value?.toFixed(2)}`);
+}
+```
+
+### Cryptographically Secure Seeds
+
+If you need a random seed that is cryptographically secure to initialize your PRNG (Pseudo-Random Number Generator), use the utility provided.
+
+```ts
+import { mulberry32, random32BitSeedCrypto } from '@tstdl/base/random';
+
+// Initialize Mulberry32 with a crypto-secure seed
+const secureSeed = random32BitSeedCrypto();
+const rng = mulberry32(secureSeed);
+```
+
+## 📚 API
+
+### Classes & Interfaces
+
+| Name                          | Description                                                                     |
+| :---------------------------- | :------------------------------------------------------------------------------ |
+| `RandomNumberGenerator`       | Abstract base class defining `next()` and `nextInt()`.                          |
+| `SeededRandomNumberGenerator` | Abstract class extending `RandomNumberGenerator` with `fork()` and `clone()`.   |
+| `Mulberry32`                  | Implementation of `SeededRandomNumberGenerator` using the Mulberry32 algorithm. |
+| `Sfc32`                       | Implementation of `SeededRandomNumberGenerator` using the SFC32 algorithm.      |
+
+### Functions
+
+| Name                             | Description                                                                          |
+| :------------------------------- | :----------------------------------------------------------------------------------- |
+| `mulberry32(seed?)`              | Factory function to create a `Mulberry32` instance.                                  |
+| `sfc32(seed1?, seed2?, ...)`     | Factory function to create an `Sfc32` instance.                                      |
+| `randomSeries(options?)`         | Generator function that yields a sequence of numbers based on simulation parameters. |
+| `random32BitSeed()`              | Generates a random 32-bit integer using `Math.random()`.                             |
+| `random32BitSeedCrypto()`        | Generates a random 32-bit integer using the environment's crypto API.                |
+| `defaultRandomNumberGeneratorFn` | The default RNG function (uses `Math.random`).                                       |
+
+### Types
+
+#### `RandomNumberGeneratorFn`
+
+A function that returns a random float in the range $[0, 1)$. Equivalent to `() => number`.
+
+#### `RandomSeriesOptions`
+
+| Property             | Type                             | Default          | Description                                                                                                                                              |
+| :------------------- | :------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initial`            | `number \| [number, number]`     | `bounds ?? 1`    | Initial value or range for the series. If a range is provided, a random value within it is chosen using `generator`.                                     |
+| `bounds`             | `[number, number]`               | `undefined`      | Optional `[min, max]` boundaries. When provided, a regression toward the mean is applied as values approach the edges.                                   |
+| `volatility`         | `number \| Iterator<number>`     | `0.025`          | Change factor per step. Can be a fixed number or an iterator for dynamic volatility (e.g., using another `randomSeries`).                                |
+| `relativeTo`         | `'current' \| 'initial'`         | `'initial'`      | Determines if `volatility` is applied relative to the current value or the initial value.                                                                |
+| `regressionExponent` | `number`                         | `10`             | Controls the strength of the pull back toward the mean of `bounds`. Practical values range from 0.5 to 15. High values have little pull near the mean but exponential pull near the bounds. Values < 1 stay very close to the mean. |
+| `generator`          | `RandomNumberGeneratorFn`        | `Math.random`    | The source of randomness for the series. Use a seeded generator for reproducibility.                                                                     |