@lppedd/di-wise-neo 0.3.0

package/src/decorators/decorators.ts

@@ -0,0 +1,47 @@
+import { assert } from "../errors";
+import { getMetadata } from "../metadata";
+import type { Constructor, Token } from "../token";
+import type { Decorator } from "../tokenRegistry";
+import { forwardRef, isTokenRef, type TokenRef } from "../tokensRef";
+
+export function processDecoratedParameter(
+  decorator: Decorator,
+  token: Token | TokenRef,
+  target: object,
+  propertyKey: string | symbol | undefined,
+  parameterIndex: number,
+): void {
+  // Error out immediately if the decorator has been applied
+  // to a static property or a static method
+  if (propertyKey !== undefined && typeof target === "function") {
+    assert(false, `@${decorator} cannot be used on static member ${target.name}.${String(propertyKey)}`);
+  }
+
+  const tokenRef = isTokenRef(token) ? token : forwardRef(() => token);
+
+  if (propertyKey === undefined) {
+    // Constructor
+    const metadata = getMetadata(target as Constructor<any>);
+    metadata.dependencies.constructor.push({
+      decorator: decorator,
+      tokenRef: tokenRef,
+      index: parameterIndex,
+    });
+  } else {
+    // Normal instance method
+    const metadata = getMetadata(target.constructor as Constructor<any>);
+    const methods = metadata.dependencies.methods;
+    let dep = methods.get(propertyKey);
+
+    if (dep === undefined) {
+      dep = [];
+      methods.set(propertyKey, dep);
+    }
+
+    dep.push({
+      decorator: decorator,
+      tokenRef: tokenRef,
+      index: parameterIndex,
+    });
+  }
+}

package/src/decorators/index.ts

@@ -0,0 +1,7 @@
+export { AutoRegister } from "./autoRegister";
+export { Inject } from "./inject";
+export { Injectable } from "./injectable";
+export { InjectAll } from "./injectAll";
+export { Optional } from "./optional";
+export { OptionalAll } from "./optionalAll";
+export { Scoped } from "./scoped";

package/src/decorators/inject.ts

@@ -0,0 +1,42 @@
+import type { Constructor, Token } from "../token";
+import type { TokenRef } from "../tokensRef";
+import { processDecoratedParameter } from "./decorators";
+
+/**
+ * Parameter decorator that injects the instance associated with the given class.
+ *
+ * Throws an error if the class is not registered in the container.
+ */
+export function Inject<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects the value associated with the given token.
+ *
+ * Throws an error if the token is not registered in the container.
+ */
+export function Inject<Value>(token: Token<Value>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects the value associated with the given token.
+ *
+ * Allows referencing a token that is declared later in the file by using
+ * the {@link forwardRef} helper function.
+ *
+ * Throws an error if the token is not registered in the container.
+ *
+ * @example
+ * ```ts
+ * class Wizard {
+ *   constructor(@Inject(forwardRef(() => Wand)) readonly wand: Wand) {}
+ * }
+ * // Other code...
+ * class Wand {}
+ * ```
+ */
+export function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
+
+export function Inject<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
+  return function (target, propertyKey, parameterIndex: number): void {
+    processDecoratedParameter("Inject", token, target, propertyKey, parameterIndex);
+  };
+}

package/src/decorators/injectAll.ts

@@ -0,0 +1,45 @@
+import type { Constructor, Token } from "../token";
+import type { TokenRef } from "../tokensRef";
+import { processDecoratedParameter } from "./decorators";
+
+/**
+ * Parameter decorator that injects all instances provided by the registrations
+ * associated with the given class.
+ *
+ * Throws an error if the class is not registered in the container.
+ */
+export function InjectAll<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects all values provided by the registrations
+ * associated with the given token.
+ *
+ * Throws an error if the token is not registered in the container.
+ */
+export function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects all values provided by the registrations
+ * associated with the given token.
+ *
+ * Allows referencing a token that is declared later in the file by using
+ * the {@link forwardRef} helper function.
+ *
+ * Throws an error if the token is not registered in the container.
+ *
+ * @example
+ * ```ts
+ * class Wizard {
+ *   constructor(@InjectAll(forwardRef(() => Wand)) readonly wands: Wand[]) {}
+ * }
+ * // Other code...
+ * class Wand {}
+ * ```
+ */
+export function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
+
+export function InjectAll<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
+  return function (target, propertyKey, parameterIndex: number): void {
+    processDecoratedParameter("InjectAll", token, target, propertyKey, parameterIndex);
+  };
+}

package/src/decorators/injectable.ts

