@zanobijs/core 1.2.0 → 2.0.0-beta.0

package/lib/esm/injector/module.js

@@ -0,0 +1,213 @@
+import 'reflect-metadata';
+import { aliasTo } from 'awilix';
+import { isClass, unCapitalize, isEmpty } from '@zanobijs/common/utils/shared.utils';
+import { Logger } from '@zanobijs/common/utils';
+import { Injector } from './injector.js';
+import { Metadata } from '../metadata.js';
+import { InvalidModuleAnnotationException } from '../exceptions/invalid.module.exception.js';
+import { InvalidProviderModuleException } from '../exceptions/invalidProvider.module.exception.js';
+import '@zanobijs/common/exceptions/runtime.exception';
+
+/**
+ * Módulo para gestionar la configuración y el registro de
+ * controladores, servicios, proveedores y dependencias.
+ */
+class Module {
+    config;
+    module;
+    logger;
+    injector;
+    registerClass = {};
+    dependenciesClass = [];
+    metadata;
+    types = ['controller', 'service'];
+    listProviders = new Map();
+    listProvidersClass = new Map();
+    /**
+     * Constructor del módulo.
+     */
+    constructor() {
+        this.logger = Logger();
+        this.metadata = Metadata.getInstance();
+    }
+    /**
+     * Configura el módulo con la información proporcionada.
+     * @param {any} module - Módulo a configurar.
+     */
+    setup(module) {
+        if (this.metadata.isTypeModule(module)) {
+            this.module = module;
+            this.logger.debug('Module - Setup - Create Injector to module:', module.name);
+            this.injector = new Injector(this.module, this.listProviders, this.listProvidersClass);
+        }
+        else {
+            throw new InvalidModuleAnnotationException();
+        }
+    }
+    /** Metodo de exposicion para escarnear proveedores y obtener
+     * la metadata del modulo que esta confirgurado(Setup) en ese momento
+     * @public
+     */
+    scan() {
+        this.injector.scanProviders();
+        this.getMetadataModule();
+    }
+    /**
+     * Este metodo incializa una serie de pasos dentro de los cuales son:
+     * obtener la metada del modulo configurado actualmente, busca y registra
+     * las dependencias de las entidades (controladores y servicios), registra
+     * las dependencias de los proveedores que son tipo entidad (clase abst a clase)
+     * y registra las dependecias con alias cuando sus nombres no son iguales
+     * @public
+     */
+    initialize() {
+        this.logger.debug('Module - Initialize:', this.module.name);
+        this.getMetadataModule();
+        this.registerDependenciesFromEntity();
+        this.registerEntitiesFromProvider();
+        this.registerDependenciesToAlias();
+    }
+    /**
+     * Extrae los metadatos del módulo usando reflect-metadata.
+     * @private
+     */
+    getMetadataModule() {
+        this.config = this.metadata.getMetadataModule(this.module);
+    }
+    /**
+     * Registra las entidades de configuración en el módulo.
+     * @private
+     */
+    registerDependenciesFromEntity() {
+        this.registerEntities('controllers');
+        this.registerEntities('services');
+    }
+    /**
+     * se encarga de filtrar los metadatos del modulo buscando si es controlador o servicio
+     * para luego buscar en los metadatos el nombre de la dependecia y de quien depende
+     * para se agrupado y agregarlos a la lista de clases a registrar en el contenedor.
+     * @param {('controllers' | 'services')} entityType - Tipo de entidad a registrar.
+     * @private
+     */
+    registerEntities(entityType) {
+        const entities = this.config[entityType];
+        this.logger.debug('Module - searching for entities type:', entityType);
+        if (entities && entities.length > 0) {
+            const registeredEntities = entities
+                .filter((target) => {
+                return (isClass(target) &&
+                    this.types.includes(this.metadata.determineType(target)));
+            })
+                .map((target) => {
+                this.logger.debug('Module - Entity', `<<< ${target.name} >>>`);
+                this.groupDependenciesForAlias(target);
+                const targetName = unCapitalize(target.name);
+                return {
+                    [target.name]: this.injector.getInjectorClass(target),
+                    [targetName]: aliasTo(target.name),
+                };
+            });
+            Object.assign(this.registerClass, ...registeredEntities);
+        }
+        else {
+            this.logger.debug('Module - Does not have entities of that type', entityType);
+        }
+    }
+    /**
+     * Se encarga de recorrer la lista de proveedores que son tipo clase para
+     * luego buscar en los metadatos el nombre de la dependecia y de quien depende
+     * para se agrupado y agregarlos a la lista de clases a registrar en el contenedor.
+     * toma el proveedor que es nombre la clase o un token (nombre de pendencia)
+     * que va ser sustituida por la clase de useClass
+     * @private
+     */
+    registerEntitiesFromProvider() {
+        this.logger.debug('Module - searching for entities from provider');
+        for (const [key, value] of this.listProvidersClass) {
+            try {
+                this.logger.debug('Module - Entity provider', `<<< ${key} >>>`);
+                const type = this.metadata.determineType(value);
+                if (!this.types.includes(type)) {
+                    throw new Error('The type used in the provider useClass property is not valid');
+                }
+                this.groupDependenciesForAlias(value);
+                const targetName = unCapitalize(value.name);
+                const targetProviderName = unCapitalize(key);
+                const registerProviderWithEntities = {
+                    [value.name]: this.injector.getInjectorClass(value),
+                    [targetName]: aliasTo(value.name),
+                    [key]: aliasTo(value.name),
+                    [targetProviderName]: aliasTo(value.name),
+                };
+                Object.assign(this.registerClass, registerProviderWithEntities);
+            }
+            catch (error) {
+                throw new InvalidProviderModuleException(value.name, this.module.name, error.message);
+            }
+        }
+    }
+    /**
+     * Agrupación de dependencias para alias
+     *
+     * Este método agrupa las dependencias de la clase utilizando el método
+     * `getClassDependencies` de la instancia `metadata`. Si la clase
+     * tiene dependencias y estas no están vacías, las añade a la propiedad
+     * `dependenciesClass` de la instancia actual para luego validar si existe
+     * alguna dependencia con un nombre diferente y asiganar un alias.
+     *
+     * @private
+     * @param {Function} target - La clase objetivo de la cual se quieren obtener las dependencias.
+     */
+    groupDependenciesForAlias(target) {
+        const dependencies = this.metadata.getClassDependencies(target);
+        this.logger.debug(`Module - List dependecies to group by ${target.name}`, dependencies);
+        if (dependencies && !isEmpty(dependencies)) {
+            this.dependenciesClass = [...this.dependenciesClass, ...dependencies];
+        }
+    }
+    /**
+     * recorre las dependencias agrupadas y registra con un alias
+     * aquellas que tienen nombres diferente a la que esta registrada.
+     *
+     * @private
+     * @example
+     * contructor(private serviceA: ServiceA) // parametro con nombre igual
+     * contructor(private sA: ServiceA) // parametro con nombre diferente
+     */
+    registerDependenciesToAlias() {
+        this.logger.debug('Module - dependencies to register as candidates ', this.dependenciesClass);
+        this.dependenciesClass.forEach((dependency) => {
+            if (!this.registerClass[dependency.nameParameter]) {
+                this.registerClass[dependency.nameParameter] = aliasTo(dependency.nameClassContainer);
+            }
+        });
+    }
+    /**
+     * Toma el listado proveedores y los une al listado de clases que van
+     * a registrar en el contenedor (asValue y asFunction) para ser resueltos
+     */
+    registerAllProviders() {
+        this.logger.debug('Module - Register list provider:', this.module.name);
+        const listProviders = this.injector.getAllProvider();
+        listProviders.forEach((value, key) => {
+            this.registerClass[key] = value;
+        });
+    }
+    /**
+     * Devuelve las importaciones del módulo.
+     * @returns {TClass[] | undefined} - Importaciones del módulo.
+     */
+    getImports() {
+        return this.config.imports;
+    }
+    /**
+     * Devuelve las clases registradas en el módulo.
+     * @returns {any} - Clases registradas.
+     */
+    getRegisterClass() {
+        this.logger.debug(`Module ${this.module.name} - List of candidate classes to register in container.`, this.registerClass);
+        return this.registerClass;
+    }
+}
+
+export { Module };

