composed-di 0.2.9-ts4 → 0.3.0

package/src/serviceModule.ts

@@ -1,123 +1,223 @@
-import { ServiceKey } from './serviceKey';
-import { ServiceFactory } from './serviceFactory';
-import { ServiceScope } from './serviceScope';
-
-type GenericFactory = ServiceFactory<any, readonly ServiceKey<any>[]>;
-type GenericKey = ServiceKey<any>;
-
-export class ServiceModule {
-  private constructor(readonly factories: GenericFactory[]) {
-    factories.forEach((factory) => {
-      checkRecursiveDependencies(factory);
-      checkMissingDependencies(factory, this.factories);
-    });
-  }
-
-  public async get<T>(key: ServiceKey<T>): Promise<T> {
-    const factory = this.factories.find((factory: GenericFactory) => {
-      return isSuitable(key, factory);
-    });
-
-    // Check if a factory to supply the requested key was not found
-    if (!factory) {
-      throw new Error(`Could not find a suitable factory for ${key.name}`);
-    }
-
-    // Resolve all dependencies first
-    const dependencies = await Promise.all(
-      factory.dependsOn.map((dependencyKey: ServiceKey<unknown>) => {
-        return this.get(dependencyKey);
-      }),
-    );
-
-    // Call the factory to retrieve the dependency
-    return factory.initialize(...dependencies);
-  }
-
-  /**
-   * Disposes of service factories within the specified scope or all factories if no scope is provided.
-   *
-   * This method is useful for cleaning up resources and instances held by service factories,
-   * such as singleton factories, as they may hold database connections or other resources that need to be released.
-   *
-   * @param {ServiceScope} [scope] The scope to filter the factories to be disposed.
-   * If not provided, all factories are disposed of.
-   * @return {void} No return value.
-   */
-  public dispose(scope?: ServiceScope) {
-    const factories = scope
-      ? this.factories.filter((f) => f.scope === scope)
-      : this.factories;
-
-    factories.forEach((factory) => factory.dispose?.());
-  }
-
-  /**
-   * Creates a new ServiceModule instance by aggregating and deduplicating a list of
-   * ServiceModule or GenericFactory instances.
-   * If multiple factories provide the same
-   * ServiceKey, the last one in the list takes precedence.
-   *
-   * @param {Array<ServiceModule | GenericFactory>} entries - An array of ServiceModule or GenericFactory
-   * instances to be processed into a single ServiceModule.
-   * @return {ServiceModule} A new ServiceModule containing the deduplicated factories.
-   */
-  static from(entries: (ServiceModule | GenericFactory)[]): ServiceModule {
-    // Flatten entries and keep only the last factory for each ServiceKey
-    const flattened = entries.flatMap((e) =>
-      e instanceof ServiceModule ? e.factories : [e],
-    );
-
-    const byKey = new Map<symbol, GenericFactory>();
-    // Later factories overwrite earlier ones (last-wins)
-    for (const f of flattened) {
-      byKey.set(f.provides.symbol, f);
-    }
-
-    return new ServiceModule(Array.from(byKey.values()));
-  }
-}
-
-function checkRecursiveDependencies(factory: GenericFactory) {
-  const recursive = factory.dependsOn.some((dependencyKey) => {
-    return dependencyKey === factory.provides;
-  });
-
-  if (recursive) {
-    throw new Error(
-      'Recursive dependency detected on: ' + factory.provides.name,
-    );
-  }
-}
-
-function checkMissingDependencies(
-  factory: GenericFactory,
-  factories: GenericFactory[],
-) {
-  const missingDependencies = factory.dependsOn.filter(
-    (dependencyKey: GenericKey) => {
-      return !isRegistered(dependencyKey, factories);
-    },
-  );
-  if (missingDependencies.length === 0) {
-    return;
-  }
-
-  const dependencyList = missingDependencies
-    .map((dependencyKey) => ` -> ${dependencyKey.name}`)
-    .join('\n');
-  throw new Error(
-    `${factory.provides.name} will fail because it depends on:\n ${dependencyList}`,
-  );
-}
-
-function isRegistered(key: GenericKey, factories: GenericFactory[]) {
-  return factories.some((factory) => factory.provides?.symbol === key?.symbol);
-}
-
-function isSuitable<T, D extends readonly ServiceKey<any>[]>(
-  key: ServiceKey<T>,
-  factory: ServiceFactory<any, D>,
-): factory is ServiceFactory<T, D> {
-  return factory?.provides?.symbol === key?.symbol;
-}
+import { ServiceKey, ServiceSelectorKey } from './serviceKey';
+import { ServiceFactory } from './serviceFactory';
+import { ServiceScope } from './serviceScope';
+import { ServiceSelector } from './serviceSelector';
+import { ServiceFactoryNotFoundError, ServiceModuleInitError } from './errors';
+
+type GenericFactory = ServiceFactory<unknown, readonly ServiceKey<any>[]>;
+type GenericKey = ServiceKey<any>;
+
+/**
+ * ServiceModule is a container for service factories and manages dependency resolution.
+ *
+ * It provides a way to retrieve service instances based on their ServiceKey,
+ * ensuring that all dependencies are resolved and initialized in the correct order.
+ * It also handles circular dependency detection and missing dependency validation
+ * at the time of module creation.
+ */
+export class ServiceModule {
+  /**
+   * Private constructor to enforce module creation through the `static from` method.
+   *
+   * @param factories An array of service factories that this module will manage.
+   */
+  private constructor(readonly factories: GenericFactory[]) {
+    checkCircularDependencies(this.factories);
+    factories.forEach((factory) => {
+      checkMissingDependencies(factory, this.factories);
+    });
+  }
+
+  /**
+   * Retrieves an instance for the given ServiceKey.
+   *
+   * @param key - The key of the service to retrieve.
+   * @return A promise that resolves to the service instance.
+   * @throws {ServiceFactoryNotFoundError} If no suitable factory is found for the given key.
+   */
+  public async get<T>(key: ServiceKey<T>): Promise<T> {
+    const factory = this.factories.find((factory: GenericFactory) => {
+      return isSuitable(key, factory);
+    });
+
+    // Check if a factory to supply the requested key was not found
+    if (!factory) {
+      throw new ServiceFactoryNotFoundError(
+        `Could not find a suitable factory for ${key.name}`,
+      );
+    }
+
+    // Resolve all dependencies first
+    const dependencies = await Promise.all(
+      factory.dependsOn.map((dependencyKey: ServiceKey<unknown>) => {
+        // If the dependency is a ServiceSelectorKey, create a ServiceSelector instance
+        if (dependencyKey instanceof ServiceSelectorKey) {
+          return new ServiceSelector(this, dependencyKey);
+        }
+        return this.get(dependencyKey);
+      }),
+    );
+
+    // Call the factory to retrieve the dependency
+    return factory.initialize(...dependencies);
+  }
+
+  /**
+   * Disposes of service factories within the specified scope or all factories if no scope is provided.
+   *
+   * This method is useful for cleaning up resources and instances held by service factories,
+   * such as singleton factories, as they may hold database connections or other resources that need to be released.
+   *
+   * @param scope The scope to filter the factories to be disposed.
+   * If not provided, all factories are disposed of.
+   * @return No return value.
+   */
+  public dispose(scope?: ServiceScope) {
+    const factories = scope
+      ? this.factories.filter((f) => f.scope === scope)
+      : this.factories;
+
+    factories.forEach((factory) => factory.dispose?.());
+  }
+
+  /**
+   * Creates a new ServiceModule instance by aggregating and deduplicating a list of
+   * ServiceModule or GenericFactory instances.
+   * If multiple factories provide the same
+   * ServiceKey, the last one in the list takes precedence.
+   *
+   * @param entries - An array of ServiceModule or GenericFactory
+   * instances to be processed into a single ServiceModule.
+   * @return A new ServiceModule containing the deduplicated factories.
+   * @throws {ServiceModuleInitError} If circular or missing dependencies are detected during module creation.
+   */
+  static from(entries: (ServiceModule | GenericFactory)[]): ServiceModule {
+    // Flatten entries and keep only the last factory for each ServiceKey
+    const flattened = entries.flatMap((e) =>
+      e instanceof ServiceModule ? e.factories : [e],
+    );
+
+    const byKey = new Map<symbol, GenericFactory>();
+    // Later factories overwrite earlier ones (last-wins)
+    for (const f of flattened) {
+      byKey.set(f.provides.symbol, f);
+    }
+
+    return new ServiceModule(Array.from(byKey.values()));
+  }
+}
+
+/**
+ * Validates that there are no circular dependencies among the provided factories.
+ *
+ * @param factories The list of factories to check for cycles.
+ * @throws {ServiceModuleInitError} If a circular dependency is detected.
+ */
+function checkCircularDependencies(factories: GenericFactory[]) {
+  const factoryMap = new Map<symbol, GenericFactory>();
+  for (const f of factories) {
+    factoryMap.set(f.provides.symbol, f);
+  }
+
+  const visited = new Set<symbol>();
+  const stack = new Set<symbol>();
+
+  function walk(factory: GenericFactory, path: string[]) {
+    const symbol = factory.provides.symbol;
+
+    if (stack.has(symbol)) {
+      const cyclePath = [...path, factory.provides.name].join(' -> ');
+      throw new ServiceModuleInitError(
+        `Circular dependency detected: ${cyclePath}`,
+      );
+    }
+
+    if (visited.has(symbol)) {
+      return;
+    }
+
+    visited.add(symbol);
+    stack.add(symbol);
+
+    for (const depKey of factory.dependsOn) {
+      const keysToCheck =
+        depKey instanceof ServiceSelectorKey ? depKey.values : [depKey];
+
+      for (const key of keysToCheck) {
+        const depFactory = factoryMap.get(key.symbol);
+        if (depFactory) {
+          walk(depFactory, [...path, factory.provides.name]);
+        }
+      }
+    }
+
+    stack.delete(symbol);
+  }
+
+  for (const factory of factories) {
+    walk(factory, []);
+  }
+}
+
+/**
+ * Validates that all dependencies of a given factory are present in the list of factories.
+ *
+ * @param factory The factory whose dependencies are to be checked.
+ * @param factories The list of available factories in the module.
+ * @throws {ServiceModuleInitError} If any dependency is missing.
+ */
+function checkMissingDependencies(
+  factory: GenericFactory,
+  factories: GenericFactory[],
+) {
+  const missingDependencies: GenericKey[] = [];
+
+  factory.dependsOn.forEach((dependencyKey: GenericKey) => {
+    // For ServiceSelectorKey, check all contained keys are registered
+    if (dependencyKey instanceof ServiceSelectorKey) {
+      dependencyKey.values.forEach((key) => {
+        if (!isRegistered(key, factories)) {
+          missingDependencies.push(key);
+        }
+      });
+    } else if (!isRegistered(dependencyKey, factories)) {
+      missingDependencies.push(dependencyKey);
+    }
+  });
+
+  if (missingDependencies.length === 0) {
+    return;
+  }
+
+  const dependencyList = missingDependencies
+    .map((dependencyKey) => ` -> ${dependencyKey.name}`)
+    .join('\n');
+  throw new ServiceModuleInitError(
+    `${factory.provides.name} will fail because it depends on:\n ${dependencyList}`,
+  );
+}
+
+/**
+ * Checks if a ServiceKey is registered among the provided factories.
+ *
+ * @param key The ServiceKey to look for.
+ * @param factories The list of factories to search in.
+ * @returns True if a factory provides the given key, false otherwise.
+ */
+function isRegistered(key: GenericKey, factories: GenericFactory[]) {
+  return factories.some((factory) => factory.provides?.symbol === key?.symbol);
+}
+
+/**
+ * Determines if a factory is suitable for providing a specific ServiceKey.
+ *
+ * @param key The ServiceKey being requested.
+ * @param factory The factory to check.
+ * @returns True if the factory provides the key, false otherwise.
+ */
+function isSuitable<T, D extends readonly ServiceKey<any>[]>(
+  key: ServiceKey<T>,
+  factory: ServiceFactory<any, D>,
+): factory is ServiceFactory<T, D> {
+  return factory?.provides?.symbol === key?.symbol;
+}

