@youngspe/async-scope 0.1.0-dev.0 → 0.1.0-dev.1

package/dist/lock.js

@@ -0,0 +1,200 @@
+import { Token } from './token.js';
+class RawLock {
+    #value;
+    /** If positive, locked for reading. If negative, locked for writing. */
+    #count = 0;
+    #queue = [];
+    constructor(value) {
+        this.#value = value;
+    }
+    createReadGuard(token) {
+        let raw = this;
+        if (token?.isCancelled) {
+            raw = undefined;
+        }
+        const release = () => {
+            const _raw = raw;
+            sub?.dispose();
+            sub = raw = undefined;
+            _raw?.releaseReader();
+        };
+        let sub = token?.add(release);
+        return {
+            get value() {
+                if (!raw)
+                    throw new TypeError('Cannot read from released guard');
+                return raw.#value;
+            },
+            release,
+            [Symbol.dispose]: release,
+        };
+    }
+    createWriteGuard(token) {
+        let raw = this;
+        if (token?.isCancelled) {
+            raw = undefined;
+        }
+        const release = () => {
+            const _raw = raw;
+            sub?.dispose();
+            sub = raw = undefined;
+            _raw?.releaseWriter();
+        };
+        let sub = token?.add(release);
+        return {
+            get value() {
+                if (!raw)
+                    throw new TypeError('Cannot read from released guard');
+                return raw.#value;
+            },
+            set value(value) {
+                if (!raw)
+                    throw new TypeError('Cannot write to released guard');
+                raw.#value = value;
+            },
+            release,
+            [Symbol.dispose]: release,
+        };
+    }
+    releaseReader() {
+        if (this.#count === 0)
+            throw new TypeError('Cannot release reader lock when no readers are held');
+        if (this.#count < 0)
+            throw new TypeError('Cannot release reader lock when it is locked for writing');
+        if (this.#count > 1) {
+            --this.#count;
+            return;
+        }
+        const waiter = this.#queue.shift();
+        if (!waiter) {
+            this.#count = 0;
+            return;
+        }
+        this.#count = 1;
+        waiter.resolve(this.createReadGuard(waiter.token));
+    }
+    #getQueuedReaders() {
+        let readerCount = 0;
+        for (const waiter of this.#queue) {
+            if (waiter.kind !== 'read')
+                break;
+            ++readerCount;
+        }
+        if (readerCount === 0)
+            return;
+        return this.#queue.splice(0, readerCount);
+    }
+    releaseWriter() {
+        if (this.#count === 0)
+            throw new TypeError('Cannot release writer lock when no writers are held');
+        if (this.#count > 0)
+            throw new TypeError('Cannot release writer lock when it is locked for reading');
+        const readers = this.#getQueuedReaders();
+        if (readers) {
+            this.#count = readers.length;
+            for (const r of readers) {
+                r.resolve(this.createReadGuard(r.token));
+            }
+            return;
+        }
+        const waiter = this.#queue.shift();
+        if (!waiter) {
+            this.#count = 0;
+            return;
+        }
+        if (waiter.kind === 'write') {
+            waiter.resolve(this.createWriteGuard(waiter.token));
+            return;
+        }
+    }
+    tryAcquireReader(token) {
+        // don't acquire if there is anything in the queue because as long as the queue is not empty, it
+        // must have at least one writer
+        if (token?.isCancelled || this.#count < 0 || this.#queue.length)
+            return undefined;
+        ++this.#count;
+        return this.createReadGuard(token);
+    }
+    tryAcquireWriter(token) {
+        if (token?.isCancelled || this.#count !== 0)
+            return undefined;
+        this.#count = -1;
+        return this.createWriteGuard(token);
+    }
+    #removeWaiter(waiter) {
+        const index = this.#queue.indexOf(waiter);
+        if (index < 0)
+            return;
+        this.#queue.splice(index, 1);
+        if (index === 0 && this.#count > 0 && waiter.kind === 'write') {
+            const readers = this.#getQueuedReaders();
+            if (readers) {
+                this.#count += readers.length;
+                for (const r of readers) {
+                    r.resolve(this.createReadGuard(r.token));
+                }
+            }
+        }
+    }
+    async acquireReaderAsync(token) {
+        token?.throwIfCancelled();
+        const guard = this.tryAcquireReader(token);
+        if (guard)
+            return guard;
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                kind: 'read',
+                resolve: x => {
+                    sub?.dispose();
+                    resolve(x);
+                },
+                token,
+            };
+            const sub = token?.add(e => {
+                this.#removeWaiter(waiter);
+                reject(e);
+            });
+            this.#queue.push(waiter);
+        });
+    }
+    async acquireWriterAsync(token) {
+        token?.throwIfCancelled();
+        const guard = this.tryAcquireWriter(token);
+        if (guard)
+            return guard;
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                kind: 'write',
+                resolve: x => {
+                    sub?.dispose();
+                    resolve(x);
+                },
+                token,
+            };
+            const sub = token?.add(e => {
+                this.#removeWaiter(waiter);
+                reject(e);
+            });
+            this.#queue.push(waiter);
+        });
+    }
+}
+export class Lock {
+    #raw;
+    constructor(...[value]) {
+        this.#raw = new RawLock(value);
+    }
+    acquireShared(options) {
+        return this.#raw.acquireReaderAsync(options && Token.from(options));
+    }
+    acquire(options) {
+        return this.#raw.acquireWriterAsync(options && Token.from(options));
+    }
+    tryAcquireShared(options) {
+        return this.#raw.tryAcquireReader(options && Token.from(options));
+    }
+    tryAcquire(options) {
+        return this.#raw.tryAcquireWriter(options && Token.from(options));
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/promise.d.ts

@@ -0,0 +1,5 @@
+import type { ToScope } from './scope.ts';
+import type { Awaitable } from './types.ts';
+export declare function cancellablePromise<T>(promise: Awaitable<T>, scope: ToScope): Promise<T>;
+export declare function runOrCancel<T>(fn: () => Awaitable<T>, scope: ToScope): Promise<T>;
+//# sourceMappingURL=promise.d.ts.map

package/dist/promise.js

@@ -0,0 +1,38 @@
+import { isPromiseLike } from '@youngspe/common-async-utils';
+import { Token } from './token.js';
+function cancellablePromiseInternal(promise, token) {
+    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);
+        });
+    });
+}
+export function cancellablePromise(promise, scope) {
+    const token = Token.from(scope);
+    const { error } = token;
+    if (error)
+        return Promise.reject(error);
+    return cancellablePromiseInternal(promise, token);
+}
+export function runOrCancel(fn, scope) {
+    const token = Token.from(scope);
+    const { error } = token;
+    if (error)
+        return Promise.reject(error);
+    let promise;
+    try {
+        promise = fn();
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    return cancellablePromiseInternal(promise, token);
+}
+//# sourceMappingURL=promise.js.map

package/dist/scope/base.d.ts

@@ -1,44 +1,129 @@
-import type { Awaitable, Falsy } from '../types.ts';
+import { ScopeBase } from '@youngspe/async-scope-common';
+import type { Awaitable, BetterOmit, Falsy, OptionalUndefinedParams, PartialOrUndefined, SetProps, UndefinedIfDefault, UpdateObject } 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';
+import { StandardScope } from '../scope.ts';
+import { type TimerOptions } from '../timers.ts';
+import { ContextData, type ContextDataBuilder } from './context.ts';
 export interface CommonScopeOptions extends CancellableOptions {
 }
-export interface ScopeRunOptions extends CommonScopeOptions {
+interface ScopeLaunchSpecificOptions<V extends object, V2 extends object> {
+    transformScope: (scope: Scope<V>) => Scope<V2>;
 }
-export interface ScopeContextBase {
-    readonly scope: Scope;
+interface ScopeLaunchOptionsBase<V extends object = object, V2 extends object = V> extends CommonScopeOptions, PartialOrUndefined<ScopeLaunchSpecificOptions<V, V2>> {
+}
+interface ScopeLaunchOptionsRequired<V extends object = object, V2 extends object = V> extends CommonScopeOptions, ScopeLaunchSpecificOptions<V, V2> {
+}
+export type ScopeLaunchOptions<V extends object = object, V2 extends object = V> = [
+    V
+] extends [V2] ? ScopeLaunchOptionsBase<V, V2> : ScopeLaunchOptionsRequired<V, V2>;
+export type ScopeLaunchOptionsParams<V extends object = object, V2 extends object = V> = OptionalUndefinedParams<[options: UndefinedIfDefault<ScopeLaunchOptions<V, V2>>]>;
+export interface ScopeContextBase<out V extends object = object> {
+    readonly scope: Scope<V>;
     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 {
+export type ScopeContext<T extends object = object> = BetterOmit<T, keyof ScopeContextBase> & ScopeContextBase<T>;
+export declare abstract class Scope<out V extends object = object> extends ScopeBase {
     #private;
+    /** The cancellation token that determines when this scope is closed. */
     abstract get token(): Token;
     abstract get resources(): ScopedResources;
     get isClosed(): boolean;
     get signal(): AbortSignal;
+    /** @throws if this scope is closed. */
     throwIfClosed(): void;
     protected _onError(value: unknown): void;
+    /**
+     * @see {@linkcode Token#use}
+     */
     use<T extends CancellableLike>(value: T): T;
+    /**
+     * @see {@linkcode Token#tryUse}
+     */
     tryUse<T extends CancellableLike>(value: T): T | undefined;
-    readonly scope: Scope;
-    resolveOrCancel<T>(promise: Awaitable<T>): Promise<T>;
+    /** This scope */
+    readonly scope: Scope<V>;
+    resolveOrCancel<T, U = never>(promise: Awaitable<T>, onCancel?: (error: Error) => Awaitable<U>): Promise<T | U>;
+    resolveOrUndefined<T>(promise: Awaitable<T>): Promise<T | undefined>;
+    get contextData(): ContextData<V>;
+    /**
+     * @throws if this scope is closed.
+     */
+    getContext(options?: CancellableOptions & {
+        values?: undefined;
+    }): ScopeContext<V>;
+    getContext<V2 extends object>(options: CancellableOptions & {
+        values: V2;
+    }): ScopeContext<UpdateObject<V, V2>>;
+    getContext<V2 extends object = V>(options?: CancellableOptions & {
+        values?: V2 | undefined;
+    }): ScopeContext<UpdateObject<V, Partial<V2>>>;
     /**
+     * Launches a task in a subscope context. The subscope will be closed when the function completes.
+     *
+     * Rejects if the scope is cancelled before the function is complete.
      *
      * @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;
+    launch<R, V2 extends object = V>(block: (cx: ScopeContext<V2>) => Awaitable<R>, ...params: ScopeLaunchOptionsParams<V, V2>): Promise<R>;
+    /**
+     * Launches a task in a subscope context. The subscope will be closed when the function completes.
+     *
+     * If the scope is cancelled before the function is complete, this will resolve to `undefined`.
+     *
+     * @param block the function to run
+     * @param options
+     * @returns a promise that resolves to the result of `block`, or `undefined` if the scope is
+     * closed first.
+     */
+    launchCancellable<R, V2 extends object = V>(block: (cx: ScopeContext<V2>) => Awaitable<R>, ...params: ScopeLaunchOptionsParams<V, V2>): Promise<R | undefined>;
+    /**
+     * Runs the given function in a subscope context. If the function throws a non-cancellation error,
+     * the subscope will be closed.
+     *
+     * Rejects if the scope is cancelled before the function is complete.
+     *
+     * @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, V2 extends object = V>(block: (cx: ScopeContext<V2>) => Awaitable<R>, ...params: ScopeLaunchOptionsParams<V, V2>): Promise<R>;
+    /**
+     *
+     * Runs the given function in a subscope context. If the function throws a non-cancellation error,
+     * the subscope will be closed.
+     *
+     * If the scope is cancelled before the function is complete, this will resolve to `undefined`.
+     *
+     * @param block the function to run
+     * @param options
+     * @returns a promise that resolves to the result of `block`, or `undefined` if the scope is
+     * closed first.
+     */
+    runCancellable<R, V2 extends object = V>(block: (cx: ScopeContext<V2>) => Awaitable<R>, ...params: ScopeLaunchOptionsParams<V, V2>): Promise<R | undefined>;
+    withResources(block: (builder: ScopedResources.Builder) => ScopedResources.Builder | void): Scope<V>;
+    withContextData<V2 extends object>(block: (builder: ContextDataBuilder<V>) => ContextDataBuilder<V2>): Scope<V2>;
+    withContextData<V2 extends object = V>(block: (builder: ContextDataBuilder<V>) => ContextDataBuilder<V2> | void): Scope<V | V2>;
+    withContextData<V2 extends object>(data: ContextData<V2>): Scope<SetProps<V, V2>>;
+    withContextData<V2 extends object = V>(data: ContextData<V2> | Falsy): Scope<V | SetProps<V, V2>>;
+    withContextValues<V2 extends object = V>(values: V2): Scope<UpdateObject<V, V2>>;
+    delay(ms: number, options?: TimerOptions): Promise<void>;
+    replaceToken(token: Token): StandardScope<V>;
+    static from<V extends object = object>(this: void, src: ToScope<V>): Scope<V>;
     /** An empty scope that will never be closed. */
-    static get static(): Scope;
+    static get static(): Scope<object>;
 }
 export declare const STATIC_SCOPE: Scope;
-export type ToScope = Scope | Token | readonly ToScope[] | Set<ToScope> | AbortSignal | CancellableOptions | Falsy;
+type ToScopeBase<V extends object = object> = Scope<V> | Token | readonly ToScopeBase<V>[] | Set<ToScopeBase<V>> | AbortSignal | CancellableOptions | Falsy;
+type ToScopeWithContext<V extends object> = Scope<V> | readonly [ToScopeWithContext<V>, ...ToScopeBase<Partial<V>>[]] | (CancellableOptions & {
+    scope: ToScopeWithContext<V>;
+});
+export type ToScope<V extends object = object> = object extends V ? ToScopeBase<V> : ToScopeWithContext<V>;
+export {};
 //# sourceMappingURL=base.d.ts.map

package/dist/scope/base.js

@@ -1,38 +1,67 @@
+import { ScopeBase } from '@youngspe/async-scope-common';
+import { isPromiseLike } from '@youngspe/common-async-utils';
 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 {
+import { delay } from '../timers.js';
+import { ContextData } from './context.js';
+import { CancellationError, unwrapCancellationError } from '../error.js';
+export class Scope extends ScopeBase {
     get isClosed() {
         return this.token.isCancelled;
     }
     get signal() {
         return this.token.signal;
     }
+    /** @throws if this scope is closed. */
     throwIfClosed() {
         this.token.throwIfCancelled();
     }
     _onError(value) {
         throw value;
     }
+    /**
+     * @see {@linkcode Token#use}
+     */
     use(value) {
         return this.token.use(value);
     }
+    /**
+     * @see {@linkcode Token#tryUse}
+     */
     tryUse(value) {
         return this.token.tryUse(value);
     }
+    /** This scope */
     scope = this;
-    resolveOrCancel(promise) {
+    resolveOrCancel(promise, onCancel) {
         const { token } = this;
         const { error } = token;
-        if (error)
-            return Promise.reject(error);
+        if (error) {
+            if (!onCancel)
+                return Promise.reject(error);
+            try {
+                return Promise.resolve(onCancel(error));
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        }
         if (!isPromiseLike(promise))
             return Promise.resolve(promise);
         return new Promise((resolve, reject) => {
-            const sub = token.add(reject);
+            const sub = token.add(onCancel ?
+                error => {
+                    try {
+                        return resolve(onCancel(error));
+                    }
+                    catch (error) {
+                        return reject(error);
+                    }
+                }
+                : reject);
             promise.then(x => {
                 sub?.dispose();
                 resolve(x);
@@ -42,55 +71,148 @@ export class Scope {
             });
         });
     }
-    #subScope(token, options) {
-        return scopeFrom([this, token, options]);
+    resolveOrUndefined(promise) {
+        return this.resolveOrCancel(promise, () => undefined);
     }
-    /**
-     *
-     * @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) {
+    #subScope(token, ...[options]) {
+        const newScope = scopeFrom([this, token, options]);
+        if (options?.transformScope)
+            return options.transformScope(newScope);
+        return newScope;
+    }
+    get contextData() {
+        return ContextData.empty;
+    }
+    getContext(options) {
+        this.throwIfClosed();
+        let scope = this;
+        if (options?.scope || options?.token || options?.signal) {
+            scope = Scope.from([scope, options]);
+            scope.throwIfClosed();
+        }
+        if (options?.values) {
+            scope = scope.withContextValues(options.values);
+        }
+        const cx = new Scope.#Context(scope);
+        return scope.contextData.updateContext(cx);
+    }
+    async #run(block, cancelOnComplete, onCancel, ...params) {
+        const { error } = this.token;
+        if (error) {
+            if (onCancel)
+                return await onCancel(error);
+            throw error;
+        }
         await using controller = this.use(Token.createController());
-        const subScope = this.#subScope(controller.token, options);
+        const subScope = this.#subScope(controller.token, ...params);
+        let out;
         try {
-            return await subScope.resolveOrCancel(block(new Scope.#Context(subScope)));
+            out = await subScope.resolveOrCancel(block(subScope.getContext()), onCancel ?? Promise.reject.bind(Promise));
         }
         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;
+                if (onCancel && error instanceof Error && (subScope.isClosed || unwrapCancellationError(error))) {
+                    return await onCancel(error);
+                }
+                else {
+                    throw error;
+                }
             }
-            catch (error) {
+            finally {
                 await controller.cancel(error);
-                throw error;
             }
-        };
+        }
+        if (cancelOnComplete) {
+            await controller.cancel(new CancellationError());
+        }
+        else {
+            controller.defuse();
+        }
+        return out;
+    }
+    /**
+     * Launches a task in a subscope context. The subscope will be closed when the function completes.
+     *
+     * Rejects if the scope is cancelled before the function is complete.
+     *
+     * @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.
+     */
+    launch(block, ...params) {
+        return this.#run(block, true, undefined, ...params);
+    }
+    /**
+     * Launches a task in a subscope context. The subscope will be closed when the function completes.
+     *
+     * If the scope is cancelled before the function is complete, this will resolve to `undefined`.
+     *
+     * @param block the function to run
+     * @param options
+     * @returns a promise that resolves to the result of `block`, or `undefined` if the scope is
+     * closed first.
+     */
+    async launchCancellable(block, ...params) {
+        return this.#run(block, true, () => undefined, ...params);
+    }
+    /**
+     * Runs the given function in a subscope context. If the function throws a non-cancellation error,
+     * the subscope will be closed.
+     *
+     * Rejects if the scope is cancelled before the function is complete.
+     *
+     * @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, ...params) {
+        return this.#run(block, false, undefined, ...params);
+    }
+    /**
+     *
+     * Runs the given function in a subscope context. If the function throws a non-cancellation error,
+     * the subscope will be closed.
+     *
+     * If the scope is cancelled before the function is complete, this will resolve to `undefined`.
+     *
+     * @param block the function to run
+     * @param options
+     * @returns a promise that resolves to the result of `block`, or `undefined` if the scope is
+     * closed first.
+     */
+    async runCancellable(block, ...params) {
+        return this.#run(block, false, () => undefined, ...params);
     }
     withResources(block) {
         const builder = ScopedResources.builder(this.token).inherit(this.resources);
         block(builder);
         const resources = builder.finish();
-        return new StandardScope({ ...this, resources });
+        return new StandardScope({ ...this.#parts(), resources });
+    }
+    withContextData(data) {
+        if (!data || data === ContextData.empty)
+            return this;
+        const builder = this.contextData.builder();
+        if (typeof data === 'function') {
+            data(builder);
+        }
+        else {
+            builder.merge(data);
+        }
+        return new StandardScope({ ...this.#parts(), contextData: builder.finish() });
+    }
+    withContextValues(values) {
+        const contextData = this.contextData.builder().values(values).finish();
+        return new StandardScope({ ...this.#parts(), contextData });
+    }
+    delay(ms, options) {
+        return delay(ms, { ...options, scope: [this, options?.scope] });
+    }
+    replaceToken(token) {
+        return new StandardScope({ ...this.#parts(), token });
+    }
+    #parts() {
+        return { token: this.token, resources: this.resources, contextData: this.contextData };
     }
     static from(src) {
         return scopeFrom(src);

package/dist/scope/context.d.ts

@@ -0,0 +1,19 @@
+import type { SetProps, UpdateObject } from '../types.ts';
+import type { ScopeContext, ScopeContextBase } from './base.ts';
+export declare class ContextData<V extends object = object> {
+    #private;
+    private constructor();
+    updateContext(target: ScopeContextBase<V>): ScopeContext<V>;
+    builder(): ContextDataBuilder<V>;
+    static builder(this: void): ContextDataBuilder;
+    static empty: ContextData<object>;
+}
+export interface ContextDataBuilder<V extends object = object> {
+    values<V2 extends object>(props: V2): ContextDataBuilder<UpdateObject<V, V2>>;
+    getters<V2 extends object>(getters: {
+        [K in keyof V2]: (cx: ScopeContext<SetProps<V, V2>>) => V2[K];
+    }): ContextDataBuilder<SetProps<V, V2>>;
+    merge<V2 extends object>(contextData: ContextData<V2>): ContextDataBuilder<SetProps<V, V2>>;
+    finish(): ContextData<V>;
+}
+//# sourceMappingURL=context.d.ts.map