@bymax-one/nest-core 1.1.1 → 1.2.1

package/CHANGELOG.md

@@ -11,6 +11,59 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-08-08
+
+A patch: the envelope fix below changes a response status for a class of client errors, without
+touching the module's API or any option.
+
+### Fixed
+
+- **An error carrying a 4xx status it marked exposable keeps that status, instead of collapsing to 500.** Express's body pipeline throws `http-errors` instances before any handler runs — a payload
+  past the limit is `PayloadTooLargeError` (413), malformed JSON is a `SyntaxError` (400), an
+  unsupported media type is 415. None is a Nest `HttpException`, so each reached the generic
+  500 collapse: a client that sent too large a body, or malformed JSON, was told the server failed,
+  and a monitor counted a 5xx for a request that never entered the application. The filter now reads
+  the `expose: true` flag and the numeric status these carry and honours it — restricted to the 4xx
+  range, because a self-reported 5xx is still a server failure whose account of itself must not
+  surface, so it stays a generic 500.
+
+## [1.2.0] - 2026-08-08
+
+Both entries change what a caller receives, which is why this is a minor rather than a patch: an
+application wiring `@bymax-one/nest-auth` starts seeing that library's own error codes where it
+previously saw one collapsed `BYMAX_BAD_REQUEST`, and a deployment with a feature disabled starts
+answering `404` where it answered `500`.
+
+### Fixed
+
+- **A feature disabled on the `forRootAsync` path answers `404` instead of `500`.** Route metadata
+  is fixed before the async options resolve, so the health and metrics controllers register
+  regardless and guard at request time. That guard threw a plain `Error`, which the envelope
+  renders as `BYMAX_INTERNAL_ERROR` — so every consumer registering asynchronously with
+  `metrics: { enabled: false }`, which is the ordinary configuration and the one that keeps the
+  optional `prom-client` peer unloaded, served an unauthenticated `/metrics` that answered a
+  server error to anyone who asked. It counted as a real failure in alerting, in error budgets and
+  in any uptime check pointed at the service, describing a state nothing was wrong with.
+
+  The route now reads as absent, which is what the caller would have seen had the framework been
+  able to skip the registration. Only the feature's _absence_ is normalised: a resolved path that
+  disagrees with the route the controller was registered at is a genuine misconfiguration and
+  still throws.
+
+- **A domain error's `details` reach the caller, and a nested `{ error: { … } }` body is read as
+  readily as a flat one.** The filter passed an explicit `code` through but dropped the structured
+  context beside it, and recognised the fields only when they sat directly on the response.
+
+  `@bymax-one/nest-auth` builds `{ error: { code, message, details } }`, so a backend wiring both
+  libraries rendered every distinct auth failure identically — a duplicate e-mail, a password below
+  the policy floor, a missing field all arrived as `BYMAX_BAD_REQUEST` / `"Auth Exception"` with no
+  details. A client could not branch on the failure, and neither could whoever was debugging it.
+
+  A nested object is followed only when it carries a string `code`, since `error` is an ordinary
+  word for a response body to use; a flat code still wins over a nested one; and a `details` value
+  that is neither an array nor an object — including the `null` `AuthException` writes to mean
+  "none" — is omitted rather than reshaped, so the field stays present only when context exists.
+
 ## [1.1.1] - 2026-08-07
 
 **Documentation and tooling.** `dist/` differs from `1.1.0` only in the text of the comments
@@ -264,4 +317,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.0.1]: https://github.com/bymaxone/nest-core/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/bymaxone/nest-core/releases/tag/v1.0.0
 [1.1.1]: https://github.com/bymaxone/nest-core/compare/v1.1.0...v1.1.1
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.1.1...HEAD
+[1.2.1]: https://github.com/bymaxone/nest-core/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/bymaxone/nest-core/compare/v1.1.1...v1.2.0
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.2.1...HEAD

package/dist/index.cjs

