Dioma

Elegant dependency injection container for vanilla JavaScript and TypeScrip...

Dependency Injection
zheksoon/diomadioma

README

Dioma


dioma

Elegant dependency injection container for vanilla JavaScript and TypeScript

Features


- Just do it - no decorators, no annotations, no magic- Tokens for class, value, and factory injection- Async injection and dependency cycle detection- TypeScript support- No dependencies- Tiny size

Installation


  1. ```sh
  2. npm install --save dioma

  4. yarn add dioma
  5. ```

Usage


To start injecting dependencies, you just need to add the static scope property to your class and use the inject function to get the instance of it. By default, inject makes classes "stick" to the container where they were first injected (more details in the Class registration section).

Here's an example of using it for Singleton and Transient scopes:

  1. ```typescript
  2. import { inject, Scopes } from "dioma";

  4. class Garage {
  5.   open() {
  6.     console.log("garage opened");
  7.   }

  9.   // Single instance of the class for the entire application
  10.   static scope = Scopes.Singleton();
  11. }

  13. class Car {
  14.   // injects instance of Garage
  15.   constructor(private garage = inject(Garage)) {}

  17.   park() {
  18.     this.garage.open();
  19.     console.log("car parked");
  20.   }

  22.   // New instance of the class on every injection
  23.   static scope = Scopes.Transient();
  24. }

  26. // Creates a new Car and injects Garage
  27. const car = inject(Car);

  29. car.park();
  30. ```

Scopes


Dioma supports the following scopes:

- Scopes.Singleton() - creates a single instance of the class
- Scopes.Transient() - creates a new instance of the class on every injection
- Scopes.Container() - creates a single instance of the class per container
- Scopes.Resolution() - creates a new instance of the class every time, but the instance is the same for the entire resolution
- Scopes.Scoped() is the same as Scopes.Container()

Singleton scope


Singleton scope creates a single instance of the class for the entire application.
The instances are stored in the global container, so anyone can access them.
If you want to isolate the class to a specific container, use the Container scope.

A simple example you can see in the Usage section.

Multiple singletons can be cross-referenced with each other using async injection.

Transient scope


Transient scope creates a new instance of the class on every injection:

  1. ```typescript
  2. import { inject, Scopes } from "dioma";

  4. class Engine {
  5.   start() {
  6.     console.log("Engine started");
  7.   }

  9.   static scope = Scopes.Singleton();
  10. }

  12. class Vehicle {
  13.   constructor(private engine = inject(Engine)) {}

  15.   drive() {
  16.     this.engine.start();
  17.     console.log("Vehicle driving");
  18.   }

  20.   static scope = Scopes.Transient();
  21. }

  23. // New vehicle every time
  24. const vehicle = inject(Vehicle);

  26. vehicle.drive();
  27. ```

Generally, transient scope instances can't be cross-referenced by the async injection with some exceptions.

Container scope


Container scope creates a single instance of the class per container. It's the same as the singleton, but relative to the custom container.

The usage is the same as for the singleton scope, but you need to create a container first and use container.inject instead of inject:

  1. ```typescript
  2. import { Container, Scopes } from "dioma";

  4. const container = new Container();

  6. class Garage {
  7.   open() {
  8.     console.log("garage opened");
  9.   }

  11.   // Single instance of the class for the container
  12.   static scope = Scopes.Container();
  13. }

  15. // Register Garage on the container
  16. container.register({ class: Garage });

  18. class Car {
  19.   // Use inject method of the container for Garage
  20.   constructor(private garage = container.inject(Garage)) {}

  22.   park() {
  23.     this.garage.open();
  24.     console.log("car parked");
  25.   }

  27.   // New instance on every injection
  28.   static scope = Scopes.Transient();
  29. }

  31. const car = container.inject(Car);

  33. car.park();
  34. ```

Container-scoped classes usually are registered in the container first. Without it, the class will "stick" to the container it's used in.