@bymax-one/nest-logger 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -11,6 +11,63 @@ heading here.
 
 ## [Unreleased]
 
+## [1.0.4] - 2026-07-29
+
+### Fixed
+
+- **The published declarations no longer depend on Express's types.** The HTTP
+  logging interceptor, the exception filter and the request-id middleware typed
+  their signatures with `Request` / `Response` / `NextFunction` from `express`,
+  so `dist/server/index.d.ts` imported from `express` and a consumer compiling
+  with `skipLibCheck: false` and no express types installed hit
+  `error TS2307: Cannot find module 'express'`. Present since 1.0.0; the imports
+  were `import type` only, so runtime was never affected and no express code was
+  ever bundled.
+
+  They are now typed by structural contracts declaring exactly the members this
+  package reads — `LoggableRequest` (`headers`, `method`, `url`, `ip`,
+  `user?.id`), `LoggableResponse` (`statusCode`, `setHeader`, `status().json()`)
+  and `NextHandler`. The emitted declarations import only `@nestjs/common`,
+  `pino` and `rxjs`, all declared peers.
+
+  **Not a breaking change:** an Express request and response satisfy the
+  contracts structurally, so existing call sites keep compiling with no cast —
+  the parameter types only widen what is accepted. The internal
+  `RequestWithUser` alias is gone, replaced by `LoggableRequest`; it was never
+  exported.
+
+### Added
+
+- `LoggableRequest`, `LoggableResponse`, `NextHandler` and `IncomingHeaders` are
+  exported from the package root: they type `RequestIdMiddleware.use()`, so a
+  consumer invoking it directly (in a test, say) can name them.
+
+### Removed
+
+- The `@types/express` optional peer dependency added in 1.0.3. With the
+  declarations self-contained it serves no purpose — nothing in the published
+  types names an express symbol. It stays a devDependency: the specs build
+  express-shaped mocks deliberately, to prove a real express request and
+  response still satisfy the contracts.
+
+## [1.0.3] - 2026-07-29
+
+### Fixed
+
+- **Declared `@types/express` as an optional peer dependency.** The published
+  declarations reference `Request` / `Response` / `NextFunction` from `express`
+  (the HTTP interceptor, the exception filter and the request-id middleware all
+  type their signatures with them), but the requirement was undeclared. A
+  consumer compiling with `skipLibCheck: false` and no express types installed
+  hit `error TS2307: Cannot find module 'express'` from inside
+  `dist/server/index.d.ts` with nothing in `package.json` pointing at the cause.
+  Present since 1.0.0 — the imports are `import type` only, so runtime was never
+  affected and no express code is bundled.
+
+  It is marked optional because nothing in the library needs express at runtime:
+  a consumer on a non-express adapter (Fastify) can ignore it, as can anyone
+  keeping `skipLibCheck: true` — the default the Nest CLI scaffolds.
+
 ## [1.0.2] - 2026-07-29
 
 ### Fixed
@@ -130,7 +187,10 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
 - Professional CI suite: `ci.yml`, `bench.yml`, `codeql.yml`, `scorecard.yml`,
   `release.yml`, Dependabot, and issue templates
 
