BuildFlow

Library for building complex projects

Status

This is an early experimental version

Installation

npm i @buildflow/core

Concept

Build flow provides a composable set of so called "tasks" that are responsible for specific parts of the build process. Each task can implement functionality such as compiling or generating source code as well as monitoring the file system for changes that affect the inputs of the task. Each task can also have dependencies and can pass data to it's dependants in order to compose a modular build system.

Entry

The entry task is the "top level" task that represents the full workflow and uses other tasks as dependencies.

Invalidation

Invalidation is used to indicate that a task's output is no longer valid due to changes to it's direct inputs.
With the task itself, all it's dependents are also invalidated automatically. As soon as the invalidation is complete (waiting for pending tasks to complete) the runner will re-run the entry task.

State Cache

The state of each task is cached until a task is invalidated.
When an invalidated task is re-run and it uses another task as dependency that has not been invalidated, the cached state is used.

Tasks

Tasks are simple functions that must return a Promise and are called with the task context as first parameter.

async function example(task) {
    // TODO: Do something in here...
}

• task <TaskContext> - The task context which is an EventEmitter.

task.runner, this

The current runner instance can be accessed using this or task.runner.

task.options

Get the user options that were passed to the runner.

task.invalid

True if the task has been invalidated. Otherwise false.
Note that this only affects the current task context. If a task is re-run, the new instance of the task will have this property set to true.

async task.use(fn)

Run another task and get the result.
This will mark the dependency between the current and the used task.

await task.use(fn)

• fn <function> - The other task function to use.

task.invalidate()

Start invalidating this task and all it's dependents.

task.invalidate()

task.invalidateDependents()

Start invalidating all dependents of this task.

task.invalidateDependents()

event: invalidate

The invalidate event is emitted when the current task is beeing invalidated.
This event can be used to stop watching for changes or cleaning up other resources.

task.on('invalidate', () => {
    // TODO: Stop watching for changes...
})

Runner

The runner class is responsible for running tasks and keeping track of task states.

const {Runner} = require('@buildflow/core')

new Runner(entry[, options])

Create a new runner.
A runner instance is an EventEmitter.

const runner = new Runner(entry, options)

• entry <function> - The entry task function.
• options <object> - The user options that are passed to every task.

runner.options

Get the options object that is passed to every task.

async runner.run()

Start running the task and wait for the initial execution to finish.
Note that this can only be called a single time per runner instance.

await runner.run()

async runner.invalidate()

Invalidate the runner and all tasks.
This prevents the runner from re-running any task.

await runner.invalidate()

event: done

The done event is emitted when the entry task has resolved.
Note that this event can be caused by the initial execution and later ones when a task has been invalidated and re-run.

runner.on('done', res => { /* ... */ })

• res <any> - The value returned by the entry task.

event: error

The error event is emitted when a re-runned task failed or when an error occured during invalidation.

event: re-run

The re-run event is emitted when an invalidation is complete and the entry task will be re-run.