@bymax-one/nest-core 1.5.1 → 1.5.2

package/CHANGELOG.md

@@ -11,6 +11,48 @@ heading here.
 
 ## [Unreleased]
 
+## [1.5.2] - 2026-08-15
+
+The production guard read `NODE_ENV` and nothing else, and treated an unset
+variable as production. An application that validates its own `APP_ENV` and
+never sets `NODE_ENV` was therefore classified as production on evidence it
+never gave — the OpenAPI document was refused in a development deployment, with
+no way to answer back. Two independent consumers reported the same split.
+
+**Apply to a derived backend:** nothing to change. A deployment that sets
+`NODE_ENV` behaves exactly as before. If yours validates its own variable
+instead, pass it as `environment` and the document is served where that variable
+says `development` or `test`.
+
+### Added
+
+- **`environment`, for applications that validate their own environment
+  variable.** The production guard read `NODE_ENV` and nothing else, and treated
+  an unset variable as production. An application that parses an `APP_ENV`
+  through its config schema and never sets `NODE_ENV` was therefore classified
+  as production on evidence it never gave — the OpenAPI document was refused in
+  a development deployment, with no way to answer back. Two independent
+  consumers reported the same split between the library's view of the
+  environment and their own validated one.
+
+  A top-level `environment` option is now consulted **where the process declares
+  nothing**: `NODE_ENV` unset, or set to whitespace. `NODE_ENV` wins whenever it
+  says anything at all, so no configured value can make a runtime that named
+  itself production serve the document — asserted in both guards rather than in
+  one. The declaration enters the same fail-closed classification, so an
+  unrecognized name is production like any other: this is a second source for
+  the value, never a second set of rules.
+
+  The narrowing is stated rather than buried. Both guards previously classified
+  from the process alone; now, in the single case where the process says
+  nothing, the snapshot a consumer bound decides the answer, because there is
+  nothing else to decide it with. Replacing a guess with a declaration is not an
+  override, but it is a real change to what the second guard depends on.
+
+  **Apply to a derived backend:** nothing to change. The option is optional and
+  every existing classification is unchanged — a deployment that sets `NODE_ENV`
+  behaves exactly as before.
+
 ## [1.5.1] - 2026-08-15
 
 Documentation only; no source change. The 1.5.0 warning's known-limit note told
@@ -736,4 +778,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.4.0]: https://github.com/bymaxone/nest-core/compare/v1.3.2...v1.4.0
 [1.5.0]: https://github.com/bymaxone/nest-core/compare/v1.4.0...v1.5.0
 [1.5.1]: https://github.com/bymaxone/nest-core/compare/v1.5.0...v1.5.1
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.1...HEAD
+[1.5.2]: https://github.com/bymaxone/nest-core/compare/v1.5.1...v1.5.2
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.2...HEAD

package/README.md

@@ -202,6 +202,20 @@ BymaxCoreModule.forRoot({ isGlobal: false })
 Every block is optional; an omitted block, or an omitted field within it,
 falls back to the documented default. Pass only what you want to change.
 
