@pristine-ts/common 2.0.2 → 2.0.4

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * Per-event runtime state — the framework's correlation primitives plus a handle to
+ * the per-event DI child container and the active trace. 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` / `trace` fill 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.
+ */
+export class EventContext {
+}
+//# sourceMappingURL=event-context.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-context.js","sourceRoot":"","sources":["../../../../src/contexts/event-context.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,YAAY;CAmBxB"}

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

@@ -6,6 +6,20 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import "reflect-metadata";
 import { injectable, Lifecycle, scoped } from "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 {
 };
 TracingContext = __decorate([

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

@@ -1 +1 @@
-{"version":3,"file":"tracing.context.js","sourceRoot":"","sources":["../../../../src/contexts/tracing.context.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,MAAM,EAAC,MAAM,UAAU,CAAC;AAIhD,IAAM,cAAc,GAApB,MAAM,cAAc;CAE1B,CAAA;AAFY,cAAc;IAF1B,UAAU,EAAE;IACZ,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC;GACrB,cAAc,CAE1B"}
+{"version":3,"file":"tracing.context.js","sourceRoot":"","sources":["../../../../src/contexts/tracing.context.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,MAAM,EAAC,MAAM,UAAU,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AAGI,IAAM,cAAc,GAApB,MAAM,cAAc;CAE1B,CAAA;AAFY,cAAc;IAF1B,UAAU,EAAE;IACZ,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC;GACrB,cAAc,CAE1B"}

package/dist/lib/esm/decorators/decorators.js

@@ -1,4 +1,5 @@
 export * from './inject-config.decorator';
 export * from './module-scoped.decorator';
 export * from './tag.decorator';
+export * from './traced.decorator';
 //# sourceMappingURL=decorators.js.map

package/dist/lib/esm/decorators/decorators.js.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../src/decorators/decorators.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../src/decorators/decorators.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/lib/esm/decorators/traced.decorator.js

@@ -0,0 +1,62 @@
+import { spanRunner } from "../utils/span-runner";
+/**
+ * Method decorator that wraps the decorated method in a span. The span is automatically
+ * ended when the method returns or throws, and the `TracingManager` is auto-resolved
+ * from the active `EventContext` — no need to inject it manually.
+ *
+ * ```ts
+ * class PaymentService {
+ *   @traced()                                // span name = "PaymentService.charge"
+ *   async charge(amount: number) { ... }
+ *
+ *   @traced("payment.refund.action")         // explicit name
+ *   async refund(chargeId: string) { ... }
+ * }
+ * ```
+ *
+ * **Behavior outside an event context.** When the decorated method runs without an
+ * active `EventContext` (e.g. a unit test calling the method directly, or background
+ * work that escaped the event lifecycle), the decorator is a no-op — the original
+ * method runs unchanged. Tracing must never throw or alter semantics.
+ *
+ * **Sync methods become async.** The decorator awaits the wrapped method internally,
+ * so any decorated method returns a `Promise`. Decorating a sync method changes its
+ * signature visible to callers — apply `@traced` to methods you'd already be awaiting
+ * (DB calls, HTTP, expensive computations), not to tight sync helpers.
+ *
+ * **Type-level caveat.** TypeScript's parameter and method decorator types don't carry
+ * enough information for the compiler to verify that the wrapped method's return type
+ * is compatible with `Promise<T>`. The wrapper is type-safe at runtime; the call site's
+ * static types are unchanged. Pair with explicit `: Promise<T>` annotations on the
+ * method when you want the static type to match what's actually returned.
+ *
+ * **Lives in `@pristine-ts/common`** so any package can use it without taking a direct
+ * dep on `@pristine-ts/telemetry`. The actual `TracingManager` implementation still
+ * lives in telemetry; this decorator only reads the active manager from the
+ * EventContext when one is present.
+ *
+ * @param spanName Optional explicit name for the span. Defaults to
+ *   `${ClassName}.${methodName}`.
+ */
+export function traced(spanName) {
+    return (target, propertyKey, descriptor) => {
+        var _a, _b, _c;
+        const original = descriptor.value;
+        if (typeof original !== "function") {
+            // Decorator was applied to something other than a method (a getter, a property
+            // with no initial value, etc.). Leave it alone — silently no-op rather than
+            // throw at decoration time.
+            return descriptor;
+        }
+        // Resolve a stable default name at decoration time. `target.constructor.name` is
+        // the class name for instance methods; for static methods, `target.name` is the
+        // class. We cover both via the fallback chain.
+        const className = (_c = (_b = (_a = target === null || target === void 0 ? void 0 : target.constructor) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : target === null || target === void 0 ? void 0 : target.name) !== null && _c !== void 0 ? _c : "anonymous";
+        const resolvedName = spanName !== null && spanName !== void 0 ? spanName : `${className}.${String(propertyKey)}`;
+        descriptor.value = function (...args) {
+            return spanRunner.runWithSpan(resolvedName, () => original.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=traced.decorator.js.map

package/dist/lib/esm/decorators/traced.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traced.decorator.js","sourceRoot":"","sources":["../../../../src/decorators/traced.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,MAAM,CAAC,QAAiB;IACtC,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;;QACnF,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,+EAA+E;YAC/E,4EAA4E;YAC5E,4BAA4B;YAC5B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,iFAAiF;QACjF,gFAAgF;QAChF,+CAA+C;QAC/C,MAAM,SAAS,GAAW,MAAA,MAAA,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,0CAAE,IAAI,mCAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,WAAW,CAAC;QACnF,MAAM,YAAY,GAAG,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,GAAG,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAEvE,UAAU,CAAC,KAAK,GAAG,UAAyB,GAAG,IAAW;YACxD,OAAO,UAAU,CAAC,WAAW,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAChF,CAAC,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/esm/enums/enums.js

@@ -2,4 +2,5 @@ export * from "./http-method.enum";
 export * from "./internal-container-parameter.enum";
 export * from "./metadata.enum";
 export * from "./service-definition-tag.enum";
+export * from "./span-keyname.enum";
 //# sourceMappingURL=enums.js.map

package/dist/lib/esm/enums/enums.js.map

@@ -1 +1 @@
-{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../../src/enums/enums.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qCAAqC,CAAC;AACpD,cAAc,iBAAiB,CAAC;AAChC,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../../src/enums/enums.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qCAAqC,CAAC;AACpD,cAAc,iBAAiB,CAAC;AAChC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC"}

package/dist/lib/esm/enums/span-keyname.enum.js

@@ -0,0 +1,31 @@
+/**
+ * This enum is for the different span names that are integrated in Pristine.
+ */
+export var SpanKeynameEnum;
+(function (SpanKeynameEnum) {
+    SpanKeynameEnum["ChildContainerCreation"] = "child.container.creation";
+    SpanKeynameEnum["ChildContainerRegistration"] = "child.container.registration";
+    SpanKeynameEnum["ConfigurationInitialization"] = "configuration.initialization";
+    SpanKeynameEnum["ErrorResponseInterceptors"] = "error.response.interceptors";
+    SpanKeynameEnum["EventDispatcherResolver"] = "event.dispatcher.resolver";
+    SpanKeynameEnum["EventExecution"] = "event.execution";
+    SpanKeynameEnum["EventInitialization"] = "event.initialization";
+    SpanKeynameEnum["EventPreMappingInterception"] = "event.pre-mapping.interception";
+    SpanKeynameEnum["EventPostMappingInterception"] = "event.post-mapping.interception";
+    SpanKeynameEnum["EventPreResponseMappingInterception"] = "event.pre-response-mapping.interception";
+    SpanKeynameEnum["EventPostResponseMappingInterception"] = "event.post-response-mapping.interception";
+    SpanKeynameEnum["EventMapping"] = "event.mapping";
+    SpanKeynameEnum["KernelInitialization"] = "kernel.initialization";
+    SpanKeynameEnum["ModuleInitialization"] = "module.initialization";
+    SpanKeynameEnum["ModuleInitializationImportModules"] = "module.initialization.import.modules";
+    SpanKeynameEnum["RequestExecution"] = "request.execution";
+    SpanKeynameEnum["RequestInterceptors"] = "request.interceptors";
+    SpanKeynameEnum["ResponseInterceptors"] = "response.interceptors";
+    SpanKeynameEnum["RootExecution"] = "root.execution";
+    SpanKeynameEnum["RouterControllerResolver"] = "router.controller.resolver";
+    SpanKeynameEnum["RouterFindMethodRouterNode"] = "router.find.method.router.node";
+    SpanKeynameEnum["RouterRequestAuthentication"] = "router.request.authentication";
+    SpanKeynameEnum["RouterRequestExecution"] = "router.request.execution";
+    SpanKeynameEnum["RouterSetup"] = "router.setup";
+})(SpanKeynameEnum || (SpanKeynameEnum = {}));
+//# sourceMappingURL=span-keyname.enum.js.map

package/dist/lib/esm/enums/span-keyname.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-keyname.enum.js","sourceRoot":"","sources":["../../../../src/enums/span-keyname.enum.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,eAyBX;AAzBD,WAAY,eAAe;IACzB,sEAAmD,CAAA;IACnD,8EAA2D,CAAA;IAC3D,+EAA4D,CAAA;IAC5D,4EAAyD,CAAA;IACzD,wEAAqD,CAAA;IACrD,qDAAkC,CAAA;IAClC,+DAA4C,CAAA;IAC5C,iFAA8D,CAAA;IAC9D,mFAAgE,CAAA;IAChE,kGAA+E,CAAA;IAC/E,oGAAiF,CAAA;IACjF,iDAA8B,CAAA;IAC9B,iEAA8C,CAAA;IAC9C,iEAA8C,CAAA;IAC9C,6FAA0E,CAAA;IAC1E,yDAAsC,CAAA;IACtC,+DAA4C,CAAA;IAC5C,iEAA8C,CAAA;IAC9C,mDAAgC,CAAA;IAChC,0EAAuD,CAAA;IACvD,gFAA6D,CAAA;IAC7D,gFAA6D,CAAA;IAC7D,sEAAmD,CAAA;IACnD,+CAA4B,CAAA;AAC9B,CAAC,EAzBW,eAAe,KAAf,eAAe,QAyB1B"}

package/dist/lib/esm/interfaces/interfaces.js

@@ -9,5 +9,6 @@ export * from "./module-scoped-registration.interface";
 export * from "./resolver.interface";
 export * from "./tagged-registration.interface";
 export * from "./token-provider-registration.interface";
+export * from "./tracing-manager.interface";
 export * from "./value-provider-registration.interface";
 //# sourceMappingURL=interfaces.js.map

package/dist/lib/esm/interfaces/interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../../src/interfaces/interfaces.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yCAAyC,CAAC;AACxD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wCAAwC,CAAC;AACvD,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,yCAAyC,CAAC"}
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../../src/interfaces/interfaces.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yCAAyC,CAAC;AACxD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wCAAwC,CAAC;AACvD,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yCAAyC,CAAC"}

package/dist/lib/esm/interfaces/tracing-manager.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tracing-manager.interface.js.map

package/dist/lib/esm/interfaces/tracing-manager.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-manager.interface.js","sourceRoot":"","sources":["../../../../src/interfaces/tracing-manager.interface.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,104 @@
+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;
+import { AsyncLocalStorage } from "async_hooks";
+import { injectable } from "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)));
+    }
+};
+EventContextManager.als = new AsyncLocalStorage();
+EventContextManager = EventContextManager_1 = __decorate([
+    injectable()
+], EventContextManager);
+export { EventContextManager };
+//# sourceMappingURL=event-context.manager.js.map

package/dist/lib/esm/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,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAsB,UAAU,EAAC,MAAM,UAAU,CAAC;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;;AA5EuB,uBAAG,GAAG,IAAI,iBAAiB,EAAgB,AAAxC,CAAyC;AADzD,mBAAmB;IAD/B,UAAU,EAAE;GACA,mBAAmB,CA8E/B"}

package/dist/lib/esm/managers/managers.js

@@ -0,0 +1,2 @@
+export * from "./event-context.manager";
+//# sourceMappingURL=managers.js.map

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

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

package/dist/lib/esm/models/models.js

@@ -1,3 +1,6 @@
 export * from "./request";
 export * from "./response";
+export * from "./span-event.model";
+export * from "./span.model";
+export * from "./trace.model";
 //# sourceMappingURL=models.js.map

package/dist/lib/esm/models/models.js.map

@@ -1 +1 @@
-{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../src/models/models.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../src/models/models.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/lib/esm/models/span-event.model.js

@@ -0,0 +1,24 @@
+/**
+ * A named, timestamped marker attached to a `Span`. Represents a noteworthy moment
+ * inside the span's lifetime that doesn't warrant a child span of its own — e.g.
+ * "validation passed", "rate limit check ok", "found 50 rows in DB".
+ *
+ * Modeled after OpenTelemetry's "span events" concept: a `Span` carries `events: SpanEvent[]`
+ * alongside its `children: Span[]`. Renderers (the console/file tracer output, etc.) interleave
+ * events with spans by timestamp to produce a chronological trail of what happened during the span.
+ *
+ * Use `TracingManager.addEventToCurrentSpan(message, attributes?)` to add one — it finds
+ * the most-recently-started in-progress span and attaches the event there.
+ */
+export class SpanEvent {
+    constructor(message, attributes) {
+        this.message = message;
+        /**
+         * The timestamp in milliseconds at which the event was created. Used to interleave
+         * events with sibling spans when rendering a sorted trail.
+         */
+        this.timestamp = Date.now();
+        this.attributes = attributes;
+    }
+}
+//# sourceMappingURL=span-event.model.js.map

package/dist/lib/esm/models/span-event.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-event.model.js","sourceRoot":"","sources":["../../../../src/models/span-event.model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,SAAS;IAapB,YAA4B,OAAe,EAAE,UAAsC;QAAvD,YAAO,GAAP,OAAO,CAAQ;QAZ3C;;;WAGG;QACa,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAS7C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}

package/dist/lib/esm/models/span.model.js

@@ -0,0 +1,75 @@
+import { randomUUID } from "crypto";
+/**
+ * This model represents a span.
+ */
+export class Span {
+    /**
+     * This model represents a span.
+     * @param keyname The keyname of the span.
+     * @param id The unique id of the span.
+     * @param context The context to associate with the span.
+     */
+    constructor(keyname, id, context) {
+        this.keyname = keyname;
+        /**
+         * The timestamp in milliseconds at which the span was started.
+         */
+        this.startDate = Date.now();
+        /**
+         * The children spans.
+         */
+        this.children = [];
+        /**
+         * Named, timestamped markers attached to this span. Use these for noteworthy moments
+         * inside the span's lifetime that don't warrant their own child span — e.g.
+         * "validation passed", "found 50 rows in DB". Empty by default; populated by
+         * `TracingManager.addEventToCurrentSpan(...)`.
+         */
+        this.events = [];
+        /**
+         * The context associated with the span.
+         */
+        this.context = {};
+        /**
+         * Whether or not the span is in progress, meaning it has not ended.
+         */
+        this.inProgress = true;
+        this.id = id !== null && id !== void 0 ? id : randomUUID();
+        this.context = context !== null && context !== void 0 ? context : {};
+    }
+    /**
+     * This method returns the duration of the span in milliseconds.
+     */
+    getDuration() {
+        var _a;
+        return ((_a = this.endDate) !== null && _a !== void 0 ? _a : Date.now()) - this.startDate;
+    }
+    /**
+     * This method ends the span.
+     */
+    end() {
+        var _a;
+        (_a = this.tracingManager) === null || _a === void 0 ? void 0 : _a.endSpan(this);
+    }
+    /**
+     * This method sets the trace for the span and all of its children.
+     * @param trace The trace the span should be attached to.
+     */
+    setTrace(trace) {
+        this.trace = trace;
+        this.children.forEach(childSpan => childSpan.setTrace(trace));
+    }
+    /**
+     * This method adds a child span to the current span. It only adds it if it's not already part of the children.
+     * @param span The span to add as a child.
+     */
+    addChild(span) {
+        const existingChildSpan = this.children.find(childSpan => childSpan.id === span.id);
+        if (existingChildSpan) {
+            return;
+        }
+        span.parentSpan = this;
+        this.children.push(span);
+    }
+}
+//# sourceMappingURL=span.model.js.map

package/dist/lib/esm/models/span.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.model.js","sourceRoot":"","sources":["../../../../src/models/span.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAC;AAclC;;GAEG;AACH,MAAM,OAAO,IAAI;IAuDf;;;;;OAKG;IACH,YAA0B,OAAe,EAAE,EAAW,EAAE,OAAmC;QAAjE,YAAO,GAAP,OAAO,CAAQ;QA5CzC;;WAEG;QACI,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAYtC;;WAEG;QACI,aAAQ,GAAW,EAAE,CAAC;QAE7B;;;;;WAKG;QACI,WAAM,GAAgB,EAAE,CAAC;QAEhC;;WAEG;QACI,YAAO,GAA8B,EAAE,CAAC;QAE/C;;WAEG;QACI,eAAU,GAAG,IAAI,CAAC;QASvB,IAAI,CAAC,EAAE,GAAG,EAAE,aAAF,EAAE,cAAF,EAAE,GAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,WAAW;;QAChB,OAAO,CAAC,MAAA,IAAI,CAAC,OAAO,mCAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IACvD,CAAC;IAED;;OAEG;IACI,GAAG;;QACR,MAAA,IAAI,CAAC,cAAc,0CAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,KAAY;QAC1B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,IAAU;QACxB,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QAEpF,IAAI,iBAAiB,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;CACF"}

package/dist/lib/esm/models/trace.model.js

@@ -0,0 +1,42 @@
+import { randomUUID } from "crypto";
+/**
+ * This model represents a trace.
+ */
+export class Trace {
+    /**
+     * This model represents a trace.
+     * @param id The unique id of the trace.
+     * @param context The context associated with the trace.
+     */
+    constructor(id, context) {
+        /**
+         * The timestamp in milliseconds at which the trace was started.
+         */
+        this.startDate = Date.now();
+        /**
+         * Index of all spans in this trace by keyname, populated by `TracingManager.addSpan`.
+         * Lives on the Trace (not on a particular TracingManager instance) so any TracingManager
+         * reading the active trace through `EventContext.trace` sees the same index — required
+         * for cross-container span lookup (kernel-resolved manager vs per-event resolved manager).
+         */
+        this.spansByKeyname = {};
+        /**
+         * The context associated with the trace.
+         */
+        this.context = {};
+        /**
+         * Whether or not the trace was ended.
+         */
+        this.hasEnded = false;
+        this.id = id !== null && id !== void 0 ? id : randomUUID();
+        this.context = context !== null && context !== void 0 ? context : {};
+    }
+    /**
+     * This returns the duration of the trace in miliseconds.
+     */
+    getDuration() {
+        var _a;
+        return ((_a = this.endDate) !== null && _a !== void 0 ? _a : Date.now()) - this.startDate;
+    }
+}
+//# sourceMappingURL=trace.model.js.map

package/dist/lib/esm/models/trace.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.model.js","sourceRoot":"","sources":["../../../../src/models/trace.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAC;AAGlC;;GAEG;AACH,MAAM,OAAO,KAAK;IAuChB;;;;OAIG;IACH,YAAmB,EAAW,EAAE,OAAmC;QAtCnE;;WAEG;QACI,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAYtC;;;;;WAKG;QACI,mBAAc,GAAkC,EAAE,CAAC;QAE1D;;WAEG;QACI,YAAO,GAA+B,EAAE,CAAC;QAEhD;;WAEG;QACI,aAAQ,GAAY,KAAK,CAAC;QAQ/B,IAAI,CAAC,EAAE,GAAG,EAAE,aAAF,EAAE,cAAF,EAAE,GAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,WAAW;;QAChB,OAAO,CAAC,MAAA,IAAI,CAAC,OAAO,mCAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IACvD,CAAC;CACF"}