@vercube/di 0.0.1-alpha.15

package/dist/index.cjs

@@ -0,0 +1,599 @@
+"use strict";
+
+//#region packages/di/src/Common/BaseDecorators.ts
+var BaseDecorator = class {
+	/** Holds options object that is passed as 2nd argument in createDecorator() factory */
+	options;
+	/** Holds class instance that is decorated */
+	instance;
+	/** Holds class prototype that is decorated */
+	prototype;
+	/** Holds property name that was decorated */
+	propertyName;
+	/** Holds property descriptor that was decorated */
+	descriptor;
+	/** Holds property index if decorators if for Method Property */
+	propertyIndex;
+	/**
+	* This method is called when decorator is created and ready to be used.
+	*/
+	created() {}
+	/**
+	* This method is called when decorator is destroyed for cleanup tasks (like unregistering listeners, clearing timers).
+	* For standard services it is called at the end of SSR requests and for Vue components it is called when component is
+	* destroyed.
+	*/
+	destroyed() {}
+};
+
+//#endregion
+//#region packages/di/src/Types/IOCTypes.ts
+let IOC;
+(function(_IOC) {
+	let ServiceFactoryType = /* @__PURE__ */ function(ServiceFactoryType$1) {
+		ServiceFactoryType$1["CLASS"] = "CLASS";
+		ServiceFactoryType$1["CLASS_SINGLETON"] = "CLASS_SINGLETON";
+		ServiceFactoryType$1["INSTANCE"] = "INSTANCE";
+		return ServiceFactoryType$1;
+	}({});
+	_IOC.ServiceFactoryType = ServiceFactoryType;
+	let InjectMethod = /* @__PURE__ */ function(InjectMethod$1) {
+		InjectMethod$1["LAZY"] = "LAZY";
+		InjectMethod$1["STATIC"] = "STATIC";
+		return InjectMethod$1;
+	}({});
+	_IOC.InjectMethod = InjectMethod;
+	let DependencyType = /* @__PURE__ */ function(DependencyType$1) {
+		DependencyType$1[DependencyType$1["STANDARD"] = 0] = "STANDARD";
+		DependencyType$1[DependencyType$1["OPTIONAL"] = 1] = "OPTIONAL";
+		return DependencyType$1;
+	}({});
+	_IOC.DependencyType = DependencyType;
+})(IOC || (IOC = {}));
+
+//#endregion
+//#region packages/di/src/Domain/Engine.ts
+/**
+* This map holds metadata for ALL classes in system along with their dependencies. Original idea was
+* to store those informations in object prototype, but accessing this map is blazing fast with Map
+* container (<1ms).
+*/
+const classMap = new Map();
+const ROOT_PROTO = Object.getPrototypeOf({});
+/**
+* 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)
+*/
+function registerInject(prototype, propertyName, dependency, type) {
+	let entry = classMap.get(prototype);
+	if (!entry) {
+		const newEntry = { deps: [] };
+		entry = newEntry;
+		classMap.set(prototype, entry);
+	}
+	const newDep = {
+		propertyName,
+		dependency,
+		type
+	};
+	entry.deps.push(newDep);
+}
+/**
+* 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
+*/
+function getEntryForClass(classType) {
+	const entry = classMap.get(classType.prototype);
+	return entry === void 0 ? null : entry;
+}
+/**
+* Returns array of dependencies for particular class instance.
+* @param instance class instance
+* @returns array of @Inject dependencies defined for this class
+*/
+function getDeps(instance) {
+	const prototype = Object.getPrototypeOf(instance);
+	if (!prototype) return [];
+	const entry = classMap.get(prototype);
+	return entry !== void 0 && entry.deps !== void 0 ? entry.deps : [];
+}
+/**
+* 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
+*/
+function injectDeps(container, instance, method) {
+	let prototype = Object.getPrototypeOf(instance);
+	if (!prototype) return;
+	/**
+	* Here we will traverse through prototype chain until we hit dead end (ROOT_PROTO). This is because we
+	* must process inject for current class and also for every base class.
+	*
+	* So we will use "do" loop to iterate full prototype chain.
+	*/
+	do {
+		const entry = classMap.get(prototype);
+		if (entry) for (const iter of entry.deps) {
+			const propertyName = iter.propertyName;
+			const dependency = iter.dependency;
+			const type = iter.type;
+			if (Object.prototype.hasOwnProperty.call(instance, propertyName) && instance[propertyName] !== void 0) continue;
+			if (type === IOC.DependencyType.OPTIONAL) {
+				Object.defineProperty(instance, propertyName, { get: function() {
+					return container.getOptional(dependency);
+				} });
+				continue;
+			}
+			switch (method) {
+				case IOC.InjectMethod.LAZY: {
+					Object.defineProperty(instance, propertyName, { get: function() {
+						return container.get(dependency);
+					} });
+					break;
+				}
+				case IOC.InjectMethod.STATIC: {
+					instance[propertyName] = container.get(dependency);
+					break;
+				}
+				default: throw new Error(`IOCEngine.injectDeps() - invalid inject method ${method}`);
+			}
+		}
+		prototype = Object.getPrototypeOf(prototype);
+	} while (prototype && prototype !== ROOT_PROTO);
+}
+const IOCEngine = {
+	registerInject,
+	getEntryForClass,
+	injectDeps,
+	getDeps
+};
+
+//#endregion
+//#region packages/di/src/Decorators/Inject.ts
+function Inject(key) {
+	return (target, propertyName) => {
+		IOCEngine.registerInject(target, propertyName, key, IOC.DependencyType.STANDARD);
+	};
+}
+
+//#endregion
+//#region packages/di/src/Decorators/InjectOptional.ts
+function InjectOptional(key) {
+	return (target, propertyName) => {
+		IOCEngine.registerInject(target, propertyName, key, IOC.DependencyType.OPTIONAL);
+	};
+}
+
+//#endregion
+//#region packages/di/src/Decorators/Init.ts
+var InitDecorator = class extends BaseDecorator {
+	/**
+	* Called when decorator is initialized.
+	*/
+	created() {
+		if (typeof this.instance[this.propertyName] === "function") this.instance[this.propertyName]();
+	}
+};
+function Init() {
+	return createDecorator(InitDecorator, {});
+}
+
+//#endregion
+//#region packages/di/src/Domain/ContainerEvents.ts
+var ContainerEvents = class {
+	fOnExpanded = [];
+	/**
+	* Registers to container "onExpanded" event.
+	* @param handler event handler
+	*/
+	onExpanded(handler) {
+		this.fOnExpanded.push(handler);
+	}
+	/**
+	* Calls on expanded event.
+	* @param serviceKeys key of service we have installed
+	*/
+	callOnExpanded(serviceKeys) {
+		for (const handler of this.fOnExpanded) handler(serviceKeys);
+	}
+};
+
+//#endregion
+//#region packages/di/src/Utils/Utils.ts
+function Identity(name) {
+	return Symbol(name);
+}
+function createDecorator(decoratorClass, params) {
+	return function internalDecorator(target, propertyName, descriptor) {
+		if (!target.__decorators) target.__decorators = [];
+		target.__decorators.push({
+			classType: decoratorClass,
+			params,
+			target,
+			propertyName,
+			descriptor
+		});
+	};
+}
+/**
+* This map holds map of Container:DecoratorMetadata values. For every container created,
+* we must hold array of decorated instances, we realize it by holding map where key is
+* container (for easier removal later) and value is IContainerDecoratorMetadataObject.
+*/
+const containerMap = new Map();
+/**
+* Helper function to query data from container
+* @param container container to get metadata fro
+* @return metadata object
+*/
+function getContainerMetadata(container) {
+	if (!containerMap.has(container)) containerMap.set(container, { decoratedInstances: new Map() });
+	return containerMap.get(container);
+}
+function initializeDecorators(target, container) {
+	const prototype = Object.getPrototypeOf(target);
+	if (prototype.__decorators) for (const entry of prototype.__decorators) {
+		const instance = container.resolve(entry.classType);
+		if (instance) {
+			instance.options = entry.params;
+			instance.instance = target;
+			instance.prototype = prototype;
+			instance.propertyName = entry.propertyName;
+			instance.descriptor = entry.descriptor;
+			instance.propertyIndex = typeof entry.descriptor === "number" ? entry.descriptor : -1;
+			instance.created();
+		}
+		const { decoratedInstances } = getContainerMetadata(container);
+		const instanceList = decoratedInstances.get(target) ?? [];
+		instanceList.push(instance);
+		decoratedInstances.set(target, instanceList);
+	}
+}
+function destroyDecorators(target, container) {
+	const { decoratedInstances } = getContainerMetadata(container);
+	const instanceList = decoratedInstances.get(target);
+	if (instanceList) for (const instance of instanceList) instance.destroyed();
+	decoratedInstances.delete(target);
+}
+function initializeContainer(container) {
+	container.flushQueue();
+}
+function destroyContainer(container) {
+	container.getAllServices().forEach((service) => destroyDecorators(service, container));
+	containerMap.delete(container);
+}
+
+//#endregion
+//#region packages/di/src/Domain/Container.ts
+var Container = class Container {
+	fLocked = false;
+	fDefaultParams = { createLocked: false };
+	fServices = new Map();
+	fNewQueue = new Map();
+	fSingletonInstances = new Map();
+	fInjectMethod = IOC.InjectMethod.STATIC;
+	fContainerEvents = new ContainerEvents();
+	/**
+	* Constructor for container.
+	* @param params initial params for container
+	*/
+	constructor(params) {
+		this.fLocked = params?.createLocked ?? false;
+		this.fDefaultParams = Object.assign(this.fDefaultParams, params);
+		this.fInjectMethod = params?.injectMethod ?? IOC.InjectMethod.STATIC;
+		this.bindInstance(Container, this);
+	}
+	/**
+	* Returns array of all service keys. This basically returns keys from all .bindXXX calls.
+	* @returns {Array} array of service keys
+	*/
+	get servicesKeys() {
+		return [...this.fServices.keys()];
+	}
+	/**
+	* Returns events handler.
+	*/
+	get events() {
+		return this.fContainerEvents;
+	}
+	/**
+	* Binds particular key to container in singleton scope. Multiple queries/injects of this
+	* service will always return the same instance.
+	*
+	* @param key key of service, preferably class or abstract class
+	* @param value implementation
+	*/
+	bind(key, value) {
+		const newDef = {
+			serviceKey: key,
+			serviceValue: value ?? key,
+			type: IOC.ServiceFactoryType.CLASS_SINGLETON
+		};
+		if (typeof key === "symbol" && !value) throw new Error("Container - provide implementation for binds with symbols.");
+		const existingServiceDef = this.fServices.get(key);
+		if (existingServiceDef) this.internalDispose(existingServiceDef);
+		this.fServices.set(key, newDef);
+		this.fNewQueue.set(key, newDef);
+	}
+	/**
+	* Binds particular key to container in transient scope. Every query/@Inject of this service
+	* will have totally brand-new instance of class.
+	* @param key key of service, preferably class or abstract class
+	* @param value implementation
+	*/
+	bindTransient(key, value) {
+		const newDef = {
+			serviceKey: key,
+			serviceValue: value ?? key,
+			type: IOC.ServiceFactoryType.CLASS
+		};
+		const existingServiceDef = this.fServices.get(key);
+		if (existingServiceDef) this.internalDispose(existingServiceDef);
+		this.fServices.set(key, newDef);
+		this.fNewQueue.set(key, newDef);
+	}
+	/**
+	* Binds particular key class to an existing class instance. If you use this method,
+	* class wont be instantiated automatically. The common use case is to
+	* share single class instance between two or more containers.
+	*
+	* @param key key of service, preferably class or abstract class
+	* @param value instance of class to be used as resolution
+	*/
+	bindInstance(key, value) {
+		const newDef = {
+			serviceKey: key,
+			serviceValue: value,
+			type: IOC.ServiceFactoryType.INSTANCE
+		};
+		const existingServiceDef = this.fServices.get(key);
+		if (existingServiceDef) this.internalDispose(existingServiceDef);
+		this.fServices.set(key, newDef);
+		this.fNewQueue.set(key, newDef);
+	}
+	/**
+	* Binds mocked instance to a particular service ID. Its designed to be used in unit tests, where you can quickly
+	* replace real IOC implementation with a partial stub. Please note, you are responsible to provide enough data
+	* for test to pass, TypeScript wont check it.
+	*
+	* Example:
+	*
+	* container.bind(HttpServer, {
+	*   listen: jest.fn(),
+	* });
+	*
+	* @param key service to be replaced
+	* @param mockInstance mock instance
+	*/
+	bindMock(key, mockInstance) {
+		const newDef = {
+			serviceKey: key,
+			serviceValue: mockInstance,
+			type: IOC.ServiceFactoryType.INSTANCE
+		};
+		const existingServiceDef = this.fServices.get(key);
+		if (existingServiceDef) this.internalDispose(existingServiceDef);
+		this.fServices.set(key, newDef);
+		this.fNewQueue.set(key, newDef);
+	}
+	/**
+	* Returns implementation for a particular key class. This is the same as @Inject,
+	* but triggered programitically.
+	* @param key key used in .bind() function to bind key class to implementation class
+	* @returns service for identifier
+	*/
+	get(key) {
+		return this.internalGet(key);
+	}
+	/**
+	* Returns implementation for a particular key class. This is the same as @Inject,
+	* but triggered programitically.
+	* @param key key used in .bind() function to bind key class to implementation class
+	* @returns service for identifier
+	*/
+	getOptional(key) {
+		return this.internalGetOptional(key);
+	}
+	/**
+	* Uses the container provider to register multiple things in IOC container at once.
+	* @param provider provider that will register new services into IOC container
+	*/
+	use(provider) {
+		provider(this);
+	}
+	/**
+	* Expands container during runtime, adding new services to it.
+	* @param providers functor that is used to expand the container
+	* @param flush whether container should be flushed now or not
+	*/
+	expand(providers, flush = true) {
+		const preLockState = this.fLocked;
+		const allProviders = Array.isArray(providers) ? providers : [providers];
+		try {
+			this.fLocked = false;
+			for (const provider of allProviders) this.use(provider);
+			const newKeys = [...this.fNewQueue.keys()].filter((k) => !this.fSingletonInstances.has(k));
+			this.fContainerEvents.callOnExpanded(newKeys);
+			if (flush) this.flushQueue();
+		} finally {
+			this.fLocked = preLockState;
+		}
+	}
+	/**
+	* Creates instance of particular class using, respecting all @Injects inside created class.
+	* @param classType type of class to instantiate
+	* @param method (optional) inject method
+	* @returns new class instance with dependencies
+	*/
+	resolve(classType, method = IOC.InjectMethod.LAZY) {
+		const newInstance = new classType();
+		this.internalProcessInjects(newInstance, method);
+		return newInstance;
+	}
+	/**
+	* Returns all IOC services registered in container.
+	* @returns array with all registered services
+	*/
+	getAllServices() {
+		return this.servicesKeys.map((k) => this.get(k));
+	}
+	/**
+	* Unlocks the container, allowing things to be retrieved and used.
+	*/
+	unlock() {
+		this.fLocked = false;
+	}
+	/**
+	* Locks the container, disabling to add new services here.
+	*/
+	lock() {
+		this.fLocked = true;
+	}
+	/**
+	* Flushes new services queue, registering them into container.
+	*/
+	flushQueue() {
+		if (this.fNewQueue.size === 0) return;
+		const values = [...this.fNewQueue.values()];
+		for (const def of values) {
+			if (def.type !== IOC.ServiceFactoryType.CLASS_SINGLETON) continue;
+			const instance = this.internalResolve(def);
+			initializeDecorators(instance, this);
+		}
+		this.fNewQueue.clear();
+	}
+	/**
+	* Internally retrieve dependency from container.
+	* @param key key to get
+	* @param parent parent (for debugging purposes)
+	* @returns queried instance
+	*/
+	internalGet(key, parent) {
+		const serviceDef = this.fServices.get(key);
+		if (!serviceDef) throw new Error(`Unresolved dependency for [${this.getKeyDescription(key)}]`);
+		return this.internalResolve(serviceDef);
+	}
+	/**
+	* Internally retrieve dependency from container.
+	* @param key key to get
+	* @param parent parent
+	* @returns queried instance
+	*/
+	internalGetOptional(key) {
+		const serviceDef = this.fServices.get(key);
+		if (!serviceDef) return null;
+		return this.internalResolve(serviceDef);
+	}
+	/**
+	* Internally resolves service def, turning it into class instance with deps injected.
+	* @param serviceDef service def to resolve
+	* @returns class instance
+	*/
+	internalResolve(serviceDef) {
+		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;
+				}
+				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;
+			}
+			default: throw new Error(`Container - invalid factory type: ${serviceDef.type}`);
+		}
+	}
+	/**
+	* Internally inject deps for particular class..
+	* @param instance instance to inject
+	* @param method method for injecting dependencies, either lazy or static
+	*/
+	internalProcessInjects(instance, method) {
+		if (method === IOC.InjectMethod.LAZY) {
+			IOCEngine.injectDeps(this, instance, IOC.InjectMethod.LAZY);
+			return;
+		}
+		const processQueue = [];
+		const elementSet = new Set();
+		const toProcessElements = [];
+		processQueue.push(instance);
+		toProcessElements.push(instance);
+		while (processQueue.length > 0) {
+			const element = processQueue.pop();
+			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);
+				elementSet.add(inj.dependency);
+				if (!isOptional) {
+					processQueue.push(childInstance);
+					toProcessElements.push(childInstance);
+				}
+			}
+		}
+		for (const el of toProcessElements) IOCEngine.injectDeps(this, el, IOC.InjectMethod.STATIC);
+	}
+	/**
+	* Disposes a module, clearing everything allocated to it.
+	* @param def def that should be disposed
+	*/
+	internalDispose(def) {
+		switch (def.type) {
+			case IOC.ServiceFactoryType.INSTANCE: {
+				destroyDecorators(def.serviceValue, this);
+				break;
+			}
+			case IOC.ServiceFactoryType.CLASS_SINGLETON: {
+				const existingInstance = this.fSingletonInstances.get(def.serviceKey);
+				if (existingInstance) destroyDecorators(existingInstance, this);
+				break;
+			}
+			case IOC.ServiceFactoryType.CLASS: break;
+			default: throw new Error(`Container::internalDispose() - invalid def type: ${def.type}`);
+		}
+	}
+	/**
+	* Describes particular key for better error messaging.
+	* @param key service key
+	* @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";
+	}
+};
+
+//#endregion
+exports.BaseDecorator = BaseDecorator
+exports.Container = Container
+Object.defineProperty(exports, 'IOC', {
+  enumerable: true,
+  get: function () {
+    return IOC;
+  }
+});
+exports.Identity = Identity
+exports.Init = Init
+exports.Inject = Inject
+exports.InjectOptional = InjectOptional
+exports.createDecorator = createDecorator
+exports.destroyContainer = destroyContainer
+exports.destroyDecorators = destroyDecorators
+exports.initializeContainer = initializeContainer
+exports.initializeDecorators = initializeDecorators

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./Common/BaseDecorators.js";
+export * from "./Decorators/Inject.js";
+export * from "./Decorators/InjectOptional.js";
+export * from "./Decorators/Init.js";
+export * from "./Domain/Container.js";
+export * from "./Types/IOCTypes.js";
+export * from "./Utils/Utils.js";