@youngspe/async-scope 0.1.0-dev.0

package/dist/cancel.d.ts

@@ -0,0 +1,24 @@
+import { Subscription } from './events/sub.js';
+import type { ToScope } from './scope.ts';
+import type * as Symbols from './symbols.ts';
+import type { Awaitable, Falsy } from './types.ts';
+export interface CancellableParent {
+}
+export interface Cancellable {
+    cancel(reason: Error): Awaitable<void>;
+    /** Return false to prevent the parent from adding this cancellable. */
+    [Symbols.cancellableAdded]?(key: CancellableParent, sub: Subscription): boolean | void;
+    [Symbols.cancellableRemoved]?(key: CancellableParent): void;
+}
+export type CancellableLike = Cancellable | Falsy | Disposable | AsyncDisposable | readonly CancellableLike[];
+export type CancellationListener = (reason: Error) => Awaitable<void>;
+export declare function cancelObject(target: CancellableOrDisposable, reason: Error): Promise<void>;
+export declare function cancel(target: CancellableLike, reason?: Error): Promise<void>;
+export interface CancellableOrDisposable extends Partial<Cancellable>, Partial<Disposable>, Partial<AsyncDisposable> {
+}
+export interface CancellableOptions {
+    scope?: ToScope;
+    token?: ToScope;
+    signal?: AbortSignal | undefined;
+}
+//# sourceMappingURL=cancel.d.ts.map

package/dist/cancel.js

@@ -0,0 +1,27 @@
+import { CancellationError } from './error.js';
+import { Subscription } from './events/sub.js';
+import { whenAllSettled } from './join.js';
+import { isArray } from './utils.js';
+export async function cancelObject(target, reason) {
+    if (typeof target.cancel === 'function') {
+        await target.cancel(reason);
+        return;
+    }
+    if (typeof target[Symbol.asyncDispose] === 'function') {
+        await target[Symbol.asyncDispose]();
+        return;
+    }
+    if (typeof target[Symbol.dispose] === 'function') {
+        target[Symbol.dispose]();
+        return;
+    }
+}
+export function cancel(target, reason = new CancellationError()) {
+    if (!target)
+        return Promise.resolve();
+    if (isArray(target)) {
+        return whenAllSettled(target, t => cancel(t, reason));
+    }
+    return cancelObject(target, reason);
+}
+//# sourceMappingURL=cancel.js.map

package/dist/error.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Represents an operation that has been cancelled but not necessarily due to a failure.
+ */
+export declare class CancellationError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    /** An arbitrary value attached to the error */
+    value?: unknown;
+}
+type ToError<T> = Error extends T ? Error : T extends Error ? T : Error;
+/**
+ * Converts `value` to an {@link Error}.
+ * This is intended for use during cancellation, so the fallback type is {@link CancellationError}.
+ *
+ * @param value - The value to convert.
+ * @returns An Error instance. When `value` is:
+ * - An {@link Error} instance, `value` itself.
+ * - `undefined` or an empty {@link Iterable}, a plain {@link CancellationError}
+ * - A `string`, a {@link CancellationError} with `value` as the message.
+ * - An {@link Iterable} yielding exactly one item, the output of this function applied to the item
+ * - Any other {@link Iterable}, an {@link AggregateError} containing the items with this function
+ *   recursively applied to them.
+ * - Any other value, a {@link CancellationError} with the {@link CancellationError.value|value} property
+ *   set to `value`.
+ */
+export declare function toError<T>(value: T): ToError<T>;
+/**
+ * Combines an iterator of errors into a single value.
+ *
+ * @param errors
+ * @returns
+ * - if `errors` contains zero non-`undefined` items, `undefined`.
+ * - if `errors` contains exactly one distinct non-undefined value, that value.
+ * - otherwise, an {@link AggregateError} of the items in `errors`, after removing `undefined` values and duplicates.
+ */
+export declare function combineErrors(errors: Iterable<unknown>): unknown;
+export {};
+//# sourceMappingURL=error.d.ts.map

