@pristine-ts/common 2.0.2 → 2.0.3

package/dist/lib/cjs/common.module.js

@@ -20,6 +20,7 @@ __exportStar(require("./contexts/contexts"), exports);
 __exportStar(require("./decorators/decorators"), exports);
 __exportStar(require("./enums/enums"), exports);
 __exportStar(require("./errors/errors"), exports);
+__exportStar(require("./managers/managers"), exports);
 __exportStar(require("./models/models"), exports);
 __exportStar(require("./interfaces/interfaces"), exports);
 __exportStar(require("./types/types"), exports);

package/dist/lib/cjs/common.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.module.js","sourceRoot":"","sources":["../../../src/common.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mEAA4D;AAG5D,sDAAoC;AACpC,0DAAwC;AACxC,gDAA8B;AAC9B,kDAAgC;AAChC,kDAAgC;AAChC,0DAAwC;AACxC,gDAA8B;AAC9B,gDAA8B;AAC9B,0DAAwC;AAE3B,QAAA,YAAY,GAAoB;IAC3C,OAAO,EAAE,2CAAmB;IAC5B,aAAa,EAAE,EAAE;IACjB,qBAAqB,EAAE,EAAE;CAC1B,CAAA"}
+{"version":3,"file":"common.module.js","sourceRoot":"","sources":["../../../src/common.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mEAA4D;AAG5D,sDAAoC;AACpC,0DAAwC;AACxC,gDAA8B;AAC9B,kDAAgC;AAChC,sDAAoC;AACpC,kDAAgC;AAChC,0DAAwC;AACxC,gDAA8B;AAC9B,gDAA8B;AAC9B,0DAAwC;AAE3B,QAAA,YAAY,GAAoB;IAC3C,OAAO,EAAE,2CAAmB;IAC5B,aAAa,EAAE,EAAE;IACjB,qBAAqB,EAAE,EAAE;CAC1B,CAAA"}

package/dist/lib/cjs/contexts/contexts.js

@@ -14,5 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./event-context"), exports);
 __exportStar(require("./tracing.context"), exports);
 //# sourceMappingURL=contexts.js.map

package/dist/lib/cjs/contexts/contexts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contexts.js","sourceRoot":"","sources":["../../../../src/contexts/contexts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC"}
+{"version":3,"file":"contexts.js","sourceRoot":"","sources":["../../../../src/contexts/contexts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,oDAAkC"}

package/dist/lib/cjs/contexts/event-context.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventContext = void 0;
+/**
+ * Per-event runtime state — the framework's correlation primitives plus a handle to
+ * the per-event DI child container. Propagated implicitly via `AsyncLocalStorage`
+ * (managed by `EventContextManager`) so downstream code doesn't have to thread these
+ * fields through every method signature.
+ *
+ * **Not to be confused with `ExecutionContextInterface` (in `@pristine-ts/core`):**
+ *   - `ExecutionContext` describes *where* the framework is running (AWS Lambda, CLI,
+ *     Express, etc.) — set once per `kernel.handle()` call, immutable, host-shaped.
+ *   - `EventContext` describes *which specific event* is being handled — set per event
+ *     in the pipeline, mutable (`traceId` fills in once tracing starts), correlation-
+ *     shaped.
+ *
+ * One `kernel.handle()` call can produce multiple events (each event mapper can return
+ * a list); each event gets its own `EventContext` instance.
+ */
+class EventContext {
+}
+exports.EventContext = EventContext;
+//# sourceMappingURL=event-context.js.map

package/dist/lib/cjs/contexts/event-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-context.js","sourceRoot":"","sources":["../../../../src/contexts/event-context.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,YAAY;CAYxB;AAZD,oCAYC"}

package/dist/lib/cjs/contexts/tracing.context.js

@@ -9,6 +9,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TracingContext = void 0;
 require("reflect-metadata");
 const tsyringe_1 = require("tsyringe");
+/**
+ * @deprecated Read the trace id from the active `EventContext` instead:
+ *
+ * ```ts
+ * import {EventContextManager} from "@pristine-ts/common";
+ *
+ * const traceId = EventContextManager.traceId();
+ * ```
+ *
+ * `TracingContext` predates the `AsyncLocalStorage`-backed `EventContext` and survives
+ * only as a back-compat shim. `TracingManager.startTracing()` still mirrors the trace id
+ * into this class so existing consumers keep working, but new code should read from
+ * `EventContextManager`. This class will be removed in a future major.
+ */
 let TracingContext = class TracingContext {
 };
 exports.TracingContext = TracingContext;

package/dist/lib/cjs/contexts/tracing.context.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.context.js","sourceRoot":"","sources":["../../../../src/contexts/tracing.context.ts"],"names":[],"mappings":";;;;;;;;;AAAA,4BAA0B;AAC1B,uCAAuD;AAIhD,IAAM,cAAc,GAApB,MAAM,cAAc;CAE1B,CAAA;AAFY,wCAAc;yBAAd,cAAc;IAF1B,IAAA,qBAAU,GAAE;IACZ,IAAA,iBAAM,EAAC,oBAAS,CAAC,eAAe,CAAC;GACrB,cAAc,CAE1B"}
+{"version":3,"file":"tracing.context.js","sourceRoot":"","sources":["../../../../src/contexts/tracing.context.ts"],"names":[],"mappings":";;;;;;;;;AAAA,4BAA0B;AAC1B,uCAAuD;AAEvD;;;;;;;;;;;;;GAaG;AAGI,IAAM,cAAc,GAApB,MAAM,cAAc;CAE1B,CAAA;AAFY,wCAAc;yBAAd,cAAc;IAF1B,IAAA,qBAAU,GAAE;IACZ,IAAA,iBAAM,EAAC,oBAAS,CAAC,eAAe,CAAC;GACrB,cAAc,CAE1B"}

package/dist/lib/cjs/managers/event-context.manager.js

@@ -0,0 +1,107 @@
+"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 EventContextManager_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventContextManager = void 0;
+const async_hooks_1 = require("async_hooks");
+const tsyringe_1 = require("tsyringe");
+/**
+ * Owns the `AsyncLocalStorage` instance that propagates the active `EventContext`
+ * across `await` boundaries, `Promise.all`, `setImmediate`, and the rest of Node's
+ * async machinery. Provides:
+ *
+ *   - `run(ctx, fn)` — install the context for the duration of `fn`. **Framework-only**;
+ *     normal application code never calls this. Pristine's event pipeline calls it once
+ *     per event.
+ *   - Read accessors — `current()`, `eventId()`, `traceId()`, `container()`. Available
+ *     as instance methods (DI-resolved) and as static convenience methods.
+ *   - `bind(fn)` — escape hatch for background work that breaks the natural async
+ *     chain (raw `setImmediate`, `EventEmitter`-based code, certain native modules).
+ *     Captures the current context and returns a wrapped function that restores it
+ *     on call.
+ *
+ * Why static state inside an `@injectable()` class: the `AsyncLocalStorage` instance
+ * itself must be a single process-wide singleton — multiple instances would each track
+ * their own propagation chain and contexts wouldn't be visible across them. Making the
+ * ALS `private static readonly` while keeping the class `@injectable()` lets DI consumers
+ * resolve it normally (and substitute fakes in tests) while the underlying state stays
+ * shared and consistent.
+ */
+let EventContextManager = EventContextManager_1 = class EventContextManager {
+    run(ctx, fn) {
+        return EventContextManager_1.als.run(ctx, fn);
+    }
+    /** Returns the active `EventContext`, or `undefined` if no context is installed
+     *  (i.e. we're outside any `run()` call). */
+    current() {
+        return EventContextManager_1.als.getStore();
+    }
+    /** Convenience: the `eventId` of the active context, or `undefined`. */
+    eventId() {
+        var _a;
+        return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.eventId;
+    }
+    /** Convenience: the `traceId` of the active context, or `undefined`. */
+    traceId() {
+        var _a;
+        return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.traceId;
+    }
+    /** Convenience: the per-event DI child container, or `undefined`. */
+    container() {
+        var _a;
+        return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.container;
+    }
+    /**
+     * Returns a wrapped version of `fn` that restores the current context on call. Use
+     * when you need to spawn work that escapes the natural async chain (e.g. a callback
+     * registered with a third-party `EventEmitter`, or a `setImmediate` whose callback
+     * runs after the parent function returned). Without `bind`, that work would see no
+     * context.
+     *
+     * If no context is active when `bind` is called, returns `fn` unchanged.
+     */
+    bind(fn) {
+        const ctx = this.current();
+        if (ctx === undefined)
+            return fn;
+        const als = EventContextManager_1.als;
+        return ((...args) => als.run(ctx, () => fn(...args)));
+    }
+    // ── Static convenience mirrors. ────────────────────────────────────────────────
+    // For callers that don't want DI noise (e.g. utility code, decorators, helpers
+    // that don't have a constructor to inject through). All forwarding to the same
+    // shared ALS instance.
+    static current() {
+        return EventContextManager_1.als.getStore();
+    }
+    static eventId() {
+        var _a;
+        return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.eventId;
+    }
+    static traceId() {
+        var _a;
+        return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.traceId;
+    }
+    static container() {
+        var _a;
+        return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.container;
+    }
+    static bind(fn) {
+        const ctx = EventContextManager_1.current();
+        if (ctx === undefined)
+            return fn;
+        const als = EventContextManager_1.als;
+        return ((...args) => als.run(ctx, () => fn(...args)));
+    }
+};
+exports.EventContextManager = EventContextManager;
+EventContextManager.als = new async_hooks_1.AsyncLocalStorage();
+exports.EventContextManager = EventContextManager = EventContextManager_1 = __decorate([
+    (0, tsyringe_1.injectable)()
+], EventContextManager);
+//# sourceMappingURL=event-context.manager.js.map

package/dist/lib/cjs/managers/event-context.manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-context.manager.js","sourceRoot":"","sources":["../../../../src/managers/event-context.manager.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,6CAA8C;AAC9C,uCAAyD;AAGzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEI,IAAM,mBAAmB,2BAAzB,MAAM,mBAAmB;IAU9B,GAAG,CAAI,GAAiB,EAAE,EAAwB;QAChD,OAAO,qBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED;iDAC6C;IAC7C,OAAO;QACL,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,qEAAqE;IACrE,SAAS;;QACP,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IACnC,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CAAoC,EAAK;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;IAED,kFAAkF;IAClF,+EAA+E;IAC/E,+EAA+E;IAC/E,uBAAuB;IAEvB,MAAM,CAAC,OAAO;QACZ,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,SAAS;;QACd,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,IAAI,CAAoC,EAAK;QAClD,MAAM,GAAG,GAAG,qBAAmB,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;;AA7EU,kDAAmB;AACN,uBAAG,GAAG,IAAI,+BAAiB,EAAgB,AAAxC,CAAyC;8BADzD,mBAAmB;IAD/B,IAAA,qBAAU,GAAE;GACA,mBAAmB,CA8E/B"}

package/dist/lib/cjs/managers/managers.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./event-context.manager"), exports);
+//# sourceMappingURL=managers.js.map

package/dist/lib/cjs/managers/managers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managers.js","sourceRoot":"","sources":["../../../../src/managers/managers.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC"}