@@ -0,0 +1,61 @@
+import { getMetadata } from "../metadata";
+import type { Constructor, Tokens } from "../token";
+import { forwardRef, isTokensRef, type TokenRef, type TokensRef } from "../tokensRef";
+
+/**
+ * Class decorator for registering additional aliasing tokens for the decorated type
+ * when registering it.
+ *
+ * The container uses {@link ExistingProvider} under the hood.
+ *
+ * @example
+ * ```ts
+ * @Injectable(Weapon)
+ * class Wand {}
+ * ```
+ */
+export function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
+
+/**
+ * Class decorator for registering additional aliasing tokens for the decorated type
+ * when registering it.
+ *
+ * The container uses {@link ExistingProvider} under the hood.
+ *
+ * Allows referencing tokens that are declared later in the file by using
+ * the {@link forwardRef} helper function.
+ *
+ * @example
+ * ```ts
+ * @Injectable(forwardRef() => Weapon) // Weapon is declared after Wand
+ * class Wizard {}
+ * // Other code...
+ * class Weapon {}
+ * ```
+ */
+export function Injectable<This extends object, Value extends This>(
+  tokens: TokenRef<Value> | TokensRef<Value>,
+): ClassDecorator;
+
+/**
+ * @__NO_SIDE_EFFECTS__
+ */
+export function Injectable(...args: unknown[]): ClassDecorator {
+  return function (Class): void {
+    const metadata = getMetadata(Class as any as Constructor<any>);
+    const arg0 = args[0];
+    const tokensRef = isTokensRef(arg0) ? arg0 : forwardRef(() => args as Tokens);
+    const existingTokensRef = metadata.tokensRef;
+    metadata.tokensRef = {
+      getRefTokens: () => {
+        const existingTokens = existingTokensRef.getRefTokens();
+
+        for (const token of tokensRef.getRefTokens()) {
+          existingTokens.add(token);
+        }
+
+        return existingTokens;
+      },
+    };
+  };
+}

package/src/decorators/optional.ts

@@ -0,0 +1,39 @@
+import type { Constructor, Token } from "../token";
+import type { TokenRef } from "../tokensRef";
+import { processDecoratedParameter } from "./decorators";
+
+/**
+ * Parameter decorator that injects the instance associated with the given class,
+ * or `undefined` if the class is not registered in the container.
+ */
+export function Optional<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects the value associated with the given token,
+ * or `undefined` if the token is not registered in the container.
+ */
+export function Optional<Value>(token: Token<Value>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects the value associated with the given token,
+ * or `undefined` if the token is not registered in the container.
+ *
+ * Allows referencing a token that is declared later in the file by using
+ * the {@link forwardRef} helper function.
+ *
+ * @example
+ * ```ts
+ * class Wizard {
+ *   constructor(@Optional(forwardRef(() => Wand)) readonly wand: Wand | undefined) {}
+ * }
+ * // Other code...
+ * class Wand {}
+ * ```
+ */
+export function Optional<Value>(tokens: TokenRef<Value>): ParameterDecorator;
+
+export function Optional<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
+  return function (target, propertyKey, parameterIndex: number): void {
+    processDecoratedParameter("Optional", token, target, propertyKey, parameterIndex);
+  };
+}

package/src/decorators/optionalAll.ts

@@ -0,0 +1,42 @@
+import type { Constructor, Token } from "../token";
+import type { TokenRef } from "../tokensRef";
+import { processDecoratedParameter } from "./decorators";
+
+/**
+ * Parameter decorator that injects all instances provided by the registrations
+ * associated with the given class, or an empty array if the class is not registered
+ * in the container.
+ */
+export function OptionalAll<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects all values provided by the registrations
+ * associated with the given token, or an empty array if the token is not registered
+ * in the container.
+ */
+export function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
+
+/**
+ * Parameter decorator that injects all values provided by the registrations
+ * associated with the given token, or an empty array if the token is not registered
+ * in the container.
+ *
+ * Allows referencing a token that is declared later in the file by using
+ * the {@link forwardRef} helper function.
+ *
+ * @example
+ * ```ts
+ * class Wizard {
+ *   constructor(@OptionalAll(forwardRef(() => Wand)) readonly wands: Wand[]) {}
+ * }
+ * // Other code...
+ * class Wand {}
+ * ```
+ */
+export function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
+
+export function OptionalAll<T>(token: Token<T> | TokenRef<T>): ParameterDecorator {
+  return function (target, propertyKey, parameterIndex: number): void {
+    processDecoratedParameter("OptionalAll", token, target, propertyKey, parameterIndex);
+  };
+}

package/src/decorators/scoped.ts

@@ -0,0 +1,32 @@
+import { getMetadata } from "../metadata";
+import type { Scope } from "../scope";
+import type { Constructor } from "../token";
+
+/**
+ * Class decorator for setting the scope of the decorated type when registering it.
+ *
+ * The scope set by this decorator can be overridden by explicit registration options, if provided.
+ *
+ * @example
+ * ```ts
+ * @Scoped(Scope.Container)
+ * class Wizard {}
+ *
+ * container.register(Wizard);
+ *
+ * // Under the hood
+ * container.register(
+ *   Wizard,
+ *   { useClass: Wizard },
+ *   { scope: Scope.Container },
+ * );
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export function Scoped(scope: Scope): ClassDecorator {
+  return function (Class): void {
+    const metadata = getMetadata(Class as any as Constructor<any>);
+    metadata.scope = scope;
+  };
+}