Asynchronous bootstrapping is hard, different things can go wrong, error handling and load order just to name a few. The aim of this module is to make it simple.
avvio
is fully reentrant and graph-based. You can load
components/plugins within plugins, and be still sure that things will
happen in the right order. At the end of the loading, your application will start.
To install avvio
, simply use npm:
npm install avvio --save
The example below can be found here and run using node example.js
.
It demonstrates how to use avvio
to load functions / plugins in order.
'use strict'
const app = require('avvio')()
app
.use(first, { hello: 'world' })
.after((err, cb) => {
console.log('after first and second')
cb()
})
app.use(third)
app.ready(function (err) {
// the error must be handled somehow
if (err) {
throw err
}
console.log('application booted!')
})
function first (instance, opts, cb) {
console.log('first loaded', opts)
instance.use(second)
cb()
}
function second (instance, opts, cb) {
console.log('second loaded')
process.nextTick(cb)
}
// async/await or Promise support
async function third (instance, opts) {
console.log('third loaded')
}
avvio()
instance.use()
instance.after()
instance.ready()
instance.start()
instance.override()
instance.onClose()
instance.close()
avvio.express()
avvio.toJSON()
avvio.prettyPrint()
Starts the avvio sequence.
As the name suggest, instance
is the object representing your application.
Avvio will add the functions use
, after
and ready
to the instance.
const server = {}
require('avvio')(server)
server.use(function first (s, opts, cb) {
// s is the same of server
s.use(function second (s, opts, cb) {
cb()
})
cb()
}).after(function (err, cb) {
// after first and second are finished
cb()
})
Options:
expose
: a key/value property to change howuse
,after
andready
are exposed.autostart
: do not start loading plugins automatically, but wait for a call to.start()
or.ready()
.timeout
: the number of millis to wait a plugin to load after which it will error with codeERR_AVVIO_PLUGIN_TIMEOUT
. Default0
(disabled).
Events:
'start'
when the application starts'preReady'
fired before the ready queue is run
The avvio
function can also be used as a
constructor to inherit from.
function Server () {}
const app = require('avvio')(new Server())
app.use(function (s, opts, done) {
// your code
done()
})
app.on('start', () => {
// you app can start
})
Loads one or more functions asynchronously.
The function must have the signature: instance, options, done
However, if the function returns a Promise
(i.e. async
), the above function signature is not required.
Plugin example:
function plugin (server, opts, done) {
done()
}
app.use(plugin)
done
should be called only once, when your plugin is ready to go. Additional
calls to done
are ignored.
async/await is also supported:
async function plugin (server, opts) {
await sleep(10)
}
app.use(plugin)
use
returns the instance on which use
is called, to support a chainable API.
A function that returns the options argument instead of an object is supported as well:
function first (server, opts, done) {
server.foo = 'bar'
done()
}
function second (server, opts, done) {
console.log(opts.foo === 'bar') // Evaluates to true
done()
}
/**
* If the options argument is a function, it has access to the parent
* instance via the first positional variable
*/
const func = parent => {
return {
foo: parent.foo
}
}
app.use(first)
app.use(second, func)
This is useful in cases where an injected variable from a plugin needs to be made available to another.
It is also possible to use esm with import('./file.mjs')
:
import boot from 'avvio'
const app = boot()
app.use(import('./fixtures/esm.mjs'))
In order to handle errors in the loading plugins, you must use the
.ready()
method, like so:
app.use(function (instance, opts, done) {
done(new Error('error'))
}, opts)
app.ready(function (err) {
if (err) throw err
})
When an error happens, the loading of plugins will stop until there is
an after
callback specified. Otherwise, it will be handled
in ready
.
Calls a function after all the previously defined plugins are loaded, including
all their dependencies. The 'start'
event is not emitted yet.
The callback changes basing on the parameters your are giving:
- If no parameter is given to the callback and there is an error, that error will be passed to the next error handler.
- If one parameter is given to the callback, that parameter will be the
error
object. - If two parameters are given to the callback, the first will be the
error
object, the second will be thedone
callback. - If three parameters are given to the callback, the first will be the
error
object, the second will be the top levelcontext
unless you have specified both server and override, in that case thecontext
will be what the override returns, and the third thedone
callback.
In the "no parameter" and "one parameter" variants, the callback can also
return a Promise
.
const server = {}
const app = require('avvio')(server)
...
// after with one parameter
app.after(function (err) {
if (err) throw err
})
// after with two parameter
app.after(function (err, done) {
if (err) throw err
done()
})
// after with three parameters
app.after(function (err, context, done) {
if (err) throw err
assert.equal(context, server)
done()
})
// async after with one parameter
app.after(async function (err) {
await sleep(10)
if (err) {
throw err
}
})
// async after with no parameter
app.after(async function () {
await sleep(10)
})
done
must be called only once.
Returns the instance on which after
is called, to support a chainable API.
Calls a function after all the plugins and after
call are completed, but before 'start'
is emitted. ready
callbacks are executed one at a time.
The callback changes basing on the parameters your are giving:
- If no parameter is given to the callback and there is an error, that error will be passed to the next error handler.
- If one parameter is given to the callback, that parameter will be the
error
object. - If two parameters are given to the callback, the first will be the
error
object, the second will be thedone
callback. - If three parameters are given to the callback, the first will be the
error
object, the second will be the top levelcontext
unless you have specified both server and override, in that case thecontext
will be what the override returns, and the third thedone
callback.
If no callback is provided ready
will return a Promise that is resolved or rejected once plugins and after
calls are completed. On success context
is provided to the .then
callback, if an error occurs it is provided to the .catch
callback.
const server = {}
const app = require('avvio')(server)
...
// ready with one parameter
app.ready(function (err) {
if (err) throw err
})
// ready with two parameter
app.ready(function (err, done) {
if (err) throw err
done()
})
// ready with three parameters
app.ready(function (err, context, done) {
if (err) throw err
assert.equal(context, server)
done()
})
// ready with Promise
app.ready()
.then(() => console.log('Ready'))
.catch(err => {
console.error(err)
process.exit(1)
})
// await ready from an async function.
async function main () [
try {
await app.ready()
console.log('Ready')
} catch(err) {
console.error(err)
process.exit(1)
}
}
done
must be called only once.
The callback form of this function has no return value.
If autostart: false
is passed as an option, calling .ready()
will
also start the boot sequence.
Start the boot sequence, if it was not started yet.
Returns the app
instance.
Same as:
const app = express()
const avvio = require('avvio')
avvio(app, {
expose: {
use: 'load'
}
})
Allows to override the instance of the server for each loading plugin. It allows the creation of an inheritance chain for the server instances. The first parameter is the server instance and the second is the plugin function while the third is the options object that you give to use.
const assert = require('assert')
const server = { count: 0 }
const app = require('avvio')(server)
console.log(app !== server, 'override must be set on the Avvio instance')
app.override = function (s, fn, opts) {
// create a new instance with the
// server as the prototype
const res = Object.create(s)
res.count = res.count + 1
return res
}
app.use(function first (s1, opts, cb) {
assert(s1 !== server)
assert(server.isPrototypeOf(s1))
assert(s1.count === 1)
s1.use(second)
cb()
function second (s2, opts, cb) {
assert(s2 !== s1)
assert(s1.isPrototypeOf(s2))
assert(s2.count === 2)
cb()
}
})
Registers a new callback that will be fired once then close
api is called.
The callback changes basing on the parameters your are giving:
- If one parameter is given to the callback, that parameter will be the
context
. - If zero or one parameter is given, the callback may return a promise
- If two parameters are given to the callback, the first will be the top level
context
unless you have specified both server and override, in that case thecontext
will be what the override returns, the second will be thedone
callback.
const server = {}
const app = require('avvio')(server)
...
// onClose with one parameter
app.onClose(function (context) {
// ...
})
// onClose with one parameter, returning a promise
app.onClose(function (context) {
return new Promise((resolve, reject) => {
// ...
})
})
// async onClose with one parameter
app.onClose(async function (context) {
// ...
await ...
})
// onClose with two parameter
app.onClose(function (context, done) {
// ...
done()
})
If the callback returns a promise, the next onClose callback and the close callback won't run until the promise is either resolved or rejected.
done
must be called only once.
Returns the instance on which onClose
is called, to support a chainable API.
Starts the shutdown procedure, the callback is called once all the registered callbacks with onClose
has been executed.
The callback changes based on the parameters your are giving:
- If one parameter is given to the callback, that parameter will be the
error
object. - If two parameters are given to the callback, the first will be the
error
object, the second will be thedone
callback. - If three parameters are given to the callback, the first will be the
error
object, the second will be the top levelcontext
unless you have specified both server and override, in that case thecontext
will be what the override returns, and the third thedone
callback.
If no callback is provided close
will return a Promise.
const server = {}
const app = require('avvio')(server)
...
// close with one parameter
app.close(function (err) {
if (err) throw err
})
// close with two parameter
app.close(function (err, done) {
if (err) throw err
done()
})
// close with three parameters
app.close(function (err, context, done) {
if (err) throw err
assert.equal(context, server)
done()
})
// close with Promise
app.close()
.then(() => console.log('Closed'))
.catch(err => {
console.error(err)
process.exit(1)
})
done
must be called only once.
Return a JSON tree rappresenting the state of the plugins and the loading time.
Call it on preReady
to get the complete tree.
const avvio = require('avvio')()
avvio.on('preReady', () => {
avvio.toJSON()
})
The ouput is like this:
{
"label": "bound root",
"start": 1550245184665,
"nodes": [
{
"parent": "bound root",
"start": 1550245184665,
"label": "first",
"nodes": [
{
"parent": "first",
"start": 1550245184708,
"label": "second",
"nodes": [],
"stop": 1550245184709,
"diff": 1
}
],
"stop": 1550245184709,
"diff": 44
},
{
"parent": "bound root",
"start": 1550245184709,
"label": "third",
"nodes": [],
"stop": 1550245184709,
"diff": 0
}
],
"stop": 1550245184709,
"diff": 44
}
This method will return a printable string with the tree returned by the toJSON()
method.
const avvio = require('avvio')()
avvio.on('preReady', () => {
console.log(avvio.prettyPrint())
})
The output will be like:
avvio 56 ms
├── first 52 ms
├── second 1 ms
└── third 2 ms
This project was kindly sponsored by nearForm.
Copyright Matteo Collina 2016-2017, Licensed under MIT.