@vercube/di 0.0.3 → 0.0.5

package/dist/index.d.mts

@@ -0,0 +1,426 @@
+//#region src/Common/BaseDecorators.d.ts
+/**
+ * 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> {
+  /** 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;
+}
+//#endregion
+//#region src/Domain/ContainerEvents.d.ts
+type OnExpandedEvent = (serviceKeys: IOC.ServiceKey[]) => void;
+/**
+ * This class allows for container to listen on various IOC events.
+ */
+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;
+}
+//#endregion
+//#region src/Domain/Container.d.ts
+/**
+ * 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 {
+  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;
+}
+//#endregion
+//#region src/Types/IOCTypes.d.ts
+/**
+ * This module exports various types used in IOC system.
+ */
+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.
+   */
+  type ServiceKey<T = unknown> = symbol | Newable<T> | Abstract<T>;
+  /**
+   * This type holds implementation that might be used in class.
+   */
+  type ServiceValue<T = unknown> = Newable<T> | T;
+  /**
+   * This interface holds information about service in IOC container.
+   */
+  interface ServiceDef<T = unknown> {
+    serviceKey: ServiceKey<T>;
+    serviceValue: ServiceValue<T>;
+    type: ServiceFactoryType;
+  }
+  /**
+   * This holds type of bind we have used.
+   */
+  enum ServiceFactoryType {
+    CLASS = "CLASS",
+    CLASS_SINGLETON = "CLASS_SINGLETON",
+    INSTANCE = "INSTANCE",
+  }
+  /**
+   * Standard class.
+   */
+  interface Newable<T> {
+    new (...args: unknown[]): T;
+  }
+  /**
+   * Abstract class.
+   */
+  interface Abstract<T> {
+    prototype: T;
+  }
+  /**
+   * Service instance
+   */
+  type Instance = any;
+  /**
+   * Helper type for "some prototype".
+   */
+  type Prototype = any;
+  /**
+   * Container provider function.
+   */
+  type ProviderFunc = (container: Container) => void;
+  /**
+   * Container constructor parameters
+   */
+  interface ContainerParams {
+    createLocked: boolean;
+    injectMethod?: IOC.InjectMethod;
+  }
+  /**
+   * Method for injecting dependencies.
+   * Lazy - means dependency is resolved at the time when property is **accessed**, while
+   * Static - means dependency is resolved as soon as class is instantiated
+   */
+  enum InjectMethod {
+    LAZY = "LAZY",
+    STATIC = "STATIC",
+  }
+  /**
+   * This type represents unique service identity. For now, its symbol, but we leave
+   * gate open in case we would want to replace it.
+   */
+  type Identity = symbol;
+  /**
+   * Service map used in application configs.
+   */
+  interface ServiceMap {
+    [key: string]: ServiceMapEntry;
+  }
+  /**
+   * Service map handler function (requirement for async to work, see SPT-5448)
+   */
+  type ServiceMapEntry = () => ServiceMapTask | ServiceMapTask[];
+  /**
+   * Expander asynchronous task.
+   */
+  type ServiceMapTask = Promise<{
+    default: IOC.ProviderFunc;
+  }>;
+  /**
+   * IOC dependency stack, used for debuggging
+   */
+  type Stack = (ServiceKey | Instance)[];
+  /**
+   * Type of dependency - either standard or optional.
+   */
+  enum DependencyType {
+    STANDARD = 0,
+    OPTIONAL = 1,
+  }
+}
+//#endregion
+//#region src/Decorators/Inject.d.ts
+/**
+ * Injects a dependency with particular key to service.
+ * @param key key to inject
+ * @returns decorator
+ */
+declare function Inject(key: IOC.ServiceKey): Function;
+//#endregion
+//#region src/Decorators/InjectOptional.d.ts
+/**
+ * Injects a dependency with particular key to service.
+ * @param key key to inject
+ * @returns decorator
+ */
+declare function InjectOptional(key: IOC.ServiceKey): Function;
+//#endregion
+//#region src/Decorators/Init.d.ts
+/**
+ * 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
+ */
+declare function Init(): Function;
+//#endregion
+//#region src/Decorators/Destroy.d.ts
+/**
+ * Decorator that automatically executes the decorated method when the service or component
+ * is destroyed. Use this decorator to run cleanup logic like unregistering event listeners
+ * or clearing timers.
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   @Destroy()
+ *   cleanup() {
+ *     // Cleanup logic here
+ *   }
+ * }
+ * ```
+ * @returns {Function} Decorator function that creates a DestroyDecorator instance
+ */
+declare function Destroy(): Function;
+//#endregion
+//#region src/Utils/Utils.d.ts
+/**
+ * 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
+ */
+declare function Identity(name: string): IOC.Identity;
+/**
+ * A simple type of constructor for class "T"
+ */
+interface IClassType<T> {
+  new (): T;
+}
+/**
+ * Holds decorator entry struct. It is saved in __decorators array for every class and holds
+ * various informations.
+ */
+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.
+ */
+interface IDecoratedPrototype {
+  __decorators?: IDecoratorEntry[];
+  __metadata?: any;
+}
+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
+ */
+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;
+/**
+ * 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
+ */
+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;
+/**
+ * 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;
+//#endregion
+export { BaseDecorator, Container, Destroy, IClassType, IDecoratedInstance, IDecoratedPrototype, IDecoratorEntry, IOC, Identity, Init, Inject, InjectOptional, createDecorator, destroyContainer, destroyDecorators, initializeContainer, initializeDecorators };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-//#region packages/di/src/Common/BaseDecorators.ts
+//#region src/Common/BaseDecorators.ts
 /**
 * 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.
@@ -29,7 +29,7 @@ var BaseDecorator = class {
 };
 
 //#endregion
-//#region packages/di/src/Types/IOCTypes.ts
+//#region src/Types/IOCTypes.ts
 let IOC;
 (function(_IOC) {
 	let ServiceFactoryType = /* @__PURE__ */ function(ServiceFactoryType$1) {
@@ -54,13 +54,13 @@ let IOC;
 })(IOC || (IOC = {}));
 
 //#endregion
