hinoki

this is a release candidate for version 1.0 implementation and tests are complete. the documentation in this readme is not yet finished. it's already useful though. the newest version introduces massive breaking changes. if you used an earlier version of hinoki please read this new readme carefully. future changes will be documented in the changelog. future versions will use semver.

sane, simple, dependency injection and more for Node.js and browsers

Hinoki seems to be the least surprising IoC container available for Node.
I definitely do like its ascetic worldview.
Thanks a lot for this!
andrey

• huge test suite passing with code coverage
• continously tested in Node.js (0.12, 4.0), io.js (2, 3) and all relevant browsers:
• supports CommonJS, AMD and browser globals
• npm package: npm install hinoki
• bower package: bower install hinoki
• inspired by prismatic's fantastic graph.

hinoki takes its name from the hinoki cypress, a tree that only grows in japan and is the preferred wood for building palaces, temples and shrines.
we hope hinoki becomes the building material for your digital palaces too !

the gist

(web) applications are systems. systems with many components: functions, helpers, actions, objects, data, configuration, etc.
components that depend on each other, often asynchronously in the case of Node.js, often in complex ways.

dependency injection can simplify such systems greatly !

dependency injection is simple: a component declares the names of the other components it needs. dependency injection then hands each component these declared dependencies. regardless of how complex the dependency graph is.

one of hinoki's main concepts is the factory:
a factory is simply a function which returns a component. the parameters of a factory are the names of that component's dependencies.

given a bunch of factories hinoki figures out the dependency tree and ensures that each factory gets called with the right components (dependencies) as arguments.

there's much more to hinoki but that is the most important point.

you no longer need to write any boilerplate to wire up and connect the components of your application.

nothing is hardwired. everything is mockable. every component is easy to test in isolation.

manual wiring boilerplate disappears.

hinoki is an extremely simple and functional approach to dependency injection. it supports usage patterns not possible with other dependency injection systems.

get it

npm install hinoki

var hinoki = require('hinoki');

bower install hinoki

lib/hinoki.js supports AMD.
sets the global variable hinoki when neither CommonJS nor AMD are available.

keys and values

like a map hinoki manages a mapping from keys to values.

think of the values as the parts of your system.
think of the keys as the names for those parts.

like a map we can ask for a value that is associated with a given key:

var source = function() {};

var lifetime = {
  one: 1,
  two: 2,
  three: 3,
};

var key = 'three';

hinoki(source, lifetime, key).then(function(value) {
  assert(value === 3);
});

the first argument is the source. more on that in a bit. here it does nothing. it's not optional don't worry about it for now. we'll come to that in a bit.

the second argument is a lifetime.
a lifetime is a plain-old-javascript-object that maps keys to values.
lifetimes store values.
we'll learn more about lifetimes later.

the third argument is the key we want to get the value of.

if we ask for a key and a value is present for that key in the lifetime then hinoki will return a promise that resolves exactly to that value !

hinoki always returns a promise !

that code not very useful. we could have used lifetime.three directly.
we'll get to the useful stuff in a bit !

we can also look up the values for multiple keys in multiple lifetimes at once:

var lifetimes = [
  {one: 1},
  {one: 'one'},
  {two: 2, three: 3},
  {two: 'two'},
];

hinoki(function() {}, lifetimes, ['three', 'one', 'two'])
  .spread(function(a, b, c) {
    assert(b === 1);
    assert(c === 2);
    assert(a === 3);
  });

the value is always returned from the first lifetime having the key !

multiple lifetimes are really useful. more on that later.

we can even pass in a function as the third argument:

var lifetimes = [
  {one: 1},
  {two: 2},
  {three: 3},
];

hinoki(function() {}, lifetimes, function(two, one, three) {
  assert(one === 1);
  assert(two === 2);
  assert(three === 3);
  return two + three;
}).then(function(value) {
  assert(value === 5);
})

hinoki has just parsed the keys from the function parameter names and called the function with the values (associated with those keys) as arguments.

in this case hinoki returns a promise that resolves to the value (or promise) returned by the function.

that's an improvement but still not really what hinoki is about.

let's get to that now !

sources and factories

what if we ask for a value that is not present in the lifetime(s) ?

var lifetime = {
  one: 1,
  two: 2,
  three: 3,
};

hinoki(function() {}, lifetime, 'four').then(function(value) {
  /* this code is never reached */
});

the promise is rejected with an error:

Unhandled rejection NotFoundError: neither value nor factory found for `four` in path `four`

if there is no value for the key in any of the lifetimes hinoki calls the source function with the key !

think of source as a fallback on missing key value mappings.

the source is not supposed to return a value directly. instead the source is supposed to return a factory or null.

a factory is simply a function that returns a value.

returning null (undefined is fine too) signals hinoki that the source can't return a factory that can make a value for that key.

sources make factories.
factories make values.

