README.md

@testingrequired/ioc

A simple dependency injection implementation.

Notice

This is not intended for production use.

Installation

$ npm i @testingrequired/ioc

Getting Started

Components

Define components with the component decorator.

Example

import { component, register } from "@testingrequired/ioc";

@component
class Component {}

Register Example

Components can also be defined using the register function for more control.

import { component, register, instance } from "@testingrequired/ioc";

class RandomEachTime {}

register(
  RandomEachTime,
  () => {
    const component = new RandomEachTime();
    component.value = Math.floor(Math.random() * (10000 - 0) + 0);
    return component;
  },
  { lifetime: instance }
);

Dependencies

The inject function defines a dependency to a component.

import { component, inject, resolve } from "@testingrequired/ioc";

@component
class Child {}

@component
class Parent {
  @inject(Child) child;
}

const parent = resolve(Parent);

parent.child instanceof Child === true;

Example

See the working example

Testing

A container's register function can be passed a custom factory even after dependency resolution. This factory can return a mock/spy/stub.

import { makeContainer } from "@testingrequired/ioc";

const container = makeContainer();

@container.component
class Child {}

class Parent {
  @container.inject(Child) child;
}

class Sibling {}

container.register(Child, () => new Sibling());

const parent = containter.resolve(Parent);

parent.child instanceof Sibling === true;

Development

build

Build project in to dist

$ npm run build

watch

Build project when files change.

$ npm run build -- -w

test

Run tests

npm run test

example

Run example app.

This will use current build in dist.

$ npm run example

API

register(componentKey, [factory, [options = {}]])

Register a class as a component.

import { register } from "@testingrequired/ioc";

class Foo {}

register(Foo);

component

The class, string or symbol used to identify the component.

factory

Function to be called when creating instance of component. This defaults to calling new on component.

options

lifetime

There are two lifetime options: session (one instance for every resolve) & instance (new instance on each resolve).

import { register, session, instance } from "@testingrequired/ioc";

class Singleton {}

register(Singleton, null, { lifetime: session });

class NewEveryTime {}

register(NewEveryTime, null, { lifetime: instance });

register.fn(componentKey, fn)

Register a functional component.

import { component, register } from "@testingrequired/ioc";

@component
class ComponentA {}

@component
class ComponentB {}

export default register.fn(
  [ComponentA, ComponentB],
  (componentA, componentB) => /* ...implementation */
);

resolve(componentKey)

Return instance of component.

import { resolve } from "@testingrequired/ioc";

const foo = resolve(Foo);

component

Register a class as an injectable component.

import { component } from "@testingrequired/ioc";

@component
class Foo {}

component(options = {})

Pass options while registering a component.

import { component } from "@testingrequired/ioc";

@component({})
class Foo {}

Options

Lifetime

There are two lifetime options: session (one instance for every resolve) & instance (new instance on each resolve).

import { component, session, instance } from "@testingrequired/ioc";

@component({ lifetime: session })
class Singleton {}

// same as:

@component.session
class Singleton {}

// ---

@component({ lifetime: instance })
class NewEveryTime {}

// same as:

@component.instance
class NewEveryTime {}

inject(componentKey)

Injects initialized component.

import { inject } from "@testingrequired/ioc";

class Bar {
  @inject(Foo) foo;
}

makeContainer

Create a container to manage components.

import { makeContainer } from "@testingrequired/ioc";

const container = makeContainer();

@container.component
class Foo {}

class Bar {
  @container.inject(Foo) foo;
}