@youngspe/async-scope 0.1.0-dev.0

package/dist/token/base.js

@@ -0,0 +1,252 @@
+import { CancellationError, toError } from '../error.js';
+import * as Symbols from '../symbols.js';
+import { isArray, isIterable } from '../utils.js';
+import { Subscription } from '../events/sub.js';
+import { CancelEvent } from '../token.js';
+export class Token {
+    /** If `true`, this token has been _defused_, meaning it is guaranteed never to be cancelled. */
+    get isDefused() {
+        return false;
+    }
+    /**
+     * If `true`, this token has been _cancelled_, and trigger any additional listeners.
+     *
+     * This is equivalent to `token.error !== undefined`
+     *
+     * @see {@link Token#error}
+     */
+    get isCancelled() {
+        return this.error !== undefined;
+    }
+    /**
+     * Adds listeners
+     *
+     * @param listeners - listeners that should be added to this token.
+     * Each parameter may be:
+     * - A {@link CancellableLike}:
+     *   - A {@link Cancellable}
+     *   - A {@link Disposable}
+     *   - An {@link AsyncDisposable}
+     *   - A falsy value, which will be ignored
+     *   - A (possibly nested) array of any of the above.
+     * - A function that receives an {@link Error} and optionally returns a promise.
+     *
+     * @returns
+     * - A {@link Subscription} that may be used to pause, resume, or remove the provide listeners if either the listeners were safely added or the token is defused.
+     * - `undefined` if no listener could be safely added. This is typically due to the token being cancelled
+     *   and indicates any future attempts will also fail.
+     */
+    add(...listeners) {
+        if (this.isCancelled)
+            return undefined;
+        if (this.isDefused)
+            return Subscription.noop;
+        const subs = [];
+        for (let listener of listeners) {
+            if (!listener)
+                continue;
+            if (isArray(listener)) {
+                this.add(...listener);
+                continue;
+            }
+            if (typeof listener === 'function') {
+                listener = { cancel: listener };
+            }
+            const sub = this.addOne(listener);
+            if (!sub)
+                return undefined;
+            subs.push(sub);
+        }
+        return Subscription.collect(subs);
+    }
+    use(target) {
+        const { error } = this;
+        if (error)
+            throw error;
+        this.add(target);
+        return target;
+    }
+    /**
+     * Attempts to add a listener to this token.
+     * Returns the target if successfully added, or `undefined` if not added.
+     */
+    tryUse(listener) {
+        return this.add(listener) ? listener : undefined;
+    }
+    #signal;
+    /**
+     * An {@link AbortSignal} representing this token.
+     * When this token is cancelled, the returned signal will be aborted.
+     * When this token is defused, a new signal is generated on each access.
+     */
+    get signal() {
+        if (this.#signal)
+            return this.#signal;
+        if (this.isDefused) {
+            // When this is defused, generate a new AbortSignal every time so listeners that get added don't
+            // stick around.
+            return AbortSignal.any([]);
+        }
+        const { error } = this;
+        if (error)
+            return (this.#signal = AbortSignal.abort(error));
+        const ac = new AbortController();
+        const listener = {
+            cancel: ac.abort.bind(ac),
+            [Symbols.cancellableRemoved]: () => {
+                // Discard the AbortSignal on defuse so we don't keep the event listeners.
+                this.#signal = undefined;
+            },
+        };
+        this.addOne(listener);
+        return (this.#signal = ac.signal);
+    }
+    throwIfCancelled() {
+        const { error } = this;
+        if (error)
+            throw error;
+    }
+    static createController(options) {
+        return CancelEvent.createController(options);
+    }
+    static create(options) {
+        return Token.createController(options).token;
+    }
+    /** A token that will never be cancelled. */
+    static get static() {
+        return STATIC_TOKEN;
+    }
+    /** @returns a token that has already been cancelled. */
+    static cancelled(reason = new CancellationError()) {
+        return new CancelledToken(toError(reason));
+    }
+    /**
+     *
+     * @returns A {@link Token} that will be cancelled when any of the given tokens are
+     * cancelled.
+     *
+     * If present, the first token encountered that has already been called will be returned.
+     */
+    static combine(src) {
+        let last = undefined;
+        const tokens = new Set();
+        for (const item of src) {
+            if (!item)
+                continue;
+            if (item.isCancelled)
+                return item;
+            last = item;
+            if (item.isDefused)
+                continue;
+            tokens.add(item);
+        }
+        if (tokens.size > 1) {
+            return Token.create({
+                init: ctrl => {
+                    const sub = Subscription.collect(Array.from(tokens, t => t.add(ctrl)));
+                    return {
+                        resume: () => {
+                            sub.resume();
+                            return { pause: () => sub.pause() };
+                        },
+                        close: () => {
+                            sub.dispose();
+                        },
+                    };
+                },
+            });
+        }
+        const [token] = tokens;
+        return token ?? last ?? STATIC_TOKEN;
+    }
+    /** @returns a {@link Token} that is cancelled when `signal` is aborted. */
+    static fromAbortSignal(signal, options) {
+        if (signal.aborted)
+            return new CancelledToken(toError(signal.reason));
+        const { onError, ...callbacks } = options ?? {};
+        return Token.create({
+            ...callbacks,
+            init: ({ cancel }) => {
+                const onAbort = () => void cancel(signal.reason).catch(onError);
+                signal.addEventListener('abort', onAbort, { once: true });
+                return {
+                    close: () => {
+                        signal.removeEventListener('abort', onAbort);
+                    },
+                };
+            },
+        });
+    }
+    static from(src) {
+        const tokens = new Set();
+        const signals = new Set();
+        const flatten = (src) => {
+            if (!src)
+                return undefined;
+            if (src instanceof AbortSignal) {
+                if (src.aborted)
+                    return Token.cancelled(src.reason);
+                signals.add(src);
+                return undefined;
+            }
+            if (src instanceof Token) {
+                if (src.isCancelled)
+                    return src;
+                if (!src.isDefused) {
+                    tokens.add(src);
+                }
+                return undefined;
+            }
+            if (isIterable(src)) {
+                for (const item of src) {
+                    const out = flatten(item);
+                    if (out)
+                        return out;
+                }
+                return undefined;
+            }
+            return flatten(src.scope) || flatten(src.token) || flatten(src.signal);
+        };
+        const cancelled = flatten(src);
+        if (cancelled)
+            return cancelled;
+        let [signal] = signals;
+        if (signals.size > 1) {
+            signal = AbortSignal.any(Array.from(signals));
+        }
+        if (signal) {
+            tokens.add(Token.fromAbortSignal(signal));
+        }
+        return Token.combine(tokens);
+    }
+}
+/** Singleton class for {@link STATIC_TOKEN}. */
+class StaticToken extends Token {
+    get error() {
+        return undefined;
+    }
+    get isDefused() {
+        return true;
+    }
+    addOne() {
+        return Subscription.noop;
+    }
+}
+/**
+ * A {@link Token} that will never be cancelled.
+ * @see {@link Token.static}.
+ */
+export const STATIC_TOKEN = new StaticToken();
+/**
+ * A {@link Token} that is already cancelled.
+ * @see {@link Token.cancelled}
+ */
+class CancelledToken extends Token {
+    error = new Error();
+    constructor(error) {
+        super();
+        this.error = error;
+    }
+    addOne() { }
+}
+//# sourceMappingURL=base.js.map

package/dist/token.d.ts

@@ -0,0 +1,4 @@
+export { Token, STATIC_TOKEN } from './token/base.ts';
+export { CancelEvent } from './events/cancel.ts';
+export type { TokenController } from './token/base.ts';
+//# sourceMappingURL=token.d.ts.map

package/dist/token.js

@@ -0,0 +1,3 @@
+export { Token, STATIC_TOKEN } from './token/base.js';
+export { CancelEvent } from './events/cancel.js';
+//# sourceMappingURL=token.js.map

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * A value that yields `T` when awaited. Useful for functions that take either the value itself or a
+ * promise that yields it.
+ *
+ * @template T The type of the value returned by `value` when awaited.
+ *
+ * @example
+ * function asyncMultiply(lhs: Awaitable<number>, rhs: Awaitable<number>) {
+ *   const [l, r] = await Promise.all([lhs, rhs]);
+ *   return l * r;
+ * }
+ *
+ */
+export type Awaitable<T> = T | Promise<T> | PromiseLike<T>;
+/**
+ * A value that's treated like `false` in conditional operations like `if` or `&&`
+ *
+ * More permissive APIs may accept falsy values and treat them as empty or undefined.
+ *
+ * @example
+ * interface Node { value: number }
+ *
+ * const nodes: Node[] = [];
+ *
+ * function addNode(node: Node | Falsy) {
+ *   if (node) {
+ *     nodes.push(node);
+ *   }
+ * }
+ *
+ * // Generate some nodes:
+ * const exampleNodes = [-2,1,4,-6,-3,-2,5].map(value => ({ value }));
+ *
+ * // Add only the nodes with a positive value.
+ * // When the value is negative, `node.value > 0 && node` will evaluate to `false`.
+ * exampleNodes.forEach(node => addNode(node.value > 0 && node));
+ *
+ */
+export type Falsy = false | null | undefined | 0 | 0n | '';
+/** If `--exactOptionalProperties` is enabled, evaluates to `Then`. Otherwise `Else`. */
+export type IfExactOptionalPropertiesEnabled<Then, Else> = {
+    x: undefined;
+} extends {
+    x?: never;
+} ? Else : Then;
+/** Evalutes to `Then` if `T` is `never`, otherwise `Else`. */
+type IfNever<T, Then, Else> = (T extends any ? Else : never) | (Then & ([T] extends [never] ? unknown : never));
+/**
+ * Evaluates to `never` if `T` is `never`, otherwise `U`.
+ *
+ * @example
+ *
+ * // This type may or may not contain an error value of type `E`:
+ * type State<E> = Ready | Failed<E>;
+ * type Ready = { status: 'ready', value: number }
+ * // When `E` is `never`, `Failed<E>` is also never thanks to `OrNever<E>`:
+ * type Failed<E> = { status: 'failed'; error: E } & OrNever<E>;
+ *
+ * // This means when `E` is `never`, the type `State<never>` evaluates to
+ * // `Ready` to correctly reflect that it can never be in the `Failed` state.
+ *
+ * // Given a function with this signature:
+ * function createState<E>(): State<E> {
+ *   return { value: 0 }
+ * }
+ *
+ * // The following operation is valid because we have specified there will
+ * // never be an error:
+ * const { value } = createState<never>();
+ */
+export type OrNever<T, U = unknown> = IfNever<T, never, U>;
+/** Evaluates to `T`, unless `T` is never, in which case it evaluates to `Else`. */
+export type UnlessNeverElse<T, Else> = [T] extends [never] ? Else : T;
+type _OptionalUndefinedParams<A extends any[], R extends any[]> = {
+    [K in keyof R]: undefined;
+} extends R ? A extends [...infer L, ...R] ? [
+    ...L,
+    ...Partial<R>
+] : A : R extends [any, ...infer Rest] ? _OptionalUndefinedParams<A, Rest> : A;
+export type OptionalUndefinedParams<A extends any[]> = _OptionalUndefinedParams<A, A>;
+type SimplifyObject<T> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * Makes properties of `T` that may be `undefined` optional.
+ * Useful for a params/options object for a function when a value might not be required depending
+ * on the type parameters.
+ *
+ * @example
+ *
+ * interface MyParams<T, U> {
+ *   items: T[]
+ *   // This property may be undefined if a `T` is already a valid `U`, but
+ *   // as-is you'll still need to include `transform: undefined` in your options.
+ *   transform: ((value: T) => U) | (T extends U ? undefined : never);
+ * }
+ *
+ * function myMap<T, U = T>({
+ *   items,
+ *   transform,
+ * }: OptionalUndefinedProps<MyParams<T, U>>): U[] {
+ *   return transform ? items.map(transform) : items as (T & U)[]
+ * }
+ *
+ * const strings = myMap({
+ *   items: [1, 2, 3],
+ *   transform: String,
+ * }); // ['1', '2', '3']
+ *
+ * // `transform` is not required because `T` and `U` are both `number`.
+ * const unchanged = myMap({ items: [1, 2, 3] }); // [1, 2, 3]
+ */
+export type OptionalUndefinedProps<T> = SimplifyObject<Partial<T> & {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+}>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,51 @@
+import type { Awaitable, UnlessNeverElse } from './types.ts';
+/**
+ * Gets the base {@link Iterable} types for each constituent of union type `I` that is an iterable.
+ * Discards all non-iterable constituents.
+ *
+ * This is a helper for {@linkcode AsIterable}.
+ */
+type ExtractIterable<I> = I extends Iterable<infer X, infer Y, infer Z> ? Iterable<X, Y, Z> : never;
+/**
+ * If `I` or any of its union constituents extend {@link Iterable}, evaluates to the base iterable
+ * type of `I` or its constituents.
+ * Otherwise, evaluates to {@linkcode Iterable|Iterable<unknown, unknown, any>}.
+ *
+ * This is used in the predicate type of {@linkcode isIterable} to narrow a type down to
+ * {@link Iterable} while preserving the most likely `yield`, `return`, and `next` types.
+ */
+type AsIterable<I> = UnlessNeverElse<ExtractIterable<I>, Iterable<unknown, unknown, any>>;
+export declare function isIterable<T>(value: T | AsIterable<T> | null | undefined): value is AsIterable<T>;
+export declare function isPromiseLike<T>(value: Awaitable<T> | null | undefined): value is PromiseLike<T>;
+/** @returns `true` if `value` has a {@linkcode Symbol.dispose} method. */
+export declare function isDisposable(value: unknown): value is Disposable;
+/** @returns `true` if `value` has a {@linkcode Symbol.asyncDispose} method. */
+export declare function isAsyncDisposable(value: unknown): value is AsyncDisposable;
+/**
+ * Gets the base {@link Array} types for each constituent of union type `I` that is an array.
+ * Discards all non-array constituents.
+ *
+ * This is a helper for {@linkcode AsArray}.
+ */
+type ExtractArray<I> = I extends Array<infer X> ? X[] : I extends ReadonlyArray<infer X> ? readonly X[] : never;
+/**
+ * If `I` or any of its union constituents extend {@link Array} or {@link ReadonlyArray}, evaluates
+ * to the base array type of `I` or its constituents.
+ * Otherwise, evaluates to `unknown[]`.
+ *
+ * This is used in the predicate type of {@linkcode isArray} to narrow a type down to {@link Array}
+ * while preserving the most likely element type.
+ */
+type AsArray<I> = UnlessNeverElse<ExtractArray<I>, unknown[]>;
+interface IsArrayFunction {
+    <I>(value: I | AsArray<I> | null | undefined): value is AsArray<I>;
+}
+/**
+ * @returns `true` if {@link value} is an array.
+ *
+ * @remarks
+ * This is an alias for {@link Array.isArray} but the types work out better for readonly arrays.
+ */
+export declare const isArray: IsArrayFunction;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,20 @@
+export function isIterable(value) {
+    return typeof value?.[Symbol.iterator] === 'function';
+}
+export function isPromiseLike(value) {
+    return typeof value?.then === 'function';
+}
+export function isDisposable(value) {
+    return typeof value?.[Symbol.dispose] === 'function';
+}
+export function isAsyncDisposable(value) {
+    return typeof value?.[Symbol.asyncDispose] === 'function';
+}
+/**
+ * @returns `true` if {@link value} is an array.
+ *
+ * @remarks
+ * This is an alias for {@link Array.isArray} but the types work out better for readonly arrays.
+ */
+export const isArray = Array.isArray.bind(Array);
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@youngspe/async-scope",
+  "version": "0.1.0-dev.0",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./events": "./dist/events.js"
+  },
+  "type": "module",
+  "devDependencies": {
+    "knip": "^6.3.0"
+  },
+  "files": [
+    "./dist",
+    "!**/*.map",
+    "!**/*.test.*"
+  ],
+  "scripts": {
+    "test": "tsgo -b tsconfig.test.json --noCheck && node --expose-gc --enable-source-maps --test \"./dist/**/*.test.js\""
+  }
+}