@expressots/core 4.0.0-preview.1 → 4.0.0-preview.3

package/lib/esm/application/bootstrap.js

@@ -4,35 +4,75 @@ import { Logger } from "../provider/logger/logger.provider.js";
 import fs from "fs";
 import path from "path";
 /**
- * Synchronously load .env files BEFORE defineConfig() resolves.
+ * Synchronously load `.env` files into `process.env`.
  *
- * Call this at the top of your config file to ensure environment variables
- * are available when defineConfig() runs.
+ * Call this **before** `bootstrap()` or `defineConfig()` so that every
+ * environment variable is available when the rest of the application
+ * resolves configuration, binds services, or reads `Env.*` builders.
  *
- * @param options - Environment file configuration
+ * ### How it works
  *
- * @example
+ * 1. Reads `process.env.NODE_ENV` (defaults to `"development"`).
+ * 2. Loads files in priority order (last file wins on conflicts):
+ *    `.env` → `.env.local` → `.env.{env}.local` → `.env.{env}`
+ * 3. If `options.files` maps the current environment to a custom name
+ *    (e.g. `{ production: ".env.prod" }`), that name replaces `.env.{env}`.
+ * 4. Missing files are silently skipped.
+ * 5. Sets `process.env._EXPRESSOTS_ENV_LOADED = "true"` so subsequent
+ *    calls are no-ops (unless `force: true`).
+ *
+ * ### Important
+ *
+ * `NODE_ENV` must already be set in the **shell** (or inherited from
+ * the process) before `loadEnvSync()` runs. The function reads
+ * `process.env.NODE_ENV` to decide which file to load; it does **not**
+ * derive the environment from file contents.
+ *
+ * @param options - See {@link LoadEnvSyncOptions} for all fields.
+ *
+ * @example Zero-config (recommended for most apps)
  * ```typescript
- * // config.ts
- * import { defineConfig, Env, loadEnvSync } from "@expressots/core";
+ * // src/main.ts
+ * import { bootstrap, loadEnvSync } from "@expressots/core";
+ * import { App } from "./app";
+ *
+ * loadEnvSync();          // .env + .env.development (or .env.production, etc.)
+ * void bootstrap(App);
+ * ```
  *
- * // Load .env files first
+ * @example Custom file mapping
+ * ```typescript
  * loadEnvSync({
  *   files: {
- *     development: ".env.dev",
- *     production: ".env.prod",
+ *     development: ".env",
+ *     production:  ".env.prod",
+ *     staging:     ".env.staging",
  *   },
  * });
+ * // With NODE_ENV=production  -> .env + .env.prod
+ * // With NODE_ENV=development -> .env  (mapped to itself, so loaded once)
+ * ```
+ *
+ * @example With defineConfig()
+ * ```typescript
+ * // src/config.ts
+ * import { defineConfig, Env, loadEnvSync } from "@expressots/core";
+ *
+ * loadEnvSync({ files: { production: ".env.prod" } });
  *
- * // Now defineConfig() will read from loaded .env files
  * export const appConfig = defineConfig({
- *   server: {
- *     port: Env.port("PORT", { default: 3000 }),
- *   },
+ *   server: { port: Env.port("PORT", { default: 3000 }) },
  * });
  * ```
  *
- * @public API
+ * @example Force reload (hot-module replacement)
+ * ```typescript
+ * loadEnvSync({ force: true });
+ * ```
+ *
+ * @see {@link LoadEnvSyncOptions} for option details
+ * @see {@link BootstrapOptions.envFileConfig} for the bootstrap()-level alternative
+ * @public
  */
 export function loadEnvSync(options) {
     // Skip if already loaded (unless force reload)
@@ -95,26 +135,26 @@ const CI_PLATFORM_MAP = new Map([
 const PLATFORM_HINTS = new Map([
     [
         "GitHub Actions",
-        (missingVars) => `
-🔧 GitHub Actions Setup:
-   - Go to: Settings → Secrets and variables → Actions
-   - Add repository secrets for: ${missingVars}
+        (missingVars) => `
+🔧 GitHub Actions Setup:
+   - Go to: Settings → Secrets and variables → Actions
+   - Add repository secrets for: ${missingVars}
    - Use: \${{ secrets.VARIABLE_NAME }} in workflow files`,
     ],
     [
         "GitLab CI",
-        (missingVars) => `
-🔧 GitLab CI Setup:
-   - Go to: Settings → CI/CD → Variables
-   - Add CI/CD variables for: ${missingVars}
+        (missingVars) => `
+🔧 GitLab CI Setup:
+   - Go to: Settings → CI/CD → Variables
+   - Add CI/CD variables for: ${missingVars}
    - Use: $VARIABLE_NAME in .gitlab-ci.yml`,
     ],
     [
         "Jenkins",
-        (missingVars) => `
-🔧 Jenkins Setup:
-   - Configure: Manage Jenkins → Credentials
-   - Add credentials for: ${missingVars}
+        (missingVars) => `
+🔧 Jenkins Setup:
+   - Configure: Manage Jenkins → Credentials
+   - Add credentials for: ${missingVars}
    - Use: env.VARIABLE_NAME in pipeline`,
     ],
 ]);
@@ -179,14 +219,14 @@ function getPlatformHint(platform, missing) {
 class EnvFileNotFoundError extends Error {
     constructor(fileName, environment) {
         const template = getEnvTemplate(environment);
-        super(`
-❌ Missing required environment file: ${fileName}
-
-💡 Create ${fileName} with:
-${template}
-
-📖 Docs: https://expresso-ts.com/docs/env
-🔍 Check existing files: ls -la .env*
+        super(`
+❌ Missing required environment file: ${fileName}
+
+💡 Create ${fileName} with:
+${template}
+
+📖 Docs: https://expresso-ts.com/docs/env
+🔍 Check existing files: ls -la .env*
     `.trim());
         this.name = "EnvFileNotFoundError";
     }
@@ -199,20 +239,20 @@ class CIEnvValidationError extends Error {
     constructor(missing, environment) {
         const ciPlatform = detectCIPlatform();
         const platformHint = getPlatformHint(ciPlatform, missing);
-        super(`
-❌ CI/CD Environment Validation Failed
-
-Missing required environment variables in ${environment}:
-${missing.map((key) => `   • ${key}`).join("\n")}
-
-${platformHint}
-
-💡 Action Required:
-   1. Add missing variables to your CI/CD platform secrets
-   2. Ensure variables are available in ${environment} environment
-   3. Check variable names match exactly (case-sensitive)
-
-📖 Docs: https://expresso-ts.com/docs/ci-cd
+        super(`
+❌ CI/CD Environment Validation Failed
+
+Missing required environment variables in ${environment}:
+${missing.map((key) => `   • ${key}`).join("\n")}
+
+${platformHint}
+
+💡 Action Required:
+   1. Add missing variables to your CI/CD platform secrets
+   2. Ensure variables are available in ${environment} environment
+   3. Check variable names match exactly (case-sensitive)
+
+📖 Docs: https://expresso-ts.com/docs/ci-cd
     `.trim());
         this.name = "CIEnvValidationError";
     }
@@ -223,16 +263,16 @@ ${platformHint}
  */
 class EnvValidationError extends Error {
     constructor(missing, fileName) {
-        super(`
-❌ Environment validation failed
-
-Missing values in ${fileName}:
-${missing.map((key) => `   • ${key} (required but empty)`).join("\n")}
-
-💡 Add values to ${fileName}:
-${missing.map((key) => `   ${key}=your-value-here`).join("\n")}
-
-📖 Docs: https://expresso-ts.com/docs/env
+        super(`
+❌ Environment validation failed
+
+Missing values in ${fileName}:
+${missing.map((key) => `   • ${key} (required but empty)`).join("\n")}
+
+💡 Add values to ${fileName}:
+${missing.map((key) => `   ${key}=your-value-here`).join("\n")}
+
+📖 Docs: https://expresso-ts.com/docs/env
     `.trim());
         this.name = "EnvValidationError";
     }
@@ -244,8 +284,8 @@ ${missing.map((key) => `   ${key}=your-value-here`).join("\n")}
  * @private
  */
 function getEnvTemplate(environment) {
-    return `PORT=3000
-NODE_ENV=${environment}
+    return `PORT=3000
+NODE_ENV=${environment}
 # Add your environment variables here`;
 }
 /**
@@ -410,11 +450,11 @@ async function loadAndValidateEnvironment(currentEnvironment, envFileConfig) {
     // 🎯 STEP 2: Determine and load the file for the current environment
     // Only ONE file is loaded at runtime - the file for the current environment
     const envFileName = envFileConfig.files?.[currentEnvironment] ?? `.env.${currentEnvironment}`;
-    // Load optional files silently
+    // Load optional files silently (override: true so later files win)
     const optionalFiles = [".env", ".env.local", `${envFileName}.local`];
     for (const file of optionalFiles) {
         try {
-            config({ path: file });
+            config({ path: file, override: true });
             result.loaded.push(file);
         }
         catch {
@@ -457,8 +497,8 @@ async function loadAndValidateEnvironment(currentEnvironment, envFileConfig) {
         }
     }
     else {
-        // Load the file
-        config({ path: envFileName });
+        // Load the environment-specific file (highest priority, overrides all previous)
+        config({ path: envFileName, override: true });
         result.loaded.push(envFileName);
     }
     // Validate variables have values
@@ -522,151 +562,6 @@ async function readPackageJson() {
         return _packageCache;
     }
 }
-/**
- * Bootstrap the ExpressoTS application with zero configuration.
- *
- * @layer public
- * @audience application-developers
- * @concept bootstrap
- * @difficulty beginner
- *
- * @summary Quick Start
- * The simplest way to start your application:
- * ```typescript
- * await bootstrap(App);
- * ```
- *
- * This function orchestrates 8 critical startup phases:
- * 1. Environment detection (CI/CD vs local)
- * 2. Smart .env loading with opt-in behavior
- * 3. Port determination (priority chain)
- * 4. Package.json metadata extraction
- * 5. DI container initialization via AppFactory
- * 6. Environment injection into app instance
- * 7. API version detection from decorators
- * 8. Server startup with graceful shutdown
- *
- * @param AppClass - Application class extending AppExpress
- * @param options - Optional bootstrap configuration
- * @returns Promise resolving to IWebServerPublic instance
- *
- * @example
- * ```typescript
- * // Simplest usage - zero config (no .env file loading)
- * await bootstrap(App);
- *
- * // With overrides (still no .env file loading)
- * await bootstrap(App, {
- *   port: 4000,
- *   appName: "My API",
- *   appVersion: "2.0.0"
- * });
- *
- * // Opt-in to .env file loading and auto-creation
- * await bootstrap(App, {
- *   currentEnvironment: "development",
- *   envFileConfig: {
- *     files: {
- *       development: ".env.dev",
- *       production: ".env.prod"
- *     },
- *     required: ["DATABASE_URL", "API_KEY"],
- *     autoCreateTemplate: true,  // Explicitly enable file creation
- *     validateValues: true
- *   }
- * });
- *
- * // Auto-assign port (useful for testing)
- * await bootstrap(App, { port: 0 });
- * ```
- *
- * @layer internal
- * @audience framework-developers
- *
- * **Internal Architecture**
- *
- * Bootstrap orchestrates 8 critical steps:
- * 1. Environment detection (CI/CD vs local)
- * 2. Smart .env loading with opt-in behavior
- * 3. Port determination (priority chain)
- * 4. Package.json metadata extraction
- * 5. DI container initialization via AppFactory
- * 6. Environment injection into app instance
- * 7. API version detection from decorators
- * 8. Server startup with graceful shutdown
- *
- * **Design Decisions**
- * - Opt-in .env loading prevents breaking changes for containerized deployments
- * - Port 0 support enables parallel testing without conflicts
- * - Early validation fails fast with actionable error messages
- * - CI/CD auto-detection provides zero-config for containerized environments
- *
- * **Performance Characteristics**
- * - Startup time: ~8-25ms typical (optimized)
- * - Environment loading: ~2-5ms (file I/O)
- * - Package.json read: ~1-2ms first call, cached thereafter
- * - CI detection: cached after first call
- * - App instantiation: ~5-10ms (DI container setup)
- * - Logger instances: lazy initialization (only created when needed)
- *
- * @see {@link loadAndValidateEnvironment} for environment loading logic
- * @see {@link AppFactory.create} for DI container initialization
- * @see {@link determinePort} for port resolution logic
- *
- * @layer advanced
- * @audience power-users
- *
- * **Advanced Patterns**
- *
- * Multi-environment setup with validation:
- * ```typescript
- * await bootstrap(App, {
- *   currentEnvironment: process.env.NODE_ENV || "development",
- *   envFileConfig: {
- *     files: {
- *       development: ".env.dev",
- *       staging: ".env.staging",
- *       production: ".env.prod"
- *     },
- *     required: ["DATABASE_URL", "JWT_SECRET"],
- *     autoCreateTemplate: true,
- *     validateValues: process.env.NODE_ENV === "production"
- *   }
- * });
- * ```
- *
- * Containerized deployment (Docker/K8s):
- * ```typescript
- * await bootstrap(App, {
- *   envFileConfig: {
- *     skipFileLoading: true,  // Use process.env only
- *     required: ["DATABASE_URL", "REDIS_URL"]
- *   }
- * });
- * ```
- *
- * Testing with dynamic ports:
- * ```typescript
- * const server = await bootstrap(App, { port: 0 });
- * const actualPort = server.port;  // Use in tests
- * ```
- *
- * @troubleshooting
- * **Common Issues**
- * - ❌ PORT not detected → Use options.port or envFileConfig
- * - ❌ CI validation fails → Check platform secrets configuration
- * - ❌ Template not created → Set autoCreateTemplate: true explicitly
- * - ❌ Port already in use → Use port: 0 for testing
- *
- * @performance
- * - Async initialization: ~5-15ms (typical)
- * - Package.json read: ~2ms first call, cached thereafter
- * - CI detection: cached after first call
- * - Port binding: varies by OS
- * - Total startup: ~8-25ms (optimized with caching)
- *
- * @public API
- */
 /**
  * Type guard to check if argument is BootstrapConfig.
  * Detects config objects by checking for the required structure.
@@ -707,9 +602,7 @@ function transformConfigToOptions(config) {
         envFileConfig: config.bootstrap?.envFileConfig,
     };
 }
-/**
- * Implementation.
- */
+/** @internal Implementation overload. */
 export async function bootstrap(AppClass, optionsOrConfig) {
     let logger;
     // Note: Path resolution is auto-initialized as a side effect when
@@ -769,6 +662,17 @@ export async function bootstrap(AppClass, optionsOrConfig) {
         // STEP 5: Create app instance
         // App's globalConfiguration() will run in constructor
         // initEnvironment() can skip if .env already loaded
+        //
+        // Activate log buffering BEFORE constructing the app so any logs the
+        // application emits during construction (e.g. inside `globalConfiguration()`
+        // or `configureServices()`) are captured and replayed in the right order
+        // after the startup banner. AppClass extends AppExpress for the standard
+        // adapter, so the static method is inherited; we duck-type to avoid a
+        // hard dependency on adapter-express from core.
+        const appClassWithBuffering = AppClass;
+        if (typeof appClassWithBuffering.startLogBuffering === "function") {
+            appClassWithBuffering.startLogBuffering();
+        }
         const app = await AppFactory.create(AppClass);
         // Set environment on app instance (for this.environment access)
         app.environment =

package/lib/esm/config/define-config.js

@@ -120,7 +120,7 @@ class ConfigInstance {
         this._options = {
             validateOnAccess: true,
             throwOnError: process.env.NODE_ENV === "production",
-            logLevel: "info",
+            logLevel: "warn",
             ...options,
         };
         // Lazy resolution: Don't resolve immediately

package/lib/esm/config/env-field-builders.js

@@ -377,6 +377,49 @@ function array(envVar, options = {}) {
  *
  * @public API
  */
+/**
+ * Returns true when the current Node environment (`NODE_ENV`) matches the
+ * supplied name. Pass an array to match any of several names. The comparison
+ * is case-insensitive and falls back to `"development"` when `NODE_ENV` is
+ * unset, mirroring the convention used elsewhere in the framework.
+ *
+ * ```ts
+ * const config = defineConfig({
+ *   server: { port: when(Env.is("production"), 443, 3000) },
+ * });
+ * ```
+ *
+ * @public API
+ */
+function isEnvironment(name) {
+    const current = (process.env.NODE_ENV ?? "development").toLowerCase();
+    const targets = Array.isArray(name) ? name : [name];
+    return targets.some((target) => target.toLowerCase() === current);
+}
+/**
+ * Conditional helper for environment-specific config values.
+ *
+ * `when(condition, value, fallback)` returns `value` when `condition` is
+ * truthy, otherwise `fallback`. The condition can be either a boolean
+ * (typically the result of `Env.is(...)`) or a callable that's evaluated
+ * lazily. The latter form lets you defer side-effectful checks until the
+ * config is actually resolved.
+ *
+ * ```ts
+ * const config = defineConfig({
+ *   logging: {
+ *     level: when(Env.is("production"), "info", "debug"),
+ *     pretty: when(() => process.env.NO_COLOR !== "1", true, false),
+ *   },
+ * });
+ * ```
+ *
+ * @public API
+ */
+function envWhen(condition, value, fallback) {
+    const ok = typeof condition === "function" ? condition() : condition;
+    return ok ? value : fallback;
+}
 export const Env = {
     string,
     number,
@@ -387,6 +430,11 @@ export const Env = {
     secret,
     json,
     array,
+    is: isEnvironment,
+    when: envWhen,
 };
+// Re-export the conditional helpers as top-level free functions so users can
+// import them without going through the `Env` namespace if they prefer.
+export { isEnvironment as envIs, envWhen };
 // Re-export individual builders for tree-shaking
 export { string as envString, number as envNumber, boolean as envBoolean, enumField as envEnum, url as envUrl, port as envPort, secret as envSecret, json as envJson, array as envArray, };

package/lib/esm/config/index.js

@@ -60,7 +60,12 @@
 // ============================================================================
 export { defineConfig, Env } from "./define-config.js";
 // Individual field builders (for tree-shaking)
-export { envString, envNumber, envBoolean, envEnum, envUrl, envPort, envSecret, envJson, envArray, } from "./env-field-builders.js";
+export { envString, envNumber, envBoolean, envEnum, envUrl, envPort, envSecret, envJson, envArray, 
+// Environment-aware value selection helpers.
+// The canonical user-facing API for `when` is `Env.when(...)` to avoid
+// colliding with the middleware module's `when()` helper. We still expose
+// the underlying functions under disambiguated names for advanced use.
+envIs, envWhen, } from "./env-field-builders.js";
 // ============================================================================
 // Secret Value
 // ============================================================================

package/lib/esm/framework-version.js

@@ -0,0 +1,7 @@
+/**
+ * Framework version string surfaced in startup banners and diagnostics.
+ *
+ * This file is auto-synced from the root `package.json` by
+ * `scripts/sync-version.js` before each build. Do not edit by hand.
+ */
+export const FRAMEWORK_VERSION = "4.0.0-preview.3";

package/lib/esm/lazy-loading/index.js

@@ -38,6 +38,8 @@
 // Lazy Module
 // ============================================================================
 export { LazyModule, CreateLazyModule, createLazyModule, isLazyModule, getModuleName, LAZY_MODULE_METADATA_KEY, } from "./lazy-module.js";
+// Free-function wrappers for the LazyModule chain methods.
+export { withPreloadHint, withLazyConfig } from "./lazy-module-helpers.js";
 // ============================================================================
 // Lazy Module Loader
 // ============================================================================

package/lib/esm/lazy-loading/lazy-module-helpers.js

@@ -0,0 +1,45 @@
+/**
+ * Standalone (free-function) wrappers around `LazyModule` chain methods.
+ *
+ * The fluent API (`module.withPreloadHint(...).withLazyConfig(...)`) remains
+ * the recommended style. These helpers exist so users can compose lazy
+ * configurations with point-free style or apply the same hint to a list of
+ * modules:
+ *
+ * ```ts
+ * import { CreateLazyModule, withPreloadHint, withLazyConfig } from "@expressots/core";
+ *
+ * const Admin = withPreloadHint(
+ *   CreateLazyModule([AdminController]),
+ *   "low",
+ * );
+ *
+ * const Analytics = withLazyConfig(
+ *   CreateLazyModule([AnalyticsController]),
+ *   { preloadHint: "medium", prefetchAfterIdle: 5000 },
+ * );
+ * ```
+ *
+ * @public API
+ */
+/**
+ * Set a preload hint on the supplied lazy module and return it.
+ *
+ * Equivalent to `module.withPreloadHint(hint)`. Returned reference is the same
+ * instance — no copy is made.
+ *
+ * @public API
+ */
+export function withPreloadHint(module, hint) {
+    return module.withPreloadHint(hint);
+}
+/**
+ * Merge the supplied partial config into the lazy module and return it.
+ *
+ * Equivalent to `module.withLazyConfig(config)`.
+ *
+ * @public API
+ */
+export function withLazyConfig(module, config) {
+    return module.withLazyConfig(config);
+}

package/lib/esm/middleware/index.js

@@ -4,8 +4,6 @@ export { Middleware, ExpressoMiddleware, } from "./middleware-service.js";
 export { middlewareResolver, isMiddlewareAvailable, isPackageAvailable, resolvePackage, getAvailableMiddleware, getRegisteredMiddleware, clearMiddlewareCache, getPackageName, MIDDLEWARE_REGISTRY, } from "./middleware-resolver.js";
 // Middleware profiler
 export { MiddlewareProfiler, } from "./middleware-profiler.js";
-// Middleware presets
-export { MIDDLEWARE_PRESETS, getPreset, getPresetNames, getPresetsByTag, createPreset, mergePresets, } from "./middleware-presets.js";
 // Content Negotiation exports
 export { ContentNegotiationService, FormatterRegistry, AcceptHeaderParser, JsonFormatter, XmlFormatter, CsvFormatter, YamlFormatter, PlainTextFormatter, } from "./content-negotiation/index.js";
 // ═══════════════════════════════════════════════════════════════════════════
@@ -13,6 +11,9 @@ export { ContentNegotiationService, FormatterRegistry, AcceptHeaderParser, JsonF
 // ═══════════════════════════════════════════════════════════════════════════
 // V4 Middleware utilities
 export { use, compose, when, parallel, timeout } from "./middleware-utils.js";
+// V4 Standalone preset helpers (free-function wrappers around
+// Middleware.definePreset / Middleware.applyPreset)
+export { definePreset, applyPreset, getStandalonePresetNames, clearStandalonePresets, } from "./presets-standalone.js";
 // V4 Middleware registry
 export { MiddlewareRegistry, getMiddlewareRegistry, resetMiddlewareRegistry, } from "./middleware-registry.js";
 // V4 Upload registry (for @FileUpload decorator integration)