package/dist/error.js

@@ -0,0 +1,74 @@
+import { isArray, isIterable } from './utils.js';
+/**
+ * Represents an operation that has been cancelled but not necessarily due to a failure.
+ */
+export class CancellationError extends Error {
+    static {
+        this.prototype.name = 'CancellationError';
+    }
+    static [Symbol.hasInstance](value) {
+        return ((value instanceof Error && value.name === this.prototype.name)
+            || Function.prototype[Symbol.hasInstance].call(this, value));
+    }
+    /** An arbitrary value attached to the error */
+    value;
+}
+export function toError(value) {
+    const errors = new Set();
+    const inner = (value) => {
+        if (value instanceof Error)
+            return value;
+        if (value === undefined)
+            return;
+        if (typeof value === 'string')
+            return new CancellationError(value);
+        if (isIterable(value)) {
+            for (const item of value) {
+                const ret = inner(item);
+                if (ret) {
+                    errors.add(ret);
+                }
+            }
+            return;
+        }
+        let msg;
+        if (typeof value === 'function') {
+            msg = value.name;
+        }
+        else if (value === null
+            || typeof value !== 'object'
+            || (typeof value.toString === 'function' && value.toString !== Object.prototype.toString)) {
+            // eslint-disable-next-line @typescript-eslint/no-base-to-string
+            msg = String(value);
+        }
+        return Object.assign(new CancellationError(msg), { value });
+    };
+    let error = inner(value);
+    if (error)
+        return error;
+    if (errors.size > 1)
+        return new AggregateError(errors);
+    [error] = errors;
+    return error ?? new CancellationError();
+}
+/**
+ * Combines an iterator of errors into a single value.
+ *
+ * @param errors
+ * @returns
+ * - if `errors` contains zero non-`undefined` items, `undefined`.
+ * - if `errors` contains exactly one distinct non-undefined value, that value.
+ * - otherwise, an {@link AggregateError} of the items in `errors`, after removing `undefined` values and duplicates.
+ */
+export function combineErrors(errors) {
+    if (isArray(errors) && errors.length <= 1)
+        return errors[0];
+    const errorSet = errors instanceof Set ? errors : new Set(errors);
+    errorSet.delete(undefined);
+    if (errorSet.size <= 1) {
+        const [error] = errorSet.values();
+        return error;
+    }
+    return new AggregateError(errorSet);
+}
+//# sourceMappingURL=error.js.map

package/dist/events/cancel.d.ts

@@ -0,0 +1,13 @@
+import { type CancellableOrDisposable } from '../cancel.ts';
+import { Token, type TokenController } from '../token.ts';
+import type { Awaitable } from '../types.ts';
+import { GenericEventEmitter } from './generic.ts';
+import { type Subscription } from './sub.ts';
+export declare class CancelEvent extends Token {
+    #private;
+    constructor(inner: GenericEventEmitter<Error, Awaitable<void>>);
+    get error(): Error | undefined;
+    protected addOne(listener: CancellableOrDisposable): Subscription | undefined;
+    static createController(this: void, params?: Token.CreateParams): TokenController;
+}
+//# sourceMappingURL=cancel.d.ts.map

package/dist/events/cancel.js

