factory-di

This library contains function to create some kind of Dependency Injection Containres. These containers do not use any global scope or metadata.

Advantages
Simple example
Containers
Class
computedValue
constant
factory
singleton

Advantages

strict type checking that all required dependencies are registered
lightweight
no global containers
no decorators

Simple example

foo.ts:

import { Class } from 'factory-di';

interface Database {
	// ...
}

class Foo {
	constructor(private database: Database) {}
}

// creates container which can create Foo instances
// and declare that database parameter of interface Database should be registered via token 'database'
export default Class(Foo, 'database');

database.ts:

import { Class } from 'factory-di';

class Database {
	constructor(
		private host: string,
		private login: string,
		private password: string
	) {}
}

// creates container which can create Database instances and declare tokens for all parameters
export default Class(Database, 'dbHost', 'dbLogin', 'dbPassword');

index.ts:

import { singleton, constant } from 'factory-di';
import fooContainer from './foo';
import databaseContainer from './database';

// you can not create Foo via fooContainer before its dependency 'database' is registered
// fooContainer.resolve(); // this line would cause TS error

// registers all required dependencies
const containerWithDatabase = fooContainer
	// registers database
	.register('database', databaseContainer)
	// you should register also all dependencies of 'database'
	// or a call of "resolve" would cause TS error too
	.register({
		dbHost: '<your_host>',
		dbLogin: '<your_login>',
		dbPassword: '<your_password>',
	});

// now you can create Foo
const fooInstance = containerWithDatabase.resolve();

Containers

Containers are objects which can create some values. They are similar to factories. They do not use the global scope as regular Dependency Injection Containers.

Each container has a main value. It can be created via a resolve call without parameters.

class Foo {}

const fooInstance = Class(Foo).resolve();

A container can have any list of dependencies. You should declare all dependencies when you create a container.

class Bar {
	constructor(public foo: Foo) {}
}

// create a container and declare Foo dependency for the only argument of Bar constructor
const container = Class(Bar, 'Foo');

Each dependency has a token. You can use a string or a symbol as a dependency token.

Before you create an instance you should register all declared dependencies. Or you can pass required dependencies to the resolve methos.

You can register dependencies via the register method. It receives a dependency token and a dependency container.

class Bar {
	constructor(public foo: Foo) {}
}

const container = Class(Bar, 'Foo')
	// registers Foo dependency with a new container
	.register('Foo', Class(Foo));

const barInstance = container.resolve();

Multiple dependencies registrations can be union to a single 'register' method call.

class Bar {
	constructor(public dep1: string, public dep2: number) {}
}

const container = Class(SomeClass, 'dep1', 'dep2')
	// registers all dependencies via object
	.register({
		dep1: constant('myStringValue'),
		dep2: constant(123),
	});

If you want to register a simple value as a dependency via the register method you can omit the constant function call. This example is equal to the previous.

const container = Class(SomeClass, 'dep1', 'dep2')
	// registers all dependencies via object
	.register({
		dep1: 'myStringValue',
		dep2: 123,
	});

If a container has unregistered dependencies you can pass them directly to the resolve meethod to create a main value of the container.

const instance = Class(SomeClass, 'dep1', 'dep2').resolve({
	dep1: 'myStringValue',
	dep2: 123,
});

Each call of the register method returns a new inpedendent container. Containers can have many levels of nesting.

Dependencies can be registered via a root container or via any nested container.

class Foo {}

class Bar {
	constructor(public foo: Foo) {}
}

class Root {
	constructor(public bar: Bar) {}
}

const root1 = Class(Root, 'bar')
	.register('bar', Class(Bar, 'foo'))
	.register('foo', Class(Foo)) // register foo via the Root container
	.resolve();

const root2 = Class(Root, 'bar')
	.register(
		'bar',
		Class(Bar, 'foo').register('foo', Class(Foo)) // register foo via the Bar container
	)
	.resolve();

If some dependency is registered twice in different child containers then each child container receives its own dependency value.

class Foo1 {
	constructor(public str: string) {}
}

class Foo2 {
	constructor(public str: string) {}
}

class Root {
	constructor(public foo1: Foo1, public foo2: Foo2) {}
}

const root = Class(Root, 'foo1', 'foo2')
	// register 'strValue1' via foo1
	.register('foo1', Class(Foo, 'str').register('str', constant('strValue1')))
	// register 'strValue2' via foo2
	.register('foo2', Class(Foo, 'str').register('str', constant('strValue2')))
	.resolve();

