@composed-di/core 0.5.2-alpha → 0.6.0-alpha

package/src/serviceFactory.ts

@@ -1,6 +1,6 @@
-import { ServiceKey, ServiceSelectorKey } from './serviceKey';
-import { ServiceScope } from './serviceScope';
-import { ServiceSelector } from './serviceSelector';
+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> =
@@ -8,22 +8,22 @@ type ServiceType<T> =
     ? ServiceSelector<U>
     : T extends ServiceKey<infer U>
       ? U
-      : never;
+      : 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]>;
-};
+  [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;
+  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
@@ -39,14 +39,14 @@ export abstract class ServiceFactory<
     initialize,
     dispose = () => {},
   }: {
-    scope?: ServiceScope;
-    provides: ServiceKey<T>;
-    dependsOn?: D;
-    initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
-    dispose?: (instance: T) => void;
+    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;
+    let promisedInstance: Promise<T> | undefined
+    let resolvedInstance: T | undefined
 
     return {
       scope,
@@ -54,32 +54,32 @@ export abstract class ServiceFactory<
       dependsOn,
       async initialize(...dependencies: DependencyTypes<D>): Promise<T> {
         if (resolvedInstance !== undefined) {
-          return resolvedInstance;
+          return resolvedInstance
         }
 
         if (promisedInstance !== undefined) {
-          return promisedInstance;
+          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;
+            resolvedInstance = await initialize(...dependencies)
+            return resolvedInstance
           } finally {
-            promisedInstance = undefined;
+            promisedInstance = undefined
           }
-        })();
-        return promisedInstance;
+        })()
+        return promisedInstance
       },
       dispose(): void {
         if (resolvedInstance !== undefined) {
-          dispose(resolvedInstance);
-          resolvedInstance = undefined;
+          dispose(resolvedInstance)
+          resolvedInstance = undefined
         }
-        promisedInstance = undefined;
+        promisedInstance = undefined
       },
-    };
+    }
   }
 
   /**
@@ -91,14 +91,14 @@ export abstract class ServiceFactory<
     dependsOn,
     initialize,
   }: {
-    provides: ServiceKey<T>;
-    dependsOn: D;
-    initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
+    provides: ServiceKey<T>
+    dependsOn: D
+    initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>
   }): ServiceFactory<T, D> {
     return {
       provides,
       dependsOn,
       initialize,
-    };
+    }
   }
 }

package/src/serviceKey.ts

@@ -1,5 +1,5 @@
 // @ts-ignore
-import { ServiceSelector } from './serviceSelector';
+import { ServiceSelector } from './serviceSelector'
 
 /**
  * A typed token used to identify and retrieve a service from a ServiceModule.
@@ -30,11 +30,18 @@ import { ServiceSelector } from './serviceSelector';
  * ```
  */
 export class ServiceKey<T> {
+  /**
+   * Phantom field that brands this key with the service type `T`.
+   * Exists only at the type level (`declare` emits no runtime code) and
+   * prevents keys of different service types from being interchangeable.
+   */
+  declare private readonly _type: T
+
   /**
    * A unique symbol that identifies this service key.
    * Used internally for identity comparison between keys.
    */
-  public readonly symbol: symbol;
+  public readonly symbol: symbol
 
   /**
    * Creates a new ServiceKey with the given name.
@@ -42,7 +49,7 @@ export class ServiceKey<T> {
    * @param name A human-readable name for the service, used in error messages and debugging.
    */
   constructor(public readonly name: string) {
-    this.symbol = Symbol(name);
+    this.symbol = Symbol(name)
   }
 }
 
@@ -90,6 +97,6 @@ export class ServiceSelectorKey<T> extends ServiceKey<ServiceSelector<T>> {
    *               All keys must be registered in the ServiceModule for dependency validation to pass.
    */
   constructor(readonly values: ServiceKey<T>[]) {
-    super(`ServiceSelector[${values}]`);
+    super(`ServiceSelector[${values}]`)
   }
 }

package/src/serviceModule.ts

