"I'm really gonna giver when I head down this run" or "I don't have to worry about managing dependencies, I just giver and Giver injects my clients with what services they need"

Giver (styled "give'r") is a library that provides dependency injection through modern ECMAScript decorators. With Giver, you can easily achieve inversion of control in your code. Giver has no dependencies, is tiny (~2 KB), and is thoroughly tested.

[!NOTE]
Because the decorators proposal is in Stage 3, only some transpilers have released support for decorators syntax. Because of this, Giver can only be used in Typescript or any other compatible transpilation tool.

Usage

import { inject, injectable } from 'giver'

@injectable()
class LoggerService {
  log = (
    message: string
  ) => console.log(message);
}

class MyApplication {
  @inject() loggerService!: LoggerService

  start() {
    this.loggerService.log('Application started');
  }
}

const myApplication = new MyApplication();
myApplication.start();
// Emits "Application started" to the console.

Features

[!IMPORTANT] The current scope of Giver is completely implemented and tested today. That said, Giver is simple and not a full featured DI library, yet.

Giver supports constructor style injection of dependencies that are resolved with a registry.

• Services can be injected by using the registry.
• Services can be registered for injection.

Motivation

The existing dependency injection libraries on npm are great; However, at the time of writing, they all either:

1. Use experimental decorators.
2. Require dependencies.

So, the motivation for Giver is to be a lightweight, feature filled, tiny DI library.

Goals

1. services can be injected like this

@injectable()
class MyDependency {
  log = (msg: string) => console.log(msg);
}

@injectable()
class MyOtherDependency {
  getContent = () => "content";
}

@injectable()
class MyService {
  @inject(MyDependency) myDependency!: MyDependency;
  @inject(MyOtherDependency) myOtherDependency!: MyOtherDependency;

  doWork = () => {
    this.myDependency.log(this.myOtherDependency.getContent());
  };
}

const myService = giver.getInstanceOfClass(MyService);
myService.doWork();

3. clients can get instances of services like this:

const myService = giver.instanceOf(MyService);

4. bootstrapping can be done manually:

const giver = new Giver();
giver.register(MyService);
giver.register(MyOtherService, Lifetime.SINGLETON);

5. circular dependencies are detected and reported

6. services can be registered by any token:

type Token = symbol | string | number | Class;
giver.register(MyService, MyServiceToken);

7. clients can reference services that are not registered directly (e.g. they are interfaces)

class MyService {
  @inject(MyDependencyToken)
  private readonly myDependency!: IMyDependency;
  
  ctor(){}
}

Non-goals as of now

a) services define their lifetime: singleton or transient, like this:

@injectable(Lifetime.TRANSIENT | Lifetime.SINGLETON)
class MyService {
  doWork() {}
}

   ...

class MyService {...}
giver.register(MyService, Lifetime.TRANSIENT);

b) containers can be created with a parent/child relationship, child containers default to the parents services unless overridden. today, we just have one global container.

c) other registration patterns:

• provide by class
• provide by function (factory)
• provide by value

Prior art

Giver is inspired by Guice and tsyringe.