@tsed/di 8.0.1 → 8.0.3

package/src/common/errors/InjectionError.ts

@@ -0,0 +1,68 @@
+import {getConstructorArgNames, isClass, isString, nameOf} from "@tsed/core";
+
+import {TokenProvider} from "../interfaces/TokenProvider.js";
+import {colors} from "../utils/colors.js";
+
+export class InjectionError extends Error {
+  name = "INJECTION_ERROR";
+
+  public tokens: TokenProvider[] = [];
+  public origin: any;
+
+  constructor(token: TokenProvider, origin?: any) {
+    super(isString(origin) ? origin : "");
+
+    this.tokens = [token];
+
+    if (origin) {
+      if (isString(origin)) {
+        this.origin = {
+          message: origin,
+          stack: this.stack
+        };
+      } else {
+        if (origin.tokens) {
+          this.tokens = this.tokens.concat(origin.tokens);
+          this.origin = origin.origin;
+        } else {
+          this.origin = origin;
+          this.stack = origin.stack;
+        }
+      }
+    }
+
+    const originMessage = this.origin ? "\nOrigin: " + this.origin.message : "";
+    const tokensMessage = this.tokens.map((token) => nameOf(token)).join(" > ");
+
+    this.message = `Injection failed on ${tokensMessage}${originMessage}`;
+  }
+
+  static throwInjectorError(token: any, currentDependency: any, error: any) {
+    if (currentDependency && isClass(token)) {
+      error.message = printDependencyInjectionError(token, {...currentDependency, message: error.message});
+    }
+
+    throw new InjectionError(token, error);
+  }
+}
+
+function printDependencyInjectionError(token: any, options: {token: any; index: number; deps: any[]; message: string}) {
+  let erroredArg = "";
+
+  const args = getConstructorArgNames(token)
+    .map((arg, index) => {
+      if (options.index === index) {
+        erroredArg = arg;
+        arg = colors.red(arg);
+      }
+
+      return `${arg}: ${nameOf(options.deps[index])}`;
+    })
+    .join(", ");
+
+  const signature = nameOf(token) + "->constructor(" + args + ")";
+  const indexOf = signature.indexOf(erroredArg) - 5;
+  const drawline = (indexOf: number) => " ".repeat(indexOf) + colors.red("^" + "‾".repeat(erroredArg.length - 1));
+
+  return "Unable to inject dependency. " + options.message + "\n\n" + signature + "\n" + (indexOf > -1 ? drawline(indexOf) : "");
+}

package/src/common/errors/InvalidPropertyTokenError.ts

@@ -0,0 +1,13 @@
+import {classOf, nameOf} from "@tsed/core";
+
+export class InvalidPropertyTokenError extends Error {
+  name = "INVALID_TOKEN_ERROR";
+
+  constructor(target: any, propertyKey: string) {
+    super(
+      `Object isn't a valid token. Please check the token set on ${nameOf(
+        classOf(target)
+      )}.${propertyKey}.\n- Check that it is not a circular reference.\n- Check that the token (class or symbol) exists`
+    );
+  }
+}

package/src/common/fn/configuration.spec.ts

@@ -0,0 +1,42 @@
+import {Store} from "@tsed/core";
+import {beforeEach} from "vitest";
+
+import {DITest} from "../../node/index.js";
+import {Configuration} from "../decorators/configuration.js";
+import {Injectable} from "../decorators/injectable.js";
+import {Provider} from "../domain/Provider.js";
+import {configuration} from "./configuration.js";
+import {inject} from "./inject.js";
+import {injector} from "./injector.js";
+
+@Injectable()
+class Test {
+  public config = configuration();
+}
+
+describe("configuration()", () => {
+  beforeEach(() =>
+    DITest.create({
+      feature: "feature"
+    })
+  );
+  afterEach(() => DITest.reset());
+
+  it("should inject configuration", async () => {
+    const instance = inject(Test);
+
+    expect(instance.config).toEqual(injector().settings);
+    expect(instance.config.get("feature")).toEqual("feature");
+  });
+
+  it("should declare a new provider with custom configuration", () => {
+    @Configuration({})
+    class Test {}
+
+    const provider = new Provider(Test);
+    provider.injectable = false;
+    provider.configuration = {};
+
+    expect(Store.from(Test).get("configuration")).toEqual({});
+  });
+});