@@ -1,15 +1,11 @@
-import { ServiceKey, ServiceSelectorKey } from './serviceKey';
-import { ServiceFactory } from './serviceFactory';
-import { ServiceScope } from './serviceScope';
-import { ServiceSelector } from './serviceSelector';
-import { ServiceFactoryNotFoundError, ServiceModuleInitError } from './errors';
-import type {
-  EventSpan,
-  ServiceModuleListener,
-} from './serviceModuleListener';
+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>;
+type GenericFactory = ServiceFactory<unknown, readonly ServiceKey<any>[]>
+type GenericKey = ServiceKey<any>
 
 /**
  * ServiceModule is a container for service factories and manages dependency resolution.
@@ -26,10 +22,10 @@ export class ServiceModule {
    * @param factories An array of service factories that this module will manage.
    */
   private constructor(readonly factories: GenericFactory[]) {
-    checkCircularDependencies(this.factories);
+    checkCircularDependencies(this.factories)
     factories.forEach((factory) => {
-      checkMissingDependencies(factory, this.factories);
-    });
+      checkMissingDependencies(factory, this.factories)
+    })
   }
 
   /**
@@ -40,15 +36,15 @@ export class ServiceModule {
    * @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);
-    });
+    const factory = this.factories.find((candidate: GenericFactory) => {
+      return isSuitable(key, candidate)
+    })
 
     // 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
@@ -56,14 +52,14 @@ export class ServiceModule {
       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 new ServiceSelector(this, dependencyKey)
         }
-        return this.get(dependencyKey);
+        return this.get(dependencyKey)
       }),
-    );
+    )
 
     // Call the factory to retrieve the dependency
-    return factory.initialize(...dependencies);
+    return factory.initialize(...dependencies)
   }
 
   /**
@@ -74,12 +70,12 @@ export class ServiceModule {
    */
   public async getOrNull<T>(key: ServiceKey<T>): Promise<T | null> {
     try {
-      return await this.get(key);
+      return await this.get(key)
     } catch (error) {
       if (error instanceof ServiceFactoryNotFoundError) {
-        return null;
+        return null
       }
-      throw error;
+      throw error
     }
   }
 