// each child instance has its own string value
root.foo1.str; // 'strValue1'
root.foo2.str; // 'strValue2'

If some dependency is registered via a parent container and via any child container then the parent dependency value is used for parent and children containers.

class Foo1 {
	constructor(public str: string) {}
}

class Root {
	constructor(public foo1: Foo1) {}
}

const root = Class(Root, 'foo1', 'foo2')
	// register 'strValue1' via foo1
	.register('foo1', Class(Foo, 'str').register('str', constant('strValue1')))
	// register 'strValueRoot'
	.register('str', constant('strValueRoot'))
	.resolve();

root.foo1.str; // 'strValueRoot'

If a dependency is registered in some container then this dependency is applied only for this container and its children containers. The dependency won't be used for parents of the container.

Class

The Class function can be used to create containers which create some class instances.

There are two form of the Class function.

Each constructor dependency as a separate argument

The first form can be used for constructors which receive each dependency as a separate argument. The simplified type of the first form.

function Class(
	// the first argument is a class constructor
	Constructor: { new (...args: any[]): any },
	// other arguments - list of tokens for each argument of the constructor
	...tokens: Array<string | symbol>
): Container;

Example.

class MyClass {
	constructor(public param1: string, public param2: number) {}
}

const myClassContainer = Class(MyClass, 'param1Token', 'param2Token');

const myClassInstance = myClassContainer
	.register('param1Token', constant('strValue'))
	.register('param2Token', constant(123))
	.resolve();

Object with constructor dependencies

The second form can be used for constructors which receive an object with dependencies as the only argument. The simplified type of the second form.

function Class(
	// the first argument is a class constructor
	Constructor: { new (params: Record<string, any>): any },
	// map of tokens where
	//   keys - keys of the constructor argument
	//   values - tokens for the corresponding argument
	tokensMap: Record<string, string | symbol>
): Container;

Example.

interface MyClassParams {
	strParam: string;
	numParam: number;
}

class MyClass {
	constructor(public params: MyClassParams) {}
}

const myClassContainer = Class(MyClass, {
	strParam: 'param1Token',
	numParam: 'param2Token',
});

const myClassInstance = myClassContainer
	.register('param1Token', 'strValue')
	.register('param2Token', 123)
	.resolve();

myClassInstance.params.strParam; // 'strValue'
myClassInstance.params.numParam; // 123

Also dependencies can be registered inside the Class function call. Then field names of the class first parameter will be used as tokens.

interface MyClassParams {
	strParam: string;
	numParam: number;
}

class MyClass {
	constructor(public params: MyClassParams) {}
}

/**
 * container has 2 unregistered dependencies with tokens
 *  - param1Token
 *  - param2Token
 */
const container1 = Class(MyClass, {
	strParam: 'param1Token',
	numParam: 'param2Token',
});

/**
 * container has 2 registered dependencies with tokens
 *  - strParam
 *  - numParam
 */
const container2 = Class(MyClass, {
	/**
	 * inside Class function you should always use constant function to register static values (not child containers)
	 */
	strParam: constant('strValue'),
	numParam: constant(123),
});

computedValue

The computedValue function can be used to create containers for any computed values.

There are two form of the computedValue function.

Each computedValue dependency as a separate argument

The first form can be used for functions which receive each dependency as a separate argument. The simplified type of the first form.

function computedValue(
	// the first argument is a function which creates some value
	create: (...args: any[]): any,
	// other arguments - list of tokens for each argument of the create function
	...tokens: Array<string | symbol>
): Container;

Example.

const myContainer = computedValue(
	// function can return any value
	(param1: string, param2: number) => new MyClass(param1, param2),
	'param1Token',
	'param2Token'
);

const myValue = myContainer
	.register('param1Token', 'strValue')
	.register('param2Token', 123)
	.resolve();

Object with computedValue dependencies

The second form can be used for functions which receive an object with dependencies as the only argument. The simplified type of the second form.

function computedValue(
	// the first argument is a function which creates some value
	create: (params: Record<string, any>): any,
	// map of tokens where
	//   keys - keys of the create function argument
	//   values - tokens for the corresponding argument
	tokensMap: Record<string, string | symbol>
): Container;

Example.

interface MyFactoryMethodParams {
	strParam: string;
	numParam: number;
}

const myContainer = computedValue(
	// function can return any value
	(params: MyFactoryMethodParams) => new MyClass(params),
	{
		strParam: 'param1Token',
		numParam: 'param2Token',
	}
);

