dot package

A lightweight inversion of control framework for JavaScript and TypeScript

Remarks

For a discussion of the project goals, please see Github Discussions.

Example

import { createContainer, injectable, inject, type interfaces } from "@mscharley/dot";

export interface Warrior {
  fight: () => string;
  sneak: () => string;
}

export interface Weapon {
  hit: () => string;
}

export interface ThrowableWeapon {
  throw: () => string;
}

const TYPES = {
  Warrior: new Token<Warrior>('Warrior'),
  Weapon: new Token<Weapon>('Weapon'),
  ThrowableWeapon: new Token<ThrowableWeapon>('ThrowableWeapon'),
};

@injectable()
class Katana implements Weapon {
  public hit(): string {
    return 'cut!';
  }
}

@injectable()
class Shuriken implements ThrowableWeapon {
  public throw(): string {
    return 'hit!';
  }
}

@injectable(TYPES.Weapon, TYPES.ThrowableWeapon)
class Ninja implements Warrior {
  public constructor(
    private readonly katana: Weapon,
    private readonly shuriken: ThrowableWeapon,
  ) {
    console.log('constructing:', this.katana, this.shuriken);
  }

  public fight(): string {
    return this.katana.hit();
  }
  public sneak(): string {
    return this.shuriken.throw();
  }
}

const myContainer = createContainer();

const demoModule: interfaces.ContainerModule = (bind) => {
  bind(TYPES.Warrior).inSingletonScope().to(Ninja);
  bind(TYPES.Weapon).to(Katana);
  bind(TYPES.ThrowableWeapon).to(Shuriken);
};
myContainer.load(demoModule);

const ninja = await myContainer.get(TYPES.Warrior);

console.log('fight', ninja.fight()); // cut!
console.log('sneak', ninja.sneak()); // hit!

const ninja2 = await myContainer.get(TYPES.Warrior);

console.log('ninja === ninja2:', ninja === ninja2); // true

Classes

Class

Description

InvalidOperationError

Error for operations which aren’t allowed

MetadataToken

An identifier that specifies bindings should also have metadata attached to them

NamedToken

Helper token type for the common case of simple named bindings

RecursiveResolutionError

A recursion was detected while trying to resolve a dependency

Token

A simple identifier that has a reference to a type which can be injected

TokenResolutionError

Error for wrapping issues with resolving dependencies

Abstract Classes

Abstract Class

Description

IocError

Superclass for all errors that are thrown by the IOC container

ResolutionError

An error occurred while trying to resolve a request

Functions

Function

Description

injectable(constructorTokens)

Decorator for classes to flag them as being usable with this library

isMetadataToken(o)

Type guard to check if something is a token that supports metadata

isToken(o)

Type guard to check if something is a token

named(id, name, options)

Helper to provide a simple way to interact with named bindings

stringifyIdentifier(id)

Turn a service identifier into a string

unmanaged(defaultValue, name)

Used to label a constructor parameter as unmanaged by the IOC container.

withOptions(id, options)

Helper to provide a nicer interface for injecting with options

Interfaces

Interface

Description

ClassDecorator_2

Typesafe definition of a class decorator

ClassFieldDecorator

Typesafe definition of a class field decorator

InjectDecoratorFactory

Type for the @inject decorator itself

Namespaces

Namespace

Description

interfaces

Variables

Variable

Description

createContainer

Create a new empty container

inject

Decorator for property injections

Type Aliases

Type Alias

Description

AnyToken

An easy way to reference any kind of token

ErrorCode

The error codes used by the IOC container

TokenType

A helper type to extract the type that a token will inject