avvio

What is avvio?

The avvio npm package is designed to handle the asynchronous bootstrapping of applications, particularly those built with Node.js. It allows developers to define a series of asynchronous (or synchronous) tasks that need to be executed in a specific order during the startup phase of an application. This can include initializing databases, setting up dependencies, or any other setup tasks that need to be completed before the application starts serving requests. Avvio ensures that each task is completed before moving on to the next, and it provides a clean API for managing this process.

What are avvio's main functionalities?

Plugin System

Avvio allows you to structure your application initialization in a modular way using plugins. Each plugin can be an asynchronous function that performs some initialization tasks. The `use` method is used to register these plugins, and Avvio ensures they are executed in the order they are registered.

const avvio = require('avvio')(app);
avvio.use(function (instance, opts, done) {
  // async initialization task
  done();
});

Async/Await Support

Avvio supports modern JavaScript async/await syntax out of the box. This allows for cleaner and more readable asynchronous code within your initialization tasks.

const avvio = require('avvio')(app);
avvio.use(async function (instance, opts) {
  // async task using await
});

Encapsulation and Context

Avvio provides a mechanism for encapsulation and context sharing across plugins. Using the `decorate` method, you can add properties or methods to the application instance that can be accessed by subsequent plugins, facilitating a shared context.

const avvio = require('avvio')(app);
avvio.use(function (instance, opts, done) {
  instance.decorate('utility', () => {});
  done();
});

Other packages similar to avvio

fastify

Fastify is a web framework for Node.js that includes a powerful plugin architecture, somewhat similar to Avvio. While Fastify is more focused on building web applications and APIs, it uses an underlying plugin system inspired by Avvio for managing the application lifecycle.

pino

Pino is a very fast JSON logger for Node.js, and while it doesn't offer plugin-based application bootstrapping like Avvio, it can be integrated into applications using Avvio for structured and efficient logging throughout the application lifecycle.

seneca

Seneca is a microservices toolkit for Node.js that allows you to write microservices easily and quickly. It offers a plugin system that can be seen as similar to Avvio's, focusing on the modular construction of applications, though it is more oriented towards microservice architecture.

README

avvio

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 made 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.

• Install
• Example
• API
• Acknowledgements
• License

Install

To install avvio, simply use npm:

npm install avvio --save

Example

The example below can be found here and ran 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 () {
  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')
}

API

• avvio()
• instance.use()
• instance.after()
• instance.ready()
• instance.start()
• instance.override()
• instance.onClose()
• instance.close()
• avvio.express()

---

avvio([instance], [options], [started])

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 how use, after and ready are exposed.
• autostart: do not start loading plugins automatically, but wait for a call to .start()  or .ready().

Events:

• 'start'  when the application starts
• 'preReady' fired before the ready queue is run

The avvio function can be used also as a constructor to inherits 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
})

---

app.use(func, [opts])

Loads one or more functions asynchronously. The function must have the signature: instance, options, done

Plugin example:

function plugin (server, opts, done) {
  done()
}

app.use(plugin)

done must be called only once, when your plugin is ready to go.

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.

Error handling

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.

---

app.after(func(error, [context], [done]))

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:

1. If no parameter is given to the callback and there is an error, that error will be passed to the next error handler.
2. If one parameter is given to the callback, that parameter will be the error object.
3. If two parameters are given to the callback, the first will be the error object, the second will be the done callback.
4. If three parameters are given to the callback, the first will be the error object, the second will be the top level context unless you have specified both server and override, in that case the context will be what the override returns, and the third the done 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.

---

app.ready([func(error, [context], [done])])

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:

1. If no parameter is given to the callback and there is an error, that error will be passed to the next error handler.
2. If one parameter is given to the callback, that parameter will be the error object.
3. If two parameters are given to the callback, the first will be the error object, the second will be the done callback.
4. If three parameters are given to the callback, the first will be the error object, the second will be the top level context unless you have specified both server and override, in that case the context will be what the override returns, and the third the done 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.

---

app.start()

Start the boot sequence, if it was not started yet. Returns the app instance.

---

avvio.express(app)

Same as:

const app = express()
const avvio = require('avvio')

avvio(app, {
  expose: {
    use: 'load'
  }
})

---

app.override(server, plugin, options)

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()
  }
})

---

app.onClose(func([context], [done]))

Registers a new callback that will be fired once then close api is called.

The callback changes basing on the parameters your are giving:

1. If one parameter is given to the callback, that parameter will be the context.
2. If zero or one parameter is given, the callback may return a promise
3. 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 the context will be what the override returns, the second will be the done 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.

---

app.close(func(error, [context], [done]))

Starts the shutdown procedure, the callback is called once all the registered callbacks with onClose has been executed.

The callback changes basing on the parameters your are giving:

1. If one parameter is given to the callback, that parameter will be the error object.
2. If two parameters are given to the callback, the first will be the error object, the second will be the done callback.
3. If three parameters are given to the callback, the first will be the error object, the second will be the top level context unless you have specified both server and override, in that case the context will be what the override returns, and the third the done callback.

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()
})

done must be called only once.

---

Acknowledgements

This project was kindly sponsored by nearForm.

License

Copyright Matteo Collina 2016-2017, Licensed under MIT.