Impl NPM | npm.io

Impl

Fantastic dependency injection for npm modules.

Features

Made for npm modules with semantic versioning
Works in browsers with Browserify
Light weight and fast
No dependencies

Impl works fine if it's loaded multiple times, e.g. when linking modules locally during development.

How does it work?

The most simple use case is to associate a module with an instance:

var MyThing = require('my-thing');

impl.instance(MyThing, new MyThing());

A module that need an instance of my-thing can retrieve it like this:

var MyThing = require('my-thing');

var myThing = impl.get(MyThing);

Contracts

A Contract is a plain Node module that exports some functions. The functions body will be ignored and can be empty. A simple contract for a messaging API could look like this:

// module: my-messaging-contract
exports.publish = function (message, callback) {};

The module exposing the contract can document the API. Release versions should follow semantic versioning. Any JavaScript object that implements a contract must expose functions with the same name and arity as defined in the contract.

Types

A type is an implementation of a contract. Impl doesn't force you to create types in a specific way. All you have to do is associate the type with the contract:

// module: my-amqp-messaging
var impl = require('impl');
var Messaging = require('my-messaging-contract');

function AMQPMessaging() {}
AMQPMessaging.prototype.publish = function (message, callback) {
  // RPC logic over AMQP, invokes callback with reply
};

impl.set(Messaging, AMQPMessaging);

The idea is that you depend on the module that defines Messaging with semantic versioning, e.g. ^1.0.0 stating that you're fine with any patches or new features being implemented in the Messaging contract, but no breaking changes.

Instances

An instance can be any JavaScript object. An instance is associated with a type like this:

var impl = require('impl');
var AMQPMessaging = require('my-amqp-messaging');

impl.instance(AMQPMessaging, new AMQPMessaging());

This should be done in the bootstraping logic of an application. Your app now depends on a version of AMQPMessaging which in turn depends on the Messaging contract.

Factories

If you don't want a single instance of something, use a factory function that gets invoked every time an instance is requested:

var impl = require('impl');
var AMQPMessaging = require('my-amqp-messaging');

impl.factory(AMQPMessaging, function () {
  return new AMQPMessaging();
});

Note: Returned instances don't have to be instanceof Type.

Resolving instances by contract

Now you can retrieve instances by contract:

var impl = require('impl');
var Messaging = require('my-messaging-contract');

var messaging = impl.get(Messaging);

This means any module that wants an instance of Messaging has to depend on the messaging contract, again by using semantic versioning, e.g. ^1.0.0. This ensures that a contract compatible version is made available by the application.

Install

$ npm install impl --save

API

set(Contract, Type): Associates a contract with a type that implements the contract.
instance(Type, instance): Sets an instance for a type.
factory(Type, factory): Sets a factory function for a type.
get(ContractOrType[, options]): Returns an instance for a contract or a type. If a contract is given, verifies that the resolved instance implements the contract. Options must be an object an can have these properties:
- optional: If set to true, no exception will be thrown in case no instance of factory is found for the given contract or type. Instead, null will be returned.
unset(ContractOrType): Removes any association from the given contract or type.