Resolving hapi plugin dependencies since 2015

Lead Maintainer - Devin Ivy

npm install hodgepodge

See also the API Reference

Hodgepodge is intended for use with hapi v19+ and nodejs v12+ (see v3 for lower support).

This module is currently under ad hoc maintenance, which means it relies fully on community support.

When you declare dependencies on a hapi plugin, whether by server.dependency() or by the dependencies plugin property, hapi does not actually defer plugin registration to resolve those dependencies. It just assures that those dependencies exist at the time the server is initialized. Hodgepodge actually reorders your plugin registrations so that they occur in an order that respects their dependencies, simply by paying attention to their listed dependencies.

Note

It's suggested to use hodgepodge only when it's really necessary– ideally plugin registration order should not matter. You may, for example, utilize the once plugin registration option or once/multiple plugin properties so that plugins may simply be registered by every other plugin that depends on them.

See "Handling plugin dependencies" for an in-depth look at taming inter-plugin dependencies.

const Hodgepodge = require('hodgepodge');

(async () => {

    const plugins = Hodgepodge.sort([
        pluginA, // pluginA.dependencies === 'pluginB'
        pluginB
    ]);

    // Now plugins looks like [pluginB, pluginA]
    // This ordering respects pluginA's dependency on pluginB

    await server.register(plugins);
})();

In a sense this is an alternative to the server.dependency(deps, [after]) pattern, which some find to be clunky. In contrast to use of server.dependency()'s after callback, dependencies are dealt with at the time of plugin registration rather than during server initialization (during onPreStart).

Due to this core difference in timing, it may be required that your plugin be registered using hodgepodge to ensure that plugin dependencies are resolved in time for the plugin to be used. In order to enforce this, wrap your plugin's dependencies in an object with a single property hodgepodge. When hodgepodge passes over your plugin, it will unwrap this property; but if hodgepodge is not used to register your plugin, hapi will fail when it tries to register your plugin because { hodgepodge: [] } is an invalid dependencies plugin property. This is by design, in case you want to enforce registration of your plugin using hodgepodge. If you do this, remember that hodgepodge is then a peerDependency of your project!

Hodgepodge throws an exception when there are circular dependencies, or if dependencies will otherwise not be met during registration.

Because hodgepodge reorders serial plugin registrations rather than deferring plugin registration until dependencies are met, hodgepodge can only resolve dependencies among plugins that are registered at the same time.

Resolving hapi plugin dependencies since 2015

Note

Hodgepodge is intended for use with hapi v19+ and nodejs v12+ (see v3 for lower support).

This module is currently under ad hoc maintenance, which means it relies fully on community support.

A function that returns an array of reordered hapi plugins to respect their dependencies properties,

• plugins - a mixed value, typically a mixed array, of hapi plugin registrations as would be passed to server.register(). This argument permissively accepts all values so that hapi can handle plugin formatting errors.
• looseTally - a boolean value defaulting to false that, when true, only requires that hapi plugins with a dependencies.hodgepodge property present have their dependencies fully satisfied in the list of plugins. This may be desirable when plugins without dependencies.hodgepodge have had their dependencies satisfied from prior plugin registrations or otherwise do not want to rely on hodgepodge for dependency resolution. The name of the option refers to keeping a "loose tally" of missing dependencies.

Hodgepodge.sort() will unwrap the dependencies property of all plugins in the plugins list that wrap their dependencies using dependencies.hodgepodge. This can be leveraged in a plugin to require that hodgepodge be used to register it; otherwise vanilla plugin registration would fail since { hodgepodge: [] } is not a valid plugin dependencies value. For example, a plugin as such,

const plugin = {
    register() {/* ... */},
    name: 'my-plugin',
    dependencies: { hodgepodge: ['some-dep'] }
};

will be "unwrapped" to effectively use the following valid format,

const plugin = {
    register() {/* ... */},
    name: 'my-plugin',
    dependencies: ['some-dep']
};

Hodgepodge.sort() throws an exception when there are circular dependencies. It also throws an exception when there are missing dependencies in the list of plugins, differing in behavior based upon looseTally.

Hodgepodge accepts and understands any plugin registration format that you would normally pass to server.register(). It returns an array of the reordered plugin registrations.

const Hodgepodge = require('hodgepodge');

(async () => {

    const plugins = Hodgepodge.sort([
        require('my-plugin'),         // Requires john-does-plugin be registered first
        require('john-does-plugin'),  // Requires don-moes-plugin be registered first
        require('don-moes-plugin')
    ]);

    // Registers don-moes-plugin, john-does-plugin, then my-plugin
    await server.register(plugins);
})();

Here's what plugin authorship looks like assuming use of hodgepodge,

// Life with hodgepodge

module.exports = {
    register(server) {

        // Requires vision
        server.views(/* ... */);
    },
    name: 'my-plugin',
    dependencies: ['@hapi/vision']  // Hodgepodge enforces this dependency when the plugin is registered
    // dependencies: { hodgepodge: ['@hapi/vision'] }
    // The commented line above would additionally ensure
    // this plugin is registered with hodgepodge (optional)
};

Here's what the clunkier (but steadfast!) server.dependency(deps, [after]) pattern looks like,

// Life without hodgepodge

const internals = {};

module.exports = {
    name: 'my-plugin',
    register(server) {

        server.dependency(['@hapi/vision'], internals.register(options));
    }
};

internals.register = (options) => {

    return (server) => {

        // Requires vision
        server.views(/* ... */);
    };
};