package/lib/esm/metadata.js

@@ -0,0 +1,164 @@
+import { IS_EXPORT, IS_SERVICE, IS_CONTROLLER, IS_IMPORTS, IS_MODULE, MODULE_EXPORTS, MODULE_SERVICES, MODULE_CONTROLLERS, MODULE_IMPORTS, DEPENDENCIES_CLASS, DEPENDENCIES_PARAMETERS, DEPENDENCIES_INJECT, LIFETIME_CLASS } from '@zanobijs/common/utils/constants';
+
+/**
+ * La clase `Metadata` proporciona métodos para acceder y manipular
+ * metadatos relacionados con diversos componentes y módulos.
+ */
+class Metadata {
+    static instance;
+    metadataMap = {
+        [IS_MODULE]: 'module',
+        [IS_IMPORTS]: 'import',
+        [IS_CONTROLLER]: 'controller',
+        [IS_SERVICE]: 'service',
+        [IS_EXPORT]: 'export',
+    };
+    constructor() { }
+    /**
+     * Obtiene la instancia única (singleton) de `Metadata`.
+     *
+     * @returns La instancia única de `Metadata`.
+     */
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = new Metadata();
+        }
+        return this.instance;
+    }
+    /**
+     * Obtiene los metadatos de un módulo específico.
+     *
+     * @param { IModuleConfig } module - El módulo del cual obtener los metadatos.
+     * @returns Un objeto con los metadatos del módulo
+     * {imports, controllers ,services, exports }.
+     */
+    getMetadataModule(module) {
+        return {
+            imports: Reflect.getMetadata(MODULE_IMPORTS, module),
+            controllers: Reflect.getMetadata(MODULE_CONTROLLERS, module),
+            services: Reflect.getMetadata(MODULE_SERVICES, module),
+            exports: Reflect.getMetadata(MODULE_EXPORTS, module),
+        };
+    }
+    /**
+     * Obtiene todas las dependencias asociadas con una clase.
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Un objeto con las dependencias del target.
+     */
+    getAllDependencies(target) {
+        return {
+            dClass: this.getClassDependencies(target),
+            dParam: this.getParameterDependencies(target),
+            dInject: this.getInjectionDependencies(target),
+        };
+    }
+    /**
+     * Obtiene las dependencias de clase asociadas con una clase.
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Las dependencias de clase de la clase.
+     */
+    getClassDependencies(target) {
+        return Reflect.getMetadata(DEPENDENCIES_CLASS, target);
+    }
+    /**
+     * Obtiene las dependencias de parámetro asociadas con una clase.
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Las dependencias de parámetro de la clase.
+     */
+    getParameterDependencies(target) {
+        return Reflect.getMetadata(DEPENDENCIES_PARAMETERS, target);
+    }
+    /**
+     * Obtiene las dependencias a inyectar asociadas con una clase.
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Un Map con las dependencias a inyectar de la clase.
+     */
+    getInjectionDependencies(target) {
+        return Reflect.getMetadata(DEPENDENCIES_INJECT, target) || new Map();
+    }
+    /**
+     * Obtiene el lifetime declarado en `@Injectable`/`@Controller` de una clase.
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns El lifetime de la clase. `'singleton'` si no se declaró ninguno.
+     */
+    getLifetime(target) {
+        return Reflect.getMetadata(LIFETIME_CLASS, target) ?? 'singleton';
+    }
+    /**
+     * Determina el tipo de una clase basado en sus metadatos.
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Una cadena de texto que indica el tipo del clase segun el mapa de metadata.
+     * @throws {Error} Lanza un error si el tipo de la clase es desconocido.
+     */
+    determineType(target) {
+        for (const key in this.metadataMap) {
+            if (this.hasMetadata(key, target)) {
+                return this.metadataMap[key];
+            }
+        }
+        throw new Error(`${target.name} type is unknown`);
+    }
+    /**
+     * Verifica si una clase tiene un metadato específico.
+     *
+     * @param metadataKey - La llave del metadato a verificar.
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Verdadero si el target tiene el metadato, falso en caso contrario.
+     */
+    hasMetadata(metadataKey, target) {
+        return !!Reflect.getMetadata(metadataKey, target);
+    }
+    /**
+     * Verifica si una clase es de tipo "module".
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Verdadero si el target es de tipo "module", falso en caso contrario.
+     */
+    isTypeModule(target) {
+        return this.hasMetadata(IS_MODULE, target);
+    }
+    /**
+     * Verifica si una clase es de tipo "import".
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Verdadero si el target es de tipo "import", falso en caso contrario.
+     */
+    isTypeImport(target) {
+        return this.hasMetadata(IS_IMPORTS, target);
+    }
+    /**
+     * Verifica si una clase es de tipo "controller".
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Verdadero si el target es de tipo "controller", falso en caso contrario.
+     */
+    isTypeController(target) {
+        return this.hasMetadata(IS_CONTROLLER, target);
+    }
+    /**
+     * Verifica si una clase es de tipo "service".
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Verdadero si el target es de tipo "service", falso en caso contrario.
+     */
+    isTypeService(target) {
+        return this.hasMetadata(IS_SERVICE, target);
+    }
+    /**
+     * Verifica si una clase es de tipo "export".
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns Verdadero si el target es de tipo "export", falso en caso contrario.
+     */
+    isTypeExports(target) {
+        return this.hasMetadata(IS_EXPORT, target);
+    }
+}
+
+export { Metadata };

