@expressive-tea/core 2.0.0

package/decorators/annotations.d.ts

@@ -0,0 +1,91 @@
+import { type ParameterDecorator } from '@expressive-tea/commons';
+/**
+ * Is passing directly to the decorated argument described <a href="http://expressjs.com/en/4x/api.html#req">here</a>.
+ * @decorator {ParameterDecorator} request - Assign express Request instance to parameter.
+ * @summary Assign Express Request Instance.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   methodError({REPLACE-AT}request req) {}
+ * }
+ *
+ */
+export declare function request(target: object, propertyKey: string | symbol, parameterIndex: number): void;
+/**
+ * Is passing directly to the decorated argument described <a href="http://expressjs.com/en/4x/api.html#res">here</a>.
+ * @decorator {ParameterDecorator} response - Assign express Response instance to parameter.
+ * @summary Assign Express Response Instance.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   methodError({REPLACE-AT}response res) {}
+ * }
+ *
+ */
+export declare function response(target: object, propertyKey: string | symbol, parameterIndex: number): void;
+/**
+ * Is passing directly to the decorated argument and you can check how is working following the next guide
+ * <a href="http://expressjs.com/en/guide/using-middleware.html">here</a>.
+ * @decorator {ParameterDecorator} next - Assign express Next Callback function to parameter.
+ * @summary Assign Express Next Callback function.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   methodError({REPLACE-AT}next next) {}
+ * }
+ *
+ */
+export declare function next(target: object, propertyKey: string | symbol, parameterIndex: number): void;
+/**
+ * It will pass a get query parameters which it must be defined on the query parameters string unless it will get a
+ * undefined result. This decorator provides the way to return query parameters in one of the next ways: <br>
+ * <b>whole</b> query object when no parameters is passing to the decorator. <br>
+ * <b>partial</b> query object when a list of parameters name is passing to the decorator. <br>
+ * <b>single</b> query parameter when pass a field name directly to the decorator.
+ * @decorator {ParameterDecorator} query - Assign a single, partial or whole url query parameters.
+ * @summary Get URL Query Parameters.
+ * @param {string | string[] | undefined } parameter - Name or parameter's list name.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   method({REPLACE-AT}query() req) {}
+ *   method2({REPLACE-AT}query('username') username) {}
+ *   method3({REPLACE-AT}query(['username', 'password']) credentials) {}
+ * }
+ *
+ */
+export declare function query(parameter?: string | string[]): ParameterDecorator;
+/**
+ * It will pass a get body parameters which it must be defined on the request body, unless it will get a
+ * undefined result. This decorator provides the way to return body parameters in one of the next ways: <br>
+ * <b>whole</b> body object when no parameters is passing to the decorator. <br>
+ * <b>partial</b> body object when a list of parameters name is passing to the decorator. <br>
+ * <b>single</b> body parameter when pass a field name directly to the decorator.
+ * @decorator {ParameterDecorator} body - Assign a single, partial or whole request body parameters.
+ * @summary Assign parameter(s) from body request object.
+ * @param {string | string[] | undefined } bodyParam - Name or parameter's list name.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   method({REPLACE-AT}body() req) {}
+ *   method2({REPLACE-AT}body('username') username) {}
+ *   method3({REPLACE-AT}body(['username', 'password']) credentials) {}
+ * }
+ *
+ */
+export declare function body(bodyParam?: string | string[]): ParameterDecorator;
+/**
+ * It will return the value defined on the url path for the current method or a global middleware, this only works
+ * for single parameter, and also might be side affected if there is an any <b>param</b> decorator is declared for the
+ * the selected parameter it will transformed first and passed the value.
+ * @decorator {ParameterDecorator} param - Assign url parameter.
+ * @summary Get a parameter value defined on the url by path.
+ * @param {string} parameter id name.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/:userId') // This Response to all GET Requests for controller route.
+ *   method({REPLACE-AT}param('userId') username) {}
+ * }
+ *
+ */
+export declare function param(parameter: string): ParameterDecorator;

