@evanion/nestjs-correlation-id 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,61 @@
-RELEASE 1.0.0
+# Changelog
+
+## 2.0.0 (2026-08-27)
+
+First release from the [Evanion/libraries](https://github.com/Evanion/libraries)
+monorepo. The library moved here from the standalone
+`Evanion/nestjs-correlation-id` repo; 1.1.0 was the last release from there.
+
+### ⚠️ Breaking Changes
+
+- **NestJS 6 through 9 are no longer supported.** The peer range is now
+  `^10 || ^11 || ^12`. Those majors are long past end of life, and claiming
+  support for versions that are never tested is worse than declaring the range
+  honestly.
+- **An `exports` map was added.** Deep imports into `dist/` no longer resolve.
+  They were never a documented entry point.
+- **`uuid` is no longer a dependency.** Ids now come from `node:crypto`'s
+  `randomUUID`, which has been built into every supported Node version. The
+  generated format is unchanged (RFC 4122 v4), and a custom `generator` is
+  unaffected. This library now has no runtime dependencies beyond `tslib`.
+- **Node 20 or newer is required**, declared via `engines`.
+
+### 🚀 Features
+
+- **Ships both ESM and CommonJS.** NestJS 12 is ESM-only while 10 and 11 are
+  CommonJS, so both formats are needed to cover the supported range. `import`
+  and `require()` both work, and both are verified against a packed tarball on
+  every release.
+- **NestJS 12 support.**
+- **`CorrelationConfig` is now exported** from the package root. It is the type
+  `CorrelationModule.forRoot()` takes, and it was never exported — so callers
+  could configure the module without being able to name the type.
+- **`@nestjs/axios` is now an optional peer dependency.** It is only used for a
+  type in `withCorrelation`, and the import is type-only, so it is erased at
+  runtime. Consumers that do not use `withCorrelation` no longer need it
+  installed.
+
+### 🩹 Fixes
+
+- **The `@nestjs/axios` peer range was malformed and matched nothing.** It read
+  `^0.1.0 || ^1.0.0 || ^2.0.0 || ^3.00` — that `^3.00` is not valid semver, and
+  one invalid comparator invalidates the _entire_ range, so even the `^2.0.0`
+  entry failed to match. This is why
+  [#1 "Add support for @nestjs/axios 2x"](https://github.com/Evanion/nestjs-correlation-id/issues/1)
+  stayed broken after 2.x was ostensibly added: a single missing zero.
+- The README imported from `@nestjs-common` rather than `@nestjs/common`.
+
+### 🏗️ Internal
+
+- Tests migrated from jest to vitest, and expanded from 5 to 12.
+- Releases now go through `nx release` with npm trusted publishing and
+  provenance, replacing release-it.
+
+## 1.0.0
 
 - Initial release
+
+> Releases 1.0.3 through 1.1.0 were published from the standalone repository
+> without changelog entries. See the
+> [commit history](https://github.com/Evanion/nestjs-correlation-id/commits/main)
+> there for what changed.

package/README.md

@@ -8,6 +8,31 @@
   </a>
 </div>
 
+### Requirements
+
+|            |             |
+| ---------- | ----------- |
+| **NestJS** | 12          |
+| **Node**   | 20 or newer |
+
+Ships ESM only, matching NestJS 12. There is no CommonJS build, so
+`require('@evanion/nestjs-correlation-id')` will not work — use `import`.
+
+One build means one module graph and one `CorrelationService` class object, so
+injecting by class token is always safe. The dual build this package used to
+ship could hand Nest two unrelated copies of the same class.
+
+The middleware is typed against `node:http`'s `IncomingMessage` and
+`ServerResponse` and reads and writes raw headers, so it works under
+`@nestjs/platform-express` and `@nestjs/platform-fastify` alike. `express` is
+not a peer dependency.
+
+`@nestjs/axios` is an optional peer dependency, needed only if you use
+[`withCorrelation`](#how-to-use). It is a
+type-only import, so it is not pulled in at runtime.
+
+This package has no runtime dependencies beyond `tslib`.
+
 ### Why?
 
 When debugging an issue in your applications logs, it helps to be able to follow a specific request up and down your whole stack. This is usually done by including a `correlation-id` (aka `Request-id`) header in all your requests, and forwarding the same id across all your microservices.
@@ -43,7 +68,14 @@ export class AppModule implements NestModule {
 }
 ```
 
-And then just inject the correlation middleware in your HttpService by calling the `registerAsync` method with the `withCorrelation` function.
+`CorrelationIdMiddleware` opens an
+[`AsyncLocalStorage`](https://nodejs.org/api/async_context.html) context for the
+request. Everything downstream of it — guards, interceptors, controllers, and
+anything they await — sees that request's id, and concurrent requests stay
+isolated.
+
+Then forward the id on outgoing HTTP calls by passing `withCorrelation()` to
+`HttpModule.registerAsync`.
 
 ```ts
 import { HttpModule } from '@nestjs/axios';
@@ -57,7 +89,49 @@ import { withCorrelation } from '@evanion/nestjs-correlation-id';
 export class UsersModule {}
 ```
 
-You can now use the `HttpService` as usual in your `UsersService` and `UsersController`
+Use `HttpService` as usual in `UsersService` and `UsersController`. It stays a
+singleton: the correlation header is attached by an axios request interceptor
+that reads the current context when the request is made.
+
+`withCorrelation()` needs `CorrelationModule.forRoot()` to have been called
+somewhere in the application — it is a global module, so once in the root module
+is enough. Without it, Nest fails at boot with
+`Nest can't resolve dependencies of the HTTP_MODULE_OPTIONS (?)`.
+
+### Working outside a request
+
+`CorrelationService` is a singleton, so it is injected like any other provider
+and resolved with `module.get(CorrelationService)`. Outside a correlation
+context `getCorrelationId()` returns `undefined`, and outgoing calls carry no
+correlation header.
+
+For work with no request behind it — queue consumers, cron jobs, scripts — open
+a context yourself:
+
+```ts
+await this.correlationService.run(this.correlationService.generate(), () =>
+  this.processJob(job),
+);
+```
+
+### Configuration
+
+`CorrelationModule.forRoot()` accepts a `CorrelationConfig`, exported from the
+package root.
+
+```ts
+import {
+  CorrelationModule,
+  type CorrelationConfig,
+} from '@evanion/nestjs-correlation-id';
+
+const config: Partial<CorrelationConfig> = {
+  header: 'X-Request-Id', // defaults to 'X-Correlation-Id'
+  generator: () => myId(), // defaults to node:crypto randomUUID
+};
+
+CorrelationModule.forRoot(config);
+```
 
 ### Customize
 
@@ -79,64 +153,56 @@ export class AppModule implements NestModule {
 
 #### Add `correlationId` to logs
 
-In order to add the correlation ID to your logs, you can use the `CorrelationService` service to get the current correlationId.
-
-In the following example, we are using the [@ntegral/nestjs-sentry](https://github.com/ntegral/nestjs-sentry) package, but you can use any package or provider you like.
+Inject `CorrelationService` wherever you build log context and read the current
+id. It is a singleton, so nothing about injecting it changes the scope of the
+provider holding it.
 
 ```ts
 import { CorrelationService } from '@evanion/nestjs-correlation-id';
 import { Injectable, NestMiddleware } from '@nestjs/common';
-import { InjectSentry, SentryService } from '@ntegral/nestjs-sentry';
-import { NextFunction, Request, Response } from 'express';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import * as Sentry from '@sentry/node';
 
 @Injectable()
-export class SentryMiddleware implements NestMiddleware {
-  constructor(
-    private readonly correlationService: CorrelationService,
-    @InjectSentry() private readonly sentryService: SentryService,
-  ) {}
-
-  async use(_req: Request, _res: Response, next: NextFunction) {
-    const correlationId = await this.correlationService.getCorrelationId();
-    this.sentryService.instance().configureScope((scope) => {
-      scope.setTag('correlationId', correlationId);
-    });
+export class SentryTagMiddleware implements NestMiddleware {
+  constructor(private readonly correlationService: CorrelationService) {}
+
+  use(_req: IncomingMessage, _res: ServerResponse, next: () => void) {
+    const correlationId = this.correlationService.getCorrelationId();
+    if (correlationId) Sentry.setTag('correlationId', correlationId);
     next();
   }
 }
 ```
 
-Then add it to your `AppModule`
+`getCorrelationId()` is synchronous — it never returned a promise — and gives
+`undefined` when there is no correlation context, so apply this after
+`CorrelationIdMiddleware`, which is what opens one.
 
 ```ts
-import { Module } from '@nestjs-common';
-import { SentryModule } from '@ntegral/nestjs-sentry';
-import { CorrelationModule } from '@evanion/nestjs-correlation-id';
-import { SentryMiddleware } from './middleware/sentry.middleware';
-
 @Module({
-  imports: [
-    CorrelationModule.forRoot(),
-    SentryModule.forRoot({
-      // ... your config
-    }),
-  ],
+  imports: [CorrelationModule.forRoot()],
 })
 export class AppModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
     consumer.apply(CorrelationIdMiddleware).forRoutes('*');
-    consumer.apply(SentryMiddleware).forRoutes('*');
+    consumer.apply(SentryTagMiddleware).forRoutes('*');
   }
 }
 ```
 
-If you need to manually set the correlationId anywhere in your application. You can use the `CorrelationService` service to set the correlationId.
+To replace the id of the current context:
 
 ```ts
 this.correlationService.setCorrelationId('some_correlation_id');
 ```
 
-see [e2e tests](/test) for a fully working example
+It throws outside a correlation context, rather than writing somewhere nothing
+will read.
+
+See the [specs on GitHub](https://github.com/Evanion/libraries/tree/main/nest/correlation-id/src)
+for fully worked examples, including an end-to-end one that stands up a real
+Nest application.
 
 ## Change Log
 
@@ -144,7 +210,7 @@ See [Changelog](CHANGELOG.md) for more information.
 
 ## Contributing
 
-Contributions welcome! See [Contributing](CONTRIBUTING.md).
+Contributions welcome! See [Contributing](https://github.com/Evanion/libraries/blob/main/CONTRIBUTING.md).
 
 ## Author
 

package/dist/constants.d.ts

@@ -1,2 +1,17 @@
 export declare const CORRELATION_ID_HEADER = "X-Correlation-Id";
-export declare const CORRELATION_CONFIG_TOKEN = "CORRELATION_CONFIG";
+/**
+ * Namespaced because the provider is registered in a `global: true` module: a
+ * bare 'CORRELATION_CONFIG' would collide silently with any other package that
+ * happened to pick the same string. Deliberately a string and not a Symbol --
+ * a bare `Symbol()` is not stable across duplicate copies of a module, which
+ * would reintroduce exactly the hazard the single ESM build removes.
+ */
+export declare const CORRELATION_CONFIG_TOKEN = "@evanion/nestjs-correlation-id:CORRELATION_CONFIG";
+/**
+ * Token of the provider that attaches the outgoing-request interceptor to the
+ * axios instance `withCorrelation` configures. Nothing injects it; it exists so
+ * Nest instantiates the factory that registers the interceptor.
+ */
+export declare const CORRELATION_AXIOS_INTERCEPTOR = "@evanion/nestjs-correlation-id:AXIOS_INTERCEPTOR";
+export declare const DEFAULT_CORRELATION_ID_VALIDATOR: (value: string) => boolean;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,sDACgB,CAAC;AACtD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,qDACU,CAAC;AACrD,eAAO,MAAM,gCAAgC,GAAI,OAAO,MAAM,KAAG,OACjC,CAAC"}

package/dist/constants.js

@@ -1,5 +1,16 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CORRELATION_CONFIG_TOKEN = exports.CORRELATION_ID_HEADER = void 0;
-exports.CORRELATION_ID_HEADER = 'X-Correlation-Id';
-exports.CORRELATION_CONFIG_TOKEN = 'CORRELATION_CONFIG';
+export const CORRELATION_ID_HEADER = 'X-Correlation-Id';
+/**
+ * Namespaced because the provider is registered in a `global: true` module: a
+ * bare 'CORRELATION_CONFIG' would collide silently with any other package that
+ * happened to pick the same string. Deliberately a string and not a Symbol --
+ * a bare `Symbol()` is not stable across duplicate copies of a module, which
+ * would reintroduce exactly the hazard the single ESM build removes.
+ */
+export const CORRELATION_CONFIG_TOKEN = '@evanion/nestjs-correlation-id:CORRELATION_CONFIG';
+/**
+ * Token of the provider that attaches the outgoing-request interceptor to the
+ * axios instance `withCorrelation` configures. Nothing injects it; it exists so
+ * Nest instantiates the factory that registers the interceptor.
+ */
+export const CORRELATION_AXIOS_INTERCEPTOR = '@evanion/nestjs-correlation-id:AXIOS_INTERCEPTOR';
+export const DEFAULT_CORRELATION_ID_VALIDATOR = (value) => /^[\w.:-]{1,128}$/.test(value);

package/dist/correlation-id.middleware.d.ts

@@ -1,10 +1,11 @@
 import { NestMiddleware } from '@nestjs/common';
-import { Request, Response } from 'express';
-import { CorrelationService } from './correlation.service';
-import { CorrelationConfig } from './interfaces/correlation-config.interface';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { CorrelationService } from './correlation.service.js';
+import type { CorrelationConfig } from './interfaces/correlation-config.interface.js';
 export declare class CorrelationIdMiddleware implements NestMiddleware {
     private correlationService;
     private correlationConfig;
     constructor(correlationService: CorrelationService, correlationConfig: CorrelationConfig);
-    use(req: Request, res: Response, next: () => void): void;
+    use(req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void): void;
 }
+//# sourceMappingURL=correlation-id.middleware.d.ts.map

package/dist/correlation-id.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-id.middleware.d.ts","sourceRoot":"","sources":["../src/correlation-id.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAatF,qBACa,uBAAwB,YAAW,cAAc;IAE1D,OAAO,CAAC,kBAAkB;IAE1B,OAAO,CAAC,iBAAiB;gBAFjB,kBAAkB,EAAE,kBAAkB,EAEtC,iBAAiB,EAAE,iBAAiB;IAG9C,GAAG,CACD,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI;CAwBlC"}

package/dist/correlation-id.middleware.js

@@ -1,39 +1,45 @@
-"use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-var __param = (this && this.__param) || function (paramIndex, decorator) {
-    return function (target, key) { decorator(target, key, paramIndex); }
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CorrelationIdMiddleware = void 0;
-const common_1 = require("@nestjs/common");
-const constants_1 = require("./constants");
-const correlation_service_1 = require("./correlation.service");
-let CorrelationIdMiddleware = exports.CorrelationIdMiddleware = class CorrelationIdMiddleware {
+import { __decorate, __metadata, __param } from "tslib";
+import { Inject, Injectable } from '@nestjs/common';
+import { CORRELATION_CONFIG_TOKEN, DEFAULT_CORRELATION_ID_VALIDATOR } from './constants.js';
+import { CorrelationService } from './correlation.service.js';
+/**
+ * Node normalises repeated request headers into a single comma-joined string
+ * for everything except set-cookie, which stays an array. Joining an array the
+ * same way keeps both shapes on one code path -- and the default validator
+ * rejects the result, which is the wanted behaviour for a duplicated
+ * correlation id.
+ */
+const singleValue = (value) => (Array.isArray(value) ? value.join(', ') : value);
+let CorrelationIdMiddleware = class CorrelationIdMiddleware {
+    correlationService;
+    correlationConfig;
     constructor(correlationService, correlationConfig) {
         this.correlationService = correlationService;
         this.correlationConfig = correlationConfig;
     }
     use(req, res, next) {
-        const { header } = this.correlationConfig;
-        const correlationId = req.get(header) || this.correlationService.getCorrelationId();
-        if (!req.headers[header])
-            req.headers[header] = correlationId;
-        if (!res.get(header))
-            res.set(header, correlationId);
-        this.correlationService.setCorrelationId(correlationId);
-        next();
+        const { header, validate = DEFAULT_CORRELATION_ID_VALIDATOR, } = this.correlationConfig;
+        const key = header.toLowerCase();
+        const incoming = singleValue(req.headers[key]);
+        // The generator runs only when nothing usable arrived, so a counter- or
+        // sequence-backed generator is not advanced for an id that gets discarded.
+        const correlationId = incoming && validate(incoming)
+            ? incoming
+            : this.correlationService.generate();
+        if (!req.headers[key])
+            req.headers[key] = correlationId;
+        // setHeader preserves the casing it is given, so the configured casing is
+        // what goes out on the wire.
+        if (res.getHeader(header) === undefined)
+            res.setHeader(header, correlationId);
+        // Everything downstream of next() -- guards, interceptors, the controller,
+        // and anything they await -- runs inside this context.
+        this.correlationService.run(correlationId, next);
     }
 };
-exports.CorrelationIdMiddleware = CorrelationIdMiddleware = __decorate([
-    (0, common_1.Injectable)(),
-    __param(1, (0, common_1.Inject)(constants_1.CORRELATION_CONFIG_TOKEN)),
-    __metadata("design:paramtypes", [correlation_service_1.CorrelationService, Object])
+CorrelationIdMiddleware = __decorate([
+    Injectable(),
+    __param(1, Inject(CORRELATION_CONFIG_TOKEN)),
+    __metadata("design:paramtypes", [CorrelationService, Object])
 ], CorrelationIdMiddleware);
+export { CorrelationIdMiddleware };

package/dist/correlation.module.d.ts

@@ -1,5 +1,6 @@
 import { DynamicModule } from '@nestjs/common';
-import { CorrelationConfig } from './interfaces/correlation-config.interface';
+import type { CorrelationConfig } from './interfaces/correlation-config.interface.js';
 export declare class CorrelationModule {
     static forRoot(config?: Partial<CorrelationConfig>): DynamicModule;
 }
+//# sourceMappingURL=correlation.module.d.ts.map

package/dist/correlation.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.module.d.ts","sourceRoot":"","sources":["../src/correlation.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,gBAAgB,CAAC;AAUjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAEtF,qBACa,iBAAiB;IAC5B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,aAAa;CAiBnE"}

package/dist/correlation.module.js

@@ -1,31 +1,29 @@
-"use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
 var CorrelationModule_1;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CorrelationModule = void 0;
-const common_1 = require("@nestjs/common");
-const uuid_1 = require("uuid");
-const constants_1 = require("./constants");
-const correlation_service_1 = require("./correlation.service");
-let CorrelationModule = exports.CorrelationModule = CorrelationModule_1 = class CorrelationModule {
+import { __decorate } from "tslib";
+import { Module } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+import { CORRELATION_CONFIG_TOKEN, CORRELATION_ID_HEADER, DEFAULT_CORRELATION_ID_VALIDATOR, } from './constants.js';
+import { CorrelationService } from './correlation.service.js';
+let CorrelationModule = CorrelationModule_1 = class CorrelationModule {
     static forRoot(config) {
         const correlationConfigProvider = {
-            provide: constants_1.CORRELATION_CONFIG_TOKEN,
-            useValue: Object.assign(Object.assign({}, config), { header: (config === null || config === void 0 ? void 0 : config.header) || constants_1.CORRELATION_ID_HEADER, generator: (config === null || config === void 0 ? void 0 : config.generator) || uuid_1.v4 }),
+            provide: CORRELATION_CONFIG_TOKEN,
+            useValue: {
+                ...config,
+                header: config?.header || CORRELATION_ID_HEADER,
+                generator: config?.generator || randomUUID,
+                validate: config?.validate || DEFAULT_CORRELATION_ID_VALIDATOR,
+            },
         };
         return {
             global: true,
             module: CorrelationModule_1,
-            providers: [correlationConfigProvider, correlation_service_1.CorrelationService],
-            exports: [correlationConfigProvider, correlation_service_1.CorrelationService],
+            providers: [correlationConfigProvider, CorrelationService],
+            exports: [correlationConfigProvider, CorrelationService],
         };
     }
 };
-exports.CorrelationModule = CorrelationModule = CorrelationModule_1 = __decorate([
-    (0, common_1.Module)({})
+CorrelationModule = CorrelationModule_1 = __decorate([
+    Module({})
 ], CorrelationModule);
+export { CorrelationModule };

package/dist/correlation.service.d.ts

@@ -1,7 +1,38 @@
-import { CorrelationConfig } from './interfaces/correlation-config.interface';
+import type { CorrelationConfig } from './interfaces/correlation-config.interface.js';
+/**
+ * A plain singleton over AsyncLocalStorage.
+ *
+ * It used to be `@Injectable({ scope: Scope.REQUEST })`. Nest propagates scope
+ * upward through the injection graph, so every provider that reached this one
+ * -- including `HttpService`, via `withCorrelation` -- silently became
+ * request-scoped: re-instantiated per request, and never given `onModuleInit`.
+ * AsyncLocalStorage gives the same per-request isolation with none of that.
+ */
 export declare class CorrelationService {
-    private correlationId;
+    private readonly correlationConfig;
+    private readonly storage;
     constructor(correlationConfig: CorrelationConfig);
-    getCorrelationId(): string;
+    /**
+     * Runs `callback` in a correlation context. Everything it awaits, schedules
+     * or calls sees `correlationId`, and overlapping contexts stay isolated.
+     *
+     * The middleware does this per request. Call it directly for work that has no
+     * request behind it -- queue consumers, cron jobs, scripts.
+     */
+    run<T>(correlationId: string, callback: () => T): T;
+    /**
+     * The id of the surrounding correlation context, or `undefined` when there is
+     * none. Outside a context there is genuinely no correlation id, so this does
+     * not invent one.
+     */
+    getCorrelationId(): string | undefined;
+    /** Replaces the id of the surrounding correlation context. */
     setCorrelationId(correlationId: string): void;
+    /**
+     * A fresh id from the configured generator. Called only when no usable id
+     * arrived with the request, so a counter- or sequence-backed generator is not
+     * advanced for ids that get discarded.
+     */
+    generate(): string;
 }
+//# sourceMappingURL=correlation.service.d.ts.map

package/dist/correlation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.service.d.ts","sourceRoot":"","sources":["../src/correlation.service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAMtF;;;;;;;;GAQG;AACH,qBACa,kBAAkB;IAK3B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAJpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6C;gBAIlD,iBAAiB,EAAE,iBAAiB;IAGvD;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;IAInD;;;;OAIG;IACH,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAItC,8DAA8D;IAC9D,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAU7C;;;;OAIG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/correlation.service.js

@@ -1,36 +1,60 @@
-"use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-var __param = (this && this.__param) || function (paramIndex, decorator) {
-    return function (target, key) { decorator(target, key, paramIndex); }
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CorrelationService = void 0;
-const common_1 = require("@nestjs/common");
-const uuid_1 = require("uuid");
-const constants_1 = require("./constants");
-let CorrelationService = exports.CorrelationService = class CorrelationService {
+import { __decorate, __metadata, __param } from "tslib";
+import { Inject, Injectable } from '@nestjs/common';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { CORRELATION_CONFIG_TOKEN } from './constants.js';
+/**
+ * A plain singleton over AsyncLocalStorage.
+ *
+ * It used to be `@Injectable({ scope: Scope.REQUEST })`. Nest propagates scope
+ * upward through the injection graph, so every provider that reached this one
+ * -- including `HttpService`, via `withCorrelation` -- silently became
+ * request-scoped: re-instantiated per request, and never given `onModuleInit`.
+ * AsyncLocalStorage gives the same per-request isolation with none of that.
+ */
+let CorrelationService = class CorrelationService {
+    correlationConfig;
+    storage = new AsyncLocalStorage();
     constructor(correlationConfig) {
-        this.correlationId = correlationConfig.generator
-            ? correlationConfig.generator()
-            : (0, uuid_1.v4)();
+        this.correlationConfig = correlationConfig;
     }
+    /**
+     * Runs `callback` in a correlation context. Everything it awaits, schedules
+     * or calls sees `correlationId`, and overlapping contexts stay isolated.
+     *
+     * The middleware does this per request. Call it directly for work that has no
+     * request behind it -- queue consumers, cron jobs, scripts.
+     */
+    run(correlationId, callback) {
+        return this.storage.run({ correlationId }, callback);
+    }
+    /**
+     * The id of the surrounding correlation context, or `undefined` when there is
+     * none. Outside a context there is genuinely no correlation id, so this does
+     * not invent one.
+     */
     getCorrelationId() {
-        return this.correlationId;
+        return this.storage.getStore()?.correlationId;
     }
+    /** Replaces the id of the surrounding correlation context. */
     setCorrelationId(correlationId) {
-        this.correlationId = correlationId;
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error('setCorrelationId() was called outside a correlation context. Apply CorrelationIdMiddleware, or wrap the work in CorrelationService.run().');
+        }
+        store.correlationId = correlationId;
+    }
+    /**
+     * A fresh id from the configured generator. Called only when no usable id
+     * arrived with the request, so a counter- or sequence-backed generator is not
+     * advanced for ids that get discarded.
+     */
+    generate() {
+        return this.correlationConfig.generator();
     }
 };
-exports.CorrelationService = CorrelationService = __decorate([
-    (0, common_1.Injectable)({ scope: common_1.Scope.REQUEST }),
-    __param(0, (0, common_1.Inject)(constants_1.CORRELATION_CONFIG_TOKEN)),
+CorrelationService = __decorate([
+    Injectable(),
+    __param(0, Inject(CORRELATION_CONFIG_TOKEN)),
     __metadata("design:paramtypes", [Object])
 ], CorrelationService);
+export { CorrelationService };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export * from './correlation-id.middleware';
-export * from './correlation.service';
-export * from './correlation.module';
-export * from './withCorrelation.function';
-export * from './constants';
+export * from './correlation-id.middleware.js';
+export * from './correlation.service.js';
+export * from './correlation.module.js';
+export * from './withCorrelation.function.js';
+export * from './constants.js';
+export * from './interfaces/correlation-config.interface.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8CAA8C,CAAC"}