@@ -96,9 +92,9 @@ export class ServiceModule {
   public dispose(scope?: ServiceScope) {
     const factories = scope
       ? this.factories.filter((f) => f.scope === scope)
-      : this.factories;
+      : this.factories
 
-    factories.forEach((factory) => factory.dispose?.());
+    factories.forEach((factory) => factory.dispose?.())
   }
 
   /**
@@ -107,44 +103,24 @@ export class ServiceModule {
    * If multiple factories provide the same
    * ServiceKey, the last one in the list takes precedence.
    *
-   * When a listener is provided, every factory is wrapped with instrumentation:
-   * the listener is notified when a service is initialized or disposed and when
-   * a method is called on a service instance, and may return an EventSpan per
-   * operation to observe its completion. Service instances are wrapped in a
-   * Proxy to observe method calls, and errors are rethrown after being
-   * reported, so behavior is otherwise unchanged.
-   *
    * @param entries - An array of ServiceModule or GenericFactory
    * instances to be processed into a single ServiceModule.
-   * @param listener - An optional ServiceEventListener notified of service
-   * lifecycle events and method calls in the resulting module.
    * @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)[],
-    listener?: ServiceModuleListener,
-  ): ServiceModule {
+  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>();
+    const byKey = new Map<symbol, GenericFactory>()
     // Later factories overwrite earlier ones (last-wins)
     for (const f of flattened) {
-      byKey.set(f.provides.symbol, f);
-    }
-
-    if (listener) {
-      return new ServiceModule(
-        Array.from(byKey.values()).map((factory) => {
-          return makeObservable(listener, factory);
-        }),
-      );
+      byKey.set(f.provides.symbol, f)
     }
 
-    return new ServiceModule(Array.from(byKey.values()));
+    return new ServiceModule(Array.from(byKey.values()))
   }
 }
 
@@ -155,48 +131,48 @@ export class ServiceModule {
  * @throws {ServiceModuleInitError} If a circular dependency is detected.
  */
 function checkCircularDependencies(factories: GenericFactory[]) {
-  const factoryMap = new Map<symbol, GenericFactory>();
+  const factoryMap = new Map<symbol, GenericFactory>()
   for (const f of factories) {
-    factoryMap.set(f.provides.symbol, f);
+    factoryMap.set(f.provides.symbol, f)
   }
 
-  const visited = new Set<symbol>();
-  const stack = new Set<symbol>();
+  const visited = new Set<symbol>()
+  const stack = new Set<symbol>()
 
   function walk(factory: GenericFactory, path: string[]) {
-    const symbol = factory.provides.symbol;
+    const symbol = factory.provides.symbol
 
     if (stack.has(symbol)) {
-      const cyclePath = [...path, factory.provides.name].join(' -> ');
+      const cyclePath = [...path, factory.provides.name].join(' -> ')
       throw new ServiceModuleInitError(
         `Circular dependency detected: ${cyclePath}`,
-      );
+      )
     }
 
     if (visited.has(symbol)) {
-      return;
+      return
     }
 
-    visited.add(symbol);
-    stack.add(symbol);
+    visited.add(symbol)
+    stack.add(symbol)
 
     for (const depKey of factory.dependsOn) {
       const keysToCheck =
-        depKey instanceof ServiceSelectorKey ? depKey.values : [depKey];
+        depKey instanceof ServiceSelectorKey ? depKey.values : [depKey]
 
       for (const key of keysToCheck) {
-        const depFactory = factoryMap.get(key.symbol);
+        const depFactory = factoryMap.get(key.symbol)
         if (depFactory) {
-          walk(depFactory, [...path, factory.provides.name]);
+          walk(depFactory, [...path, factory.provides.name])
         }
       }
     }
 
-    stack.delete(symbol);
+    stack.delete(symbol)
   }
 
   for (const factory of factories) {
-    walk(factory, []);
+    walk(factory, [])
   }
 }
 
@@ -211,31 +187,31 @@ function checkMissingDependencies(
   factory: GenericFactory,
   factories: GenericFactory[],
 ) {
-  const missingDependencies: GenericKey[] = [];
+  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);
+          missingDependencies.push(key)
         }
-      });
+      })
     } else if (!isRegistered(dependencyKey, factories)) {
-      missingDependencies.push(dependencyKey);
+      missingDependencies.push(dependencyKey)
     }
-  });
+  })
 
   if (missingDependencies.length === 0) {
-    return;
+    return
   }
 
   const dependencyList = missingDependencies
     .map((dependencyKey) => ` -> ${dependencyKey.name}`)
