@youngspe/async-scope 0.1.0-dev.0

package/dist/events/sub.d.ts

@@ -0,0 +1,64 @@
+import type { Falsy } from '../types.ts';
+export interface SubscriptionLifecycle<Init extends any[] = [], Resume extends any[] = []> {
+    init?: ((this: void, ...args: Init) => SubscriptionLifecycle.Initialized<Resume> | void) | undefined;
+    dispose?: ((this: void) => void) | undefined;
+}
+export declare namespace SubscriptionLifecycle {
+    interface Initialized<Resume extends any[] = []> {
+        resume?: ((this: void, ...args: Resume) => Resumed | void) | undefined;
+        close?: ((this: void) => void) | undefined;
+    }
+    interface Resumed {
+        pause?: ((this: void) => void) | undefined;
+    }
+}
+export declare class SubscriptionLifecycleManager<Init extends any[] = [], Resume extends any[] = []> implements SubscriptionLifecycle<Init, Resume> {
+    #private;
+    constructor(lifecycle?: SubscriptionLifecycle<Init, Resume>);
+    init: (...args: Init) => SubscriptionLifecycleManagerInit<Resume>;
+    pause: () => void;
+    close: () => void;
+    dispose: () => void;
+    [Symbol.dispose]: () => void;
+}
+declare class SubscriptionLifecycleManagerInit<Resume extends any[] = []> implements SubscriptionLifecycle.Initialized {
+    #private;
+    constructor(init?: SubscriptionLifecycle.Initialized<Resume> | void, onClose?: (this: void) => void);
+    resume: (...args: Resume) => SubscriptionLifecycleManagerResume;
+    pause: () => void;
+    close: () => void;
+    [Symbol.dispose]: () => void;
+}
+declare class SubscriptionLifecycleManagerResume implements SubscriptionLifecycle.Resumed {
+    #private;
+    constructor(resumed?: SubscriptionLifecycle.Resumed | void, onPause?: (this: void) => void);
+    pause: () => void;
+    [Symbol.dispose]: () => void;
+}
+export declare abstract class Subscription {
+    get isActive(): boolean;
+    dispose(): void;
+    pause(): void;
+    resume(): void;
+    [Symbol.dispose](): void;
+    static readonly noop: Readonly<{
+        get isActive(): boolean;
+        dispose(): void;
+        pause(): void;
+        resume(): void;
+        [Symbol.dispose](): void;
+    }>;
+    static fromDispose(this: void, dispose: (() => void) | undefined): Readonly<{
+        get isActive(): boolean;
+        dispose(): void;
+        pause(): void;
+        resume(): void;
+        [Symbol.dispose](): void;
+    }>;
+    static fromLifecycle(this: void, lifecycle: (SubscriptionLifecycle<[], [first: boolean]> & {
+        isActive?: ((this: void) => boolean) | undefined;
+    }) | (() => SubscriptionLifecycle.Initialized<[first: boolean]>) | undefined): Subscription;
+    static collect(this: void, subscriptions: Iterable<Subscription | Falsy>): Subscription;
+}
+export {};
+//# sourceMappingURL=sub.d.ts.map

package/dist/events/sub.js

