ioc-service-container
Version:
Lightweight ioc service container
139 lines (99 loc) • 5.54 kB
Markdown
# IoC Service Container
> This is a lightweight **zero-dependency** library for a service container written in [TypeScript](https://www.typescriptlang.org).
[](https://sonarcloud.io/dashboard?id=ioc-service-container)
[](https://sonarcloud.io/dashboard?id=ioc-service-container)
[](https://sonarcloud.io/dashboard?id=ioc-service-container)
[](https://sonarcloud.io/dashboard?id=ioc-service-container)
[](https://sonarcloud.io/dashboard?id=ioc-service-container)
## Features
- **Fully typed**
- **100 % [TypeScript](https://www.typescriptlang.org)**
- **100 % Test coverage**
- **0 Dependencies**
- **< 2 KB Package size**
- **[Typescript Decorator](https://www.typescriptlang.org/docs/handbook/decorators.html) support**
- **Simple API**
- **Works beautiful with [jest-mock-extended](https://www.npmjs.com/package/jest-mock-extended)**
## Demo
In this [StackBlitz-Demo](https://stackblitz.com/edit/react-ts-qya4xy?file=App.tsx) 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.
## Get started
Install the dependency with `npm install ioc-service-container`
## Usage
### 1. Define the Types
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<T extends keyof IoCTypes, U extends IoCTypes[T]>(id: T): U;
}
```
### 2. Setup your services
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. Inject services
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](https://stackblitz.com/edit/react-ts-qya4xy?file=App.tsx))
#### 3.2 `@inject` Decorator
> This requires `"experimentalDecorators": true` to be enabled in your `tsconfig.json` (See
> [Typescript Docs](https://www.typescriptlang.org/tsconfig#experimentalDecorators))
```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<Api>('FooApi'); // Use this syntax if you don't want to use decorators
private readonly barApi = scg('BarApi'); // Shortcut for ServiceContainer.get()
}
```
### 4. Other Use-Cases
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.