prex

  • Version 0.4.9
  • Published
  • 183 kB
  • 2 dependencies
  • Apache-2.0 license

Install

npm i prex
yarn add prex
pnpm add prex

Overview

Async coordination primitives and extensions on top of ES6 Promises

Index

Functions

function delay

delay: {
(msec: number): Promise<void>;
<T>(msec: number, value: T | PromiseLike<T>): Promise<T>;
(token: any, msec: number): Promise<void>;
<T>(token: any, msec: number, value: T | PromiseLike<T>): Promise<T>;
};
  • Waits the specified number of milliseconds before resolving.

    Parameter msec

    The number of milliseconds to wait before resolving.

  • Waits the specified number of milliseconds before resolving with the provided value.

    Parameter msec

    The number of milliseconds to wait before resolving.

    Parameter value

    An optional value for the resulting Promise.

  • Waits the specified number of milliseconds before resolving.

    Parameter token

    A CancellationToken

    Parameter msec

    The number of milliseconds to wait before resolving.

  • Waits the specified number of milliseconds before resolving with the provided value.

    Parameter token

    A CancellationToken

    Parameter msec

    The number of milliseconds to wait before resolving.

    Parameter value

    An optional value for the resulting Promise.

Classes

class AsyncBoundedQueue

class AsyncBoundedQueue<T> {}
  • An asynchronous queue with a bounded endpoint.

constructor

constructor(iterable?: Iterable<T | PromiseLike<T>>);
  • Initializes a new instance of the AsyncProducerConsumerQueue class.

    Parameter iterable

    An optional iterable of values or promises.

property size

readonly size: number;
  • Gets the number of entries in the queue. When positive, indicates the number of entries available to get. When negative, indicates the number of requests waiting to be fulfilled.

method drain

drain: () => AsyncIterableIterator<T>;
  • Consumes all items in the queue until the queue ends.

method end

end: () => void;
  • Indicates the queue is done adding and that no more items will be added to the queue.

method get

get: () => Promise<T | undefined>;
  • Removes and returns a Promise for the first value in the queue. If the queue has ended, returns a Promise for undefined. If the queue is empty, returns a Promise for the next value to be added to the queue.

method put

put: (value: T | PromiseLike<T>) => void;
  • Adds a value to the end of the queue. If the queue is empty but has a pending dequeue request, the value will be dequeued and the request fulfilled.

    Parameter value

    A value or promise to add to the queue.

class AsyncQueue

class AsyncQueue<T> {}
  • An asynchronous queue.

constructor

constructor(iterable?: Iterable<T | PromiseLike<T>>);
  • Initializes a new instance of the AsyncQueue class.

    Parameter iterable

    An optional iterable of values or promises.

property size

readonly size: number;
  • Gets the number of entries in the queue. When positive, indicates the number of entries available to get. When negative, indicates the number of requests waiting to be fulfilled.

method get

get: () => Promise<T>;
  • Removes and returns a Promise for the first value in the queue. If the queue is empty, returns a Promise for the next value to be added to the queue.

method put

put: (value: T | PromiseLike<T>) => void;
  • Adds a value to the end of the queue. If the queue is empty but has a pending dequeue request, the value will be dequeued and the request fulfilled.

    Parameter value

    A value or promise to add to the queue.

class AsyncStack

class AsyncStack<T> {}
  • An asynchronous Stack.

constructor

constructor(iterable?: Iterable<T | PromiseLike<T>>);
  • Initializes a new instance of the AsyncStack class.

    Parameter iterable

    An optional iterable of values or promises.

property size

readonly size: number;
  • Gets the number of entries in the stack. When positive, indicates the number of entries available to get. When negative, indicates the number of requests waiting to be fulfilled.

method pop

pop: () => Promise<T>;
  • Removes and returns a Promise for the top value of the stack. If the stack is empty, returns a Promise for the next value to be pushed on to the stack.

method push

push: (value: T | PromiseLike<T>) => void;
  • Adds a value to the top of the stack. If the stack is empty but has a pending pop request, the value will be popped and the request fulfilled.

    Parameter value

    A value or promise to add to the stack.

