@tsed/di 8.0.0 → 8.0.2

package/src/common/decorators/interceptor.ts

@@ -0,0 +1,17 @@
+import {ProviderType} from "../domain/ProviderType.js";
+import {Injectable} from "./injectable.js";
+
+/**
+ * The decorators `@Interceptor()` declare a new service can be injected in other service or controller on there `constructor`.
+ * All services annotated with `@Interceptor()` are constructed one time.
+ *
+ * > `@Service()` use the `reflect-metadata` to collect and inject service on controllers or other services.
+ *
+ * @returns {Function}
+ * @decorator
+ */
+export function Interceptor(): Function {
+  return Injectable({
+    type: ProviderType.INTERCEPTOR
+  });
+}

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

@@ -0,0 +1,53 @@
+import {catchAsyncError, classOf, nameOf} from "@tsed/core";
+
+import {inject} from "../fn/inject.js";
+import {injector} from "../fn/injector.js";
+import type {MyLazyModule} from "./__mock__/lazy.module.js";
+import {Injectable} from "./injectable.js";
+import {LazyInject, OptionalLazyInject} from "./lazyInject.js";
+
+describe("LazyInject", () => {
+  it("should lazy load module (import)", async () => {
+    @Injectable()
+    class MyInjectable {
+      @LazyInject("MyLazyModule", () => import("./__mock__/lazy.import.module.js"))
+      lazy: Promise<MyLazyModule>;
+    }
+
+    const service = inject<MyInjectable>(MyInjectable);
+    const nbProviders = injector().getProviders().length;
+
+    const lazyService = await service.lazy;
+
+    expect(nameOf(classOf(lazyService))).toEqual("MyLazyModule");
+    expect(nbProviders).not.toEqual(injector().getProviders().length);
+  });
+
+  it("should throw an error when the module doesn't exists", async () => {
+    @Injectable()
+    class MyInjectable {
+      // @ts-ignore
+      @LazyInject("Lazy", () => import("lazy-module"), {})
+      lazy?: Promise<MyLazyModule>;
+    }
+
+    const service = inject<MyInjectable>(MyInjectable);
+    const error = await catchAsyncError(() => service.lazy);
+
+    expect(error?.message).toContain("Failed to load url lazy-module");
+  });
+
+  it("should lazy load optionally a module", async () => {
+    @Injectable()
+    class MyInjectable {
+      // @ts-ignore
+      @OptionalLazyInject("default", () => import("lazy-module-optional"))
+      lazy?: Promise<MyLazyModule>;
+    }
+
+    const service = inject(MyInjectable);
+    const lazyService = await service.lazy;
+
+    expect(lazyService).toEqual(undefined);
+  });
+});

package/src/common/decorators/lazyInject.ts

