IoC Service Container

> This is a lightweight zero-dependency library for a service container written in TypeScript.


!min-size
!min-size-g-zip
!dependency-count
!npm-version
!ts-types

Features

- Fully typed
- 100 % TypeScript
- 100 % Test coverage
- 0 Dependencies
- < 2 KB Package size
- Typescript Decorator support
- Simple API
- Works beautiful with jest-mock-extended

Demo

In this StackBlitz-Demo you can see a demonstration of the
ioc-service-container. In the App.tsx you can verify that the UserService is fully typed without importing the
class.

!TypeScriptSupport

Get started

Install the dependency with npm install ioc-service-container

Usage

$3

If you use the ioc-service-container in a TypeScript project, define the types of your services in a ioc.d.ts file
otherwise you can skip this step.

``typescript
// Import your services
import { TestApi } from '../your-path/to/TestApi';
import { FooApi } from '../your-path/to/FooApi';
import { TestService } from '../your-path/to/TestService';

// Create the mapping between ServiceId and Service
type IoCTypes = {
TestApi: TestApi;
FooApi: FooApi;
TestService: TestService;
myString: string;
// ...
};

// Redeclare the scg function to get full Typscript support
declare module 'ioc-service-container' {
export function scg(id: T): U;
}
`

$3

According to this you have to pass a factory, a constructable or an entity to the ioc container. So at
the initial script of your application you call a function named e.g. setupService:

`typescript
import { ServiceContainer } from 'ioc-service-container';

function setupService() {
ServiceContainer.set('TestApi', CustomTestApi); // setup by class reference
ServiceContainer.set('FooApi', () => new CustomFooApi()); // setup by custom factory

const testService = new TestService();
ServiceContainer.set('TestService', testService); // pass the instance directly
ServiceContainer.set('myString', 'hello world'); // pass primitive values
}
`

The factory is only instantiated at need.

$3

Now you have 2 options to inject the requested service.

#### 3.1 scg() Function

The first is the most common one: const testApi = scg('TestApi);. (Shortcut for ServiceContainer.get(). Because of
the type declaration you have full TypeScript support at this point and no dependency on the file/class TestApi. (See
the Demo)

#### 3.2 @inject Decorator

> This requires "experimentalDecorators": true to be enabled in your tsconfig.json (See
> Typescript Docs)

`typescript
export class CustomTestService implements TestService {
@inject
private readonly customApi!: Api; // Important is the name of the property, it's mapped to the service id

@inject('FooApi') // If you don't want to name your property like the service id, pass the id as parameter
private readonly nameThisHowYouWant!: Api;

private readonly fooApi = ServiceContainer.get('FooApi'); // Use this syntax if you don't want to use decorators

private readonly barApi = scg('BarApi'); // Shortcut for ServiceContainer.get()
}
`

$3

For Testing or similar use cases you have the option to use ServiceContainer.isSet('anId'),
ServiceContainer.override('anId', 123) or ServiceContainer.reset().

Background

Structuring your code and avoiding implizit dependencies is two of the most effective ways to avoiding bugs, especially
when code gets extended. To goal of Dependency Injection (DI) is to prevent structures like this:

`javascript
class CustomService {
constructor() {
this.api = new CustomApi();
}
}
`

The CustomService has an implizit dependency to the CustomApi`.

The goal of DI is to encapsulate the dependencies of a class. The CustomService should work without knowing which api it
is using.