@pristine-ts/telemetry 2.0.3 → 2.0.5

package/dist/lib/esm/utils/span-runner.js

@@ -1,108 +0,0 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { EventContextManager } from "@pristine-ts/common";
-/**
- * Runs a function inside a span that is automatically ended when the function returns
- * or throws.
- *
- * 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
- * return spanRunner.runWithSpan(this.tracingManager, "payment.charge",
- *   () => this.client.charge(amount));
- * ```
- *
- * **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.
- *
- * Stateless — instantiate once and reuse, or use the exported singleton `spanRunner`.
- */
-export class SpanRunner {
-    runWithSpan(tracingManagerOrSpanKeyname, spanKeynameOrFn, fnOrOptions, maybeOptions) {
-        return __awaiter(this, void 0, void 0, function* () {
-            // Disambiguate by the first argument's shape. A string means "ALS form"; an object
-            // with `startSpan` means the explicit-manager form.
-            let tracingManager;
-            let spanKeyname;
-            let fn;
-            let options;
-            if (typeof tracingManagerOrSpanKeyname === "string") {
-                spanKeyname = tracingManagerOrSpanKeyname;
-                fn = spanKeynameOrFn;
-                options = fnOrOptions;
-                // Resolve the manager from the active event context. If there isn't one (e.g. a
-                // unit test calling this directly), fall back to running the function without a
-                // span — tracing must never throw or change semantics.
-                const container = EventContextManager.container();
-                if (container !== undefined) {
-                    try {
-                        tracingManager = container.resolve("TracingManagerInterface");
-                    }
-                    catch (_a) {
-                        tracingManager = undefined;
-                    }
-                }
-            }
-            else {
-                tracingManager = tracingManagerOrSpanKeyname;
-                spanKeyname = spanKeynameOrFn;
-                fn = fnOrOptions;
-                options = maybeOptions;
-            }
-            if (tracingManager === undefined) {
-                // No manager available: ALS form called outside any event context, or no
-                // TracingManager registered in the container. Run the function unchanged so
-                // callers get the same behavior they'd see without `runWithSpan` wrapping at all.
-                return yield fn();
-            }
-            const span = tracingManager.startSpan(spanKeyname, options === null || options === void 0 ? void 0 : options.parentKeyname, options === null || options === void 0 ? void 0 : options.parentId, options === null || options === void 0 ? void 0 : options.context);
-            try {
-                return yield fn();
-            }
-            catch (error) {
-                // Annotate the span with error info so it surfaces in the rendered output without
-                // forcing the caller to remember to add it themselves. Span.context is string-typed
-                // by design (cheap to serialize), so we coerce.
-                if (error instanceof Error) {
-                    span.context = Object.assign(Object.assign({}, span.context), { error: "true", errorName: error.name, errorMessage: error.message });
-                }
-                else {
-                    span.context = Object.assign(Object.assign({}, span.context), { error: "true", errorName: "non-error-throw", errorMessage: String(error) });
-                }
-                throw error;
-            }
-            finally {
-                span.end();
-            }
-        });
-    }
-}
-/**
- * Default singleton. Stateless so sharing is safe.
- */
-export const spanRunner = new SpanRunner();
-//# sourceMappingURL=span-runner.js.map

package/dist/lib/esm/utils/span-runner.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"span-runner.js","sourceRoot":"","sources":["../../../../src/utils/span-runner.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAexD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,UAAU;IAcf,WAAW,CACf,2BAA6D,EAC7D,eAAgD,EAChD,WAAwD,EACxD,YAAgC;;YAEhC,mFAAmF;YACnF,oDAAoD;YACpD,IAAI,cAAmD,CAAC;YACxD,IAAI,WAAmB,CAAC;YACxB,IAAI,EAAwB,CAAC;YAC7B,IAAI,OAAsC,CAAC;YAE3C,IAAI,OAAO,2BAA2B,KAAK,QAAQ,EAAE,CAAC;gBACpD,WAAW,GAAG,2BAA2B,CAAC;gBAC1C,EAAE,GAAG,eAAuC,CAAC;gBAC7C,OAAO,GAAG,WAA4C,CAAC;gBACvD,gFAAgF;gBAChF,gFAAgF;gBAChF,uDAAuD;gBACvD,MAAM,SAAS,GAAG,mBAAmB,CAAC,SAAS,EAAE,CAAC;gBAClD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;oBAC5B,IAAI,CAAC;wBACH,cAAc,GAAG,SAAS,CAAC,OAAO,CAA0B,yBAAyB,CAAC,CAAC;oBACzF,CAAC;oBAAC,WAAM,CAAC;wBACP,cAAc,GAAG,SAAS,CAAC;oBAC7B,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,cAAc,GAAG,2BAA2B,CAAC;gBAC7C,WAAW,GAAG,eAAyB,CAAC;gBACxC,EAAE,GAAG,WAAmC,CAAC;gBACzC,OAAO,GAAG,YAAY,CAAC;YACzB,CAAC;YAED,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,yEAAyE;gBACzE,4EAA4E;gBAC5E,kFAAkF;gBAClF,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;YAED,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CACnC,WAAW,EACX,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,aAAa,EACtB,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ,EACjB,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,CACjB,CAAC;YAEF,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,kFAAkF;gBAClF,oFAAoF;gBACpF,gDAAgD;gBAChD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;oBAC3B,IAAI,CAAC,OAAO,mCACP,IAAI,CAAC,OAAO,KACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,KAAK,CAAC,IAAI,EACrB,YAAY,EAAE,KAAK,CAAC,OAAO,GAC5B,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC,OAAO,mCACP,IAAI,CAAC,OAAO,KACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,GAC5B,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;QACH,CAAC;KAAA;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,UAAU,EAAE,CAAC"}

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

@@ -1 +0,0 @@
-export * from "./traced.decorator";

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

@@ -1,35 +0,0 @@
-/**
- * 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/utils/span-runner.d.ts

@@ -1,55 +0,0 @@
-import { TracingManagerInterface } from "../interfaces/tracing-manager.interface";
-/**
- * Options to scope a `runWithSpan` call beyond just naming the span.
- */
-export interface SpanRunnerOptions {
-    /** When set, attach the new span as a child of the most recent span with this keyname. */
-    parentKeyname?: string;
-    /** Disambiguates parents when multiple spans share the same `parentKeyname`. */
-    parentId?: string;
-    /** Free-form context recorded on the span and surfaced in the rendered output. */
-    context?: {
-        [key: string]: string;
-    };
-}
-/**
- * Runs a function inside a span that is automatically ended when the function returns
- * or throws.
- *
- * 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
- * return spanRunner.runWithSpan(this.tracingManager, "payment.charge",
- *   () => this.client.charge(amount));
- * ```
- *
- * **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.
- *
- * Stateless — instantiate once and reuse, or use the exported singleton `spanRunner`.
- */
-export declare class SpanRunner {
-    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.
- */
-export declare const spanRunner: SpanRunner;