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

package/lib/README.md

@@ -1,66 +1,66 @@
-<div align="center">
-  <a href="https://expresso-ts.com">
-    <img src="https://github.com/expressots/expressots/blob/main/media/expressots.png" alt="ExpressoTS" width="120">
-  </a>
-
-  <h1>@expressots/core</h1>
-
-  <p>A TypeScript framework for building server-side applications — fast to code, lean to run, simple to deploy.</p>
-
-  <p>
-    <a href="https://www.npmjs.com/package/@expressots/core"><img src="https://img.shields.io/npm/v/@expressots/core?style=flat&color=0d0d0d" alt="npm"></a>
-    <a href="https://github.com/expressots/expressots/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/expressots/expressots?style=flat&color=0d0d0d" alt="License"></a>
-    <a href="https://discord.com/invite/PyPJfGK"><img src="https://img.shields.io/badge/Discord-join-0d0d0d?logo=discord&logoColor=white" alt="Discord"></a>
-  </p>
-
-  <p>
-    <a href="https://doc.expresso-ts.com">Documentation</a> ·
-    <a href="https://doc.expresso-ts.com/docs/core/first-steps">Getting Started</a> ·
-    <a href="https://discord.com/invite/PyPJfGK">Community</a>
-  </p>
-</div>
-
----
-
-## Install
-
-```bash
-npm i @expressots/core
-```
-
-## What This Package Does
-
-ExpressoTS Core is the foundation of the ExpressoTS framework. It provides dependency injection, routing, middleware orchestration, lifecycle hooks, interceptors, guards, error handling, and the application bootstrap — everything needed to structure and run a server-side TypeScript application with minimal boilerplate.
-
-## Quick Look
-
-```typescript
-// app.provider.ts
-import { AppFactory } from "@expressots/core";
-import { App } from "./app";
-
-async function bootstrap() {
-  const app = await AppFactory.create(App);
-  await app.listen(3000, "development");
-}
-
-bootstrap();
-```
-
-## Documentation
-
-For guides, API reference, architecture patterns, and examples visit **[doc.expresso-ts.com](https://doc.expresso-ts.com)**.
-
-## Contributing
-
-See the [Contributing Guide](https://github.com/expressots/expressots/blob/main/CONTRIBUTING.md) for how to get involved.
-
-## Support
-
-- [GitHub Sponsors](https://github.com/sponsors/expressots)
-- [Discord](https://discord.com/invite/PyPJfGK)
-- [Report an Issue](https://github.com/expressots/expressots/issues)
-
-## License
-
-MIT — see [LICENSE](./LICENSE.md).
+<div align="center">
+  <a href="https://expresso-ts.com">
+    <img src="https://github.com/expressots/expressots/blob/main/media/expressots.png" alt="ExpressoTS" width="120">
+  </a>
+
+  <h1>@expressots/core</h1>
+
+  <p>A TypeScript framework for building server-side applications — fast to code, lean to run, simple to deploy.</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@expressots/core"><img src="https://img.shields.io/npm/v/@expressots/core?style=flat&color=0d0d0d" alt="npm"></a>
+    <a href="https://github.com/expressots/expressots/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/expressots/expressots?style=flat&color=0d0d0d" alt="License"></a>
+    <a href="https://discord.com/invite/PyPJfGK"><img src="https://img.shields.io/badge/Discord-join-0d0d0d?logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+  <p>
+    <a href="https://doc.expresso-ts.com">Documentation</a> ·
+    <a href="https://doc.expresso-ts.com/docs/core/first-steps">Getting Started</a> ·
+    <a href="https://discord.com/invite/PyPJfGK">Community</a>
+  </p>
+</div>
+
+---
+
+## Install
+
+```bash
+npm i @expressots/core
+```
+
+## What This Package Does
+
+ExpressoTS Core is the foundation of the ExpressoTS framework. It provides dependency injection, routing, middleware orchestration, lifecycle hooks, interceptors, guards, error handling, and the application bootstrap — everything needed to structure and run a server-side TypeScript application with minimal boilerplate.
+
+## Quick Look
+
+```typescript
+// app.provider.ts
+import { AppFactory } from "@expressots/core";
+import { App } from "./app";
+
+async function bootstrap() {
+  const app = await AppFactory.create(App);
+  await app.listen(3000, "development");
+}
+
+bootstrap();
+```
+
+## Documentation
+
+For guides, API reference, architecture patterns, and examples visit **[doc.expresso-ts.com](https://doc.expresso-ts.com)**.
+
+## Contributing
+
+See the [Contributing Guide](https://github.com/expressots/expressots/blob/main/CONTRIBUTING.md) for how to get involved.
+
+## Support
+
+- [GitHub Sponsors](https://github.com/sponsors/expressots)
+- [Discord](https://discord.com/invite/PyPJfGK)
+- [Report an Issue](https://github.com/expressots/expressots/issues)
+
+## License
+
+MIT — see [LICENSE](./LICENSE.md).

package/lib/cjs/application/application-factory.js

@@ -122,6 +122,12 @@ class AppFactory {
      *
      * @throws {Error} If webServerType is not a valid constructor
      *
+     * @deprecated Use `bootstrap()` from `@expressots/core` instead. `bootstrap()`
+     * additionally handles environment file loading, port configuration,
+     * graceful shutdown, the startup banner, and configuration validation.
+     * `AppFactory.create()` will keep working for advanced use cases but is
+     * scheduled for removal in a future major release.
+     *
      * @public API
      */
     static async create(webServerType) {

package/lib/cjs/application/bootstrap.js

@@ -11,35 +11,75 @@ const logger_provider_js_1 = require("../provider/logger/logger.provider.js");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("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
  */
 function loadEnvSync(options) {
     // Skip if already loaded (unless force reload)
@@ -102,26 +142,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`,
     ],
 ]);
@@ -186,14 +226,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";
     }
@@ -206,20 +246,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";
     }
@@ -230,16 +270,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";
     }
@@ -251,8 +291,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`;
 }
 /**
@@ -417,11 +457,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 {
-            (0, shared_1.config)({ path: file });
+            (0, shared_1.config)({ path: file, override: true });
             result.loaded.push(file);
         }
         catch {
@@ -464,8 +504,8 @@ async function loadAndValidateEnvironment(currentEnvironment, envFileConfig) {
         }
     }
     else {
-        // Load the file
-        (0, shared_1.config)({ path: envFileName });
+        // Load the environment-specific file (highest priority, overrides all previous)
+        (0, shared_1.config)({ path: envFileName, override: true });
         result.loaded.push(envFileName);
     }
     // Validate variables have values
@@ -529,151 +569,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.
@@ -714,9 +609,7 @@ function transformConfigToOptions(config) {
         envFileConfig: config.bootstrap?.envFileConfig,
     };
 }
-/**
- * Implementation.
- */
+/** @internal Implementation overload. */
 async function bootstrap(AppClass, optionsOrConfig) {
     let logger;
     // Note: Path resolution is auto-initialized as a side effect when
@@ -776,6 +669,17 @@ 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 application_factory_js_1.AppFactory.create(AppClass);
         // Set environment on app instance (for this.environment access)
         app.environment =

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

@@ -122,7 +122,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/cjs/config/env-field-builders.js

@@ -28,6 +28,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Env = void 0;
+exports.envIs = isEnvironment;
+exports.envWhen = envWhen;
 exports.envString = string;
 exports.envNumber = number;
 exports.envBoolean = boolean;
@@ -389,6 +391,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;
+}
 exports.Env = {
     string,
     number,
@@ -399,4 +444,6 @@ exports.Env = {
     secret,
     json,
     array,
+    is: isEnvironment,
+    when: envWhen,
 };

package/lib/cjs/config/index.js

@@ -57,7 +57,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSecretValue = exports.createSecretValue = exports.envArray = exports.envJson = exports.envSecret = exports.envPort = exports.envUrl = exports.envEnum = exports.envBoolean = exports.envNumber = exports.envString = exports.Env = exports.defineConfig = void 0;
+exports.isSecretValue = exports.createSecretValue = exports.envWhen = exports.envIs = exports.envArray = exports.envJson = exports.envSecret = exports.envPort = exports.envUrl = exports.envEnum = exports.envBoolean = exports.envNumber = exports.envString = exports.Env = exports.defineConfig = void 0;
 // ============================================================================
 // Core Exports
 // ============================================================================
@@ -75,6 +75,12 @@ Object.defineProperty(exports, "envPort", { enumerable: true, get: function () {
 Object.defineProperty(exports, "envSecret", { enumerable: true, get: function () { return env_field_builders_js_1.envSecret; } });
 Object.defineProperty(exports, "envJson", { enumerable: true, get: function () { return env_field_builders_js_1.envJson; } });
 Object.defineProperty(exports, "envArray", { enumerable: true, get: function () { return env_field_builders_js_1.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.
+Object.defineProperty(exports, "envIs", { enumerable: true, get: function () { return env_field_builders_js_1.envIs; } });
+Object.defineProperty(exports, "envWhen", { enumerable: true, get: function () { return env_field_builders_js_1.envWhen; } });
 // ============================================================================
 // Secret Value
 // ============================================================================