@bymax-one/nest-core 1.6.2 → 1.6.3

package/CHANGELOG.md

@@ -11,6 +11,60 @@ heading here.
 
 ## [Unreleased]
 
+## [1.6.3] - 2026-10-23
+
+The error envelope's `path` carried the query string, and the documented
+recipe for pairing with `@bymax-one/nest-logger` bound nothing.
+
+**Apply to a derived backend:**
+
+- **`path` changes in the response body.** An application that reads `path`
+  from the envelope now gets the request path alone. `/invoices/42?token=x`
+  and `http://host/invoices/42` both now read `/invoices/42`. The query string was never part of the documented
+  contract, and is where reset codes and tokens travel.
+- **The nest-logger correlation recipe changes.** An application that
+  followed the previous README recipe bound
+  `BYMAX_CORRELATION_PROVIDER` to `LogContextService` with `useExisting`, and
+  got no correlation id at all. Replace it with the `useFactory` in the
+  README's "Integration with `@bymax-one/nest-logger`", and make sure
+  nest-logger's request-id middleware is mounted (`applyAccessLog(app)` or
+  `applyRequestIdMiddleware(consumer)`). Without it there is no id to read.
+
+### Fixed
+
+- **The envelope `path` no longer carries the query string.** Both adapters
+  report the original URL, query included: Express returns `originalUrl`, and
+  Fastify the raw URL. The filter copied that into `path`, which is documented
+  as the request URL path. So a query-string secret reached the client and any
+  log that stores the envelope. An absolute-form target, as a proxy sends it,
+  also carried its scheme, authority and any credentials; only the path is
+  kept now. The `onUnexpectedError` context now receives the same path. The unexpected-error sink already reported the route
+  template and is unaffected.
+- **The nest-logger integration recipe binds what it promises.** It imported
+  `NestLoggerModule`, which does not exist; the module is `BymaxLoggerModule`.
+  It also aliased `LogContextService` with `useExisting`, but that service
+  has no `getCorrelationId()`. The binding was inert, and silently so: the
+  filter treats a failing correlation read as "no id". The README and the
+  specification now adapt the `requestId` key with a factory; the README
+  binds `PinoUnexpectedErrorSink` (nest-logger 1.4.1) beside it. The snippet
+  passed the published-surface gate before only because that gate ignores
+  diagnostics from a peer the fixture does not install.
+- **A thrown value that cannot be described no longer breaks the response.**
+  With `envelope.exposeInternals` on, a value with no prototype, or an `Error`
+  whose `stack` getter throws, threw out of the filter. The internals dump now
+  degrades to a fixed message, and the hooks still run.
+- **The discard warning no longer claims a mismatch for identical entries.**
+  It now says a generated client will not match the library's own types only
+  where the two definitions differ.
+
+### Changed
+
+- **Served component order (since 1.6.1).** Since 1.6.1, a document's own
+  `components.schemas` and `components.parameters` entries are listed before
+  this package's catalogue and before contributed entries. The 1.6.1 entry did
+  not say so. Order in a components map carries no meaning in OpenAPI, but it
+  shows in Swagger UI's model list and in a stored `openapi.json` snapshot.
+
 ## [1.6.2] - 2026-10-22
 
 An unexpected error became `500 BYMAX_INTERNAL_ERROR` and the application had no
@@ -1138,4 +1192,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.6.0]: https://github.com/bymaxone/nest-core/compare/v1.5.3...v1.6.0
 [1.6.1]: https://github.com/bymaxone/nest-core/compare/v1.6.0...v1.6.1
 [1.6.2]: https://github.com/bymaxone/nest-core/compare/v1.6.1...v1.6.2
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.2...HEAD
+[1.6.3]: https://github.com/bymaxone/nest-core/compare/v1.6.2...v1.6.3
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.3...HEAD

package/README.md

@@ -1546,27 +1546,67 @@ your samples and your logs.
 
 ## 🔗 Integration with `@bymax-one/nest-logger`
 
