Asynchronous bootstrapping is hard, different things can go wrong, error handling and load order just to name a few. The module aims 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.
TypeScript type definitions are bundled with the package (index.d.ts), so no extra @types package is needed.
To enable internal debug logging, run your application with the NODE_DEBUG=avvio environment variable set:
NODE_DEBUG=avvio node app.js
Example
The example below demonstrates how to use avvio to load functions and plugins in order.
'use strict'const app = require('avvio')()app .use(first, { hello: 'world' }) .after((err, cb) => { if (err) { throw err } console.log('after first and second') cb() })app.use(third)app.ready(function (err) { 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 supportasync function third (instance, opts) { console.log('third loaded')}
The important part of this example is that first registers second while it is loading.
This creates the following plugin tree:
root├── first│ └── second└── third
The plugins are loaded in this order:
firstsecondthird
Only after the required plugins have completed can the application become ready.
How Avvio works
Avvio builds a tree of plugins and loads that tree in a predictable order.
The main concepts are:
plugins can register other plugins;
nested plugins become dependencies of their parent;
plugins are loaded according to their position in the tree;
after() waits for plugins registered before it;
ready() waits for the complete boot process;
errors stop the boot process until they are handled or propagated to ready();
onClose() and close() provide the shutdown lifecycle.
The plugin tree
A call to use() adds a plugin to the current context.
A plugin can register additional plugins while it is loading. Those plugins become children of the current plugin.
For example:
app.use(first)app.use(third)function first (instance, opts, done) { instance.use(second) done()}
creates this tree:
root├── first│ └── second└── third
The nested second plugin belongs to first, because it was registered while first was loading.
This is what makes Avvio reentrant: a plugin can use the same application instance to register more plugins without losing the correct execution order.
Load order
Avvio loads plugins according to their position in the plugin tree.
Given:
app.use(first)app.use(third)function first (instance, opts, done) { instance.use(second) done()}function second (instance, opts, done) { done()}function third (instance, opts, done) { done()}
the execution order is:
firstsecondthird
second must finish before Avvio can continue with third, because second is a dependency of first.
This allows plugins to register the components they depend on without requiring the application to manually calculate the complete load order.
The boot lifecycle
The boot process can be thought of as a sequence of phases:
use() │ │ register plugins ▼plugin loading │ │ nested plugins are loaded ▼after() │ │ wait for plugins registered so far ▼ready() │ │ wait for the complete boot process ▼start
A plugin can register more plugins while it is loading:
As the name suggests, instance is the object representing your application. Avvio adds the functions use, after, ready, onClose, and close to the instance.
const server = {}require('avvio')(server)server .use(function first (s, opts, cb) { s.use(function second (s, opts, cb) { cb() }) cb() }) .after(function (err, cb) { if (err) { throw err } // first and second are finished cb() })
Options
expose
A key/value property to change how use, after, ready, onClose, and close are exposed on the instance.
This is useful when one of the default names is already taken.
'%s' is already defined, specify an expose option for '%s'
Thrown when a property that Avvio needs to expose on the instance (use, after, ready, onClose, close) is already taken. Use the expose option to rename it.
AVV_ERR_ATTRIBUTE_ALREADY_DEFINED
'%s' is already defined
Thrown when the instance already has a then property, which Avvio needs to make itself awaitable.
AVV_ERR_CALLBACK_NOT_FN
Callback for '%s' hook is not a function. Received: '%s'
Thrown when a non-function value is passed where a callback (ready, close, onClose, etc.) is expected.
AVV_ERR_PLUGIN_NOT_VALID
Plugin must be a function or a promise. Received: '%s'
Thrown when the value passed to use() is neither a function nor a thenable.
AVV_ERR_ROOT_PLG_BOOTED
Root plugin has already booted
Thrown when calling use() after the instance has already booted.
AVV_ERR_PARENT_PLG_LOADED
Impossible to load '%s' plugin because the parent '%s' was already loaded
Thrown when trying to register a plugin on a parent that has already finished loading.
AVV_ERR_READY_TIMEOUT
Plugin did not start in time: '%s'. You may have forgotten to call 'done' function or to resolve a Promise
Thrown when a ready() or after() callback does not complete before the configured timeout elapses.
AVV_ERR_PLUGIN_EXEC_TIMEOUT
Plugin did not start in time: '%s'. You may have forgotten to call 'done' function or to resolve a Promise
Thrown when a plugin passed to use() does not complete before the configured timeout elapses.
The plugin or callback name used in '%s' is derived from the function name, an explicit name option, or, for fastify-plugin-wrapped plugins, the metadata attached to the plugin.