package/decorators/annotations.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.request = request;
+exports.response = response;
+exports.next = next;
+exports.query = query;
+exports.body = body;
+exports.param = param;
+const commons_1 = require("@expressive-tea/commons");
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+const commons_2 = require("@expressive-tea/commons");
+/**
+ * @module Decorators/Annotations
+ */
+function addToArguments(target, propertyKey, parameterIndex, type, args) {
+    const decoratedParameters = commons_1.Metadata.get(commons_2.ARGUMENTS_KEY, target, propertyKey) || [];
+    decoratedParameters.unshift({
+        arguments: args,
+        index: parameterIndex,
+        key: propertyKey,
+        type
+    });
+    commons_1.Metadata.set(commons_2.ARGUMENTS_KEY, decoratedParameters, target, propertyKey);
+}
+/**
+ * Is passing directly to the decorated argument described <a href="http://expressjs.com/en/4x/api.html#req">here</a>.
+ * @decorator {ParameterDecorator} request - Assign express Request instance to parameter.
+ * @summary Assign Express Request Instance.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   methodError({REPLACE-AT}request req) {}
+ * }
+ *
+ */
+function request(target, propertyKey, parameterIndex) {
+    addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.REQUEST);
+}
+/**
+ * Is passing directly to the decorated argument described <a href="http://expressjs.com/en/4x/api.html#res">here</a>.
+ * @decorator {ParameterDecorator} response - Assign express Response instance to parameter.
+ * @summary Assign Express Response Instance.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   methodError({REPLACE-AT}response res) {}
+ * }
+ *
+ */
+function response(target, propertyKey, parameterIndex) {
+    addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.RESPONSE);
+}
+/**
+ * Is passing directly to the decorated argument and you can check how is working following the next guide
+ * <a href="http://expressjs.com/en/guide/using-middleware.html">here</a>.
+ * @decorator {ParameterDecorator} next - Assign express Next Callback function to parameter.
+ * @summary Assign Express Next Callback function.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   methodError({REPLACE-AT}next next) {}
+ * }
+ *
+ */
+function next(target, propertyKey, parameterIndex) {
+    addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.NEXT);
+}
+/**
+ * It will pass a get query parameters which it must be defined on the query parameters string unless it will get a
+ * undefined result. This decorator provides the way to return query parameters in one of the next ways: <br>
+ * <b>whole</b> query object when no parameters is passing to the decorator. <br>
+ * <b>partial</b> query object when a list of parameters name is passing to the decorator. <br>
+ * <b>single</b> query parameter when pass a field name directly to the decorator.
+ * @decorator {ParameterDecorator} query - Assign a single, partial or whole url query parameters.
+ * @summary Get URL Query Parameters.
+ * @param {string | string[] | undefined } parameter - Name or parameter's list name.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   method({REPLACE-AT}query() req) {}
+ *   method2({REPLACE-AT}query('username') username) {}
+ *   method3({REPLACE-AT}query(['username', 'password']) credentials) {}
+ * }
+ *
+ */
+function query(parameter) {
+    return (target, propertyKey, parameterIndex) => {
+        addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.QUERY, parameter);
+    };
+}
+/**
+ * It will pass a get body parameters which it must be defined on the request body, unless it will get a
+ * undefined result. This decorator provides the way to return body parameters in one of the next ways: <br>
+ * <b>whole</b> body object when no parameters is passing to the decorator. <br>
+ * <b>partial</b> body object when a list of parameters name is passing to the decorator. <br>
+ * <b>single</b> body parameter when pass a field name directly to the decorator.
+ * @decorator {ParameterDecorator} body - Assign a single, partial or whole request body parameters.
+ * @summary Assign parameter(s) from body request object.
+ * @param {string | string[] | undefined } bodyParam - Name or parameter's list name.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/') // This Response to all GET Requests for controller route.
+ *   method({REPLACE-AT}body() req) {}
+ *   method2({REPLACE-AT}body('username') username) {}
+ *   method3({REPLACE-AT}body(['username', 'password']) credentials) {}
+ * }
+ *
+ */
+function body(bodyParam) {
+    return (target, propertyKey, parameterIndex) => {
+        addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.BODY, bodyParam);
+    };
+}
+/**
+ * It will return the value defined on the url path for the current method or a global middleware, this only works
+ * for single parameter, and also might be side affected if there is an any <b>param</b> decorator is declared for the
+ * the selected parameter it will transformed first and passed the value.
+ * @decorator {ParameterDecorator} param - Assign url parameter.
+ * @summary Get a parameter value defined on the url by path.
+ * @param {string} parameter id name.
+ * @example
+ * class GenericController {
+ *   {REPLACE-AT}Get('/:userId') // This Response to all GET Requests for controller route.
+ *   method({REPLACE-AT}param('userId') username) {}
+ * }
+ *
+ */
+function param(parameter) {
+    return (target, propertyKey, parameterIndex) => {
+        addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.GET_PARAM, parameter);
+    };
+}

