@coderspirit/lambda-ioc

Super type safe dependency injection 💉 for TypeScript (inspired by Diddly)

NOTE: This is a “fork” of Tom Sherman’s Diddly library, who deserves most credit for this work.

Install instructions

Node

# With NPM
npm install @coderspirit/lambda-ioc

# Or with Yarn:
yarn add @coderspirit/lambda-ioc

Deno

Lambda-IoC is served through different CDNs

import { ... } from 'https://denopkg.com/Coder-Spirit/lambda-ioc@[VERSION]/lambda-ioc/deno/index.ts'
import { ... } from 'https://deno.land/x/lambda_ioc@[VERSION]/lambda-ioc/deno/index.ts'

Example

import {
  constructor,
  createContainer,
  func
} from '@coderspirit/lambda-ioc'

function printNameAndAge(name: string, age: number) {
  console.log(`${name} is aged ${age}`)
}

class Person {
  constructor(
    public readonly age: number,
    public readonly name: string
  ) {}
}

const container = createContainer()
  .registerValue('someAge', 5)
  .registerValue('someName', 'Timmy')
  // We can register functions
  .register('fn', func(printNameAndAge, 'someName', 'someAge'))
  // And constructors too
  .register('Person', constructor(Person, 'someAge', 'someName'))
  // We can "define groups" by using `:` as an infix, the group's name will be
  // the first part of the string before `:`.
  // Groups can be used in all "register" methods.
  .registerValue('group1:a', 1) // group == 'group1'
  .registerValue('group1:b', 2)
  .registerValue('group2:a', 3) // group == 'group2'
  .registerValue('group2:b', 4)

// We can resolve registered functions
const print = container.resolve('fn')
print() // Prints "Timmy is aged 5"

// We can resolve registered constructors
const person = container.resolve('Person')
console.print(person.age) // Prints "5"
console.print(person.name) // Prints "Timmy"

// We can resolve registered "groups"
container.resolveGroup('group1') // ~ [1, 2], not necessarily in the same order
container.resolveGroup('group2') // ~ [3, 4], not necessarily in the same order

// We can also resolve the container itself, and the return type will always be
// up to date. This is useful if we want to use the container as a factory for
// some of your dependencies.
const resolvedContainer = container.resolve('$')

// If you want to indirectly resolve the container itself, it can be done only
// with the methods:
//   - registerConstructor
//   - registerAsyncConstructor
// This is because they have "privileged" information about the container's
// type, while relying on `register` or `registerAsync` plus "combinators" does
// not allow us to leverage that information.

It is also possible to register and resolve asynchronous factories and dependencies. If you are curious, just try out:

registerAsync
registerAsyncConstructor
resolveAsync

Benefits

100% type safe:
- The type checker will complain if we try to resolve unregistered dependencies.
- The type checker will complain if we try to register new dependencies that depend on unregistered dependencies, or if there is any kind of type mismatch.
Purely functional
Immutable
Circular dependencies are impossible

Drawbacks

All dependencies must be declared “in order”.
- This implies that this IoC container cannot be used in combination with some auto-wiring solutions, such as IoC decorators.
The involved types are a bit convoluted:
- They might cause the type checker to be slow.
- In some situations, the type checker might be unable to infer the involved types due to excessive “nested types” depth.

Differences respect to Diddly

First-class support for Deno.
First-class support for asynchronous dependency resolution.
Stricter types for dependencies re-registration.
Groups registration and resolution: very useful when we need to resolve all dependencies belonging to a same category.
Self-resolution. The container is able to resolve itself, to be used as a factory.
The container interface has been split into ReaderContainer and WriterContainer, making it easier to use precise types.
More extense documentation.