@youngspe/async-scope 0.1.0-dev.0

package/dist/scope/standard.js

@@ -0,0 +1,24 @@
+import { Token } from '../token.js';
+import { Scope } from '../scope.js';
+import { ScopedResources } from '../scopedResource.js';
+export class StandardScope extends Scope {
+    #resources;
+    #token;
+    #onError;
+    get token() {
+        return this.#token;
+    }
+    get resources() {
+        return this.#resources;
+    }
+    _onError(value) {
+        return this.#onError ? this.#onError(value) : super._onError(value);
+    }
+    constructor(params) {
+        super();
+        this.#token = params.token ?? Token.static;
+        this.#resources = (params.token?.isCancelled ? undefined : params.resources) ?? ScopedResources.empty;
+        this.#onError = params.onError;
+    }
+}
+//# sourceMappingURL=standard.js.map

package/dist/scope.d.ts

@@ -0,0 +1,4 @@
+export { Scope, STATIC_SCOPE } from './scope/base.ts';
+export { StandardScope } from './scope/standard.ts';
+export type { CommonScopeOptions, ScopeContext, ScopeRunOptions, ToScope } from './scope/base.ts';
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.js

@@ -0,0 +1,3 @@
+export { Scope, STATIC_SCOPE } from './scope/base.js';
+export { StandardScope } from './scope/standard.js';
+//# sourceMappingURL=scope.js.map

package/dist/scopedResource.d.ts

@@ -0,0 +1,59 @@
+import { Scope } from './scope.ts';
+import type { Token } from './token.ts';
+import type { Awaitable, Falsy } from './types.ts';
+export declare class ResourceError extends Error {
+    resource: ResourceReadKey | undefined;
+    constructor(resource?: ResourceReadKey);
+}
+interface Covariant<out T> {
+    _covariant: Covariant<T>;
+}
+interface Contravariant<in T> {
+    _contravariant: Contravariant<T>;
+}
+declare const _covariant: unique symbol;
+declare const _contravariant: unique symbol;
+export declare abstract class ResourceKey<in TIn extends TOut, out TOut = TIn> {
+    #private;
+    private _base;
+    [_covariant]: Covariant<TOut>;
+    [_contravariant]: Contravariant<TIn>;
+    static create<T>(this: void, name?: string | ((...args: never) => T) | (abstract new (...args: never) => T)): ResourceKey<T>;
+    get optional(): ResourceReadKey<TOut | undefined>;
+    static optional<K extends ResourceKey.Structured<T>, T = ResourceKey.Resolved<K>>(key: K): ResourceReadKey<T | undefined>;
+    abstract toString(): string;
+}
+export declare namespace ResourceKey {
+    type Object<T> = {
+        readonly [K in keyof T]: Structured<T[K]>;
+    };
+    type Structured<T> = ResourceReadKey<T> | Object<T> | (Falsy & (undefined extends T ? unknown : never));
+    type Resolved<K extends Structured<unknown>> = K extends Falsy ? undefined : K extends ResourceReadKey<infer T> ? T : K extends {
+        [k: string]: Structured<unknown>;
+    } ? {
+        [P in keyof K]: Resolved<K[P]>;
+    } : unknown;
+}
+export interface ResourceReadKey<out T = unknown> extends ResourceKey<never, T> {
+}
+export interface ResourceWriteKey<in T> extends ResourceKey<T, unknown> {
+}
+export declare class ScopedResources {
+    #private;
+    private constructor();
+    get<K extends ResourceKey.Structured<T>, T = ResourceKey.Resolved<K>>(key: K): T;
+    tryGet<K extends ResourceKey.Structured<T>, T = ResourceKey.Resolved<K>>(key: K): T | undefined;
+    get isEmpty(): boolean;
+    static readonly empty: ScopedResources;
+    static builder(this: void, token?: Token): ScopedResources.Builder;
+    static combine(this: void, collections: Iterable<ScopedResources | Falsy>): ScopedResources;
+}
+export declare namespace ScopedResources {
+    interface Builder {
+        inherit(parent: ScopedResources | Scope): this;
+        put<T>(key: ResourceWriteKey<T>, value: Awaitable<T>): this;
+        finish(): ScopedResources;
+    }
+}
+export {};
+//# sourceMappingURL=scopedResource.d.ts.map

package/dist/scopedResource.js

