@tsed/di 6.88.0 → 6.91.0

package/lib/types/domain/LocalsContainer.d.ts

@@ -0,0 +1,25 @@
+import type { TokenProvider } from "../interfaces/TokenProvider";
+export declare class LocalsContainer<V = any> extends Map<TokenProvider, V> {
+    /**
+     * Emit an event to all service. See service [lifecycle hooks](/docs/services.md#lifecycle-hooks).
+     * @param eventName The event name to emit at all services.
+     * @param args List of the parameters to give to each services.
+     * @returns {Promise<any[]>} A list of promises.
+     */
+    emit(eventName: string, ...args: any[]): Promise<void>;
+    /**
+     * @param eventName
+     * @param value
+     * @param args
+     */
+    alter<T = any>(eventName: string, value: any, ...args: any[]): T;
+    /**
+     * @param eventName
+     * @param value
+     * @param args
+     */
+    alterAsync<T = any>(eventName: string, value: any, ...args: any[]): Promise<T>;
+    toArray(): V[];
+    destroy(): Promise<void>;
+    protected getListeners(event: string): any[];
+}

package/lib/types/domain/Provider.d.ts

@@ -0,0 +1,68 @@
+import { Store, Type } from "@tsed/core";
+import { IProvider, TokenProvider } from "../interfaces";
+import { ProviderScope } from "./ProviderScope";
+import { ProviderType } from "./ProviderType";
+export declare class Provider<T = any> implements IProvider<T> {
+    type: ProviderType | any;
+    /**
+     * @deprecated Use injector.get(provider.token) instead.
+     */
+    instance: T;
+    deps: TokenProvider[];
+    imports: any[];
+    useFactory: Function;
+    useAsyncFactory: Function;
+    useValue: any;
+    private _useClass;
+    private _provide;
+    private _store;
+    private _tokenStore;
+    [key: string]: any;
+    constructor(token: TokenProvider, options?: Partial<Provider>);
+    get token(): any;
+    get provide(): TokenProvider;
+    set provide(value: TokenProvider);
+    get useClass(): Type<T>;
+    /**
+     * Create a new store if the given value is a class. Otherwise the value is ignored.
+     * @param value
+     */
+    set useClass(value: Type<T>);
+    get className(): string;
+    get name(): string;
+    get store(): Store;
+    get path(): string;
+    set path(path: string);
+    /**
+     * Get the scope of the provider.
+     *
+     * ::: tip Note
+     * Async provider is always a SINGLETON
+     * :::
+     *
+     * @returns {boolean}
+     */
+    get scope(): ProviderScope;
+    /**
+     * Change the scope value of the provider.
+     * @param scope
+     */
+    set scope(scope: ProviderScope);
+    get configuration(): Partial<TsED.Configuration>;
+    set configuration(configuration: Partial<TsED.Configuration>);
+    get children(): TokenProvider[];
+    get(key: string): any;
+    isAsync(): boolean;
+    clone(): Provider;
+    /**
+     *
+     * @returns {boolean}
+     */
+    hasChildren(): boolean;
+    /**
+     *
+     * @returns {boolean}
+     */
+    hasParent(): boolean;
+    toString(): string;
+}

package/lib/types/domain/ProviderScope.d.ts

@@ -0,0 +1,5 @@
+export declare enum ProviderScope {
+    SINGLETON = "singleton",
+    REQUEST = "request",
+    INSTANCE = "instance"
+}

package/lib/types/domain/ProviderType.d.ts

@@ -0,0 +1,10 @@
+export declare enum ProviderType {
+    VALUE = "value",
+    FACTORY = "factory",
+    SERVICE = "service",
+    PROVIDER = "provider",
+    MODULE = "module",
+    CONTROLLER = "controller",
+    INTERCEPTOR = "interceptor",
+    MIDDLEWARE = "middleware"
+}

package/lib/types/domain/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./Container";
+export * from "./InjectablePropertyType";
+export * from "./LocalsContainer";
+export * from "./Provider";
+export * from "./ProviderScope";
+export * from "./ProviderType";
+export * from "./ContextLogger";
+export * from "./DIContext";

package/lib/types/errors/InjectionError.d.ts

@@ -0,0 +1,8 @@
+import { TokenProvider } from "../interfaces";
+export declare class InjectionError extends Error {
+    name: string;
+    tokens: TokenProvider[];
+    origin: any;
+    constructor(token: TokenProvider, origin?: any);
+    static throwInjectorError(token: any, currentDependency: any, error: any): void;
+}