@@ -0,0 +1,91 @@
+import {catchError, isFunction} from "@tsed/core";
+
+import {lazyInject, optionalLazyInject} from "../fn/lazyInject.js";
+
+function mapOptions(args: any[], optional = false) {
+  function wrap(key: string, resolver: any) {
+    return async () => {
+      try {
+        const {[key]: token} = await resolver();
+
+        return {default: token};
+      } catch (er) {
+        if (!optional) {
+          throw er;
+        }
+
+        return;
+      }
+    };
+  }
+
+  if (isFunction(args[0])) {
+    return wrap("default", args[0]);
+  }
+
+  return wrap(args[0], args[1]);
+}
+
+/**
+ * Lazy load a provider from his package and invoke only when the provider is used
+ *
+ * ```typescript
+ * import type {PlatformException} from "@tsed/platform-exceptions";
+ *
+ * @Injectable()
+ * export class MyService {
+ *   @LazyInject(() => import("@tsed/platform-exceptions"))
+ *   exceptions: Promise<PlatformException>;
+ * }
+ * ```
+ *
+ * @param key - The named export to import from the module.
+ * @param resolver - A function that returns a promise resolving to the module.
+ * @returns {Function}
+ * @decorator
+ */
+export function LazyInject(resolver: () => Promise<{default: unknown}>): PropertyDecorator;
+export function LazyInject(key: string, resolver: () => Promise<{default: unknown}>): PropertyDecorator;
+export function LazyInject(...args: any[]): PropertyDecorator {
+  let resolver = mapOptions(args);
+
+  return (target: any, propertyKey: string | symbol): any | void => {
+    catchError(() => Reflect.deleteProperty(target, propertyKey));
+    Reflect.defineProperty(target, propertyKey, {
+      async get() {
+        return lazyInject<any>(resolver as any);
+      }
+    });
+  };
+}
+
+/**
+ * Optionally Lazy load a provider from his package and invoke only when the provider is used
+ *
+ * ```typescript
+ * import type {PlatformException} from "@tsed/platform-exceptions";
+ *
+ * @Injectable()
+ * export class MyService {
+ *   @OptionalLazyInject(() => import("@tsed/platform-exceptions"))
+ *   exceptions: Promise<PlatformException>;
+ * }
+ * ```
+ * @param key - The named export to import from the module.
+ * @param resolver - A function that returns a promise resolving to the module.
+ * @decorator
+ */
+export function OptionalLazyInject(resolver: () => Promise<{default: unknown}>): PropertyDecorator;
+export function OptionalLazyInject(key: string, resolver: () => Promise<{default: unknown}>): PropertyDecorator;
+export function OptionalLazyInject(...args: any[]): PropertyDecorator {
+  const resolver = mapOptions(args, true);
+
+  return (target: any, propertyKey: string | symbol): any | void => {
+    catchError(() => Reflect.deleteProperty(target, propertyKey));
+    Reflect.defineProperty(target, propertyKey, {
+      async get() {
+        return optionalLazyInject(resolver as any);
+      }
+    });
+  };
+}

package/src/common/decorators/module.ts

@@ -0,0 +1,52 @@
+import {useDecorators} from "@tsed/core";
+
+import {ProviderScope} from "../domain/ProviderScope.js";
+import {ProviderType} from "../domain/ProviderType.js";
+import {TokenProvider} from "../interfaces/TokenProvider.js";
+import {Configuration} from "./configuration.js";
+import {Injectable} from "./injectable.js";
+
+export interface ModuleOptions extends Omit<TsED.Configuration, "scopes"> {
+  /**
+   * Provider scope
+   */
+  scope?: ProviderScope;
+  /**
+   * Providers must be initialized before building this module
+   */
+  imports?: TokenProvider[];
+  /**
+   * Explicit token must be injected in the constructor
+   */
+  deps?: TokenProvider[];
+
+  /**
+   * Additional properties are stored as provider configuration.
+   */
+  [key: string]: any;
+}
+
+/**
+ * Declare a new Ts.ED module
+ *
+ * ## Options
+ * - imports: List of Provider which must be built by injector before invoking the module
+ * - deps: List of provider must be injected to the module constructor (explicit declaration)
+ *
+ * @param options
+ * @decorator
+ */
+export function Module(options: Partial<ModuleOptions> = {}) {
+  const {scopes, imports, deps, scope, ...configuration} = options;
+
+  return useDecorators(
+    Configuration(configuration),
+    Injectable({
+      type: ProviderType.MODULE,
+      scope: ProviderScope.SINGLETON,
+      imports,
+      deps,
+      injectable: false
+    })
+  );
+}

package/src/common/decorators/opts.ts

