Hamburger.js

A thread first Promise execution DSL.

Example

We will solve the async-problem:

Given a path to a directory containing an index file, index.txt, and zero or more other files, read the index file (which contains one filename per line), then read each of the files listed in the index concurrently, concat the resulting strings (in the order specified by the index), and write the result to stdout.

A solution:

1const fs = require('fs')
2const path = require('path')
3const hamburger = require('hamburger')
4
5const Promise = require('bluebird')
6const _ = require('lodash')
7
8const readFile = Promise.promisify(fs.readFile)
9
10const concatFiles = (dir) =>
11  hamburger
12  ()
13    (dir)
14    (path.join, 'index.txt')
15    (readFile, {encoding: 'utf8'})
16    (_.split, '\n')
17    (_.filter)
18    (_.map, _.unary(_.partial(path.join, dir)))
19    (_.map, _.partial(readFile, _, {encoding: 'utf8'}))
20    (Promise.all)
21    (_.join, '')
22  ()
23
24const main = () => {
25  concatFiles(process.argv[2])
26  .then(data => {
27      process.stdout.write(data)
28      process.exit(0)
29    },
30    err => {
31      process.stderr.write(String(err) + '\n')
32      process.exit(1)
33    })
34}
35
36if (process.mainModule.filename === __filename) main()

Discussion

Here is concatFiles again, but annotated:

1/**
2 * concatFiles accepts a directory and returns
3 * a Promise solving the async-problem described above.
4 */
5function concatFiles(dir){
6  // Call hamburger with no args to start a chain
7  // which returns functions that accept tasks to
8  // run. The returned function will continue returning
9  // functions until called with no arguments. Once
10  // called with no arguments, the tasks will be run in
11  // the order defined threading the result of each function
12  // call as the the first argument of the next task
13  return hamburger()
14
15    // If the first argument in a task is not a function
16    // it is resolved as a Promise. Once resolved, it is
17    // threaded into the first argument of the next task
18    // Here `dir` is a String, so it is resolved directly.
19    (dir)
20
21    // The first argument is a function, so it is called
22    // with the result of the previous task as the first
23    // argument and any additional arguments following the
24    // first, i.e, `path.join(dir, 'input.txt)`. The result
25    // of this function is threaded to the first argument
26    // of the next task
27    (path.join, 'index.txt')
28
29    // `readFile` is a promisified version of `fs.readFile`.
30    // Since it is a function, it is called with the result
31    // of the previous task arguments:
32    //
33    // readFile(path.join(dir, 'input.txt'))
34    //
35    // This returns a promise which will be resolved before
36    // threading into the next task
37    (readFile, {encoding: 'utf8'})
38
39    // Since the previous task returned a promise, it must
40    // be resolved. The result is threaded into the first
41    // argument of the next task:
42    //
43    // readFile(path.join(dir, 'input.txt'))
44    //  .then((result) => _.split(result, '\n')
45    //
46    // This results in an array of lines in the file
47    (_.split, '\n')
48
49    // The array of lines is threaded into `_.filter(lines)`
50    // to remove any empty lines.
51    (_.filter)
52
53    // We have an array of file names, map this array using
54    // a function that joins the directory before the filename
55    // We are using `_.unary` here because `_.map` includes
56    // the array index, which we want to ignore in `join`.
57    //
58    // _.map(fileNames, (fileName) => path.join(dir, fileName))
59    //
60    (_.map, _.unary(_.partial(path.join, dir)))
61
62    // We now have an array of fully qualified file paths
63    // Map this again using the promisified `readFile`
64    //
65    // _.map(filePaths, (filePath) =>
66    //    readFile(filePath, {encoding: 'utf8'}))
67    //
68    // This will return an array of promises. Each promise
69    // is reading a file and the files are read in parallel
70    (_.map, _.partial(readFile, _, {encoding: 'utf8'}))
71
72    // We have an array of Promises, await with `Promise.all`:
73    //
74    // Promise.all(arrayOfReadFilePromises)
75    //
76    // This returns a new Promise that  awaits all `readFile`
77    // promises to complete. The returned promise will be
78    // resolved with an array of file contents as UTF8 strings.
79    (Promise.all)
80
81    // Join the array of file contents
82    //
83    // Promise.all(arrayOfReadFilePromises)
84    //   .then((contentsArray) => _.join(contentsArray, ''))
85    //
86    (_.join, '')
87
88    // We are done adding tasks, call with no-args to end the
89    // chain and return a Promise of the result of the final task.
90  ()
91}

Tasks

The function chaining is sugar for building an array of tasks. Each task is defined as an array.

• If the first argument of the array is not a function, it is resolved as a Promise and threaded as the first argument of the next task.
• If the first argument of the array is a function, it is executed with the result of the previous task as the first argument and any additional arguments defined in the array as additional arguments.
• If the first argument is undefined, i.e. the function is called with no arguments, it is not added as a task. Instead the first task is executed and a Promise is returned for the result of the entire task chain.

Here is the example again with tasks explicitly created without the function chaining sugar:

1function concatFiles(dir){
2  // create a thunk of tasks
3  var burger = hamburger([
4    [dir],
5    [path.join, 'index.txt'],
6    [readFile, {encoding: 'utf8'}],
7    [_.split, '\n'],
8    [_.filter],
9    [_.map, _.unary(_.partial(path.join, dir))],
10    [_.map, _.partial(readFile, _, {encoding: 'utf8'})],
11    [Promise.all],
12    [_.join, '']
13  ])
14
15  // execute the thunk of tasks and return the Promise
16  return burger()
17}

Note the first task will not be run until the thunk is executed (by calling with no arguments) and any subsequent task will not run until prior tasks have completed. The returned thunk can be executed multiple times with all tasks executed again. This can be used for rerunning the same tasks that may have side effects, e.g. a request to a web service that changes over time. In our example, we could re-execute the task chain if the contents of the files change over time.

1function concatFilesThunk(dir){
2  // create a thunk of tasks
3  var burger = hamburger([
4    [dir],
5    [path.join, 'index.txt'],
6    [readFile, {encoding: 'utf8'}],
7    [_.split, '\n'],
8    [_.filter],
9    [_.map, _.unary(_.partial(path.join, dir))],
10    [_.map, _.partial(readFile, _, {encoding: 'utf8'})],
11    [Promise.all],
12    [_.join, '']
13  ])
14
15  // return the reusable thunk
16  return burger
17}
18
19var thunk = concatFilesThunk(dir)
20
21// re-execute the task chain multiple times
22thunk().then((result1) => {})
23thunk().then((result2) => {})