Inversify Binding Decorators

Common errors

• Cannot apply @injectable decorator multiple times. Please use @provide(ID, true) if you are trying to declare multiple bindings!

  cause Attempted to apply the `@provide` decorator more than once to a single class without explicitly allowing multiple bindings.
  fix If you intend to provide the class under multiple identifiers, use `@provide(identifier, true)` for each additional binding. For example, `@provide("Logger", true)` and `@provide("ConsoleLogger", true)`.

• Error: Missing required @injectable annotation in: ClassName

  cause A class intended for dependency injection via `@provide` was not also decorated with `@injectable` from `inversify`.
  fix Ensure that any class decorated with `@provide` also has the `@injectable()` decorator from `inversify` applied to it, e.g., `@injectable() @provide(MyService) class MyService { ... }`.

Warnings

• breaking Major versions of `inversify-binding-decorators` (e.g., 2.x, 3.x, 4.x) are tightly coupled to corresponding major versions of `inversify`. Upgrading `inversify` may necessitate upgrading this library and vice-versa, potentially involving breaking changes in the core InversifyJS API.
  Fix: Always check the compatibility matrix between `inversify` and `inversify-binding-decorators` before upgrading either package. Review both packages' release notes for breaking changes.
• gotcha Applying the `@provide` decorator multiple times to a single class without explicit permission will throw an error to prevent accidental duplicate bindings.
  Fix: If multiple bindings for the same class are intended, pass `true` as the second argument to `@provide`, e.g., `@provide("Ninja", true)` for multiple identifiers.
• gotcha The `reflect-metadata` polyfill must be imported exactly once at the entry point of your application to enable TypeScript's decorator metadata reflection, which is crucial for both InversifyJS and `inversify-binding-decorators` to function correctly.
  Fix: Ensure `import "reflect-metadata";` is present at the very top of your main application file (e.g., `main.ts`, `app.ts`).

Install

• npm install inversify-binding-decorators npm
• yarn add inversify-binding-decorators yarn
• pnpm add inversify-binding-decorators pnpm

Imports

• provide
  wrong:

  import provide from 'inversify-binding-decorators';

  correct:

  import { provide } from 'inversify-binding-decorators';

  This is a named export for the primary decorator. Do not attempt a default import.
• buildProviderModule
  wrong:

  const { buildProviderModule } = require('inversify-binding-decorators');

  correct:

  import { buildProviderModule } from 'inversify-binding-decorators';

  Use named import for the utility function that registers all decorated bindings. ESM is the standard for modern TypeScript projects.
• injectable

  import { injectable, Container } from 'inversify';

  While not from this package, `injectable` from `inversify` is crucial for classes using DI and works alongside `@provide`.

Quickstart

Demonstrates how to use the `@provide` decorator to declare bindings and `buildProviderModule` to load them into an InversifyJS container.

import { injectable, Container } from "inversify";
import { provide, buildProviderModule } from "inversify-binding-decorators";
import "reflect-metadata"; // Must be imported once at the application entry point

interface Weapon { hit(): string; }
interface ThrowableWeapon { throw(): string; }

@injectable()
@provide(Katana)
class Katana implements Weapon {
    public hit() {
        return "cut!";
    }
}

@injectable()
@provide(Shuriken)
class Shuriken implements ThrowableWeapon {
    public throw() {
        return "hit!";
    }
}

const container = new Container();
// Load all bindings declared via @provide decorators
container.load(buildProviderModule());

// Resolve instances from the container
const katana = container.get<Weapon>(Katana);
const shuriken = container.get<ThrowableWeapon>(Shuriken);

console.log(`Katana: ${katana.hit()}`);
console.log(`Shuriken: ${shuriken.throw()}`);