@pristine-ts/common 2.0.3 → 2.0.4

package/dist/types/contexts/event-context.d.ts

@@ -1,26 +1,33 @@
 import { DependencyContainer } from "tsyringe";
+import { Trace } from "../models/trace.model";
 /**
  * Per-event runtime state — the framework's correlation primitives plus a handle to
- * the per-event DI child container. Propagated implicitly via `AsyncLocalStorage`
- * (managed by `EventContextManager`) so downstream code doesn't have to thread these
- * fields through every method signature.
+ * 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` fills in once tracing starts), correlation-
- *     shaped.
+ *     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 declare class EventContext {
     /** Unique id for this specific event. Same value the framework uses everywhere
-     *  else as the correlation/eventId (logging, breadcrumbs, file tracer filenames). */
+     *  else as the correlation/eventId (logging, file tracer filenames). */
     eventId: string;
     /** Trace id once tracing has started. Filled in by `TracingManager.startTracing`. */
     traceId?: string;
+    /** The active `Trace` for this event. Single source of truth: every `TracingManager`
+     *  instance — whether resolved from the root container, a per-event child container,
+     *  or anywhere else — reads and writes spans through this reference. This is what
+     *  lets `addEventToCurrentSpan` from a controller find the same trace started in the
+     *  kernel, even though the TracingManager instances differ across containers. */
+    trace?: Trace;
     /** The per-event DI child container. Helpers (`@traced`, `runWithSpan(name, fn)`,
      *  the LogHandler eventId fallback) reach through this to resolve event-scoped
      *  services without callers having to inject them explicitly. */

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

@@ -1,3 +1,4 @@
 export * from './inject-config.decorator';
 export * from './module-scoped.decorator';
 export * from './tag.decorator';
+export * from './traced.decorator';

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

@@ -0,0 +1,40 @@
+/**
+ * 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 declare function traced(spanName?: string): MethodDecorator;

package/dist/types/enums/enums.d.ts

@@ -2,3 +2,4 @@ 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";

package/dist/types/enums/span-keyname.enum.d.ts

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

package/dist/types/interfaces/interfaces.d.ts

@@ -9,4 +9,5 @@ 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";

package/dist/types/interfaces/tracing-manager.interface.d.ts

@@ -0,0 +1,78 @@
+import { Span } from "../models/span.model";
+import { Trace } from "../models/trace.model";
+/**
+ * This interface specifies what a tracing manager should implement.
+ *
+ * Lives in `@pristine-ts/common` so any package can declare a `TracingManagerInterface`
+ * dependency or use the `@traced` decorator / `spanRunner` helper without taking a
+ * direct dep on `@pristine-ts/telemetry`. The concrete implementation
+ * (`TracingManager`, plus the tracers that consume traces) still lives in telemetry.
+ */
+export interface TracingManagerInterface {
+    /**
+     * This property contains a reference to the active trace.
+     */
+    trace?: Trace;
+    /**
+     * This methods starts the Tracing. This should be the first method called before doing anything else.
+     * @param spanRootKeyname The keyname of the span at the root.
+     * @param traceId The trace id if there is one.
+     * @param context The context if there is one.
+     */
+    startTracing(spanRootKeyname?: string, traceId?: string, context?: {
+        [key: string]: string;
+    }): Span;
+    /**
+     * This method ends the trace entirely.
+     */
+    endTrace(): void;
+    /**
+     * This method starts a new span.
+     * @param keyname The keyname for this new span.
+     * @param parentKeyname The keyname of the parent span.
+     * @param parentId The id of the parent span.
+     * @param context The context if there is one.
+     */
+    startSpan(keyname: string, parentKeyname?: string, parentId?: string, context?: {
+        [key: string]: string;
+    }): Span;
+    /**
+     * This methods adds an already created Span to the trace. It assumes that it its hierarchy is correct.
+     * @param span The span to add.
+     */
+    addSpan(span: Span): Span;
+    /**
+     * This methods ends the span by setting the end date and by calling the tracers.
+     * It will also end the trace if the rootspan is being ended.
+     * @param span The span to end.
+     */
+    endSpan(span: Span): void;
+    /**
+     * This method ends the span using a keyname.
+     * @param keyname The keyname of the span to end.
+     */
+    endSpanKeyname(keyname: string): void;
+    /**
+     * Attaches a named, timestamped event to the most-recently-started in-progress span.
+     * Use for noteworthy moments inside a span's lifetime that don't warrant their own
+     * child span — "validation passed", "found 50 rows", etc. Logs a warning and drops
+     * the marker if no span is currently active.
+     */
+    addEventToCurrentSpan(message: string, attributes?: {
+        [key: string]: string;
+    }): void;
+    /**
+     * Returns the active trace's spans + their events as a flat, timestamp-sorted list.
+     * Public utility for custom tracers, debug endpoints, test helpers, or any consumer
+     * who wants "the active trace as a flat list" without walking the span tree manually.
+     * Returns an empty array when no active trace exists.
+     */
+    getCurrentTrail(): Array<{
+        kind: "span" | "event";
+        name: string;
+        date: Date;
+        attributes: {
+            [key: string]: string;
+        };
+    }>;
+}