package/lib/types/errors/UndefinedTokenError.d.ts

@@ -0,0 +1,4 @@
+export declare class UndefinedTokenError extends Error {
+    name: string;
+    constructor();
+}

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./constants/index";
+export * from "./domain";
+export * from "./interfaces";
+export * from "./decorators";
+export * from "./registries/ProviderRegistry";
+export * from "./registries/GlobalProviders";
+export * from "./services/InjectorService";
+export * from "./services/DILogger";
+export * from "./services/DIConfiguration";
+export * from "./services/DITest";
+export * from "./errors/InjectionError";
+export * from "./errors/UndefinedTokenError";
+export * from "./utils/createContainer";
+export * from "./utils/getConfiguration";
+export * from "./utils/getConfiguration";
+export * from "./utils/setLoggerLevel";
+export * from "./utils/colors";

package/lib/types/interfaces/DIConfigurationOptions.d.ts

@@ -0,0 +1,25 @@
+import type { DIResolver } from "./DIResolver";
+import type { ProviderScope } from "../domain/ProviderScope";
+import type { TokenProvider } from "./TokenProvider";
+declare global {
+    namespace TsED {
+        interface Context {
+        }
+        interface Configuration {
+            scopes: {
+                [key: string]: ProviderScope;
+            };
+            /**
+             * Define a list of resolvers (it can be an external DI).
+             */
+            resolvers: DIResolver[];
+            /**
+             * Define dependencies to build the provider
+             */
+            imports: TokenProvider[];
+            [key: string]: any;
+        }
+    }
+}
+export interface DIConfigurationOptions extends TsED.Configuration {
+}

package/lib/types/interfaces/DILogger.d.ts

@@ -0,0 +1,8 @@
+export interface DILogger {
+    info(...args: any[]): void | any;
+    warn(...args: any[]): void | any;
+    debug(...args: any[]): void | any;
+    error(...args: any[]): void | any;
+    trace(...args: any[]): void | any;
+    [key: string]: any;
+}

package/lib/types/interfaces/DIResolver.d.ts

@@ -0,0 +1,5 @@
+import type { TokenProvider } from "./TokenProvider";
+export interface DIResolver {
+    deps?: TokenProvider[];
+    get<T = any>(type: TokenProvider, options: any): T | undefined;
+}

package/lib/types/interfaces/IProvider.d.ts

@@ -0,0 +1,54 @@
+import type { Type } from "@tsed/core";
+import type { DIResolver } from "./DIResolver";
+import type { ProviderScope } from "../domain/ProviderScope";
+import type { ProviderType } from "../domain/ProviderType";
+import type { TokenProvider } from "./TokenProvider";
+/**
+ *
+ */
+export interface IProvider<T = any> {
+    /**
+     * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
+     */
+    provide: TokenProvider;
+    /**
+     * Provider type
+     */
+    type?: ProviderType | string;
+    /**
+     * Instance build by the injector
+     */
+    instance?: T;
+    /**
+     * Define dependencies to build the provider
+     */
+    deps?: TokenProvider[];
+    /**
+     * Class to instantiate for the `token`.
+     */
+    useClass?: Type<T>;
+    /**
+     * Provide a function to build the provider
+     */
+    useFactory?: Function;
+    /**
+     * Provide an async function to build the provider
+     */
+    useAsyncFactory?: Function;
+    /**
+     * Provide predefined value
+     */
+    useValue?: any;
+    /**
+     * Scope used by the injector to build the provider.
+     */
+    scope?: ProviderScope;
+    /**
+     * A list of resolvers which will be used to resolve missing Symbol/Class when injector invoke a Class. This property allow external DI usage.
+     */
+    resolvers?: DIResolver[];
+    /**
+     *
+     */
+    [key: string]: any;
+}

package/lib/types/interfaces/InjectableProperties.d.ts

@@ -0,0 +1,24 @@
+import type { InjectablePropertyType } from "../domain/InjectablePropertyType";
+import type { TokenProvider } from "./TokenProvider";
+import type { InjectorService } from "../services/InjectorService";
+import type { InvokeOptions } from "./InvokeOptions";
+export interface InjectableProperty {
+    propertyKey: string;
+}
+export interface InjectablePropertyOptions extends InjectableProperty {
+    bindingType: InjectablePropertyType.METHOD | InjectablePropertyType.PROPERTY | InjectablePropertyType.INTERCEPTOR;
+    propertyType: string;
+    useType?: TokenProvider;
+    resolver: (injector: InjectorService, locals: Map<TokenProvider, any>, options: Partial<InvokeOptions> & {
+        options: any;
+    }) => () => any;
+    options?: any;
+}
+export interface InjectablePropertyValue extends InjectableProperty {
+    bindingType: InjectablePropertyType.CONSTANT | InjectablePropertyType.VALUE;
+    expression: string;
+    defaultValue?: any;
+}
+export interface InjectableProperties {
+    [key: string]: InjectablePropertyOptions | InjectablePropertyValue;
+}

