@vercube/di 1.1.7 → 1.2.1

package/dist/index.d.mts

@@ -72,6 +72,17 @@ declare class Container {
    * @returns {Array} array of service keys
    */
   get servicesKeys(): IOC.ServiceKey[];
+  /**
+   * Returns a read-only view of all service definitions without instantiating them.
+   * @returns {ReadonlyMap} map of service key to its definition
+   */
+  get services(): ReadonlyMap<IOC.ServiceKey, Readonly<IOC.ServiceDef>>;
+  /**
+   * Checks whether a singleton instance for a given key has already been constructed.
+   * @param key service key to check
+   * @returns {boolean} true when a singleton instance already exists
+   */
+  hasInstance(key: IOC.ServiceKey): boolean;
   /**
    * Returns events handler.
    */
@@ -189,6 +200,13 @@ declare class Container {
    * @returns class instance
    */
   protected internalResolve(serviceDef: IOC.ServiceDef): IOC.Instance;
+  /**
+   * Constructs a new instance for a service def and injects its dependencies.
+   * @param serviceDef service def to construct
+   * @param singleton whether resulting instance should be cached as a singleton
+   * @returns newly created class instance
+   */
+  protected internalConstruct(serviceDef: IOC.ServiceDef, singleton: boolean): IOC.Instance;
   /**
    * Internally inject deps for particular class..
    * @param instance instance to inject
@@ -366,6 +384,97 @@ declare function Destroy(): Function;
  */
 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;
+}
+/**
+ * Optional hook for observing the IOC container.
+ */
+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 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
+/**
+ * This is a struct that holds information about class dependency - what dependency, which field to inject,etc.
+ */
+interface IClassDep {
+  propertyName: string;
+  dependency: IOC.ServiceKey;
+  type: IOC.DependencyType;
+}
+/**
+ * This holds single "metadata" entry for particular class. It holds all @Inject stuff for class.
+ */
+interface IClassMapEntry {
+  deps: IClassDep[];
+}
+/**
+ * This method registers @Inject() in particular class.
+ * @param prototype class prototype for which we register @Inject()
+ * @param propertyName name of property that is inejcted
+ * @param dependency what we should inject there
+ * @param type type of dependency (standard or optional dependency)
+ */
+declare function registerInject(prototype: IOC.Prototype, propertyName: string, dependency: IOC.ServiceKey, type: IOC.DependencyType): void;
+/**
+ * Returns classmap entry for particular class. It holds information about @Injects for this particular class.
+ * @param classType type of class to check
+ * @returns class map entry or null if cannot be found
+ */
+declare function getEntryForClass(classType: IOC.Newable<unknown>): IClassMapEntry | null;
+/**
+ * Returns array of dependencies for particular class instance.
+ * @param instance class instance
+ * @returns array of @Inject dependencies defined for this class
+ */
+declare function getDeps(instance: IOC.Instance): IClassDep[];
+/**
+ * This method injects stuff into class, using container passed as first argument. We need container as
+ * inject execution is always context based.
+ * @param container container instance that is providing dependencies
+ * @param instance class instance to inject
+ * @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: {
+  registerInject: typeof registerInject;
+  getEntryForClass: typeof getEntryForClass;
+  injectDeps: typeof injectDeps;
+  getDeps: typeof getDeps;
+};
+//#endregion
 //#region src/Utils/Utils.d.ts
 /**
  * This function generates new service key for particular service. Providing
@@ -441,4 +550,4 @@ declare function initializeContainer(container: Container): void;
  */
 declare function destroyContainer(container: Container): void;
 //#endregion
-export { BaseDecorator, Container, Destroy, IClassType, IDecoratedInstance, IDecoratedPrototype, IDecoratorEntry, IOC, Identity, Init, Inject, InjectOptional, Injectable, createDecorator, destroyContainer, destroyDecorators, initializeContainer, initializeDecorators };
+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 };

package/dist/index.mjs

@@ -152,6 +152,27 @@ var ContainerEvents = class {
 	}
 };
 //#endregion