class AutoResetEvent

class AutoResetEvent {}
  • Asynchronously notifies one or more waiting Promises that an event has occurred.

constructor

constructor(initialState?: boolean);
  • Initializes a new instance of the AutoResetEvent class.

    Parameter initialState

    A value indicating whether to set the initial state to signaled.

method reset

reset: () => void;
  • Sets the state of the event to nonsignaled, causing asynchronous operations to pause.

method set

set: () => void;
  • Sets the state of the event to signaled, resolving one or more waiting Promises. The event is then automatically reset.

method wait

wait: (token?: CancellationToken | Cancelable) => Promise<void>;
  • Asynchronously waits for the event to become signaled.

    Parameter token

    A CancellationToken used to cancel the request.

class Barrier

class Barrier {}
  • Enables multiple tasks to cooperatively work on an algorithm through multiple phases.

constructor

constructor(
participantCount: number,
postPhaseAction?: (barrier: Barrier) => void | PromiseLike<void>
);
  • Initializes a new instance of the Barrier class.

    Parameter participantCount

    The initial number of participants for the barrier.

    Parameter postPhaseAction

    An action to execute between each phase.

property currentPhaseNumber

readonly currentPhaseNumber: number;
  • Gets the number of the Barrier's current phase.

property participantCount

readonly participantCount: number;
  • Gets the total number of participants in the barrier.

property remainingParticipants

readonly remainingParticipants: number;
  • Gets the number of participants in the barrier that haven't yet signaled in the current phase.

method add

add: (participantCount?: number) => void;
  • Notifies the Barrier there will be additional participants.

    Parameter participantCount

    The number of additional participants.

method remove

remove: (participantCount?: number) => void;
  • Notifies the Barrier there will be fewer participants.

    Parameter participantCount

    The number of participants to remove.

method signalAndWait

signalAndWait: (token?: CancellationToken | Cancelable) => Promise<void>;
  • Signals that a participant has reached the barrier and waits for all other participants to reach the barrier.

    Parameter token

    An optional CancellationToken used to cancel the request.

class CancelError

class CancelError extends Error {}
  • An error thrown when an operation is canceled.

constructor

