@pristine-ts/telemetry 2.0.2 → 2.0.3

package/dist/types/decorators/traced.decorator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * @param spanName Optional explicit name for the span. Defaults to
+ *   `${ClassName}.${methodName}`.
+ */
+export declare function traced(spanName?: string): MethodDecorator;

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

@@ -8,6 +8,14 @@ import { LogHandlerInterface } from "@pristine-ts/logging";
  * The Tracing Manager provides methods to help with tracing.
  * It is tagged and can be injected using TracingManagerInterface which facilitates mocking.
  * It is module scoped to the TelemetryModuleKeyname.
+ *
+ * **Lifecycle: container-scoped, not singleton.** Each per-event DI child container gets
+ * its own `TracingManager` instance with its own `trace` and `spans` state. Earlier
+ * versions used `@singleton()` — a single instance shared across every event — which
+ * was a latent bug: parallel events would clobber each other's `this.trace`. Resolving
+ * `TracingManager` from the root container still returns the root instance (used for
+ * kernel-initialization spans before any event has started); resolving from a child
+ * container returns the per-event instance, which is what application code wants.
  */
 export declare class TracingManager implements TracingManagerInterface {
     private readonly tracers;

package/dist/types/telemetry.module.d.ts

@@ -1,4 +1,5 @@
 import { ModuleInterface } from "@pristine-ts/common";
+export * from "./decorators/decorators";
 export * from "./enums/enums";
 export * from "./interfaces/interfaces";
 export * from "./managers/managers";

package/dist/types/utils/span-runner.d.ts

@@ -16,42 +16,38 @@ export interface SpanRunnerOptions {
  * Runs a function inside a span that is automatically ended when the function returns
  * or throws.
  *
- * Replaces the manual `start → try → finally end()` boilerplate:
+ * Two call shapes are supported:
+ *
+ * **Explicit form** (`runWithSpan(tracingManager, name, fn)`) — pass the manager you've
+ * already injected. Works anywhere, including outside an event context. Use this when
+ * you have a `TracingManager` reference in hand:
  *
  * ```ts
- * // Before:
- * const span = this.tracingManager.startSpan("payment.charge");
- * try {
- *   return await this.client.charge(amount);
- * } finally {
- *   span.end();
- * }
- *
- * // After:
  * return spanRunner.runWithSpan(this.tracingManager, "payment.charge",
  *   () => this.client.charge(amount));
  * ```
  *
- * Why pass `tracingManager` explicitly? The manager is registered per-container, and
- * Pristine creates a child container per event. A "magic" lookup that finds the right
- * one requires AsyncLocalStorage propagation — deferred until that infrastructure
- * exists. For now, services inject `@inject("TracingManagerInterface") private readonly
- * tracingManager: TracingManagerInterface` and pass it through.
+ * **ALS form** (`runWithSpan(name, fn)`) — auto-resolves the `TracingManager` from the
+ * active `EventContext`'s container. Concise; works when called from anywhere inside
+ * a Pristine event (controller, service, etc.) without needing the manager threaded
+ * through:
+ *
+ * ```ts
+ * return spanRunner.runWithSpan("payment.charge", () => this.client.charge(amount));
+ * ```
+ *
+ * If the ALS form is used outside any `EventContext` (e.g. a unit test that doesn't
+ * boot a kernel), no span is created and `fn` runs unchanged — same no-throw contract
+ * as the rest of the tracing layer.
  *
  * On thrown errors: the error's name/message is attached to the span's context (visible
- * in the rendered tree/json output) and then re-thrown. The span is ended either way.
+ * in the rendered tree/JSON output) and then re-thrown. The span is ended either way.
  *
  * Stateless — instantiate once and reuse, or use the exported singleton `spanRunner`.
  */
 export declare class SpanRunner {
-    /**
-     * Runs `fn` inside a span. See class docs for full semantics.
-     *
-     * @typeParam T The return type of `fn`. Always wrapped in `Promise<T>` because the
-     *   helper awaits internally — a sync `fn` works fine, but the return type loses its
-     *   sync-ness.
-     */
     runWithSpan<T>(tracingManager: TracingManagerInterface, spanKeyname: string, fn: () => Promise<T> | T, options?: SpanRunnerOptions): Promise<T>;
+    runWithSpan<T>(spanKeyname: string, fn: () => Promise<T> | T, options?: SpanRunnerOptions): Promise<T>;
 }
 /**
  * Default singleton. Stateless so sharing is safe.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/telemetry",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "",
   "module": "dist/lib/esm/telemetry.module.js",
   "main": "dist/lib/cjs/telemetry.module.js",
@@ -12,8 +12,8 @@
     "test:cov": "jest --coverage"
   },
   "dependencies": {
-    "@pristine-ts/common": "^2.0.2",
-    "@pristine-ts/logging": "^2.0.2",
+    "@pristine-ts/common": "^2.0.3",
+    "@pristine-ts/logging": "^2.0.3",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
@@ -61,7 +61,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "b0899c7eb6b34a99c6df0739507b1458549a0009",
+  "gitHead": "c741bb430ab8f6286068dc3870fcadf4cefd0023",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",