@@ -0,0 +1,123 @@
+import { cancelObject } from '../cancel.js';
+import { combineErrors, toError } from '../error.js';
+import * as Symbols from '../symbols.js';
+import { joinPromises } from '../join.js';
+import { Token } from '../token.js';
+import { GenericEventEmitter } from './generic.js';
+import {} from './sub.js';
+export class CancelEvent extends Token {
+    #inner;
+    #error;
+    #key = {};
+    constructor(inner) {
+        super();
+        this.#inner = inner;
+    }
+    get error() {
+        return this.#error;
+    }
+    addOne(listener) {
+        if (this.#error)
+            return undefined;
+        const sub = this.#inner.add(e => cancelObject(listener, e), {
+            once: true,
+            onRemove: listener[Symbols.cancellableRemoved]
+                && (() => void listener[Symbols.cancellableRemoved]?.(this.#key)),
+        });
+        if (sub.isActive) {
+            listener[Symbols.cancellableAdded]?.(this.#key, sub);
+        }
+        return sub;
+    }
+    static #Controller = class Controller {
+        #inner;
+        #parentSubs = new Map();
+        #promise;
+        #callbacks;
+        constructor(inner, callbacks) {
+            this.#inner = inner;
+            this.#callbacks = callbacks;
+            this.token = new CancelEvent(inner.emitter);
+        }
+        token;
+        cancel = (reason) => (this.#promise ??= (async error => {
+            this.token.#error = error;
+            const callbacks = this.#callbacks;
+            const { onBeforeCancel, onAfterCancel } = callbacks;
+            callbacks.onBeforeCancel = callbacks.onAfterCancel = callbacks.onDefuse = undefined;
+            const errors = new Set();
+            try {
+                await onBeforeCancel?.(error);
+            }
+            catch (e) {
+                errors.add(e);
+            }
+            await joinPromises(this.#inner.getListeners().listeners(), l => l(error), undefined, e => errors.add(e));
+            try {
+                await onAfterCancel?.(error);
+            }
+            catch (e) {
+                errors.add(e);
+            }
+            if (errors.size)
+                throw combineErrors(errors);
+        })(toError(reason)));
+        defuse = () => this.#inner.dispose();
+        [Symbols.cancellableAdded] = (key, sub) => {
+            if (this.token.isDefused || this.token.isCancelled || this.#parentSubs.has(key))
+                return false;
+            this.#parentSubs.set(key, sub);
+            return true;
+        };
+        [Symbols.cancellableRemoved] = (key) => {
+            this.#parentSubs.delete(key);
+        };
+        [Symbol.asyncDispose] = this.cancel;
+        static createInner({ onAfterCancel, onBeforeCancel, onDefuse, init, dispose, }) {
+            const callbacks = { onBeforeCancel, onAfterCancel, onDefuse };
+            return GenericEventEmitter.createController({
+                context: ctrl => new CancelEvent.#Controller(ctrl, callbacks),
+                init: ({ context }) => {
+                    const parents = context.#parentSubs;
+                    const _init = init?.(context);
+                    return {
+                        resume: ({ context }) => {
+                            const parents = context.#parentSubs;
+                            for (const sub of parents.values()) {
+                                sub.resume();
+                            }
+                            const _resume = _init?.resume?.(context);
+                            return {
+                                pause: () => {
+                                    try {
+                                        _resume?.pause?.();
+                                    }
+                                    finally {
+                                        parents.forEach(sub => sub.pause());
+                                    }
+                                },
+                            };
+                        },
+                        close: () => {
+                            parents.forEach(sub => sub.dispose());
+                            parents.clear();
+                            try {
+                                _init?.close?.();
+                            }
+                            finally {
+                                const { onDefuse } = callbacks;
+                                callbacks.onBeforeCancel = callbacks.onAfterCancel = callbacks.onDefuse = undefined;
+                                onDefuse?.();
+                            }
+                        },
+                    };
+                },
+                dispose,
+            });
+        }
+    };
+    static createController(params = {}) {
+        return CancelEvent.#Controller.createInner(params).context;
+    }
+}
+//# sourceMappingURL=cancel.js.map

package/dist/events/generic.d.ts

@@ -0,0 +1,51 @@
+import type { OptionalUndefinedProps } from '../types.ts';
+import { type SubscriptionLifecycle, Subscription } from './sub.ts';
+export interface EventListenerKey {
+}
+export type MaybePromise<T, Async extends boolean> = T | (Async extends true ? Promise<T> : never);
+export type Awaitable<T> = T | Promise<T> | PromiseLike<T>;
+export interface ListenerSet<T, Ret> extends Disposable {
+    get isEmpty(): boolean;
+    listeners(): Generator<(value: T) => Ret, void, void>;
+    listenersReversed(): Generator<(value: T) => Ret, void, void>;
+    call(value: T): Generator<Ret, void, void>;
+    callReversed(value: T): Generator<Ret, void, void>;
+    popFront(): ((value: T) => Ret) | undefined;
+    popBack(): ((value: T) => Ret) | undefined;
+}
+export interface GenericEventController<T, Ret = void, Async extends boolean = false, Context = void> extends Disposable {
+    readonly emitter: GenericEventEmitter<T, Ret>;
+    readonly getListeners: (this: void) => MaybePromise<ListenerSet<T, Ret>, Async>;
+    readonly dispose: (this: void) => void;
+    get context(): Context;
+}
+export type GenericEventEmitterParams<T, Ret, Async extends boolean = false, Context = void> = OptionalUndefinedProps<GenericEventEmitterParams.Base<T, Ret, Async, Context>>;
+export declare namespace GenericEventEmitterParams {
+    interface Base<T, Ret, Async extends boolean, Context> extends GenericEventLifecycle<T, Ret, Async, Context> {
+        context: ((ctrl: GenericEventController<T, Ret, Async>) => Context) | (undefined extends Context ? undefined : never);
+        isAsync: Async | (false extends Async ? undefined : never);
+    }
+}
+type GenericEventLifecycle<T, Ret, Async extends boolean, Context> = SubscriptionLifecycle<[
+    controller: GenericEventController<T, Ret, Async, Context>
+], [
+    controller: GenericEventController<T, Ret, Async, Context>
+]>;
+export interface AddListenerOptions {
+    signal?: AbortSignal | undefined;
+    once?: boolean | undefined;
+    key?: EventListenerKey | undefined;
+    onRemove?: (() => void) | undefined;
+}
+export declare class GenericEventEmitter<T, Ret = void> {
+    #private;
+    private constructor();
+    get isDisposed(): boolean;
+    add(listener: (this: void, value: T) => Ret, options?: AddListenerOptions): Subscription;
+    has(key: EventListenerKey | undefined | null): boolean;
+    remove(key: EventListenerKey | undefined | null): boolean;
+    static createController<T, Ret = void, Async extends boolean = false, Context = void>(this: void, params: GenericEventEmitterParams<T, Ret, Async, Context>): GenericEventController<T, Ret, Async, Context>;
+    static create<T, Ret = void, Async extends boolean = false>(this: void, params: GenericEventEmitterParams<T, Ret, Async>): GenericEventEmitter<T, Ret>;
+}
+export {};
+//# sourceMappingURL=generic.d.ts.map

package/dist/events/generic.js

@@ -0,0 +1,316 @@
+import { SubscriptionLifecycleManager, Subscription } from './sub.js';
+function wrapListener(listener) {
+    let _listener = listener;
+    let out;
+    return value => {
+        const l = _listener;
+        _listener = undefined;
+        if (l) {
+            out = l(value);
+        }
+        return out;
+    };
+}
+class ListenerSetImpl {
+    #handlers;
+    #onRemove;
+    #onDispose;
+    #released = false;
+    constructor(handlers, onRemove, onDispose) {
+        this.#handlers = handlers;
+        this.#onRemove = onRemove;
+        this.#onDispose = onDispose;
+    }
+    static create(handlers, { onRemove, onDispose }) {
+        return new ListenerSetImpl(handlers?.filter(h => !h.paused), onRemove, onDispose);
+    }
+    static EMPTY = new this(undefined, undefined, undefined);
+    get isEmpty() {
+        return !this.#handlers?.length;
+    }
+    #removeIfNeeded(handler) {
+        if (handler.once) {
+            const { dispose } = handler;
+            handler.listener = handler.dispose = undefined;
+            this.#onRemove?.call(undefined, handler);
+            dispose?.();
+        }
+    }
+    #cleanupHandlersIfNeeded() {
+        if (this.#handlers?.length)
+            return;
+        this.#handlers = this.#onRemove = undefined;
+    }
+    *listeners() {
+        let listener;
+        while ((listener = this.popFront())) {
+            yield listener;
+        }
+    }
+    *listenersReversed() {
+        let listener;
+        while ((listener = this.popBack())) {
+            yield listener;
+        }
+    }
+    *call(value) {
+        let listener;
+        while ((listener = this.popFront())) {
+            yield listener(value);
+        }
+    }
+    *callReversed(value) {
+        let listener;
+        while ((listener = this.popBack())) {
+            yield listener(value);
+        }
+    }
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        const onDispose = this.#onDispose;
+        this.#onDispose = undefined;
+        onDispose?.();
+    }
+    dispose() {
+        this.#handlers = this.#onRemove = undefined;
+        this.release();
+    }
+    [Symbol.dispose]() {
+        return this.dispose();
+    }
+    popFront() {
+        let handler;
+        while ((handler = this.#handlers?.shift())) {
+            const { listener, paused } = handler;
+            if (paused || !listener)
+                continue;
+            this.#removeIfNeeded(handler);
+            return wrapListener(listener);
+        }
+        this.#cleanupHandlersIfNeeded();
+    }
+    popBack() {
+        let handler;
+        while ((handler = this.#handlers?.pop())) {
+            const { listener, paused } = handler;
+            if (paused || !listener)
+                continue;
+            this.#removeIfNeeded(handler);
+            return listener;
+        }
+        this.#cleanupHandlersIfNeeded();
+    }
+}
+const controllerFinalizationRegistry = new FinalizationRegistry((state) => state.dispose());
+class GenericEventEmitterState {
+    handlers = new Map();
+    #activeCount = 0;
+    #lifecycle;
+    controller;
+    constructor(lifecycle) {
+        this.#lifecycle = new SubscriptionLifecycleManager(lifecycle);
+    }
+    #getLifecycleArgs() {
+        const controller = this.controller?.deref();
+        if (!controller)
+            return undefined;
+        return [controller];
+    }
+    addHandler(handler) {
+        if (!this.handlers)
+            return 'disposed';
+        if (this.handlers.has(handler.key))
+            return;
+        const { paused } = handler;
+        if (!paused && this.#activeCount++ === 0) {
+            const args = this.#getLifecycleArgs();
+            if (!args)
+                return;
+            this.#lifecycle.init(...args).resume(...args);
+        }
+        this.handlers.set(handler.key, handler);
+        return;
+    }
+    removeHandler(key) {
+        if (!this.handlers)
+            return false;
+        const handler = this.handlers.get(key);
+        if (!handler)
+            return false;
+        this.handlers.delete(key);
+        const { paused } = handler;
+        handler.dispose?.();
+        if (!paused && --this.#activeCount === 0) {
+            this.#lifecycle.pause();
+        }
+        return true;
+    }
+    resumeHandler(key) {
+        const handler = this.handlers?.get(key);
+        if (!handler)
+            return;
+        const { paused } = handler;
+        handler.paused = false;
+        if (paused && this.#activeCount++ === 0) {
+            const args = this.#getLifecycleArgs();
+            if (!args)
+                return;
+            this.#lifecycle.init(...args).resume(...args);
+        }
+    }
+    pauseHandler(key) {
+        const handler = this.handlers?.get(key);
+        if (!handler)
+            return;
+        const { paused } = handler;
+        handler.paused = true;
+        if (!paused && --this.#activeCount === 0) {
+            this.#lifecycle.pause();
+        }
+    }
+    dispose() {
+        controllerFinalizationRegistry.unregister(this);
+        const handlers = this.handlers;
+        this.handlers = undefined;
+        if (!handlers)
+            return;
+        for (const handler of handlers.values()) {
+            const { dispose } = handler;
+            handler.dispose = handler.listener = undefined;
+            dispose?.();
+        }
+        handlers.clear();
+        this.#lifecycle.dispose();
+    }
+}
+export class GenericEventEmitter {
+    #state;
+    constructor(state) {
+        this.#state = state;
+    }
+    get isDisposed() {
+        return !this.#state?.deref()?.handlers;
+    }
+    add(listener, options) {
+        const { signal, onRemove, once = false } = options ?? {};
+        if (signal?.aborted)
+            return Subscription.noop;
+        let _state = this.#state;
+        const state = _state?.deref();
+        if (!state)
+            return Subscription.noop;
+        if (options?.key != null) {
+            state.removeHandler(options.key);
+        }
+        const key = options?.key ?? {};
+        const handler = { key, listener, once, paused: false };
+        const sub = Subscription.fromLifecycle({
+            init: () => ({
+                resume: first => {
+                    if (!first) {
+                        _state?.deref()?.resumeHandler(key);
+                    }
+                    return { pause: () => _state?.deref()?.pauseHandler(key) };
+                },
+            }),
+            dispose: () => {
+                const s = _state;
+                _state = undefined;
+                s?.deref()?.removeHandler(key);
+            },
+            isActive: () => !!_state?.deref()?.handlers?.has(key),
+        });
+        let removeSignal = undefined;
+        if (signal) {
+            const onAbort = () => sub.dispose();
+            signal.addEventListener('abort', onAbort, { once: true });
+            removeSignal = () => signal.removeEventListener('abort', onAbort);
+        }
+        handler.dispose =
+            onRemove && removeSignal ?
+                () => {
+                    try {
+                        removeSignal();
+                    }
+                    finally {
+                        onRemove();
+                    }
+                }
+                : onRemove || removeSignal;
+        state.addHandler(handler);
+        return sub;
+    }
+    has(key) {
+        return key != null && !!this.#state?.deref()?.handlers?.has(key);
+    }
+    remove(key) {
+        if (key == null)
+            return false;
+        return this.#state?.deref()?.removeHandler(key) ?? false;
+    }
+    static #Controller = class Controller {
+        #state;
+        #inUse = false;
+        #notifyQueue = [];
+        #isAsync;
+        #context;
+        #getContext;
+        constructor(params) {
+            const { context, isAsync, ...lifecycle } = params;
+            this.#isAsync = isAsync ?? false;
+            this.#state = new GenericEventEmitterState(lifecycle);
+            this.#state.controller = new WeakRef(this);
+            this.emitter = new GenericEventEmitter(new WeakRef(this.#state));
+            this.#getContext = context;
+            controllerFinalizationRegistry.register(this, this.#state, this.#state);
+        }
+        emitter;
+        getListeners = () => {
+            let onDispose;
+            const inner = () => {
+                this.#inUse = this.#isAsync;
+                const handlers = this.#state.handlers && Array.from(this.#state.handlers.values());
+                if (!handlers && !onDispose)
+                    return ListenerSetImpl.EMPTY;
+                return ListenerSetImpl.create(handlers, {
+                    onRemove: handlers && (({ key }) => void this.#state.removeHandler(key)),
+                    onDispose,
+                });
+            };
+            if (this.#isAsync) {
+                onDispose = () => {
+                    const next = this.#notifyQueue.shift();
+                    if (next) {
+                        next();
+                    }
+                    else {
+                        this.#inUse = false;
+                    }
+                };
+                if (this.#inUse) {
+                    return new Promise(resolve => void this.#notifyQueue.push(resolve)).then(inner);
+                }
+            }
+            return inner();
+        };
+        dispose = () => this.#state.dispose();
+        [Symbol.dispose] = this.dispose;
+        get context() {
+            const cx = this.#getContext;
+            if (cx) {
+                this.#getContext = undefined;
+                this.#context = cx(this);
+            }
+            return this.#context;
+        }
+    };
+    static createController(params) {
+        return new GenericEventEmitter.#Controller(params);
+    }
+    static create(params) {
+        return GenericEventEmitter.createController(params).emitter;
+    }
+}
+//# sourceMappingURL=generic.js.map