@tstdl/base 0.92.166 → 0.92.168

package/cancellation/token.d.ts

@@ -1,138 +1,201 @@
 import { BehaviorSubject, type Observable, type Observer, type Subscribable, type Unsubscribable } from 'rxjs';
+/**
+ * Configuration for connecting a source to a CancellationToken.
+ */
 export type ConnectConfig = {
     /**
-     * Propagate parent set to child.
+     * Propagate 'set' (true) states to the child token.
      * @default true
      */
     set?: boolean;
     /**
-     * Propagate unset to child.
+     * Propagate 'unset' (false) states to the child token.
      * @default true
      */
     unset?: boolean;
     /**
-     * Propagate complete to child.
+     * Propagate the 'complete' event to the child token.
      * @default true
      */
     complete?: boolean;
     /**
-     * Propagate errors to child.
+     * Propagate errors to the child token.
      * @default true
      */
     error?: boolean;
     /**
-     * Update state immediately and don't wait for next state change.
+     * Immediately apply the source's current state upon connection.
+     * If false, waits for the next state change.
      * @default true
      */
     immediate?: boolean;
     /**
-     * Only update the state once (if immediate is also true it basically just sets the same value).
+     * Only propagate the first applicable state change, then disconnect.
      * @default false
      */
     once?: 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).
+ */
 export declare class CancellationSignal implements PromiseLike<void>, Subscribable<void> {
-    #private;
+    protected readonly _stateSubject: BehaviorSubject<boolean>;
     /**
-     * Observable which emits the current state and every state change.
+     * Observable which emits the current state (true for set, false for unset)
+     * and any subsequent state changes.
      */
     readonly state$: Observable<boolean>;
     /**
-     * Observable which emits when this token is set.
+     * Observable which emits `void` only when the token becomes set.
      */
     readonly set$: Observable<void>;
     /**
-     * Observable which emits when this token is unset.
+     * Observable which emits `void` only when the token becomes unset.
      */
     readonly unset$: Observable<void>;
     /**
-     * Returns a promise which is resolved when this token changes its state.
+     * A promise that resolves with the next state of the token.
      */
     get $state(): Promise<boolean>;
     /**
-     * Returns a promise which is resolved when this token is set.
+     * A promise that resolves when the token is next set.
+     * If the token is already set, it resolves immediately.
      */
     get $set(): Promise<void>;
     /**
-     * Returns a promise which is resolved when this token is unset.
+     * 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 this token is set.
+     * Whether the token is currently in a 'set' state.
      */
     get isSet(): boolean;
     /**
-     * Whether this token is unset.
+     * Whether the token is currently in an 'unset' state.
      */
     get isUnset(): boolean;
+    /**
+     * @internal
+     */
     constructor(stateSubject: BehaviorSubject<boolean>);
     /**
-     * Returns an AbortSignal.
+     * Returns a standard `AbortSignal` that is aborted when this token is set.
+     * Useful for interoperability with APIs like `fetch`.
      */
     asAbortSignal(): AbortSignal;
     /**
-     * Create a new token and connect it to this instance.
+     * 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?: ConnectConfig): CancellationToken;
     /**
-     * Propagate events from this instance to `target`. Events from the `target` are *not* propagated to this instance.
-     * @param target receiver to connect
+     * Propagates state changes from this token to a target `CancellationToken`.
+     * @param target The token to receive state updates.
+     * @param config Configuration for the connection.
      */
     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>;
+    /**
+     * Subscribes to notifications for when the token becomes set.
+     * This is an alias for `this.set$.subscribe(observer)`.
+     * Implements the `Subscribable<void>` interface.
+     */
     subscribe(observer: Partial<Observer<void>>): Unsubscribable;
 }
+/**
+ * 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 declare class CancellationToken extends CancellationSignal {
     #private;
-    /** Signal for this token */
+    /**
+     * 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 which state to initialze this token to
-     * - `false`: unset
-     * - `true`: set
-     * @default false
+     * @param initialState The initial state of the token. `false` (unset) by default.
      */
     constructor(initialState?: boolean);
     /**
-     * Creates a token and sets it whenever the source signals
-     * @param source source to listen to
-     * @param complete complete token after signal
+     * 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>, options?: {
-        complete?: boolean;
-    }): CancellationToken;
+    static from(source: AbortSignal | PromiseLike<any> | Observable<void>, config?: ConnectConfig): CancellationToken;
     /**
-     * Creates a token and connects the source to its next, error and complete.
-     * @param observable observable to subscribe. Takes emitted value as state if type is boolean otherwise sets state to true.
+     * 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;
-    static connect(state$: Observable<boolean>, target: CancellationToken, config?: ConnectConfig): void;
     /**
-     * Become a child of the provided parent. Events from the parent are propagated to this token. Events from this token are *not* propagated to the parent.
+     * 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;
     /**
-     * Set this token.
+     * Sets the token's state to `true`.
+     * This signals cancellation or completion of the associated operation.
      */
     set(): void;
     /**
-     * Unset this token.
+     * Sets the token's state to `false`.
+     * This can be used to reset the token.
      */
     unset(): void;
     /**
-     * Set the state.
+     * Explicitly sets the state of the token.
+     * @param state `true` for set, `false` for unset.
      */
     setState(state: boolean): void;
     /**
-     * Errors the token.
+     * Puts the token into an errored state.
+     * All current and future subscribers will receive this error.
      */
     error(error: Error): void;
     /**
-     * Clean up subscriptions.
-     *
-     * Keep in mind that *active* awaits (promise) on this token will throw.
+     * Completes the token's lifecycle.
+     * No further state changes can occur. Active awaits may throw an error.
      */
     complete(): void;
 }

