@pristine-ts/telemetry 1.0.440 → 2.0.2

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

@@ -0,0 +1,59 @@
+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.
+ *
+ * Replaces the manual `start → try → finally end()` boilerplate:
+ *
+ * ```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.
+ *
+ * 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 {
+    /**
+     * 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>;
+}
+/**
+ * Default singleton. Stateless so sharing is safe.
+ */
+export declare const spanRunner: SpanRunner;

package/dist/types/utils/trace-renderer.d.ts

@@ -0,0 +1,41 @@
+import { Trace } from "../models/trace.model";
+/**
+ * Pure-function renderers for `Trace` objects. Used by both `ConsoleTracer` (writes to
+ * stdout) and `FileTracer` (writes to disk) so the visual output is identical regardless
+ * of destination. All methods are stateless — instantiate once and reuse, or use the
+ * exported singleton `traceRenderer` if you don't care.
+ */
+export declare class TraceRenderer {
+    /**
+     * Indented ASCII tree mirroring the span hierarchy. Right-aligned durations, slowest
+     * leaf span flagged as `← bottleneck`. Best for human readers.
+     *
+     * Internal/parent spans are skipped for bottleneck detection on purpose: a parent's
+     * duration is the sum of its children's work, so it would always dwarf any single
+     * leaf and the flag would never highlight where the actual time was spent.
+     */
+    renderTree(trace: Trace): string;
+    /**
+     * One line per span sorted by start time, no indentation. Best for grep / log
+     * aggregation.
+     */
+    renderFlat(trace: Trace): string;
+    /**
+     * Pretty-printed JSON dump of the trace + every span. Best for piping into a downstream
+     * tool that wants structured access.
+     */
+    renderJson(trace: Trace): string;
+    /**
+     * Serializes a trace to a plain JSON-friendly object. Exposed for callers that want to
+     * embed the structured form in a larger payload (e.g. a NDJSON line).
+     */
+    serialize(trace: Trace): Record<string, unknown>;
+    private serializeSpan;
+    /** Depth-first traversal helper. Visits the root and every descendant once. */
+    private walkSpans;
+}
+/**
+ * Default singleton. Use this from any caller that doesn't care to construct its own —
+ * the class is stateless so sharing is safe.
+ */
+export declare const traceRenderer: TraceRenderer;

package/dist/types/utils/utils.d.ts

@@ -0,0 +1,2 @@
+export * from "./span-runner";
+export * from "./trace-renderer";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/telemetry",
-  "version": "1.0.440",
+  "version": "2.0.2",
   "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": "^1.0.440",
-    "@pristine-ts/logging": "^1.0.440",
+    "@pristine-ts/common": "^2.0.2",
+    "@pristine-ts/logging": "^2.0.2",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
@@ -61,7 +61,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "2828491bc8cc720476584f3cf60791a4a705a77e",
+  "gitHead": "b0899c7eb6b34a99c6df0739507b1458549a0009",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",

package/dist/lib/cjs/tracers/basic.tracer.js

@@ -1,50 +0,0 @@
-"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;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.XrayTracer = void 0;
-const tsyringe_1 = require("tsyringe");
-const common_1 = require("@pristine-ts/common");
-const stream_1 = require("stream");
-/**
- * We need this to have at least one tracer so the @injectAll(ServiceDefinitionTagEnum.Tracer) does not fail
- * Until there's a fix for: https://github.com/microsoft/tsyringe/issues/63
- */
-let XrayTracer = class XrayTracer {
-    constructor() {
-        this.spanStartedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.spanEndedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceStartedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceEndedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-    }
-};
-exports.XrayTracer = XrayTracer;
-exports.XrayTracer = XrayTracer = __decorate([
-    (0, common_1.tag)(common_1.ServiceDefinitionTagEnum.Tracer),
-    (0, tsyringe_1.injectable)()
-], XrayTracer);
-//# sourceMappingURL=basic.tracer.js.map

package/dist/lib/cjs/tracers/basic.tracer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"basic.tracer.js","sourceRoot":"","sources":["../../../../src/tracers/basic.tracer.ts"],"names":[],"mappings":";;;;;;;;;AAAA,uCAAoC;AACpC,gDAAkE;AAClE,mCAAgC;AAGhC;;;GAGG;AAGI,IAAM,UAAU,GAAhB,MAAM,UAAU;IAAhB;QACL,sBAAiB,GAAc,IAAI,iBAAQ,CAAC;YAC1C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,oBAAe,GAAc,IAAI,iBAAQ,CAAC;YACxC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,uBAAkB,GAAc,IAAI,iBAAQ,CAAC;YAC3C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,qBAAgB,GAAc,IAAI,iBAAQ,CAAC;YACzC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;IACL,CAAC;CAAA,CAAA;AAzBY,gCAAU;qBAAV,UAAU;IAFtB,IAAA,YAAG,EAAC,iCAAwB,CAAC,MAAM,CAAC;IACpC,IAAA,qBAAU,GAAE;GACA,UAAU,CAyBtB"}

package/dist/lib/esm/tracers/basic.tracer.js

@@ -1,47 +0,0 @@
-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;
-};
-import { injectable } from "tsyringe";
-import { ServiceDefinitionTagEnum, tag } from "@pristine-ts/common";
-import { Readable } from "stream";
-/**
- * We need this to have at least one tracer so the @injectAll(ServiceDefinitionTagEnum.Tracer) does not fail
- * Until there's a fix for: https://github.com/microsoft/tsyringe/issues/63
- */
-let XrayTracer = class XrayTracer {
-    constructor() {
-        this.spanStartedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.spanEndedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceStartedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceEndedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-    }
-};
-XrayTracer = __decorate([
-    tag(ServiceDefinitionTagEnum.Tracer),
-    injectable()
-], XrayTracer);
-export { XrayTracer };
-//# sourceMappingURL=basic.tracer.js.map

package/dist/lib/esm/tracers/basic.tracer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"basic.tracer.js","sourceRoot":"","sources":["../../../../src/tracers/basic.tracer.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AACpC,OAAO,EAAC,wBAAwB,EAAE,GAAG,EAAC,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAC,QAAQ,EAAC,MAAM,QAAQ,CAAC;AAGhC;;;GAGG;AAGI,IAAM,UAAU,GAAhB,MAAM,UAAU;IAAhB;QACL,sBAAiB,GAAc,IAAI,QAAQ,CAAC;YAC1C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,oBAAe,GAAc,IAAI,QAAQ,CAAC;YACxC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,uBAAkB,GAAc,IAAI,QAAQ,CAAC;YAC3C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,qBAAgB,GAAc,IAAI,QAAQ,CAAC;YACzC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;IACL,CAAC;CAAA,CAAA;AAzBY,UAAU;IAFtB,GAAG,CAAC,wBAAwB,CAAC,MAAM,CAAC;IACpC,UAAU,EAAE;GACA,UAAU,CAyBtB"}

package/dist/types/tracers/basic.tracer.d.ts

@@ -1,12 +0,0 @@
-import { Readable } from "stream";
-import { TracerInterface } from "../interfaces/tracer.interface";
-/**
- * We need this to have at least one tracer so the @injectAll(ServiceDefinitionTagEnum.Tracer) does not fail
- * Until there's a fix for: https://github.com/microsoft/tsyringe/issues/63
- */
-export declare class XrayTracer implements TracerInterface {
-    spanStartedStream?: Readable;
-    spanEndedStream?: Readable;
-    traceStartedStream?: Readable;
-    traceEndedStream?: Readable;
-}