factories declare dependencies through their parameter names:
the parameter names of a factory function are interpreted as keys. hinoki will get values for those keys and call the factory with them as arguments.

let's see an example:

var lifetime = {
  one: 1,
  two: 2,
  three: 3,
};

var source = function(key) {
  if (key === 'five') {
    return function(one, four) {
      return one + four;
    };
  }
  if (key === 'four') {
    return function(one, three) {
      return Promise.resolve(one + three);
    };
  }
};

hinoki(source, lifetime, 'five').then(function(value) {
  assert(value === 5);
  assert(lifetime.five === 5);
  assert(lifetime.four === 4);
});

there's a lot going on here. let's break it down. you'll understand most of hinoki afterwards:

we want the value for the key 'five'.
hinoki immediately returns a promise. it will resolve that promise with the value later.
there is no key 'five' in the lifetime so hinoki calls our source function with the argument 'five'.
source returns the factory function for 'five'.
the factory for 'five' has parameter names 'one' and 'four'.
hinoki calls itself to get the values for 'one' and 'four' such that it can call the factory with those values.
'one' is easy. it's already in the lifetime.
but there is no key 'four' in the lifetime therefore hinoki calls our source function again with the argument 'four'.
source returns the factory function for 'four'.
the factory for 'four' has parameters 'one' and 'three'.
hinoki calls itself to get the values for 'one' and 'three'.
fortunately values for both 'one' and 'three' are already in the lifetime.
hinoki can now call the factory for 'four' with arguments 1 and 3.
the factory for 'four' returns a promise.

when a factory returns a promise hinoki must naturally wait for the promise to be resolved before calling any other factories that depend on that value !

at some point the promise for 'four' resolves to 4.
hinoki can now continue making everything that depends on the value for 'four':

first hinoki sets lifetime.four = 4.

values returned from factories are stored/cached in the lifetime !
what if we have multiple lifetimes? the answer is very useful and worth its own section.

now hinoki can call the factory for 'five' with arguments 1 and 4.
ince the factory for 'five' doesn't return a promise hinoki doesn't have to wait.
hinoki sets lifetime.five = 5.
remember that promise hinoki has returned immediately ? now that we have the value for key 'five' hinoki resolves it with 5.

that's it for the breakdown.
you should now have a pretty good idea what hinoki does.
keep in mind that this scales to any number of keys, values, factories, lifetimes and dependencies !

having to add an if-clause in the source for every factory is not very convenient.
fortunately there's much more to sources. read on !

sources in depth

the first argument passed to hinoki is always interpreted as the source and passed to hinoki.source internally.

hinoki.source takes either an object, a string, an array or a function.
hinoki.source always returns a source function.

when hinoki.source is called with a function argument its simply returned.

objects

if an object mapping keys to the factories for those keys is passed to hinoki.source it is wrapped in a source function that simply looks up the key in the object:

var lifetime = {
  one: 1,
  two: 2,
  three: 3,
};

var factories = {
  five: function(on, three) {
    return one + four;
  },
  four: function(one, three) {
    return Promise.resolve(one + three);
  },
};

hinoki(factories, lifetime, 'five').then(function(value) {
  assert(value === 5);
  assert(lifetime.five === 5);
  assert(lifetime.four === 4);
});

much more readable and maintainable than all those if-clauses we had before.

strings

if a string is passed to hinoki.source it is interpreted as a filepath.

if the filepath points to a .js or .coffee file hinoki.source will require it and return a source function that looks up keys in the module.exports returned by the require.

if the filepath points to a folder hinoki.source will require all .js and .coffee files in that folder recursively. other files are ignored. all module.exports returned by the requires are merged into one object. a source function is returned that looks up keys in that object.

it is very easy to load factories from files that simply export factories this way !

sources can also be strings. in that case hinoki interprets them as filenames to require

this means that you can just drop your factories as exports pull them all in and wire them up.

you could have all your factories as exports in a number of

your factories could then depend on other factories exported by any other file in that directory.

arrays

sources compose:
if an array is passed to hinoki.source it is interpreted as an array of potential sources.

this section needs work

generator functions

this section needs work

decorator functions

this section needs work

lifetimes in depth

this section needs work

lifetimes store values.

why multiple lifetimes ?

because values

there's only one application

but there are many requests

there are many events

many lifetimes

but you still want

let's see an example:

request, response

fragments is with this idea at its core.

factories in depth

this section needs work

changelog

future changes will be documented here

contributing

bugfixes, issues and discussion are always welcome.
kindly ask before implementing new features.

i will happily merge pull requests that fix bugs with reasonable code.

i will only merge pull requests that modify/add functionality if the changes align with my goals for this package, are well written, documented and tested.

communicate !
write an issue to start a discussion before writing code that may or may not get merged.

This project adheres to the Contributor Covenant 1.2. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

license: MIT