@expressive-tea/core 2.0.0

package/decorators/health.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthCheck = HealthCheck;
+exports.getHealthChecks = getHealthChecks;
+const commons_1 = require("@expressive-tea/commons");
+/**
+ * Health check decorator metadata key
+ * @private
+ */
+const HEALTH_CHECKS_KEY = 'expressive-tea:health-checks';
+/**
+ * Class decorator to register health checks for monitoring and orchestration.
+ *
+ * Adds standardized health check endpoints:
+ * - `/health` - Detailed health status with all checks
+ * - `/health/live` - Liveness probe (Kubernetes compatible)
+ * - `/health/ready` - Readiness probe (only passes if all critical checks pass)
+ *
+ * Health checks are executed asynchronously and can be marked as critical for readiness.
+ * Non-critical checks only affect the detailed `/health` endpoint.
+ *
+ * @decorator {ClassDecorator} HealthCheck - Register health checks
+ * @param options - Health check configuration
+ * @returns Class decorator function
+ * @since 2.0.0
+ * @summary Register application health checks for monitoring
+ *
+ * @example
+ * // Basic health check
+ * @HealthCheck({
+ *   checks: [
+ *     {
+ *       name: 'database',
+ *       check: async () => {
+ *         const isConnected = await db.ping();
+ *         return { status: isConnected ? 'pass' : 'fail' };
+ *       },
+ *       critical: true,
+ *       timeout: 5000
+ *     }
+ *   ]
+ * })
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Multiple health checks with different priorities
+ * @HealthCheck({
+ *   checks: [
+ *     {
+ *       name: 'database',
+ *       check: async () => {
+ *         const connected = await db.ping();
+ *         return {
+ *           status: connected ? 'pass' : 'fail',
+ *           details: { connections: db.poolSize }
+ *         };
+ *       },
+ *       critical: true  // Required for readiness
+ *     },
+ *     {
+ *       name: 'cache',
+ *       check: async () => {
+ *         const ready = await redis.ping();
+ *         return {
+ *           status: ready ? 'pass' : 'warn',  // Warn but don't fail
+ *           details: { cached_items: await redis.dbsize() }
+ *         };
+ *       },
+ *       critical: false  // Optional, won't block readiness
+ *     },
+ *     {
+ *       name: 'external_api',
+ *       check: async () => {
+ *         try {
+ *           const response = await fetch('https://api.example.com/status');
+ *           return { status: response.ok ? 'pass' : 'warn' };
+ *         } catch (error) {
+ *           return {
+ *             status: 'warn',
+ *             error: error.message
+ *           };
+ *         }
+ *       },
+ *       timeout: 3000
+ *     }
+ *   ]
+ * })
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Kubernetes deployment.yaml example
+ * // spec:
+ * //   containers:
+ * //   - name: my-app
+ * //     livenessProbe:
+ * //       httpGet:
+ * //         path: /health/live
+ * //         port: 3000
+ * //       initialDelaySeconds: 30
+ * //       periodSeconds: 10
+ * //     readinessProbe:
+ * //       httpGet:
+ * //         path: /health/ready
+ * //         port: 3000
+ * //       initialDelaySeconds: 5
+ * //       periodSeconds: 5
+ */
+function HealthCheck(options) {
+    return (target) => {
+        // Store health checks in metadata
+        commons_1.Metadata.set(HEALTH_CHECKS_KEY, options.checks, target);
+        return target;
+    };
+}
+/**
+ * Get health checks from a class
+ * @param target - Target class
+ * @returns Array of health checks
+ * @since 2.0.0
+ * @internal
+ */
+function getHealthChecks(target) {
+    return commons_1.Metadata.get(HEALTH_CHECKS_KEY, target) || [];
+}

package/decorators/module.d.ts