package/cancellation/token.js

@@ -1,67 +1,93 @@
 import { BehaviorSubject, defer, filter, first, firstValueFrom, from, fromEvent, isObservable, map, skip, take } from 'rxjs';
-import { noopOperator } from '../rxjs-utils/noop.js';
+import { match, P } from 'ts-pattern';
+import { registerFinalization } from '../memory/finalization.js';
 import { noop } from '../utils/noop.js';
 import { isBoolean } 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).
+ */
 export class CancellationSignal {
-    #stateSubject;
+    _stateSubject;
     /**
-     * Observable which emits the current state and every state change.
+     * Observable which emits the current state (true for set, false for unset)
+     * and any subsequent state changes.
      */
-    state$ = defer(() => this.#stateSubject);
+    state$ = defer(() => this._stateSubject);
     /**
-     * Observable which emits when this token is set.
+     * Observable which emits `void` only when the token becomes set.
      */
     set$ = this.state$.pipe(filter((state) => state), map(() => undefined));
     /**
-     * Observable which emits when this token is unset.
+     * Observable which emits `void` only when the token becomes unset.
      */
     unset$ = this.state$.pipe(filter((state) => !state), map(() => undefined));
     /**
-     * Returns a promise which is resolved when this token changes its state.
+     * 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)));
     }
     /**
-     * Returns a promise which is resolved when this token is set.
+     * 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$);
+        return firstValueFrom(this.set$.pipe(first()));
     }
     /**
-     * Returns a promise which is resolved when this token is unset.
+     * 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$);
+        return firstValueFrom(this.unset$.pipe(first()));
     }
+    /**
+     * The current state of the token.
+     * @returns `true` if set, `false` if unset.
+     */
     get state() {
-        return this.#stateSubject.value;
+        return this._stateSubject.value;
     }
     /**
-     * Whether this token is set.
+     * Whether the token is currently in a 'set' state.
      */
     get isSet() {
-        return this.#stateSubject.value;
+        return this._stateSubject.value;
     }
     /**
-     * Whether this token is unset.
+     * Whether the token is currently in an 'unset' state.
      */
     get isUnset() {
-        return !this.#stateSubject.value;
+        return !this._stateSubject.value;
     }
+    /**
+     * @internal
+     */
     constructor(stateSubject) {
-        this.#stateSubject = stateSubject;
+        this._stateSubject = stateSubject;
     }
     /**
-     * Returns an AbortSignal.
+     * Returns a standard `AbortSignal` that is aborted when this token is set.
+     * Useful for interoperability with APIs like `fetch`.
      */
     asAbortSignal() {
         const abortController = new AbortController();
-        this.set$.pipe(first()).subscribe(() => abortController.abort());
-        return abortController.signal;
+        const subscription = this.set$.pipe(first()).subscribe(() => abortController.abort());
+        const signal = abortController.signal;
+        registerFinalization(signal, (subscription) => subscription.unsubscribe(), subscription);
+        return signal;
     }
     /**
-     * Create a new token and connect it to this instance.
+     * 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) {
@@ -70,99 +96,144 @@ export class CancellationSignal {
         return child;
     }
     /**
-     * Propagate events from this instance to `target`. Events from the `target` are *not* propagated to this instance.
-     * @param target receiver to connect
+     * Propagates state changes from this token to a target `CancellationToken`.
+     * @param target The token to receive state updates.
+     * @param config Configuration for the connection.
      */
     connect(target, config) {
         CancellationToken.connect(this.state$, target, config);
     }
+    /**
+     * Allows this object to be awaited. The promise resolves when the token is set.
+     * Implements the `PromiseLike<void>` interface.
+     */
     async then(onfulfilled) {
         await this.$set;
         return onfulfilled?.();
     }
+    /**
+     * Subscribes to notifications for when the token becomes set.
+     * This is an alias for `this.set$.subscribe(observer)`.
+     * Implements the `Subscribable<void>` interface.
+     */
     subscribe(observer) {
         return this.set$.subscribe(observer);
     }
 }
+/**
+ * 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 {
-    #stateSubject;
     #signal;
-    /** Signal for this token */
+    /**
+     * 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() {
-        return (this.#signal ??= new CancellationSignal(this.#stateSubject));
+        return (this.#signal ??= new CancellationSignal(this._stateSubject));
     }
     /**
-     * @param initialState which state to initialze this token to
-     * - `false`: unset
-     * - `true`: set
-     * @default false
+     * @param initialState The initial state of the token. `false` (unset) by default.
      */
     constructor(initialState = false) {
         const stateSubject = new BehaviorSubject(initialState);
         super(stateSubject);
-        this.#stateSubject = stateSubject;
     }
     static from(source, config) {
-        const source$ = (source instanceof AbortSignal) ? fromEvent(source, 'abort', () => true)
-            : isObservable(source) ? source.pipe(map((state) => (isBoolean(state) ? state : true)))
-                : from(source).pipe(map(() => true));
+        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;
     }
-    static connect(state$, target, config = {}) {
+    /**
+     * 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$, target, config = {}) {
         const { set = true, unset = true, complete = true, error = true, immediate = true, once = false } = config;
-        const stateObservable = state$
-            .pipe(immediate ? noopOperator() : skip(1), (set && unset) ? noopOperator() : set ? filter((state) => state) : unset ? filter((state) => !state) : filter(() => false), once ? take(1) : noopOperator());
+        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));
+            }
+        }
+        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,
+            error: error ? (errorValue) => target.error(errorValue) : noop,
+            complete: complete ? () => target.complete() : noop,
         });
-        target.#stateSubject.subscribe({
+        // Ensure the connection is torn down if the target is completed or errors.
+        target._stateSubject.subscribe({
             error: () => subscription.unsubscribe(),
             complete: () => subscription.unsubscribe(),
         });
     }
     /**
-     * Become a child of the provided parent. Events from the parent are propagated to this token. Events from this token are *not* propagated to the parent.
+     * 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) {
-        const { state$ } = (parent instanceof CancellationToken) ? parent.signal : parent;
-        CancellationToken.connect(state$, this, config);
+        CancellationToken.connect(parent.state$, this, config);
         return this;
     }
     /**
-     * Set this token.
+     * Sets the token's state to `true`.
+     * This signals cancellation or completion of the associated operation.
      */
     set() {
         this.setState(true);
     }
     /**
-     * Unset this token.
+     * Sets the token's state to `false`.
+     * This can be used to reset the token.
      */
     unset() {
         this.setState(false);
     }
     /**
-     * Set the state.
+     * Explicitly sets the state of the token.
+     * @param state `true` for set, `false` for unset.
      */
     setState(state) {
-        this.#stateSubject.next(state);
+        this._stateSubject.next(state);
     }
     /**
-     * Errors the token.
+     * Puts the token into an errored state.
+     * All current and future subscribers will receive this error.
      */
     error(error) {
-        this.#stateSubject.error(error);
+        this._stateSubject.error(error);
     }
     /**
-     * Clean up subscriptions.
-     *
-     * Keep in mind that *active* awaits (promise) on this token will throw.
+     * Completes the token's lifecycle.
+     * No further state changes can occur. Active awaits may throw an error.
      */
     complete() {
-        this.#stateSubject.complete();
+        this._stateSubject.complete();
     }
 }
-// export { CancellationSignal as ReadonlyCancellationToken };

package/core.d.ts

@@ -1,11 +1,7 @@
-import type { CancellationSignal } from './cancellation/token.js';
-import { Injector } from './injector/injector.js';
-import { type InjectionToken } from './injector/token.js';
-import { LogLevel, Logger, type LoggerArgument } from './logger/index.js';
+import { Injector } from './injector/index.js';
 declare global {
     var tstdlLoaded: boolean | undefined;
 }
-export declare const CORE_LOGGER: InjectionToken<Logger, never>;
 /**
  * @deprecated Usage of `getGlobalInjector` should be avoided. Use `Application` scoped injector instead.
  */
@@ -13,11 +9,3 @@ export declare function getGlobalInjector(): Injector;
 export declare function isDevMode(): boolean;
 export declare function isProdMode(): boolean;
 export declare function enableProdMode(): void;
-export declare function connect(name: string, connectFunction: (() => Promise<any>), logger: Logger, cancellationSignal: CancellationSignal, maxTries?: number): Promise<void>;
-export type CoreConfiguration = {
-    production?: boolean;
-    logger?: InjectionToken<Logger, LoggerArgument>;
-    logLevel?: LogLevel;
-    coreLogPrefix?: string;
-};
-export declare function configureTstdl(config?: CoreConfiguration): void;

package/core.js

@@ -1,16 +1,8 @@
-import { Injector } from './injector/injector.js';
-import { injectionToken } from './injector/token.js';
-import { ConsoleLogger } from './logger/console/logger.js';
-import { LogLevel, Logger } from './logger/index.js';
-import { LOG_LEVEL } from './logger/tokens.js';
-import { initializeSignals, setProcessShutdownLogger } from './process-shutdown.js';
-import { timeout } from './utils/timing.js';
-import { assertDefinedPass, isDefined } from './utils/type-guards.js';
+import { Injector } from './injector/index.js';
 if (globalThis.tstdlLoaded == true) {
     console.error(new Error('tstdl seems to be loaded multiple times. This is likely an error as some modules won\'t work as intended this way.'));
 }
 globalThis.tstdlLoaded = true;
-export const CORE_LOGGER = injectionToken('core logger');
 let globalInjector;
 let _isDevMode = true;
 /**
@@ -28,40 +20,3 @@ export function isProdMode() {
 export function enableProdMode() {
     _isDevMode = false;
 }
-export async function connect(name, connectFunction, logger, cancellationSignal, maxTries = 5) {
-    let triesLeft = maxTries;
-    let success = false;
-    while (!success && cancellationSignal.isUnset && triesLeft-- > 0) {
-        try {
-            logger.verbose(`connecting to ${name}...`);
-            await connectFunction();
-            success = true;
-            logger.info(`connected to ${name}`);
-        }
-        catch (error) {
-            logger.verbose(`error connecting to ${name}${triesLeft > 0 ? ', trying again...' : ''}`);
-            logger.error(error);
-            if (triesLeft == 0) {
-                throw new Error(`Failed to connect to ${name} - no tries left.`);
-            }
-            await timeout(3000);
-        }
-    }
-}
-let coreLogPrefix;
-export function configureTstdl(config = {}) {
-    if (config.production == true) {
-        enableProdMode();
-    }
-    const logger = getGlobalInjector().resolve(CORE_LOGGER);
-    setProcessShutdownLogger(logger);
-    initializeSignals();
-    Injector.register(Logger, { useToken: config.logger ?? ConsoleLogger });
-    Injector.register(LOG_LEVEL, { useFactory: (level) => assertDefinedPass(level, 'LogLevel argument not provided') }, { defaultArgumentProvider: () => config.logLevel ?? LogLevel.Trace });
-    if (isDefined(config.coreLogPrefix)) {
-        coreLogPrefix = config.coreLogPrefix;
-    }
-}
-Injector.register(Logger, { useToken: ConsoleLogger });
-Injector.register(LOG_LEVEL, { useValue: LogLevel.Trace });
-Injector.register(CORE_LOGGER, { useToken: Logger, defaultArgumentProvider: () => coreLogPrefix });

package/disposable/disposable.d.ts

@@ -1,11 +1,3 @@
-export declare const dispose: typeof Symbol.dispose;
-export declare const disposeAsync: typeof Symbol.asyncDispose;
-export interface Disposable {
-    [Symbol.dispose](): void;
-}
-export interface AsyncDisposable {
-    [Symbol.asyncDispose](): PromiseLike<void>;
-}
 export declare function isDisposable(object: any): object is Disposable;
 export declare function isAsyncDisposable(object: any): object is AsyncDisposable;
 export declare function isSyncOrAsyncDisposable(object: any): object is Disposable | AsyncDisposable;

package/disposable/disposable.js

@@ -1,6 +1,4 @@
 import { isFunction } from '../utils/type-guards.js';
-export const dispose = Symbol.dispose;
-export const disposeAsync = Symbol.asyncDispose;
 export function isDisposable(object) {
     return isFunction(object?.[Symbol.dispose]);
 }
@@ -8,5 +6,5 @@ export function isAsyncDisposable(object) {
     return isFunction(object?.[Symbol.asyncDispose]);
 }
 export function isSyncOrAsyncDisposable(object) {
-    return isFunction(object?.[Symbol.dispose] ?? object?.[Symbol.asyncDispose]);
+    return isDisposable(object) || isAsyncDisposable(object);
 }

package/disposable/index.d.ts

@@ -1,8 +1,2 @@
-/**
- * Dispose pattern
- *
- * @module Disposable
- */
-export * from './async-disposer.js';
 export * from './disposable.js';
 export * from './using.js';

package/disposable/index.js

@@ -1,8 +1,2 @@
-/**
- * Dispose pattern
- *
- * @module Disposable
- */
-export * from './async-disposer.js';
 export * from './disposable.js';
 export * from './using.js';