-    .join('\n');
+    .join('\n')
   throw new ServiceModuleInitError(
     `${factory.provides.name} will fail because it depends on:\n ${dependencyList}`,
-  );
+  )
 }
 
 /**
@@ -246,7 +222,7 @@ function checkMissingDependencies(
  * @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);
+  return factories.some((factory) => factory.provides?.symbol === key?.symbol)
 }
 
 /**
@@ -260,145 +236,5 @@ 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;
-}
-
-/**
- * Wraps a given service factory with instrumentation to notify a listener of
- * lifecycle events and method calls.
- *
- * For each of initialize, dispose, and method calls, the listener is invoked
- * at the start of the operation and may return an EventSpan whose `end` is
- * called with the outcome when the operation finishes. Errors are rethrown
- * after being reported.
- *
- * @param listener The listener notified of lifecycle and method call events.
- * @param delegate The original service factory to be instrumented.
- * @return A new service factory that provides the same dependencies but includes event notification logic.
- */
-function makeObservable<T, D extends readonly ServiceKey<any>[]>(
-  listener: ServiceModuleListener,
-  delegate: ServiceFactory<any, D>,
-): ServiceFactory<T, D> {
-  const key = delegate.provides;
-
-  return ServiceFactory.singleton({
-    scope: delegate.scope,
-    provides: delegate.provides,
-    dependsOn: delegate.dependsOn,
-    dispose: () => {
-      const dispose = delegate.dispose;
-      if (dispose) {
-        const span = listener.onDispose?.({ key });
-        try {
-          invokeWithin(span, dispose);
-        } catch (error) {
-          span?.end?.({ type: 'failure', error });
-          throw error;
-        }
-        span?.end?.({ type: 'success', value: undefined });
-      }
-    },
-    initialize: async (...args) => {
-      const span = listener.onInitialize?.({ key });
-      try {
-        const instance = observeMethodCalls(
-          await invokeWithin(span, () => delegate.initialize(...args)),
-          listener,
-          key,
-        );
-        span?.end?.({ type: 'success', value: instance });
-        return instance;
-      } catch (error) {
-        span?.end?.({ type: 'failure', error });
-        throw error;
-      }
-    },
-  });
-}
-
-/**
- * Wraps an object with a Proxy to notify the listener of method calls.
- *
- * Methods returning a promise report their outcome when the promise
- * settles, not when the method returns.
- *
- * @param thing The object whose method calls need to be observed.
- * @param listener The listener notified of method call events.
- * @param key The service key used to identify the service in events.
- * @return A Proxy wrapping the input object, with all method calls being reported.
- */
-function observeMethodCalls(
-  thing: any,
-  listener: ServiceModuleListener,
-  key: ServiceKey<unknown>,
-): any {
-  if (typeof thing !== 'object' || thing === null) {
-    return thing;
-  }
-
-  const className = classNameOf(thing);
-
-  return new Proxy(thing, {
-    get(target, prop) {
-      const value = Reflect.get(target, prop);
-      if (typeof value === 'function' && typeof prop === 'string') {
-        return (...args: unknown[]) => {
-          const span = listener.onMethodCall?.({
-            key,
-            className,
-            functionName: prop,
-            args,
-          });
-          try {
-            const result = invokeWithin(span, () => value.apply(target, args));
-            if (result instanceof Promise) {
-              return result.then(
-                (resolved) => {
-                  span?.end?.({ type: 'success', value: resolved });
-                  return resolved;
-                },
-                (error) => {
-                  span?.end?.({ type: 'failure', error });
-                  throw error;
-                },
-              );
-            }
-            span?.end?.({ type: 'success', value: result });
-            return result;
-          } catch (error) {
-            span?.end?.({ type: 'failure', error });
-            throw error;
-          }
-        };
-      }
-      return value;
-    },
-  });
-}
-
-/**
- * Invokes an operation through the EventSpan's `run` wrapper when the
- * listener provided one, so it can establish ambient state (tracing
- * context) around the operation; invokes the operation directly otherwise.
- *
- * @param span The EventSpan returned by the listener, if any.
- * @param fn The thunk performing the operation.
- * @returns The value returned by `fn`.
- */
-function invokeWithin<T>(span: EventSpan | void, fn: () => T): T {
-  return span?.run ? span.run(fn) : fn();
-}
-
-/**
- * Resolves the class name of a service instance, or undefined for values
- * that are not instances of a named class (plain object literals,
- * null-prototype objects).
- *
- * @param thing The service instance to inspect.
- * @returns The constructor name, or undefined when there is none to report.
- */
-function classNameOf(thing: object): string | undefined {
-  const name = thing.constructor?.name;
-  return name && name !== 'Object' ? name : undefined;
+  return factory?.provides?.symbol === key?.symbol
 }

package/src/serviceScope.ts

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

package/src/serviceSelector.ts

@@ -1,5 +1,5 @@
-import { ServiceKey, ServiceSelectorKey } from './serviceKey';
-import { ServiceModule } from './serviceModule';
+import { ServiceKey, ServiceSelectorKey } from './serviceKey'
+import { ServiceModule } from './serviceModule'
 
 /**
  * A runtime selector that provides access to multiple service implementations of the same type.
@@ -63,6 +63,6 @@ export class ServiceSelector<T> {
    * ```
    */
   get(key: ServiceKey<T>): Promise<T> {
-    return this.serviceModule.get(key);
+    return this.serviceModule.get(key)
   }
-}
+}