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

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

package/decorators/module.d.ts

@@ -1,5 +1,6 @@
-import { type Express, Router } from 'express';
-import { type ExpressiveTeaModuleProps } from '@expressive-tea/commons/interfaces';
+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
@@ -13,23 +14,21 @@ import { type ExpressiveTeaModuleProps } from '@expressive-tea/commons/interface
  * 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
- * @param {ExpressiveTeaModuleProps} options
+ * @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: [],
- *   providers: [],
- *   mountpoint: '/'
+ *   controllers: [UserController],
+ *   providers: [UserService],
+ *   mountpoint: '/api'
  * })
- * class Example {}
+ * class ApiModule {}
+ *
+ * @since 1.0.0
  */
-export declare function Module(options: ExpressiveTeaModuleProps): <T extends new (...args: any[]) => any>(Module: T) => {
-    new (...args: any[]): {
-        [x: string]: any;
-        readonly settings: ExpressiveTeaModuleProps;
-        readonly router: Router;
-        readonly controllers: any[];
-        __register(server: Express): void;
-    };
-} & T;
+export declare function Module<TBase extends Constructor = Constructor>(options: ExpressiveTeaModuleProps): (target: TBase) => ModulizedClass<TBase>;

package/decorators/module.js

@@ -1,9 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Module = void 0;
-const express_1 = require("express");
-const lodash_1 = require("lodash");
-const DependencyInjection_1 = require("../services/DependencyInjection");
+exports.Module = Module;
+const module_1 = require("../mixins/module");
 /**
  * @typedef {Object} ExpressiveTeaModuleProps
  * @property {Object[]} controllers Controllers Assigned to Module
@@ -17,33 +15,25 @@ const DependencyInjection_1 = require("../services/DependencyInjection");
  * 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
- * @param {ExpressiveTeaModuleProps} options
+ * @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: [],
- *   providers: [],
- *   mountpoint: '/'
+ *   controllers: [UserController],
+ *   providers: [UserService],
+ *   mountpoint: '/api'
  * })
- * class Example {}
+ * class ApiModule {}
+ *
+ * @since 1.0.0
  */
 function Module(options) {
     return (Module) => {
-        return class ExpressiveTeaModule extends Module {
-            constructor(...args) {
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-                super(...args);
-                this.router = (0, express_1.Router)();
-                this.settings = options;
-                (0, lodash_1.each)(this.settings.providers, (P) => { DependencyInjection_1.default.setProvider(P); });
-                this.controllers = (0, lodash_1.map)(this.settings.controllers, C => new C());
-            }
-            __register(server) {
-                (0, lodash_1.each)(this.controllers, c => c.__mount(this.router));
-                server.use(this.settings.mountpoint, this.router);
-            }
-        };
+        return (0, module_1.Modulize)(Module, options);
     };
 }
-exports.Module = Module;