api.service.Sequence

This service implements a manager for sequentially running multiple asynchronous processes. Every process is represented by a callback and an optional ID.

The process is invoked and may return a result or a promise for some result. It may throw an exception or reject the returned promise.

In all these cases, the process is considered to have finished and the sequence is instantly invoking next enqueued process.

Constructor

A sequence is an instance of this service.

const sequence = new api.service.Sequence();

Methods

append()

The method receives a callback in first argument and appends it to the sequence of callbacks to process. It returns a promise for the result of invoking that callback.

An ID given in second argument is optional and may be used to inspect the sequence using methods has(), isCurrent() and waitFor(). When omitted, the callback itself is used as ID.

Callbacks are always appended at the end of current sequence. If you need a process to be invoked as soon as possible, consider using prepend() instead.

const result = await sequence.append( () => doSomething(), "my-process" );

has()

The method enumerates the sequence of current and pending processes and detects whether any of those processes has been appended or prepended with ID given in sole argument. It returns true if there is a matching process and false otherwise.

Processes are removed from sequence once they have completed. Thus, testing a sequence for previously run processes always returns false.

if ( sequence.has( "my-process" ) ) {
	console.log( "my process is pending" );
}

isCurrent()

The method tests if currently running process has been appended or prepended with ID given in sole argument. It returns true if there is a currently running process, and it is matching given ID. Otherwise, it returns false.

if ( sequence.isCurrent( "my-process" ) ) {
	console.log( "my process is running" );
}

isEmpty()

This method checks if the sequence is currently empty or not. It returns true if there is no currently running process in the sequence and no process has been appended to the sequence to be invoked next. Otherwise, it returns false.

if ( sequence.isEmpty() ) {
	console.log( "there are no processes, currently" );
}

prepend()

The method prepends the callback given in first argument to the sequence of callbacks that haven't been invoked, yet. It returns a promise for the result of invoking that callback.

An ID given in second argument is optional and may be used to inspect the sequence using methods has(), isCurrent() and waitFor(). When omitted, the callback itself is used as ID.

Prepending a callback is inserting the given callback after currently running process, but before any other process that has been prepended or appended before. Thus, prepending multiple callbacks results in those callbacks being invoked in reverse order.

const result = await sequence.prepend( () => doSomethingUrgent(), "my-urgent-process" );

waitFor()

This method re-delivers the promise for the result of a process selected by its ID given in sole argument. The promise will be settled once the process has been invoked and has finished.

However, due to removing processes from the sequence once they have finished, it is not possible to fetch the promise for the result of previously running process.

const result = await sequence.waitFor( "my-urgent-process" );

whenIdle()

This method creates a promise resolved once all current and future processes of sequence have been invoked and have finished. The returned promise considers processes that have been appended or prepended after fetching this promise.

await sequence.whenIdle();

console.log( "all processes have finished now" );