@@ -0,0 +1,51 @@
+import {classOf} from "@tsed/core";
+
+import {DI_USE_PARAM_OPTIONS} from "../constants/constants.js";
+import {ProviderScope} from "../domain/ProviderScope.js";
+import {Inject} from "./inject.js";
+import {Scope} from "./scope.js";
+
+/**
+ * Get instance options. This options depending on his invocation context.
+ *
+ * ```typescript
+ * import {Injectable, Opts, UseOpts} from "@tsed/di";
+ *
+ * @Injectable()
+ * class MyConfigurableService {
+ *   source: string;
+ *   constructor(@Opts options: any = {}) {
+ *      console.log("Hello ", options.source); // log: Hello Service1 then Hello Service2
+ *
+ *      this.source = options.source;
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class MyService1 {
+ *   constructor(@UseOpts({source: 'Service1'}) service: MyConfigurableService) {
+ *     console.log(service.source) // log: Service1
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class MyService2 {
+ *   constructor(@UseOpts({source: 'Service2'}) service: MyConfigurableService) {
+ *     console.log(service.source) // log: Service2
+ *   }
+ * }
+ * ```
+ *
+ * ::: warning
+ * Using @@Opts@@ decorator on a constructor parameter change the Scope of the provider to `ProviderScope.INSTANCE`.
+ * :::
+ *
+ * @param target
+ * @param propertyKey
+ * @param index
+ * @decorator
+ */
+export function Opts(target: any, propertyKey: string | symbol | undefined, index: number) {
+  Scope(ProviderScope.INSTANCE)(classOf(target));
+  Inject(DI_USE_PARAM_OPTIONS)(target, propertyKey, index);
+}

package/src/common/decorators/overrideProvider.spec.ts

@@ -0,0 +1,30 @@
+import {Provider} from "../domain/Provider.js";
+import type {TokenProvider} from "../interfaces/TokenProvider.js";
+import {GlobalProviders} from "../registries/GlobalProviders.js";
+import {OverrideProvider} from "./overrideProvider.js";
+
+describe("OverrideProvider", () => {
+  class Test {}
+
+  class Test2 {}
+
+  beforeAll(() => {
+    vi.spyOn(GlobalProviders, "get");
+  });
+  it("should use OverrideProvider", () => {
+    // GIVEN
+    const provider = new Provider(Test);
+
+    vi.mocked(GlobalProviders.get).mockImplementation((token: TokenProvider) => {
+      if (token === Test) {
+        return provider;
+      }
+    });
+    // WHEN
+    OverrideProvider(Test)(Test2);
+
+    // THEN
+    expect(provider.token).toEqual(Test);
+    expect(provider.useClass).toEqual(Test2);
+  });
+});

package/src/common/decorators/overrideProvider.ts

@@ -0,0 +1,15 @@
+import {Type} from "@tsed/core";
+
+import {GlobalProviders} from "../registries/GlobalProviders.js";
+
+/**
+ * Override a provider which is already registered in ProviderRegistry.
+ * @returns {Function}
+ * @decorators
+ * @param originalProvider
+ */
+export function OverrideProvider(originalProvider: Type<any>): Function {
+  return (target: Type<any>): void => {
+    GlobalProviders.get(originalProvider)!.useClass = target;
+  };
+}

package/src/common/decorators/scope.spec.ts

@@ -0,0 +1,25 @@
+import {Store} from "@tsed/core";
+
+import {Scope} from "./scope.js";
+
+class Test {}
+
+describe("Scope", () => {
+  describe("when parameters is given", () => {
+    it("should set metadata", () => {
+      Scope("request")(Test);
+
+      expect(Store.from(Test).get("scope")).toEqual("request");
+    });
+  });
+
+  describe("when parameters is not given", () => {
+    beforeAll(() => {});
+
+    it("should set metadata", () => {
+      Scope()(Test);
+
+      expect(Store.from(Test).get("scope")).toEqual("request");
+    });
+  });
+});

package/src/common/decorators/scope.ts

@@ -0,0 +1,13 @@
+import {StoreSet} from "@tsed/core";
+
+import {ProviderScope} from "../domain/ProviderScope.js";
+
+/**
+ *
+ * @param {"request" | "singleton" | ProviderScope} scope
+ * @returns {Function}
+ * @constructor
+ */
+export function Scope(scope: "request" | "singleton" | ProviderScope = ProviderScope.REQUEST) {
+  return StoreSet("scope", scope);
+}

package/src/common/decorators/service.ts