package/lib/esm/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/lib/types/exceptions/circularModuleImport.exception.d.ts

@@ -0,0 +1,13 @@
+import { RuntimeException } from '@zanobijs/common/exceptions/runtime.exception';
+/**
+ * Excepción lanzada cuando el grafo de `imports` entre módulos contiene un
+ * ciclo: un módulo importa, directa o indirectamente, a otro módulo que ya
+ * lo está importando a él.
+ *
+ * @remarks
+ * Esta clase extiende la base `RuntimeException` de @zanobijs/common
+ * para proporcionar detalles adicionales del error.
+ */
+export declare class CircularModuleImportException extends RuntimeException {
+    constructor(chain: string);
+}

package/{exceptions → lib/types/exceptions}/constant.message.d.ts

@@ -2,3 +2,5 @@ export declare const MODULE_INVALID_ANNOTATION_ERROR: () => string;
 export declare const CONTAINER_RESOLUTION_ERROR: (entity: string, resolutionError: string) => string;
 export declare const CONTAINER_RESOLUTION_ENTITY_ERROR: (entity: string) => string;
 export declare const PROVIDER_INVALID_MODULE_ERROR: (entity: string, moduleName: string) => string;
+export declare const MISSING_INJECT_TOKEN_ERROR: (token: string, targetName: string, moduleName: string) => string;
+export declare const CIRCULAR_MODULE_IMPORT_ERROR: (chain: string) => string;