package/lib/types/interfaces/InterceptorContext.d.ts

@@ -0,0 +1,11 @@
+import type { Type } from "@tsed/core";
+export interface InterceptorNext {
+    <T>(err?: Error): T;
+}
+export interface InterceptorContext<Klass = Type, Opts = any> {
+    target: Klass;
+    propertyKey: string;
+    args: any[];
+    next: InterceptorNext;
+    options?: Opts;
+}

package/lib/types/interfaces/InterceptorMethods.d.ts

@@ -0,0 +1,4 @@
+import type { InterceptorContext, InterceptorNext } from "./InterceptorContext";
+export interface InterceptorMethods {
+    intercept?(context: InterceptorContext, next?: InterceptorNext): any;
+}

package/lib/types/interfaces/InvokeOptions.d.ts

@@ -0,0 +1,10 @@
+import { ProviderScope } from "../domain/ProviderScope";
+import { TokenProvider } from "./TokenProvider";
+export interface InvokeOptions<T = any> {
+    deps: any[];
+    imports: any[];
+    parent?: TokenProvider;
+    scope: ProviderScope;
+    useScope: boolean;
+    rebuild?: boolean;
+}

package/lib/types/interfaces/OnDestroy.d.ts

@@ -0,0 +1,3 @@
+export interface OnDestroy {
+    $onDestroy(): Promise<any> | void;
+}

package/lib/types/interfaces/OnInit.d.ts

@@ -0,0 +1,3 @@
+export interface OnInit {
+    $onInit(): Promise<any> | void;
+}

package/lib/types/interfaces/RegistrySettings.d.ts

@@ -0,0 +1,20 @@
+import { Type } from "@tsed/core";
+import type { Provider } from "../domain";
+import type { InjectorService } from "../services/InjectorService";
+import type { ResolvedInvokeOptions } from "./ResolvedInvokeOptions";
+/**
+ * @ignore
+ */
+export interface RegistrySettings {
+    injectable?: boolean;
+    model?: Type<Provider>;
+    /**
+     *
+     * @param provider
+     * @param {Map<string | Function, any>} locals
+     * @param options
+     */
+    onInvoke?(provider: Provider, locals: Map<string | Function, any>, options: ResolvedInvokeOptions & {
+        injector: InjectorService;
+    }): void;
+}

package/lib/types/interfaces/ResolvedInvokeOptions.d.ts

@@ -0,0 +1,12 @@
+import type { Provider } from "../domain/Provider";
+import type { ProviderScope } from "../domain/ProviderScope";
+import type { TokenProvider } from "./TokenProvider";
+export interface ResolvedInvokeOptions {
+    token: TokenProvider;
+    parent?: TokenProvider;
+    scope: ProviderScope;
+    deps: TokenProvider[];
+    imports: TokenProvider[];
+    provider: Provider;
+    construct(deps: TokenProvider[]): any;
+}

package/lib/types/interfaces/TokenProvider.d.ts

@@ -0,0 +1,2 @@
+import type { Type } from "@tsed/core";
+export declare type TokenProvider = string | symbol | Type | Function | any;

package/lib/types/interfaces/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./DILogger";
+export * from "./DIConfigurationOptions";
+export * from "./DIResolver";
+export * from "./InjectableProperties";
+export * from "./InterceptorMethods";
+export * from "./InterceptorContext";
+export * from "./InvokeOptions";
+export * from "./IProvider";
+export * from "./OnInit";
+export * from "./OnDestroy";
+export * from "./OnInit";
+export * from "./RegistrySettings";
+export * from "./TokenProvider";
+export * from "./ResolvedInvokeOptions";

package/lib/types/registries/GlobalProviders.d.ts

