@composed-di/core 0.5.0-alpha

package/dist/utils.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDotGraph = createDotGraph;
+exports.printDotGraph = printDotGraph;
+exports.createMermaidGraph = createMermaidGraph;
+exports.printMermaidGraph = printMermaidGraph;
+/**
+ * Escapes special characters in strings for DOT notation
+ */
+function escapeDotString(str) {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+/**
+ * Escapes special characters in strings for Mermaid notation
+ */
+function escapeMermaidString(str) {
+    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:
+ * - https://dreampuf.github.io/GraphvizOnline/
+ * - https://edotor.net/
+ *
+ * Arrows point from dependencies to dependents (from what is needed to what needs it).
+ *
+ * @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
+ */
+function createDotGraph(module, { direction, title, highlightLeaves, highlightRoots } = {
+    direction: 'TB',
+    title: 'Service Dependency Graph',
+    highlightLeaves: true,
+    highlightRoots: true,
+}) {
+    const factories = module.factories;
+    const lines = [];
+    // Start the digraph
+    lines.push('digraph ServiceDependencies {');
+    lines.push(`  label="${title}";`);
+    lines.push('  labelloc="t";');
+    lines.push('  fontsize=16;');
+    lines.push(`  rankdir=${direction};`);
+    lines.push('');
+    // Default node styling
+    lines.push('  node [');
+    lines.push('    shape=box,');
+    lines.push('    style="rounded,filled",');
+    lines.push('    fillcolor="#e1f5ff",');
+    lines.push('    color="#0288d1",');
+    lines.push('    fontname="Arial",');
+    lines.push('    fontsize=12');
+    lines.push('  ];');
+    lines.push('');
+    // Default edge styling
+    lines.push('  edge [');
+    lines.push('    color="#666666",');
+    lines.push('    arrowsize=0.8');
+    lines.push('  ];');
+    lines.push('');
+    // Build dependency maps to identify leaves and roots
+    const hasDependencies = new Set();
+    const hasDependents = new Set();
+    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();
+    let nodeCounter = 0;
+    factories.forEach((factory) => {
+        const serviceName = factory.provides.name;
+        const nodeId = `node${nodeCounter++}`;
+        nodeIds.set(serviceName, nodeId);
+        const isLeaf = !hasDependencies.has(serviceName);
+        const isRoot = !hasDependents.has(serviceName);
+        let nodeStyle = '';
+        if (highlightLeaves && isLeaf) {
+            nodeStyle = ' [fillcolor="#c8e6c9", color="#388e3c"]';
+        }
+        else if (highlightRoots && isRoot) {
+            nodeStyle = ' [fillcolor="#ffccbc", color="#d84315"]';
+        }
+        lines.push(`  ${nodeId} [label="${escapeDotString(serviceName)}"]${nodeStyle};`);
+    });
+    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};`);
+            }
+        });
+    });
+    // Close the digraph
+    lines.push('}');
+    return lines.join('\n');
+}
+/**
+ * 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 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.
+ */
+function printDotGraph(module, options) {
+    console.log(createDotGraph(module, options));
+    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
+ */
+function createMermaidGraph(module, { direction, highlightLeaves, highlightRoots } = {
+    direction: 'TB',
+    highlightLeaves: true,
+    highlightRoots: true,
+}) {
+    const factories = module.factories;
+    const lines = [];
+    // Start the flowchart
+    lines.push(`flowchart ${direction}`);
+    // Build dependency maps to identify leaves and roots
+    const hasDependencies = new Set();
+    const hasDependents = new Set();
+    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();
+    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.
+ */
+function printMermaidGraph(module, options) {
+    console.log(createMermaidGraph(module, options));
+    console.log('\n\nCopy the Mermaid output above and paste it into:');
+    console.log('https://mermaid.live/');
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@composed-di/core",
+  "private": false,
+  "version": "0.5.0-alpha",
+  "author": "Juan Herrera juanhr454@gmail.com",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "dependency injection",
+    "di",
+    "lazy dependency injection"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imherrera/composed-di.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,23 @@
+/**
+ * Error thrown when there is an issue during the initialization or configuration of a ServiceModule.
+ * This can include circular dependencies or missing dependencies that are detected during module creation.
+ */
+export class ServiceModuleInitError extends Error {
+  name = 'ServiceModuleInitError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/**
+ * Error thrown when a requested service cannot be found within the ServiceModule.
+ * This typically occurs when no factory has been registered for the given ServiceKey.
+ */
+export class ServiceFactoryNotFoundError extends Error {
+  name = 'ServiceFactoryNotFoundError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './serviceKey';
+export * from './serviceModule';
+export * from './serviceFactory';
+export * from './serviceScope';
+export * from './serviceSelector';
+export * from './serviceEventListener';
+export * from './errors';
+export * from './utils';

package/src/serviceEventListener.ts

@@ -0,0 +1,130 @@
+import type { ServiceKey } from './serviceKey';
+
+/**
+ * A handle representing a single in-flight operation (initialization,
+ * disposal, or method call), returned by a ServiceEventListener when the
+ * operation starts.
+ *
+ * Exactly one of `end` or `error` is invoked when the operation finishes,
+ * so implementations can close over per-call state (start time, an
+ * OpenTelemetry span, a correlation id) without any bookkeeping to pair
+ * concurrent start/finish events.
+ */
+export interface EventSpan {
+  /**
+   * Invoked when the operation completes successfully. For methods that
+   * return a promise, this fires when the promise resolves, not when the
+   * method returns.
+   *
+   * Whether to retain or log the outcome is the implementation's choice;
+   * the value is passed by reference, so implementations must not mutate it.
+   *
+   * @param outcome - The outcome of the operation. Present for method call
+   * spans (the return or resolved value) and initialize spans (the service
+   * instance), absent for dispose spans.
+   * @return void
+   */
+  end?(outcome?: EventOutcome): void;
+
+  /**
+   * Invoked when the operation throws or rejects. Terminal like `end`;
+   * the two are mutually exclusive. The error is rethrown to the caller
+   * after this is invoked.
+   *
+   * @param error - The error object or value that was thrown or rejected.
+   * @return void
+   */
+  error?(error: unknown): void;
+}
+
+/**
+ * The successful outcome of an operation, delivered to EventSpan.end.
+ * Future fields (e.g. a correlation id) are added here rather than as
+ * extra parameters.
+ */
+export interface EventOutcome {
+  /**
+   * The value produced by the operation: the return value for synchronous
+   * methods, or the resolved value for methods returning a promise.
+   */
+  result: unknown;
+}
+
+/**
+ * Context of a service initialization, delivered to onInitialize.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface InitializeContext {
+  /**
+   * The unique identifier of the service that is being initialized.
+   */
+  key: ServiceKey<unknown>;
+}
+
+/**
+ * Context of a service disposal, delivered to onDispose.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface DisposeContext {
+  /**
+   * The unique identifier of the service that is being disposed.
+   */
+  key: ServiceKey<unknown>;
+}
+
+/**
+ * Context of a method invocation, delivered to onMethodCall.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface MethodCallContext {
+  /**
+   * The unique identifier of the service the method belongs to.
+   */
+  key: ServiceKey<unknown>;
+
+  /**
+   * The name of the method that is being called.
+   */
+  methodName: string;
+
+  /**
+   * The arguments the method was invoked with, passed by reference;
+   * implementations must not mutate them.
+   */
+  args: readonly unknown[];
+}
+
+/**
+ * Interface for listening to service events. Implement this interface to
+ * observe lifecycle events and method calls of services in a module.
+ *
+ * Each method is invoked when the corresponding operation starts and may
+ * return an EventSpan that is notified when that operation finishes.
+ * Returning nothing opts out of completion tracking for that call.
+ */
+export interface ServiceEventListener {
+  /**
+   * Invoked at the start of the initialization process for a specific service.
+   *
+   * @param context - Context of the initialization, including the service key.
+   * @return An EventSpan notified when initialization finishes, or void.
+   */
+  onInitialize?(context: InitializeContext): EventSpan | void;
+
+  /**
+   * Invoked when the disposal process for a service starts.
+   *
+   * @param context - Context of the disposal, including the service key.
+   * @return An EventSpan notified when disposal finishes, or void.
+   */
+  onDispose?(context: DisposeContext): EventSpan | void;
+
+  /**
+   * Invoked when a method call starts on a service instance.
+   *
+   * @param context - Context of the invocation, including the service key,
+   * the method name, and its arguments.
+   * @return An EventSpan notified when the call finishes, or void.
+   */
+  onMethodCall?(context: MethodCallContext): EventSpan | void;
+}

package/src/serviceFactory.ts

@@ -0,0 +1,104 @@
+import { ServiceKey, ServiceSelectorKey } from './serviceKey';
+import { ServiceScope } from './serviceScope';
+import { ServiceSelector } from './serviceSelector';
+
+// Helper types to extract the type from ServiceKey or ServiceSelectorKey
+type ServiceType<T> =
+  T extends ServiceSelectorKey<infer U>
+    ? ServiceSelector<U>
+    : T extends ServiceKey<infer U>
+      ? U
+      : never;
+
+// Helper types to convert an array/tuple of ServiceKey to tuple of their types
+type DependencyTypes<T extends readonly ServiceKey<unknown>[]> = {
+  [K in keyof T]: ServiceType<T[K]>;
+};
+
+export abstract class ServiceFactory<
+  const T,
+  const D extends readonly ServiceKey<unknown>[] = [],
+> {
+  abstract provides: ServiceKey<T>;
+  abstract dependsOn: D;
+  abstract scope?: ServiceScope;
+  abstract initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
+  abstract dispose?: () => void;
+
+  /**
+   * Creates a singleton service factory that ensures a single instance of the provided service is initialized
+   * and used throughout the scope lifecycle.
+   */
+  static singleton<
+    const T,
+    const D extends readonly ServiceKey<unknown>[] = [],
+  >({
+    scope,
+    provides,
+    dependsOn = [] as unknown as D,
+    initialize,
+    dispose = () => {},
+  }: {
+    scope?: ServiceScope;
+    provides: ServiceKey<T>;
+    dependsOn?: D;
+    initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
+    dispose?: (instance: T) => void;
+  }): ServiceFactory<T, D> {
+    let promisedInstance: Promise<T> | undefined;
+    let resolvedInstance: T | undefined;
+
+    return {
+      scope,
+      provides,
+      dependsOn,
+      async initialize(...dependencies: DependencyTypes<D>): Promise<T> {
+        if (resolvedInstance !== undefined) {
+          return resolvedInstance;
+        }
+
+        if (promisedInstance !== undefined) {
+          return promisedInstance;
+        }
+
+        // Store the reference to the promise so that concurrent requests can wait for it
+        promisedInstance = (async () => {
+          try {
+            resolvedInstance = await initialize(...dependencies);
+            return resolvedInstance;
+          } finally {
+            promisedInstance = undefined;
+          }
+        })();
+        return promisedInstance;
+      },
+      dispose(): void {
+        if (resolvedInstance !== undefined) {
+          dispose(resolvedInstance);
+          resolvedInstance = undefined;
+        }
+        promisedInstance = undefined;
+      },
+    };
+  }
+
+  /**
+   * Creates a one-shot service factory that initializes a new instance of the provided service
+   * every time it is requested.
+   */
+  static oneShot<const T, const D extends readonly ServiceKey<unknown>[] = []>({
+    provides,
+    dependsOn,
+    initialize,
+  }: {
+    provides: ServiceKey<T>;
+    dependsOn: D;
+    initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
+  }): ServiceFactory<T, D> {
+    return {
+      provides,
+      dependsOn,
+      initialize,
+    };
+  }
+}

package/src/serviceKey.ts

@@ -0,0 +1,95 @@
+// @ts-ignore
+import { ServiceSelector } from './serviceSelector';
+
+/**
+ * A typed token used to identify and retrieve a service from a ServiceModule.
+ *
+ * ServiceKey acts as a unique identifier for a service type, allowing type-safe
+ * dependency injection. Each key has a unique symbol to ensure identity comparison
+ * works correctly even if two keys have the same name.
+ *
+ * @template T The type of service this key identifies.
+ *
+ * @example
+ * ```ts
+ * interface Logger {
+ *   log: (msg: string) => void;
+ * }
+ *
+ * const LoggerKey = new ServiceKey<Logger>('Logger');
+ *
+ * // Use with ServiceFactory and ServiceModule
+ * const loggerFactory = ServiceFactory.singleton({
+ *   provides: LoggerKey,
+ *   dependsOn: [],
+ *   initialize: () => console,
+ * });
+ *
+ * const module = ServiceModule.from([loggerFactory]);
+ * const logger = await module.get(LoggerKey);
+ * ```
+ */
+export class ServiceKey<T> {
+  /**
+   * A unique symbol that identifies this service key.
+   * Used internally for identity comparison between keys.
+   */
+  public readonly symbol: symbol;
+
+  /**
+   * Creates a new ServiceKey with the given name.
+   *
+   * @param name A human-readable name for the service, used in error messages and debugging.
+   */
+  constructor(public readonly name: string) {
+    this.symbol = Symbol(name);
+  }
+}
+
+/**
+ * A specialized ServiceKey that groups multiple ServiceKeys of the same type,
+ * allowing a service to depend on a selector that can retrieve any of the grouped services.
+ *
+ * When used in a factory's `dependsOn` array, the factory's `initialize` callback
+ * receives a `ServiceSelector<T>` instance instead of a direct service instance.
+ * This enables runtime selection between multiple implementations of the same interface.
+ *
+ * @template T The common type shared by all service keys in this selector.
+ *
+ * @example
+ * ```ts
+ * interface Logger {
+ *   log: (msg: string) => void;
+ * }
+ *
+ * const ConsoleLoggerKey = new ServiceKey<Logger>('ConsoleLogger');
+ * const FileLoggerKey = new ServiceKey<Logger>('FileLogger');
+ *
+ * // Group multiple logger implementations under one selector
+ * const LoggerSelectorKey = new ServiceSelectorKey<Logger>([
+ *   ConsoleLoggerKey,
+ *   FileLoggerKey,
+ * ]);
+ *
+ * // Use in a factory's dependsOn array
+ * const appFactory = ServiceFactory.singleton({
+ *   provides: AppKey,
+ *   dependsOn: [LoggerSelectorKey] as const,
+ *   initialize: (loggerSelector: ServiceSelector<Logger>) => {
+ *     // loggerSelector.get(ConsoleLoggerKey) or loggerSelector.get(FileLoggerKey)
+ *     return new App(loggerSelector);
+ *   },
+ * });
+ * ```
+ */
+export class ServiceSelectorKey<T> extends ServiceKey<ServiceSelector<T>> {
+  /**
+   * Creates a new ServiceSelectorKey that groups the provided service keys.
+   *
+   * @param values An array of ServiceKeys that this selector can provide access to.
+   *               All keys must be registered in the ServiceModule for dependency validation to pass.
+   */
+  constructor(readonly values: ServiceKey<T>[]) {
+    super(`ServiceSelector[${values}]`);
+  }
+}