di-wise-neo

[!NOTE] di-wise-neo is a fork of [di-wise][di-wise], aiming to provide a simpler yet more powerful API, in part thanks to TypeScript's experimental decorators. Shout out to @exuanbo for the strong foundations!

Table of Contents

• Installation
• API reference
• Ergonomics & Requirements
• Quickstart
• Container scopes
• Token registration
• Function-based injection
• Decorator-based injection
• Behavioral decorators
• Testing support

Why yet another library

I've been developing VS Code extensions for a while as part of my daily work. It's enjoyable work! However, extensions always reach that tipping point where feature bloat, and the many different UI interactions which arise from that, make writing, reading, and understanding the codebase a challenge.

Part of the problem is the crazy amount of parameter passing, and the many exported global values floating around waiting to be imported and to generate yet another coupling point.

My background with Java is full of such cases that have been (partially) mitigated by introducing dependency-injection libraries based on Java's powerful Contexts and Dependency Injection (see [Weld][cdi-weld], the reference implementation).

So why not apply the same concept to our TypeScript projects?
I've posted on Reddit just to get a feel of what the ecosystem offers, and was pointed to libraries such as [tsyringe][tsyringe], [InversifyJS][InversifyJS], or [Awilix][Awilix]. I've also explored on my own and discovered [redi][redi] and [di-wise][di-wise].

What I was looking for is a lightweight solution that offers:

• Full type safety.
• Scoped resolution of dependencies.
• Optional decorator support for constructor and method injection.
  Yes, I know, forget type-safety with decorators, but they are extremely intuitive to pick up for Java devs.
• No dependency on [reflect-metadata][reflect-metadata], as I'm an ESBuild user and ESBuild [does not][esbuild-issue] support emitDecoratorMetadata.

Unfortunately, both [tsyringe][tsyringe] and [InversifyJS][InversifyJS] require [reflect-metadata][reflect-metadata] to run correctly. [Awilix][Awilix] looks good, but it's probably too much for what I need to do, and it does not support decorators. Plus, the API just didn't click for me.

[redi][redi] focuses only on constructor injection via decorators, which is nice. However, it falls short when it comes to type safety and resolution scopes: it only supports singletons with a decorator-based trick to create fresh instances.