const myValue = myContainer
	.register('param1Token', constant('strValue'))
	.register('param2Token', constant(123))
	.resolve();

myValue.params.strParam; // 'strValue'
myValue.params.numParam; // 123

Also dependencies can be registered inside the computedValue function call. Then field names of the factory method first parameter will be used as tokens.

interface MyFactoryMethodParams {
	strParam: string;
	numParam: number;
}

/**
 * container has 2 unregistered dependencies with tokens
 *  - param1Token
 *  - param2Token
 */
const container1 = computedValue(
	(params: MyFactoryMethodParams) => new MyClass(params),
	{
		strParam: 'param1Token',
		numParam: 'param2Token',
	}
);

/**
 * container has 2 registered dependencies with tokens
 *  - strParam
 *  - numParam
 */
const container2 = computedValue(
	(params: MyFactoryMethodParams) => new MyClass(params),
	{
		/**
		 * inside computedValue function you should always use constant function to register static values (not child containers)
		 */
		strParam: constant('strValue'),
		numParam: constant(123),
	}
);

constant

The constant function can be used to create a container for some immutable value. The common case - to pass a constant container as a dependency directly to Class or computedValue method.

function constant(value: any): Container;

Example.

const myConstantContainer = constant(99);

computedValue((params: { num: number }) => new MyClass(params), {
	num: constant(99),
}).resolve();

factory

The factory function can be used to create Factory method or some Factories. It is useful when you need to create multiple instances of some dependency in runtime dynamically.

There are two ways to use the factory function - via create method or with a child container.

create method

type Resolve = (token: string | symbol) => any;

function factory(
	// the only argument is a function which returns a value (usually a factory or a factory method)
	create: (resolve: Resolve): any,
): Container;

The create function (the only argument of factory) receives the resolve method. The resolve method receives a dependency token and returns its value.

Example.

import { FactoryResolve, factory } from 'factory-di';
import { repositoryContainer } from './repository';
import { MyClass } from './myClass';

const myFactoryMethod = factory(
	// via FactoryResolve type you can declare needed dependencies
	(resolve: FactoryResolve<{ repository: Repository }>) => {
		// the factory method receives an id and return an instance
		return (id: string) =>
			new MyClass({
				repository: resolve('repository'),
				id,
			});
	}
)
	// register the only dependency
	.register('repository', repositoryContainer)
	.resolve();

const myClassInstance1 = myFactoryMethod('id1');
const myClassInstance2 = myFactoryMethod('id2');

with child container

In this example ShoppingCart needs to create multiple instances of ShoppingItem in runtime.

import { factory, Class } from 'factory-di';

class ShoppingItem {
	constructor(
		public productId: number,
		public amount: number,
	){}
}

class ShoppingCart {
	items: ShoppingItem[];


	constructor(
		// ShoppingCart needs a factory method for ShoppingItem
		private itemFactory: (productId: number, amount: number) => ShoppingItem;
	) {}

	addItem(productId: number, amount: number): ShoppingItem {
		// we need to create items in runtime
		const newItem = this.itemFactory(productId, amount)
		this.items.push(newItem);

		return newItem;
	}
}

// this container can create ShoppingItem
const itemContainer = Class(ShoppingItem, 'shoppingItemProductId', 'shoppingItemAmount');

// this container can create function  (productId, amount) => ShoppingItem
const itemFactoryContainer = factory(itemContainer, 'shoppingItemProductId', 'shoppingItemAmount');

const cartContainer = Class(ShoppingCart, 'shoppingItemFactory')
	.register(
		'shoppingItemFactory',
		itemFactoryContainer,
	);

// creates a cart
const cart = cartContainer.resolve();

cart.addItem(321, 5); // ShoppingItem { productId: 321, amount: 5 }

The first argument of factory is a child container. The next arguments describe parameters of a new facrory method. The way to describe parameters of factory method is similar to describing tokens of computedValue or Class.

without parameters

class Car {
	constructor(public manufacturer: string, public model: string) {}
}

// carContainer creates cars and requires two dependencies
const carContainer = Class(Car, 'carManufacturer', 'carModel');

// this container creates function: () => Car
// and requires the same two dependencies - 'carManufacturer' and 'carModel'
const carFactoryContainer = factory(carContainer);

// so before using carFactory you should pass these two deps
const toyotaCamryFactory = carFactoryContainer.resolve({
	carManufacturer: 'toyota',
	carModel: 'camry',
});