@@ -0,0 +1,242 @@
+import { joinPromises } from './join.js';
+import { Scope } from './scope.js';
+import { isAsyncDisposable, isDisposable } from './utils.js';
+export class ResourceError extends Error {
+    static {
+        this.prototype.name = this.name;
+    }
+    resource;
+    constructor(resource) {
+        super();
+        this.resource = resource;
+    }
+}
+export class ResourceKey {
+    static create(name) {
+        if (name === undefined) {
+            const { stack } = new Error();
+            name = stack?.match(/\n\s*at\s+([^\s]+)/)?.[1];
+        }
+        else if (typeof name === 'function') {
+            ({ name } = name);
+        }
+        return new StandardResourceKey(name || 'unknown');
+    }
+    #optional;
+    get optional() {
+        return (this.#optional ??= new OptionalResourceKey(this));
+    }
+    static optional(key) {
+        if (key instanceof ResourceKey)
+            return key.optional;
+        return new OptionalResourceKey(key);
+    }
+}
+class CustomResourceKey extends ResourceKey {
+}
+class StandardResourceKey extends ResourceKey {
+    name;
+    constructor(name) {
+        super();
+        this.name = name;
+    }
+    toString() {
+        return `ResourceKey(${this.name})`;
+    }
+}
+function formatKey(key, indent = '') {
+    if (!key)
+        return '∅';
+    if (key instanceof ResourceKey)
+        return String(key);
+    const parts = ['{\n'];
+    for (const [k, v] of Object.entries(key)) {
+        parts.push(indent, k, ': ', formatKey(v, indent + '  '), ',\n');
+    }
+    parts.push('}');
+    return parts.join('');
+}
+class OptionalResourceKey extends CustomResourceKey {
+    #inner;
+    constructor(inner) {
+        super();
+        this.#inner = inner;
+    }
+    _resolve(res) {
+        return [res.tryGet(this.#inner)];
+    }
+    toString() {
+        return `optional(${formatKey(this.#inner)})`;
+    }
+    get optional() {
+        return this;
+    }
+}
+export class ScopedResources {
+    #parents;
+    #items;
+    constructor() { }
+    #get(key) {
+        if (!key)
+            return [undefined];
+        if (key instanceof CustomResourceKey) {
+            return key._resolve(this);
+        }
+        if (key instanceof ResourceKey) {
+            if (this.#items?.has(key))
+                return [this.#items?.get(key)];
+            if (this.#parents) {
+                for (const parent of this.#parents) {
+                    const out = parent.#get(key);
+                    if (out)
+                        return out;
+                }
+            }
+            return new ResourceError(key);
+        }
+        const out = {};
+        for (const [prop, value] of Object.entries(key)) {
+            const resolved = this.#get(value);
+            if (resolved instanceof Error)
+                return resolved;
+            out[prop] = resolved[0];
+        }
+        return [out];
+    }
+    get(key) {
+        const out = this.#get(key);
+        if (out instanceof Error)
+            throw out;
+        return out[0];
+    }
+    tryGet(key) {
+        const out = this.#get(key);
+        if (out instanceof Error)
+            return undefined;
+        return out[0];
+    }
+    #isEmpty;
+    get isEmpty() {
+        if (this.#isEmpty)
+            return true;
+        if (this.#items?.size)
+            return false;
+        if (this.#parents) {
+            for (const parent of this.#parents) {
+                if (!parent.isEmpty)
+                    return false;
+                this.#parents.delete(parent);
+            }
+        }
+        return (this.#isEmpty = true);
+    }
+    #flatten(dest, visited) {
+        if (visited.has(this))
+            return;
+        visited.add(this);
+        if (this.#items?.size) {
+            dest.add(this);
+            const newParents = new Set();
+            const newVisited = new Set([this]);
+            const parents = this.#parents;
+            if (!parents)
+                return;
+            this.#parents = newParents;
+            for (const parent of parents) {
+                parent.#flatten(newParents, newVisited);
+            }
+            return;
+        }
+        if (!this.#parents)
+            return;
+        for (const parent of this.#parents) {
+            parent.#flatten(dest, visited);
+        }
+    }
+    static empty = Object.freeze(new this());
+    static builder(token) {
+        return new ScopedResources.#Builder(token);
+    }
+    #disposing;
+    #dispose() {
+        return (this.#disposing ??= (async () => {
+            const items = this.#items;
+            if (!items)
+                return;
+            this.#items = undefined;
+            this.#parents?.clear();
+            await joinPromises(items.values(), item => {
+                if (isDisposable(item)) {
+                    item[Symbol.dispose]();
+                    return;
+                }
+                if (isAsyncDisposable(item))
+                    return item[Symbol.asyncDispose]();
+            });
+            items.clear();
+        })());
+    }
+    static #Builder = class Builder {
+        #inherit = [];
+        #put = new Map();
+        #token;
+        constructor(token) {
+            if (token?.isCancelled) {
+                this.#inherit = this.#put = undefined;
+                return;
+            }
+            this.#token = token?.isDefused ? undefined : token;
+        }
+        inherit(parent) {
+            if (!parent)
+                return this;
+            this.#inherit?.push(parent instanceof Scope ? parent.resources : parent);
+            return this;
+        }
+        put(key, value) {
+            this.#put?.set(key, value);
+            return this;
+        }
+        finish() {
+            // Reverse the `inherit` list so that more recently-added entries take precedence.
+            const inherit = this.#inherit?.reverse();
+            const put = this.#put;
+            const token = this.#token;
+            this.#inherit = this.#put = this.#token = undefined;
+            let parents = undefined;
+            if (inherit?.length) {
+                const visited = new Set();
+                const dest = new Set();
+                inherit.forEach(r => r.#flatten(dest, visited));
+                parents = dest.size ? dest : undefined;
+            }
+            if (!put?.size && (parents?.size ?? 0 <= 1)) {
+                const parent = parents?.values().next().value;
+                if (!parent)
+                    return ScopedResources.empty;
+                if (!token)
+                    return parent;
+            }
+            const resources = new ScopedResources();
+            resources.#items = put?.size ? put : undefined;
+            resources.#parents = parents;
+            token?.add(() => resources.#dispose());
+            return resources;
+        }
+    };
+    static combine(collections) {
+        const set = new Set();
+        const visited = new Set();
+        for (const item of collections) {
+            if (!item)
+                continue;
+            item.#flatten(set, visited);
+        }
+        if (set.size > 1) {
+            const resources = new ScopedResources();
+            resources.#parents = set;
+        }
+        return set.values().next().value ?? ScopedResources.empty;
+    }
+}
+//# sourceMappingURL=scopedResource.js.map

package/dist/symbols.d.ts

@@ -0,0 +1,3 @@
+export declare const cancellableAdded: unique symbol;
+export declare const cancellableRemoved: unique symbol;
+//# sourceMappingURL=symbols.d.ts.map

package/dist/symbols.js

@@ -0,0 +1,3 @@
+export const cancellableAdded = Symbol.for('async-scope.cancellable-added');
+export const cancellableRemoved = Symbol.for('async-scope.cancellable-removed');
+//# sourceMappingURL=symbols.js.map

package/dist/timer.d.ts

@@ -0,0 +1,13 @@
+import type { CancellableOptions } from './cancel.ts';
+interface Clock {
+    setTimeout: typeof globalThis.setTimeout;
+    setInterval: typeof globalThis.setInterval;
+    clearTimeout: typeof globalThis.clearTimeout;
+    clearInterval: typeof globalThis.clearInterval;
+}
+interface TimerOptions extends CancellableOptions {
+    clock?: Clock | undefined;
+}
+export declare function delay(ms: number, options?: TimerOptions): Promise<void>;
+export {};
+//# sourceMappingURL=timer.d.ts.map

package/dist/timer.js

@@ -0,0 +1,28 @@
+import { Token } from './token.js';
+const GlobalClock = {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    setTimeout: (f, ...args) => globalThis.setTimeout(f, ...args),
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    setInterval: (f, ...args) => globalThis.setInterval(f, ...args),
+    clearTimeout: id => globalThis.clearTimeout(id),
+    clearInterval: id => globalThis.clearInterval(id),
+};
+export function delay(ms, options) {
+    const token = Token.from(options);
+    if (token.isCancelled)
+        return Promise.reject(token.error);
+    const { setTimeout, clearTimeout } = options?.clock ?? GlobalClock;
+    if (token.isDefused)
+        return new Promise(resolve => setTimeout(resolve, ms));
+    return new Promise((resolve, reject) => {
+        const sub = token.add(e => {
+            clearTimeout(id);
+            reject(e);
+        });
+        const id = setTimeout(() => {
+            sub?.dispose();
+            resolve();
+        }, ms);
+    });
+}
+//# sourceMappingURL=timer.js.map

package/dist/token/base.d.ts

@@ -0,0 +1,135 @@
+import type { CancellableOrDisposable, CancellableLike, CancellationListener, Cancellable } from '../cancel.ts';
+import type { Awaitable, Falsy } from '../types.ts';
+import { Subscription, type SubscriptionLifecycle } from '../events/sub.js';
+import type { ToScope } from '../scope.ts';
+export declare abstract class Token {
+    #private;
+    /**
+     * The reason for the cancellation if this token has already been cancelled, otherwise `undefined`.
+     *
+     * @see {@link Token#isCancelled}
+     */
+    abstract get error(): Error | undefined;
+    /** If `true`, this token has been _defused_, meaning it is guaranteed never to be cancelled. */
+    get isDefused(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * Attempts to add a single listener to this token.
+     * This is called by provided methods like {@link add} and {@link use}.
+     *
+     * @param key - an arbitrary object used as an identifier for the listener.
+     * @param listener - An object that may include any of the methods of a {@link Cancellable},
+     * {@link disposable}, or {@link AsyncDisposable}.
+     * @returns
+     * - A {@link Subscription} if either the listener was safely added or the token is defused.
+     * - `undefined` if the listener could not be safely added. This is typically due to the token being
+     *   cancelled and indicates any future attempts will also fail.
+     */
+    protected abstract addOne(listener: CancellableOrDisposable): Subscription | 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: (CancellableLike | CancellationListener)[]): Subscription | undefined;
+    use<X extends CancellableLike>(target: X): X;
+    /**
+     * Attempts to add a listener to this token.
+     * Returns the target if successfully added, or `undefined` if not added.
+     */
+    tryUse<X extends CancellableLike>(listener: X): X | undefined;
+    /**
+     * 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(): AbortSignal;
+    throwIfCancelled(): void;
+    static createController(this: void, options?: Token.CreateParams): TokenController;
+    static create(this: void, options: Token.CreateParams): Token;
+    /** A token that will never be cancelled. */
+    static get static(): Token;
+    /** @returns a token that has already been cancelled. */
+    static cancelled(reason?: unknown): Token;
+    /**
+     *
+     * @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: Iterable<Token | Falsy>): Token;
+    /** @returns a {@link Token} that is cancelled when `signal` is aborted. */
+    static fromAbortSignal(this: void, signal: AbortSignal, options?: Token.FromAbortSignalParams): Token;
+    static from(this: void, src: ToScope): Token;
+}
+export declare namespace Token {
+    interface Callbacks {
+        /**
+         * Called when the token is defused either explicitly or due to the controller getting garbage
+         * collected.
+         */
+        onDefuse?: ((this: void) => void) | undefined;
+        /**
+         * Called on {@link CancellationController.cancel}. If a promise-like is returned, no listeners will be
+         * notified of the cancellation until after the promise-like resolves.
+         *
+         * If this callback throws or rejects, the {@link CancellationController.cancel} promise will also
+         * reject after all cancellation listeners and the {@link onBeforeCancel} promise is settled
+         * if present.
+         */
+        onBeforeCancel?: ((this: void, error: Error) => Awaitable<void>) | undefined;
+        /**
+         * Called after all promises returned by cancellation listeners have either resolved or rejected.
+         *
+         * If this callback exists and returns a promise-like, the {@link CancellationController.cancel} promise
+         * will not resolve until after this promise-like is settled.
+         *
+         * If this callback throws or rejects, the {@link CancellationController.cancel} promise will
+         * also reject.
+         */
+        onAfterCancel?: ((this: void, error: Error) => Awaitable<void>) | undefined;
+    }
+    interface CreateParams extends SubscriptionLifecycle<[ctrl: TokenController], [ctrl: TokenController]>, Callbacks {
+    }
+    interface FromAbortSignalParams extends Callbacks {
+        /**
+         * Called asynchronously after the signal is aborted if any of the cancellation listeners or callbacks
+         * either throw or reject.
+         *
+         * If this is not provided, any errors thrown during cancellation will be unhandled rejections.
+         */
+        onError?: ((reason: unknown) => void) | undefined;
+    }
+}
+/**
+ * A {@link Token} that will never be cancelled.
+ * @see {@link Token.static}.
+ */
+export declare const STATIC_TOKEN: Token;
+export interface TokenController extends Cancellable, AsyncDisposable {
+    readonly token: Token;
+    readonly cancel: (this: void, reason?: unknown) => Promise<void>;
+    readonly defuse: (this: void) => void;
+}
+//# sourceMappingURL=base.d.ts.map