package/lib/types/exceptions/index.d.ts

@@ -0,0 +1,6 @@
+export * from './constant.message';
+export * from './invalid.module.exception';
+export * from './invalidProvider.module.exception';
+export * from './missingInjectToken.exception';
+export * from './circularModuleImport.exception';
+export * from './resolution.exception';

package/lib/types/exceptions/missingInjectToken.exception.d.ts

@@ -0,0 +1,12 @@
+import { RuntimeException } from '@zanobijs/common/exceptions/runtime.exception';
+/**
+ * Excepción lanzada cuando un `@Inject(token)` no encuentra su provider
+ * registrado, ni en el módulo actual ni en ninguno de los módulos importados.
+ *
+ * @remarks
+ * Esta clase extiende la base `RuntimeException` de @zanobijs/common
+ * para proporcionar detalles adicionales del error.
+ */
+export declare class MissingInjectTokenException extends RuntimeException {
+    constructor(token: string, targetName: string, moduleName: string);
+}

package/lib/types/factory.d.ts

@@ -0,0 +1,106 @@
+import 'reflect-metadata';
+import { AwilixContainer } from 'awilix';
+import { ILoggerService } from '@zanobijs/common';
+import { IFactoryOptions } from './interfaces';
+import { TClass } from './interfaces/globals.interface';
+/**
+ * Handle atado a un scope de `awilix` puntual (una copia liviana del
+ * contenedor raíz, ver `Factory.createRequestScope`). Resuelve entidades
+ * `singleton` desde el contenedor raíz (reusadas, gratis) y entidades
+ * `request` desde este scope (instancia nueva, se descarta con él).
+ */
+export declare class RequestScope {
+    private readonly container;
+    private readonly logger;
+    constructor(container: AwilixContainer<any>, logger: ILoggerService);
+    /**
+     * Resuelve y devuelve una instancia del scope teniendo en cuenta el
+     * nombre de la entidad proporcionada.
+     * @param {string} className - Nombre de la entidad a resolver.
+     * @returns {T} - Instancia resuelta.
+     */
+    get<T>(className: string): T;
+}
+/**
+ * Factory es una clase que facilita la creación y configuración de
+ * contenedores de inyección de dependencias utilizando metadatos y
+ * la librería `awilix` para registrar y resolver entidades como:
+ * controladores y servicios.
+ */
+export declare class Factory {
+    private moduleHandler;
+    private registeredClasses;
+    private container;
+    private logger;
+    private options;
+    private readonly scannedModules;
+    private readonly processedModules;
+    constructor(appModule: TClass, options?: IFactoryOptions);
+    /**
+     * Se encarga de escaenear modulo por modulo los proveedores con el fin de luego
+     * poder ser registrados e inyectados en quien depende de ese proveedor
+     * @param {TClass} module - Módulo desde el que se escanearan los proveedores.
+     * @param {TClass[]} path - Cadena de módulos ancestros en la recursión actual,
+     * usada para detectar ciclos de imports.
+     * @private
+     * @throws {CircularModuleImportException} Si `module` ya está en `path`.
+     */
+    private scanProviderModule;
+    /**
+     * Se encarga tomar la lista de proveedores y registralos para luego se resueltos
+     * cuando el usuario lo solicite
+     * @private
+     */
+    private registerProviderScanedModules;
+    /**
+     * Procesa modulo por modulos registrando los controladores, servicios y proveedores,
+     * estos se le irá inyectando sus dependecias resueltas para ser usados por el usuario
+     * @param {TClass} module - Módulo desde el que se registrarán las clases.
+     * @private
+     *
+     * @remarks
+     * No repite la detección de ciclos: `scanProviderModule` ya recorrió este
+     * mismo grafo de imports antes (misma metadata, mismas aristas) y habría
+     * lanzado `CircularModuleImportException` si existiera uno. Solo se
+     * deduplica por módulo (`processedModules`) para el caso de diamante.
+     */
+    private processClassModule;
+    /**
+     * Crea el contenedor de inyección de dependencias y registra el listado de
+     * controladores, servicio y proveedores que se ha venido creando a parti de escaneos
+     * y registros de clases.
+     * @returns {Factory} - Instancia actual de la fábrica.
+     */
+    create(): Factory;
+    /**
+     * Resuelve y devuelve una instancia del contenedor
+     * teniendo en cuenta el nombre de la entidad proporcionada.
+     * @param {string} className - Nombre de la entidad a resolver.
+     * @returns {T} - Instancia resuelta.
+     * @throws {ContainerResolutionEntityException | ContainerResolutionException}
+     * Si `awilix` no logra resolver la entidad o alguna de sus dependencias.
+     * @throws Propaga sin modificar cualquier otro error (p. ej. uno lanzado por
+     * el propio constructor de la clase que se está resolviendo).
+     */
+    get<T>(className: string): T;
+    /**
+     * Crea una copia liviana del contenedor raíz para usar durante una
+     * única invocación/petición (Lambda, Azure Function, request HTTP...).
+     *
+     * Las entidades `singleton` se reusan tal cual desde el contenedor raíz
+     * (cero costo). Las entidades con `lifetime: 'request'` (ver `@Injectable`)
+     * se resuelven de cero dentro de este scope y se descartan junto con él.
+     *
+     * @returns {RequestScope} - Handle atado a este scope puntual.
+     */
+    createRequestScope(): RequestScope;
+    /**
+     * Se encarga de evaluar las opciones para ver si o no aplica y realizar lo correspondiente
+     *
+     * `ZANOBIJS_LOGGER`/`ZANOBIJS_LOGGER_USER` son pensadas para poder prenderse/apagarse
+     * desde la configuración de despliegue (variables de entorno de Lambda/contenedor) sin
+     * tocar código ni redeployar. Por eso, si el operador ya las configuró externamente,
+     * NO se pisan — `options` solo aplica como default cuando la variable no existe.
+     */
+    private evaluateOptions;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+export { Factory, RequestScope } from './factory';
+export * from './injector';
+export * from './interfaces';
+export * from './exceptions';

package/{injector → lib/types/injector}/injector.d.ts

@@ -33,6 +33,8 @@ export declare class Injector {
      *
      * @param { TClass} target - La clase objetivo.
      * @returns {object} - Objeto con datos a inyectar.
+     * @throws {MissingInjectTokenException} Si un `@Inject(token)` de `target` no tiene
+     * su provider registrado en este módulo ni en ninguno de los módulos importados.
      */
     getInjectData(target: TClass): object;
     /**

package/{metadata.d.ts → lib/types/metadata.d.ts}

@@ -1,4 +1,4 @@
-import { IModuleConfig } from '@zanobijs/common';
+import { ClassLifetime, IModuleConfig } from '@zanobijs/common';
 import { TClass } from './interfaces';
 /**
  * La clase `Metadata` proporciona métodos para acceder y manipular
@@ -54,6 +54,13 @@ export declare class Metadata {
      * @returns Un Map con las dependencias a inyectar de la clase.
      */
     getInjectionDependencies(target: TClass): Map<string, string>;
+    /**
+     * Obtiene el lifetime declarado en `@Injectable`/`@Controller` de una clase.
+     *
+     * @param { TClass } target - La función/clase objetivo.
+     * @returns El lifetime de la clase. `'singleton'` si no se declaró ninguno.
+     */
+    getLifetime(target: TClass): ClassLifetime;
     /**
      * Determina el tipo de una clase basado en sus metadatos.
      *

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@zanobijs/core",
-  "version": "1.2.0",
+  "version": "2.0.0-beta.0",
   "description": "Zanobi - modern, small, powerful node.js lambda framework (@core)",
   "keywords": [],
   "author": "John Edison Cortes Rivera [Devdroide] <johne.aplicativos@gmail.com>",
   "license": "ZanobiJS Usage License \n\n Review the LICENSE file.\n\n Revise el archivo de LICENCIA.",
-  "typings": "index.d.ts",
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "typings": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/devdroide/ZanobiJS.git",
@@ -24,10 +36,14 @@
   "homepage": "https://github.com/devdroide/ZanobiJS#readme",
   "dependencies": {
     "awilix": "10.0.2",
-    "reflect-metadata": "^0.1.13"
+    "reflect-metadata": "^0.1.13",
+    "tslib": "^2.8.1"
   },
   "peerDependencies": {
     "@zanobijs/common": "*"
   },
-  "gitHead": "f1fc586158badcb1f94bfcea4b58061223ebc175"
+  "engines": {
+    "node": ">= 22.13.0"
+  },
+  "gitHead": "201c1b2c289b80d94fcc899dc087b1d95de801d7"
 }