+### `environment`
+
+The one top-level option rather than a block, because it describes the
+deployment rather than a feature.
+
+| Option        | Type     | Default | Description                                                                           |
+| ------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
+| `environment` | `string` | unset   | The environment this deployment runs in, read only where `NODE_ENV` declares nothing. |
+
+Set it when your application validates its own environment variable and does not
+also set `NODE_ENV`. `NODE_ENV` wins whenever it says anything, so this can never
+serve the OpenAPI document in a runtime that named itself production. Full rules
+and the classification table: [Production is a closed door](#production-is-a-closed-door).
+
 ### `envelope`
 
 | Option            | Type      | Default | Description                                                                                    |
@@ -959,16 +973,61 @@ can emit it once and never branch:
 ### Production is a closed door
 
 `NODE_ENV` decides, and the decision is fail-closed: only `development` and
-`test` are non-production. Any other value — including an unset variable —
-is production, and in production the document is never built and never mounted,
-whatever the configuration says. The guard runs twice, independently: the option
-resolver forces the feature off, and the bootstrap helper refuses again without
-trusting that resolution. There is no override.
+`test` are non-production. Any other value is production, and in production the
+document is never built and never mounted, whatever the configuration says. The
+guard runs twice, independently: the option resolver forces the feature off, and
+the bootstrap helper classifies the runtime again without trusting that
+resolution.
+
+**`NODE_ENV` cannot be overridden.** With it set to anything, no option serves
+the document in a runtime it named production.
 
 Enabling it in production is not an error, it is a no-op with a warning naming
 the option that was ignored, so a single configuration can be shared across
 environments.
 
+#### When your application validates its own environment variable
+
+Plenty of applications parse an `APP_ENV` through a config schema and never set
+`NODE_ENV` at all. Those deployments used to be classified as production —
+absence was the only evidence available — so the document was refused in an
+environment that never asked for the refusal, with no way to answer back.
+
+Declare the environment and it is used **where the process declares nothing**:
+
+```typescript
+BymaxCoreModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    // Your validated value, not a second copy of NODE_ENV.
+    environment: config.get('APP_ENV'),
+    openapi: { enabled: true }
+  })
+})
+```
+
+| `NODE_ENV`      | `environment` | Classified as  |
+| --------------- | ------------- | -------------- |
+| `production`    | `development` | **production** |
+| `development`   | (anything)    | development    |
+| unset, or blank | `development` | development    |
+| unset, or blank | `staging`     | **production** |
+| unset, or blank | unset         | **production** |
+
+Two properties are worth reading off that table. A declaration never overrules a
+process that named its own environment — the first row is the one that matters,
+and it is asserted in both guards rather than in one. And the declaration enters
+the same fail-closed classification, so an unrecognized name is production like
+any other; this is a second **source** for the value, never a second set of
+rules.
+
+The narrowing is deliberate and worth naming rather than burying: in the one
+case where the process declares nothing, the configuration a consumer bound does
+decide the answer, because there is nothing else to decide it with. Replacing a
+guess with a declaration is not the same as allowing an override — but it is a
+real change to what the second guard depends on, and you should know it before
+relying on either.
+
 ### Testing the enabled path under Jest
 
 `applyBymaxOpenApi` loads `@nestjs/swagger` through a dynamic `import()` — that
@@ -1359,9 +1418,11 @@ guard you would apply to any internal endpoint, or keep it off the public listen
 A published document is a map of every route, parameter and error shape an application has —
 useful to a developer, and just as useful to anyone probing the service. So unlike the metrics
 endpoint, it is not left to a guard: it is refused outright whenever the runtime is not
-positively `development` or `test`, in two independent layers, with no option to override.
-An unset `NODE_ENV` counts as production, because the deployment nobody configured is the one
-most likely to be exposed.
+positively `development` or `test`, in two independent layers. **`NODE_ENV` cannot be
+overridden** — with it set to anything, no option serves the document in a runtime it named
+production. A runtime that declares nothing is classified from the application's own
+[`environment`](#environment) when it supplied one, and counts as production otherwise, because
+the deployment nobody configured is the one most likely to be exposed.
 
 ---
 

package/dist/index.cjs

@@ -30,6 +30,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
@@ -92,9 +99,9 @@ function cloneServers(raw) {
     (server) => server.description === void 0 ? { url: server.url } : { url: server.url, description: server.description }
   );
 }
-function resolveOpenApi(raw) {
+function resolveOpenApi(raw, declaredEnvironment) {
   const requested = raw?.enabled ?? false;
-  const production = isProductionRuntime();
+  const production = isProductionRuntime(runtimeEnvironmentName(declaredEnvironment));
   return {
     enabled: requested && !production,
     suppressedInProduction: requested && production,
@@ -131,8 +138,12 @@ function normalizeCoreOptions(raw) {
     timing: resolveTiming(raw?.timing),
     health: resolveHealth(raw?.health),
     metrics: resolveMetrics(raw?.metrics),
-    openapi: resolveOpenApi(raw?.openapi),
-    telemetry: resolveTelemetry(raw?.telemetry)
+    openapi: resolveOpenApi(raw?.openapi, raw?.environment),
+    telemetry: resolveTelemetry(raw?.telemetry),
+    // Spread rather than assigned so an application that declared nothing has
+    // no `environment` member at all, matching every other optional member on
+    // this snapshot under `exactOptionalPropertyTypes`.
+    ...raw?.environment === void 0 ? {} : { environment: raw.environment }
   });
 }
 normalizeCoreOptions();

package/dist/index.d.cts

@@ -273,6 +273,28 @@ interface BymaxCoreModuleOptions {
     openapi?: OpenApiOptions;
     /** Trace correlation. Default: disabled. */
     telemetry?: TelemetryOptions;
+    /**
+     * The environment this deployment is running in, for the features that must
+     * never exist outside development — today, the OpenAPI document and its UI.
+     *
+     * **`NODE_ENV` always wins.** This is consulted only when the process
+     * declares nothing: `NODE_ENV` unset, or set to whitespace. It cannot make a
+     * runtime that identified itself as production serve the document, and no
+     * value here overrides one there.
+     *
+     * Set it when your application validates its own environment variable — an
+     * `APP_ENV` your config schema parses — and does not also set `NODE_ENV`.
+     * Without it, that deployment is classified as production because absence was
+     * the only evidence available, and the document is refused in an environment
+     * that never asked for the refusal.
+     *
+     * Recognized non-production values are `development` and `test`, compared
+     * case-insensitively and ignoring surrounding whitespace. Anything else,
+     * including an unrecognized name, is production.
+     *
+     * @example 'development'
+     */
+    environment?: string;
 }
 /** Fully-resolved envelope options. */
 interface ResolvedEnvelopeOptions {
@@ -334,9 +356,9 @@ interface ResolvedOpenApiOptions {
 }
 /**
  * The effective, defaults-applied configuration exposed under
- * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present;
- * the only optional field is `timing.slowRequestThresholdMs`, which has no
- * default and is absent unless the consumer sets it.
+ * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present.
+ * Two fields have no default and are absent unless the consumer supplies them:
+ * `timing.slowRequestThresholdMs`, and `environment`.
  */
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
@@ -345,6 +367,12 @@ interface ResolvedCoreOptions {
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
     telemetry: ResolvedTelemetryOptions;
+    /**
+     * The environment the application declared, carried through so the bootstrap
+     * helper classifies the runtime from the same two inputs the resolver did.
+     * Absent when the application declared none.
+     */
+    environment?: string;
 }
 
 /** Non-option extras accepted by `forRoot` / `forRootAsync`. */

package/dist/index.d.ts

@@ -273,6 +273,28 @@ interface BymaxCoreModuleOptions {
     openapi?: OpenApiOptions;
     /** Trace correlation. Default: disabled. */
     telemetry?: TelemetryOptions;
+    /**
+     * The environment this deployment is running in, for the features that must
+     * never exist outside development — today, the OpenAPI document and its UI.
+     *
+     * **`NODE_ENV` always wins.** This is consulted only when the process
+     * declares nothing: `NODE_ENV` unset, or set to whitespace. It cannot make a
+     * runtime that identified itself as production serve the document, and no
+     * value here overrides one there.
+     *
+     * Set it when your application validates its own environment variable — an
+     * `APP_ENV` your config schema parses — and does not also set `NODE_ENV`.
+     * Without it, that deployment is classified as production because absence was
+     * the only evidence available, and the document is refused in an environment
+     * that never asked for the refusal.
+     *
+     * Recognized non-production values are `development` and `test`, compared
+     * case-insensitively and ignoring surrounding whitespace. Anything else,
+     * including an unrecognized name, is production.
+     *
+     * @example 'development'
+     */
+    environment?: string;
 }
 /** Fully-resolved envelope options. */
 interface ResolvedEnvelopeOptions {
@@ -334,9 +356,9 @@ interface ResolvedOpenApiOptions {
 }
 /**
  * The effective, defaults-applied configuration exposed under
- * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present;
- * the only optional field is `timing.slowRequestThresholdMs`, which has no
- * default and is absent unless the consumer sets it.
+ * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present.
+ * Two fields have no default and are absent unless the consumer supplies them:
+ * `timing.slowRequestThresholdMs`, and `environment`.
  */
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
@@ -345,6 +367,12 @@ interface ResolvedCoreOptions {
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
     telemetry: ResolvedTelemetryOptions;
+    /**
+     * The environment the application declared, carried through so the bootstrap
+     * helper classifies the runtime from the same two inputs the resolver did.
+     * Absent when the application declared none.
+     */
+    environment?: string;
 }
 
 /** Non-option extras accepted by `forRoot` / `forRootAsync`. */

package/dist/index.mjs

@@ -28,6 +28,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
@@ -90,9 +97,9 @@ function cloneServers(raw) {
     (server) => server.description === void 0 ? { url: server.url } : { url: server.url, description: server.description }
   );
 }
-function resolveOpenApi(raw) {
+function resolveOpenApi(raw, declaredEnvironment) {
   const requested = raw?.enabled ?? false;
-  const production = isProductionRuntime();
+  const production = isProductionRuntime(runtimeEnvironmentName(declaredEnvironment));
   return {
     enabled: requested && !production,
     suppressedInProduction: requested && production,
@@ -129,8 +136,12 @@ function normalizeCoreOptions(raw) {
     timing: resolveTiming(raw?.timing),
     health: resolveHealth(raw?.health),
     metrics: resolveMetrics(raw?.metrics),
-    openapi: resolveOpenApi(raw?.openapi),
-    telemetry: resolveTelemetry(raw?.telemetry)
+    openapi: resolveOpenApi(raw?.openapi, raw?.environment),
+    telemetry: resolveTelemetry(raw?.telemetry),
+    // Spread rather than assigned so an application that declared nothing has
+    // no `environment` member at all, matching every other optional member on
+    // this snapshot under `exactOptionalPropertyTypes`.
+    ...raw?.environment === void 0 ? {} : { environment: raw.environment }
   });
 }
 normalizeCoreOptions();

package/dist/openapi/index.cjs

@@ -16,6 +16,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/discovery.ts
 function labelFor(className, token) {
@@ -653,7 +660,7 @@ async function applyBymaxOpenApi(app) {
   const logger = new common.Logger("BymaxCoreModule");
   const resolved = resolveCoreOptions(app);
   const options = resolved.openapi;
-  if (isProductionRuntime()) {
+  if (isProductionRuntime(runtimeEnvironmentName(resolved.environment))) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
         'openapi.enabled was requested but the OpenAPI document is never served in production. Set NODE_ENV to "development" or "test" to serve it.'

package/dist/openapi/index.mjs

@@ -14,6 +14,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/discovery.ts
 function labelFor(className, token) {
@@ -651,7 +658,7 @@ async function applyBymaxOpenApi(app) {
   const logger = new Logger("BymaxCoreModule");
   const resolved = resolveCoreOptions(app);
   const options = resolved.openapi;
-  if (isProductionRuntime()) {
+  if (isProductionRuntime(runtimeEnvironmentName(resolved.environment))) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
         'openapi.enabled was requested but the OpenAPI document is never served in production. Set NODE_ENV to "development" or "test" to serve it.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",