+//#region src/Domain/DevtoolsHook.ts
+/**
+* Global property name for the IOC devtools hook.
+*/
+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
+*/
+function setIOCDevtoolsHook(hook) {
+	devtoolsHook = hook;
+	globalThis[IOC_DEVTOOLS_HOOK_KEY] = hook;
+}
+/**
+* Returns the currently installed devtools hook, if any.
+*/
+function getIOCDevtoolsHook() {
+	return devtoolsHook;
+}
+//#endregion
 //#region src/Domain/Container.ts
 /**
 * This is new implementation of IOC Container. It mimics Inversify.js container a little bit but its
@@ -180,6 +201,7 @@ var Container = class Container {
 		this.fDefaultParams = Object.assign(this.fDefaultParams, params);
 		this.fInjectMethod = params?.injectMethod ?? IOC.InjectMethod.STATIC;
 		this.bindInstance(Container, this);
+		getIOCDevtoolsHook()?.onContainerCreated?.(this);
 	}
 	/**
 	* Returns array of all service keys. This basically returns keys from all .bindXXX calls.
@@ -189,6 +211,21 @@ var Container = class Container {
 		return [...this.fServices.keys()];
 	}
 	/**
+	* Returns a read-only view of all service definitions without instantiating them.
+	* @returns {ReadonlyMap} map of service key to its definition
+	*/
+	get services() {
+		return this.fServices;
+	}
+	/**
+	* Checks whether a singleton instance for a given key has already been constructed.
+	* @param key service key to check
+	* @returns {boolean} true when a singleton instance already exists
+	*/
+	hasInstance(key) {
+		return this.fSingletonInstances.has(key);
+	}
+	/**
 	* Returns events handler.
 	*/
 	get events() {
@@ -377,7 +414,10 @@ var Container = class Container {
 	*/
 	internalGet(key, parent) {
 		const serviceDef = this.fServices.get(key);
-		if (!serviceDef) throw new Error(`Unresolved dependency for [${this.getKeyDescription(key)}]`);
+		if (!serviceDef) {
+			const owner = parent?.constructor?.name;
+			throw new Error(`Unresolved dependency for [${this.getKeyDescription(key)}]${owner ? ` required by [${owner}]` : ""}`);
+		}
 		return this.internalResolve(serviceDef);
 	}
 	/**
@@ -400,24 +440,41 @@ var Container = class Container {
 		switch (serviceDef.type) {
 			case IOC.ServiceFactoryType.INSTANCE: return serviceDef.serviceValue;
 			case IOC.ServiceFactoryType.CLASS_SINGLETON:
-				if (!this.fSingletonInstances.has(serviceDef.serviceKey)) {
-					const constructor = serviceDef.serviceValue;
-					const instance = new constructor();
-					this.fSingletonInstances.set(serviceDef.serviceKey, instance);
-					this.internalProcessInjects(instance, this.fInjectMethod);
-					return instance;
-				}
+				if (!this.fSingletonInstances.has(serviceDef.serviceKey)) return this.internalConstruct(serviceDef, true);
 				return this.fSingletonInstances.get(serviceDef.serviceKey);
-			case IOC.ServiceFactoryType.CLASS: {
-				const constructor = serviceDef.serviceValue;
-				const instance = new constructor();
-				this.internalProcessInjects(instance, this.fInjectMethod);
-				return instance;
-			}
+			case IOC.ServiceFactoryType.CLASS: return this.internalConstruct(serviceDef, false);
 			default: throw new Error(`Container - invalid factory type: ${serviceDef.type}`);
 		}
 	}
 	/**
+	* Constructs a new instance for a service def and injects its dependencies.
+	* @param serviceDef service def to construct
+	* @param singleton whether resulting instance should be cached as a singleton
+	* @returns newly created class instance
+	*/
+	internalConstruct(serviceDef, singleton) {
+		const onResolved = getIOCDevtoolsHook()?.onResolved;
+		const start = onResolved ? performance.now() : 0;
+		const constructor = serviceDef.serviceValue;
+		const instance = new constructor();
+		if (singleton) this.fSingletonInstances.set(serviceDef.serviceKey, instance);
+		try {
+			this.internalProcessInjects(instance, this.fInjectMethod);
+		} catch (error) {
+			if (singleton) this.fSingletonInstances.delete(serviceDef.serviceKey);
+			throw error;
+		}
+		if (onResolved) onResolved({
+			key: serviceDef.serviceKey,
+			name: this.getKeyDescription(serviceDef.serviceKey),
+			type: serviceDef.type,
+			context: this.fContext,
+			start,
+			end: performance.now()
+		});
+		return instance;
+	}
+	/**
 	* Internally inject deps for particular class..
 	* @param instance instance to inject
 	* @param method method for injecting dependencies, either lazy or static
@@ -437,7 +494,7 @@ var Container = class Container {
 			const deps = IOCEngine.getDeps(element);
 			for (const inj of deps) if (!elementSet.has(inj.dependency)) {
 				const isOptional = inj.type === IOC.DependencyType.OPTIONAL;
-				const childInstance = isOptional ? this.internalGetOptional(inj.dependency) : this.internalGet(inj.dependency, instance);
+				const childInstance = isOptional ? this.internalGetOptional(inj.dependency) : this.internalGet(inj.dependency, element);
 				elementSet.add(inj.dependency);
 				if (!isOptional) {
 					processQueue.push(childInstance);
@@ -474,10 +531,11 @@ var Container = class Container {
 	* @returns string representation of service key
 	*/
 	getKeyDescription(key) {
-		if (typeof key === "symbol") return key.description;
-		else if (typeof key === "function") return key.name;
-		else if (typeof key === "object") return key.constructor?.name ?? "Unknown object";
-		return "Unknown";
+		if (typeof key === "symbol") return key.description ?? "Symbol()";
+		else if (typeof key === "string") return key;
+		else if (typeof key === "function") return key.name || "AnonymousClass";
+		else if (typeof key === "object" && key !== null) return key.constructor?.name ?? "Unknown object";
+		return `Unknown (${typeof key})`;
 	}
 };
 //#endregion
@@ -712,4 +770,4 @@ function Injectable() {
 	return () => {};
 }
 //#endregion
-export { BaseDecorator, Container, Destroy, IOC, Identity, Init, Inject, InjectOptional, Injectable, createDecorator, destroyContainer, destroyDecorators, initializeContainer, initializeDecorators };
+export { BaseDecorator, Container, ContainerEvents, Destroy, IOC, IOCEngine, IOC_DEVTOOLS_HOOK_KEY, Identity, Init, Inject, InjectOptional, Injectable, createDecorator, destroyContainer, destroyDecorators, getIOCDevtoolsHook, initializeContainer, initializeDecorators, setIOCDevtoolsHook };

package/package.json

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