@@ -0,0 +1,34 @@
+import { type ExpressiveTeaModuleProps } from '@expressive-tea/commons';
+import { type Constructor } from '../types/core';
+import { type ModulizedClass } from '../mixins/module';
+/**
+ * @typedef {Object} ExpressiveTeaModuleProps
+ * @property {Object[]} controllers Controllers Assigned to Module
+ * @property {Object[]} providers Dependency Injection Providers
+ * @property {string} mountpoint Endpoint part which Module it will use as root.
+ */
+/**
+ * @module Decorators/Module
+ */
+/**
+ * Module Decorator is a Class Decorator which is help to register a Module into Expressive Tea. A module is a
+ * placeholder over a mountpoint. We can considerate a module like a container which provide isolation and modularity
+ * for our project. This module can be mounted in different applications and will move all the controller routes too.
+ *
+ * @decorator {ClassDecorator} Module - Module Class Register Decorator
+ * @template TBase - The base constructor type being decorated
+ * @param {ExpressiveTeaModuleProps} options - Module configuration options
+ * @returns {(target: TBase) => ModulizedClass<TBase>} Decorator function that returns a modulized class
+ * @summary Module Decorator
+ *
+ * @example
+ * {REPLACE-AT}Module({
+ *   controllers: [UserController],
+ *   providers: [UserService],
+ *   mountpoint: '/api'
+ * })
+ * class ApiModule {}
+ *
+ * @since 1.0.0
+ */
+export declare function Module<TBase extends Constructor = Constructor>(options: ExpressiveTeaModuleProps): (target: TBase) => ModulizedClass<TBase>;

package/decorators/module.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Module = Module;
+const module_1 = require("../mixins/module");
+/**
+ * @typedef {Object} ExpressiveTeaModuleProps
+ * @property {Object[]} controllers Controllers Assigned to Module
+ * @property {Object[]} providers Dependency Injection Providers
+ * @property {string} mountpoint Endpoint part which Module it will use as root.
+ */
+/**
+ * @module Decorators/Module
+ */
+/**
+ * Module Decorator is a Class Decorator which is help to register a Module into Expressive Tea. A module is a
+ * placeholder over a mountpoint. We can considerate a module like a container which provide isolation and modularity
+ * for our project. This module can be mounted in different applications and will move all the controller routes too.
+ *
+ * @decorator {ClassDecorator} Module - Module Class Register Decorator
+ * @template TBase - The base constructor type being decorated
+ * @param {ExpressiveTeaModuleProps} options - Module configuration options
+ * @returns {(target: TBase) => ModulizedClass<TBase>} Decorator function that returns a modulized class
+ * @summary Module Decorator
+ *
+ * @example
+ * {REPLACE-AT}Module({
+ *   controllers: [UserController],
+ *   providers: [UserService],
+ *   mountpoint: '/api'
+ * })
+ * class ApiModule {}
+ *
+ * @since 1.0.0
+ */
+function Module(options) {
+    return (Module) => {
+        return (0, module_1.Modulize)(Module, options);
+    };
+}

package/decorators/proxy.d.ts

@@ -0,0 +1,28 @@
+import { type ExpressiveTeaProxyOptions, type ExpressiveTeaProxyProperty, type MethodDecorator } from '@expressive-tea/commons';
+import { type ProxifiedClass } from '../mixins/proxy';
+import { type Constructor } from '../types/core';
+/**
+ * ProxyContainer decorator - Creates an HTTP proxy for a microservice
+ *
+ * Transforms a class into an HTTP proxy that forwards requests from a source path
+ * to a target URL. Supports custom request/response transformations and options.
+ *
+ * @template TBase - The base constructor type being decorated
+ * @param {string} source - The source path to proxy from (e.g., '/api')
+ * @param {string} targetUrl - The target URL to proxy to (e.g., 'http://api.example.com')
+ * @returns {(target: TBase) => ProxifiedClass<TBase>} Decorator function that returns a proxified class
+ *
+ * @example
+ * {REPLACE-AT}ProxyContainer('/api', 'http://api.example.com')
+ * class ApiProxy {
+ *   {REPLACE-AT}ProxyOption('host')
+ *   getHost() {
+ *     return 'http://api.example.com';
+ *   }
+ * }
+ *
+ * @since 1.0.0
+ */
+export declare function ProxyContainer<TBase extends Constructor = Constructor>(source: string, targetUrl: string): (ProxyContainerClass: TBase) => ProxifiedClass<TBase>;
+export declare function ProxyOption(option: ExpressiveTeaProxyOptions): MethodDecorator;
+export declare function ProxyProperty(option: ExpressiveTeaProxyProperty, value: any): PropertyDecorator;

