DIOD (Dependency Injection On Demand)

DIOD v3.0.0 provides a dependency injection system centered around a Container and a ContainerBuilder. The API is composed of several key building blocks:

Core Classes

• ContainerBuilder: Used to construct and configure a dependency injection container.

Core Interfaces

• Container: The primary interface for interacting with the dependency injection container.
• Registration: Represents a registered dependency within the container.
• Newable: Represents a class or constructor that can be instantiated.
• Abstract: Base interface for DIOD abstractions.
• ConfigurableRegistration: Interface for registrations that allow configuration.
• WithDependencies: Interface for managing dependencies of a registration.
• WithScopeChange: Interface for managing the scope of a registration.

Type Aliases

• Identifier: The key used to look up a dependency.
• Factory: A function used to create an instance of a dependency.
• Instance: The resolved value of a dependency.
• BuildOptions: Configuration options used during the container building process.

Functions

• Service: A utility function for defining services.

DIOD follows the Dependency Inversion Principle (the 'D' in SOLID). While many languages use interfaces for abstractions, TypeScript interfaces are not available at runtime. Therefore, to use abstractions for autowiring dependencies in DIOD, you must define your abstractions using abstract classes.

By injecting an abstract class into a consumer (like a Use Case), you decouple the consumer from the concrete implementation. This allows you to swap implementations (e.g., switching from SqliteUserRepository to a different database) by changing only the registration in your ContainerBuilder.

// 1. Define the abstraction as an abstract class
export abstract class Mailer {
  abstract sendConfirmationEmail(userData: user): void
  abstract sendResetPasswordEmail(userData: user): void
}

// 2. Inject the abstraction into your service
@Service()
export class SignUpUseCase {
  constructor(
    private readonly mailer: Mailer // DIOD uses the abstract class for autowiring
  ) {}
}

// 3. Implement the concrete class
@Service()
export class AcmeMailer implements Mailer {
  sendConfirmationEmail(userData: user): void { /* ... */ }
  sendResetPasswordEmail(userData: user): void { /* ... */ }
}

DIOD uses constructor type-hints to automatically resolve and inject dependencies.

Key Requirements:

1. Decorators: All registered services must be decorated (e.g., using @Service()) so that TypeScript emits the necessary metadata at runtime.
2. Abstractions: Because TypeScript interfaces are removed at runtime, you must use abstract classes instead of interfaces if you want to use them as dependency tokens for autowiring.
3. Container Building: After registering services, you must use a ContainerBuilder to validate the dependency graph (checking for missing dependencies or circularities) and create an immutable container.

// Example of a service using autowiring via constructor type-hints
import { Service } from 'diod'

@Service()
export class SignUpUseCase {
	constructor(
		private readonly userRepository: UserRepository,
		private readonly mailer: Mailer,
	) {}
}

DIOD uses instance scopes to determine how services are shared. You can configure the scope during registration using a ContainerBuilder.

There are three available scopes:

• Transient (Default): Returns a new instance every time the service is requested.
• Request (asInstancePerRequest): Returns a single instance within the same request context.
• Singleton (asSingleton): Returns the same instance for every request across the entire application.

Note that manually created instances registered via useInstance are always treated as singletons and cannot be changed to other scopes.

const builder = new ContainerBuilder()

// Returns a new instance every time (Default)
builder.registerAndUse(Whatever).asTransient()

// Returns one instance per request
builder.registerAndUse(Whatever).asInstancePerRequest()

// Returns the same instance everywhere
builder.registerAndUse(Whatever).asSingleton()

const container = builder.build()

To avoid manually calling registerAndUse for every class, you can implement a custom decorator pattern that collects classes into an array and registers them all at once using a helper function.

1. Create an autoregister.ts file containing a decorator (e.g., RegisterService) that pushes classes into a local registry array.
2. Use the decorator on your service classes.
3. Use an autoregister helper function to iterate through the registry and call builder.registerAndUse(service) on your ContainerBuilder instance.

// autoregister.ts
import { ContainerBuilder, Newable } from 'diod'

const autoregisteredClasses: Newable<unknown>[] = []

const isNewable = (target: unknown): target is Newable<unknown> => {
  if (typeof target !== 'function') {
    return false
  }

  const prototype = target.prototype
  return !!prototype && !!prototype.constructor
}

export const RegisterService = (): ClassDecorator => {
  return <TFunction extends Function>(target: TFunction): TFunction => {
    if (isNewable(target)) {
      autoregisteredClasses.push(target)
    } else {
      throw new Error('Abstract classes cannot be auto registered')
    }

    return target
  }
}

export const autoregister = (builder: ContainerBuilder): ContainerBuilder => {
  for (const service of autoregisteredClasses) {
    builder.registerAndUse(service)
  }

  return builder
}

While DIOD is optimized for TypeScript, it can be used in vanilla JavaScript. Because JavaScript lacks type information, DIOD cannot automatically discover dependencies from constructors. You must manually register each service and explicitly provide its dependencies using the .withDependencies() method. When building the container, you must set the autowire option to false.

import { ContainerBuilder } from 'diod'

const builder = new ContainerBuilder()

// Manually register services and their dependencies
builder.registerAndUse(ServiceOne).withDependencies([ServiceTwo, ServiceThree])
builder.registerAndUse(ServiceTwo).withDependencies([ServiceFour])
builder.registerAndUse(ServiceThree)
builder.registerAndUse(ServiceFour)

// Build the container with autowire disabled
export const container = builder.build({ autowire: false })

// Retrieve services
const serviceOne = container.get(ServiceOne)