npm package: @merchise/action-queue
Description: A coordinated queue of actions
Author: Merchise Autrement
Latest version: 5.0.1

# A coordinated queue of actions

The class `ActionQueue` allows to create a FIFO, LIFO and replacement of
actions.  An action is a function that returns a
[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).

## API

### `new ActionQueue(options)`

Creates a new action queue.  You can pass an object with options:

- `createPromises`, it should be a bool to indicate if the functions
   'append', 'prepend' and 'replace' should create and promises.
   Defaults to true.

- `rejectCanceled`, it should be a bool to indicate if we reject the promises
  (if `createPromises` is also true) that are cancelled while still in the
  queue.  See the methods `replace` and `clear` below.

- `workers`, if present it should a small integer to indicate the
  amount of actions the queue can run concurrently.  We advice that you
  really small number: max. 10.  The default is 1, which means no
  concurrency.  Ignored if not a number, or smaller than 1.


### `append(fn, ...args)`

Push a new action using a FIFO strategy.  The new action is going to be
executed after all current pending actions in the queue.

If the option `createPromises` is true, return a promise that is
equivalent to the one that would be returned by the action after it
starts running.  This promise will resolve only if/when the action
runs and resolves, and it will reject when the action rejects or is
cancelled.

If `createPromises` is false, return undefined.

Any additional `args` passed to this method is stored and passed to callbacks.

### `prepend(fn, ...args)`

Prepend a new action using a LIFO strategy.  If a current action is already
running don't cancel it, instead queue the given action to be run later but
before any other action in the queue.

If the option `createPromises` is true, return a promise that is
equivalent to the one that would be returned by the action after it
starts running.  This promise will resolve only if/when the action
runs and resolves, and it will reject when the action rejects or is
cancelled.

If `createPromises` is false, return undefined.

Any additional `args` passed to this method is stored and passed to callbacks.

### `replace(fn, ...args)`

Cancel all pending and running actions in the queue and replace it with a new
action.   This is the same as calling `clear` and then `append`.

### `replace_pending(fn, ...args)`

Replaces the entire queue with the given action without canceling running
actions.

### `clear()`

Cancel all pending and running actions in the queue.

### `then(callback)`

Register a callback to be called when any of the actions is completed
successfully without being cancelled from the queue.

The callbacks will receive all arguments the underlying Promise yields when
resolving plus the extra `args` passed in `append` or `prepend`.


### `catch(callback)`

Register a callback to be called when any of the actions is rejected without
being cancelled.

The callbacks will receive all arguments the underlying Promise yields when
resolving plus the extra `args` passed in `append` or `prepend`.


### `finally(callback)`

Register a callback to be called when any of the actions is resolved, rejected
or cancelled (evicted from the queue).

The callbacks will receive all arguments the underlying Promise yields when
resolving plus the extra `args` passed in `append` or `prepend`.  If the
action was actually cancelled, there's no result and only the extra `args` are
passed.

### `oncancel(callback)`

Register a callback to be called when any of the actions is cancelled (evicted
from the queue).

The callbacks will receive the extra `args` passed in `append` or `prepend`.


### `length()`

Return the length of queue including the running action.

### `promise()`

Return a promise that resolves/rejects just as soon as the first
pending/running action resolves/rejects.

Cancelations don't affect the promise.  If the running action gets cancelled
midway, this promise will take over on the next action.  If no action is
scheduled to be next, we wait.

The only way this promise is rejected, is if the running action is rejected.
The only way this promise is resolved, is when the running action is resolved.

When the same queue is used several times, calls to promise may return
different promises.

### `info()`

Return an object with the running and pending jobs in the queue.

The result is an object with two properties: `running` and `pending`.  Each
contains an array of objects the properties:

- `args`; which is an array (possibly empty) with the extra arguments passed
  to `append`, `prepend` or `replace`.

- `cancel`; a function that allows to cancel this particular action

- `promise`; the promise attached to this action (undefined if
  `createPromises` is false).

### `busy()`

Return True if the queue is busy, either running or has actions waiting.  This
might True even if the queue is paused.


### `pause()`

Pause the queue.  This has no effect on the currently running action (if any);
if we was running it will finish.  But no new actions are going to be
executed.

If the queue is already paused, do nothing.

### `resume()`

Resume the queue.  If the queue is not paused, do nothing.


### `paused()`

Return True if the queue is paused.