Dependency Injection for JavaScript & TypeScript

Common errors

• TypeError: Reflect.getMetadata is not a function

  cause The required Reflect API polyfill (`reflect-metadata` or similar) has not been imported or is not available at runtime when decorated classes are processed.
  fix Install `reflect-metadata` (`npm install reflect-metadata`) and add `import 'reflect-metadata';` as the very first line in your application's main entry point file. This ensures the polyfill loads before any decorated classes are defined.

• Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option to remove this warning.

  cause TypeScript compiler is encountering decorator syntax (`@Injectable`) but the `experimentalDecorators` flag is not enabled in `tsconfig.json`.
  fix Open your `tsconfig.json` file and add or set `"experimentalDecorators": true` within the `compilerOptions` section. You will likely also need `"emitDecoratorMetadata": true` for `injection-js` to function correctly with decorators.

Warnings

• gotcha Using `injection-js` with TypeScript decorators (`@Injectable`) requires a Reflect API polyfill to be present in your environment. Without it, runtime errors will occur when the injector tries to resolve types.
  Fix: Install `reflect-metadata` (`npm i reflect-metadata`) and add `import 'reflect-metadata';` at the very top of your application's entry file, before any decorated classes are defined. Alternatively, use `@abraham/reflection` or `core-js/es7/reflect`.
• gotcha When using TypeScript decorators like `@Injectable()` for dependency injection, you must enable `experimentalDecorators` and `emitDecoratorMetadata` in your `tsconfig.json` compiler options.
  Fix: Add or ensure the following in your `tsconfig.json`: ```json { "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true } } ```
• breaking This library is an extraction of Angular's *pre-v5* dependency injection system (`ReflectiveInjector`). It is fundamentally different from Angular v5+ `StaticInjector`, which uses compile-time DI. Do not expect compatibility with newer Angular DI patterns or the Angular compiler.
  Fix: Understand that `injection-js` offers a runtime, reflection-based DI. If you need compile-time DI or are building an Angular application, use `@angular/core`'s built-in DI system. This library is for non-Angular applications that still desire Angular-style DI.
• gotcha While `injection-js` supports ES6 and ES5 syntax for defining dependencies, the modern TypeScript-first approach using decorators or the `inject` function is recommended for clarity and type safety. Older patterns using `static get parameters()` or `di.Class` might be harder to maintain.
  Fix: For new projects or refactoring, prioritize using TypeScript with decorators (`@Injectable`, `constructor` type hints) or the `inject` function for dependency resolution, along with the required `tsconfig.json` settings and `reflect-metadata` polyfill.

Install

• npm install injection-js npm
• yarn add injection-js yarn
• pnpm add injection-js pnpm

Imports

• inject
  wrong:

  const { inject } = require('injection-js');

  correct:

  import { inject } from 'injection-js';

  The `inject` function is a modern way to declare dependencies, typically used within TypeScript classes. While `require` might work in some transpiled environments, the `import` statement is the canonical way for ESM.
• ReflectiveInjector
  wrong:

  const ReflectiveInjector = require('injection-js').ReflectiveInjector;

  correct:

  import { ReflectiveInjector } from 'injection-js';

  `ReflectiveInjector` is the core class for creating and managing dependency injectors. The CJS `require` pattern is common in older Node.js projects or for specific build setups, but ESM `import` is preferred.
• Injectable
  wrong:

  import Injectable from 'injection-js/Injectable';

  correct:

  import { Injectable } from 'injection-js';

  `@Injectable()` is a decorator used to mark classes as providers for the injector. It's a named export, not a default export or a separate file path. Requires `experimentalDecorators` and `emitDecoratorMetadata` in `tsconfig.json`.

Quickstart

This quickstart demonstrates setting up `injection-js` with decorators and the `inject` function, creating an injector, and resolving dependencies. It includes the necessary `reflect-metadata` import and showcases how services depend on each other.

import 'reflect-metadata'; // Must be imported once at the application entry point
import { inject, ReflectiveInjector, Injectable } from 'injection-js';

@Injectable()
class HttpService {
  public readonly baseUrl = 'https://api.example.com';
  constructor() {
    console.log('HttpService initialized');
  }
}

@Injectable()
class LoggerService {
  log(message: string): void {
    console.log(`[Log] ${message}`);
  }
}

@Injectable()
class DataService {
  private http = inject(HttpService);
  private logger = inject(LoggerService);

  constructor() {
    this.logger.log('DataService created, ready for operations.');
  }

  fetchData(): string {
    this.logger.log(`Fetching data from: ${this.http.baseUrl}/data`);
    return `Data from ${this.http.baseUrl} for the current user.`;
  }
}

// Create an injector with providers
const appInjector = ReflectiveInjector.resolveAndCreate([
  HttpService,
  LoggerService,
  DataService
]);

// Get an instance of DataService from the injector
const dataService = appInjector.get(DataService);
console.log('Is dataService an instance of DataService?', dataService instanceof DataService);
console.log('Fetched:', dataService.fetchData());

// Demonstrate getting another service directly
const loggerService = appInjector.get(LoggerService);
loggerService.log('Application started successfully.');