@@ -0,0 +1,55 @@
+import { Type } from "@tsed/core";
+import { Provider } from "../domain/Provider";
+import type { IProvider, RegistrySettings, TokenProvider } from "../interfaces";
+import type { InjectorService } from "../services/InjectorService";
+import { ResolvedInvokeOptions } from "../interfaces/ResolvedInvokeOptions";
+export declare class GlobalProviderRegistry extends Map<TokenProvider, Provider> {
+    #private;
+    /**
+     * The get() method returns a specified element from a Map object.
+     * @param key Required. The key of the element to return from the Map object.
+     * @returns {T} Returns the element associated with the specified key or undefined if the key can't be found in the Map object.
+     */
+    get(key: TokenProvider): Provider | undefined;
+    /**
+     * The has() method returns a boolean indicating whether an element with the specified key exists or not.
+     * @param key
+     * @returns {boolean}
+     */
+    has(key: TokenProvider): boolean;
+    /**
+     * The set() method adds or updates an element with a specified key and value to a Map object.
+     * @param key Required. The key of the element to add to the Map object.
+     * @param metadata Required. The value of the element to add to the Map object.
+     */
+    set(key: TokenProvider, metadata: Provider): this;
+    /**
+     *
+     * @param target
+     * @param options
+     */
+    merge(target: TokenProvider, options: Partial<IProvider>): void;
+    /**
+     * The delete() method removes the specified element from a Map object.
+     * @param key Required. The key of the element to remove from the Map object.
+     * @returns {boolean} Returns true if an element in the Map object existed and has been removed, or false if the element does not exist.
+     */
+    delete(key: TokenProvider): boolean;
+    createRegistry(type: string, model: Type<Provider>, options?: Partial<RegistrySettings>): this;
+    onInvoke(provider: Provider, locals: Map<TokenProvider, any>, options: ResolvedInvokeOptions & {
+        injector: InjectorService;
+    }): void;
+    getRegistrySettings(target: string | TokenProvider): RegistrySettings;
+    createRegisterFn(type: string): (provider: any | IProvider, instance?: any) => void;
+    /**
+     *
+     * @param key
+     * @param options
+     */
+    protected createIfNotExists(key: TokenProvider, options: Partial<IProvider>): Provider;
+}
+/**
+ *
+ * @type {GlobalProviders}
+ */
+export declare const GlobalProviders: GlobalProviderRegistry;

package/lib/types/registries/ProviderRegistry.d.ts

@@ -0,0 +1,121 @@
+import type { IProvider } from "../interfaces";
+/**
+ * Register a provider configuration.
+ * @param {IProvider<any>} provider
+ */
+export declare function registerProvider(provider: Partial<IProvider>): void;
+/**
+ * Add a new factory in the `ProviderRegistry`.
+ *
+ * #### Example with symbol definition
+ *
+ *
+ * ```typescript
+ * import {registerFactory, InjectorService} from "@tsed/di";
+ *
+ * export interface IMyFooFactory {
+ *    getFoo(): string;
+ * }
+ *
+ * export type MyFooFactory = IMyFooFactory;
+ * export const MyFooFactory = Symbol("MyFooFactory");
+ *
+ * registerFactory(MyFooFactory, {
+ *      getFoo:  () => "test"
+ * });
+ *
+ * // or
+ *
+ * registerFactory({provide: MyFooFactory, instance: {
+ *      getFoo:  () => "test"
+ * }});
+ *
+ * @Service()
+ * export class OtherService {
+ *      constructor(@Inject(MyFooFactory) myFooFactory: MyFooFactory){
+ *          console.log(myFooFactory.getFoo()); /// "test"
+ *      }
+ * }
+ * ```
+ *
+ * > Note: When you use the factory method with Symbol definition, you must use the `@Inject()`
+ * decorator to retrieve your factory in another Service. Advice: By convention all factory class name will be prefixed by
+ * `Factory`.
+ *
+ * #### Example with class
+ *
+ * ```typescript
+ * import {InjectorService, registerFactory} from "@tsed/di";
+ *
+ * export class MyFooService {
+ *  constructor(){}
+ *      getFoo() {
+ *          return "test";
+ *      }
+ * }
+ *
+ * registerFactory(MyFooService, new MyFooService());
+ * // or
+ * registerFactory({provider: MyFooService, instance: new MyFooService()});
+ *
+ * @Service()
+ * export class OtherService {
+ *      constructor(myFooService: MyFooService){
+ *          console.log(myFooFactory.getFoo()); /// "test"
+ *      }
+ * }
+ * ```
+ * @deprecated Since 2021-05-15. Use registerProvider instead.
+ */
+export declare const registerFactory: typeof registerProvider;
+/**
+ * Add a new value in the `ProviderRegistry`.
+ *
+ * #### Example with symbol definition
+ *
+ *
+ * ```typescript
+ * import {registerValue, InjectorService} from "@tsed/di";
+ *
+ * const MyValue = Symbol.from("MyValue")
+ *
+ * registerValue({token: MyValue, useValue: "myValue"});
+ *
+ * @Service()
+ * export class OtherService {
+ *      constructor(@Inject(MyValue) myValue: string){
+ *          console.log(myValue); /// "myValue"
+ *      }
+ * }
+ * ```
+ */
+export declare const registerValue: (provider: any | IProvider<any>, value?: any) => void;
+/**
+ * Add a new controller in the `ProviderRegistry`. This controller will be built when `InjectorService` will be loaded.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * import {registerController, InjectorService} from "@tsed/di";
+ *
+ * export default class MyController {
+ *     constructor(){}
+ *     transform() {
+ *         return "test";
+ *     }
+ * }
+ *
+ * registerController({provide: MyController});
+ * // or
+ * registerController(MyController);
+ *
+ * const injector = new InjectorService();
+ * injector.load();
+ *
+ * const myController = injector.get<MyController>(MyController);
+ * myController.getFoo(); // test
+ * ```
+ *
+ * @param provider Provider configuration.
+ */
+export declare const registerController: (provider: any, instance?: any) => void;

