composed-di 0.2.9 → 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<unknown, 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);
+  }
+}

package/src/utils.ts

@@ -12,6 +12,15 @@ export interface DotGraphOptions {
   highlightRoots?: boolean;
 }
 
+export interface MermaidGraphOptions {
+  /** Graph direction: 'TB' (top-bottom), 'LR' (left-right), 'BT' (bottom-top), 'RL' (right-left) */
+  direction?: 'TB' | 'LR' | 'BT' | 'RL';
+  /** Show nodes with no dependencies in a different color */
+  highlightLeaves?: boolean;
+  /** Show nodes with no dependents in a different color */
+  highlightRoots?: boolean;
+}
+
 /**
  * Escapes special characters in strings for DOT notation
  */
@@ -19,6 +28,13 @@ function escapeDotString(str: string): string {
   return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
 }
 
+/**
+ * Escapes special characters in strings for Mermaid notation
+ */
+function escapeMermaidString(str: string): string {
+  return str.replace(/"/g, '#quot;');
+}
+
 /**
  * Generates a DOT notation graph from a ServiceModule.
  * The output can be visualized using Graphviz tools or online viewers like:
@@ -27,9 +43,9 @@ function escapeDotString(str: string): string {
  *
  * Arrows point from dependencies to dependents (from what is needed to what needs it).
  *
- * @param {ServiceModule} module - The ServiceModule to convert to DOT notation
- * @param {DotGraphOptions} options - Optional configuration for the graph appearance
- * @returns {string} A string containing the DOT notation graph
+ * @param module - The ServiceModule to convert to DOT notation
+ * @param options - Optional configuration for the graph appearance
+ * @returns A string containing the DOT notation graph
  */
 export function createDotGraph(
   module: ServiceModule,
@@ -138,9 +154,8 @@ export function createDotGraph(
  * Prints a DOT representation of a service module graph to the console.
  * The output can be used to visualize the graph using online graph visualization tools.
  *
- * @param {ServiceModule} module - The service module representing the graph to be converted into DOT format.
- * @param {DotGraphOptions} [options] - Optional configurations to customize the output of the DOT graph.
- * @return {void} - This function does not return a value.
+ * @param module - The service module representing the graph to be converted into DOT format.
+ * @param options - Optional configurations to customize the output of the DOT graph.
  */
 export function printDotGraph(
   module: ServiceModule,
@@ -150,3 +165,113 @@ export function printDotGraph(
   console.log('\n\nCopy the DOT output above and paste it into:');
   console.log('https://dreampuf.github.io/GraphvizOnline/');
 }
+
+/**
+ * Generates a Mermaid flowchart from a ServiceModule.
+ * The output can be visualized using Mermaid-compatible tools or online viewers like:
+ * - https://mermaid.live/
+ *
+ * Arrows point from dependents to dependencies (what needs it -> what provides it).
+ *
+ * @param module - The ServiceModule to convert to Mermaid notation
+ * @param options - Optional configuration for the graph appearance
+ * @returns A string containing the Mermaid flowchart
+ */
+export function createMermaidGraph(
+  module: ServiceModule,
+  { direction, highlightLeaves, highlightRoots }: MermaidGraphOptions = {
+    direction: 'TB',
+    highlightLeaves: true,
+    highlightRoots: true,
+  },
+): string {
+  const factories = module.factories;
+  const lines: string[] = [];
+
+  // Start the flowchart
+  lines.push(`flowchart ${direction}`);
+
+  // Build dependency maps to identify leaves and roots
+  const hasDependencies = new Set<string>();
+  const hasDependents = new Set<string>();
+
+  factories.forEach((factory) => {
+    const serviceName = factory.provides.name;
+
+    if (factory.dependsOn.length > 0) {
+      hasDependencies.add(serviceName);
+    }
+
+    factory.dependsOn.forEach((dependency) => {
+      hasDependents.add(dependency.name);
+    });
+  });
+
+  // Define nodes with special styling for leaves and roots
+  const nodeIds = new Map<string, string>();
+  let nodeCounter = 0;
+
+  factories.forEach((factory) => {
+    const serviceName = factory.provides.name;
+    const nodeId = `node${nodeCounter++}`;
+    nodeIds.set(serviceName, nodeId);
+
+    lines.push(`  ${nodeId}["${escapeMermaidString(serviceName)}"]`);
+  });
+
+  lines.push('');
+
+  // Define edges (dependencies)
+  factories.forEach((factory) => {
+    const serviceName = factory.provides.name;
+    const serviceNodeId = nodeIds.get(serviceName)!;
+
+    factory.dependsOn.forEach((dependency) => {
+      const depName = dependency.name;
+      const depNodeId = nodeIds.get(depName);
+
+      if (depNodeId) {
+        // Arrow points from dependent to dependency (what needs it -> what provides it)
+        lines.push(`  ${serviceNodeId} --> ${depNodeId}`);
+      }
+    });
+  });
+
+  lines.push('');
+
+  // Apply styling
+  factories.forEach((factory) => {
+    const serviceName = factory.provides.name;
+    const serviceNodeId = nodeIds.get(serviceName)!;
+
+    const isLeaf = !hasDependencies.has(serviceName);
+    const isRoot = !hasDependents.has(serviceName);
+
+    if (highlightLeaves && isLeaf) {
+      lines.push(`  style ${serviceNodeId} fill:#c8e6c9,stroke:#388e3c`);
+    } else if (highlightRoots && isRoot) {
+      lines.push(`  style ${serviceNodeId} fill:#ffccbc,stroke:#d84315`);
+    } else {
+      // Default style
+      lines.push(`  style ${serviceNodeId} fill:#e1f5ff,stroke:#0288d1`);
+    }
+  });
+
+  return lines.join('\n');
+}
+
+/**
+ * Prints a Mermaid representation of a service module graph to the console.
+ * The output can be used to visualize the graph using online Mermaid tools.
+ *
+ * @param module - The service module representing the graph to be converted into Mermaid format.
+ * @param options - Optional configurations to customize the output of the Mermaid graph.
+ */
+export function printMermaidGraph(
+  module: ServiceModule,
+  options?: MermaidGraphOptions,
+): void {
+  console.log(createMermaidGraph(module, options));
+  console.log('\n\nCopy the Mermaid output above and paste it into:');
+  console.log('https://mermaid.live/');
+}

package/dist/main.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":""}

package/dist/main.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const serviceKey_1 = require("./serviceKey");
-const serviceFactory_1 = require("./serviceFactory");
-const TEST_SERVICE_KEY = new serviceKey_1.ServiceKey('testService');
-const FOO_KEY = new serviceKey_1.ServiceKey('foo');
-const BAR_KEY = new serviceKey_1.ServiceKey('bar');
-const TestServiceFactory = (0, serviceFactory_1.singletonFactory)({
-    provides: TEST_SERVICE_KEY,
-    dependsOn: [FOO_KEY, BAR_KEY],
-    initialize: (foo, bar) => {
-        return { foo, bar };
-    },
-});
-//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";;AAAA,6CAA0C;AAC1C,qDAAoD;AAEpD,MAAM,gBAAgB,GAAG,IAAI,uBAAU,CAAc,aAAa,CAAC,CAAC;AACpE,MAAM,OAAO,GAAG,IAAI,uBAAU,CAAS,KAAK,CAAC,CAAC;AAC9C,MAAM,OAAO,GAAG,IAAI,uBAAU,CAAS,KAAK,CAAC,CAAC;AAO9C,MAAM,kBAAkB,GAAG,IAAA,iCAAgB,EAAC;IAC1C,QAAQ,EAAE,gBAAgB;IAC1B,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,CAAU;IACtC,UAAU,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACvB,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,CAAC;CACF,CAAC,CAAC"}