-//#region packages/di/src/Domain/Engine.ts
+//#region 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 classMap = /* @__PURE__ */ new Map();
 const ROOT_PROTO = Object.getPrototypeOf({});
 /**
 * This method registers @Inject() in particular class.
@@ -157,7 +157,7 @@ const IOCEngine = {
 };
 
 //#endregion
-//#region packages/di/src/Decorators/Inject.ts
+//#region src/Decorators/Inject.ts
 /**
 * Injects a dependency with particular key to service.
 * @param key key to inject
@@ -170,7 +170,7 @@ function Inject(key) {
 }
 
 //#endregion
-//#region packages/di/src/Decorators/InjectOptional.ts
+//#region src/Decorators/InjectOptional.ts
 /**
 * Injects a dependency with particular key to service.
 * @param key key to inject
@@ -183,7 +183,7 @@ function InjectOptional(key) {
 }
 
 //#endregion
-//#region packages/di/src/Decorators/Init.ts
+//#region src/Decorators/Init.ts
 /**
 * This decorator fires the decorated function as soon as decorators are injected. You
 * can use this for initialization logic in runtime-loaded container deps.
@@ -206,7 +206,7 @@ function Init() {
 }
 
 //#endregion
-//#region packages/di/src/Decorators/Destroy.ts
+//#region src/Decorators/Destroy.ts
 /**
 * Decorator that handles cleanup tasks when a service or component is destroyed.
 * This decorator class extends BaseDecorator and executes the decorated method
@@ -243,7 +243,7 @@ function Destroy() {
 }
 
 //#endregion
-//#region packages/di/src/Domain/ContainerEvents.ts
+//#region src/Domain/ContainerEvents.ts
 /**
 * This class allows for container to listen on various IOC events.
 */
@@ -266,7 +266,7 @@ var ContainerEvents = class {
 };
 
 //#endregion
-//#region packages/di/src/Utils/Utils.ts
+//#region src/Utils/Utils.ts
 /**
 * This function generates new service key for particular service. Providing
 * name is mandatory because, unlike classes, those unique symbols do not infer
@@ -302,14 +302,14 @@ function createDecorator(decoratorClass, params) {
 * 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();
+const containerMap = /* @__PURE__ */ 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() });
+	if (!containerMap.has(container)) containerMap.set(container, { decoratedInstances: /* @__PURE__ */ new Map() });
 	return containerMap.get(container);
 }
 /**
@@ -369,7 +369,7 @@ function destroyContainer(container) {
 }
 
 //#endregion
-//#region packages/di/src/Domain/Container.ts
+//#region src/Domain/Container.ts
 /**
 * 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.
@@ -377,9 +377,9 @@ function destroyContainer(container) {
 var Container = class Container {
 	fLocked = false;
 	fDefaultParams = { createLocked: false };
-	fServices = new Map();
-	fNewQueue = new Map();
-	fSingletonInstances = new Map();
+	fServices = /* @__PURE__ */ new Map();
+	fNewQueue = /* @__PURE__ */ new Map();
+	fSingletonInstances = /* @__PURE__ */ new Map();
 	fInjectMethod = IOC.InjectMethod.STATIC;
 	fContainerEvents = new ContainerEvents();
 	/**
@@ -634,7 +634,7 @@ var Container = class Container {
 			return;
 		}
 		const processQueue = [];
-		const elementSet = new Set();
+		const elementSet = /* @__PURE__ */ new Set();
 		const toProcessElements = [];
 		processQueue.push(instance);
 		toProcessElements.push(instance);

package/package.json

@@ -1,21 +1,14 @@
 {
   "name": "@vercube/di",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Dependencie Injection  module for Vercube framework",
   "repository": "@vercube/di",
   "license": "MIT",
   "sideEffects": false,
-  "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
-    }
+    ".": "./dist/index.mjs"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.mts",
   "files": [
     "dist",
     "README.md"

package/dist/Common/BaseDecorators.d.ts

@@ -1,31 +0,0 @@
-/**
-* 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 = any,
-	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/Destroy.d.ts

@@ -1,17 +0,0 @@
-/**
-* Decorator that automatically executes the decorated method when the service or component
-* is destroyed. Use this decorator to run cleanup logic like unregistering event listeners
-* or clearing timers.
-* 
-* @example
-* ```typescript
-* class MyService {
-*   @Destroy()
-*   cleanup() {
-*     // Cleanup logic here
-*   }
-* }
-* ```
-* @returns {Function} Decorator function that creates a DestroyDecorator instance
-*/
-export declare function Destroy(): Function;

package/dist/Decorators/Init.d.ts

@@ -1,6 +0,0 @@
-/**
-* 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

@@ -1,7 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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;