package/decorators/env.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Environment variable loading options with optional transformation
+ * @interface EnvOptions
+ * @template T - Type of transformed environment variables
+ * @since 2.0.0
+ */
+export interface EnvOptions<T = Record<string, string>> {
+    /**
+     * Path to the .env file (relative to project root)
+     * @default '.env'
+     */
+    path?: string;
+    /**
+     * Whether to override existing environment variables
+     * @default false
+     */
+    override?: boolean;
+    /**
+     * List of required environment variables (will throw if missing)
+     */
+    required?: string[];
+    /**
+     * Whether to ignore missing .env file
+     * @default false
+     */
+    silent?: boolean;
+    /**
+     * Optional transformation function for type-safe environment variables.
+     * Receives parsed env vars and returns transformed result.
+     * Use with validation libraries like Zod for runtime type safety.
+     *
+     * @param env - Parsed environment variables
+     * @returns Transformed and validated environment variables
+     * @since 2.0.1
+     *
+     * @example
+     * import { z } from 'zod';
+     * const EnvSchema = z.object({
+     *   PORT: z.string().transform(Number),
+     *   DATABASE_URL: z.string().url()
+     * });
+     *
+     * @Env({
+     *   transform: (env) => EnvSchema.parse(env),
+     *   onTransformError: 'throw'
+     * })
+     */
+    transform?: (env: Record<string, string>) => T;
+    /**
+     * Behavior when transform function throws an error
+     * - 'throw': Re-throw error immediately (fail-fast, recommended for production)
+     * - 'warn': Log warning and continue with unvalidated env
+     * - 'ignore': Silent failure, continue without transform
+     *
+     * @default 'throw'
+     * @since 2.0.1
+     */
+    onTransformError?: 'throw' | 'warn' | 'ignore';
+}
+/**
+ * Retrieve transformed environment variables from global storage.
+ * Returns null if no transform was applied.
+ *
+ * @template T - Type of transformed environment variables
+ * @returns Transformed environment variables or null
+ * @since 2.0.1
+ *
+ * @example
+ * const env = getTransformedEnv<MyEnvType>();
+ * if (env) {
+ *   console.log(env.PORT); // Type-safe access
+ * }
+ */
+export declare function getTransformedEnv<T>(): T | null;
+/**
+ * Class decorator to load environment variables from .env files before application initialization.
+ *
+ * This decorator can be stacked to load multiple .env files in order, allowing for
+ * environment-specific overrides (e.g., .env → .env.local → .env.production).
+ *
+ * Environment variables are loaded BEFORE the Settings singleton is initialized,
+ * ensuring they're available during the entire application lifecycle.
+ *
+ * **New in v2.0.1:** Optional type-safe transformation with validation libraries like Zod.
+ *
+ * @decorator {ClassDecorator} Env - Load environment variables from .env file
+ * @template T - Type of transformed environment variables
+ * @param options - Environment loading options
+ * @returns Class decorator function
+ * @since 2.0.0
+ * @summary Load environment variables from .env files with optional type-safe transformation
+ *
+ * @example
+ * // Basic usage - load from .env
+ * @Env()
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Load from custom path with required variables
+ * @Env({
+ *   path: '.env.production',
+ *   required: ['DATABASE_URL', 'API_KEY']
+ * })
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Stack multiple .env files (loaded in order)
+ * @Env({ path: '.env' })
+ * @Env({ path: '.env.local', override: true, silent: true })
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Type-safe transformation with Zod
+ * import { z } from 'zod';
+ *
+ * const EnvSchema = z.object({
+ *   PORT: z.string().transform(Number),
+ *   DATABASE_URL: z.string().url(),
+ *   API_KEY: z.string().min(32)
+ * });
+ *
+ * type Env = z.infer<typeof EnvSchema>;
+ *
+ * @Env<Env>({
+ *   path: '.env',
+ *   required: ['DATABASE_URL', 'API_KEY'],
+ *   transform: (env) => EnvSchema.parse(env),
+ *   onTransformError: 'throw' // Fail fast on invalid env
+ * })
+ * class MyApp extends Boot {
+ *   constructor() {
+ *     super();
+ *     // Access type-safe env
+ *     const env = Settings.getInstance().getEnv<Env>();
+ *     console.log(env.PORT); // Type: number
+ *   }
+ * }
+ *
+ * @example
+ * // In your .env file:
+ * // DATABASE_URL=postgres://localhost:5432/mydb
+ * // API_KEY="secret-key-with-special-chars"
+ * // PORT=3000
+ */
+export declare function Env<T = Record<string, string>>(options?: EnvOptions<T>): ClassDecorator;

