@tstdl/base 0.93.138 → 0.93.140

package/cancellation/token.js

@@ -1,247 +1,178 @@
-import { BehaviorSubject, defer, filter, first, firstValueFrom, from, fromEvent, isObservable, map, skip, take } from 'rxjs';
-import { match, P } from 'ts-pattern';
+import { isDevMode } from '../core.js';
 import { registerFinalization } from '../memory/finalization.js';
+import { toArray } from '../utils/array/array.js';
 import { noop } from '../utils/noop.js';
-import { isBoolean } from '../utils/type-guards.js';
+import { assertDefinedPass, isInstanceOf, isUndefined } from '../utils/type-guards.js';
 /**
- * A read-only view of a CancellationToken's state.
- *
- * It allows consumers to subscribe to state changes, await cancellation,
- * or convert to other signal types (like AbortSignal) without being able
- * to change the token's state.
- *
- * It is both `PromiseLike<void>` (resolves when set) and `Subscribable<void>`
- * (emits when set).
+ * A CancellationSignal represents a signal that can be used to indicate cancellation of an operation.
+ * It is immutable and can be shared across multiple operations.
+ * It can be created from one or more cancellation sources, such as other signals or AbortControllers.
  */
 export class CancellationSignal {
-    _stateSubject;
+    #disposeAbortController = new AbortController();
     #abortSignal;
-    /**
-     * Observable which emits the current state (true for set, false for unset)
-     * and any subsequent state changes.
-     */
-    state$ = defer(() => this._stateSubject);
-    /**
-     * Observable which emits `void` only when the token becomes set.
-     */
-    set$ = this.state$.pipe(filter((state) => state), map(() => undefined));
-    /**
-     * Observable which emits `void` only when the token becomes unset.
-     */
-    unset$ = this.state$.pipe(filter((state) => !state), map(() => undefined));
-    /**
-     * A promise that resolves with the next state of the token.
-     */
-    get $state() {
-        // skip(1) to wait for the *next* change, not the current state.
-        return firstValueFrom(this.state$.pipe(skip(1)));
+    get abortSignal() {
+        return this.#abortSignal;
     }
-    /**
-     * A promise that resolves when the token is next set.
-     * If the token is already set, it resolves immediately.
-     */
-    get $set() {
-        return firstValueFrom(this.set$.pipe(first()));
+    get isSet() {
+        return this.abortSignal.aborted;
     }
-    /**
-     * A promise that resolves when the token is next unset.
-     * If the token is already unset, it resolves immediately.
-     */
-    get $unset() {
-        return firstValueFrom(this.unset$.pipe(first()));
+    get isUnset() {
+        return !this.isSet;
     }
-    /**
-     * The current state of the token.
-     * @returns `true` if set, `false` if unset.
-     */
-    get state() {
-        return this._stateSubject.value;
+    get reason() {
+        return this.abortSignal.reason;
     }
-    /**
-     * Whether the token is currently in a 'set' state.
-     */
-    get isSet() {
-        return this._stateSubject.value;
+    constructor(sources) {
+        const signal = sourcesToAbortSignal(sources, this.#disposeAbortController);
+        this.#abortSignal = signal;
+        if (isDevMode()) {
+            // this a development only check to catch cases where the signal is used are created but not used, which can lead to memory leaks if they are not properly disposed.
+            registerFinalization(this, (controller) => controller.abort(new Error('CancellationSignal was garbage collected while still in use. This can lead to memory leaks.')), this.#disposeAbortController);
+        }
     }
-    /**
-     * Whether the token is currently in an 'unset' state.
-     */
-    get isUnset() {
-        return !this._stateSubject.value;
+    static from(sources) {
+        return new CancellationSignal(sources);
     }
-    /**
-     * @internal
-     */
-    constructor(stateSubject) {
-        this._stateSubject = stateSubject;
+    static timeout(milliseconds) {
+        const signal = AbortSignal.timeout(milliseconds);
+        return new CancellationSignal(signal);
     }
-    /**
-     * Returns a standard `AbortSignal` that is aborted when this token is set.
-     * Useful for interoperability with APIs like `fetch`.
-     */
-    get abortSignal() {
-        return (this.#abortSignal ??= this.asAbortSignal());
+    [Symbol.dispose]() {
+        this.#disposeAbortController.abort();
     }
-    /**
-     * Returns a standard `AbortSignal` that is aborted when this token is set.
-     * Useful for interoperability with APIs like `fetch`.
-     */
-    asAbortSignal() {
-        const abortController = new AbortController();
-        const subscription = this.set$.pipe(first()).subscribe(() => abortController.abort());
-        const signal = abortController.signal;
-        registerFinalization(signal, (subscription) => subscription.unsubscribe(), subscription);
-        return signal;
+    [Symbol.observable]() {
+        return this;
     }
-    /**
-     * Creates a new `CancellationToken` that is connected to this one.
-     * State changes from this token will propagate to the new child token.
-     * @see {@link connect}
-     */
-    createChild(config) {
-        const child = new CancellationToken();
-        this.connect(child, config);
-        return child;
+    dispose() {
+        this[Symbol.dispose]();
     }
     /**
-     * Propagates state changes from this token to a target `CancellationToken`.
-     * @param target The token to receive state updates.
-     * @param config Configuration for the connection.
+     * Creates a new CancellationToken that is also set when this signal is set.
+     * If this signal is already set, the new token will also be set.
      */
-    connect(target, config) {
-        CancellationToken.connect(this.state$, target, config);
+    fork() {
+        return new CancellationToken(this);
     }
     /**
-     * Allows this object to be awaited. The promise resolves when the token is set.
-     * Implements the `PromiseLike<void>` interface.
+     * Creates a new CancellationSignal that is set when either this signal or any of the specified parent signals are set.
+     * If any of the parent signals are already set, the new signal will also be set.
+     * @param parents The parent token or signal(s) to inherit from.
      */
-    async then(onfulfilled) {
-        await this.$set;
-        return onfulfilled?.();
+    inherit(parents) {
+        return CancellationSignal.from([this, ...toArray(parents)]);
     }
     /**
-     * Subscribes to notifications for when the token becomes set.
-     * This is an alias for `this.set$.subscribe(observer)`.
-     * Implements the `Subscribable<void>` interface.
+     * Creates a new CancellationSignal that is set when either this signal or any of the specified parent signals are set.
+     * If any of the parent signals are already set, the new signal will also be set.
+     * If no parents are provided, it simply returns this signal.
+     * @param parents The parent token or signal(s) to optionally inherit from.
      */
-    subscribe(observer) {
-        return this.set$.subscribe(observer);
+    optionallyInherit(parents) {
+        if (isUndefined(parents)) {
+            return this;
+        }
+        return this.inherit(parents);
     }
-}
-/**
- * A CancellationToken represents a unit of work that can be cancelled.
- * It can be explicitly set/unset, completed, or errored.
- *
- * You can create child tokens, connect them to other async primitives
- * (Promises, AbortSignals), and pass around its read-only `signal`
- * to consumers that should only react to cancellation, not trigger it.
- */
-export class CancellationToken extends CancellationSignal {
-    #signal;
     /**
-     * A read-only view of this token.
-     * Useful for passing to functions that should only be able to check for
-     * cancellation but not trigger it.
+     * Creates a new CancellationSignal that is set when either this signal is set or the specified timeout elapses.
+     * @param milliseconds The timeout duration in milliseconds.
      */
-    get signal() {
-        return (this.#signal ??= new CancellationSignal(this._stateSubject));
+    withTimeout(milliseconds) {
+        return this.inherit(AbortSignal.timeout(milliseconds));
     }
     /**
-     * @param initialState The initial state of the token. `false` (unset) by default.
+     * Creates a new CancellationSignal that is set when either this signal is set or the specified timeout elapses.
+     * If no timeout is provided, it simply returns this signal.
+     * @param milliseconds The timeout duration in milliseconds.
      */
-    constructor(initialState = false) {
-        const stateSubject = new BehaviorSubject(initialState);
-        super(stateSubject);
-    }
-    static from(source, config) {
-        const source$ = match(source)
-            .with(P.instanceOf(AbortSignal), (signal) => fromEvent(signal, 'abort').pipe(map(() => true)))
-            .with(P.when(isObservable), (obs) => obs.pipe(map((state) => (isBoolean(state) ? state : true))))
-            .otherwise((source) => from(source).pipe(map(() => true)));
-        const token = new CancellationToken();
-        CancellationToken.connect(source$, token, config);
-        return token;
+    withOptionalTimeout(milliseconds) {
+        if (isUndefined(milliseconds)) {
+            return this;
+        }
+        return this.withTimeout(milliseconds);
+    }
+    subscribe(observer) {
+        const signal = this.abortSignal;
+        const abortHandler = () => {
+            observer.next?.();
+            observer.complete?.();
+        };
+        if (signal.aborted) {
+            abortHandler();
+            return { unsubscribe: noop };
+        }
+        signal.addEventListener('abort', abortHandler, { once: true });
+        return {
+            unsubscribe: () => signal.removeEventListener('abort', abortHandler),
+        };
     }
     /**
-     * Connects an observable state source to a target token.
-     * @param source$ The observable providing boolean state.
-     * @param target The CancellationToken to update.
-     * @param config The connection configuration.
+     * Waits for the token to be set. Resolves or rejects when the token is set.
+     * @param options Configuration for the wait behavior.
      */
-    static connect(source$, target, config = {}) {
-        const { set = true, unset = true, complete = true, error = true, immediate = true, once = false } = config;
-        let stateObservable = source$;
-        if (!immediate) {
-            stateObservable = stateObservable.pipe(skip(1));
-        }
-        if (!set || !unset) {
-            if (set) {
-                stateObservable = stateObservable.pipe(filter((state) => state));
-            }
-            else if (unset) {
-                stateObservable = stateObservable.pipe(filter((state) => !state));
-            }
-            else {
-                stateObservable = stateObservable.pipe(filter(() => false));
+    async wait(options) {
+        const abortSignal = this.abortSignal;
+        await new Promise((resolve) => {
+            if (this.isSet) {
+                resolve();
+                return;
             }
-        }
-        if (once) {
-            stateObservable = stateObservable.pipe(take(1));
-        }
-        const subscription = stateObservable.subscribe({
-            next: (state) => target.setState(state),
-            error: error ? (errorValue) => target.error(errorValue) : noop,
-            complete: complete ? () => target.complete() : noop,
-        });
-        // Ensure the connection is torn down if the target is completed or errors.
-        target._stateSubject.subscribe({
-            error: () => subscription.unsubscribe(),
-            complete: () => subscription.unsubscribe(),
+            abortSignal.addEventListener('abort', () => resolve(), { once: true });
         });
+        if (options?.throw == true) {
+            throwIfSet(abortSignal);
+        }
     }
-    /**
-     * Makes this token a child of a parent token.
-     * State changes from the parent will propagate to this token.
-     * @param parent The token to inherit state from.
-     * @param config Configuration for the connection.
-     */
-    inherit(parent, config) {
-        CancellationToken.connect(parent.state$, this, config);
+    async waitThrow() {
+        await this.wait({ throw: true });
+    }
+    throwIfSet() {
+        throwIfSet(this.abortSignal);
+    }
+}
+/**
+ * A CancellationToken is a mutable cancellation source that can be set to signal cancellation.
+ * It extends CancellationSignal, so it can be used wherever a CancellationSignal is expected.
+ * It provides a `set()` method to signal cancellation, which will trigger any subscribers or waiters on the token or any tokens that inherit from it.
+ */
+export class CancellationToken extends CancellationSignal {
+    #controller;
+    get signal() {
         return this;
     }
     /**
-     * Sets the token's state to `true`.
-     * This signals cancellation or completion of the associated operation.
+     * Creates a new CancellationToken that is set when the parent signals.
+     * If the parent is already set, the new token will also be set.
+     * @param parents The parent token or signal(s) to inherit from.
      */
-    set() {
-        this.setState(true);
+    constructor(parents) {
+        const controller = new AbortController();
+        super([...toArray(parents ?? []), controller]);
+        this.#controller = controller;
     }
-    /**
-     * Sets the token's state to `false`.
-     * This can be used to reset the token.
-     */
-    unset() {
-        this.setState(false);
+    set(reason) {
+        const error = new Error('Operation cancelled', { cause: reason });
+        this.#controller.abort(error);
     }
-    /**
-     * Explicitly sets the state of the token.
-     * @param state `true` for set, `false` for unset.
-     */
-    setState(state) {
-        this._stateSubject.next(state);
+}
+export function sourcesToAbortSignal(...sources) {
+    const signals = sources.flat().map(getAbortSignal);
+    return (signals.length > 1)
+        ? AbortSignal.any(signals)
+        : assertDefinedPass(signals[0], 'At least one cancellation source must be provided');
+}
+function getAbortSignal(source) {
+    if (isInstanceOf(source, CancellationSignal)) {
+        return source.abortSignal;
     }
-    /**
-     * Puts the token into an errored state.
-     * All current and future subscribers will receive this error.
-     */
-    error(error) {
-        this._stateSubject.error(error);
+    if (isInstanceOf(source, AbortController)) {
+        return source.signal;
     }
-    /**
-     * Completes the token's lifecycle.
-     * No further state changes can occur. Active awaits may throw an error.
-     */
-    complete() {
-        this._stateSubject.complete();
+    return source;
+}
+function throwIfSet(signal) {
+    if (signal.aborted) {
+        throw signal.reason;
     }
 }

package/context/README.md

@@ -0,0 +1,174 @@
+# Context
+
+The **context** module provides a factory for creating type-safe, named context managers. It simplifies the management of global or scoped state by generating a suite of strongly-typed functions to set, retrieve, and assert execution contexts without manually passing arguments through the call stack.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Manual Context Management](#manual-context-management)
+  - [Concurrency Note](#concurrency-note)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type-Safe Generation**: Automatically generates functions with correct input/output types based on your context definition.
+- **Dynamic Naming**: Generates readable function names (e.g., `getCurrentUserContext`, `runInUserContext`) based on a provided string literal.
+- **Automatic Cleanup**: The `runIn...` pattern ensures the context is restored to its previous state after execution, even if errors occur.
+- **Assertion Helpers**: Built-in functions to enforce that code is running within a specific context.
+- **Zero Dependencies**: Lightweight implementation using closures.
+
+## Core Concepts
+
+This module solves the problem of "prop drilling" or passing state objects (like user sessions, transaction scopes, or configuration) through every function in a call chain.
+
+Instead of a singleton or a global variable that is hard to manage, `createContextProvider` creates a closed scope with specific accessor functions.
+
+When you create a context provider named `'Session'`, the module generates an object containing:
+
+1.  `getCurrentSessionContext`: To read the data.
+2.  `runInSessionContext`: To execute a function with that data active.
+3.  `setCurrentSessionContext`: To manually swap the context.
+4.  `isInSessionContext`: To check availability.
+5.  `assertInSessionContext`: To throw if unavailable.
+
+## 🚀 Basic Usage
+
+The most common use case is defining a context for a specific domain entity (e.g., a User or Request) and using the `runIn...` helper.
+
+```typescript
+import { createContextProvider } from '@tstdl/base/context';
+
+// 1. Define your Context type
+type UserContext = {
+  id: string;
+  username: string;
+  isAdmin: boolean;
+};
+
+// 2. Create the provider.
+// The second generic argument and the function argument must match to generate correct names.
+export const { getCurrentUserContext, runInUserContext, assertInUserContext, isInUserContext } = createContextProvider<UserContext, 'User'>('User');
+
+// 3. Define functions that rely on the context
+function performAdminTask() {
+  // Pass the function reference (performAdminTask) for better error messages if context is missing.
+  // When 'required' is true, the return type is automatically narrowed to non-nullable (UserContext).
+  const user = getCurrentUserContext(true, performAdminTask);
+
+  if (!user.isAdmin) {
+    throw new Error(`User ${user.username} is not authorized.`);
+  }
+
+  console.log(`Admin task performed by ${user.username}`);
+}
+
+function main() {
+  const adminUser: UserContext = { id: '1', username: 'alice', isAdmin: true };
+  const guestUser: UserContext = { id: '2', username: 'bob', isAdmin: false };
+
+  // 4. Run code within the context
+  runInUserContext(adminUser, () => {
+    console.log('Context is active:', isInUserContext()); // true
+    performAdminTask(); // Works
+  });
+
+  // Context is automatically cleared here
+  console.log('Context is active:', isInUserContext()); // false
+
+  // Running with a different user
+  runInUserContext(guestUser, () => {
+    try {
+      performAdminTask(); // Throws Error: User bob is not authorized
+    } catch (e) {
+      console.error(e);
+    }
+  });
+}
+
+main();
+```
+
+## 🏗️ Framework Examples
+
+The library uses this module internally to manage cross-cutting concerns without passing them explicitly through every constructor.
+
+### Dependency Injection (Resolution Context)
+
+The `injector` module uses a context to track the current resolution stack to detect circular dependencies and provide access to the resolution state.
+
+```typescript
+const { assertInResolutionContext, getCurrentResolutionContext, runInResolutionContext } = createContextProvider<ResolutionContext<any>, 'Resolution'>('Resolution');
+```
+
+### Transaction Management
+
+The ORM uses a transactional context to ensure that multiple repository calls within a `Transactional` block share the same database connection and transaction state.
+
+```typescript
+const { getCurrentTransactionalContext, runInTransactionalContext, isInTransactionalContext } = createContextProvider<TransactionalContext, 'Transactional'>('Transactional');
+```
+
+## 🔧 Advanced Topics
+
+### Manual Context Management
+
+While `runIn...` is preferred because it handles `try/finally` logic automatically, you can manage the context stack manually using `setCurrent...`. This is useful for complex setups or when the scope cannot be easily wrapped in a callback.
+
+```typescript
+import { createContextProvider } from '@tstdl/base/context';
+
+const { setCurrentConfigContext, getCurrentConfigContext } = createContextProvider<Record<string, any>, 'Config'>('Config');
+
+function initialize() {
+  // Set context and store the previous one (usually null)
+  const previous = setCurrentConfigContext({ env: 'production' });
+
+  try {
+    // Application logic...
+    console.log(getCurrentConfigContext());
+  } finally {
+    // Ideally, restore the previous context when done
+    setCurrentConfigContext(previous);
+  }
+}
+```
+
+### Concurrency Note
+
+The context provider uses a **module-level variable** (closure) to store the current state. It is **not** based on `AsyncLocalStorage`.
+
+- **Synchronous Operations**: It works perfectly for synchronous call stacks.
+- **Asynchronous Operations**: Because the state is stored in a simple variable, concurrent asynchronous operations (like handling multiple HTTP requests in parallel on the same Node.js event loop) will overwrite each other's context if they share the same provider instance.
+
+If you need context isolation across asynchronous boundaries (e.g., for a web server request context), you should use this module in conjunction with a mechanism that ensures isolation (like creating a new provider instance per request) or use a dedicated `AsyncLocalStorage` wrapper if available in your environment.
+
+## 📚 API
+
+### `createContextProvider`
+
+Creates a new context provider with named utility functions.
+
+```typescript
+function createContextProvider<Context, Name extends string>(name: Name): GeneratedContextAPI<Context, Name>;
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `Name` (string literal) | The name used to suffix the generated functions (e.g., 'User' -> `getCurrentUserContext`). |
+
+**Returns:**
+
+An object containing the following functions, where `[Name]` is replaced by the provided `name` argument:
+
+| Function Name | Signature | Description |
+| :--- | :--- | :--- |
+| `getCurrent[Name]Context` | `(required: true, debugFn: Function) => Context`<br>`(required?: false, debugFn?: Function) => Context \| null` | Retrieves the current context. If `required` is true, it returns `Context` (throws if null). `debugFn.name` is used for the error message. |
+| `setCurrent[Name]Context` | `(context: Context \| null) => Context \| null` | Sets the context to the provided value. Returns the *previous* context value. |
+| `runIn[Name]Context` | `<R>(context: Context, fn: () => R) => R` | Sets the context, executes `fn`, and then restores the previous context (even if `fn` throws). Returns the result of `fn`. |
+| `isIn[Name]Context` | `() => boolean` | Returns `true` if the current context is not null. |
+| `assertIn[Name]Context` | `(debugFnOrMessage: Function \| string) => void` | Throws an error if the current context is null. Accepts a function reference (for its name) or a custom message string. |