@@ -0,0 +1,14 @@
+import {Injectable} from "./injectable.js";
+
+/**
+ * The decorators `@Service()` declare a new service can be injected in other service or controller on there `constructor`.
+ * All services annotated with `@Service()` are constructed one time.
+ *
+ * > `@Service()` use the `reflect-metadata` to collect and inject service on controllers or other services.
+ *
+ * @returns {Function}
+ * @decorator
+ */
+export function Service(): Function {
+  return Injectable();
+}

package/src/common/decorators/useOpts.spec.ts

@@ -0,0 +1,90 @@
+import {descriptorOf} from "@tsed/core";
+
+import {DITest} from "../../node/index.js";
+import {ProviderScope} from "../domain/ProviderScope.js";
+import {Inject} from "./inject.js";
+import {Injectable} from "./injectable.js";
+import {Opts} from "./opts.js";
+import {Scope} from "./scope.js";
+import {UseOpts} from "./useOpts.js";
+
+describe("UseOpts", () => {
+  let testContext: any;
+
+  beforeEach(() => {
+    testContext = {};
+  });
+
+  beforeEach(() => DITest.create());
+  afterEach(() => DITest.reset());
+  it("should inject provider with options", async () => {
+    @Injectable()
+    class MyProvider {
+      source: any;
+
+      constructor(@Opts options: any = {}) {
+        testContext.source = options.source;
+        this.source = options.source;
+      }
+    }
+
+    @Injectable()
+    class MyService {
+      @Inject()
+      @UseOpts({
+        source: "test1"
+      })
+      service1: MyProvider;
+
+      constructor(@UseOpts({source: "test2"}) public service2: MyProvider) {}
+    }
+
+    const service = await DITest.invoke<MyService>(MyService);
+
+    expect(service.service2.source).toEqual("test2");
+    expect(service.service2).not.toEqual(service.service1);
+
+    expect(service.service1).toBeInstanceOf(MyProvider);
+    expect(service.service1.source).toEqual("test1");
+
+    expect(service.service2).toBeInstanceOf(MyProvider);
+  });
+  it("should invoke a service which use a configurable provider", async () => {
+    @Injectable()
+    class MyProvider {
+      source: any;
+
+      constructor(@Opts options: Partial<any> = {}) {
+        testContext.source = options.source;
+      }
+    }
+
+    @Injectable()
+    class MyService {
+      constructor(@UseOpts({source: "test2"}) public service2: MyProvider) {}
+    }
+
+    @Injectable()
+    @Scope(ProviderScope.SINGLETON)
+    class MyRepoService extends MyProvider {}
+
+    await DITest.invoke<MyRepoService>(MyRepoService);
+  });
+  it("should store metadata", () => {
+    // GIVEN
+    class Test {
+      test() {}
+    }
+
+    // WHEN
+    let actualError;
+    try {
+      UseOpts({})(Test, "test", descriptorOf(Test, "test"));
+    } catch (er) {
+      actualError = er;
+    }
+
+    // THEN
+    expect(actualError.message).toEqual("UseOpts cannot be used as method.static decorator on Test.test");
+  });
+});

package/src/common/decorators/useOpts.ts

@@ -0,0 +1,61 @@
+import {decoratorTypeOf, DecoratorTypes, Store, UnsupportedDecoratorType} from "@tsed/core";
+
+import {DI_USE_OPTIONS, DI_USE_PARAM_OPTIONS} from "../constants/constants.js";
+
+/**
+ * Add options to invoke the Service.
+ *
+ * ```typescript
+ * import {Injectable, Opts, UseOpts} from "@tsed/di";
+ *
+ * @Injectable()
+ * class MyConfigurableService {
+ *   source: string;
+ *   constructor(@Opts options: any = {}) {
+ *      console.log("Hello ", options.source); // log: Hello Service1 then Hello Service2
+ *
+ *      this.source = options.source;
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class MyService1 {
+ *   constructor(@UseOpts({source: 'Service1'}) service: MyConfigurableService) {
+ *     console.log(service.source) // log: Service1
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class MyService2 {
+ *   constructor(@UseOpts({source: 'Service2'}) service: MyConfigurableService) {
+ *     console.log(service.source) // log: Service2
+ *   }
+ * }
+ * ```
+ *
+ * ::: warning
+ * Using @@Opts@@ decorator on a constructor parameter change the Scope of the provider to `ProviderScope.INSTANCE`.
+ * :::
+ *
+ * @returns {Function}
+ * @decorator
+ * @param options
+ */
+export function UseOpts(options: {[key: string]: any}): Function {
+  return (target: Object, propertyKey: string | symbol, index?: number): any => {
+    const bindingType = decoratorTypeOf([target, propertyKey, index]);
+
+    switch (bindingType) {
+      case DecoratorTypes.PARAM_CTOR:
+        Store.from(target).merge(`${DI_USE_PARAM_OPTIONS}:${index}`, options);
+        break;
+
+      case DecoratorTypes.PROP:
+        Store.from(target, propertyKey).set(DI_USE_OPTIONS, options);
+        break;
+
+      default:
+        throw new UnsupportedDecoratorType(UseOpts, [target, propertyKey, index]);
+    }
+  };
+}