package/decorators/proxy.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyContainer = ProxyContainer;
+exports.ProxyOption = ProxyOption;
+exports.ProxyProperty = ProxyProperty;
+const commons_1 = require("@expressive-tea/commons");
+const commons_2 = require("@expressive-tea/commons");
+const RequestExceptions_1 = require("../exceptions/RequestExceptions");
+const commons_3 = require("@expressive-tea/commons");
+const proxy_1 = require("../mixins/proxy");
+const NON_ASYNC_METHODS = new Set(['host']);
+/**
+ * ProxyContainer decorator - Creates an HTTP proxy for a microservice
+ *
+ * Transforms a class into an HTTP proxy that forwards requests from a source path
+ * to a target URL. Supports custom request/response transformations and options.
+ *
+ * @template TBase - The base constructor type being decorated
+ * @param {string} source - The source path to proxy from (e.g., '/api')
+ * @param {string} targetUrl - The target URL to proxy to (e.g., 'http://api.example.com')
+ * @returns {(target: TBase) => ProxifiedClass<TBase>} Decorator function that returns a proxified class
+ *
+ * @example
+ * {REPLACE-AT}ProxyContainer('/api', 'http://api.example.com')
+ * class ApiProxy {
+ *   {REPLACE-AT}ProxyOption('host')
+ *   getHost() {
+ *     return 'http://api.example.com';
+ *   }
+ * }
+ *
+ * @since 1.0.0
+ */
+function ProxyContainer(source, targetUrl) {
+    return (ProxyContainerClass) => {
+        const settings = {
+            source,
+            targetUrl,
+            name: ProxyContainerClass.name
+        };
+        commons_1.Metadata.set(commons_3.PROXY_SETTING_KEY, settings, ProxyContainerClass);
+        return (0, proxy_1.Proxify)(ProxyContainerClass, source, targetUrl);
+    };
+}
+function ProxyOption(option) {
+    return (target, propertyKey, descriptor) => {
+        if (NON_ASYNC_METHODS.has(option) && (0, commons_2.isAsyncFunction)(descriptor.value)) {
+            throw new RequestExceptions_1.GenericRequestException(`${String(propertyKey)} must not be declared as Async Function.`);
+        }
+        commons_1.Metadata.set(commons_3.PROXY_SETTING_KEY, descriptor, target, option);
+    };
+}
+function ProxyProperty(option, value) {
+    return (target, propertyKey) => {
+        commons_1.Metadata.set(commons_3.PROXY_SETTING_KEY, propertyKey, target, option);
+        Object.defineProperty(target, propertyKey, {
+            get: () => value,
+        });
+    };
+}

package/decorators/router.d.ts

