promake


Promise-based JS make clone that can target anything, not just files
This is my personal skeleton for creating an ES2015 library npm package. You are welcome to use it.

- Why promake? Why not jake, sake, etc?

* Quick start
- Install promake
- Create a make script
- Run the make script
* API Reference
- class Promake
- [rule(targets, [prerequisites], [recipe], [options])](#ruletargets-prerequisites-recipe-options)
- [hashRule(algorithm, target, prerequisites, [recipe], [options])](#hashrulealgorithm-target-prerequisites-recipe-options)
- [task(name, [prerequisites], [recipe])](#taskname-prerequisites-recipe)
- make(target)
- [exec(command, [options])](#execcommand-options)
- [spawn(command, [args], [options])](#spawncommand-args-options)
- [cli(argv = process.argv, [options])](#cliargv--processargv-options)
- log(verbosity, ...args)
- logStream(verbosity, stream)
- static Verbosity
- class Rule
- promake
- targets
- prerequisites
- args
- [description([newDescription])](#descriptionnewdescription)
- make(executionContext?: ExecutionContext)
- [then(onResolved, [onRejected])](#thenonresolved-onrejected)
- catch(onRejected)
- finally(onFinally)
- The Resource interface
- The HashResource interface
* How to
- Glob files
- Perform File System Operations
- Execute Shell Commands
- Pass args through to a shell command
- Make Tasks Prerequisites of Other Tasks
- Depend on Values of Environment Variables
- List available tasks
* Examples
- Transpiling files with Babel
- Basic Webapp

Why promake? Why not jake, sake, etc?

I wouldn't have introduced a new build tool if I hadn't thought I could significantly improve on what others offer.
Here is what promake does that others don't:

#### Promise-based interface

All other JS build tools I've seen have a callback-based API, which is much more cumbersome to use on modern JS VMs
than promises and async/await

#### Supports arbitrary resource types as targets and prerequistes

In addition to files. For instance you could have a rule that only builds a given docker image if some files or other
docker images have been updated since the last image was created.

#### No inversion of control container like jake, mocha, etc.

You tell it to run the CLI in your script, instead of running your script via a CLI. This means:

- You can easily use ES2015 and Coffeescript since you control the script
- It doesn't pollute the global namespace with its own methods like jake does
- It's obvious how to split your rule and task definitions into multiple files
- You could even use it in the browser for optimizing various chains of contingent operations

Quick start

$3

``sh
npm install --save-dev promake
`

$3

Save the following file as promake (or whatever name you want):

`js
#!/usr/bin/env node

const Promake = require('promake')

const { task, cli } = new Promake()

task('hello', () => console.log('hello world!'))

cli()
`

Make the script executable:

`
> chmod +x promake
`

$3

`
> ./promake hello
hello world!
`

API Reference

class Promake

Promake is just a class that you instantiate, add rules and tasks to, and then tell what to run. All of its methods
are autobound, so you can write const {task, rule, cli} = new Promake() and then run the methods directly without any
problems.

const Promake = require('promake')

$3

Creates a rule that indicates that targets can be created from prerequisites by running the given recipe.
If all targets exist and are newer than all prerequisites, promake will assume they are up-to-date and skip
the recipe.

If there is another rule for a given prerequisite, promake will run that rule first before running the recipe for this
rule. If any prerequisite doesn't exist and there is no rule for it, the build will fail.

##### target (required) and prerequisites (optional)

These can be:

- a string (strings are always interpreted as file system paths relative to the working directory)
- an object conforming to the Resource interface
- (_prerequisites only_) another Rule, which is the same as adding that Rule's own targets as prerequisites.
- or an array of the above

Warning: glob patterns (e.g. src/*/.js) in targets or prerequisites will not be expanded; instead you must
glob yourself and pass in the array of matching files. See Glob Files for an example of how to do so.

##### recipe (optional)

A function that should ensure that targets get created or updated. It will be called with one argument: the
Rule being run.

If recipe returns a Promise,
promake will wait for it to resolve before moving on to the next rule or task. If the recipe throws an Error or
returns a Promise that rejects, the build will fail.

##### options (optional)

- runAtLeastOnce - if true, the recipe will be run at least once, even if the targets are apparently up-to-date.
This is useful for rules that need to look at the contents of targets to decide whether to update them.

#### Returns

The created Rule.

You can get the Rule for a given target by calling rule(target) (without prerequisites or recipe), but it will
throw and Error if no such Rule exists, or you call it with multiple targets.

$3

Creates a rule that determines if it needs to be run by testing if the hash of
the prerequisites has changed (is different than the previous has written in
target, or target doesn't exist yet). After it does run, it will write the
hash to target.

This was created to help with CI builds where timestamps can't be used to
determine whether something cached from the previous build needs to be rebuilt.

##### algorithm (required)

The crypto.createHash algorithm to use.

##### target (required)

This must be a string or FileResource, to which the hash of the
prerequisites will be written.

##### prerequisites (required)

This must be an array of strings (file paths) or objects conforming to the HashResource interface
Warning: glob patterns (e.g. src/*/.js) in targets or prerequisites will not be expanded; instead you must
glob yourself and pass in the array of matching files. See Glob Files for an example of how to do so.

##### recipe (optional)

A function that should ensure that targets get created or updated. It will be called with one argument: the
Rule being run.

If recipe returns a Promise,
promake will wait for it to resolve before moving on to the next rule or task. If the recipe throws an Error or
returns a Promise that rejects, the build will fail.

##### options (optional)

- runAtLeastOnce - if true, the recipe will be run at least once, even if the targets are apparently up-to-date.
This is useful for rules that need to look at the contents of targets to decide whether to update them.

#### Returns

The created Rule.

$3

Creates a task, which is really just a rule, but can be run by name from the CLI regardless of whether name is an
actual file that exists, similar to a phony target in make.

Task names take precedence over file names when specifying what to build in CLI options.

You can set the description for the task by calling .description()
on the returned Rule. This description will be printed alongside the task
if you call the CLI without any targets. For example:

`js
task('clean', () => require('fs-extra').remove('build')).description(
'removes build output'
)
`

##### name

The name of the task

##### prerequisites (optional)

These take the same form as for a rule, and if given, promake will ensure that they exist and are
up-to-date before the task is running, running any rules applicable to the prerequisites as necessary.

Warning: putting the name of another task in prerequisites does not work because all strings in
prerequisites are interpreted as files. See
Make Tasks Prerequisites of Other Tasks for more details.

##### recipe (optional)

If given, it will be run any time the task is requested, even if the prerequisites are up-to-date.
recipe will be called with one argument: the Rule being run.

If recipe returns a Promise,
promake will wait for it to resolve before moving on to the next rule or task. If the recipe throws an Error or
returns a Promise that rejects, the build will fail.

#### Returns

The created Rule.

Calling task(name) without any prerequisites or recipe looks up and returns the previously created task Rule for
name, but _it will throw an Error_ if no such task exists.

$3

Makes the given target if necessary.

##### target

The name of a task or file, or an object conforming to the Resource interface

#### Returns

A Promise that will be resolved when the target recipe succeeds (or doesn't need to be rerun) or rejects when the target
recipe fails.

$3

This is a wrapper for exec from promisify-child-process
with a bit of extra logic to handle logging. It has the same
API as child_process
but the returned ChildProcess also has then and catch methods like a Promise, so it can be awaited.

$3

This is a wrapper for spawn from promisify-child-process
with a bit of extra logic to handle logging. It has the same
API as child_process
but the returned ChildProcess also has then and catch methods like a Promise, so it can be awaited.

$3

Runs the command-line interface for the given arguments, which should include requested targets
(names of files or tasks).
Unless options.exit === false, after running all requested targets, it will exit the process with a code
of 0 if the build succeeded, and nonzero if the build failed.

If no targets are requested, prints usage info and the list of available tasks and exits with a code of 0.

##### argv (optional, default: process.argv)

The command-line arguments. May include:

- Task names - these tasks will be run, in the order requested
- File names - rules for these files will be run, in the order requested
- --quiet, -q: suppress output

As long as none of the args you want to pass don't correspond to a target name,
you can just add them after the target:

`
runDocker --rm --env FOO=BAR
`

But you can pass any arbitrary args to the rule for a target by adding
-- args... after the rule:

`
runDocker -- --rm --env FOO=BAR
`

If you want to pass args to multiple rules, put another -- after the args to a rule:

`
runDocker -- --rm --env FOO=BAR -- runNpm -- install --save-dev somepackage
`

(args to rule for runDocker: --rm --env FOO=BAR, args to rule for runNpm: install --save-dev somepackage)

If, god forbit, you want to pass -- as an arg to a rule, use ----:

`
runNpm -- nyc ---- --grep something
`

(args to rule for runNpm become nyc -- --grep something)

##### options (optional)

An object that may have the following properties:

- exit - unless this is false, cli() will exit once it has finished running the requested tasks and file rules.

#### Returns

A Promise that will resolve when Promake finishes running the requested tasks and file rules, or throw if it fails
(but this is only useful if options.exit === false to prevent cli() from calling process.exit when it's done).

$3

Logs ...args to console.error unless verbosity is higher than the user requested.

#### verbosity

One of the enum constants in Promake.Verbosity.

#### ...args

The things to log

$3

Pipes stream to stderr unless verbosity is higher than the user requested.

#### verbosity

One of the enum constants in Promake.Verbosity.

#### stream

An instance of stream.Readable.

$3

An enumeration of verbosity levels for logging: has keys QUIET, DEFAULT, and HIGH.

class Rule

This is an instance of a rule created by Promake.rule or Promake.task. It has the following properties:

$3

The instance of Promake this rule was created in.

$3

The normalized array of resources this rule produces.

$3

The normalized array of resources that must be made before running this rule.

$3

Any args for this rule (from the CLI, usually)

$3

Gets or sets the description of this rule. If you provide an argument,
sets the description and returns this rule. Otherwise, returns the
description.

$3

Starts running this rule if it hasn't already been run in executionContext. An ExecutionContext will be created
if none was passed. Returns a Promise that will resolve or reject when the rule finished running successfully or
failed.

$3

Same as calling make().then(onResolved, onRejected).

$3

Same as calling make().catch(onRejected).

$3

Same as calling make().finally(onFinally).

The Resource interface

This is an abstraction that allows promake to apply the same build logic to input and output resources of any type,
not just files. (Internally, promake converts all strings in targets and prerequisites to FileResources.)

Warning: due to the semantics of JS Maps, two Resource
instances are always considered different, even if they represent the same resource. So if you are using non-file
Resources, you should only create and use a single instance for a given resource.

Currently, instances need to define only one method:

##### lastModified(): Promise

If the resource doesn't exist, the returned Promise should resolve to null or undefined.
Otherwise, it should resolve to the resource's last modified time, in milliseconds.

The HashResource interface

This is an abstraction that allows promake to apply the same build logic to input and output resources of any type,
not just files. (Internally, promake converts all strings in targets and prerequisites to FileResources.)

Currently, instances need to define only one method:

##### updateHash(hash: Hash): Promise

If the resource exists, the given hash should be updated with whatever data
from the resource is relevant (e.g. the contents of a file, which is what
FileResource's implementation of updateHash does)

How to

Glob files

promake has no built-in globbing; you must pass arrays of files to rules and tasks. This is easy with the
glob package:

`sh
npm install --save-dev glob
`

In your promake script:

`js
const glob = require('glob').sync
const srcFiles = glob('src/*/.js')
const libFiles = srcFiles.map((file) => file.replace(/^src/, 'lib'))
rule(libFiles, srcFiles, () => {
/ code that compiles srcFiles to libFiles /
})
`

Perform File System Operations

I recommend using fs-extra:

`sh
npm install --save-dev fs-extra
`

To perform a single operation in a task, you can just return the Promise from async fs-extra operations:

`js
const fs = require('fs-extra')
rule(dest, src, () => fs.copy(src, dest))
`

To perform multiple operations one after another, you can use an async lambda and await each operation:

`js
const path = require('path')
const fs = require('fs-extra')
rule(dest, src, async () => {
await fs.mkdirs(path.dirname(dest)))
await fs.copy(src, dest))
})
`

Execute Shell Commands

Use the exec method
or the spawn method of your Promake instance.

`js
const { rule, exec, spawn } = new Promake()
`

To run a single command in a task, you can just return the result of exec or spawn because it is Promise-like:

`js
rule(dest, src, () => exec(cp ${src} ${dest}))
`

To run multiple commands, you can use an async lambda and await each exec or spawn call:

`js
rule(dest, src, async () => {
await exec(cp ${src} ${dest})
await exec(git add ${dest})
await exec(git commit -m "update ${dest}")
})
`

Pass args through to a shell command

The args from the CLI are avaliable on Rule.args:

`js
const { rule, spawn } = new Promake()

task('npm', (rule) => spawn('npm', rule.args))
`

And run your task with:

`
./promake npm -- install --save-dev somepackage
`

See CLI documentation for more details.

Make Tasks Prerequisites of Other Tasks

Putting the name of another task in the prerequisites of rule or task does not work because all strings in
prerequisites are interpreted as files.

Instead, you can just include the Rule returned by rule or task in the prerequisites of another. For example:

`js
const serverTask = task('server', [...serverBuildFiles, ...universalBuildFiles])
const clientTask = task('client', clientBuildFiles)
task('build', [serverTask, clientTask])
`

Or you can call task(name) to get a reference to the previously created Rule:

`js
task('server', [...serverBuildFiles, ...universalBuildFiles])
task('client', clientBuildFiles)
task('build', [task('server'), task('client')])
`

Sometimes I like to use the following structure for defining an all task:

`js
task('all', [
task('server', [...serverBuildFiles, ...universalBuildFiles]),
task('client', clientBuildFiles),
])
`

Depend on Values of Environment Variables

Use the promake-env package:

`sh
npm install --save-dev promake-env
`

`js
const {rule, exec} = new Promake()
const envRule = require('promake-env').envRule(rule)

const src = ...
const lib = ...
const buildEnv = 'lib/.buildEnv'

envRule(buildEnv, ['NODE_ENV', 'BABEL_ENV'])
rule(lib, [...src, buildEnv], () => exec('babel src/ --out-dir lib'))
`

List available tasks

Run the CLI without specifying any targets. For instance if your
build file is promake, run:

`
> ./promake
promake CLI, version X.X.X
https://github.com/jcoreio/promake/tree/vX.X.X

Usage:
./