feat(actions): include a serial action

Similar to the repeat action be ensure each task is both run and
completes before moving on to the next. With a lot of async tasks the
implementation of repeat can't ensure the order of each task. While it
may ensure each task is invoked in order, it does not ensure each
completes.

Author: esatterwhite

README.md

@@ -14,6 +14,7 @@
   * [`map(collection, iterator, label)`](#mapcollection-iterator-label)
   * [`sort(collection, comparator, label)`](#sortcollection-comparator-label)
   * [`repeat(times, name, opts, label)`](#repeattimes-name-opts-label)
+  * [`serial(times, name, opts, label)`](#serialtimes-name-opts-label)
   * [`sleep(opts)`](#sleepopts)
   * [`reset()`](#reset)
   * [`execute()`](#execute)
@@ -247,8 +248,10 @@ const state = await chain
 
 ## `repeat(times, name, opts, label)`
 
-Executes each task added sequentially and collects the results into a single object.
-This is a chain action resolved by [execute](#execute).
+Executes each task added and collects the results into a single object.
+This is a chain action resolved by [execute](#execute). Internally this uses `Promise.all`
+and does not necessarily ensure that actions execute in the order they are specified.
+If the order of execution is important, you should use [serial](#serial)
 
 **Parameters**
 
@@ -284,6 +287,61 @@ chain
 > {result: ['hi', 'hi', 'hi', 'hi', 'hi']}
 ```
 
+## `serial(times, name, opts, label)`
+
+Executes each task added sequentially and collects the results into a single array.
+This is a chain action resolved by [execute](#execute).
+
+**Parameters**
+
+* **times** [Number][]: The number of times to execute the given action name
+* **name** [String][]: The name of the action to execute.  This **must** already exist
+  on the chain as a valid action.
+* **opts** [Object][]: Any options that the named action requires.  Currently, this
+  only supports actions with an `(opts)` signature.  Custom signatures are not yet
+  supported.
+* **label** [String][]: Optional label in which to store the result.
+
+**Returns:** `this<SetupChain>`
+
+
+```javascript
+const {promisify}  = require('util')
+const SetupChain = require('@logdna/setup-chain')
+
+function randInt(min, max) { 
+  return Math.random() * (max - min) + min;
+}
+
+class MyChain extends SetupChain {
+  constructor(state) {
+    super(state, {
+      delay: ({value}) => {
+        return new Promise((resolve, reject) => {
+          const timeout = randInt(1, 1000)
+          setTimeout(() => {
+            resolve(`${value} (${timeout}ms)`)
+          }, timeout)
+        })
+      }
+    })
+
+    $incr() {
+      return ++this.count
+    }
+  }
+
+}
+
+const chain = new MyChain()
+chain
+  .serial(5, 'delay', {value: '!incr'}, 'result')
+  .execute()
+  .then(console.log)
+
+> {result: ['1 (10ms)', '2 (1ms)', '3 (1000ms)', '4 (22ms)', '5 (38ms)']}
+```
+
 ## `sleep(opts)`
 
 When used in a chain, it will wait for a specified number of milliseconds before returning. Since this is a chain action, the sleep will appear to happen sequentially

lib/actions/index.js

@@ -4,6 +4,7 @@ module.exports = {
   map: require('./map.js')
 , repeat: require('./repeat.js')
 , set: require('./set.js')
+, serial: require('./serial.js')
 , sleep: require('./sleep.js')
 , sort: require('./sort.js')
 }

lib/actions/serial.js

@@ -0,0 +1,50 @@
+'use strict'
+
+/**
+ * @module lib/actions/serial
+ * @author Eric Satterwhite
+ **/
+
+const assert = require('assert')
+const {typeOf, object} = require('@logdna/stdlib')
+
+const NAME = 'SetupChain.serial'
+const TIMES_ERR = `
+  ${NAME} requires 'times' to be an integer and greater than or equal to 0
+`.trim()
+
+const ACTION_ERR = `${NAME} 'action' invalid`
+
+module.exports = async function serial(times, action, opts) {
+  assert.equal(typeOf(times), 'number', TIMES_ERR)
+  assert.ok(times >= 0, TIMES_ERR)
+  assert.ok(Number.isInteger(times), TIMES_ERR)
+  assert.ok(Number.isFinite(times), TIMES_ERR)
+  assert.ok(
+    object.has(this.actions, action)
+  , `${ACTION_ERR}. '${action}' does not exist as a chain action.`
+  )
+
+  const results = new Array(times)
+  const fn = this.actions[action]
+
+  for (let i = 0; i < times; i++) {
+    results[i] = await fn.call(this, opts)
+  }
+
+  return results
+}
+
+/**
+ * Chain action that similar to {@link module:lib/actions/repeat|repeat} but always executes
+ * in a sequential order.
+ * @async
+ * @function module:lib/actions/serial
+ * @param {Object} input
+ * @param {Number} input.times The number of times to run the action
+ * @param {String} input.action The name of the chain action to execute
+ * @param {Object} [input.opts] Options to pass to the action
+ * @example
+ * await new SetupChain().serial(10, 'delay', {value: '!template("{{!increment}}")'}).execute()
+ **/
+

lib/chain.js

@@ -72,6 +72,11 @@ module.exports = class SetupChain {
     return this
   }
 
+  serial(times, action, opts, label) {
+    this.tasks.push(['serial', label, times, action, opts])
+    return this
+  }
+
   sort(collection, comparator, label) {
     this.tasks.push(['sort', label, collection, comparator])
     return this

test/fixtures/actions/delay.js

@@ -0,0 +1,14 @@
+'use strict'
+
+function randInt(min, max) {
+  return Math.random() * (max - min) + min
+}
+
+module.exports = function delay(opts) {
+  return new Promise((resolve) => {
+    const delay = randInt(1, 500)
+    setTimeout(() => {
+      resolve(this.lookup(opts.value))
+    }, delay)
+  })
+}

test/fixtures/actions/index.js

@@ -4,4 +4,5 @@ module.exports = {
   error: require('./error.js')
 , greet: require('./greet.js')
 , name: require('./name.js')
+, delay: require('./delay.js')
 }

test/integration/actions/serial.js

@@ -0,0 +1,95 @@
+'use strict'
+
+const {test, threw} = require('tap')
+const Chain = require('../../../lib/chain.js')
+const actions = require('../../fixtures/actions/index.js')
+
+class ActionsChain extends Chain {
+  constructor(state) {
+    super(state, actions)
+    this.count = 0
+  }
+  $incr() {
+    return ++this.count
+  }
+}
+
+test('SetupChain.serial() as a builtin action', async (t) => {
+  const chain = new ActionsChain()
+
+  t.test('chain.serial is a function', async (t) => {
+    t.type(chain.serial, 'function', 'serial is a function')
+  })
+
+  t.test('Success; Call serial for an existing action', async (t) => {
+    const state = await chain
+      .serial(5, 'delay', {value: '!template("Bodhi {{!incr}}")'}, 'all_names')
+      .execute()
+
+    const expected = ['Bodhi 1', 'Bodhi 2', 'Bodhi 3', 'Bodhi 4', 'Bodhi 5']
+    t.same(state.all_names, expected, 'Expected result in state')
+    t.same(chain.state.all_names, expected, 'Expected result in chain.state')
+  })
+
+  t.test('Success; Call serial using a lookup', async (t) => {
+    const state = await chain
+      .serial(2, 'greet', {names: '#all_names', greeting: 'Hi'}, 'all_greetings')
+      .execute()
+
+    const greetings = [
+      'Hi Bodhi 1'
+    , 'Hi Bodhi 2'
+    , 'Hi Bodhi 3'
+    , 'Hi Bodhi 4'
+    , 'Hi Bodhi 5'
+    ]
+    const expected = [greetings, greetings]
+    t.same(state.all_greetings, expected, 'Expected result in state')
+    t.same(chain.state.all_greetings, expected, 'Result in chain.state')
+  })
+
+  t.test('Error: times is not a number', async (t) => {
+    const msg = new RegExp(
+      'requires \'times\' to be an integer and greater than or equal to 0'
+    )
+
+    t.rejects(chain.serial().execute(), {
+      err: msg
+    }, 'No parameters')
+
+    t.rejects(chain.serial(null).execute(), {
+      err: msg
+    }, 'times is null')
+
+    t.rejects(chain.serial({}).execute(), {
+      err: msg
+    }, 'times is an object')
+
+    t.rejects(chain.serial('ten').execute(), {
+      err: msg
+    }, 'times is a string')
+
+    t.rejects(chain.serial(-1).execute(), {
+      err: msg
+    }, 'times is a a negetive number')
+
+    t.rejects(chain.serial(1.1).execute(), {
+      err: msg
+    }, 'times is a decimal')
+
+    t.rejects(chain.serial(Number.POSITIVE_INFINITY).execute(), {
+      err: msg
+    }, 'times is a infinate')
+
+    t.rejects(chain.serial(NaN).execute(), {
+      err: msg
+    }, 'times is NaN')
+  })
+
+  t.test('Error: action is not a function', async (t) => {
+    const msg = new RegExp('\'NOPE\' does not exist as a chain action')
+    t.rejects(chain.serial(10, 'NOPE').execute(), {
+      err: msg
+    }, 'Unknown action')
+  })
+}).catch(threw)

test/integration/chain.js

@@ -210,11 +210,12 @@ test('Setup chain', async (t) => {
   t.test('Default SetupChain (no actions, state); Only built-ins', async (t) => {
     const chain = new Chain(null, null)
     t.same(chain.state, {}, 'Empty state')
-    t.equal(Object.keys(chain.actions).length, 5, 'Built-in action count')
+    t.equal(Object.keys(chain.actions).length, 6, 'Built-in action count')
     t.match(chain.actions, {
       map: Function
     , repeat: Function
     , sleep: Function
+    , serial: Function
     , sort: Function
     , set: Function
     }, 'Built-in action names')