@tstdl/base 0.93.138 → 0.93.140

package/cancellation/tests/token.test.js

@@ -0,0 +1,136 @@
+import '../../polyfills.js';
+import { firstValueFrom, from } from 'rxjs';
+import { describe, expect, it, vi } from 'vitest';
+import { CancellationSignal, CancellationToken } from '../token.js';
+describe('CancellationToken', () => {
+    it('should be unset by default', () => {
+        const token = new CancellationToken();
+        expect(token.isSet).toBe(false);
+        expect(token.isUnset).toBe(true);
+    });
+    it('should be set when set() is called', () => {
+        const token = new CancellationToken();
+        token.set('reason');
+        expect(token.isSet).toBe(true);
+        expect(token.isUnset).toBe(false);
+        expect(token.reason).toBeInstanceOf(Error);
+        expect(token.reason.message).toBe('Operation cancelled');
+        expect(token.reason.cause).toBe('reason');
+    });
+    it('should fork a new token', () => {
+        const parent = new CancellationToken();
+        const child = parent.fork();
+        expect(child).toBeInstanceOf(CancellationToken);
+        expect(child.isSet).toBe(false);
+        parent.set();
+        expect(child.isSet).toBe(true);
+    });
+    it('should support multiple parents', () => {
+        const parent1 = new CancellationToken();
+        const parent2 = new CancellationToken();
+        const child = new CancellationToken([parent1, parent2]);
+        expect(child.isSet).toBe(false);
+        parent2.set();
+        expect(child.isSet).toBe(true);
+    });
+    it('should support single parent', () => {
+        const parent = new CancellationToken();
+        const child = new CancellationToken(parent);
+        expect(child.isSet).toBe(false);
+        parent.set();
+        expect(child.isSet).toBe(true);
+    });
+    it('should support AbortController as a source', () => {
+        const controller = new AbortController();
+        const signal = CancellationSignal.from(controller);
+        expect(signal.isSet).toBe(false);
+        controller.abort();
+        expect(signal.isSet).toBe(true);
+    });
+    it('should support AbortSignal as a source', () => {
+        const controller = new AbortController();
+        const signal = CancellationSignal.from(controller.signal);
+        expect(signal.isSet).toBe(false);
+        controller.abort();
+        expect(signal.isSet).toBe(true);
+    });
+    it('should wait for cancellation (resolve)', async () => {
+        const token = new CancellationToken();
+        setTimeout(() => token.set(), 10);
+        await token.wait();
+        expect(token.isSet).toBe(true);
+    });
+    it('should wait and throw (waitThrow)', async () => {
+        const token = new CancellationToken();
+        setTimeout(() => token.set('foo'), 10);
+        await expect(token.waitThrow()).rejects.toThrow('Operation cancelled');
+    });
+    it('should resolve immediately if already set', async () => {
+        const token = new CancellationToken();
+        token.set();
+        await token.wait();
+        expect(token.isSet).toBe(true);
+    });
+    it('should throw immediately if already set with waitThrow', async () => {
+        const token = new CancellationToken();
+        token.set();
+        await expect(token.waitThrow()).rejects.toThrow();
+    });
+    it('should throw immediately if already set', async () => {
+        const token = new CancellationToken();
+        token.set();
+        expect(() => token.throwIfSet()).toThrow();
+    });
+    it('should not throw if not set', () => {
+        const token = new CancellationToken();
+        expect(() => token.throwIfSet()).not.toThrow();
+    });
+    it('should support timeouts', async () => {
+        const token = new CancellationToken();
+        const timedSignal = token.withTimeout(10);
+        expect(timedSignal.isSet).toBe(false);
+        await timedSignal.wait();
+        expect(timedSignal.isSet).toBe(true);
+        expect(token.isSet).toBe(false);
+    });
+    it('should be observable', async () => {
+        const token = new CancellationToken();
+        const promise = firstValueFrom(from(token));
+        token.set();
+        await promise;
+    });
+    it('should support subscribe', () => {
+        const token = new CancellationToken();
+        const next = vi.fn();
+        const complete = vi.fn();
+        const subscription = token.subscribe({ next, complete });
+        token.set();
+        expect(next).toHaveBeenCalled();
+        expect(complete).toHaveBeenCalled();
+        subscription.unsubscribe();
+    });
+    it('should support Symbol.observable', () => {
+        const token = new CancellationToken();
+        const result = token[Symbol.observable]();
+        expect(result).toBe(token);
+    });
+    it('should return self as signal', () => {
+        const token = new CancellationToken();
+        expect(token.signal).toBe(token);
+    });
+    it('should handle subscribe when already set', () => {
+        const token = new CancellationToken();
+        token.set();
+        const next = vi.fn();
+        token.subscribe({ next });
+        expect(next).toHaveBeenCalled();
+    });
+    it('should support unsubscribe', () => {
+        const token = new CancellationToken();
+        const next = vi.fn();
+        const subscription = token.subscribe({ next });
+        subscription.unsubscribe();
+        token.set();
+        expect(next).not.toHaveBeenCalled();
+    });
+});

