Dioma Dependency Injection Container

Dioma provides several scope types to control the lifecycle and instantiation of classes via the static scope property:

• Scopes.Singleton(): Creates a single instance for the entire application (stored in the global container).
• Scopes.Transient(): Creates a new instance on every injection.
• Scopes.Container(): Creates a single instance per container (also referred to as Scopes.Scoped()).
• Scopes.Resolution(): Creates a new instance every time, but the same instance is reused for the duration of a single resolution (useful for request-scoped data).

import { Scopes } from "dioma";

class MyService {
  static scope = Scopes.Singleton(); // or Transient(), Container(), Resolution()
}

Tokens allow you to inject abstractions (interfaces/abstract classes), constant values, or results from factory functions instead of concrete classes.

Class Tokens

Useful for injecting an implementation for an interface or abstract class.

Value Tokens

Used to inject constant values.

Factory Tokens

Used to inject a value produced by a function. The factory function receives the container as its first argument.

import { Token, Container } from "dioma";

// Value Token
const token = new Token<string>("Value token");
container.register({ token, value: "Value" });
const value = container.inject(token);

// Factory Token
const factoryToken = new Token<string>("Factory token");
container.register({
  token: factoryToken,
  factory: (container, a: string, b: string): string => a + b,
});
const result = container.inject(factoryToken, "Hello, ", "world!");

To use Dioma, add a static scope property to your class and use the inject function to retrieve instances. By default, classes become 'sticky' to the container where they are first injected. You can define different lifecycles using Scopes.

import { inject, Scopes } from "dioma";

class Garage {
  open() {
    console.log("garage opened");
  }
  static scope = Scopes.Singleton();
}

class Car {
  constructor(private garage = inject(Garage)) {}

  park() {
    this.garage.open();
    console.log("car parked");
  }
  static scope = Scopes.Transient();
}

const car = inject(Car);
car.park();

Install Dioma using npm or yarn to use its dependency injection capabilities in your JavaScript or TypeScript projects.

npm install --save dioma

yarn add dioma

You can create a hierarchy of containers using container.childContainer(). Dioma searches for instances top-down from the current container to the root. If an instance is not found, it is created in the current container or the container where the class was originally registered.

import { Container, Scopes } from "dioma";

const parent = new Container("Parent");
const child = parent.childContainer("Child");

class SharedService {
  static scope = Scopes.Container();
}

// Register in parent
parent.register({ class: SharedService });

// Child can access the parent's instance
const instance = child.inject(SharedService);

Tokens allow for decoupled dependency injection where you can inject based on an abstract identifier rather than a concrete class.

• new Token<T>(name?): Creates a new token of type T. Tokens can be used with both inject and injectAsync.

import { Token, injectAsync } from "dioma";

const token = new Token<A>("A");

class B {
  constructor(private promiseA = injectAsync(token)) {
    // ...
  }
}

For Transient and Resolution scopes, you can pass additional arguments to the constructor during injection by providing them as subsequent arguments to the inject function.

import { inject, Scopes } from "dioma";

class Pet {
  constructor(public name: string, public owner = inject(Owner)) {}
  static scope = Scopes.Transient();
}

class Owner {
  static scope = Scopes.Singleton();
}

// Injecting Pet with the argument "Fluffy"
const pet = inject(Pet, "Fluffy");

Use a Container instance to explicitly manage class lifecycles. Registering a class allows you to control its scope or ensure it is shared across child containers. You can also unregister classes to remove them from the container and its children.

import { Container, Scopes } from "dioma";

const container = new Container();

// Register a class with a specific scope
container.register({ class: FooBar, scope: Scopes.Transient() });

// Unregister a class
container.unregister(FooBar);

Dioma uses the Injectable<T> interface to ensure that every class intended for injection has a static scope defined. If a class implements Injectable but lacks a static scope, TypeScript will flag an error. This prevents runtime errors caused by missing scope definitions.

import { Scopes, Injectable } from "dioma";

class Database implements Injectable<typeof Database> {
  constructor(private url: string) {}
  static scope = Scopes.Singleton();
}

import { inject, Scopes, Injectable } from "dioma";

class Database implements Injectable<typeof Database> {
  constructor(private url: string) {}
  connect() {
    console.log(`Connected to ${this.url}`);
  }

  static scope = Scopes.Singleton();
}

// Error, scope is not specified
class Repository implements Injectable<typeof Repository> {
  constructor(private db = inject(Database)) {}
}

When registering a class in a container, you can provide beforeInject and beforeCreate hooks to execute logic before the instance is created or injected.

container.register({
  class: MyClass,
  beforeInject: (container, descriptor, args) => {
    console.log("Before inject");
  },
  beforeCreate: (container, descriptor, args) => {
    console.log("Before create");
  },
});