package/src/common/fn/configuration.ts

@@ -0,0 +1,22 @@
+import {Store} from "@tsed/core";
+
+import type {TokenProvider} from "../interfaces/TokenProvider.js";
+import {DIConfiguration} from "../services/DIConfiguration.js";
+import {injector} from "./injector.js";
+
+export function configuration(): TsED.DIConfiguration & DIConfiguration;
+export function configuration(token: TokenProvider): Partial<TsED.Configuration>;
+export function configuration(token: TokenProvider, configuration: Partial<TsED.Configuration>): Partial<TsED.Configuration>;
+export function configuration(token?: TokenProvider, configuration?: Partial<TsED.Configuration>) {
+  if (token) {
+    const store = Store.from(token);
+
+    if (configuration) {
+      store.set("configuration", configuration);
+    }
+
+    return store.get("configuration", configuration);
+  }
+
+  return injector().settings as TsED.DIConfiguration & DIConfiguration;
+}

package/src/common/fn/constant.spec.ts

@@ -0,0 +1,37 @@
+import {DITest} from "../../node/index.js";
+import {constant} from "../fn/constant.js";
+
+describe("constant()", () => {
+  beforeEach(() =>
+    DITest.create({
+      logger: {
+        level: "off"
+      }
+    })
+  );
+  afterEach(() => DITest.reset());
+  it("should inject constant to the property", async () => {
+    // WHEN
+    class Test {
+      test: string = constant("logger.level", "default value");
+    }
+
+    // THEN
+
+    const test = await DITest.invoke<Test>(Test);
+
+    expect(test.test).toEqual("off");
+  });
+  it("should return the default value if expression is undefined", async () => {
+    // WHEN
+    class Test {
+      test: string = constant("logger.test", "default value");
+    }
+
+    // THEN
+
+    const test = await DITest.invoke<Test>(Test);
+
+    expect(test.test).toEqual("default value");
+  });
+});

package/src/common/fn/constant.ts

@@ -0,0 +1,7 @@
+import {injector} from "./injector.js";
+
+export function constant<Type>(expression: string): Type | undefined;
+export function constant<Type>(expression: string, defaultValue: Type | undefined): Type;
+export function constant<Type>(expression: string, defaultValue?: Type | undefined): Type | undefined {
+  return injector().settings.get(expression, defaultValue);
+}

package/src/common/fn/inject.spec.ts

@@ -0,0 +1,54 @@
+import {DITest} from "../../node/index.js";
+import {Injectable} from "../decorators/injectable.js";
+import {InjectorService} from "../services/InjectorService.js";
+import {inject} from "./inject.js";
+
+@Injectable()
+class ProvidersList extends Map<string, string> {}
+
+@Injectable()
+class MyService {
+  readonly providersList = inject(ProvidersList);
+
+  getValue() {
+    return this.providersList.get("key");
+  }
+}
+
+describe("inject()", () => {
+  beforeEach(() => DITest.create());
+  afterEach(() => DITest.reset());
+
+  it("should inject the expected provider", async () => {
+    class Nested {}
+
+    class Test {
+      readonly injector = inject(InjectorService);
+      readonly nested = inject(Nested);
+
+      constructor() {
+        expect(this.injector).toBeInstanceOf(InjectorService);
+        expect(this.nested).not.toBeInstanceOf(Nested);
+      }
+    }
+
+    await DITest.invoke(Test, [
+      {
+        token: Nested,
+        use: {}
+      }
+    ]);
+  });
+  it("should rebuild all dependencies using invoke", async () => {
+    const providersList = inject(ProvidersList);
+    const myService = inject(MyService);
+    providersList.set("key", "value");
+
+    expect(inject(ProvidersList).get("key")).toEqual("value");
+    expect(myService.getValue()).toEqual("value");
+
+    const newMyService = await DITest.invoke(MyService, []);
+    expect(newMyService.getValue()).toEqual(undefined);
+    expect(myService.getValue()).toEqual("value");
+  });
+});

package/src/common/fn/inject.ts

