@pristine-ts/common 2.0.3 → 2.0.5

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-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.model.d.ts

@@ -0,0 +1,82 @@
+import { SpanEvent } from "./span-event.model";
+import { SpanLifecycleOwnerInterface } from "./span-lifecycle-owner.interface";
+import { Trace } from "./trace.model";
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/common",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "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": "9a960b330ee1961bb9a6151ce50257c4d8ccd48d"
 }

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/esm/errors/loggable.error.js

@@ -1,15 +0,0 @@
-/**
- * This Error represents a LoggableError
- */
-export 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);
-    }
-}
-//# sourceMappingURL=loggable.error.js.map

package/dist/lib/esm/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,MAAM,OAAO,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"}

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

@@ -1,8 +0,0 @@
-/**
- * This Error represents a LoggableError
- */
-export declare class LoggableError extends Error {
-    readonly message: string;
-    readonly extra?: any | undefined;
-    constructor(message: string, extra?: any | undefined);
-}