constructor(message?: string);

    class CancellationToken

    class CancellationToken implements Cancelable {}
    • Propagates notifications that operations should be canceled.

    property canBeCanceled

    readonly canBeCanceled: boolean;
    • Gets a value indicating whether the underlying source can be canceled.

    property canceled

    static readonly canceled: CancellationToken;
    • A token that is already canceled.

    property cancellationRequested

    readonly cancellationRequested: boolean;
    • Gets a value indicating whether cancellation has been requested.

    property none

    static readonly none: CancellationToken;
    • A token which will never be canceled.

    method [Cancelable.cancelSignal]

    [Cancelable.cancelSignal]: () => Cancelable & CancelSignal;

      method all

      static all: (
      tokens: Iterable<CancellationToken | Cancelable>
      ) => CancellationToken;
      • Returns a CancellationToken that becomes canceled when **all** of the provided tokens are canceled.

        Parameter tokens

        An iterable of CancellationToken objects.

      method from

      static from: (
      cancelable:
      | CancellationToken
      | VSCodeCancellationTokenLike
      | AbortSignalLike
      | Cancelable
      ) => CancellationToken;
      • Adapts a CancellationToken-like primitive from a different library.

      method race

      static race: (
      tokens: Iterable<CancellationToken | Cancelable>
      ) => CancellationToken;
      • Returns a CancellationToken that becomes canceled when **any** of the provided tokens are canceled.

        Parameter tokens

        An iterable of CancellationToken objects.

      method register

      register: (callback: () => void) => CancellationTokenRegistration;
      • Registers a callback to execute when cancellation is requested.

        Parameter callback

        The callback to register.

      method throwIfCancellationRequested

      throwIfCancellationRequested: () => void;
      • Throws a CancelError if cancellation has been requested.

      class CancellationTokenCountdown

      class CancellationTokenCountdown {}
      • An object that provides a CancellationToken that becomes cancelled when **all** of its containing tokens are canceled. This is similar to CancellationToken.all, except that you are able to add additional tokens.

      constructor

      constructor(iterable?: Iterable<any>);

        property addedCount

        readonly addedCount: number;
        • Gets the number of tokens added to the countdown.

        property remainingCount

        readonly remainingCount: number;
        • Gets the number of tokens that have not yet been canceled.

        property token

        readonly token: CancellationToken;
        • Gets the CancellationToken for the countdown.

        method add

        add: (token: CancellationToken | Cancelable) => this;
        • Adds a CancellationToken to the countdown.

        class CancellationTokenSource

        class CancellationTokenSource implements CancelableSource {}
        • Signals a CancellationToken that it should be canceled.

        constructor

        constructor(linkedTokens?: Iterable<any>);
        • Initializes a new instance of a CancellationTokenSource.

          Parameter linkedTokens

          An optional iterable of tokens to which to link this source.

        property token

        readonly token: CancellationToken;
        • Gets a CancellationToken linked to this source.

        method [Cancelable.cancelSignal]

        [Cancelable.cancelSignal]: () => Cancelable & CancelSignal;

          method [CancelableSource.cancel]

          [CancelableSource.cancel]: () => void;

            method cancel

            cancel: () => void;
            • Cancels the source, evaluating any registered callbacks. If any callback raises an exception, the exception is propagated to a host specific unhanedle exception mechanism.

            method close

            close: () => void;
            • Closes the source, preventing the possibility of future cancellation.

            class CountdownEvent

            class CountdownEvent {}
            • An event that is set when all participants have signaled.

            constructor

            constructor(initialCount: number);
            • Initializes a new instance of the CountdownEvent class.

              Parameter initialCount

              The initial participant count.

            property initialCount

            readonly initialCount: number;
            • Gets the number of signals initially required to set the event.

            property remainingCount

            readonly remainingCount: number;
            • Gets the number of remaining signals required to set the event.

            method add

            add: (count?: number) => void;
            • Increments the event's current count by one or more.

              Parameter count

              An optional count specifying the additional number of signals for which the event will wait.

            method reset

            reset: (count?: number) => void;
            • Resets the remaining and initial count to the specified value, or the initial count.

              Parameter count

              An optional count specifying the number of required signals.

            method signal

            signal: (count?: number) => boolean;
            • Registers one or more signals with the CountdownEvent, decrementing the remaining count.

              Parameter count

              An optional count specifying the number of signals to register.

            method wait

            wait: (token?: CancellationToken | Cancelable) => Promise<void>;
            • Asynchronously waits for the event to become signaled.

              Parameter token

              An optional CancellationToken used to cancel the request.

            class Deferred

            class Deferred<T> {}
            • Encapsulates a Promise and exposes its resolve and reject callbacks.

            constructor

            constructor();
            • Initializes a new instance of the Deferred class.

            property callback

            readonly callback:
            | ((err: Error | null | undefined) => void)
            | ((err: Error | null | undefined, value: T) => void);
            • Gets a NodeJS-style callback that can be used to resolve or reject the promise.

            property promise

            readonly promise: Promise<T>;
            • Gets the promise.

            property reject

            readonly reject: (reason: any) => void;
            • Gets the callback used to reject the promise.

            property resolve

            readonly resolve: (value?: T | PromiseLike<T> | undefined) => void;
            • Gets the callback used to resolve the promise.

            method createCallback

            createCallback: <A extends any[]>(
            selector: (...args: A) => T
            ) => (err: Error | null | undefined, ...args: A) => void;
            • Creates a NodeJS-style callback that can be used to resolve or reject the promise with multiple values.

            class ManualResetEvent

            class ManualResetEvent {}
            • Asynchronously notifies one or more waiting Promises that an event has occurred.

            constructor

            constructor(initialState?: boolean);
            • Initializes a new instance of the ManualResetEvent class.

              Parameter initialState

              A value indicating whether to set the initial state to signaled.

            property isSet

            readonly isSet: boolean;
            • Gets a value indicating whether the event is signaled.

            method reset

            reset: () => void;
            • Sets the state of the event to nonsignaled, causing asynchronous operations to pause.

            method set

            set: () => void;
            • Sets the state of the event to signaled, resolving one or more waiting Promises.

            method wait

            wait: (token?: CancellationToken | Cancelable) => Promise<void>;
            • Asynchronously waits for the event to become signaled.

              Parameter token

              A CancellationToken used to cancel the request.

            class Pulsar

            class Pulsar {}
            • Asynchronously notifies one or more waiting Promises that an event has occurred.

            method pulse

            pulse: () => void;
            • Notifies the next waiter.

            method pulseAll

            pulseAll: () => void;
            • Notifies all waiters.

            method wait

            wait: (token?: CancellationToken | Cancelable) => Promise<void>;
            • Asynchronously waits for the the next pulse.

              Parameter token

              A CancellationToken used to cancel the request.

            class ReaderWriterLock

            class ReaderWriterLock {}
            • Coordinates readers and writers for a resource.

            method read

            read: (token?: CancellationToken | Cancelable) => Promise<LockHandle>;
            • Asynchronously waits for and takes a read lock on a resource.

              Parameter token

              A CancellationToken used to cancel the request.

            method upgradeableRead

            upgradeableRead: (
            token?: CancellationToken | Cancelable
            ) => Promise<UpgradeableLockHandle>;
            • Asynchronously waits for and takes a read lock on a resource that can later be upgraded to a write lock.

              Parameter token

              A CancellationToken used to cancel the request.

            method write

            write: (token?: CancellationToken | Cancelable) => Promise<LockHandle>;
            • Asynchronously waits for and takes a write lock on a resource.

              Parameter token

              A CancellationToken used to cancel the request.

            class Semaphore

            class Semaphore {}
            • Limits the number of asynchronous operations that can access a resource or pool of resources.

            constructor

            constructor(initialCount: number, maxCount?: number);
            • Initializes a new instance of the Semaphore class.

              Parameter initialCount

              The initial number of entries.

              Parameter maxCount

              The maximum number of entries.

            property count

            readonly count: number;
            • Gets the number of remaining asynchronous operations that can enter the Semaphore.

            method release

            release: (count?: number) => void;
            • Releases the Semaphore one or more times.

              Parameter count

              The number of times to release the Semaphore.

            method wait

            wait: (token?: CancellationToken | Cancelable) => Promise<void>;
            • Asynchronously waits for the event to become signaled.

              Parameter token

              A CancellationToken used to cancel the request.

            Interfaces

            interface AbortSignalLike

            interface AbortSignalLike {}
            • Describes a foreign cancellation primitive similar to the one used by the DOM.

            property aborted

            readonly aborted: boolean;

              method addEventListener

              addEventListener: (type: 'abort', callback: () => any) => any;

                interface CancellationTokenRegistration

                interface CancellationTokenRegistration extends Disposable {}
                • An object used to unregister a callback registered to a CancellationToken.

                method unregister

                unregister: () => void;
                • Unregisters the callback

                interface LockHandle

                interface LockHandle extends Disposable {}
                • An object used to release a held lock.

                method release

                release: () => void;
                • Releases the lock.

                interface UpgradeableLockHandle

                interface UpgradeableLockHandle extends LockHandle, Disposable {}
                • An object used to release a held lock or upgrade to a write lock.

                method upgrade

                upgrade: (token?: CancellationToken | Cancelable) => Promise<LockHandle>;
                • Upgrades the lock to a write lock.

                  Parameter token

                  A CancellationToken used to cancel the request.

                interface VSCodeCancellationTokenLike

                interface VSCodeCancellationTokenLike {}
                • Describes a foreign cancellation primitive similar to the one provided by vscode for extensions.

                property isCancellationRequested

                readonly isCancellationRequested: boolean;

                  method onCancellationRequested

                  onCancellationRequested: (listener: () => any) => { dispose(): any };

                    Package Files (14)

                    Dependencies (2)

                    Dev Dependencies (15)

                    Peer Dependencies (0)

                    No peer dependencies.

                    Badge

                    To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                    You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/prex.

                    • Markdown
                      [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/prex)
                    • HTML
                      <a href="https://www.jsdocs.io/package/prex"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>