package/lib/types/services/DIConfiguration.d.ts

@@ -0,0 +1,47 @@
+import { ProviderScope } from "../domain";
+import type { DIResolver, TokenProvider } from "../interfaces";
+export declare class DIConfiguration {
+    readonly default: Map<string, any>;
+    protected map: Map<string, any>;
+    [key: string]: any;
+    constructor(initialProps?: {});
+    get scopes(): {
+        [key: string]: ProviderScope;
+    };
+    set scopes(value: {
+        [key: string]: ProviderScope;
+    });
+    get resolvers(): DIResolver[];
+    set resolvers(resolvers: DIResolver[]);
+    get imports(): TokenProvider[];
+    set imports(imports: TokenProvider[]);
+    /**
+     *
+     * @param callbackfn
+     * @param thisArg
+     */
+    forEach(callbackfn: (value: any, index: string, map: Map<string, any>) => void, thisArg?: any): void;
+    /**
+     *
+     * @param propertyKey
+     * @param value
+     */
+    set(propertyKey: string | Partial<TsED.Configuration>, value?: any): this;
+    setRaw(propertyKey: string, value: any): this;
+    /**
+     *
+     * @param propertyKey
+     * @param defaultValue
+     * @returns {undefined|any}
+     */
+    get<T = any>(propertyKey: string, defaultValue?: T): T;
+    getRaw(propertyKey: string, defaultValue?: any): any;
+    merge(obj: Partial<TsED.Configuration>): void;
+    /**
+     *
+     * @param value
+     * @returns {any}
+     */
+    resolve(value: any): any;
+    build(): void;
+}

package/lib/types/services/DILogger.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/services/DITest.d.ts

@@ -0,0 +1,37 @@
+import { TokenProvider } from "../interfaces/TokenProvider";
+import { InjectorService } from "./InjectorService";
+export interface DITestInvokeOptions {
+    token?: TokenProvider;
+    use: any;
+}
+/**
+ * Tool to run test with lightweight DI sandbox.
+ */
+export declare class DITest {
+    protected static _injector: InjectorService | null;
+    static get injector(): InjectorService;
+    static set injector(injector: InjectorService);
+    static hasInjector(): boolean;
+    static create(settings?: Partial<TsED.Configuration>): Promise<void>;
+    /**
+     * Create a new injector with the right default services
+     */
+    static createInjector(settings?: any): InjectorService;
+    /**
+     * Resets the test injector of the test context, so it won't pollute your next test. Call this in your `tearDown` logic.
+     */
+    static reset(): Promise<void>;
+    /**
+     * Invoke a provider and return a fresh instance
+     * @param target
+     * @param providers
+     */
+    static invoke<T = any>(target: TokenProvider, providers?: DITestInvokeOptions[]): T | Promise<T>;
+    /**
+     * Return the instance from injector registry
+     * @param target
+     * @param options
+     */
+    static get<T = any>(target: TokenProvider, options?: any): T;
+    protected static configure(settings?: Partial<TsED.Configuration>): Partial<TsED.Configuration>;
+}