@vercube/di 1.2.1 → 1.3.0

package/dist/index.d.mts

@@ -3,7 +3,7 @@
  * This is base class for all property decorators used in application. Decorator class must extend this one.
  * This class instance is created using IOC container so you can @Inject() things here.
  */
-declare abstract class BaseDecorator<T = any, P = any> {
+export declare abstract class BaseDecorator<T = any, P = any> {
   /** Holds options object that is passed as 2nd argument in createDecorator() factory */
   options: T;
   /** Holds class instance that is decorated */
@@ -29,11 +29,11 @@ declare abstract class BaseDecorator<T = any, P = any> {
 }
 //#endregion
 //#region src/Domain/ContainerEvents.d.ts
-type OnExpandedEvent = (serviceKeys: IOC.ServiceKey[]) => void;
+export type OnExpandedEvent = (serviceKeys: IOC.ServiceKey[]) => void;
 /**
  * This class allows for container to listen on various IOC events.
  */
-declare class ContainerEvents {
+export declare class ContainerEvents {
   private fOnExpanded;
   /**
    * Registers to container "onExpanded" event.
@@ -52,7 +52,7 @@ declare class ContainerEvents {
  * This is new implementation of IOC Container. It mimics Inversify.js container a little bit but its
  * simpler and (probably) more performant on larger scales.
  */
-declare class Container {
+export declare class Container {
   protected fContext: string | undefined;
   protected fLocked: boolean;
   protected fDefaultParams: IOC.ContainerParams;
@@ -61,6 +61,7 @@ declare class Container {
   protected fSingletonInstances: Map<IOC.ServiceKey, IOC.Instance>;
   protected fInjectMethod: IOC.InjectMethod;
   protected fContainerEvents: ContainerEvents;
+  protected fRevision: number;
   /**
    * Constructor for container.
    * @param params initial params for container
@@ -92,6 +93,13 @@ declare class Container {
    * @returns {string} the context of the container
    */
   get context(): string | undefined;
+  /**
+   * Counter that changes whenever a binding is added, replaced or first
+   * instantiated - that is, whenever a description of this container would
+   * come out different.
+   * @returns {number} the current revision
+   */
+  get revision(): number;
   /**
    * Binds particular key to container in singleton scope. Multiple queries/injects of this
    * service will always return the same instance.
@@ -230,7 +238,7 @@ declare class Container {
 /**
  * This module exports various types used in IOC system.
  */
-declare namespace IOC {
+export declare namespace IOC {
   /**
    * This is a key that we use to identify service. Symbol is new way of doing it, however we
    * also keep standard/abstract classes for backward compatability.
@@ -337,7 +345,7 @@ declare namespace IOC {
  * @param key key to inject
  * @returns decorator
  */
-declare function Inject(key: IOC.ServiceKey): Function;
+export declare function Inject(key: IOC.ServiceKey): Function;
 //#endregion
 //#region src/Decorators/InjectOptional.d.ts
 /**
@@ -345,7 +353,7 @@ declare function Inject(key: IOC.ServiceKey): Function;
  * @param key key to inject
  * @returns decorator
  */
-declare function InjectOptional(key: IOC.ServiceKey): Function;
+export declare function InjectOptional(key: IOC.ServiceKey): Function;
 //#endregion
 //#region src/Decorators/Init.d.ts
 /**
@@ -353,7 +361,7 @@ declare function InjectOptional(key: IOC.ServiceKey): Function;
  * Use this decorator to run initialization logic for runtime-loaded container dependencies.
  * @returns {Function} Decorator function that creates an InitDecorator instance
  */
-declare function Init(): Function;
+export declare function Init(): Function;
 //#endregion
 //#region src/Decorators/Destroy.d.ts
 /**
@@ -372,7 +380,7 @@ declare function Init(): Function;
  * ```
  * @returns {Function} Decorator function that creates a DestroyDecorator instance
  */
-declare function Destroy(): Function;
+export declare function Destroy(): Function;
 //#endregion
 //#region src/Decorators/Injectable.d.ts
 /**
@@ -382,48 +390,95 @@ declare function Destroy(): Function;
  * This decorator is intentionally a no-op at runtime - it exists solely as a
  * compile-time marker that the build-time scanner can detect via AST analysis.
  */
-declare function Injectable(): ClassDecorator;
+export declare function Injectable(): ClassDecorator;
 //#endregion
-//#region src/Domain/DevtoolsHook.d.ts
-/**
- * Global property name for the IOC devtools hook.
- */
-declare const IOC_DEVTOOLS_HOOK_KEY = "__VERCUBE_DEVTOOLS_HOOK__";
-/**
- * A single service resolution record emitted when the container constructs an instance.
- */
-interface IOCResolveRecord {
-  /** Service key that was resolved. */
-  key: IOC.ServiceKey;
-  /** Human readable name of the service key. */
-  name: string;
-  /** Factory type used to build the instance. */
-  type: IOC.ServiceFactoryType;
-  /** Context of the container that performed the resolution. */
-  context: string | undefined;
-  /** Timestamp (ms) before construction. */
-  start: number;
-  /** Timestamp (ms) after construction and injection. */
-  end: number;
-}
+//#region src/Types/DescribeTypes.d.ts
 /**
- * Optional hook for observing the IOC container.
+ * Types describing a container's contents.
+ *
+ * The description is built from binding metadata only. Nothing is resolved, so
+ * inspecting a container never constructs a service the application itself
+ * never asked for.
  */
-interface IOCDevtoolsHook {
-  /** Called once for every {@link Container} instance after construction. */
-  onContainerCreated?: (container: Container) => void;
-  /** Called whenever the container constructs a new service instance. */
-  onResolved?: (record: IOCResolveRecord) => void;
+export declare namespace Describe {
+  /** How a binding produces its value. */
+  type ServiceKind = 'singleton' | 'transient' | 'instance';
+  /** One `@Inject` / `@InjectOptional` declaration. */
+  interface Dependency {
+    /** Id of the service this resolves to, or `unbound:Name` when nothing is bound. */
+    id: string;
+    /** Display name of the dependency key. */
+    name: string;
+    /** Property the dependency is injected into. */
+    property: string;
+    /** Whether the declaration was `@InjectOptional`. */
+    optional: boolean;
+    /** Whether something is actually bound under the key. */
+    bound: boolean;
+  }
+  /** A service in the container. */
+  interface ServiceNode {
+    /** Unique id. The display name, suffixed with `#n` when names collide. */
+    id: string;
+    /** Display name of the binding key. */
+    name: string;
+    kind: ServiceKind;
+    /**
+     * Category of the service.
+     *
+     * The container itself can only tell a class from a plain value; anything
+     * finer - controller, middleware, plugin - comes from the `annotate`
+     * callback, because only the framework layer knows what those are.
+     */
+    role: string;
+    /** Implementation class name, when it differs from the key. */
+    implementation: string | null;
+    /** Whether an instance already exists. */
+    instantiated: boolean;
+    /** Whether the key is a symbol. */
+    symbol: boolean;
+    dependencies: Dependency[];
+    /** Number of services depending on this one. */
+    dependents: number;
+    /** Extra fields contributed by `annotate`. */
+    [extra: string]: unknown;
+  }
+  /** A directed dependency edge. */
+  interface ServiceEdge {
+    from: string;
+    to: string;
+    property: string;
+    optional: boolean;
+  }
+  /** Everything known about a container's bindings. */
+  interface ContainerDescription {
+    /** Container label, when one was given. */
+    context?: string;
+    nodes: ServiceNode[];
+    edges: ServiceEdge[];
+    /** Dependency cycles, each as the ordered ids forming the loop. */
+    cycles: string[][];
+    /** Number of services that were never instantiated. */
+    unusedCount: number;
+  }
+  /** What `annotate` is told about the node it is classifying. */
+  interface AnnotateContext {
+    key: IOC.ServiceKey;
+    def: Readonly<IOC.ServiceDef>;
+    /** Constructor behind the binding, or null for plain values. */
+    ctor: (Function & {
+      prototype: unknown;
+    }) | null;
+  }
+  /** Options for {@link describeContainer}. */
+  interface Options {
+    /**
+     * Refines a node before it is added to the description. Typically sets
+     * `role` and attaches framework-specific fields.
+     */
+    annotate?: (node: ServiceNode, context: AnnotateContext) => void;
+  }
 }
-/**
- * Installs or replaces the devtools hook.
- * @param hook hook implementation, or `undefined` to uninstall
- */
-declare function setIOCDevtoolsHook(hook: IOCDevtoolsHook | undefined): void;
-/**
- * Returns the currently installed devtools hook, if any.
- */
-declare function getIOCDevtoolsHook(): IOCDevtoolsHook | undefined;
 //#endregion
 //#region src/Domain/Engine.d.ts
 /**
@@ -468,13 +523,119 @@ declare function getDeps(instance: IOC.Instance): IClassDep[];
  * @param method inject method, "lazy" queries dep during property access while "static" injects during class creation
  */
 declare function injectDeps(container: Container, instance: IOC.Instance, method: IOC.InjectMethod): void;
-declare const IOCEngine: {
+export declare const IOCEngine: {
   registerInject: typeof registerInject;
   getEntryForClass: typeof getEntryForClass;
   injectDeps: typeof injectDeps;
   getDeps: typeof getDeps;
 };
 //#endregion
+//#region src/Domain/Describe.d.ts
+/**
+ * Produces a readable label for any service key.
+ *
+ * @param key - Service key from a `bind*` call
+ * @returns Display name for the key
+ */
+export declare function describeKey(key: IOC.ServiceKey): string;
+/**
+ * Names the value a key was bound to, or `null` when it adds no information.
+ *
+ * @param key - Service key
+ * @param value - Bound implementation or instance
+ * @returns Implementation name, or null
+ */
+export declare function describeImplementation(key: IOC.ServiceKey, value: unknown): string | null;
+/**
+ * Resolves the class constructor behind a service definition.
+ *
+ * @param def - Service definition from the container
+ * @returns The constructor, or null for plain values
+ */
+export declare function resolveConstructor(def: Readonly<IOC.ServiceDef>): (Function & {
+  prototype: unknown;
+}) | null;
+/**
+ * Collects every injection declaration of a class, inherited ones included.
+ *
+ * @param ctor - Class constructor to inspect
+ * @returns Dependency declarations, nearest prototype first
+ */
+export declare function collectClassDeps(ctor: (Function & {
+  prototype: unknown;
+}) | null): IClassDep[];
+/**
+ * Maps a binding's factory type onto its description kind.
+ *
+ * @param type - Factory type recorded by the container
+ * @returns The matching kind
+ */
+export declare function toServiceKind(type: IOC.ServiceFactoryType): Describe.ServiceKind;
+/**
+ * Builds a serialisable description of a container.
+ *
+ * Reads `container.services`, which is binding metadata, never
+ * `getAllServices()`, which would construct every registered service. An
+ * inspector that instantiates what it inspects is not an inspector.
+ *
+ * @param container - The container to describe
+ * @param options - Optional annotation callback
+ * @returns Nodes, edges, cycles and the unused-service count
+ */
+export declare function describeContainer(container: Container, options?: Describe.Options): Describe.ContainerDescription;
+//#endregion
+//#region src/Domain/DevtoolsHook.d.ts
+/**
+ * Global property name for the IOC observer registry.
+ */
+export declare const IOC_DEVTOOLS_HOOK_KEY = "__VERCUBE_DEVTOOLS_HOOK__";
+/**
+ * A single service resolution record emitted when the container constructs an instance.
+ */
+export interface IOCResolveRecord {
+  /** Service key that was resolved. */
+  key: IOC.ServiceKey;
+  /** Human readable name of the service key. */
+  name: string;
+  /** Factory type used to build the instance. */
+  type: IOC.ServiceFactoryType;
+  /** Context of the container that performed the resolution. */
+  context: string | undefined;
+  /** Timestamp (ms) before construction. */
+  start: number;
+  /** Timestamp (ms) after construction and injection. */
+  end: number;
+}
+/**
+ * Optional hook for observing the IOC container.
+ */
+export interface IOCDevtoolsHook {
+  /** Called once for every {@link Container} instance after construction. */
+  onContainerCreated?: (container: Container) => void;
+  /** Called whenever the container constructs a new service instance. */
+  onResolved?: (record: IOCResolveRecord) => void;
+}
+/**
+ * Installs an observer.
+ *
+ * @param hook - The observer to install
+ * @returns A function that removes it again
+ */
+export declare function addIOCDevtoolsHook(hook: IOCDevtoolsHook): () => void;
+/**
+ * Replaces every installed observer with `hook`, or removes them all.
+ *
+ * @param hook - The observer to install, or `undefined` to uninstall everything
+ * @deprecated Use {@link addIOCDevtoolsHook}, which does not evict other observers.
+ */
+export declare function setIOCDevtoolsHook(hook: IOCDevtoolsHook | undefined): void;
+/**
+ * Returns the fan-out hook the container calls into.
+ *
+ * @returns The registry, or undefined when no observer is installed
+ */
+export declare function getIOCDevtoolsHook(): IOCDevtoolsHook | undefined;
+//#endregion
 //#region src/Utils/Utils.d.ts
 /**
  * This function generates new service key for particular service. Providing
@@ -484,18 +645,18 @@ declare const IOCEngine: {
  * @param name name of the service
  * @returns unique service identity
  */
-declare function Identity(name: string): IOC.Identity;
+export declare function Identity(name: string): IOC.Identity;
 /**
  * A simple type of constructor for class "T"
  */
-interface IClassType<T> {
+export interface IClassType<T> {
   new (): T;
 }
 /**
  * Holds decorator entry struct. It is saved in __decorators array for every class and holds
  * various informations.
  */
-interface IDecoratorEntry {
+export interface IDecoratorEntry {
   classType: any;
   params: any;
   target: any;
@@ -507,11 +668,11 @@ interface IDecoratorEntry {
  * array that holds information about all decorators used in this class. It will be used later for
  * turning those declarations for real code.
  */
-interface IDecoratedPrototype {
+export interface IDecoratedPrototype {
   __decorators?: IDecoratorEntry[];
   __metadata?: any;
 }
-interface IDecoratedInstance {
+export interface IDecoratedInstance {
   __decoratorInstances?: BaseDecorator<any>[];
 }
 /**
@@ -521,14 +682,14 @@ interface IDecoratedInstance {
  * @param params custom options object that will be availalbe in "options" property of decorator class
  * @return ES6 decorator function
  */
-declare function createDecorator<P, T extends BaseDecorator<P>>(decoratorClass: IClassType<T>, params: P): Function;
+export declare function createDecorator<P, T extends BaseDecorator<P>>(decoratorClass: IClassType<T>, params: P): Function;
 /**
  * This function initializes all registered decorators on particular instance. It must be called in order
  * for decorator code work in particular class.
  * @param target class instance to sue
  * @param container IOC container for context
  */
-declare function initializeDecorators(target: IDecoratedInstance, container: Container): void;
+export declare function initializeDecorators(target: IDecoratedInstance, container: Container): void;
 /**
  * This function releases all decorators applied to target instance by calling their .destroyed()
  * method. Its used to provide a way for cleanup for decorators. @see BaseDecorator.destroy()
@@ -536,18 +697,18 @@ declare function initializeDecorators(target: IDecoratedInstance, container: Con
  * @param target instance of class that should have decorators cleaned up
  * @param container ioc container
  */
-declare function destroyDecorators(target: IDecoratedInstance, container: Container): void;
+export declare function destroyDecorators(target: IDecoratedInstance, container: Container): void;
 /**
  * This function is responsible for preparing IOC container to work with all decorators. It simply
  * initializes all decorators on all services registered.
  * @param container IOC container
  */
-declare function initializeContainer(container: Container): void;
+export declare function initializeContainer(container: Container): void;
 /**
  * This function is responsible for preparing IOC container to work with all decorators. It simply
  * initializes all decorators on all services registered.
  * @param container IOC container
  */
-declare function destroyContainer(container: Container): void;
+export declare function destroyContainer(container: Container): void;
 //#endregion
-export { BaseDecorator, Container, ContainerEvents, Destroy, type IClassDep, type IClassMapEntry, IClassType, IDecoratedInstance, IDecoratedPrototype, IDecoratorEntry, IOC, IOCDevtoolsHook, IOCEngine, IOCResolveRecord, IOC_DEVTOOLS_HOOK_KEY, Identity, Init, Inject, InjectOptional, Injectable, OnExpandedEvent, createDecorator, destroyContainer, destroyDecorators, getIOCDevtoolsHook, initializeContainer, initializeDecorators, setIOCDevtoolsHook };
+export type { IClassDep, IClassMapEntry };

package/dist/index.mjs

@@ -154,23 +154,64 @@ var ContainerEvents = class {
 //#endregion
 //#region src/Domain/DevtoolsHook.ts
 /**
-* Global property name for the IOC devtools hook.
+* Global property name for the IOC observer registry.
 */
 const IOC_DEVTOOLS_HOOK_KEY = "__VERCUBE_DEVTOOLS_HOOK__";
-let devtoolsHook = globalThis[IOC_DEVTOOLS_HOOK_KEY];
 /**
-* Installs or replaces the devtools hook.
-* @param hook hook implementation, or `undefined` to uninstall
+* Returns the global registry, creating it on first use.
+*
+* @returns The registry
+*/
+function registry() {
+	let current = globalThis[IOC_DEVTOOLS_HOOK_KEY];
+	if (!current) {
+		const observers = [];
+		current = {
+			observers,
+			onContainerCreated(container) {
+				for (const observer of observers) observer.onContainerCreated?.(container);
+			},
+			onResolved(record) {
+				for (const observer of observers) observer.onResolved?.(record);
+			}
+		};
+		globalThis[IOC_DEVTOOLS_HOOK_KEY] = current;
+	}
+	return current;
+}
+/**
+* Installs an observer.
+*
+* @param hook - The observer to install
+* @returns A function that removes it again
+*/
+function addIOCDevtoolsHook(hook) {
+	const observers = registry().observers;
+	observers.push(hook);
+	return () => {
+		const index = observers.indexOf(hook);
+		if (index !== -1) observers.splice(index, 1);
+	};
+}
+/**
+* Replaces every installed observer with `hook`, or removes them all.
+*
+* @param hook - The observer to install, or `undefined` to uninstall everything
+* @deprecated Use {@link addIOCDevtoolsHook}, which does not evict other observers.
 */
 function setIOCDevtoolsHook(hook) {
-	devtoolsHook = hook;
-	globalThis[IOC_DEVTOOLS_HOOK_KEY] = hook;
+	const current = registry();
+	current.observers.length = 0;
+	if (hook) current.observers.push(hook);
 }
 /**
-* Returns the currently installed devtools hook, if any.
+* Returns the fan-out hook the container calls into.
+*
+* @returns The registry, or undefined when no observer is installed
 */
 function getIOCDevtoolsHook() {
-	return devtoolsHook;
+	const current = globalThis[IOC_DEVTOOLS_HOOK_KEY];
+	return current && current.observers.length > 0 ? current : void 0;
 }
 //#endregion
 //#region src/Domain/Container.ts
@@ -190,6 +231,7 @@ var Container = class Container {
 	fSingletonInstances = /* @__PURE__ */ new Map();
 	fInjectMethod = IOC.InjectMethod.STATIC;
 	fContainerEvents = new ContainerEvents();
+	fRevision = 0;
 	/**
 	* Constructor for container.
 	* @param params initial params for container
@@ -239,6 +281,15 @@ var Container = class Container {
 		return this.fContext;
 	}
 	/**
+	* Counter that changes whenever a binding is added, replaced or first
+	* instantiated - that is, whenever a description of this container would
+	* come out different.
+	* @returns {number} the current revision
+	*/
+	get revision() {
+		return this.fRevision;
+	}
+	/**
 	* Binds particular key to container in singleton scope. Multiple queries/injects of this
 	* service will always return the same instance.
 	*
@@ -258,6 +309,7 @@ var Container = class Container {
 			this.fServices.delete(key);
 		}
 		this.fServices.set(key, newDef);
+		this.fRevision++;
 		this.fNewQueue.set(key, newDef);
 	}
 	/**
@@ -275,6 +327,7 @@ var Container = class Container {
 		const existingServiceDef = this.fServices.get(key);
 		if (existingServiceDef) this.internalDispose(existingServiceDef);
 		this.fServices.set(key, newDef);
+		this.fRevision++;
 		this.fNewQueue.set(key, newDef);
 	}
 	/**
@@ -294,6 +347,7 @@ var Container = class Container {
 		const existingServiceDef = this.fServices.get(key);
 		if (existingServiceDef) this.internalDispose(existingServiceDef);
 		this.fServices.set(key, newDef);
+		this.fRevision++;
 		this.fNewQueue.set(key, newDef);
 	}
 	/**
@@ -319,6 +373,7 @@ var Container = class Container {
 		const existingServiceDef = this.fServices.get(key);
 		if (existingServiceDef) this.internalDispose(existingServiceDef);
 		this.fServices.set(key, newDef);
+		this.fRevision++;
 		this.fNewQueue.set(key, newDef);
 	}
 	/**
@@ -457,7 +512,10 @@ var Container = class Container {
 		const start = onResolved ? performance.now() : 0;
 		const constructor = serviceDef.serviceValue;
 		const instance = new constructor();
-		if (singleton) this.fSingletonInstances.set(serviceDef.serviceKey, instance);
+		if (singleton) {
+			this.fSingletonInstances.set(serviceDef.serviceKey, instance);
+			this.fRevision++;
+		}
 		try {
 			this.internalProcessInjects(instance, this.fInjectMethod);
 		} catch (error) {
@@ -572,7 +630,7 @@ let IOC;
 */
 const classMap = /* @__PURE__ */ new Map();
 globalThis.__IOCClassMap = globalThis.__IOCClassMap ?? classMap;
-const ROOT_PROTO = Object.getPrototypeOf({});
+const ROOT_PROTO$1 = Object.getPrototypeOf({});
 /**
 * Retrieves the class dependency metadata map used for IOC injection purposes.
 *
@@ -667,7 +725,7 @@ function injectDeps(container, instance, method) {
 			}
 		}
 		prototype = Object.getPrototypeOf(prototype);
-	} while (prototype && prototype !== ROOT_PROTO);
+	} while (prototype && prototype !== ROOT_PROTO$1);
 }
 const IOCEngine = {
 	registerInject,
@@ -770,4 +828,215 @@ function Injectable() {
 	return () => {};
 }
 //#endregion
-export { BaseDecorator, Container, ContainerEvents, Destroy, IOC, IOCEngine, IOC_DEVTOOLS_HOOK_KEY, Identity, Init, Inject, InjectOptional, Injectable, createDecorator, destroyContainer, destroyDecorators, getIOCDevtoolsHook, initializeContainer, initializeDecorators, setIOCDevtoolsHook };
+//#region src/Domain/Describe.ts
+/** Prototype of a plain object; the stop condition when walking prototype chains. */
+const ROOT_PROTO = Object.getPrototypeOf({});
+/**
+* Produces a readable label for any service key.
+*
+* @param key - Service key from a `bind*` call
+* @returns Display name for the key
+*/
+function describeKey(key) {
+	if (typeof key === "symbol") return key.description ?? "Symbol()";
+	if (typeof key === "string") return key;
+	if (typeof key === "function") return key.name || "Anonymous";
+	if (typeof key === "object" && key !== null) return key.constructor?.name ?? "Object";
+	return "Unknown";
+}
+/**
+* Names the value a key was bound to, or `null` when it adds no information.
+*
+* @param key - Service key
+* @param value - Bound implementation or instance
+* @returns Implementation name, or null
+*/
+function describeImplementation(key, value) {
+	if (value === key) return null;
+	if (typeof value === "function") {
+		const name = value.name;
+		return name && name !== describeKey(key) ? name : null;
+	}
+	if (typeof value === "object" && value !== null) {
+		const name = value.constructor?.name;
+		return name && name !== describeKey(key) ? name : null;
+	}
+	return null;
+}
+/**
+* Resolves the class constructor behind a service definition.
+*
+* @param def - Service definition from the container
+* @returns The constructor, or null for plain values
+*/
+function resolveConstructor(def) {
+	const value = def.serviceValue;
+	if (typeof value === "function") return value;
+	if (typeof value === "object" && value !== null) {
+		const ctor = value.constructor;
+		if (ctor === Object || ctor === Array || typeof ctor !== "function") return null;
+		return ctor;
+	}
+	return null;
+}
+/**
+* Collects every injection declaration of a class, inherited ones included.
+*
+* @param ctor - Class constructor to inspect
+* @returns Dependency declarations, nearest prototype first
+*/
+function collectClassDeps(ctor) {
+	if (!ctor?.prototype) return [];
+	const deps = [];
+	const seen = /* @__PURE__ */ new Set();
+	let proto = ctor.prototype;
+	while (proto && proto !== ROOT_PROTO) {
+		const entry = IOCEngine.getEntryForClass({ prototype: proto });
+		for (const dep of entry?.deps ?? []) {
+			if (seen.has(dep.propertyName)) continue;
+			seen.add(dep.propertyName);
+			deps.push(dep);
+		}
+		proto = Object.getPrototypeOf(proto);
+	}
+	return deps;
+}
+/**
+* Maps a binding's factory type onto its description kind.
+*
+* @param type - Factory type recorded by the container
+* @returns The matching kind
+*/
+function toServiceKind(type) {
+	switch (type) {
+		case IOC.ServiceFactoryType.CLASS_SINGLETON: return "singleton";
+		case IOC.ServiceFactoryType.CLASS: return "transient";
+		default: return "instance";
+	}
+}
+/**
+* Builds a serialisable description of a container.
+*
+* Reads `container.services`, which is binding metadata, never
+* `getAllServices()`, which would construct every registered service. An
+* inspector that instantiates what it inspects is not an inspector.
+*
+* @param container - The container to describe
+* @param options - Optional annotation callback
+* @returns Nodes, edges, cycles and the unused-service count
+*/
+function describeContainer(container, options = {}) {
+	const services = container.services;
+	const ids = buildIdMap(services);
+	const nodes = [];
+	const edges = [];
+	const dependentCounts = /* @__PURE__ */ new Map();
+	for (const [key, def] of services) {
+		const id = ids.get(key);
+		const name = describeKey(key);
+		const ctor = resolveConstructor(def);
+		const dependencies = [];
+		for (const dep of collectClassDeps(ctor)) {
+			const targetId = ids.get(dep.dependency);
+			const targetName = describeKey(dep.dependency);
+			const optional = dep.type === IOC.DependencyType.OPTIONAL;
+			dependencies.push({
+				id: targetId ?? `unbound:${targetName}`,
+				name: targetName,
+				property: dep.propertyName,
+				optional,
+				bound: targetId !== void 0
+			});
+			if (targetId !== void 0) {
+				edges.push({
+					from: id,
+					to: targetId,
+					property: dep.propertyName,
+					optional
+				});
+				dependentCounts.set(targetId, (dependentCounts.get(targetId) ?? 0) + 1);
+			}
+		}
+		const node = {
+			id,
+			name,
+			kind: toServiceKind(def.type),
+			role: ctor ? "service" : "value",
+			implementation: describeImplementation(key, def.serviceValue),
+			instantiated: def.type === IOC.ServiceFactoryType.INSTANCE || container.hasInstance(key),
+			symbol: typeof key === "symbol",
+			dependencies,
+			dependents: 0
+		};
+		options.annotate?.(node, {
+			key,
+			def,
+			ctor
+		});
+		nodes.push(node);
+	}
+	for (const node of nodes) node.dependents = dependentCounts.get(node.id) ?? 0;
+	return {
+		context: container.context,
+		nodes,
+		edges,
+		cycles: findCycles(nodes, edges),
+		unusedCount: nodes.filter((node) => !node.instantiated).length
+	};
+}
+/**
+* Assigns a stable, unique id to every service key.
+*
+* @param services - The container's service map
+* @returns Map of service key to unique id
+*/
+function buildIdMap(services) {
+	const ids = /* @__PURE__ */ new Map();
+	const used = /* @__PURE__ */ new Map();
+	for (const key of services.keys()) {
+		const base = describeKey(key);
+		const seen = used.get(base) ?? 0;
+		used.set(base, seen + 1);
+		ids.set(key, seen === 0 ? base : `${base}#${seen}`);
+	}
+	return ids;
+}
+/**
+* Finds dependency cycles by depth-first search with colour marking.
+*
+* Each cycle is reported once, rotated to start at its lexicographically
+* smallest member so the same loop always serialises identically.
+*
+* @param nodes - Graph nodes
+* @param edges - Graph edges
+* @returns One ordered id list per cycle
+*/
+function findCycles(nodes, edges) {
+	const adjacency = /* @__PURE__ */ new Map();
+	for (const node of nodes) adjacency.set(node.id, []);
+	for (const edge of edges) adjacency.get(edge.from)?.push(edge.to);
+	const state = /* @__PURE__ */ new Map();
+	const path = [];
+	const found = /* @__PURE__ */ new Map();
+	const visit = (id) => {
+		state.set(id, "visiting");
+		path.push(id);
+		for (const next of adjacency.get(id) ?? []) {
+			const nextState = state.get(next);
+			if (nextState === "visiting") {
+				const cycle = path.slice(path.indexOf(next));
+				const smallest = cycle.indexOf([...cycle].sort()[0]);
+				const normalised = [...cycle.slice(smallest), ...cycle.slice(0, smallest)];
+				found.set(normalised.join(" "), normalised);
+				continue;
+			}
+			if (nextState === void 0) visit(next);
+		}
+		path.pop();
+		state.set(id, "done");
+	};
+	for (const node of nodes) if (!state.has(node.id)) visit(node.id);
+	return [...found.values()];
+}
+//#endregion
+export { BaseDecorator, Container, ContainerEvents, Destroy, IOC, IOCEngine, IOC_DEVTOOLS_HOOK_KEY, Identity, Init, Inject, InjectOptional, Injectable, addIOCDevtoolsHook, collectClassDeps, createDecorator, describeContainer, describeImplementation, describeKey, destroyContainer, destroyDecorators, getIOCDevtoolsHook, initializeContainer, initializeDecorators, resolveConstructor, setIOCDevtoolsHook, toServiceKind };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercube/di",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Dependency Injection  module for Vercube framework",
   "repository": {
     "type": "git",