-Pairing this package with `@bymax-one/nest-logger` yields correlated logs and
-error responses with one binding and no hard coupling: `LogContextService`
-satisfies `ICorrelationIdProvider` out of the box, so `useExisting` aliases it
-onto the shared token. Bind it from a `@Global()` module of your own so the
-binding is visible outside the module that declares it:
+Pairing this package with `@bymax-one/nest-logger` gives correlated logs and
+error responses without either package importing the other. nest-logger's
+request-id middleware stores the id under the `requestId` key of
+`LogContextService`. That service is not itself an `ICorrelationIdProvider` —
+it has no `getCorrelationId()` — so adapt it with a factory. `useExisting` on
+it binds an object without that method, and the filter then reads no id and
+reports nothing. Bind both tokens from a `@Global()` module of your own so they
+are visible outside the module that declares them:
 
 ```typescript
 import { Global, Module } from '@nestjs/common'
-import { BYMAX_CORRELATION_PROVIDER } from '@bymax-one/nest-core'
-import { LogContextService, NestLoggerModule } from '@bymax-one/nest-logger'
+import { BYMAX_CORRELATION_PROVIDER, BYMAX_UNEXPECTED_ERROR_SINK } from '@bymax-one/nest-core'
+import type { ICorrelationIdProvider } from '@bymax-one/nest-core'
+import {
+  BymaxLoggerModule,
+  LogContextService,
+  PinoUnexpectedErrorSink
+} from '@bymax-one/nest-logger'
 
 @Global()
 @Module({
-  imports: [NestLoggerModule.forRoot()],
-  providers: [{ provide: BYMAX_CORRELATION_PROVIDER, useExisting: LogContextService }],
-  exports: [BYMAX_CORRELATION_PROVIDER]
+  imports: [BymaxLoggerModule.forRoot({ service: { name: 'api', version: '1.0.0' } })],
+  providers: [
+    {
+      provide: BYMAX_CORRELATION_PROVIDER,
+      inject: [LogContextService],
+      useFactory: (context: LogContextService): ICorrelationIdProvider => ({
+        getCorrelationId: () => context.get<string>('requestId')
+      })
+    },
+    { provide: BYMAX_UNEXPECTED_ERROR_SINK, useClass: PinoUnexpectedErrorSink }
+  ],
+  exports: [BYMAX_CORRELATION_PROVIDER, BYMAX_UNEXPECTED_ERROR_SINK]
 })
 export class ObservabilityModule {}
 ```
 
-Every error envelope now carries the same correlation id your logs do. The
+The id exists only once nest-logger's request-id middleware runs, and
+`BymaxLoggerModule` mounts none on its own. Mount it in `main.ts`, or call
+`applyRequestIdMiddleware(consumer)` from a module's `configure()`:
+
+> **Express only.** nest-logger's request-id middleware supports
+> `@nestjs/platform-express`; the Fastify adapter is unsupported, so do not
+> rely on this correlation provider there.
+
+```typescript
+import { NestFactory } from '@nestjs/core'
+import { applyAccessLog } from '@bymax-one/nest-logger'
+import { AppModule } from './app.module'
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule)
+  applyAccessLog(app) // opens the request context that carries `requestId`
+  await app.listen(3000)
+}
+void bootstrap()
+```
+
+Every error envelope now carries the same correlation id your logs do, and the
+cause of every collapsed `500` is logged with it (`PinoUnexpectedErrorSink`
+needs `@bymax-one/nest-logger` 1.4.1 or later). The
 same `@Global()`-module pattern is how every pluggable token in this package
 is overridden: `BYMAX_TIMING_SINK` and `BYMAX_HEALTH_INDICATORS` follow it
 identically.

package/dist/index.cjs