package/src/serviceScope.ts

@@ -1,7 +1,7 @@
-export class ServiceScope {
-  readonly symbol: symbol;
-
-  constructor(readonly name: string) {
-    this.symbol = Symbol(name);
-  }
-}
+export class ServiceScope {
+  readonly symbol: symbol;
+
+  constructor(readonly name: string) {
+    this.symbol = Symbol(name);
+  }
+}

package/src/serviceSelector.ts

@@ -0,0 +1,68 @@
+import { ServiceKey, ServiceSelectorKey } from './serviceKey';
+import { ServiceModule } from './serviceModule';
+
+/**
+ * A runtime selector that provides access to multiple service implementations of the same type.
+ *
+ * ServiceSelector is automatically created and injected when a factory depends on a
+ * `ServiceSelectorKey<T>`. It allows the dependent service to dynamically choose which
+ * implementation to use at runtime, rather than being bound to a single implementation
+ * at configuration time.
+ *
+ * @template T The common type shared by all services accessible through this selector.
+ *
+ * @example
+ * ```ts
+ * // In a factory that depends on ServiceSelectorKey
+ * const appFactory = ServiceFactory.singleton({
+ *   provides: AppKey,
+ *   dependsOn: [LoggerSelectorKey] as const,
+ *   initialize: (loggerSelector: ServiceSelector<Logger>) => {
+ *     return {
+ *       logWithConsole: async () => {
+ *         const logger = await loggerSelector.get(ConsoleLoggerKey);
+ *         logger.log('Using console logger');
+ *       },
+ *       logWithFile: async () => {
+ *         const logger = await loggerSelector.get(FileLoggerKey);
+ *         logger.log('Using file logger');
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export class ServiceSelector<T> {
+  /**
+   * Creates a new ServiceSelector instance.
+   *
+   * Note: ServiceSelector instances are created automatically by ServiceModule
+   * when resolving dependencies. You typically don't need to create them manually.
+   *
+   * @param serviceModule The ServiceModule used to resolve the selected service.
+   * @param selectorKey The ServiceSelectorKey that defines which services can be selected.
+   */
+  constructor(
+    readonly serviceModule: ServiceModule,
+    readonly selectorKey: ServiceSelectorKey<T>,
+  ) {}
+
+  /**
+   * Retrieves a service instance by its key from the available services in this selector.
+   *
+   * The key must be one of the keys that were included in the `ServiceSelectorKey`
+   * used to create this selector.
+   *
+   * @param key The ServiceKey identifying which service implementation to retrieve.
+   * @returns A Promise that resolves to the requested service instance.
+   *
+   * @example
+   * ```ts
+   * const logger = await loggerSelector.get(ConsoleLoggerKey);
+   * logger.log('Hello!');
+   * ```
+   */
+  get(key: ServiceKey<T>): Promise<T> {
+    return this.serviceModule.get(key);
+  }
+}