@@ -0,0 +1,199 @@
+import { type ClassDecorator, type MethodDecorator } from '@expressive-tea/commons';
+import { type RouterizedClass } from '../mixins/route';
+import { type Constructor, TFunction } from '../types/core';
+import { type RequestHandler } from 'express';
+/**
+ * @module Decorators/Router
+ */
+/**
+ * Route Controller Decorator assign a router point into the module mount-point placeholder and is used just to create
+ * a bucket to contains all the endpoints defined by method of the Controller.  If mount-point is not defined automati-
+ * cally this must considerate mounted on root, but is mandatory define the Controller with this decorator in order
+ * to allow Expressive Tea Setting up the Controller as part of a Module.
+ *
+ * @decorator {ClassDecorator} Route - Assign a route to controller endpoints.
+ * @template TBase - The base constructor type being decorated
+ * @param {string} mountpoint - Register the url part to mount the Controller (default: '/')
+ * @returns {(target: TBase) => RouterizedClass<TBase>} Decorator function that returns a routerized class
+ * @summary Generate a Placeholder endpoint root for controller routes.
+ *
+ * @example
+ * {REPLACE-AT}Route('/users')
+ * class UserController {
+ *   {REPLACE-AT}Get('/')
+ *   getUsers() { return ['user1', 'user2']; }
+ * }
+ *
+ * @since 1.0.0
+ */
+export declare function Route<TBase extends Constructor = Constructor>(mountpoint?: string): (RouterClass: TBase) => RouterizedClass<TBase>;
+/**
+ * Define a GET Endpoint response over the controller router and can define in which route should be responds and
+ * by default this is responding to everything on the controller root path.
+ * @decorator {MethodDecorator} Get - Create an GET Response over the designed route.
+ * @summary Define a GET Controller Endpoint on Controller.
+ * @param {string} route URL Part to mount create a handler.
+ * @example
+ * {REPLACE-AT}Route('/')
+ * class GenericController {
+ *   {REPLACE-AT}Get() // This Response to all GET Requests for controller route.
+ *   methodError() {}
+ *
+ *   {REPLACE-AT}Get('/data') // This Response to "/data" GET Requests for controller route.
+ *   methodData() {}
+ * }
+ *
+ */
+export declare function Get(route?: string): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Define a POST Endpoint response over the controller router and can define in which route should be responds and
+ * by default this is responding to everything on the controller root path.
+ * @decorator {MethodDecorator} POST - Create an POST Response over the designed route.
+ * @summary Define a POST Controller Endpoint on Controller.
+ * @param {string} route URL Part to mount create a handler.
+ * @example
+ * {REPLACE-AT}Route('/')
+ * class GenericController {
+ *   {REPLACE-AT}Post() // This Response to all GET Requests for controller route.
+ *   methodError() {}
+ *
+ *   {REPLACE-AT}Post('/data') // This Response to "/data" GET Requests for controller route.
+ *   methodData() {}
+ * }
+ *
+ */
+export declare function Post(route?: string): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Define a PUT Endpoint response over the controller router and can define in which route should be responds and
+ * by default this is responding to everything on the controller root path.
+ * @decorator {MethodDecorator} Put - Create an PUT Response over the designed route.
+ * @summary Define a PUT Controller Endpoint on Controller.
+ * @param {string} route URL Part to mount create a handler.
+ * @example
+ * {REPLACE-AT}Route('/')
+ * class GenericController {
+ *   {REPLACE-AT}Put() // This Response to all PUT Requests for controller route.
+ *   methodError() {}
+ *
+ *   {REPLACE-AT}Put('/data') // This Response to "/data" PUT Requests for controller route.
+ *   methodData() {}
+ * }
+ *
+ */
+export declare function Put(route?: string): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Define a PATCH Endpoint response over the controller router and can define in which route should be responds and
+ * by default this is responding to everything on the controller root path.
+ * @decorator {MethodDecorator} Patch - Create an PATCH Response over the designed route.
+ * @summary Define a PATCH Controller Endpoint on Controller.
+ * @param {string} route URL Part to mount create a handler.
+ * @example
+ * {REPLACE-AT}Route('/')
+ * class GenericController {
+ *   {REPLACE-AT}Patch() // This Response to all PATCH Requests for controller route.
+ *   methodError() {}
+ *
+ *   {REPLACE-AT}Patch('/data') // This Response to "/data" PATCH Requests for controller route.
+ *   methodData() {}
+ * }
+ *
+ */
+export declare function Patch(route?: string): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Define a DELETE Endpoint response over the controller router and can define in which route should be responds and
+ * by default this is responding to everything on the controller root path.
+ * @decorator {MethodDecorator} Delete - Create an DELETE Response over the designed route.
+ * @summary Define a DELETE Controller Endpoint on Controller.
+ * @param {string} route URL Part to mount create a handler.
+ * @example
+ * {REPLACE-AT}Route('/')
+ * class GenericController {
+ *   {REPLACE-AT}Delete() // This Response to all DELETE Requests for controller route.
+ *   methodError() {}
+ *
+ *   {REPLACE-AT}Delete('/data') // This Response to "/data" DELETE Requests for controller route.
+ *   methodData() {}
+ * }
+ *
+ */
+export declare function Delete(route?: string): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Define a Route path parameter transformation method as mentioned on Express this is just call by controller endpoints
+ * route paths and it helps to define logic on each route path parameters. Example, you can require transform userId
+ * parameter and added to request object.
+ *
+ * The method to response this must follow the Express callback notation (Request, Response, Next, paramValue) which
+ * also must be use Next method to allow continue the process flow from Express.
+ * @decorator {MethodDecorator} Param - Create a transformation middleware for router parameters.
+ * @summary Define a Parameter transformation on router path..
+ * @param {string} route URL Part to mount create a handler.
+ * @example
+ * {REPLACE-AT}Route('/')
+ * class GenericController {
+ *   {REPLACE-AT}Param('userId') // This Response to all GET Requests for controller route.
+ *   async methodError(req, res, next, param, id) {
+ *     const user = await User.find(id)
+ *     try {
+ *       if(!user) throw new Error('User not Found');
+ *
+ *       req.user = user;
+ *       next();
+ *     } catch(e) {
+ *       next(e);
+ *     }
+ *   }
+ *
+ *   {REPLACE-AT}Get('/:userId') // This Response to "/:userId" GET Requests for controller route.
+ *   methodData(req, res) {
+ *    res.json(req.user);
+ *   }
+ * }
+ *
+ */
+export declare function Param(route?: string): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Middleware Decorator is following the middleware functionality inheritance from Express framework itself and follow
+ * the same rules, that execute any code before response the request and can change the current request or response
+ * object, and requires use next callback to pass control to next middleware.
+ *
+ * This define the middlewares at Controller and Controller methods level, for application levels please see the
+ * Plug Decorator which can be useful to declare at that level..
+ * @decorator {MethodDecorator|ClassDecorator} Middleware - Attach a middleware definition on the root route or endpoint
+ * routes.
+ * @summary Assign a middleware to the Controller or Method route path flow.
+ * @example
+ * {REPLACE-AT}Middleware((req, res, next) {
+ *     req.controllerName = 'Example';
+ *     next();
+ *  })
+ * class ExampleController {
+ *   {REPLACE-AT}Get('/someResponse')
+ *   {REPLACE-AT}Middleware((req, res, next) {
+ *     req.methodName = 'someResponse';
+ *     next();
+ *   })
+ *   someRespone(req, res) {
+ *     res.send(`${req.controllerName}:${req.methodName}`);
+ *   }
+ * }
+ *
+ * @param {Function} middleware Register a middleware over router.
+ */
+export declare function Middleware(middleware: RequestHandler | TFunction<RequestHandler>): ClassDecorator & MethodDecorator;
+/**
+ * Will generate a GET route to respond rendering a view template setting up before; the controller method <b>MUST</b>
+ * return an object in order to fulfilled the local variables into the view.
+ * @decorator {MethodDecorator}  View - Create a Vew Response over the designed route.
+ * @summary Define a View response endpoint on Controller.
+ * @param {string} viewName - View render layout name defined by configuration.
+ * @param {string} route - URL Part to mount create a handler.
+ * @return {object} Controller must return and object as local variables for the view.
+ * @example
+ * {REPLACE-AT}Route('/')
+ * class GenericController {
+ *   {REPLACE-AT}View('login', '/view') // This Response to all GET Requests for controller route.
+ *   methodError() {}
+ * }
+ *
+ */
+export declare function View(viewName: string, route?: string): MethodDecorator;