@@ -0,0 +1,29 @@
+import type {InvokeOptions} from "../interfaces/InvokeOptions.js";
+import type {TokenProvider} from "../interfaces/TokenProvider.js";
+import {injector} from "./injector.js";
+import {invokeOptions, localsContainer} from "./localsContainer.js";
+
+/**
+ * Inject a provider to another provider.
+ *
+ * Use this function to inject a custom provider on constructor parameter or property.
+ *
+ * ```typescript
+ * @Injectable()
+ * export class MyService {
+ *   connection = inject(CONNECTION);
+ * }
+ * ```
+ *
+ * @param token A token provider or token provider group
+ * @param opts
+ * @returns {Function}
+ * @decorator
+ */
+export function inject<T>(token: TokenProvider<T>, opts?: Partial<Pick<InvokeOptions, "useOpts" | "rebuild" | "locals">>): T {
+  return injector().resolve(token, {
+    ...opts,
+    ...invokeOptions(),
+    locals: opts?.locals || localsContainer()
+  });
+}

package/src/common/fn/injectMany.ts

@@ -0,0 +1,16 @@
+import type {InvokeOptions} from "../interfaces/InvokeOptions.js";
+import {injector} from "./injector.js";
+import {localsContainer} from "./localsContainer.js";
+
+/**
+ * Injects multiple instances of a given token using the injector service.
+ * @param token - The injection token to resolve
+ * @param opts - Optional configuration for the injection
+ * @param opts.useOpts - Options for instance creation
+ * @param opts.rebuild - Whether to rebuild the instance
+ * @param opts.locals - Local container overrides
+ * @returns Array of resolved instances
+ */
+export function injectMany<T>(token: string | symbol, opts?: Partial<Pick<InvokeOptions, "useOpts" | "rebuild" | "locals">>): T[] {
+  return injector().getMany<T>(token, {...opts, locals: opts?.locals || localsContainer()} as InvokeOptions);
+}

package/src/common/fn/injectable.spec.ts

@@ -0,0 +1,87 @@
+import {Store} from "@tsed/core";
+
+import {DITest, logger} from "../../node/index.js";
+import {ProviderScope} from "../domain/ProviderScope.js";
+import {ProviderType} from "../domain/ProviderType.js";
+import {inject} from "./inject.js";
+import {controller, injectable, interceptor} from "./injectable.js";
+
+class Nested {
+  get() {
+    return "hello";
+  }
+}
+
+class MyClass {
+  nested = inject(Nested);
+  logger = logger();
+}
+
+class MyController {}
+
+injectable(Nested).scope(ProviderScope.SINGLETON).class(Nested);
+injectable(MyClass);
+
+describe("injectable", () => {
+  describe("injectable()", () => {
+    it("should define a singleton scope", async () => {
+      const instance = await DITest.invoke(MyClass);
+
+      expect(instance.nested).toBeInstanceOf(Nested);
+      expect(instance.nested.get()).toEqual("hello");
+    });
+    it("should define class with scope", async () => {
+      injectable(MyClass).scope(ProviderScope.SINGLETON).class(MyClass).store().set("test", "test");
+
+      expect(Store.from(MyClass).get("test")).toEqual("test");
+    });
+    it("should create a factory", async () => {
+      const builder = injectable(Symbol.for("Test")).factory(() => "test");
+      const provider = builder.inspect();
+
+      expect(provider.type).toEqual(ProviderType.PROVIDER);
+      expect(builder.token()).toEqual(Symbol.for("Test"));
+    });
+    it("should create an async factory", async () => {
+      const builder = injectable(Symbol.for("Test")).asyncFactory(() => Promise.resolve("test"));
+      const provider = builder.inspect();
+
+      expect(provider.type).toEqual(ProviderType.PROVIDER);
+      expect(builder.token()).toEqual(Symbol.for("Test"));
+    });
+    it("should create a value", async () => {
+      const builder = injectable(Symbol.for("Test")).value({
+        test: "test"
+      });
+      const provider = builder.inspect();
+
+      expect(provider.type).toEqual(ProviderType.VALUE);
+      expect(builder.token()).toEqual(Symbol.for("Test"));
+    });
+  });
+
+  describe("controller()", () => {
+    it("should define a singleton scope", async () => {
+      const builder = controller(MyController)
+        .path("/my-controller")
+        .scope(ProviderScope.REQUEST)
+        .middlewares({
+          use: [() => {}]
+        });
+
+      const provider = builder.inspect();
+
+      expect(provider.type).toEqual(ProviderType.CONTROLLER);
+      expect(provider.scope).toEqual(ProviderScope.REQUEST);
+    });
+  });
+
+  describe("interceptor()", () => {
+    it("should define a singleton scope", async () => {
+      const builder = interceptor(MyController);
+      const provider = builder.inspect();
+
+      expect(provider.type).toEqual(ProviderType.INTERCEPTOR);
+    });
+  });
+});