package/decorators/env.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTransformedEnv = getTransformedEnv;
+exports.Env = Env;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const dotenv = require("dotenv");
+/**
+ * Global storage for transformed environment variables.
+ * Set by @Env decorator when transform option is provided.
+ * @private
+ */
+let transformedEnv = null;
+/**
+ * Store transformed environment variables in global storage.
+ * Used internally by @Env decorator.
+ *
+ * @template T - Type of transformed environment variables
+ * @param env - Transformed environment variables
+ * @private
+ * @since 2.0.1
+ */
+function storeTransformedEnv(env) {
+    transformedEnv = env;
+}
+/**
+ * Retrieve transformed environment variables from global storage.
+ * Returns null if no transform was applied.
+ *
+ * @template T - Type of transformed environment variables
+ * @returns Transformed environment variables or null
+ * @since 2.0.1
+ *
+ * @example
+ * const env = getTransformedEnv<MyEnvType>();
+ * if (env) {
+ *   console.log(env.PORT); // Type-safe access
+ * }
+ */
+function getTransformedEnv() {
+    return transformedEnv;
+}
+/**
+ * Load environment variables from a .env file using dotenv.
+ * Supports transformation and validation via optional transform function.
+ *
+ * @template T - Type of transformed environment variables
+ * @param options - Environment loading options
+ * @throws {Error} If required variables are missing, file is not found (when not silent), or transform fails (when onTransformError='throw')
+ * @since 2.0.0
+ * @private
+ */
+function loadEnvFile(options) {
+    const { path: envPath = '.env', override = false, required = [], silent = false, transform, onTransformError = 'throw' } = options;
+    const fullPath = (0, path_1.resolve)(process.cwd(), envPath);
+    // Check if file exists
+    if (!(0, fs_1.existsSync)(fullPath)) {
+        if (!silent) {
+            throw new Error(`Environment file not found: ${fullPath}`);
+        }
+        return undefined;
+    }
+    // Load with dotenv
+    const result = dotenv.config({
+        path: fullPath,
+        override
+    });
+    if (result.error && !silent) {
+        throw new Error(`Failed to load ${fullPath}: ${result.error.message}`);
+    }
+    // Validate required variables
+    const missing = required.filter((key) => process.env[key] === undefined);
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+    }
+    // Apply transform if provided
+    if (transform) {
+        try {
+            const envVars = result.parsed || {};
+            const transformed = transform(envVars);
+            // Store transformed result globally
+            storeTransformedEnv(transformed);
+            return transformed;
+        }
+        catch (error) {
+            const errorMsg = `Environment transformation failed: ${error.message}`;
+            if (onTransformError === 'throw') {
+                throw new Error(errorMsg);
+            }
+            else if (onTransformError === 'warn') {
+                console.warn(`[Expressive Tea] ${errorMsg}`);
+                if (error.stack) {
+                    console.warn(error.stack);
+                }
+            }
+            // 'ignore' - do nothing, return undefined
+        }
+    }
+    return undefined;
+}
+/**
+ * Class decorator to load environment variables from .env files before application initialization.
+ *
+ * This decorator can be stacked to load multiple .env files in order, allowing for
+ * environment-specific overrides (e.g., .env → .env.local → .env.production).
+ *
+ * Environment variables are loaded BEFORE the Settings singleton is initialized,
+ * ensuring they're available during the entire application lifecycle.
+ *
+ * **New in v2.0.1:** Optional type-safe transformation with validation libraries like Zod.
+ *
+ * @decorator {ClassDecorator} Env - Load environment variables from .env file
+ * @template T - Type of transformed environment variables
+ * @param options - Environment loading options
+ * @returns Class decorator function
+ * @since 2.0.0
+ * @summary Load environment variables from .env files with optional type-safe transformation
+ *
+ * @example
+ * // Basic usage - load from .env
+ * @Env()
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Load from custom path with required variables
+ * @Env({
+ *   path: '.env.production',
+ *   required: ['DATABASE_URL', 'API_KEY']
+ * })
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Stack multiple .env files (loaded in order)
+ * @Env({ path: '.env' })
+ * @Env({ path: '.env.local', override: true, silent: true })
+ * class MyApp extends Boot {}
+ *
+ * @example
+ * // Type-safe transformation with Zod
+ * import { z } from 'zod';
+ *
+ * const EnvSchema = z.object({
+ *   PORT: z.string().transform(Number),
+ *   DATABASE_URL: z.string().url(),
+ *   API_KEY: z.string().min(32)
+ * });
+ *
+ * type Env = z.infer<typeof EnvSchema>;
+ *
+ * @Env<Env>({
+ *   path: '.env',
+ *   required: ['DATABASE_URL', 'API_KEY'],
+ *   transform: (env) => EnvSchema.parse(env),
+ *   onTransformError: 'throw' // Fail fast on invalid env
+ * })
+ * class MyApp extends Boot {
+ *   constructor() {
+ *     super();
+ *     // Access type-safe env
+ *     const env = Settings.getInstance().getEnv<Env>();
+ *     console.log(env.PORT); // Type: number
+ *   }
+ * }
+ *
+ * @example
+ * // In your .env file:
+ * // DATABASE_URL=postgres://localhost:5432/mydb
+ * // API_KEY="secret-key-with-special-chars"
+ * // PORT=3000
+ */
+function Env(options = {}) {
+    return (target) => {
+        // Load env file immediately when decorator is applied
+        loadEnvFile(options);
+        return target;
+    };
+}

package/decorators/health.d.ts

@@ -0,0 +1,115 @@
+import type { HealthCheck as HealthCheckConfig } from '../engines/health';
+/**
+ * Health check decorator options
+ * @since 2.0.0
+ */
+export interface HealthCheckOptions {
+    /** Array of health checks to register */
+    checks: HealthCheckConfig[];
+}
+/**
+ * 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
+ */
+export declare function HealthCheck(options: HealthCheckOptions): ClassDecorator;
+/**
+ * Get health checks from a class
+ * @param target - Target class
+ * @returns Array of health checks
+ * @since 2.0.0
+ * @internal
+ */
+export declare function getHealthChecks(target: any): HealthCheckConfig[];