package/src/common/decorators/value.spec.ts

@@ -0,0 +1,59 @@
+import {DITest} from "../../node/index.js";
+import {configuration} from "../fn/configuration.js";
+import {Value} from "./value.js";
+
+describe("@Value()", () => {
+  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 {
+        @Value("logger.level", "default value")
+        test: string;
+      }
+
+      // THEN
+
+      const test = await DITest.invoke<Test>(Test);
+
+      expect(test.test).toEqual("off");
+    });
+    it("should create a getter with default value", async () => {
+      expect(configuration().get("logger.test")).toEqual(undefined);
+
+      // WHEN
+      class Test {
+        @Value("logger.test", "default value")
+        test: string;
+      }
+
+      // THEN
+
+      const test = await DITest.invoke<Test>(Test);
+
+      expect(test.test).toEqual("default value");
+      expect(configuration().get("logger.test")).toEqual(undefined);
+    });
+    it("should create a getter with native default value", async () => {
+      // WHEN
+      class Test {
+        @Value("logger.test")
+        test: string = "default prop";
+      }
+
+      // THEN
+
+      const test = await DITest.invoke<Test>(Test);
+
+      expect(test.test).toEqual("default prop");
+      expect(configuration().get("logger.test")).toEqual("default prop");
+    });
+  });
+});

package/src/common/decorators/value.ts

@@ -0,0 +1,60 @@
+import {catchError} from "@tsed/core";
+
+import {injector} from "../fn/injector.js";
+
+export function bindValue(target: any, propertyKey: string | symbol, expression: string, defaultValue?: any) {
+  const descriptor = {
+    get() {
+      return injector().settings.get(expression, defaultValue);
+    },
+    set(value: unknown) {
+      injector().settings.set(expression, value);
+    },
+    enumerable: true,
+    configurable: true
+  };
+
+  catchError(() => Reflect.deleteProperty(target, propertyKey));
+  catchError(() => Reflect.defineProperty(target, propertyKey, descriptor));
+}
+
+/**
+ * Return value from Configuration.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import {Env} from "@tsed/core";
+ * import {Constant, Value} from "@tsed/di";
+ *
+ * export class MyClass {
+ *
+ *    @Constant("env")
+ *    env: Env;
+ *
+ *    @Value("swagger.path")
+ *    swaggerPath: string;
+ *
+ *    @Value("swagger.path", "defaultValue")
+ *    swaggerPath: string;
+ *
+ *    constructor() {
+ *       console.log(this.swaggerPath) // undefined. Not available on constructor
+ *    }
+ *
+ *    $onInit() {
+ *      console.log(this.swaggerPath)  // something
+ *    }
+ * }
+ * ```
+ *
+ * @param expression
+ * @param defaultValue
+ * @returns {(targetClass: any, attributeName: string) => any}
+ * @decorator
+ */
+export function Value(expression: string, defaultValue?: unknown): PropertyDecorator {
+  return (target, propertyKey) => {
+    return bindValue(target, propertyKey, expression, defaultValue);
+  };
+}