@proto-kit/common 0.1.1-develop.211 → 0.1.1-develop.2137

package/src/config/ModuleContainer.ts

@@ -1,12 +1,34 @@
 import "reflect-metadata";
 
-import { container, Frequency, InjectionToken, Lifecycle } from "tsyringe";
+import {
+  DependencyContainer,
+  Frequency,
+  InjectionToken,
+  instanceCachingFactory,
+  isClassProvider,
+  isFactoryProvider,
+  isTokenProvider,
+  isValueProvider,
+  Lifecycle,
+} from "tsyringe";
 import log from "loglevel";
-
-import { StringKeyOf, TypedClass } from "../types";
-import { DependencyFactory } from "../dependencyFactory/DependencyFactory";
-
-import { Configurable, ConfigurableModule } from "./ConfigurableModule";
+import merge from "lodash/merge";
+
+import { MergeObjects, StringKeyOf, TypedClass } from "../types";
+import {
+  DependencyFactory,
+  InferDependencies,
+} from "../dependencyFactory/DependencyFactory";
+import { EventEmitterProxy } from "../events/EventEmitterProxy";
+
+import {
+  Configurable,
+  ConfigurableModule,
+  NoConfig,
+} from "./ConfigurableModule";
+import { ChildContainerProvider } from "./ChildContainerProvider";
+import { ChildContainerCreatable } from "./ChildContainerCreatable";
+import { getInjectAliases } from "./injectAlias";
 
 const errors = {
   configNotSetInContainer: (moduleName: string) =>
@@ -16,8 +38,7 @@ const errors = {
 
   onlyValidModuleNames: (moduleName: NonNullable<unknown>) =>
     new Error(
-      // eslint-disable-next-line max-len
-      // eslint-disable-next-line @typescript-eslint/no-base-to-string,@typescript-eslint/restrict-template-expressions
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
       `Only known module names are allowed, using unknown module name: ${moduleName}`
     ),
 
@@ -35,17 +56,31 @@ const errors = {
       attempting to inject a dependency that is not registered 
       as a runtime module for this chain: ${name}`
     ),
+
+  dependencyContainerNotSet: (className: string) =>
+    new Error(
+      `DependencyContainer not set. Be sure to only call DI-related function in create() and not inside the constructor. (${className})`
+    ),
+
+  validModuleInstance: (moduleName: string, moduleTypeName: string) =>
+    new Error(
+      `Incompatible module instance ("${moduleName}" not instanceof ${moduleTypeName})`
+    ),
 };
 
 export const ModuleContainerErrors = errors;
 
+export interface BaseModuleInstanceType
+  extends ChildContainerCreatable,
+    Configurable<unknown> {}
+
 // determines that a module should be configurable by default
-export type BaseModuleType = TypedClass<Configurable<unknown>>;
+export type BaseModuleType = TypedClass<BaseModuleInstanceType>;
 
 // allows to specify what kind of modules can be passed into a container
 export interface ModulesRecord<
   // use the default configurable module type
-  ModuleType extends BaseModuleType = BaseModuleType
+  ModuleType extends BaseModuleType = BaseModuleType,
 > {
   [name: string]: ModuleType;
 }
@@ -56,26 +91,58 @@ export type ModulesConfig<Modules extends ModulesRecord> = {
   [ConfigKey in StringKeyOf<Modules>]: InstanceType<
     Modules[ConfigKey]
   > extends Configurable<infer Config>
-    ? Config
+    ? Config extends NoConfig
+      ? Config | undefined
+      : Config
     : never;
 };
 
 /**
- * Parameters required when creating a module container instance
+ * This type make any config partial (i.e. optional) up to the first level
+ * So { Module: { a: { b: string } } }
+ * will become
+ * { Module?: { a?: { b: string } } }
+ * Note that b does not become optional, as we don't want nested objects to
+ * become unreasonably partialized (for example Field).
  */
-export interface ModuleContainerDefinition<Modules extends ModulesRecord> {
-  modules: Modules;
-  // config is optional, as it may be provided by the parent/wrapper class
-  config?: ModulesConfig<Modules>;
+export type RecursivePartial<T> = {
+  [Key in keyof T]?: Partial<T[Key]>;
+};
+
+// Removes all keys with a "never" value from an object
+export type FilterNeverValues<Type extends Record<string, unknown>> = {
+  [Key in keyof Type as Type[Key] extends never ? never : Key]: Type[Key];
+};
+
+export type DependenciesFromModules<Modules extends ModulesRecord> =
+  FilterNeverValues<{
+    [Key in keyof Modules]: Modules[Key] extends TypedClass<DependencyFactory>
+      ? InferDependencies<InstanceType<Modules[Key]>>
+      : never;
+  }>;
+
+export type ResolvableModules<Modules extends ModulesRecord> = MergeObjects<
+  DependenciesFromModules<Modules>
+> &
+  Modules;
+
+export interface ModuleContainerLike {
+  get dependencyContainer(): DependencyContainer;
+
+  resolveOrFail<ModuleType>(
+    moduleName: string,
+    moduleType: TypedClass<ModuleType>
+  ): ModuleType;
 }
 
 /**
  * Reusable module container facilitating registration, resolution
  * configuration, decoration and validation of modules
  */
-export class ModuleContainer<
-  Modules extends ModulesRecord
-> extends ConfigurableModule<unknown> {
+export class ModuleContainer<Modules extends ModulesRecord>
+  extends ConfigurableModule<ModulesConfig<Modules>>
+  implements ModuleContainerLike
+{
   /**
    * Determines how often are modules decorated upon resolution
    * from the tsyringe DI container
@@ -83,19 +150,19 @@ export class ModuleContainer<
   private static readonly moduleDecorationFrequency: Frequency = "Once";
 
   // DI container holding all the registered modules
-  protected readonly container = container.createChildContainer();
+  private providedContainer?: DependencyContainer = undefined;
 
-  public constructor(public definition: ModuleContainerDefinition<Modules>) {
+  private eventEmitterProxy: EventEmitterProxy<Modules> | undefined = undefined;
+
+  public constructor(public definition: Modules) {
     super();
-    // register all provided modules when the container is created
-    this.registerModules(definition.modules);
   }
 
   /**
    * @returns list of module names
    */
   public get moduleNames() {
-    return Object.keys(this.definition.modules);
+    return Object.keys(this.definition);
   }
 
   /**
@@ -127,27 +194,49 @@ export class ModuleContainer<
     });
   }
 
+  protected get container(): DependencyContainer {
+    this.assertContainerInitialized(this.providedContainer);
+    return this.providedContainer;
+  }
+
   /**
    * Assert that the iterated `moduleName` is of ModuleName type,
    * otherwise it may be just string e.g. when modules are iterated over
    * using e.g. a for loop.
    */
   public assertIsValidModuleName(
-    modules: Modules,
     moduleName: string
   ): asserts moduleName is StringKeyOf<Modules> {
-    this.isValidModuleName(modules, moduleName);
+    if (!this.isValidModuleName(this.definition, moduleName)) {
+      throw errors.onlyValidModuleNames(moduleName);
+    }
   }
 
   public isValidModuleName(
     modules: Modules,
     moduleName: number | string | symbol
-  ): asserts moduleName is StringKeyOf<Modules> {
-    if (!Object.prototype.hasOwnProperty.call(modules, moduleName)) {
-      throw errors.onlyValidModuleNames(moduleName);
+  ): moduleName is StringKeyOf<Modules> {
+    return Object.prototype.hasOwnProperty.call(modules, moduleName);
+  }
+
+  public assertContainerInitialized(
+    container: DependencyContainer | undefined
+  ): asserts container is DependencyContainer {
+    if (container === undefined) {
+      throw errors.dependencyContainerNotSet(this.constructor.name);
     }
   }
 
+  protected registerAliases(originalToken: string, clas: TypedClass<any>) {
+    const aliases = getInjectAliases(clas);
+
+    aliases.forEach((alias) =>
+      this.container.register(alias, {
+        useToken: originalToken,
+      })
+    );
+  }
+
   /**
    * Register modules into the current container, and registers
    * a respective resolution hook in order to decorate the module
@@ -156,39 +245,41 @@ export class ModuleContainer<
    * @param modules
    */
   protected registerModules(modules: Modules) {
-    for (const moduleName in modules) {
+    Object.keys(modules).forEach((moduleName) => {
       if (Object.prototype.hasOwnProperty.call(modules, moduleName)) {
-        this.assertIsValidModuleName(modules, moduleName);
+        this.assertIsValidModuleName(moduleName);
 
         log.debug(`Registering module: ${moduleName}`);
 
+        const useClass = modules[moduleName];
+
         this.container.register(
           moduleName,
-          { useClass: modules[moduleName] },
+          { useClass },
           { lifecycle: Lifecycle.ContainerScoped }
         );
         this.onAfterModuleResolution(moduleName);
+
+        this.registerAliases(moduleName, useClass);
+
+        if (this.isDependencyFactory(useClass)) {
+          this.useDependencyFactory(useClass);
+        }
       }
-    }
+    });
   }
 
-  /**
-   * Inject a set of dependencies using the given list of DependencyFactories
-   * This method should be called during startup
-   */
-  protected registerDependencyFactories(
-    factories: TypedClass<DependencyFactory>[]
-  ) {
-    factories.forEach((factory) => {
-      this.container.resolve(factory).initDependencies(this.container);
-    });
+  public get events(): EventEmitterProxy<Modules> {
+    if (this.eventEmitterProxy === undefined) {
+      this.eventEmitterProxy = new EventEmitterProxy<Modules>(this);
+    }
+    return this.eventEmitterProxy;
   }
 
   /**
    * Register a non-module value into the current container
    * @param modules
    */
-  // eslint-disable-next-line no-warning-comments
   // TODO Rename to plural since object is param
   public registerValue<Value>(modules: Record<string, Value>) {
     Object.entries(modules).forEach(([moduleName, useValue]) => {
@@ -205,7 +296,25 @@ export class ModuleContainer<
    * @param config
    */
   public configure(config: ModulesConfig<Modules>) {
-    this.definition.config = config;
+    this.config = config;
+  }
+
+  public configurePartial(config: RecursivePartial<ModulesConfig<Modules>>) {
+    this.config = merge<
+      ModulesConfig<Modules> | NoConfig,
+      RecursivePartial<ModulesConfig<Modules>>
+    >(this.currentConfig ?? {}, config);
+  }
+
+  public get config() {
+    return super.config;
+  }
+
+  public set config(config: ModulesConfig<Modules>) {
+    super.config = merge<
+      ModulesConfig<Modules> | NoConfig,
+      ModulesConfig<Modules>
+    >(this.currentConfig ?? {}, config);
   }
 
   /**
@@ -218,23 +327,30 @@ export class ModuleContainer<
    * @param moduleName
    * @returns
    */
-  public resolve<ResolvableModuleName extends StringKeyOf<Modules>>(
-    moduleName: ResolvableModuleName
-  ): InstanceType<Modules[ResolvableModuleName]> {
-    return this.container.resolve<InstanceType<Modules[ResolvableModuleName]>>(
-      moduleName
-    );
+  public resolve<KeyType extends StringKeyOf<ResolvableModules<Modules>>>(
+    moduleName: KeyType
+  ): InstanceType<ResolvableModules<Modules>[KeyType]> {
+    return this.container.resolve<
+      InstanceType<ResolvableModules<Modules>[KeyType]>
+    >(moduleName);
   }
 
   public resolveOrFail<ModuleType>(
     moduleName: string,
-    moduleType: TypedClass<ModuleType>
+    moduleType?: TypedClass<ModuleType>
   ) {
+    if (!this.container.isRegistered(moduleName)) {
+      throw new Error(`Dependency with token ${moduleName} not registered`);
+    }
+
     const instance = this.container.resolve<ModuleType>(moduleName);
-    const isValidModuleInstance = instance instanceof moduleType;
 
-    if (!isValidModuleInstance) {
-      throw new Error("Incompatible module instance");
+    if (moduleType !== undefined) {
+      const isValidModuleInstance = instance instanceof moduleType;
+
+      if (!isValidModuleInstance) {
+        throw errors.validModuleInstance(moduleName, moduleType.name);
+      }
     }
 
     return instance;
@@ -248,14 +364,96 @@ export class ModuleContainer<
     moduleName: StringKeyOf<Modules>,
     containedModule: InstanceType<Modules[StringKeyOf<Modules>]>
   ) {
-    const config = this.definition.config?.[moduleName];
-
+    const config = super.config?.[moduleName];
     // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (!config) {
       throw errors.configNotSetInContainer(moduleName.toString());
     }
 
-    containedModule.config = config;
+    if (containedModule instanceof ModuleContainer) {
+      containedModule.configure(config);
+    } else {
+      containedModule.config = config;
+    }
+  }
+
+  private isDependencyFactory(type: any): type is DependencyFactory {
+    return "dependencies" in type;
+  }
+
+  /**
+   * Inject a set of dependencies using the given list of DependencyFactories
+   * This method should be called during startup
+   */
+  protected initializeDependencyFactories(factories: StringKeyOf<Modules>[]) {
+    factories.forEach((factoryName) => {
+      this.resolve(factoryName);
+    });
+  }
+
+  /**
+   * Retrieves all dependencies generated by a particular dependencyfactory
+   * and injects them inside this modulecontainer's DI container.
+   * This will be automatically called for every module, but can also be called
+   * explicitly to initialize an extra factory
+   * @param factory
+   * @private
+   */
+  protected useDependencyFactory(factory: DependencyFactory) {
+    const dependencies = factory.dependencies();
+
+    // eslint-disable-next-line sonarjs/cognitive-complexity
+    Object.entries(dependencies).forEach(([rawKey, declaration]) => {
+      const key = rawKey.charAt(0).toUpperCase() + rawKey.slice(1);
+
+      if (
+        !this.container.isRegistered(key) ||
+        declaration.forceOverwrite === true
+      ) {
+        if (
+          this.container.isRegistered(key) &&
+          (declaration?.forceOverwrite ?? false)
+        ) {
+          log.warn(
+            `You are trying to overwrite dependency ${key}, which is already registered. This is currently not supported. Try to define your dependency earlier.`
+          );
+        }
+
+        // Find correct provider type and call respective register
+        if (isValueProvider(declaration)) {
+          this.container.register(key, declaration);
+        } else if (isFactoryProvider(declaration)) {
+          // this enables us to have a singletoned factory
+          // that returns the same instance for each resolve
+          this.container.register(key, {
+            useFactory: instanceCachingFactory(declaration.useFactory),
+          });
+        } else if (isClassProvider(declaration)) {
+          this.container.register(key, declaration, {
+            lifecycle: Lifecycle.Singleton,
+          });
+          this.registerAliases(
+            key,
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            declaration.useClass as TypedClass<unknown>
+          );
+
+          // Register static dependencies
+          if (this.isDependencyFactory(declaration.useClass)) {
+            this.useDependencyFactory(declaration.useClass);
+          }
+        } else if (isTokenProvider(declaration)) {
+          this.container.register(key, declaration, {
+            lifecycle: Lifecycle.Singleton,
+          });
+        } else {
+          // Can never be reached
+          throw new Error("Above if-statement is exhaustive");
+        }
+      } else {
+        log.debug(`Dependency ${key} already registered, skipping`);
+      }
+    });
   }
 
   /**
@@ -271,8 +469,38 @@ export class ModuleContainer<
           throw errors.unableToDecorateModule(containedModuleName);
         }
         this.decorateModule(moduleName, containedModule);
+        containedModule.create(() => {
+          const container = this.container.createChildContainer();
+          container.reset();
+          return container;
+        });
+
+        if (this.isDependencyFactory(containedModule)) {
+          this.useDependencyFactory(containedModule);
+        }
       },
       { frequency: ModuleContainer.moduleDecorationFrequency }
     );
   }
+
+  /**
+   * This is a placeholder for individual modules to override.
+   * This method will be called whenever the underlying container fully
+   * initialized
+   */
+  public create(childContainerProvider: ChildContainerProvider): void {
+    this.providedContainer = childContainerProvider();
+
+    this.registerValue({
+      ChildContainerProvider: () => this.container.createChildContainer(),
+    });
+
+    // register all provided modules when the container is created
+    this.registerModules(this.definition);
+    this.container.register("ParentContainer", { useValue: this });
+  }
+
+  public get dependencyContainer(): DependencyContainer {
+    return this.container;
+  }
 }

package/src/config/Startable.ts

@@ -0,0 +1,3 @@
+export interface Startable {
+  start(): Promise<void>;
+}

package/src/config/injectAlias.ts

@@ -0,0 +1,70 @@
+import { TypedClass } from "../types";
+
+export const injectAliasMetadataKey = "protokit-inject-alias";
+
+/**
+ * Attaches metadata to the class that the ModuleContainer can pick up
+ * and inject this class in the DI container under the specified aliases.
+ * This method supports inheritance, therefore also gets aliases defined
+ * on superclasses
+ */
+export function injectAlias(aliases: string[]) {
+  return (target: TypedClass<unknown>) => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const superAliases = Reflect.getMetadata(
+      injectAliasMetadataKey,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      Object.getPrototypeOf(target)
+    ) as string[] | undefined;
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const existingAliases = Reflect.getMetadata(
+      injectAliasMetadataKey,
+      target
+    ) as string[] | undefined;
+
+    let allAliases = aliases;
+
+    if (superAliases !== undefined) {
+      allAliases = allAliases.concat(superAliases);
+    }
+    if (existingAliases !== undefined) {
+      allAliases = allAliases.concat(existingAliases);
+    }
+
+    Reflect.defineMetadata(
+      injectAliasMetadataKey,
+      allAliases.filter(
+        (value, index, array) => array.indexOf(value) === index
+      ),
+      target
+    );
+  };
+}
+
+/**
+ * Marks the class to implement a certain interface T, while also attaching
+ * a DI-injection alias as metadata, that will be picked up by the ModuleContainer
+ * to allow resolving by that interface name
+ * @param name The name of the injection alias, convention is to use the same as the name of T
+ */
+export function implement<T>(name: string) {
+  return (
+    /**
+     * Check if the target class extends RuntimeModule, while
+     * also providing static config presets
+     */
+    target: TypedClass<T>
+  ) => {
+    injectAlias([name])(target);
+  };
+}
+
+export function getInjectAliases(target: TypedClass<unknown>): string[] {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const aliases = Reflect.getMetadata(
+    injectAliasMetadataKey,
+    target
+  ) as string[];
+  return aliases ?? [];
+}