@zerooneit/expressive-tea 1.3.0-beta.5 → 2.0.0

package/decorators/annotations.js

@@ -1,20 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.param = exports.body = exports.query = exports.next = exports.response = exports.request = void 0;
-const Metadata_1 = require("@expressive-tea/commons/classes/Metadata");
-const constants_1 = require("@expressive-tea/commons/constants");
+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 = Metadata_1.default.get(constants_1.ARGUMENTS_KEY, target, propertyKey) || [];
+    const decoratedParameters = commons_1.Metadata.get(commons_2.ARGUMENTS_KEY, target, propertyKey) || [];
     decoratedParameters.unshift({
         arguments: args,
         index: parameterIndex,
         key: propertyKey,
         type
     });
-    Metadata_1.default.set(constants_1.ARGUMENTS_KEY, decoratedParameters, target, propertyKey);
+    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>.
@@ -28,9 +34,8 @@ function addToArguments(target, propertyKey, parameterIndex, type, args) {
  *
  */
 function request(target, propertyKey, parameterIndex) {
-    addToArguments(target, propertyKey, parameterIndex, constants_1.ARGUMENT_TYPES.REQUEST);
+    addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.REQUEST);
 }
-exports.request = 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.
@@ -43,9 +48,8 @@ exports.request = request;
  *
  */
 function response(target, propertyKey, parameterIndex) {
-    addToArguments(target, propertyKey, parameterIndex, constants_1.ARGUMENT_TYPES.RESPONSE);
+    addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.RESPONSE);
 }
-exports.response = 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>.
@@ -59,9 +63,8 @@ exports.response = response;
  *
  */
 function next(target, propertyKey, parameterIndex) {
-    addToArguments(target, propertyKey, parameterIndex, constants_1.ARGUMENT_TYPES.NEXT);
+    addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.NEXT);
 }
-exports.next = 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>
@@ -82,10 +85,9 @@ exports.next = next;
  */
 function query(parameter) {
     return (target, propertyKey, parameterIndex) => {
-        addToArguments(target, propertyKey, parameterIndex, constants_1.ARGUMENT_TYPES.QUERY, parameter);
+        addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.QUERY, parameter);
     };
 }
-exports.query = query;
 /**
  * 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>
@@ -106,10 +108,9 @@ exports.query = query;
  */
 function body(bodyParam) {
     return (target, propertyKey, parameterIndex) => {
-        addToArguments(target, propertyKey, parameterIndex, constants_1.ARGUMENT_TYPES.BODY, bodyParam);
+        addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.BODY, bodyParam);
     };
 }
-exports.body = body;
 /**
  * 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
@@ -126,7 +127,6 @@ exports.body = body;
  */
 function param(parameter) {
     return (target, propertyKey, parameterIndex) => {
-        addToArguments(target, propertyKey, parameterIndex, constants_1.ARGUMENT_TYPES.GET_PARAM, parameter);
+        addToArguments(target, propertyKey, parameterIndex, commons_2.ARGUMENT_TYPES.GET_PARAM, parameter);
     };
 }
-exports.param = param;

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[];

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) || [];
+}