@pristine-ts/common 2.0.4 → 2.0.6

package/dist/types/errors/forbidden.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 403. Caller is authenticated but lacks permission. CLI exit `ExitCode.NoPermission` (77). */
+export declare class ForbiddenError extends PristineError {
+    constructor(message?: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/internal.error.d.ts

@@ -0,0 +1,12 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/**
+ * Catch-all for framework/system bugs that shouldn't be exposed verbatim. 500.
+ * CLI exit `ExitCode.Software` (70). `SystemError` triggers message sanitization in
+ * production mode.
+ */
+export declare class InternalError extends PristineError {
+    constructor(message?: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/not-found.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 404. Resource doesn't exist. CLI exit `ExitCode.Error` (1). */
+export declare class NotFoundError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/pristine-error-code.enum.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Standard error-code catalog used across the framework. Each value is a `SCREAMING_SNAKE_CASE`
+ * slug surfaced in the HTTP response body (`{"code": ...}`) and on CLI stderr (`✗ CODE: ...`).
+ *
+ * **Use the enum members for framework-standard cases.** Consumers can add their own
+ * domain-specific codes by passing a plain string — `PristineErrorOptions.code` is typed
+ * `PristineErrorCode | string` so both the enum and free-form strings get autocomplete-
+ * friendly type checking.
+ *
+ * ```ts
+ * throw new PristineError("Token expired", {
+ *   code: "TOKEN_EXPIRED",                       // consumer-defined code
+ *   httpStatus: 401,
+ * });
+ *
+ * throw new PristineError("Item missing", {
+ *   code: PristineErrorCode.NotFound,            // framework-standard code
+ *   httpStatus: 404,
+ * });
+ * ```
+ */
+export declare enum PristineErrorCode {
+    BadRequest = "BAD_REQUEST",
+    Unauthorized = "UNAUTHORIZED",
+    Forbidden = "FORBIDDEN",
+    NotFound = "NOT_FOUND",
+    Conflict = "CONFLICT",
+    ValidationFailed = "VALIDATION_FAILED",
+    ConfigError = "CONFIG_ERROR",
+    UsageError = "USAGE_ERROR",
+    InternalError = "INTERNAL_ERROR"
+}

package/dist/types/errors/pristine-error-kind.enum.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Categorizes a `PristineError` by who caused it. Replaces the older `expected: boolean`
+ * field, whose meaning ("expected by whom?") wasn't self-explanatory.
+ *
+ * The kind drives how the channel reporters render the error in production mode:
+ *
+ * - `UserError`: caller did something wrong. Message is safe to expose verbatim;
+ *   structured details surface as-is. HTTP responses use the carried `httpStatus`
+ *   (typically 4xx). CLI stderr shows the message and details.
+ *
+ * - `SystemError`: framework or downstream bug — not the caller's fault. In production
+ *   mode the message is replaced with a generic "Internal Server Error" / "Internal Error"
+ *   so internal details never leak to clients. Stack and cause chain are still logged
+ *   internally via the LogHandler for operators. In development mode (`PRISTINE_ENV=dev`)
+ *   the full message surfaces.
+ *
+ * Default is `UserError` — most thrown errors in framework and application code are caller-
+ * induced. `PristineError.from(unknown)` marks raw `Error` and non-Error throws as
+ * `SystemError` since they didn't opt into the typed contract.
+ */
+export declare enum PristineErrorKind {
+    UserError = "user-error",
+    SystemError = "system-error"
+}

package/dist/types/errors/pristine-error-options.interface.d.ts

@@ -0,0 +1,59 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/**
+ * Options carried by every `PristineError`. All fields optional — defaults give a sensible
+ * "user error with 500 / exit 1" shape when none are set.
+ */
+export interface PristineErrorOptions {
+    /**
+     * Stable slug for the error category. Surfaces in HTTP response bodies and CLI stderr;
+     * safe to use as the join key for i18n, log queries, and alerting rules.
+     *
+     * Accepts the framework's `PristineErrorCode` enum for standard categories, or any
+     * `SCREAMING_SNAKE_CASE` string for domain-specific codes (`"TOKEN_EXPIRED"`,
+     * `"STRIPE_CARD_DECLINED"`). The enum is the catalog of well-known codes; strings are
+     * the extensibility hatch.
+     *
+     * Defaults to `PristineErrorCode.InternalError` at render time when absent.
+     */
+    code?: PristineErrorCode | string;
+    /**
+     * HTTP status when this error reaches the HTTP boundary. Omit when the error has no
+     * natural HTTP semantics (e.g. a CLI-only `ConfigError`) — the responder will fall back
+     * to 500.
+     */
+    httpStatus?: number;
+    /**
+     * Process exit code when this error reaches the CLI boundary. Accepts the framework's
+     * `ExitCode` enum (sysexits.h-aligned) or any raw number for custom codes. Omit to fall
+     * back to `ExitCode.Error` (1) for user errors and `ExitCode.Software` (70) for system
+     * errors.
+     */
+    exitCode?: ExitCode | number;
+    /**
+     * Underlying error this one wraps. Uses the standard `Error.cause` slot (Node 16.9+),
+     * so any tooling that knows the standard cause chain works automatically. Walked by
+     * `PristineError.from` to preserve the original error type when normalizing.
+     */
+    cause?: Error;
+    /**
+     * Structured fields safe to surface in the response body / stderr. Per-error-class
+     * schema — e.g. a `NotFoundError` may carry `{ resource, id }`. Surfaced to users
+     * only when `kind === UserError` (the default) or `mode === development`.
+     */
+    details?: Record<string, unknown>;
+    /**
+     * Categorizes the error by who caused it. Drives how the message is rendered in
+     * production mode:
+     *
+     * - `UserError` (default): caller did something wrong. Message surfaced verbatim;
+     *   details exposed; production responses include both.
+     *
+     * - `SystemError`: framework/system bug, not the caller's fault. Production responses
+     *   replace the message with a generic "Internal Server Error" / "Internal Error" and
+     *   omit details + stack. The raw error is still logged via the LogHandler for
+     *   operators. `PristineError.from` marks unknown throws as `SystemError`.
+     */
+    kind?: PristineErrorKind;
+}

package/dist/types/errors/pristine.error.d.ts

@@ -0,0 +1,78 @@
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+/**
+ * Single error base for the entire framework. Replaces the old `LoggableError` +
+ * `HttpError` + ad-hoc subclass hierarchy.
+ *
+ * **What it gives you**:
+ * - A structured `options` bag (`code`, `httpStatus`, `exitCode`, `details`, `cause`,
+ *   `kind`) read by both the HTTP and CLI channel reporters.
+ * - Automatic `error.name = ClassName` for subclasses.
+ * - Automatic prototype-chain fix via `new.target.prototype` — subclasses never need to
+ *   repeat the `Object.setPrototypeOf(this, FooError.prototype)` incantation, AND
+ *   `instanceof` works correctly for direct/standard-library/custom subclasses at any
+ *   depth (verified by spec).
+ * - Standard `Error.cause` propagation (Node 16.9+ native).
+ *
+ * **Subclass form** when a named class makes `instanceof` checks read better:
+ *
+ * ```ts
+ * export class TokenExpiredError extends UnauthorizedError {
+ *   constructor(tokenId: string) {
+ *     super("The token has expired", {
+ *       code: "TOKEN_EXPIRED",
+ *       details: { tokenId },
+ *     });
+ *   }
+ * }
+ * // ...
+ * try { ... }
+ * catch (e) { if (e instanceof TokenExpiredError) ... }   // works.
+ * ```
+ *
+ * **Direct form** when the call site self-documents:
+ *
+ * ```ts
+ * throw new PristineError(`User '${id}' not found`, {
+ *   code: PristineErrorCode.NotFound,
+ *   httpStatus: 404,
+ *   details: { resource: "User", id },
+ * });
+ * ```
+ *
+ * **Re-throw with enrichment** when catching, adding context, and re-throwing. Use the
+ * standard `cause` chain rather than mutating the original — this preserves the original
+ * error's identity for tooling that walks `error.cause`:
+ *
+ * ```ts
+ * try { await dispatcher.dispatch(event); }
+ * catch (cause) {
+ *   throw new PristineError("Event dispatch failed", {
+ *     code: "EVENT_DISPATCH_FAILED",
+ *     kind: PristineErrorKind.SystemError,
+ *     cause,
+ *     details: { eventId: event.id },
+ *   });
+ * }
+ * ```
+ */
+export declare class PristineError extends Error {
+    readonly options: PristineErrorOptions;
+    constructor(message: string, options?: PristineErrorOptions);
+    /**
+     * Normalizes any thrown value into a `PristineError`. The chokepoint that every channel
+     * reporter funnels through before rendering, so the reporters never need to handle
+     * unknown shapes.
+     *
+     * - `PristineError` instances pass through unchanged.
+     * - `Error` instances are wrapped with `kind: SystemError` and propagated as `cause` —
+     *   the wrapper preserves the original message and stack for `mode === Development`
+     *   rendering.
+     * - Anything else (strings, numbers, `throw {someObject}`) is coerced via `String(...)`
+     *   into a message with `kind: SystemError`.
+     *
+     * The standard `Error.cause` chain is preserved: if the input has a `cause`, it stays
+     * on the wrapper (which itself has the input as its cause), so a debugger walking
+     * `error.cause.cause.cause` sees the full history.
+     */
+    static from(error: unknown): PristineError;
+}

package/dist/types/errors/unauthorized.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 401. Caller is not authenticated. CLI exit `ExitCode.NoPermission` (77). */
+export declare class UnauthorizedError extends PristineError {
+    constructor(message?: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/usage.error.d.ts

@@ -0,0 +1,11 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/**
+ * CLI-only — bad command-line usage (wrong flag, missing required arg, unknown command).
+ * No `httpStatus`. CLI exit `ExitCode.Usage` (64).
+ */
+export declare class UsageError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/validation.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 422. Input parsed but failed semantic validation. CLI exit `ExitCode.DataError` (65). */
+export declare class ValidationError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

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

@@ -25,6 +25,32 @@ export interface ModuleInterface {
      * for the module.
      */
     configurationDefinitions?: ConfigurationDefinition[];
+    /**
+     * Default values this module wants applied to configuration keys — typically keys owned
+     * by **other** modules. Use it when a context-providing module (e.g. `CliModule`) has an
+     * opinion about how a dependency-module's keys should be configured by default.
+     *
+     * Precedence in the resolution chain:
+     *   1. Explicit overrides passed to `kernel.start()` — beats this.
+     *   2. `pristine.config.ts:config` block — beats this.
+     *   3. **`configDefaults`** (this field).
+     *   4. The owning `configurationDefinition.defaultResolvers` chain — loses to this.
+     *   5. The owning `configurationDefinition.defaultValue` — loses to this.
+     *
+     * Not to be confused with `configurationDefinition.defaultValue`: that's the
+     * owning-module's hard fallback when nothing else fires; `configDefaults` is a
+     * different module expressing a preferred value above the resolver chain.
+     *
+     * Validation:
+     *   - **Unknown key** (not declared by any module's `configurationDefinitions` in the
+     *     graph) → kernel throws at boot, naming the source module + key.
+     *   - **Two modules disagree** on the same key's `configDefaults` → kernel throws at
+     *     registration time, naming both module keynames.
+     *
+     * Keys are configuration parameter names (e.g. `"pristine.logging.consoleLoggerOutputMode"`),
+     * not arbitrary strings.
+     */
+    configDefaults?: Record<string, unknown>;
     /**
      * This function lets you run code on the module initialization. Be careful the tags and the router are not created yet.
      * @param container

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

@@ -4,9 +4,9 @@ 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.
+ * dependency or use the `@traced` decorator 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 {
     /**
@@ -53,22 +53,22 @@ export interface TracingManagerInterface {
      */
     endSpanKeyname(keyname: string): void;
     /**
-     * Attaches a named, timestamped event to the most-recently-started in-progress span.
+     * Attaches a named, timestamped marker 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?: {
+    addMarkerToCurrentSpan(message: string, attributes?: {
         [key: string]: string;
     }): void;
     /**
-     * Returns the active trace's spans + their events as a flat, timestamp-sorted list.
+     * Returns the active trace's spans + their markers 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";
+        kind: "span" | "marker";
         name: string;
         date: Date;
         attributes: {

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

@@ -1,5 +1,6 @@
 import { DependencyContainer } from "tsyringe";
 import { EventContext } from "../contexts/event-context";
+import { TracingManagerInterface } from "../interfaces/tracing-manager.interface";
 /**
  * Owns the `AsyncLocalStorage` instance that propagates the active `EventContext`
  * across `await` boundaries, `Promise.all`, `setImmediate`, and the rest of Node's
@@ -40,6 +41,8 @@ export declare class EventContextManager {
     traceId(): string | undefined;
     /** Convenience: the per-event DI child container, or `undefined`. */
     container(): DependencyContainer | undefined;
+    /** Convenience: the `TracingManager` that owns this event's trace, or `undefined`. */
+    tracingManager(): TracingManagerInterface | 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
@@ -54,5 +57,6 @@ export declare class EventContextManager {
     static eventId(): string | undefined;
     static traceId(): string | undefined;
     static container(): DependencyContainer | undefined;
+    static tracingManager(): TracingManagerInterface | undefined;
     static bind<F extends (...args: any[]) => any>(fn: F): F;
 }

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

@@ -1,5 +1,6 @@
 export * from "./request";
 export * from "./response";
-export * from "./span-event.model";
+export * from "./span-lifecycle-owner.interface";
+export * from "./span-marker.model";
 export * from "./span.model";
 export * from "./trace.model";

package/dist/types/models/span-lifecycle-owner.interface.d.ts

@@ -0,0 +1,11 @@
+import { Span } from "./span.model";
+/**
+ * Minimal structural type for the back-reference a `Span` keeps to whatever lifecycle
+ * owner created it. Lets `span.end()` delegate without importing the full
+ * `TracingManagerInterface` (which is registered through DI under the
+ * `"TracingManagerInterface"` token). Telemetry's `TracingManagerInterface` satisfies
+ * this shape by having a compatible `endSpan` method.
+ */
+export interface SpanLifecycleOwnerInterface {
+    endSpan(span: Span): void;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * 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".
+ *
+ * **Markers are instants, not durations.** They carry a single timestamp; they have no
+ * children and no end date. If you need hierarchical timing, spawn a child `Span`
+ * instead — that gives you start/end semantics and its own marker list.
+ *
+ * Modeled after OpenTelemetry's "span events" concept (we renamed `event` → `marker`
+ * here because `Event` is heavily overloaded in Pristine's dispatched-event domain —
+ * `Event<T>`, `EventHandler`, `EventPipeline`, `EventDispatcher`, etc.). A `Span` carries
+ * `markers: SpanMarker[]` alongside its `children: Span[]`. Renderers interleave markers
+ * with child spans by timestamp to produce a chronological trail of what happened.
+ *
+ * Use `TracingManager.addMarkerToCurrentSpan(message, attributes?)` to add one — it
+ * finds the most-recently-started in-progress span and attaches the marker there.
+ */
+export declare class SpanMarker {
+    readonly message: string;
+    /**
+     * The timestamp in milliseconds at which the marker was created. Used to interleave
+     * markers with sibling spans when rendering a sorted trail.
+     */
+    readonly timestamp: number;
+    /**
+     * Free-form attributes attached to the marker. String-keyed for cheap serialization,
+     * mirroring `Span.context`'s shape. `undefined` when the marker carries no metadata.
+     */
+    readonly attributes?: {
+        [key: string]: string;
+    };
+    constructor(message: string, attributes?: {
+        [key: string]: string;
+    });
+}

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

@@ -1,14 +1,6 @@
+import { SpanLifecycleOwnerInterface } from "./span-lifecycle-owner.interface";
+import { SpanMarker } from "./span-marker.model";
 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.
  */
@@ -47,9 +39,12 @@ export declare class 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(...)`.
+     * `TracingManager.addMarkerToCurrentSpan(...)`.
+     *
+     * Markers are flat by design (instants, not durations). For hierarchical timing, use
+     * child spans.
      */
-    events: SpanEvent[];
+    markers: SpanMarker[];
     /**
      * The context associated with the span.
      */

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

@@ -1,4 +1,3 @@
 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.4",
+  "version": "2.0.6",
   "description": "",
   "module": "dist/lib/esm/common.module.js",
   "main": "dist/lib/cjs/common.module.js",
@@ -63,5 +63,5 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "f376d34e13c1b17b7764c0b47708148e4e51390b"
+  "gitHead": "539029d624372f9bb1e22e09da7152eabb95c105"
 }

package/dist/lib/cjs/errors/loggable.error.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoggableError = void 0;
-/**
- * This Error represents a LoggableError
- */
-class LoggableError extends Error {
-    constructor(message, extra) {
-        super(message);
-        this.message = message;
-        this.extra = extra;
-        // Set the prototype explicitly.
-        // As specified in the documentation in TypeScript
-        // https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#extending-built-ins-like-error-array-and-map-may-no-longer-work
-        Object.setPrototypeOf(this, LoggableError.prototype);
-    }
-}
-exports.LoggableError = LoggableError;
-//# sourceMappingURL=loggable.error.js.map

package/dist/lib/cjs/errors/loggable.error.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"loggable.error.js","sourceRoot":"","sources":["../../../../src/errors/loggable.error.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IACtC,YAA4B,OAAe,EAAW,KAAW;QAC/D,KAAK,CAAC,OAAO,CAAC,CAAC;QADW,YAAO,GAAP,OAAO,CAAQ;QAAW,UAAK,GAAL,KAAK,CAAM;QAG/D,gCAAgC;QAChC,kDAAkD;QAClD,gIAAgI;QAChI,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;CACF;AATD,sCASC"}

package/dist/lib/cjs/models/span-event.model.js

@@ -1,28 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SpanEvent = void 0;
-/**
- * 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.
- */
-class SpanEvent {
-    constructor(message, attributes) {
-        this.message = message;
-        /**
-         * The timestamp in milliseconds at which the event was created. Used to interleave
-         * events with sibling spans when rendering a sorted trail.
-         */
-        this.timestamp = Date.now();
-        this.attributes = attributes;
-    }
-}
-exports.SpanEvent = SpanEvent;
-//# sourceMappingURL=span-event.model.js.map

package/dist/lib/cjs/models/span-event.model.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"span-event.model.js","sourceRoot":"","sources":["../../../../src/models/span-event.model.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,MAAa,SAAS;IAapB,YAA4B,OAAe,EAAE,UAAsC;QAAvD,YAAO,GAAP,OAAO,CAAQ;QAZ3C;;;WAGG;QACa,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAS7C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAhBD,8BAgBC"}

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

@@ -1,117 +0,0 @@
-"use strict";
-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());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.spanRunner = exports.SpanRunner = void 0;
-const event_context_manager_1 = require("../managers/event-context.manager");
-/**
- * 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`.
- */
-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;
-                // ── container.resolve, justified ──────────────────────────────────────────────
-                // This is one of the documented "legitimate exception" cases (see CLAUDE.md):
-                // SpanRunner is a stateless utility class with static-ish methods invoked from
-                // free functions / decorators that have no constructor to inject through. The
-                // ALS-form overload exists precisely so callers don't have to thread a
-                // TracingManager reference everywhere. If there's no active event context (e.g. a
-                // unit test calling this directly), the lookup is skipped and the function runs
-                // without a span — tracing must never throw or change semantics.
-                const container = event_context_manager_1.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();
-            }
-        });
-    }
-}
-exports.SpanRunner = SpanRunner;
-/**
- * Default singleton. Stateless so sharing is safe.
- */
-exports.spanRunner = new SpanRunner();
-//# sourceMappingURL=span-runner.js.map