package/src/common/fn/injectable.ts

@@ -0,0 +1,15 @@
+import {ControllerProvider} from "../domain/ControllerProvider.js";
+import type {Provider} from "../domain/Provider.js";
+import {ProviderType} from "../domain/ProviderType.js";
+import {providerBuilder} from "../utils/providerBuilder.js";
+
+type PickedProps = "scope" | "path" | "alias" | "hooks" | "deps" | "imports" | "configuration" | "priority";
+
+const Props = ["type", "scope", "path", "alias", "hooks", "deps", "imports", "configuration", "priority"];
+export const injectable = providerBuilder<Provider, PickedProps | "type">(Props);
+export const interceptor = providerBuilder<Provider, PickedProps | "type">(Props, {
+  type: ProviderType.INTERCEPTOR
+});
+export const controller = providerBuilder<ControllerProvider, PickedProps | "children" | "middlewares">([...Props, "middlewares"], {
+  type: ProviderType.CONTROLLER
+});

package/src/common/fn/injector.ts

@@ -0,0 +1,26 @@
+import {InjectorService} from "../services/InjectorService.js";
+
+let globalInjector: InjectorService = new InjectorService();
+
+/**
+ * Return the existing injector service.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import {injector, Injectable} from "@tsed/di";
+ *
+ * @Injectable()
+ * class MyService {
+ *   injector = injector();
+ * }
+ * ```
+ */
+export function injector(): InjectorService {
+  return globalInjector;
+}
+
+export async function destroyInjector() {
+  await globalInjector.destroy();
+  globalInjector = new InjectorService();
+}

package/src/common/fn/lazyInject.spec.ts

@@ -0,0 +1,22 @@
+import {afterEach, beforeEach} from "vitest";
+
+import {DITest} from "../../node/index.js";
+import {lazyInject, optionalLazyInject} from "./lazyInject.js";
+
+describe("lazyInject", () => {
+  beforeEach(() => DITest.create());
+  afterEach(() => DITest.reset());
+
+  it("should lazy load module", async () => {
+    const service = await lazyInject(() => import("./__mock__/lazy.import.module.js"));
+
+    expect(service).toBeDefined();
+    expect(service.called).toBeTruthy();
+  });
+
+  it("should optionally lazy load module", async () => {
+    const service = await optionalLazyInject(() => import("./__mock__/lazy.import.module.js"));
+
+    expect(service).toBeDefined();
+  });
+});

package/src/common/fn/lazyInject.ts

@@ -0,0 +1,36 @@
+import {isFunction} from "@tsed/core";
+
+import type {TokenProvider} from "../interfaces/TokenProvider.js";
+import {inject} from "./inject.js";
+import {injector} from "./injector.js";
+
+/**
+ * Lazy load a provider from his package and invoke only when the provider is used.
+ */
+export async function lazyInject<Token>(factory: () => Promise<{default: TokenProvider<Token>}>): Promise<Token> {
+  const {default: token} = await factory();
+
+  if (!injector().has(token)) {
+    const instance = await inject(token);
+
+    const instanceWithHook = instance as unknown as {$onInit?: () => Promise<void>};
+
+    if ("$onInit" in instanceWithHook && isFunction(instanceWithHook.$onInit)) {
+      await instanceWithHook.$onInit();
+    }
+  }
+
+  return injector().get(token) as unknown as Promise<Token>;
+}
+
+export async function optionalLazyInject<Token>(
+  factory: () => Promise<{
+    default: TokenProvider;
+  }>
+): Promise<Token | undefined> {
+  try {
+    return await lazyInject(factory);
+  } catch (er) {
+    return undefined;
+  }
+}