@@ -287,12 +287,45 @@ function buildErrorEnvelope(input) {
 var INTERNAL_ERROR_STATUS = 500;
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
-function extractExplicitCode(response) {
-  if (typeof response !== "object" || response === null || !("code" in response)) {
+function resolveErrorCarrier(response) {
+  if (typeof response !== "object" || response === null) {
     return void 0;
   }
-  const code = response.code;
-  return typeof code === "string" ? code : void 0;
+  if (hasStringCode(response)) {
+    return response;
+  }
+  const nested = response.error;
+  if (typeof nested === "object" && nested !== null && hasStringCode(nested)) {
+    return nested;
+  }
+  return void 0;
+}
+function hasStringCode(value) {
+  return "code" in value && typeof value.code === "string";
+}
+function extractExplicitCode(carrier) {
+  return carrier.code;
+}
+function extractExplicitDetails(carrier) {
+  const details = carrier.details;
+  return typeof details === "object" && details !== null ? details : void 0;
+}
+var CLIENT_ERROR_MIN2 = 400;
+var CLIENT_ERROR_MAX2 = 500;
+function resolveExposedClientError(exception) {
+  if (typeof exception !== "object" || exception === null) {
+    return void 0;
+  }
+  const candidate = exception;
+  if (candidate.expose !== true) {
+    return void 0;
+  }
+  const status = Number.isInteger(candidate.status) ? candidate.status : candidate.statusCode;
+  if (typeof status !== "number" || !Number.isInteger(status) || status < CLIENT_ERROR_MIN2 || status >= CLIENT_ERROR_MAX2) {
+    return void 0;
+  }
+  const message = exception instanceof Error ? exception.message : "";
+  return { status, message: message === "" ? INTERNAL_ERROR_MESSAGE : message };
 }
 function isValidationResponse(response) {
   return typeof response === "object" && response !== null && "message" in response && Array.isArray(response.message);
@@ -302,12 +335,13 @@ function toValidationDetails(violations) {
     (violation) => typeof violation === "string" ? { issue: violation } : violation
   );
 }
-function extractHttpMessage(response, exception) {
+function extractHttpMessage(response, exception, carrier) {
   if (typeof response === "string") {
     return response;
   }
-  if (typeof response === "object" && response !== null && "message" in response) {
-    const message = response.message;
+  const source = carrier ?? response;
+  if (typeof source === "object" && source !== null && "message" in source) {
+    const message = source.message;
     if (typeof message === "string") {
       return message;
     }
@@ -407,6 +441,15 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
     if (exception instanceof common.HttpException) {
       return this.mapHttpException(exception, context);
     }
+    const exposed = resolveExposedClientError(exception);
+    if (exposed !== void 0) {
+      return this.toEnvelope(
+        exposed.status,
+        codeForStatus(exposed.status),
+        exposed.message,
+        context
+      );
+    }
     try {
       this.onUnexpectedError(exception, context);
     } catch {
@@ -414,9 +457,10 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
     return this.mapUnknown(exception, context);
   }
   /**
-   * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-   * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-   * details; everything else derives its code from the status.
+   * Map an `HttpException` to the envelope. A domain error passes its own code,
+   * message and details through, whether it wrote them flat on the response or
+   * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+   * with structured details; everything else derives its code from the status.
    *
    * @param exception - The HTTP exception to format.
    * @param context - The neutral request context.
@@ -425,9 +469,15 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
   mapHttpException(exception, context) {
     const status = exception.getStatus();
     const response = exception.getResponse();
-    const explicitCode = extractExplicitCode(response);
-    if (explicitCode !== void 0) {
-      return this.toEnvelope(status, explicitCode, extractHttpMessage(response, exception), context);
+    const carrier = resolveErrorCarrier(response);
+    if (carrier !== void 0) {
+      return this.toEnvelope(
+        status,
+        extractExplicitCode(carrier),
+        extractHttpMessage(response, exception, carrier),
+        context,
+        extractExplicitDetails(carrier)
+      );
     }
     if (isValidationResponse(response)) {
       return this.toEnvelope(
@@ -682,8 +732,8 @@ var PassThroughInterceptor = class {
 };
 function assertAsyncFeatureEnabled(feature, enabled) {
   if (!enabled) {
-    throw new Error(
-      `[BymaxCoreModule] The "${feature}" controller was reached while the feature is disabled. On the forRootAsync path this controller is always registered because options resolve after the module is defined; enable "${feature}" in the resolved options, or do not expose this controller while the feature is disabled.`
+    throw new common.NotFoundException(
+      `[BymaxCoreModule] The "${feature}" feature is disabled, so this route does not exist.`
     );
   }
 }

package/dist/index.d.cts

@@ -464,9 +464,10 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      */
     private buildEnvelope;
     /**
-     * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-     * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-     * details; everything else derives its code from the status.
+     * Map an `HttpException` to the envelope. A domain error passes its own code,
+     * message and details through, whether it wrote them flat on the response or
+     * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+     * with structured details; everything else derives its code from the status.
      *
      * @param exception - The HTTP exception to format.
      * @param context - The neutral request context.

package/dist/index.d.ts

@@ -464,9 +464,10 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      */
     private buildEnvelope;
     /**
-     * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-     * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-     * details; everything else derives its code from the status.
+     * Map an `HttpException` to the envelope. A domain error passes its own code,
+     * message and details through, whether it wrote them flat on the response or
+     * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+     * with structured details; everything else derives its code from the status.
      *
      * @param exception - The HTTP exception to format.
      * @param context - The neutral request context.

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Logger, Get, Res, Controller, HttpStatus } from '@nestjs/common';
+import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Logger, Get, Res, Controller, HttpStatus, NotFoundException } from '@nestjs/common';
 import { HttpAdapterHost, DiscoveryService, Reflector, BaseExceptionFilter, APP_FILTER, APP_INTERCEPTOR, DiscoveryModule } from '@nestjs/core';
 import { tap, catchError, throwError } from 'rxjs';
 
@@ -285,12 +285,45 @@ function buildErrorEnvelope(input) {
 var INTERNAL_ERROR_STATUS = 500;
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
-function extractExplicitCode(response) {
-  if (typeof response !== "object" || response === null || !("code" in response)) {
+function resolveErrorCarrier(response) {
+  if (typeof response !== "object" || response === null) {
     return void 0;
   }
-  const code = response.code;
-  return typeof code === "string" ? code : void 0;
+  if (hasStringCode(response)) {
+    return response;
+  }
+  const nested = response.error;
+  if (typeof nested === "object" && nested !== null && hasStringCode(nested)) {
+    return nested;
+  }
+  return void 0;
+}
+function hasStringCode(value) {
+  return "code" in value && typeof value.code === "string";
+}
+function extractExplicitCode(carrier) {
+  return carrier.code;
+}
+function extractExplicitDetails(carrier) {
+  const details = carrier.details;
+  return typeof details === "object" && details !== null ? details : void 0;
+}
+var CLIENT_ERROR_MIN2 = 400;
+var CLIENT_ERROR_MAX2 = 500;
+function resolveExposedClientError(exception) {
+  if (typeof exception !== "object" || exception === null) {
+    return void 0;
+  }
+  const candidate = exception;
+  if (candidate.expose !== true) {
+    return void 0;
+  }
+  const status = Number.isInteger(candidate.status) ? candidate.status : candidate.statusCode;
+  if (typeof status !== "number" || !Number.isInteger(status) || status < CLIENT_ERROR_MIN2 || status >= CLIENT_ERROR_MAX2) {
+    return void 0;
+  }
+  const message = exception instanceof Error ? exception.message : "";
+  return { status, message: message === "" ? INTERNAL_ERROR_MESSAGE : message };
 }
 function isValidationResponse(response) {
   return typeof response === "object" && response !== null && "message" in response && Array.isArray(response.message);
@@ -300,12 +333,13 @@ function toValidationDetails(violations) {
     (violation) => typeof violation === "string" ? { issue: violation } : violation
   );
 }
-function extractHttpMessage(response, exception) {
+function extractHttpMessage(response, exception, carrier) {
   if (typeof response === "string") {
     return response;
   }
-  if (typeof response === "object" && response !== null && "message" in response) {
-    const message = response.message;
+  const source = carrier ?? response;
+  if (typeof source === "object" && source !== null && "message" in source) {
+    const message = source.message;
     if (typeof message === "string") {
       return message;
     }
@@ -405,6 +439,15 @@ var BymaxExceptionFilter = class {
     if (exception instanceof HttpException) {
       return this.mapHttpException(exception, context);
     }
+    const exposed = resolveExposedClientError(exception);
+    if (exposed !== void 0) {
+      return this.toEnvelope(
+        exposed.status,
+        codeForStatus(exposed.status),
+        exposed.message,
+        context
+      );
+    }
     try {
       this.onUnexpectedError(exception, context);
     } catch {
@@ -412,9 +455,10 @@ var BymaxExceptionFilter = class {
     return this.mapUnknown(exception, context);
   }
   /**
-   * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-   * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-   * details; everything else derives its code from the status.
+   * Map an `HttpException` to the envelope. A domain error passes its own code,
+   * message and details through, whether it wrote them flat on the response or
+   * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+   * with structured details; everything else derives its code from the status.
    *
    * @param exception - The HTTP exception to format.
    * @param context - The neutral request context.
@@ -423,9 +467,15 @@ var BymaxExceptionFilter = class {
   mapHttpException(exception, context) {
     const status = exception.getStatus();
     const response = exception.getResponse();
-    const explicitCode = extractExplicitCode(response);
-    if (explicitCode !== void 0) {
-      return this.toEnvelope(status, explicitCode, extractHttpMessage(response, exception), context);
+    const carrier = resolveErrorCarrier(response);
+    if (carrier !== void 0) {
+      return this.toEnvelope(
+        status,
+        extractExplicitCode(carrier),
+        extractHttpMessage(response, exception, carrier),
+        context,
+        extractExplicitDetails(carrier)
+      );
     }
     if (isValidationResponse(response)) {
       return this.toEnvelope(
@@ -680,8 +730,8 @@ var PassThroughInterceptor = class {
 };
 function assertAsyncFeatureEnabled(feature, enabled) {
   if (!enabled) {
-    throw new Error(
-      `[BymaxCoreModule] The "${feature}" controller was reached while the feature is disabled. On the forRootAsync path this controller is always registered because options resolve after the module is defined; enable "${feature}" in the resolved options, or do not expose this controller while the feature is disabled.`
+    throw new NotFoundException(
+      `[BymaxCoreModule] The "${feature}" feature is disabled, so this route does not exist.`
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "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",
@@ -86,8 +86,8 @@
     "lint": "eslint --no-error-on-unmatched-pattern src scripts test",
     "lint:fix": "eslint --no-error-on-unmatched-pattern src scripts test --fix",
     "mutation": "stryker run",
+    "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "mutation:dry-run": "stryker run --dryRunOnly",
-    "mutation:incremental": "stryker run --incremental",
     "prepare": "husky",
     "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm check:mutants && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
     "release": "npm publish --provenance --access public",