And lastly, [di-wise][di-wise]. This small library was quite a surprise! Easy to pick up, no scope creep, injection context support, and full type safety via Angular-like inject<T>() functions (that's more like a service locator, but whatever). The only problems are the slightly overcomplicated API - especially regarding typings - and the use of ECMAScript Stage 3 decorators, which do not support decorating method parameters :sob:

So what's the right move? Forking the best pick and refactoring it to suite my production needs.

Installation

npm i @lppedd/di-wise-neo

pnpm add @lppedd/di-wise-neo

yarn add @lppedd/di-wise-neo

API reference

You can find the complete API reference at [lppedd.github.io/di-wise-neo][di-wise-neo].

Ergonomics

• Does not depend on other libraries.
• Does not use [reflect-metadata][reflect-metadata] to drive decorators.
• Can be used from JavaScript with function-based injection.

Requirements

• The JS environment must support features such as Array.at, Array.flat, WeakRef, WeakMap, Set, Map.

Decorator-based injection

• When using decorator-based injection, experimentalDecorators must be enabled in your tsconfig.json file.

Quickstart

//
// A couple of classes to cover the example
//

export class ExtensionContext { /* ... */ }

// Both the secret store and the contribution registrar
// require the extension context to read and set values

export class SecretStore {
  // We can use function-based injection, which gives us type safety
  readonly context = inject(ExtensionContext);

  // Or even
  // constructor(readonly context = inject(ExtensionContext)) {}

  /* ... */
}

export class ContributionRegistrar {
  // We can also opt to use decorator-based constructor injection
  constructor(@Inject(ExtensionContext) readonly context: ExtensionContext) {}

  /* ... */

  // Or method injection. The @Optional decorator injects "T | undefined".
  protected withSecretStore(@Optional(SecretStore) store: SecretStore | undefined): void {
    if (store?.isSet("key")) {
      /* ... */
    }
  }
}

//
// Using di-wise-neo
//

// Create a new DI container
const container = createContainer({
  // Optionally override the default "Transient" registration scope.
  // I prefer to use "Container" (a.k.a. Singleton) scope, but "Transient" is the better default.
  defaultScope: "Container",
});

// Register our managed dependencies in the container
container.register(ExtensionContext)
         .register(SecretStore)
         .register(ContributionRegistrar);

// Get the contribution registrar.
// The container will create a new managed instance for us, with all dependencies injected.
const registrar = container.resolve(ContributionRegistrar);
registrar.registerCommand("my.command", () => { console.log("hey!"); });

Container scopes

The [Container][source-container] supports three scope types that determine how and when values are cached and reused.

Transient

Creates a new value every time the dependency is resolved, which means values are never cached.

• A class registered via ClassProvider is instantiated on each resolution
• A factory function registered via FactoryProvider is invoked on each resolution
• A value registered via ValueProvider is always returned as-is

[!NOTE] When a Transient or Resolution-scoped value is injected into a Container-scoped instance, it effectively inherits the lifecycle of that instance. The value will live as long as the containing instance, even though it is not cached by the container itself.

Resolution

Creates and caches a single value per resolution graph.
The same value is reused during a single resolution request, but a new one is created for each request.

Container

Creates and caches a single value per container.
If the value is not found in the current container, it is looked up in the parent container, and so on.

It effectively behaves like a singleton scope but allows container-specific overrides.

Token registration

The container allows registering tokens via providers. The generic usage is:

container.register(/* ... */);

An explicit scope can be specified using the third argument, when applicable.
If omitted, the default scope is Transient.

container.register(token, provider, { scope: "Resolution" });

ClassProvider

You can register a class by passing it directly to the register method:

container.register(SecretStore);

Alternatively, use an explicit ClassProvider object - useful when registering an interface or abstract type:

const IStore = createType<Store>("Store");
container.register(IStore, {
  useClass: SecretStore, // class SecretStore implements Store
});

Upon resolving IStore - which represents the Store interface - the container creates an instance of SecretStore, caching it according to the configured scope.

FactoryProvider

A lazily computed value can be registered using a factory function:

const Env = createType<string>("Env")
container.register(Env, {
  useFactory: () => isNode() ? "Node.js" : "browser",
});

The factory function is invoked upon token resolution, and its result is cached according to the configured scope.

ValueProvider

A fixed value - always taken as-is and unaffected by scopes - can be registered using:

const PID = createType<number>("PID");
const processId = spawnProcess();
container.register(PID, {
  useValue: processId,
});

This is especially useful when injecting third-party values that are not created through the DI container.

ExistingProvider

Registers an alias to another token, allowing multiple identifiers to resolve to the same value.
Using the previous PID example, we can register a TaskID alias:

const TaskID = createType<number>("TaskID");
container.register(TaskID, {
  useExisting: PID,
});

The container will translate TaskID to PID before resolving the value.

Function-based injection

The primary way to perform dependency injection in di-wise-neo is through functions like inject(T), injectAll(T), optional(T), and optionalAll(T).

[!TIP] Using injection functions is recommended because it preserves type safety.

Injection context

All injection functions must be invoked inside an injection context, which stores the currently active container.
The injection context is available in these situations:

• Inside the constructor of a class instantiated by the DI container.
• In property initializers of such classes.
• Within factory functions used by FactoryProvider.
• Within functions passed to Injector.runInContext.

inject<T>(Token): T

Injects the value associated with a token, throwing an error if the token is not registered in the container.

export class ProcessManager {
  constructor(readonly rootPID /*: number */ = inject(PID)) {}

  /* ... */
}

If PID cannot be resolved, a resolution error with detailed information is thrown.

injectAll<T>(Token): T[]

Injects all values associated with a token, throwing an error if the token has never been registered in the container.

export class ExtensionContext {
  readonly stores /*: Store[] */ = injectAll(IStore);

  /* ... */

  clearStorage(): void {
    this.stores.forEach((store) => store.clear());
  }
}

optional<T>(Token): T

Injects the value associated with a token, or undefined if the token is not registered in the container.

export class ProcessManager {
  constructor(readonly rootPID /*: number | undefined */ = optional(PID)) {}

  /* ... */
}

optionalAll<T>(Token): T[]

Injects all values associated with a t