package/cancellation/token.d.ts

@@ -1,207 +1,83 @@
-import { BehaviorSubject, type Observable, type Observer, type Subscribable, type Unsubscribable } from 'rxjs';
-/**
- * Configuration for connecting a source to a CancellationToken.
- */
-export type ConnectConfig = {
-    /**
-     * Propagate 'set' (true) states to the child token.
-     * @default true
-     */
-    set?: boolean;
-    /**
-     * Propagate 'unset' (false) states to the child token.
-     * @default true
-     */
-    unset?: boolean;
-    /**
-     * Propagate the 'complete' event to the child token.
-     * @default true
-     */
-    complete?: boolean;
-    /**
-     * Propagate errors to the child token.
-     * @default true
-     */
-    error?: boolean;
+import type { InteropObservable, Observer, Subscribable, Unsubscribable } from 'rxjs';
+import type { OneOrMany } from '../types/types.js';
+export type CancellationSource = CancellationToken | CancellationSignal | AbortController | AbortSignal;
+export type CancellationSignalWaitOptions = {
     /**
-     * Immediately apply the source's current state upon connection.
-     * If false, waits for the next state change.
-     * @default true
-     */
-    immediate?: boolean;
-    /**
-     * Only propagate the first applicable state change, then disconnect.
+     * If true, the promise returned by `wait()` will reject with the error when the token is set.
+     * If false, it will resolve normally when the token is set.
      * @default false
      */
-    once?: boolean;
+    throw?: boolean;
 };
 /**
- * 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 declare class CancellationSignal implements PromiseLike<void>, Subscribable<void> {
+export declare class CancellationSignal implements Disposable, Subscribable<void>, InteropObservable<void> {
     #private;
-    protected readonly _stateSubject: BehaviorSubject<boolean>;
-    /**
-     * Observable which emits the current state (true for set, false for unset)
-     * and any subsequent state changes.
-     */
-    readonly state$: Observable<boolean>;
-    /**
-     * Observable which emits `void` only when the token becomes set.
-     */
-    readonly set$: Observable<void>;
-    /**
-     * Observable which emits `void` only when the token becomes unset.
-     */
-    readonly unset$: Observable<void>;
-    /**
-     * A promise that resolves with the next state of the token.
-     */
-    get $state(): Promise<boolean>;
-    /**
-     * A promise that resolves when the token is next set.
-     * If the token is already set, it resolves immediately.
-     */
-    get $set(): Promise<void>;
-    /**
-     * A promise that resolves when the token is next unset.
-     * If the token is already unset, it resolves immediately.
-     */
-    get $unset(): Promise<void>;
-    /**
-     * The current state of the token.
-     * @returns `true` if set, `false` if unset.
-     */
-    get state(): boolean;
-    /**
-     * Whether the token is currently in a 'set' state.
-     */
+    get abortSignal(): AbortSignal;
     get isSet(): boolean;
-    /**
-     * Whether the token is currently in an 'unset' state.
-     */
     get isUnset(): boolean;
+    get reason(): any;
+    constructor(sources: OneOrMany<CancellationSource>);
+    static from(sources: OneOrMany<CancellationSource>): CancellationSignal;
+    static timeout(milliseconds: number): CancellationSignal;
+    [Symbol.dispose](): void;
+    [Symbol.observable](): Subscribable<void>;
+    dispose(): void;
     /**
-     * @internal
+     * 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.
      */
-    constructor(stateSubject: BehaviorSubject<boolean>);
+    fork(): CancellationToken;
     /**
-     * Returns a standard `AbortSignal` that is aborted when this token is set.
-     * Useful for interoperability with APIs like `fetch`.
+     * 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.
      */
-    get abortSignal(): AbortSignal;
+    inherit(parents: OneOrMany<CancellationSource>): CancellationSignal;
     /**
-     * Returns a standard `AbortSignal` that is aborted when this token is set.
-     * Useful for interoperability with APIs like `fetch`.
+     * 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.
      */
-    asAbortSignal(): AbortSignal;
+    optionallyInherit(parents?: OneOrMany<CancellationSource>): CancellationSignal;
     /**
-     * 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}
+     * 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.
      */
-    createChild(config?: ConnectConfig): CancellationToken;
+    withTimeout(milliseconds: number): CancellationSignal;
     /**
-     * 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 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.
      */
-    connect(target: CancellationToken, config?: ConnectConfig): void;
-    /**
-     * Allows this object to be awaited. The promise resolves when the token is set.
-     * Implements the `PromiseLike<void>` interface.
-     */
-    then<TResult>(onfulfilled?: ((value: void) => TResult | PromiseLike<TResult>) | null): Promise<TResult>;
+    withOptionalTimeout(milliseconds?: number): CancellationSignal;
+    subscribe(observer: Partial<Observer<void>>): Unsubscribable;
     /**
-     * Subscribes to notifications for when the token becomes set.
-     * This is an alias for `this.set$.subscribe(observer)`.
-     * Implements the `Subscribable<void>` interface.
+     * Waits for the token to be set. Resolves or rejects when the token is set.
+     * @param options Configuration for the wait behavior.
      */
-    subscribe(observer: Partial<Observer<void>>): Unsubscribable;
+    wait(options?: CancellationSignalWaitOptions): Promise<void>;
+    waitThrow(): Promise<void>;
+    throwIfSet(): void;
 }
 /**
- * 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.
+ * 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 declare class CancellationToken extends CancellationSignal {
     #private;
-    /**
-     * 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.
-     */
     get signal(): CancellationSignal;
     /**
-     * @param initialState The initial state of the token. `false` (unset) by default.
-     */
-    constructor(initialState?: boolean);
-    /**
-     * Creates a token that is set when the source signals.
-     * @param source The event source to listen to.
-     * @example
-     * // From a fetch promise
-     * const token = CancellationToken.from(fetch('/api/data'));
-     *
-     * // From a browser AbortSignal
-     * const controller = new AbortController();
-     * const token = CancellationToken.from(controller.signal);
-     */
-    static from(source: AbortSignal | PromiseLike<any> | Observable<void>, config?: ConnectConfig): CancellationToken;
-    /**
-     * Creates a token and connects it to an `Observable<boolean>` source.
-     * The token's state will mirror the boolean values emitted by the observable.
-     * @param source The observable source.
-     * @param config Configuration for the connection.
-     */
-    static from(source: Observable<boolean>, config?: ConnectConfig): CancellationToken;
-    /**
-     * 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.
-     */
-    static connect(source$: Observable<boolean>, target: CancellationToken, config?: ConnectConfig): void;
-    /**
-     * 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: CancellationToken | CancellationSignal, config?: ConnectConfig): this;
-    /**
-     * Sets the token's state to `true`.
-     * This signals cancellation or completion of the associated operation.
-     */
-    set(): void;
-    /**
-     * Sets the token's state to `false`.
-     * This can be used to reset the token.
-     */
-    unset(): void;
-    /**
-     * Explicitly sets the state of the token.
-     * @param state `true` for set, `false` for unset.
-     */
-    setState(state: boolean): void;
-    /**
-     * Puts the token into an errored state.
-     * All current and future subscribers will receive this error.
-     */
-    error(error: Error): void;
-    /**
-     * Completes the token's lifecycle.
-     * No further state changes can occur. Active awaits may throw an error.
+     * 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.
      */
-    complete(): void;
+    constructor(parents?: OneOrMany<CancellationSource>);
+    set(reason?: any): void;
 }
+export declare function sourcesToAbortSignal(...sources: OneOrMany<CancellationSource>[]): AbortSignal;