// now you can use toyotaCamryFactory to create cars
toyotaCamryFactory(); // Car { manufacturer: 'toyota', model: 'camry'}

list of parameters

// by passing 'carModel' we define that factory method has one parameter
// and its value will be passed as 'carModel' dependency to carContainer
// carFactoryContainer creates function: (model) => Car
// and requires the only dependency - 'carManufacturer'.
const carFactoryContainer = factory(carContainer, 'carModel');

// so before using carFactory you should pass carManufacturer
const toyotaFactory = carFactoryContainer.resolve({
	carManufacturer: 'toyota',
});

toyotaFactory('camry'); // Car { manufacturer: 'toyota', model: 'camry'}
toyotaFactory('corolla'); // Car { manufacturer: 'toyota', model: 'corolla'}

// this container creates function: (manufacturer, model) => Car
const carFactoryContainer = factory(
	carContainer,
	'carManufacturer',
	'carModel'
);
const carFactory = carFactoryContainer.resolve();

carFactory('toyota', 'corolla'); // Car { manufacturer: 'toyota', model: 'corolla'}
carFactory('ford', 'mondeo'); // Car { manufacturer: 'ford', model: 'mondeo'}

parameters as fields of object

// by passing "{model: 'carModel'}" we define that factory method has one parameter
// and its field 'model' will be passed as 'carModel' dependency to carContainer
// carFactoryContainer creates function: ({ model }) => Car
// and requires the only dependency - 'carManufacturer'.
const carFactoryContainer = factory(carContainer, { model: 'carModel' });

// so before using carFactory you should register carManufacturer
const toyotaFactory = carFactoryContainer
	.register({
		carManufacturer: 'toyota',
	})
	.resolve();

toyotaFactory({ model: 'camry' }); // Car { manufacturer: 'toyota', model: 'camry'}
toyotaFactory({ model: 'corolla' }); // Car { manufacturer: 'toyota', model: 'corolla'}

// this container creates function: ({ manufacturer, model }) => Car
const carFactoryContainer = factory(carContainer, {
	manufacturer: 'carManufacturer',
	model: 'carModel',
});
const carFactory = carFactoryContainer.resolve();

carFactory({ manufacturer: 'toyota', model: 'corolla' }); // Car { manufacturer: 'toyota', model: 'corolla'}
carFactory({ manufacturer: 'ford', model: 'mondeo' }); // Car { manufacturer: 'ford', model: 'mondeo'}

singleton

If some containers need the same dependency then by default they receive different instances of this dependency.

class Logger {}

class Module1 {
	constructor(public logger: Logger) {}
}

class Module2 {
	constructor(public logger: Logger) {}
}

class App {
	constructor(public modules: { module1: Module1; module2: Module2 }) {}
}

const app = Class(App, {
	module1: Class(Module1, 'logger'),
	module2: Class(Module2, 'logger'),
})
	.register('logger', Class(Logger))
	.resolve();

a.modules.module1.logger === a.modules.module2.logger; // false

If you need some dependency to be a singleton you can call the singleton method and pass a key of any dependency as an argument.

const app = Class(App, {
	module1: Class(Module1, 'logger'),
	module2: Class(Module2, 'logger'),
})
	.register('logger', Class(Logger))
	.singleton('logger')
	.resolve();

a.modules.module1.logger === a.modules.module2.logger; // true

There are some factors of the singleton method behavior.

if you make a dependency to be a singleton it affects only the current container and its children
two different containers registered with the same token create independent instances even if you mark this token as singleton
if you register some dependency container twice it is considered as two independent containers and they create independent instances even if you mark them as singleton
each call of the resolve method has its own set of singletons. During each call all singletons receive new instances
if you use the factory function to create several instances then each call of the factory reinitializes singletons of all children containers of the factory. If you need some dependency to be a singleton inside all instances created by the factory you should register this dependency and mark it as singleton via the container of the factory or via some parent container

factory-di

factory-di

Advantages

Simple example

Containers

Class

Each constructor dependency as a separate argument

Object with constructor dependencies

computedValue

Each computedValue dependency as a separate argument

Object with computedValue dependencies

constant

factory

create method

with child container

without parameters

list of parameters

parameters as fields of object

singleton

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

factory-di

factory-di

Advantages

Simple example

Containers

Class

Each constructor dependency as a separate argument

Object with constructor dependencies

computedValue

Each computedValue dependency as a separate argument

Object with computedValue dependencies

constant

factory

create method

with child container

without parameters

list of parameters

parameters as fields of object

singleton

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads