diff --git a/API.md b/API.md index 944942a..e168cc9 100644 --- a/API.md +++ b/API.md @@ -1,13 +1,19 @@ -# API Reference +# API +Resolving hapi plugin dependencies since 2015 -## Interface +> **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](https://github.com/hapipal/hodgepodge/issues/11), which means it relies fully on community support. +## `Hodgepodge` ### `Hodgepodge.sort(plugins, [looseTally])` -A function that returns an array of reordered hapi `plugins` to respect their [`dependencies` properties](https://github.com/hapijs/hapi/blob/master/API.md#plugins), - - `plugins` - a mixed value, typically a mixed array, of hapi plugin registrations as would be passed to [`server.register()`](https://github.com/hapijs/hapi/blob/master/API.md#server.register()). This argument permissively accepts all values so that hapi can handle plugin formatting errors. +A function that returns an array of reordered hapi `plugins` to respect their [`dependencies` properties](https://hapi.dev/api/#plugins), + - `plugins` - a mixed value, typically a mixed array, of hapi plugin registrations as would be passed to [`server.register()`](https://hapi.dev/api/#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](https://github.com/hapijs/hapi/blob/master/API.md#plugins) 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, +`Hodgepodge.sort()` will unwrap the [`dependencies` property](https://hapi.dev/api/#plugins) 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, ```js const plugin = { register() {/* ... */}, @@ -31,7 +37,7 @@ const plugin = { ## Examples ### Registering plugins -Hodgepodge accepts and understands any plugin registration format that you would normally pass to [`server.register()`](https://github.com/hapijs/hapi/blob/master/API.md#server.register()). It returns an array of the reordered plugin registrations. +Hodgepodge accepts and understands any plugin registration format that you would normally pass to [`server.register()`](https://hapi.dev/api/#server.register()). It returns an array of the reordered plugin registrations. ```js const Hodgepodge = require('hodgepodge'); @@ -70,7 +76,7 @@ module.exports = { ``` #### Without hodgepodge -Here's what the clunkier (but steadfast!) [`server.dependency(deps, [after])`](https://github.com/hapijs/hapi/blob/master/API.md#server.dependency()) pattern looks like, +Here's what the clunkier (but steadfast!) [`server.dependency(deps, [after])`](https://hapi.dev/api/#server.dependency()) pattern looks like, ```js // Life without hodgepodge diff --git a/LICENSE b/LICENSE index f977350..a8f00c8 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2015-2020, Devin Ivy and project contributors +Copyright (c) 2015-2021, Devin Ivy and project contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in diff --git a/README.md b/README.md index 4562a24..400a365 100644 --- a/README.md +++ b/README.md @@ -2,21 +2,28 @@ Resolving hapi plugin dependencies since 2015 -[![Build Status](https://travis-ci.org/hapipal/hodgepodge.svg?branch=master)](https://travis-ci.org/hapipal/hodgepodge) [![Coverage Status](https://coveralls.io/repos/hapipal/hodgepodge/badge.svg?branch=master&service=github)](https://coveralls.io/github/hapipal/hodgepodge?branch=master) +[![Build Status](https://travis-ci.com/hapipal/hodgepodge.svg?branch=master)](https://travis-ci.com/hapipal/hodgepodge) [![Coverage Status](https://coveralls.io/repos/hapipal/hodgepodge/badge.svg?branch=master&service=github)](https://coveralls.io/github/hapipal/hodgepodge?branch=master) Lead Maintainer - [Devin Ivy](https://github.com/devinivy) +## Installation +```sh +npm install hodgepodge +``` + ## Usage > See also the [API Reference](API.md) > -> This version of hodgepodge is for **hapi v17+** +> Hodgepodge is intended for use with hapi v19+ and nodejs v12+ (see v3 for lower support). +> +> This module is currently under [ad hoc maintenance](https://github.com/hapipal/underdog/issues/17), which means it relies fully on community support. -When you declare dependencies on a hapi plugin, whether by [`server.dependency()`](https://github.com/hapijs/hapi/blob/master/API.md#server.dependency()) or by the [`dependencies` plugin property](https://github.com/hapijs/hapi/blob/master/API.md#plugins), 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`. +When you declare dependencies on a hapi plugin, whether by [`server.dependency()`](https://hapi.dev/api/#server.dependency()) or by the [`dependencies` plugin property](https://hapi.dev/api/#plugins), 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](https://github.com/hapijs/hapi/blob/master/API.md#server.register()) or -[`once`/`multiple` plugin properties](https://github.com/hapijs/hapi/blob/master/API.md#plugins) so that plugins may simply be registered by every other plugin that depends on them. +> 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](https://hapi.dev/api/#server.register()) or +[`once`/`multiple` plugin properties](https://hapi.dev/api/#plugins) so that plugins may simply be registered by every other plugin that depends on them. > > See ["Handling plugin dependencies"](https://hapipal.com/best-practices/handling-plugin-dependencies) for an in-depth look at taming inter-plugin dependencies. @@ -38,7 +45,7 @@ const Hodgepodge = require('hodgepodge'); ``` ### More -In a sense this is an alternative to the [`server.dependency(deps, [after])`](https://github.com/hapijs/hapi/blob/master/API.md#server.dependency()) [pattern](API.md#without-hodgepodge), 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`](https://github.com/hapijs/hapi/blob/master/API.md#server.ext())). +In a sense this is an alternative to the [`server.dependency(deps, [after])`](https://hapi.dev/api/#server.dependency()) [pattern](API.md#without-hodgepodge), 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`](https://hapi.dev/api/#server.ext())). 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! diff --git a/lib/index.js b/lib/index.js index be222f0..9bb33bb 100644 --- a/lib/index.js +++ b/lib/index.js @@ -18,7 +18,7 @@ exports.sort = (plugins, looseTally) => { const originalItem = item; item = internals.normalizePlugin(item); - if (item === internals.NOT_A_PLUGIN) { + if (item === internals.kNoPlugin) { return list.add(originalItem); } @@ -91,7 +91,7 @@ exports.sort = (plugins, looseTally) => { internals.normalizePlugin = (item) => { if (!item) { - return internals.NOT_A_PLUGIN; + return internals.kNoPlugin; } else if (!item.plugin) { item = { plugin: item }; @@ -102,10 +102,10 @@ internals.normalizePlugin = (item) => { } if (!item.plugin || typeof item.plugin.register !== 'function') { - return internals.NOT_A_PLUGIN; + return internals.kNoPlugin; } return item; }; -internals.NOT_A_PLUGIN = 'not-a-plugin'; +internals.kNoPlugin = Symbol('noPlugin'); diff --git a/package.json b/package.json index 372b787..b43544f 100644 --- a/package.json +++ b/package.json @@ -10,8 +10,8 @@ "test": "test" }, "scripts": { - "test": "lab -a @hapi/code -t 100 -L -I \"FinalizationRegistry,WeakRef\"", - "coveralls": "node_modules/.bin/lab -r lcov | node_modules/.bin/coveralls" + "test": "lab -a @hapi/code -t 100 -L", + "coveralls": "lab -r lcov | coveralls" }, "repository": { "type": "git",