-[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.0.4...HEAD
+[1.0.4]: https://github.com/bymaxone/nest-logger/compare/v1.0.3...v1.0.4
+[1.0.3]: https://github.com/bymaxone/nest-logger/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/bymaxone/nest-logger/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/bymaxone/nest-logger/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/bymaxone/nest-logger/compare/v0.1.0...v1.0.0
 [0.1.0]: https://github.com/bymaxone/nest-logger/releases/tag/v0.1.0

package/README.md

@@ -143,11 +143,15 @@ pnpm add -D pino-pretty
 
 # Optional — OpenTelemetry trace correlation
 pnpm add @opentelemetry/api @opentelemetry/sdk-node
+
 ```
 
 > [!NOTE]
 > `@opentelemetry/api` is resolved lazily when the Pino instance is built. When it is absent the trace mixin silently steps aside — the logger never fails to start, and never warns, over an optional peer.
 
+> [!NOTE]
+> The published declarations depend on no HTTP framework's types. The HTTP interceptor, the exception filter and the request-id middleware are typed by structural contracts (`LoggableRequest`, `LoggableResponse`, `NextHandler`) that an Express request and response satisfy as-is, so nothing extra is needed even when you compile with `skipLibCheck: false`. The emitted `.d.ts` imports only `@nestjs/common`, `pino` and `rxjs`.
+
 ### 2. Register the module
 
 ```typescript

package/dist/server/index.cjs

@@ -1363,8 +1363,8 @@ exports.RequestIdMiddleware = class RequestIdMiddleware {
    * Echo or mint the `x-request-id`, expose it on the response, and run the
    * remainder of the request inside a fresh log-context scope.
    *
-   * @param req - The incoming Express request.
-   * @param res - The outgoing Express response.
+   * @param req - The incoming request (Express satisfies the contract).
+   * @param res - The outgoing response (Express satisfies the contract).
    * @param next - The next handler in the chain.
    */
   use(req, res, next) {

package/dist/server/index.d.cts

@@ -2,7 +2,6 @@ import * as _nestjs_common from '@nestjs/common';
 import { ModuleMetadata, Type, DynamicModule, INestApplication, LoggerService, OnApplicationShutdown, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler, MiddlewareConsumer, NestMiddleware, CustomDecorator } from '@nestjs/common';
 import { Logger } from 'pino';
 import { Observable } from 'rxjs';
-import { Request, Response, NextFunction } from 'express';
 
 /**
  * Pino log levels (mirrored to NestJS-compatible names).
@@ -753,6 +752,66 @@ declare class HttpLoggingInterceptor implements NestInterceptor {
  */
 declare function applyRequestIdMiddleware(consumer: MiddlewareConsumer, routes?: string): void;
 
+/**
+ * Minimal HTTP request/response contracts the logging layer reads.
+ *
+ * Layer: server/interfaces — exported structural contracts shared by the HTTP
+ * logging interceptor, the exception filter and the request-id middleware. They
+ * are part of the public API: they appear in those components' published
+ * signatures, so a consumer calling `RequestIdMiddleware.use()` directly needs
+ * to be able to name them. Declared structurally, listing only the members
+ * those three actually touch, so the published declarations depend on no HTTP
+ * framework's types. Naming Express's
+ * `Request`/`Response` here would make the emitted `.d.ts` import from
+ * `express`, forcing every consumer that compiles with `skipLibCheck: false` to
+ * install `@types/express` whether or not they use those signatures.
+ *
+ * The shapes mirror what the Express adapter provides — `status().json()` and
+ * `setHeader()` are Express/Node response methods — so this is not an
+ * adapter-agnostic abstraction; a Fastify adapter remains unsupported. An
+ * Express request and response satisfy these contracts structurally, with no
+ * cast at the call site.
+ */
+/** Raw inbound headers, as the HTTP layer delivers them. */
+type IncomingHeaders = Record<string, string | string[] | undefined>;
+/**
+ * The inbound request members the logging layer reads.
+ *
+ * `user` is populated by upstream auth in the consumer app (a guard or
+ * middleware); only `id` is ever read, for the acting-user log field.
+ */
+interface LoggableRequest {
+    /** Inbound headers — read for correlation ids and the user agent. */
+    readonly headers: IncomingHeaders;
+    /** HTTP verb, logged as-is. */
+    readonly method: string;
+    /** Request target, normalized and query-stripped before it reaches a log. */
+    readonly url: string;
+    /** Client address when the adapter resolves one. */
+    readonly ip?: string | undefined;
+    /** Authenticated principal, when upstream auth attached one. */
+    readonly user?: {
+        readonly id?: string | undefined;
+    } | undefined;
+}
+/**
+ * The outbound response members the logging layer writes or reads: the status
+ * for the terminal log entry, `setHeader` to echo the correlation id, and the
+ * chainable `status().json()` used by the exception filter to emit a body.
+ */
+interface LoggableResponse {
+    /** Status code, read when logging the completed request. */
+    readonly statusCode: number;
+    /** Sets a response header (used for the correlation id). */
+    setHeader(name: string, value: string): void;
+    /** Selects the status code and returns the chainable body writer. */
+    status(code: number): {
+        json(body: unknown): unknown;
+    };
+}
+/** Continuation passed to a middleware; invoked with no arguments here. */
+type NextHandler = () => void;
+
 /**
  * Reads (or generates) the correlation id and starts the per-request log
  * context scope.
@@ -783,11 +842,11 @@ declare class RequestIdMiddleware implements NestMiddleware {
      * Echo or mint the `x-request-id`, expose it on the response, and run the
      * remainder of the request inside a fresh log-context scope.
      *
-     * @param req - The incoming Express request.
-     * @param res - The outgoing Express response.
+     * @param req - The incoming request (Express satisfies the contract).
+     * @param res - The outgoing response (Express satisfies the contract).
      * @param next - The next handler in the chain.
      */
-    use(req: Request, res: Response, next: NextFunction): void;
+    use(req: LoggableRequest, res: LoggableResponse, next: NextHandler): void;
 }
 
 /**
@@ -950,4 +1009,4 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
 }>;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type OtelOptions, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };

package/dist/server/index.d.ts

@@ -2,7 +2,6 @@ import * as _nestjs_common from '@nestjs/common';
 import { ModuleMetadata, Type, DynamicModule, INestApplication, LoggerService, OnApplicationShutdown, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler, MiddlewareConsumer, NestMiddleware, CustomDecorator } from '@nestjs/common';
 import { Logger } from 'pino';
 import { Observable } from 'rxjs';
-import { Request, Response, NextFunction } from 'express';
 
 /**
  * Pino log levels (mirrored to NestJS-compatible names).
@@ -753,6 +752,66 @@ declare class HttpLoggingInterceptor implements NestInterceptor {
  */
 declare function applyRequestIdMiddleware(consumer: MiddlewareConsumer, routes?: string): void;
 
+/**
+ * Minimal HTTP request/response contracts the logging layer reads.
+ *
+ * Layer: server/interfaces — exported structural contracts shared by the HTTP
+ * logging interceptor, the exception filter and the request-id middleware. They
+ * are part of the public API: they appear in those components' published
+ * signatures, so a consumer calling `RequestIdMiddleware.use()` directly needs
+ * to be able to name them. Declared structurally, listing only the members
+ * those three actually touch, so the published declarations depend on no HTTP
+ * framework's types. Naming Express's
+ * `Request`/`Response` here would make the emitted `.d.ts` import from
+ * `express`, forcing every consumer that compiles with `skipLibCheck: false` to
+ * install `@types/express` whether or not they use those signatures.
+ *
+ * The shapes mirror what the Express adapter provides — `status().json()` and
+ * `setHeader()` are Express/Node response methods — so this is not an
+ * adapter-agnostic abstraction; a Fastify adapter remains unsupported. An
+ * Express request and response satisfy these contracts structurally, with no
+ * cast at the call site.
+ */
+/** Raw inbound headers, as the HTTP layer delivers them. */
+type IncomingHeaders = Record<string, string | string[] | undefined>;
+/**
+ * The inbound request members the logging layer reads.
+ *
+ * `user` is populated by upstream auth in the consumer app (a guard or
+ * middleware); only `id` is ever read, for the acting-user log field.
+ */
+interface LoggableRequest {
+    /** Inbound headers — read for correlation ids and the user agent. */
+    readonly headers: IncomingHeaders;
+    /** HTTP verb, logged as-is. */
+    readonly method: string;
+    /** Request target, normalized and query-stripped before it reaches a log. */
+    readonly url: string;
+    /** Client address when the adapter resolves one. */
+    readonly ip?: string | undefined;
+    /** Authenticated principal, when upstream auth attached one. */
+    readonly user?: {
+        readonly id?: string | undefined;
+    } | undefined;
+}
+/**
+ * The outbound response members the logging layer writes or reads: the status
+ * for the terminal log entry, `setHeader` to echo the correlation id, and the
+ * chainable `status().json()` used by the exception filter to emit a body.
+ */
+interface LoggableResponse {
+    /** Status code, read when logging the completed request. */
+    readonly statusCode: number;
+    /** Sets a response header (used for the correlation id). */
+    setHeader(name: string, value: string): void;
+    /** Selects the status code and returns the chainable body writer. */
+    status(code: number): {
+        json(body: unknown): unknown;
+    };
+}
+/** Continuation passed to a middleware; invoked with no arguments here. */
+type NextHandler = () => void;
+
 /**
  * Reads (or generates) the correlation id and starts the per-request log
  * context scope.
@@ -783,11 +842,11 @@ declare class RequestIdMiddleware implements NestMiddleware {
      * Echo or mint the `x-request-id`, expose it on the response, and run the
      * remainder of the request inside a fresh log-context scope.
      *
-     * @param req - The incoming Express request.
-     * @param res - The outgoing Express response.
+     * @param req - The incoming request (Express satisfies the contract).
+     * @param res - The outgoing response (Express satisfies the contract).
      * @param next - The next handler in the chain.
      */
-    use(req: Request, res: Response, next: NextFunction): void;
+    use(req: LoggableRequest, res: LoggableResponse, next: NextHandler): void;
 }
 
 /**
@@ -950,4 +1009,4 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
 }>;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type OtelOptions, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };

package/dist/server/index.mjs

@@ -1357,8 +1357,8 @@ var RequestIdMiddleware = class {
    * Echo or mint the `x-request-id`, expose it on the response, and run the
    * remainder of the request inside a fresh log-context scope.
    *
-   * @param req - The incoming Express request.
-   * @param res - The outgoing Express response.
+   * @param req - The incoming request (Express satisfies the contract).
+   * @param res - The outgoing response (Express satisfies the contract).
    * @param next - The next handler in the chain.
    */
   use(req, res, next) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -73,10 +73,10 @@
     "rxjs": "^7.8.0"
   },
   "peerDependenciesMeta": {
-    "pino-pretty": {
+    "@opentelemetry/api": {
       "optional": true
     },
-    "@opentelemetry/api": {
+    "pino-pretty": {
       "optional": true
     }
   },