package/dist/types/models/models.d.ts

@@ -1,2 +1,5 @@
 export * from "./request";
 export * from "./response";
+export * from "./span-event.model";
+export * from "./span.model";
+export * from "./trace.model";

package/dist/types/models/span-event.model.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare class SpanEvent {
+    readonly message: string;
+    /**
+     * The timestamp in milliseconds at which the event was created. Used to interleave
+     * events with sibling spans when rendering a sorted trail.
+     */
+    readonly timestamp: number;
+    /**
+     * Free-form attributes attached to the event. String-keyed for cheap serialization,
+     * mirroring `Span.context`'s shape. `undefined` when the event carries no metadata.
+     */
+    readonly attributes?: {
+        [key: string]: string;
+    };
+    constructor(message: string, attributes?: {
+        [key: string]: string;
+    });
+}

package/dist/types/models/span.model.d.ts

@@ -0,0 +1,90 @@
+import { Trace } from "./trace.model";
+import { SpanEvent } from "./span-event.model";
+/**
+ * Minimal structural type for the back-reference Span keeps to whatever lifecycle owner
+ * created it. Lets `span.end()` delegate without importing the full TracingManagerInterface
+ * (which lives in @pristine-ts/telemetry). Telemetry's TracingManagerInterface satisfies
+ * this shape by having a compatible `endSpan` method.
+ */
+export interface SpanLifecycleOwnerInterface {
+    endSpan(span: Span): void;
+}
+/**
+ * This model represents a span.
+ */
+export declare class Span {
+    keyname: string;
+    /**
+     * The unique id of the span.
+     */
+    id: string;
+    /**
+     * The owner of the span (typically a TracingManager). Set when the span is created so
+     * `span.end()` can delegate back to the manager.
+     */
+    tracingManager?: SpanLifecycleOwnerInterface;
+    /**
+     * The trace the span is attached to.
+     */
+    trace?: Trace;
+    /**
+     * The timestamp in milliseconds at which the span was started.
+     */
+    startDate: number;
+    /**
+     * The timestamp in milliseconds at which the span was ended.
+     */
+    endDate?: number;
+    /**
+     * The parent span.
+     */
+    parentSpan?: Span;
+    /**
+     * The children spans.
+     */
+    children: Span[];
+    /**
+     * 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(...)`.
+     */
+    events: SpanEvent[];
+    /**
+     * The context associated with the span.
+     */
+    context: {
+        [key: string]: string;
+    };
+    /**
+     * Whether or not the span is in progress, meaning it has not ended.
+     */
+    inProgress: boolean;
+    /**
+     * 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: string, id?: string, context?: {
+        [key: string]: string;
+    });
+    /**
+     * This method returns the duration of the span in milliseconds.
+     */
+    getDuration(): number;
+    /**
+     * This method ends the span.
+     */
+    end(): void;
+    /**
+     * 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: Trace): void;
+    /**
+     * 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: Span): void;
+}

package/dist/types/models/trace.model.d.ts

@@ -0,0 +1,53 @@
+import { Span } from "./span.model";
+/**
+ * This model represents a trace.
+ */
+export declare class Trace {
+    /**
+     * The unique id of the trace.
+     */
+    id: string;
+    /**
+     * The timestamp in milliseconds at which the trace was started.
+     */
+    startDate: number;
+    /**
+     * The timestamp in milliseconds at which the trace was ended.
+     */
+    endDate?: number;
+    /**
+     * The span that is at the root.
+     */
+    rootSpan?: Span;
+    /**
+     * 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).
+     */
+    spansByKeyname: {
+        [keyname: string]: Span[];
+    };
+    /**
+     * The context associated with the trace.
+     */
+    context?: {
+        [key: string]: string;
+    };
+    /**
+     * Whether or not the trace was ended.
+     */
+    hasEnded: boolean;
+    /**
+     * This model represents a trace.
+     * @param id The unique id of the trace.
+     * @param context The context associated with the trace.
+     */
+    constructor(id?: string, context?: {
+        [key: string]: string;
+    });
+    /**
+     * This returns the duration of the trace in miliseconds.
+     */
+    getDuration(): number;
+}

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

@@ -0,0 +1,55 @@
+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;

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

@@ -1,3 +1,4 @@
 export * from "./date.util";
 export * from "./enum.util";
 export * from "./metadata.util";
+export * from "./span-runner";

package/package.json

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