@vercube/di 0.0.1-alpha.15

package/dist/Common/BaseDecorators.d.ts

@@ -0,0 +1,31 @@
+/**
+* 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.
+*/
+export declare abstract class BaseDecorator<
+	T,
+	P = any
+> {
+	/** Holds options object that is passed as 2nd argument in createDecorator() factory */
+	options: T;
+	/** Holds class instance that is decorated */
+	instance: any;
+	/** Holds class prototype that is decorated */
+	prototype: P;
+	/** Holds property name that was decorated */
+	propertyName: string;
+	/** Holds property descriptor that was decorated */
+	descriptor: PropertyDescriptor;
+	/** Holds property index if decorators if for Method Property */
+	propertyIndex: number;
+	/**
+	* This method is called when decorator is created and ready to be used.
+	*/
+	created(): void;
+	/**
+	* 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(): void;
+}

package/dist/Decorators/Init.d.ts

@@ -0,0 +1,6 @@
+/**
+* Decorator that automatically executes the decorated method when dependencies are injected.
+* Use this decorator to run initialization logic for runtime-loaded container dependencies.
+* @returns {Function} Decorator function that creates an InitDecorator instance
+*/
+export declare function Init(): Function;

package/dist/Decorators/Inject.d.ts

@@ -0,0 +1,7 @@
+import { IOC } from "../Types/IOCTypes.js";
+/**
+* Injects a dependency with particular key to service.
+* @param key key to inject
+* @returns decorator
+*/
+export declare function Inject(key: IOC.ServiceKey): Function;

package/dist/Decorators/InjectOptional.d.ts

@@ -0,0 +1,7 @@
+import { IOC } from "../Types/IOCTypes.js";
+/**
+* Injects a dependency with particular key to service.
+* @param key key to inject
+* @returns decorator
+*/
+export declare function InjectOptional(key: IOC.ServiceKey): Function;

package/dist/Domain/Container.d.ts

@@ -0,0 +1,154 @@
+import { IOC } from "../Types/IOCTypes.js";
+import { ContainerEvents } from "./ContainerEvents.js";
+/**
+* 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.
+*/
+export declare class Container {
+	protected fLocked: boolean;
+	protected fDefaultParams: IOC.ContainerParams;
+	protected fServices: Map<IOC.ServiceKey, IOC.ServiceDef>;
+	protected fNewQueue: Map<IOC.ServiceKey, IOC.ServiceDef>;
+	protected fSingletonInstances: Map<IOC.ServiceKey, IOC.Instance>;
+	protected fInjectMethod: IOC.InjectMethod;
+	protected fContainerEvents: ContainerEvents;
+	/**
+	* Constructor for container.
+	* @param params initial params for container
+	*/
+	constructor(params?: Partial<IOC.ContainerParams>);
+	/**
+	* Returns array of all service keys. This basically returns keys from all .bindXXX calls.
+	* @returns {Array} array of service keys
+	*/
+	get servicesKeys(): IOC.ServiceKey[];
+	/**
+	* Returns events handler.
+	*/
+	get events(): ContainerEvents;
+	/**
+	* 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<T>(key: IOC.ServiceKey<T>, value?: IOC.ServiceValue<T>): void;
+	/**
+	* 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<T>(key: IOC.ServiceKey<T>, value?: IOC.ServiceValue<T>): void;
+	/**
+	* 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<T>(key: IOC.ServiceKey<T>, value: T): void;
+	/**
+	* 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<T>(key: IOC.ServiceKey<T>, mockInstance: Partial<T>): void;
+	/**
+	* 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<T>(key: IOC.ServiceKey<T>): T;
+	/**
+	* 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<T>(key: IOC.ServiceKey<T>): T | null;
+	/**
+	* 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: IOC.ProviderFunc): void;
+	/**
+	* 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: IOC.ProviderFunc | IOC.ProviderFunc[], flush?: boolean): void;
+	/**
+	* 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<T>(classType: IOC.Newable<T>, method?: IOC.InjectMethod): T;
+	/**
+	* Returns all IOC services registered in container.
+	* @returns array with all registered services
+	*/
+	getAllServices(): IOC.Instance[];
+	/**
+	* Unlocks the container, allowing things to be retrieved and used.
+	*/
+	unlock(): void;
+	/**
+	* Locks the container, disabling to add new services here.
+	*/
+	lock(): void;
+	/**
+	* Flushes new services queue, registering them into container.
+	*/
+	flushQueue(): void;
+	/**
+	* Internally retrieve dependency from container.
+	* @param key key to get
+	* @param parent parent (for debugging purposes)
+	* @returns queried instance
+	*/
+	protected internalGet<T>(key: IOC.ServiceKey<T>, parent?: IOC.Instance): T;
+	/**
+	* Internally retrieve dependency from container.
+	* @param key key to get
+	* @param parent parent
+	* @returns queried instance
+	*/
+	protected internalGetOptional<T>(key: IOC.ServiceKey<T>): T | null;
+	/**
+	* Internally resolves service def, turning it into class instance with deps injected.
+	* @param serviceDef service def to resolve
+	* @returns class instance
+	*/
+	protected internalResolve(serviceDef: IOC.ServiceDef): IOC.Instance;
+	/**
+	* Internally inject deps for particular class..
+	* @param instance instance to inject
+	* @param method method for injecting dependencies, either lazy or static
+	*/
+	protected internalProcessInjects(instance: IOC.Instance, method: IOC.InjectMethod): void;
+	/**
+	* Disposes a module, clearing everything allocated to it.
+	* @param def def that should be disposed
+	*/
+	protected internalDispose(def: IOC.ServiceDef): void;
+	/**
+	* Describes particular key for better error messaging.
+	* @param key service key
+	* @returns string representation of service key
+	*/
+	protected getKeyDescription(key: IOC.ServiceKey): string;
+}

package/dist/Domain/ContainerEvents.d.ts

@@ -0,0 +1,18 @@
+import type { IOC } from "../Types/IOCTypes.js";
+export type OnExpandedEvent = (serviceKeys: IOC.ServiceKey[]) => void;
+/**
+* This class allows for container to listen on various IOC events.
+*/
+export declare class ContainerEvents {
+	private fOnExpanded;
+	/**
+	* Registers to container "onExpanded" event.
+	* @param handler event handler
+	*/
+	onExpanded(handler: OnExpandedEvent): void;
+	/**
+	* Calls on expanded event.
+	* @param serviceKeys key of service we have installed
+	*/
+	callOnExpanded(serviceKeys: IOC.ServiceKey[]): void;
+}

package/dist/Domain/Engine.d.ts

@@ -0,0 +1,55 @@
+/**
+* This module is responsible for internal work of IOC engine inject mechanics. Its written in
+* "raw" (non-OOP) style to maximize simplicity and execution speed.
+*/
+import { IOC } from "../Types/IOCTypes.js";
+import { Container } from "./Container.js";
+/**
+* This is a struct that holds information about class dependency - what dependency, which field to inject,etc.
+*/
+export 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.
+*/
+export 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;
+export declare const IOCEngine: {
+	registerInject: typeof registerInject
+	getEntryForClass: typeof getEntryForClass
+	injectDeps: typeof injectDeps
+	getDeps: typeof getDeps
+};
+export {};

package/dist/Types/IOCTypes.d.ts

@@ -0,0 +1,48 @@
+import { Container } from "../Domain/Container.js";
+/**
+* This module exports various types used in IOC system.
+*/
+export declare namespace IOC {
+	type ServiceKey<T = unknown> = symbol | Newable<T> | Abstract<T>;
+	type ServiceValue<T = unknown> = Newable<T> | T;
+	interface ServiceDef<T = unknown> {
+		serviceKey: ServiceKey<T>;
+		serviceValue: ServiceValue<T>;
+		type: ServiceFactoryType;
+	}
+		enum ServiceFactoryType {
+		CLASS = "CLASS",
+		CLASS_SINGLETON = "CLASS_SINGLETON",
+		INSTANCE = "INSTANCE",
+	}
+	interface Newable<T> {
+		new (...args: unknown[]): T;
+	}
+	interface Abstract<T> {
+		prototype: T;
+	}
+	type Instance = any;
+	type Prototype = any;
+	type ProviderFunc = (container: Container) => void;
+	interface ContainerParams {
+		createLocked: boolean;
+		injectMethod?: IOC.InjectMethod;
+	}
+		enum InjectMethod {
+		LAZY = "LAZY",
+		STATIC = "STATIC",
+	}
+	type Identity = symbol;
+	interface ServiceMap {
+		[key: string]: ServiceMapEntry;
+	}
+	type ServiceMapEntry = () => ServiceMapTask | ServiceMapTask[];
+	type ServiceMapTask = Promise<{
+		default: IOC.ProviderFunc
+	}>;
+	type Stack = (ServiceKey | Instance)[];
+		enum DependencyType {
+		STANDARD = 0,
+		OPTIONAL = 1,
+	}
+}

package/dist/Utils/Utils.d.ts

@@ -0,0 +1,79 @@
+import { type BaseDecorator } from "../Common/BaseDecorators.js";
+import { Container } from "../Domain/Container.js";
+import { IOC } from "../Types/IOCTypes.js";
+/**
+* This function generates new service key for particular service. Providing
+* name is mandatory because, unlike classes, those unique symbols do not infer
+* their names from code.
+*
+* @param name name of the service
+* @returns unique service identity
+*/
+export declare function Identity(name: string): IOC.Identity;
+/**
+* A simple type of constructor for class "T"
+*/
+export interface IClassType<T> {
+	new (): T;
+}
+/**
+* Holds decorator entry struct. It is saved in __decorators array for every class and holds
+* various informations.
+*/
+export interface IDecoratorEntry {
+	classType: any;
+	params: any;
+	target: any;
+	propertyName: string;
+	descriptor: PropertyDescriptor;
+}
+/**
+* This is a type for every class instance that is decorated. It should contain hidden __decorators
+* array that holds information about all decorators used in this class. It will be used later for
+* turning those declarations for real code.
+*/
+export interface IDecoratedPrototype {
+	__decorators?: IDecoratorEntry[];
+	__metadata?: any;
+}
+export interface IDecoratedInstance {
+	__decoratorInstances?: BaseDecorator<any>[];
+}
+/**
+* This function creates ES6 decorator based on class that was passed in argument.
+*
+* @param decoratorClass class of decorator that will be used
+* @param params custom options object that will be availalbe in "options" property of decorator class
+* @return ES6 decorator 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
+*/
+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()
+*
+* @param target instance of class that should have decorators cleaned up
+* @param container ioc container
+*/
+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
+*/
+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
+*/
+export declare function destroyContainer(container: Container): void;