avvio

Avvio is a graph-based, reentrant asynchronous bootstrapper. It allows you to load plugins or components in a specific order, even when loading plugins from within other plugins. It supports both callback-style and async/await functions.

Key features:

• Reentrancy: You can call .use() inside a plugin being loaded by avvio.
• Graph-based: Ensures correct load order and dependency management.
• Flexible API: Supports callbacks, Promises, and async/await.

'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) {
  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 function third (instance, opts) {
  console.log('third loaded')
}

To start the Avvio sequence, call avvio([instance], [options], [started]). The instance is the object representing your application (e.g., a server object). Avvio will augment this instance with the use, after, and ready methods. You can also use avvio as a constructor to inherit from it.

Configuration Options

• expose: A key/value property to change how use, after, and ready are exposed on the instance.
• autostart: If set to false, Avvio will not start loading plugins automatically; it will wait for a call to .start() or .ready().
• timeout: The number of milliseconds to wait for a plugin to load before erroring with ERR_AVVIO_PLUGIN_TIMEOUT. Default is 0 (disabled).

Events

• 'start': Emitted when the application starts.
• 'preReady': Emitted before the ready queue is run.

const server = {}

require('avvio')(server)

server.use(function first (s, opts, cb) {
  // s is the same as server
  s.use(function second (s, opts, cb) {
    cb()
  })
  cb()
}).after(function (err, cb) {
  // after first and second are finished
  cb()
})

The app.after(func) method calls a function after all previously defined plugins (and their dependencies) have loaded. Note that the 'start' event is not yet emitted.

Callback Signatures

The callback behavior changes based on the number of arguments provided:

1. 0 args: (err) => void. If an error occurs, it is passed to the next error handler.
2. 1 arg: (err) => void. The parameter is the error object.
3. 2 args: (err, done) => void. The first is the error, the second is the done callback.
4. 3 args: (err, context, done) => void. The first is the error, the second is the top-level context, and the third is the done callback.

Awaitable Alternative

You can use await app.after() (with no arguments) as a shorthand to load all previously registered plugins and wait for them to finish. Unlike the callback version, await app.after() is not chainable.

// async after with one parameter
app.after(async function (err) {
  await sleep(10)
  if (err) {
    throw err
  }
})

// await after (shorthand for loading previous plugins)
await app.after()

The app.ready([callback]) method ensures all plugins and after calls are completed. It is executed before the 'start' event is emitted.

Callback Signatures

1. 0 args: Returns a Promise that resolves when plugins/after calls are complete.
2. 1 arg: (err) => void. The parameter is the error object.
3. 2 args: (err, done) => void. The first is the error, the second is the done callback.
4. 3 args: (err, context, done) => void. The first is the error, the second is the top-level context, and the third is the done callback.

If autostart: false was used during initialization, calling .ready() will also trigger the boot sequence.

// ready with Promise
app.ready()
  .then(() => console.log('Ready'))
  .catch(err => {
    console.error(err)
    process.exit(1)
  })

// await ready
async function main () {
  try {
    await app.ready()
    console.log('Ready')
  } catch(err) {
    console.error(err)
    process.exit(1)
  }
}

The app.use(func, [optsOrFunc]) method loads one or more functions asynchronously.

Plugin Signature

Plugins must follow one of these patterns:

1. Callback style: (instance, options, done) => void. You must call done() exactly once when the plugin is ready.
2. Promise style: async (instance, options) => void. If the function returns a Promise, the signature is not required.
3. Immediate style: If the plugin is ready immediately, you can omit done from the signature.

Advanced Usage

• Chainable/Awaitable: use returns a thenable wrapped instance, allowing you to chain calls or await app.use(...).
• Dynamic Options: If the second argument to use is a function, it receives the parent instance as its first argument. This allows a plugin to inject variables into subsequent plugins.
• ESM Support: You can use import() to load ESM modules: app.use(import('./plugin.mjs')).

Error Handling

To catch errors during plugin loading, you must use the .ready() method.

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

app.use(plugin)

To shut down the application and clean up resources, use app.close() or the [Symbol.asyncDispose]() method.

app.close()

Starts the shutdown procedure. It executes all registered onClose callbacks.

• If no callback is provided, it returns a Promise.
• If a callback is provided, it follows the standard error/context/done signature patterns.

Symbol.asyncDispose

For Node.js 20+, app[Symbol.asyncDispose]() is an alias for app.close(). This allows using the await using syntax for automatic resource cleanup when a scope is exited, which is highly recommended for unit tests.

app.onClose(func)

Registers a callback to be fired once close is called. If the callback returns a Promise, the shutdown will wait for that Promise to resolve/reject before proceeding to the next onClose callback or finishing the close procedure.

// Using Symbol.asyncDispose for automatic cleanup
test('my test', async () => {
  await using app = avvio()

  app.use(function (server, opts, done) {
    done()
  })

  await app.ready()
  // app.close() will be called automatically when exiting this scope
})

Avvio is used to manage the loading order and lifecycle of plugins. You can instantiate it directly or use it to wrap an existing server instance. When wrapping a server, Avvio can expose its API methods (like use, ready, onClose) directly onto that server via the expose option.

Constructor Signature: new Boot(server, opts, done)

• server: An optional existing instance (e.g., a Fastify server) that you want to attach Avio's management capabilities to.
• opts: Configuration object:
  • autostart (boolean, default: true): Whether to automatically call .start().
  • timeout (number, default: 0): Timeout in milliseconds for plugin loading and ready states.
  • expose (object): Configuration to map Avvio methods to the server instance. Keys include use, after, ready, onClose, and close.

const Boot = require('avvio');

// Option 1: Create a standalone Avvio instance
const avvio = new Boot();

// Option 2: Wrap an existing server
const server = {}; // your server instance
const avvio = new Boot(server, {
  expose: {
    use: 'use',
    ready: 'ready',
    onClose: 'onClose'
  }
});