sequential-promise-processor

A processor that queues and resolves promises in series

Getting started

Installation

To install this package to your Node.js modules, simply run:

npm i -S @com.christiangrete.libs.js/sequential-promise-processor

Or, using Yarn, run:

yarn add @com.christiangrete.libs.js/sequential-promise-processor

Usage

Just import it as an ES2015 module and create an instance to get started:

import {
  SequentialPromiseProcessor
} from '@com.christiangrete.libs.js/sequential-promise-processor'

const sequentialPromiseProcessor = new SequentialPromiseProcessor()

The class is also available as the default member, so you don’t need to explicitly import it as a named member.

This package is distributed using the UMD pattern and can be required using RequireJS or used as a global variable under window.SequentialPromiseProcessor.default as well.

Example

Let’s assume that we want to execute git commands in a series:

import {
  SequentialPromiseProcessor
} from '@com.christiangrete.libs.js/sequential-promise-processor'

import {exec} from 'child_process'

// A factory function that returns another function which will be passed to the
// Promise constructor as its executor function with the corresponding command
const createExecutor = $command => ($resolve, $reject) => {
  exec($command, ($error, $stdout, $stderr) => {
    if ($error === null) {
      $resolve($stdout)
    } else {
      $reject($error, $stderr)
    }
  })
}

// Another factory function that returns a new Promise object created with the
// corresponding command and the executor function from the factory above
const createFactory = ($command, $callback) => () => {
  const _executor = createExecutor($command)
  const _promise = new Promise(_executor)

  if (typeof $callback === 'function') {
    _promise.then(
      $stdout => $callback(null, $stdout),
      ($error, $stderr) => $callback($error, $stderr)
    )
  }

  return _promise
}

// A list of commands that will be executed in series
const commands = [
  'git add --all',
  'git status',
  "git commit -m 'fix stuff'",
  'git pull origin develop',
  'git push origin develop'
]

// A list of factory functions referenced with the corresponding command from
// the list above
const factories = commands.map($command => createFactory(
  $command,
  (...$arguments) => console.log(...$arguments)
))

const sequentialPromiseProcessor = new SequentialPromiseProcessor()

// This method adds all factory functions to the queue...
sequentialPromiseProcessor.queue(factories) // Queues the factories from above
// ...it could also be used as follows:
// sequentialPromiseProcessor.queue(...factories)
// ...or...
// sequentialPromiseProcessor.queue(factories[0]).queue(factories[1])

// Start processing the queue needs to be done manually.
sequentialPromiseProcessor.process()

// It is possible to remove a factory from the queue, unless it has already
// been processed.
sequentialPromiseProcessor.unqueue(factories[1])

// It is also possible to pause the processing of the queue...
sequentialPromiseProcessor.pause()

// ...and to resume it later on...
setTimeout(() => {
  sequentialPromiseProcessor.resume()
}, 500)

// ...or completely abort the process.
sequentialPromiseProcessor.cancel()

Policy

This is communist software. It is crafted with heart and soul to the best of the authors’ knowledge and belief: Not for profit but to satisfy the concrete needs. Do whatever you want with it (as long as you keep the authors’ copyright notices in all copies or substantial portions of it included) for free. Imagine how the world could be if others would produce and distribute their products for the same benefits and ask yourself why they’re actually not.

Contributing

You’re more than welcome to contribute to the source code of this project. See the contribution guidelines on how to get involved.

Also, have a look at the to-do list.

License

This software is licensed under MIT License.

Copyright © 2017 Christian Grete

• GitHub
• npm
• Twitter
• LinkedIn
• XING