Optional Peer Dependencies for Node.js middleware

Description

Node's peer dependencies are automatically installed when the middleware that refers to them is installed. Just because your middleware supports 16 database systems, doesn't mean your end user wants to install all those drivers.

For those cases, you'll want to use codependency. Simply add your peer dependencies to your package.json file, in a field called "optionalPeerDependencies" and use the require() function from this library. It will give you:

• automatic semver validation.
• instructive error reporting for your end user.
• optionality (it won't throw errors if you don't want it to).
• a developer-friendly environment (allows symlinking to your middleware).

Installation

npm install codependency

Usage

The shortest usage example

Middleware package.json

{
  "name": "mymiddleware",
  "optionalPeerDependencies": {
    "redis": "~0.9.0",
    "mysql": "~2.0.0"
  }
}

Setting up and using a require-function from the middleware

var codependency = require('codependency');
var requirePeer = codependency.register(module);

var redis = requirePeer('redis');

From another file, you can now easily use the middleware's require function for peers:

var codependency = require('codependency');
var requirePeer = codependency.get('mymiddleware');

var redis = requirePeer('redis');

Advanced usage

var codependency = require('codependency');
var requirePeer = codependency.register(module, {
    index: ['optionalPeerDependencies', 'devDependencies']
});

// require redis, but don't throw an error if the module is not found

var redis = requirePeer('redis', { optional: true }); // returns undefined

API

codependency.register(module, options)

The module argument must be the root module of the middleware. Its location is the basis for the search for package.json, which is to contain the peer dependencies hashmap. Its parent will be used to require from. This allows you to work on middleware development, while symlinking to it from your end-user project. For example:

/home/bob/todolist/node_modules/mymiddleware -> /home/bob/mymiddleware

The options object may contain an index property, which defaults to the array ["optionalPeerDependencies"]. Override it to change which properties of your package.json will be used to index.

If the module argument is not the root module you may set the options.strictCheck property to false to search for package.json in a parent directory.

This function returns a require function, which has the following signature:

requirePeer(name, options)

The name argument is the name of one of your peer dependencies. It will be required and returned. The options object may contain one of the following:

• optional: boolean (default: false), in order to not throw an error if the module cannot be found.
• dontThrow: boolean (default: false), in order to not throw an error if the module's version did not satisfy the requirement or something else went wrong during the require.

It also has a resolve method which can give you information about a peer dependency before requiring it.

requirePeer.resolve(name)

The name argument is the name of one of your peer dependencies. The returned object has the following signature:

{
  "supportedRange": "2.5.1",
  "installedVersion": "2.5.1",
  "isInstalled": true,
  "isValid": true,
  "pkgPath": "zmq/package.json"
}

• supportedRange is the range that the middleware explicitly supports.
• installedVersion is the version that is currently installed (null if none).
• isInstalled indicates if the dependency has been installed.
• isValid indicates if the installed version is valid within the supported range.
• pkgPath is a path to package.json of the dependency, used internally by requirePeer().

Errors

During a peer-require, a user may encounter the following exceptions:

• Module "redis" required by "mymiddleware" not found. Please run: npm install redis@'~0.10.0' --save
• Module "mysql" required by "mymiddleware" has no version information in "mysql/package.json".
• Version of module "couchbase" required by "mymiddleware" is not a string (found instead: number).
• Version "2.3.0" of module "zmq" required by "mymiddleware" does not satisfy required range "~2.5.0".