@@ -359,6 +359,19 @@ function extractRequestInfo(context) {
 var INTERNAL_ERROR_STATUS = 500;
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
+var ABSOLUTE_FORM_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+function pathOf(url) {
+  let target = String(url);
+  const prefix = ABSOLUTE_FORM_PREFIX.exec(target);
+  if (prefix !== null) {
+    const afterScheme = target.slice(prefix[0].length);
+    const authorityEnd = afterScheme.search(/[/?#]/);
+    target = authorityEnd === -1 ? "" : afterScheme.slice(authorityEnd);
+  }
+  const pathEnd = target.search(/[?#]/);
+  const path = pathEnd === -1 ? target : target.slice(0, pathEnd);
+  return path === "" ? "/" : path;
+}
 function resolveErrorCarrier(response) {
   if (typeof response !== "object" || response === null) {
     return void 0;
@@ -420,11 +433,16 @@ function extractHttpMessage(response, exception, carrier) {
   }
   return exception.message;
 }
+var UNREPRESENTABLE_MESSAGE = "Unrepresentable thrown value";
 function buildInternalDetails(exception) {
-  if (exception instanceof Error) {
-    return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+  try {
+    if (exception instanceof Error) {
+      return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+    }
+    return { message: String(exception) };
+  } catch {
+    return { message: UNREPRESENTABLE_MESSAGE };
   }
-  return { message: String(exception) };
 }
 exports.BymaxExceptionFilter = class BymaxExceptionFilter {
   /**
@@ -496,7 +514,7 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
     const traceId = this.readAnnotation(() => this.traceContext.getTraceContext()?.traceId);
     const context = {
       method: String(httpAdapter.getRequestMethod(request)),
-      path: String(httpAdapter.getRequestUrl(request)),
+      path: pathOf(httpAdapter.getRequestUrl(request)),
       ...correlationId !== void 0 ? { correlationId } : {},
       ...traceId !== void 0 ? { traceId } : {}
     };

package/dist/index.mjs

@@ -357,6 +357,19 @@ function extractRequestInfo(context) {
 var INTERNAL_ERROR_STATUS = 500;
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
+var ABSOLUTE_FORM_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+function pathOf(url) {
+  let target = String(url);
+  const prefix = ABSOLUTE_FORM_PREFIX.exec(target);
+  if (prefix !== null) {
+    const afterScheme = target.slice(prefix[0].length);
+    const authorityEnd = afterScheme.search(/[/?#]/);
+    target = authorityEnd === -1 ? "" : afterScheme.slice(authorityEnd);
+  }
+  const pathEnd = target.search(/[?#]/);
+  const path = pathEnd === -1 ? target : target.slice(0, pathEnd);
+  return path === "" ? "/" : path;
+}
 function resolveErrorCarrier(response) {
   if (typeof response !== "object" || response === null) {
     return void 0;
@@ -418,11 +431,16 @@ function extractHttpMessage(response, exception, carrier) {
   }
   return exception.message;
 }
+var UNREPRESENTABLE_MESSAGE = "Unrepresentable thrown value";
 function buildInternalDetails(exception) {
-  if (exception instanceof Error) {
-    return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+  try {
+    if (exception instanceof Error) {
+      return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+    }
+    return { message: String(exception) };
+  } catch {
+    return { message: UNREPRESENTABLE_MESSAGE };
   }
-  return { message: String(exception) };
 }
 var BymaxExceptionFilter = class {
   /**
@@ -494,7 +512,7 @@ var BymaxExceptionFilter = class {
     const traceId = this.readAnnotation(() => this.traceContext.getTraceContext()?.traceId);
     const context = {
       method: String(httpAdapter.getRequestMethod(request)),
-      path: String(httpAdapter.getRequestUrl(request)),
+      path: pathOf(httpAdapter.getRequestUrl(request)),
       ...correlationId !== void 0 ? { correlationId } : {},
       ...traceId !== void 0 ? { traceId } : {}
     };

package/dist/openapi/index.cjs

@@ -737,7 +737,7 @@ function warnDiscardedComponents(logger, discarded) {
   const elided = discarded.length - MAX_WARNED_OPERATIONS;
   const listed = discarded.slice(0, MAX_WARNED_OPERATIONS).map(({ contributor, member, name }) => `${contributor} -> ${member}.${name}`).join(", ");
   logger.warn(
-    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
+    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so where the two differ a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
   );
 }
 function buildConfig(builder, options) {

package/dist/openapi/index.mjs

@@ -735,7 +735,7 @@ function warnDiscardedComponents(logger, discarded) {
   const elided = discarded.length - MAX_WARNED_OPERATIONS;
   const listed = discarded.slice(0, MAX_WARNED_OPERATIONS).map(({ contributor, member, name }) => `${contributor} -> ${member}.${name}`).join(", ");
   logger.warn(
-    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
+    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so where the two differ a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
   );
 }
 function buildConfig(builder, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "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",