@pristine-ts/common 2.0.2 → 2.0.3

package/dist/types/contexts/tracing.context.d.ts

@@ -1,4 +1,18 @@
 import "reflect-metadata";
+/**
+ * @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.
+ */
 export declare class TracingContext {
     traceId?: string;
 }

package/dist/types/managers/event-context.manager.d.ts

@@ -0,0 +1,58 @@
+import { DependencyContainer } from "tsyringe";
+import { EventContext } from "../contexts/event-context";
+/**
+ * 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.
+ */
+export declare class EventContextManager {
+    private static readonly als;
+    /**
+     * Installs `ctx` as the active `EventContext` for the duration of `fn` (and every
+     * async chain reachable from it). Returns whatever `fn` returns. Used by Pristine's
+     * event pipeline; application code shouldn't need to call this directly.
+     */
+    run<T>(ctx: EventContext, fn: () => T): T;
+    run<T>(ctx: EventContext, fn: () => Promise<T>): Promise<T>;
+    /** Returns the active `EventContext`, or `undefined` if no context is installed
+     *  (i.e. we're outside any `run()` call). */
+    current(): EventContext | undefined;
+    /** Convenience: the `eventId` of the active context, or `undefined`. */
+    eventId(): string | undefined;
+    /** Convenience: the `traceId` of the active context, or `undefined`. */
+    traceId(): string | undefined;
+    /** Convenience: the per-event DI child container, or `undefined`. */
+    container(): DependencyContainer | undefined;
+    /**
+     * 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<F extends (...args: any[]) => any>(fn: F): F;
+    static current(): EventContext | undefined;
+    static eventId(): string | undefined;
+    static traceId(): string | undefined;
+    static container(): DependencyContainer | undefined;
+    static bind<F extends (...args: any[]) => any>(fn: F): F;
+}

package/dist/types/managers/managers.d.ts

@@ -0,0 +1 @@
+export * from "./event-context.manager";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/common",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "",
   "module": "dist/lib/esm/common.module.js",
   "main": "dist/lib/cjs/common.module.js",
@@ -63,5 +63,5 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "b0899c7eb6b34a99c6df0739507b1458549a0009"
+  "gitHead": "c741bb430ab8f6286068dc3870fcadf4cefd0023"
 }