di-wise 🧙‍♀️

Table of Contents

Installation

npm install di-wise
pnpm add di-wise
yarn add di-wise

deno add jsr:@exuanbo/di-wise

Features

Zero dependencies

Modern decorator implementation

Context-based DI system

import {createContainer, Inject, inject, Injectable, Scope, Scoped, Type} from "di-wise";
interface Spell {
 cast(): void;
}
const Spell = Type<Spell>("Spell");
@Scoped(Scope.Container)
@Injectable(Spell)
class Fireball implements Spell {
 cast() {
 console.log("🔥");
 }
}
class Wizard {
 @Inject(Wand)
 wand!: Wand;
 // Equivalent to
 wand = inject(Wand);
 constructor(spell = inject(Spell)) {
 // inject() can be used anywhere during construction
 this.wand.store(spell);
 }
}
const container = createContainer();
container.register(Fireball);
// Under the hood
[Fireball, Spell].forEach((token) => {
 container.register(
 token,
 {useClass: Fireball},
 {scope: Scope.Container},
 );
});
const wizard = container.resolve(Wizard);
wizard.wand.activate(); // => 🔥

Multiple provider types

import {Build, createContainer, inject, Value} from "di-wise";
class Wizard {
 equipment = inject(
 Cloak,
 // Provide a default value
 Value({
 activate() {
 console.log("👻");
 },
 }),
 );
 wand: Wand;
 constructor(wand: Wand) {
 this.wand = wand;
 }
}
const container = createContainer();
const wizard = container.resolve(
 Build(() => {
 // inject() can be used in factory functions
 const wand = inject(Wand);
 return new Wizard(wand);
 }),
);
wizard.equipment.activate(); // => 👻

Hierarchical injection

import {createContainer, inject, Injectable, Type} from "di-wise";
const MagicSchool = Type<string>("MagicSchool");
const Spell = Type<{cast(): void}>("Spell");
// Parent container with shared config
const hogwarts = createContainer();
hogwarts.register(MagicSchool, {useValue: "Hogwarts"});
@Injectable(Spell)
class Fireball {
 school = inject(MagicSchool);
 cast() {
 console.log(`🔥 from ${this.school}`);
 }
}
// Child containers with isolated spells
const gryffindor = hogwarts.createChild();
gryffindor.register(Fireball);
const slytherin = hogwarts.createChild();
slytherin.register(Spell, {
 useValue: {cast: () => console.log("🐍")},
});
gryffindor.resolve(Spell).cast(); // => 🔥 from Hogwarts
slytherin.resolve(Spell).cast(); // => 🐍

Full control over registration and caching

Various injection scopes

import {createContainer, Scope} from "di-wise";
export const singletons = createContainer({
 defaultScope: Scope.Container,
 autoRegister: true,
});
// Always resolves to the same instance
const wizard = singletons.resolve(Wizard);

Inherited (default)

Transient

Resolution

Container

Flexible token-based injection

import {inject, Type} from "di-wise";
class Wizard {
 wand = inject(Wand, Type.Null);
 // ^? (property) Wizard.wand: Wand | null
 spells = injectAll(Spell, Type.Null);
 // ^? (property) Wizard.spells: Spell[]
 // => []
}

Automatic circular dependency resolution

import {createContainer, Inject, inject} from "di-wise";
class Wand {
 owner = inject(Wizard);
}
class Wizard {
 @Inject(Wand)
 wand!: Wand;
 // Equivalent to
 wand = inject.by(this, Wand);
}
const container = createContainer();
const wizard = container.resolve(Wizard);
expect(wizard.wand.owner).toBe(wizard);

Dynamic injection

import {createContainer, inject, Injector} from "di-wise";
class Wizard {
 private injector = inject(Injector);
 private wand?: Wand;
 getWand() {
 // Lazy load wand only when needed
 return (this.wand ??= this.injector.inject(Wand));
 }
 castAllSpells() {
 // Get all registered spells
 const spells = this.injector.injectAll(Spell);
 spells.forEach((spell) => spell.cast());
 }
}
const container = createContainer();
const wizard = container.resolve(Wizard);
wizard.getWand(); // => Wand

import {createContainer, inject, Injector} from "di-wise";
class Wand {
 owner = inject(Wizard);
}
class Wizard {
 private injector = inject.by(this, Injector);
 getWand() {
 return this.injector.inject(Wand);
 }
}
const container = createContainer();
const wizard = container.resolve(Wizard);
const wand = wizard.getWand();
expect(wand.owner).toBe(wizard);

Constructor Injection

Middleware

import {applyMiddleware, createContainer, type Middleware} from "di-wise";
const logger: Middleware = (composer, _api) => {
 composer
 .use("resolve", (next) => (token) => {
 console.log("Resolving:", token.name);
 const result = next(token);
 console.log("Resolved:", token.name);
 return result;
 })
 .use("resolveAll", (next) => (token) => {
 console.log("Resolving all:", token.name);
 const result = next(token);
 console.log("Resolved all:", token.name);
 return result;
 });
};
const performanceTracker: Middleware = (composer, _api) => {
 composer.use("resolve", (next) => (token) => {
 const start = performance.now();
 const result = next(token);
 const end = performance.now();
 console.log(`Resolution time for ${token.name}: ${end - start}ms`);
 return result;
 });
};
const container = applyMiddleware(createContainer(), [logger, performanceTracker]);
// Use the container with applied middlewares
const wizard = container.resolve(Wizard);

Usage

API

Credits

License