package/src/common/fn/localsContainer.ts

@@ -0,0 +1,55 @@
+import {LocalsContainer} from "../domain/LocalsContainer.js";
+import type {UseImportTokenProviderOpts} from "../interfaces/ImportTokenProviderOpts.js";
+import {InjectorService} from "../services/InjectorService.js";
+import {injector} from "./injector.js";
+
+let globalLocals: LocalsContainer | undefined;
+let globalInvOpts: any = {};
+const stagedLocals: LocalsContainer[] = [];
+
+/**
+ * Get the locals container initiated by DITest or .bootstrap() method.
+ */
+export function localsContainer({
+  providers,
+  rebuild
+}: {
+  providers?: UseImportTokenProviderOpts[];
+  rebuild?: boolean;
+} = {}) {
+  if (!globalLocals || providers) {
+    globalLocals = new LocalsContainer();
+
+    if (providers) {
+      providers.forEach((p) => {
+        globalLocals!.set(p.token, p.use);
+      });
+
+      globalLocals.set(InjectorService, injector());
+    }
+
+    if (rebuild) {
+      globalInvOpts.rebuild = rebuild;
+    }
+  }
+
+  return globalLocals;
+}
+
+export function invokeOptions() {
+  return {...globalInvOpts};
+}
+
+/**
+ * Reset the locals container.
+ */
+export function detachLocalsContainer() {
+  globalLocals && stagedLocals.push(globalLocals);
+  globalLocals = undefined;
+  globalInvOpts = {};
+}
+
+export function cleanAllLocalsContainer() {
+  detachLocalsContainer();
+  stagedLocals.map((item) => item.clear());
+}

package/src/common/fn/refValue.spec.ts

@@ -0,0 +1,47 @@
+import {DITest} from "../../node/index.js";
+import {configuration} from "./configuration.js";
+import {refValue} from "./refValue.js";
+
+describe("refValue()", () => {
+  beforeEach(() =>
+    DITest.create({
+      logger: {
+        level: "off"
+      }
+    })
+  );
+  afterEach(() => DITest.reset());
+  describe("when decorator is used as property decorator", () => {
+    it("should create a getter", async () => {
+      // WHEN
+      class Test {
+        test = refValue("logger.level", "default value");
+      }
+
+      // THEN
+
+      const test = await DITest.invoke<Test>(Test);
+
+      expect(test.test.value).toEqual("off");
+
+      test.test.value = "test";
+
+      expect(test.test.value).toEqual("test");
+    });
+    it("should create a getter with default value", async () => {
+      expect(configuration().get("logger.test")).toEqual(undefined);
+
+      // WHEN
+      class Test {
+        test = refValue("logger.test", "default value");
+      }
+
+      // THEN
+
+      const test = await DITest.invoke<Test>(Test);
+
+      expect(test.test.value).toEqual("default value");
+      expect(configuration().get("logger.test")).toEqual(undefined);
+    });
+  });
+});

package/src/common/fn/refValue.ts

@@ -0,0 +1,33 @@
+import {injector} from "./injector.js";
+
+/**
+ * Get a value from the `injector.settings`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import {refValue, Injectable} from "@tsed/di";
+ *
+ * @Injectable()
+ * class Test {
+ *   test = refValue("logger.level", "default value");
+ *
+ *   constructor() {
+ *     console.log(this.test.value); // "off"
+ *   }
+ * }
+ *
+ * @param expression The expression to get the value from the `injector.settings`.
+ */
+export function refValue<Type>(expression: string): {value: Type | undefined};
+export function refValue<Type>(expression: string, defaultValue: Type | undefined): {value: Type};
+export function refValue<Type>(expression: string, defaultValue?: Type | undefined): {value: Type | undefined} {
+  return Object.freeze({
+    get value() {
+      return injector().settings.get(expression, defaultValue);
+    },
+    set value(value: Type) {
+      injector().settings.set(expression, value);
+    }
+  });
+}