@@ -0,0 +1,207 @@
+export class SubscriptionLifecycleManager {
+    #lifecycle;
+    #init;
+    constructor(lifecycle) {
+        this.#lifecycle = lifecycle || {};
+    }
+    init = (...args) => {
+        return (this.#init ??= new SubscriptionLifecycleManagerInit(this.#lifecycle?.init?.(...args), () => (this.#init = undefined)));
+    };
+    pause = () => {
+        this.#init?.pause();
+    };
+    close = () => {
+        try {
+            this.pause();
+        }
+        finally {
+            const init = this.#init;
+            this.#init = undefined;
+            init?.close?.();
+        }
+    };
+    dispose = () => {
+        try {
+            this.close();
+        }
+        finally {
+            const lifecycle = this.#lifecycle;
+            this.#lifecycle = undefined;
+            lifecycle?.dispose?.();
+        }
+    };
+    [Symbol.dispose] = this.dispose;
+}
+class SubscriptionLifecycleManagerInit {
+    #init;
+    #resumed;
+    #onClose;
+    constructor(init, onClose) {
+        this.#init = init || {};
+        this.#onClose = onClose;
+    }
+    resume = (...args) => {
+        return (this.#resumed ??= new SubscriptionLifecycleManagerResume(this.#init?.resume?.(...args), () => (this.#resumed = undefined)));
+    };
+    pause = () => {
+        this.#resumed?.pause();
+    };
+    close = () => {
+        const onClose = this.#onClose;
+        this.#onClose = undefined;
+        try {
+            try {
+                this.pause();
+            }
+            finally {
+                const init = this.#init;
+                this.#init = undefined;
+                init?.close?.();
+            }
+        }
+        finally {
+            onClose?.();
+        }
+    };
+    [Symbol.dispose] = this.close;
+}
+class SubscriptionLifecycleManagerResume {
+    #resumed;
+    #onPause;
+    constructor(resumed, onPause) {
+        this.#resumed = resumed || {};
+        this.#onPause = onPause;
+    }
+    pause = () => {
+        const resumed = this.#resumed;
+        const onPause = this.#onPause;
+        this.#resumed = this.#onPause = undefined;
+        try {
+            resumed?.pause?.();
+        }
+        finally {
+            onPause?.();
+        }
+    };
+    [Symbol.dispose] = this.pause;
+}
+export class Subscription {
+    get isActive() {
+        return false;
+    }
+    dispose() { }
+    pause() { }
+    resume() { }
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+    static noop = Object.freeze(new (class NoopSubscription extends this {
+    })());
+    static fromDispose(dispose) {
+        if (!dispose)
+            return Subscription.noop;
+        return new DisposeSubscription(dispose);
+    }
+    static fromLifecycle(lifecycle) {
+        if (!lifecycle)
+            return Subscription.noop;
+        return new LifecycleSubscription(lifecycle);
+    }
+    static collect(subscriptions) {
+        const set = new Set();
+        for (const sub of subscriptions) {
+            if (sub && sub.isActive) {
+                set.add(sub);
+            }
+        }
+        if (set.size > 1)
+            return new SubscriptionSet(set);
+        const [sub] = set;
+        return sub ?? Subscription.noop;
+    }
+}
+class DisposeSubscription extends Subscription {
+    #dispose;
+    constructor(dispose) {
+        super();
+        this.#dispose = dispose;
+    }
+    get isActive() {
+        return !!this.#dispose;
+    }
+    dispose() {
+        const dispose = this.#dispose;
+        this.#dispose = undefined;
+        dispose?.();
+    }
+}
+class LifecycleSubscription extends Subscription {
+    #lifecycle;
+    #initialized;
+    #isActive;
+    constructor(lifecycle) {
+        super();
+        if (typeof lifecycle !== 'function') {
+            this.#isActive = lifecycle?.isActive;
+        }
+        this.#lifecycle =
+            lifecycle
+                && new SubscriptionLifecycleManager(typeof lifecycle === 'function' ? { init: lifecycle } : lifecycle);
+        this.#initialized = this.#lifecycle?.init();
+        this.#initialized?.resume(true);
+    }
+    resume() {
+        this.#initialized?.resume(false);
+    }
+    pause() {
+        this.#lifecycle?.pause();
+    }
+    dispose() {
+        const lifecycle = this.#lifecycle;
+        this.#lifecycle = this.#initialized = this.#isActive = undefined;
+        lifecycle?.dispose();
+    }
+    get isActive() {
+        return !!this.#lifecycle && this.#isActive?.() !== false;
+    }
+}
+class SubscriptionSet extends Subscription {
+    #items;
+    constructor(items) {
+        super();
+        this.#items = items;
+    }
+    #forEach(action) {
+        const errors = new Set();
+        for (const item of this.#items) {
+            if (!item.isActive) {
+                this.#items.delete(item);
+                continue;
+            }
+            try {
+                action?.(item);
+            }
+            catch (e) {
+                errors.add(e);
+            }
+            if (errors.size > 1)
+                throw new AggregateError(errors);
+            if (errors.size === 1)
+                throw errors.values().next().value;
+        }
+    }
+    pause() {
+        this.#forEach(item => item.pause());
+    }
+    resume() {
+        this.#forEach(item => item.resume());
+    }
+    dispose() {
+        this.#forEach(item => item.dispose());
+    }
+    get isActive() {
+        this.#forEach();
+        return !!this.#items.size;
+    }
+}
+//# sourceMappingURL=sub.js.map

package/dist/events.d.ts

@@ -0,0 +1,3 @@
+export { GenericEventEmitter, type GenericEventEmitterParams, type GenericEventController, type AddListenerOptions, type EventListenerKey, type ListenerSet, type MaybePromise, } from './events/generic.ts';
+export { Subscription, type SubscriptionLifecycle, SubscriptionLifecycleManager } from './events/sub.ts';
+//# sourceMappingURL=events.d.ts.map

package/dist/events.js

@@ -0,0 +1,3 @@
+export { GenericEventEmitter, } from './events/generic.js';
+export { Subscription, SubscriptionLifecycleManager } from './events/sub.js';
+//# sourceMappingURL=events.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Token, type TokenController } from './token.ts';
+export { Scope, type CommonScopeOptions, type ScopeContext, type ScopeRunOptions, type ToScope, } from './scope.ts';
+export { cancel, type Cancellable, type CancellableLike, type CancellableOptions, type CancellableParent, type CancellationListener, } from './cancel.ts';
+export * as Symbols from './symbols.ts';
+export * from './events.ts';
+export { ResourceError, ResourceKey, type ResourceReadKey, type ResourceWriteKey, ScopedResources, } from './scopedResource.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,7 @@
+export { Token } from './token.js';
+export { Scope, } from './scope.js';
+export { cancel, } from './cancel.js';
+export * as Symbols from './symbols.js';
+export * from './events.js';
+export { ResourceError, ResourceKey, ScopedResources, } from './scopedResource.js';
+//# sourceMappingURL=index.js.map

package/dist/join.d.ts

@@ -0,0 +1,16 @@
+import type { Awaitable, Falsy, OptionalUndefinedParams } from './types.ts';
+type Operation<T, U> = ((value: T, index: number) => Awaitable<U>) | ([T] extends [U] ? null | undefined : never);
+export declare function joinPromises<T, U = T, Out = never, Out2 = never>(src: Iterable<Awaitable<T>> | AsyncIterable<T>, ...[operation, onResolve, onReject]: OptionalUndefinedParams<[
+    operation: Operation<T, U>,
+    onResolve: ((value: U, index: number) => Awaitable<Out | Falsy>) | null | undefined,
+    onReject: ((reason: unknown, index: number) => Awaitable<Out2 | Falsy>) | null | undefined
+]>): Promise<NonNullable<Out | Out2> | undefined>;
+/**
+ * Like `Promise.allSettled()`, this waits until all promises have settled. Like `Promise.all()`, this rejects if any promise rejects.
+ */
+export declare function whenAllSettled<T, U = T, Out = never>(src: Iterable<Awaitable<T>> | AsyncIterable<T>, ...[operation, onResolve]: OptionalUndefinedParams<[
+    operation: Operation<T, U>,
+    onResolve: ((value: U, index: number) => Awaitable<Out | Falsy>) | null | undefined
+]>): Promise<Out | undefined>;
+export {};
+//# sourceMappingURL=join.d.ts.map

package/dist/join.js

@@ -0,0 +1,85 @@
+import { isIterable, isPromiseLike } from './utils.js';
+export async function joinPromises(src, ...[operation, onResolve, onReject]) {
+    return new Promise((_resolve, _reject) => {
+        let done = false;
+        let count = 1;
+        const resolve = (value) => {
+            if (value || --count === 0) {
+                done = true;
+                _resolve(value || undefined);
+            }
+        };
+        const reject = (e) => ((done = true), _reject(e));
+        const processItem = async (_value, index) => {
+            try {
+                if (done)
+                    return;
+                let awaited;
+                try {
+                    const value = isPromiseLike(_value) ? await _value : _value;
+                    if (operation) {
+                        if (done)
+                            return;
+                        const ret = operation(value, index);
+                        awaited = isPromiseLike(ret) ? await ret : ret;
+                        if (done)
+                            return;
+                    }
+                    else {
+                        awaited = value;
+                    }
+                }
+                catch (e) {
+                    if (!onReject)
+                        return reject(e);
+                    if (done)
+                        return;
+                    return resolve(await onReject(e, index));
+                }
+                return resolve(await onResolve?.(awaited, index));
+            }
+            catch (e) {
+                return reject(e);
+            }
+        };
+        void (async () => {
+            try {
+                let i = 0;
+                if (isIterable(src)) {
+                    for (const item of src) {
+                        ++count;
+                        void processItem(item, i++);
+                        if (done)
+                            break;
+                    }
+                }
+                else {
+                    for await (const item of src) {
+                        ++count;
+                        void processItem(item, i++);
+                        if (done)
+                            break;
+                    }
+                }
+                return resolve(undefined);
+            }
+            catch (e) {
+                return reject(e);
+            }
+        })();
+    });
+}
+/**
+ * Like `Promise.allSettled()`, this waits until all promises have settled. Like `Promise.all()`, this rejects if any promise rejects.
+ */
+export async function whenAllSettled(src, ...[operation, onResolve]) {
+    const errors = new Set();
+    const out = await joinPromises(src, operation, onResolve, e => void errors.add(e));
+    if (out !== undefined)
+        return out;
+    if (errors.size > 1)
+        throw new AggregateError(errors);
+    if (errors.size === 1)
+        throw errors.values().next().value;
+}
+//# sourceMappingURL=join.js.map

package/dist/scope/base.d.ts

@@ -0,0 +1,44 @@
+import type { Awaitable, Falsy } from '../types.ts';
+import { Token } from '../token.ts';
+import { type CancellableOptions } from '../cancel.ts';
+import type { CancellableLike } from '../cancel.ts';
+import { ScopedResources } from '../scopedResource.ts';
+export interface CommonScopeOptions extends CancellableOptions {
+}
+export interface ScopeRunOptions extends CommonScopeOptions {
+}
+export interface ScopeContextBase {
+    readonly scope: Scope;
+    readonly token: Token;
+    readonly resources: ScopedResources;
+    readonly signal: AbortSignal;
+}
+export type ScopeContext<T extends object = object> = Omit<T, keyof ScopeContextBase> & ScopeContextBase;
+export declare abstract class Scope {
+    #private;
+    abstract get token(): Token;
+    abstract get resources(): ScopedResources;
+    get isClosed(): boolean;
+    get signal(): AbortSignal;
+    throwIfClosed(): void;
+    protected _onError(value: unknown): void;
+    use<T extends CancellableLike>(value: T): T;
+    tryUse<T extends CancellableLike>(value: T): T | undefined;
+    readonly scope: Scope;
+    resolveOrCancel<T>(promise: Awaitable<T>): Promise<T>;
+    /**
+     *
+     * @param block the function to run
+     * @param options
+     * @returns a promise that resolves to the result of `block`, or rejects if the scope is closed first.
+     */
+    run<R>(block: (cx: ScopeContext) => Awaitable<R>, options?: ScopeRunOptions): Promise<R>;
+    function<R, Args extends readonly unknown[]>(block: (cx: ScopeContext, ...args: Args) => Awaitable<R>, options?: ScopeRunOptions): (...args: Args) => Promise<R>;
+    withResources(block: (builder: ScopedResources.Builder) => ScopedResources.Builder | void): Scope;
+    static from(this: void, src: ToScope): Scope;
+    /** An empty scope that will never be closed. */
+    static get static(): Scope;
+}
+export declare const STATIC_SCOPE: Scope;
+export type ToScope = Scope | Token | readonly ToScope[] | Set<ToScope> | AbortSignal | CancellableOptions | Falsy;
+//# sourceMappingURL=base.d.ts.map

package/dist/scope/base.js

@@ -0,0 +1,125 @@
+import { Token, STATIC_TOKEN } from '../token.js';
+import {} from '../cancel.js';
+import { scopeFrom } from './from.js';
+import { isPromiseLike } from '../utils.js';
+import { ScopedResources } from '../scopedResource.js';
+import { StandardScope } from '../scope.js';
+export class Scope {
+    get isClosed() {
+        return this.token.isCancelled;
+    }
+    get signal() {
+        return this.token.signal;
+    }
+    throwIfClosed() {
+        this.token.throwIfCancelled();
+    }
+    _onError(value) {
+        throw value;
+    }
+    use(value) {
+        return this.token.use(value);
+    }
+    tryUse(value) {
+        return this.token.tryUse(value);
+    }
+    scope = this;
+    resolveOrCancel(promise) {
+        const { token } = this;
+        const { error } = token;
+        if (error)
+            return Promise.reject(error);
+        if (!isPromiseLike(promise))
+            return Promise.resolve(promise);
+        return new Promise((resolve, reject) => {
+            const sub = token.add(reject);
+            promise.then(x => {
+                sub?.dispose();
+                resolve(x);
+            }, e => {
+                sub?.dispose();
+                reject(e);
+            });
+        });
+    }
+    #subScope(token, options) {
+        return scopeFrom([this, token, options]);
+    }
+    /**
+     *
+     * @param block the function to run
+     * @param options
+     * @returns a promise that resolves to the result of `block`, or rejects if the scope is closed first.
+     */
+    async run(block, options) {
+        await using controller = this.use(Token.createController());
+        const subScope = this.#subScope(controller.token, options);
+        try {
+            return await subScope.resolveOrCancel(block(new Scope.#Context(subScope)));
+        }
+        catch (error) {
+            await controller.cancel(error);
+            throw error;
+        }
+    }
+    function(block, options) {
+        let _block = block;
+        const controller = this.tryUse(Token.createController());
+        if (!controller)
+            return () => Promise.reject(this.token.error);
+        const subScope = this.#subScope(controller.token, options);
+        const sub = subScope.token.add(reason => {
+            _block = reason;
+        });
+        return async (...args) => {
+            sub?.dispose();
+            if (_block instanceof Error)
+                throw _block;
+            try {
+                const ret = await subScope.resolveOrCancel(_block(new Scope.#Context(subScope), ...args));
+                await controller.cancel();
+                return ret;
+            }
+            catch (error) {
+                await controller.cancel(error);
+                throw error;
+            }
+        };
+    }
+    withResources(block) {
+        const builder = ScopedResources.builder(this.token).inherit(this.resources);
+        block(builder);
+        const resources = builder.finish();
+        return new StandardScope({ ...this, resources });
+    }
+    static from(src) {
+        return scopeFrom(src);
+    }
+    /** An empty scope that will never be closed. */
+    static get static() {
+        return STATIC_SCOPE;
+    }
+    static #Context = class Context {
+        scope;
+        get token() {
+            return this.scope.token;
+        }
+        get signal() {
+            return this.scope.signal;
+        }
+        get resources() {
+            return this.scope.resources;
+        }
+        constructor(scope) {
+            this.scope = scope;
+        }
+    };
+}
+class StaticScope extends Scope {
+    resources = ScopedResources.empty;
+    get token() {
+        return STATIC_TOKEN;
+    }
+}
+export const STATIC_SCOPE = new StaticScope();
+//# sourceMappingURL=base.js.map

package/dist/scope/from.d.ts

@@ -0,0 +1,3 @@
+import { Scope, type ToScope } from '../scope.ts';
+export declare function scopeFrom(src: ToScope, onError?: (error: unknown) => void): Scope;
+//# sourceMappingURL=from.d.ts.map

package/dist/scope/from.js

@@ -0,0 +1,87 @@
+import { Token } from '../token.js';
+import { Scope, STATIC_SCOPE, StandardScope } from '../scope.js';
+import { isArray } from '../utils.js';
+import { ScopedResources } from '../scopedResource.js';
+export function scopeFrom(src, onError) {
+    if (!src)
+        return STATIC_SCOPE;
+    if (src instanceof Scope)
+        return src;
+    if (src instanceof Token)
+        return new StandardScope({ token: src, onError });
+    if (src instanceof AbortSignal) {
+        return new StandardScope({ token: Token.fromAbortSignal(src, { onError }), onError });
+    }
+    let hasNonScopeToken = false;
+    const scopes = new Set();
+    const tokens = new Set();
+    const abortSignals = new Set();
+    const resources = new Set();
+    function flatten(src) {
+        if (!src)
+            return;
+        if (src instanceof Scope) {
+            if (src.token.isCancelled)
+                return src.token;
+            scopes.add(src);
+            if (!src.token.isDefused) {
+                tokens.add(src.token);
+            }
+            if (!src.resources.isEmpty) {
+                resources.add(src.resources);
+            }
+            return;
+        }
+        if (src instanceof Token) {
+            hasNonScopeToken = true;
+            if (src.isCancelled)
+                return src;
+            if (!src.isDefused) {
+                tokens.add(src);
+            }
+            return;
+        }
+        if (src instanceof AbortSignal) {
+            hasNonScopeToken = true;
+            if (src.aborted)
+                return Token.cancelled(src.reason);
+            abortSignals.add(src);
+            return;
+        }
+        if (isArray(src) || src instanceof Set) {
+            for (const child of src) {
+                const cancelled = flatten(child);
+                if (cancelled)
+                    return cancelled;
+            }
+            return;
+        }
+        return flatten(src.scope) || flatten(src.token) || flatten(src.signal);
+    }
+    const cancelled = flatten(src);
+    if (!hasNonScopeToken && scopes.size <= 1) {
+        // If only one scope was passed in with no other tokens, we can return the
+        // scope directly.
+        //
+        // If there are zero scopes and tokens, we can return the static scope
+        //
+        const [scope] = scopes;
+        if (!cancelled || scope?.token === cancelled)
+            return scope ?? Scope.static;
+    }
+    if (cancelled)
+        return new StandardScope({ token: cancelled });
+    let [signal] = abortSignals;
+    if (abortSignals.size > 1) {
+        signal = AbortSignal.any(Array.from(abortSignals));
+    }
+    if (signal) {
+        tokens.add(Token.fromAbortSignal(signal));
+    }
+    return new StandardScope({
+        token: Token.combine(tokens),
+        resources: ScopedResources.combine(resources),
+        onError,
+    });
+}
+//# sourceMappingURL=from.js.map

package/dist/scope/standard.d.ts

@@ -0,0 +1,15 @@
+import { Token } from '../token.ts';
+import { Scope } from '../scope.ts';
+import { ScopedResources } from '../scopedResource.js';
+export declare class StandardScope extends Scope {
+    #private;
+    get token(): Token;
+    get resources(): ScopedResources;
+    protected _onError(value: unknown): void;
+    constructor(params: {
+        token?: Token | undefined;
+        resources?: ScopedResources | undefined;
+        onError?: ((e: unknown) => void) | undefined;
+    });
+}
+//# sourceMappingURL=standard.d.ts.map