sack

Sack

Inversion-of-control container for all your dependency injection needs.

Installation

Sack is meant to be used with Browserify, so install with npm:

npm install sack

Introduction

This is a simple Inversion of Control Container. It provides the mechanism you need to have a centralized store of object instances that other types can passive request get injected.

This means that you can have objects use, access, or compose other objects without having to explicitly know how to create / setup / initialize them.

It lets you have a highly-decoupled and framework-independent domain objects.

Usage

Dependencies are all managed via a Container instance:

var Container = require('sack').Container;

...

var container = new Container();

Registering Objects

Register a class constructor that will get executed every time the dependency is resolved, creating a new instance:

container.register('service', MyService);

Register a constructor function that will get executed one time when the first time a dependency is resolved, and then re-used after that (singleton):

container.shared('service', MyService);

Register an existing object instance as a dependency:

container.register('service', someService);

Register a (lazily evaluated) callback to provide the dependency on every request:

container.register('service', function() {
  return new MyService();
});

Registered a callback to provide the dependency the first time it is requested, and then re-use it all subsequent times (singleton via callback):

container.shared('service', function() {
  return new MyService();
});

Register a factory callback for a specific class constructor. This is useful for allowing objects to create several of another object without explictly knowing how:

container.registerFactory(GameEntity, function(pool) {
  return pool.aquire(GameEntity);
});

Resolving Objects

You can create / request objects via the make() function.

var service = container.make('service');

Expressing Dependencies

Whenever Sack creates an object, it satisfies that object's dependencies by resolving them out of the container as well.

An object expresses its dependency as a constructor parameter, whose name must match a registered object.

function UserEditController(users)
{
  this.users = users;
}

UserEditController.prototype.refreshUsers()
{
  this.users.refresh();
}

Assuming we have registered some implementation for users:

container.register('users', new LocalStorageUsers());

Then making UserEditController via the container will resolve the dependency automatically.

var controller = container.make(UserEditController);

Tern Support

The source files are all decorated with JSDoc3-style annotations that work great with the Tern code inference system. Combined with the Node plugin (see this project's .tern-project file), you can have intelligent autocomplete for methods in this library.

Testing

Testing is done with Tape and can be run with the command npm test.

Automated CI cross-browser testing is provided by Testling.

License

Copyright 2014 Brandon Valosek

Sack is released under the MIT license.

Changelog

1.1.0 (2014-01-20)

• Container self-registers with tag "container" instead of "resolver"
• Added member function factory(T) to create by constructor reference.
• Added explicit registration functions:
  • registerInstance(),
  • registerConstructor()
  • registerClosure()
  • registerFactory()
• Added additional explicit creation functions:
  • factory()
  • build()
• Original API (make() and register()) will attempt to correctly guess/determine which of the explicit flavors of function to use.