@code-pushup/utils 0.101.0 → 0.102.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/utils",
-  "version": "0.101.0",
+  "version": "0.102.0",
   "description": "Low-level utilities (helper functions, etc.) used by Code PushUp CLI",
   "license": "MIT",
   "homepage": "https://github.com/code-pushup/cli/tree/main/packages/utils#readme",
@@ -27,7 +27,7 @@
     "node": ">=17.0.0"
   },
   "dependencies": {
-    "@code-pushup/models": "0.101.0",
+    "@code-pushup/models": "0.102.0",
     "ansis": "^3.3.0",
     "build-md": "^0.4.2",
     "bundle-require": "^5.1.0",

package/src/lib/clock-epoch.d.ts

@@ -0,0 +1,44 @@
+export type Microseconds = number;
+export type Milliseconds = number;
+/**
+ * Defines clock utilities for time conversions.
+ * Handles time origins in NodeJS and the Browser
+ * Provides process and thread IDs.
+ * @param init
+ */
+export type EpochClockOptions = {
+    pid?: number;
+    tid?: number;
+};
+/**
+ * Creates epoch-based clock utility.
+ * Epoch time has been the time since January 1, 1970 (UNIX epoch).
+ * Date.now gives epoch time in milliseconds.
+ * performance.now() + performance.timeOrigin when available is used for higher precision.
+ */
+export declare function epochClock(init?: EpochClockOptions): {
+    timeOriginMs: number;
+    pid: number;
+    tid: number;
+    epochNowUs: () => Microseconds;
+    msToUs: (ms: number) => Microseconds;
+    usToUs: (us: number) => Microseconds;
+    fromEpochMs: (ms: number) => Microseconds;
+    fromEpochUs: (us: number) => Microseconds;
+    fromPerfMs: (perfMs: Milliseconds) => Microseconds;
+    fromEntryStartTimeMs: (perfMs: Milliseconds) => Microseconds;
+    fromDateNowMs: (ms: number) => Microseconds;
+};
+export declare const defaultClock: {
+    timeOriginMs: number;
+    pid: number;
+    tid: number;
+    epochNowUs: () => Microseconds;
+    msToUs: (ms: number) => Microseconds;
+    usToUs: (us: number) => Microseconds;
+    fromEpochMs: (ms: number) => Microseconds;
+    fromEpochUs: (us: number) => Microseconds;
+    fromPerfMs: (perfMs: Milliseconds) => Microseconds;
+    fromEntryStartTimeMs: (perfMs: Milliseconds) => Microseconds;
+    fromDateNowMs: (ms: number) => Microseconds;
+};

package/src/lib/clock-epoch.js

@@ -0,0 +1,36 @@
+import process from 'node:process';
+import { threadId } from 'node:worker_threads';
+const msToUs = (ms) => Math.round(ms * 1000);
+const usToUs = (us) => Math.round(us);
+/**
+ * Creates epoch-based clock utility.
+ * Epoch time has been the time since January 1, 1970 (UNIX epoch).
+ * Date.now gives epoch time in milliseconds.
+ * performance.now() + performance.timeOrigin when available is used for higher precision.
+ */
+export function epochClock(init = {}) {
+    const pid = init.pid ?? process.pid;
+    const tid = init.tid ?? threadId;
+    const timeOriginMs = performance.timeOrigin;
+    const epochNowUs = () => msToUs(timeOriginMs + performance.now());
+    const fromEpochUs = usToUs;
+    const fromEpochMs = msToUs;
+    const fromPerfMs = (perfMs) => msToUs(timeOriginMs + perfMs);
+    const fromEntryStartTimeMs = fromPerfMs;
+    const fromDateNowMs = fromEpochMs;
+    return {
+        timeOriginMs,
+        pid,
+        tid,
+        epochNowUs,
+        msToUs,
+        usToUs,
+        fromEpochMs,
+        fromEpochUs,
+        fromPerfMs,
+        fromEntryStartTimeMs,
+        fromDateNowMs,
+    };
+}
+export const defaultClock = epochClock();
+//# sourceMappingURL=clock-epoch.js.map

package/src/lib/clock-epoch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-epoch.js","sourceRoot":"","sources":["../../../src/lib/clock-epoch.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAK/C,MAAM,MAAM,GAAG,CAAC,EAAU,EAAgB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AACnE,MAAM,MAAM,GAAG,CAAC,EAAU,EAAgB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAa5D;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,OAA0B,EAAE;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,QAAQ,CAAC;IAEjC,MAAM,YAAY,GAAG,WAAW,CAAC,UAAU,CAAC;IAE5C,MAAM,UAAU,GAAG,GAAiB,EAAE,CACpC,MAAM,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3C,MAAM,WAAW,GAAG,MAAM,CAAC;IAE3B,MAAM,WAAW,GAAG,MAAM,CAAC;IAE3B,MAAM,UAAU,GAAG,CAAC,MAAoB,EAAgB,EAAE,CACxD,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,CAAC;IAEhC,MAAM,oBAAoB,GAAG,UAAU,CAAC;IACxC,MAAM,aAAa,GAAG,WAAW,CAAC;IAElC,OAAO;QACL,YAAY;QACZ,GAAG;QACH,GAAG;QAEH,UAAU;QACV,MAAM;QACN,MAAM;QAEN,WAAW;QACX,WAAW;QACX,UAAU;QACV,oBAAoB;QACpB,aAAa;KACd,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,EAAE,CAAC"}

package/src/lib/performance-observer.d.ts

@@ -0,0 +1,18 @@
+import { type PerformanceEntry } from 'node:perf_hooks';
+import type { Buffered, Encoder, Observer, Sink } from './sink-source.types.js';
+export declare const DEFAULT_FLUSH_THRESHOLD = 20;
+export type PerformanceObserverOptions<T> = {
+    sink: Sink<T, unknown>;
+    encode: (entry: PerformanceEntry) => T[];
+    buffered?: boolean;
+    flushThreshold?: number;
+};
+export declare class PerformanceObserverSink<T> implements Observer, Buffered, Encoder<PerformanceEntry, T[]> {
+    #private;
+    constructor(options: PerformanceObserverOptions<T>);
+    encode(entry: PerformanceEntry): T[];
+    subscribe(): void;
+    flush(entriesToProcess?: PerformanceEntry[]): void;
+    unsubscribe(): void;
+    isSubscribed(): boolean;
+}

package/src/lib/performance-observer.js

@@ -0,0 +1,63 @@
+import { PerformanceObserver, performance, } from 'node:perf_hooks';
+export const DEFAULT_FLUSH_THRESHOLD = 20;
+export class PerformanceObserverSink {
+    #encode;
+    #buffered;
+    #flushThreshold;
+    #sink;
+    #observer;
+    #observedTypes = ['mark', 'measure'];
+    #getEntries = (list) => this.#observedTypes.flatMap(t => list.getEntriesByType(t));
+    #observedCount = 0;
+    constructor(options) {
+        this.#encode = options.encode;
+        this.#sink = options.sink;
+        this.#buffered = options.buffered ?? false;
+        this.#flushThreshold = options.flushThreshold ?? DEFAULT_FLUSH_THRESHOLD;
+    }
+    encode(entry) {
+        return this.#encode(entry);
+    }
+    subscribe() {
+        if (this.#observer) {
+            return;
+        }
+        this.#observer = new PerformanceObserver(list => {
+            const entries = this.#getEntries(list);
+            this.#observedCount += entries.length;
+            if (this.#observedCount >= this.#flushThreshold) {
+                this.flush(entries);
+            }
+        });
+        this.#observer.observe({
+            entryTypes: this.#observedTypes,
+            buffered: this.#buffered,
+        });
+    }
+    flush(entriesToProcess) {
+        if (!this.#observer) {
+            return;
+        }
+        const entries = entriesToProcess || this.#getEntries(performance);
+        entries.forEach(entry => {
+            const encoded = this.encode(entry);
+            encoded.forEach(item => {
+                this.#sink.write(item);
+            });
+        });
+        // In real PerformanceObserver, entries remain in the global buffer
+        // They are only cleared when explicitly requested via performance.clearMarks/clearMeasures
+        this.#observedCount = 0;
+    }
+    unsubscribe() {
+        if (!this.#observer) {
+            return;
+        }
+        this.#observer?.disconnect();
+        this.#observer = undefined;
+    }
+    isSubscribed() {
+        return this.#observer !== undefined;
+    }
+}
+//# sourceMappingURL=performance-observer.js.map

package/src/lib/performance-observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-observer.js","sourceRoot":"","sources":["../../../src/lib/performance-observer.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,mBAAmB,EAEnB,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAGzB,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAS1C,MAAM,OAAO,uBAAuB;IAGlC,OAAO,CAAmC;IAC1C,SAAS,CAAU;IACnB,eAAe,CAAS;IACxB,KAAK,CAAmB;IACxB,SAAS,CAAkC;IAC3C,cAAc,GAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClD,WAAW,GAAG,CAAC,IAAkC,EAAE,EAAE,CACnD,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,cAAc,GAAW,CAAC,CAAC;IAE3B,YAAY,OAAsC;QAChD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;QAC3C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,cAAc,IAAI,uBAAuB,CAAC;IAC3E,CAAC;IAED,MAAM,CAAC,KAAuB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,SAAS;QACP,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE;YAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;YACtC,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBAChD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACtB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YACrB,UAAU,EAAE,IAAI,CAAC,cAAc;YAC/B,QAAQ,EAAE,IAAI,CAAC,SAAS;SACzB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,gBAAqC;QACzC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,gBAAgB,IAAI,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QAClE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;YACtB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;gBACrB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,mEAAmE;QACnE,2FAA2F;QAE3F,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,WAAW;QACT,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;IACtC,CAAC;CACF"}

package/src/lib/sink-source.types.d.ts

@@ -0,0 +1,43 @@
+export type Encoder<I, O> = {
+    encode: (input: I) => O;
+};
+export type Decoder<O, I> = {
+    decode: (output: O) => I;
+};
+export type Sink<I, O> = {
+    open: () => void;
+    write: (input: I) => void;
+    close: () => void;
+    isClosed: () => boolean;
+} & Encoder<I, O>;
+export type Buffered = {
+    flush: () => void;
+};
+export type BufferedSink<I, O> = Sink<I, O> & Buffered;
+export type Source<I, O = unknown> = {
+    read?: () => O;
+    decode?: (input: I) => O;
+};
+export type Observer = {
+    subscribe: () => void;
+    unsubscribe: () => void;
+    isSubscribed: () => boolean;
+};
+export type Recoverable = {
+    recover: () => RecoverResult;
+    repack: () => void;
+    finalize: () => void;
+};
+export type RecoverResult<T = unknown> = {
+    records: T[];
+    errors: {
+        lineNo: number;
+        line: string;
+        error: Error;
+    }[];
+    partialTail: string | null;
+};
+export type RecoverOptions = {
+    keepInvalid?: boolean;
+};
+export type Output<I, O> = {} & BufferedSink<I, O>;

package/src/lib/sink-source.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sink-source.types.js.map

package/src/lib/sink-source.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink-source.types.js","sourceRoot":"","sources":["../../../src/lib/sink-source.types.ts"],"names":[],"mappings":""}

package/src/lib/user-timing-extensibility-api-utils.d.ts

@@ -0,0 +1,72 @@
+import type { DevToolsColor, DevToolsProperties, MarkOptionsWithDevtools, MarkerPayload, MeasureOptionsWithDevtools, TrackEntryPayload } from './user-timing-extensibility-api.type.js';
+export declare function mergePropertiesWithOverwrite(baseProperties: DevToolsProperties | undefined, overrideProperties?: DevToolsProperties | undefined): [string, string | number | boolean | object | undefined][];
+export declare function markerPayload(options?: Omit<MarkerPayload, 'dataType'>): {
+    color?: DevToolsColor;
+    tooltipText?: string;
+    properties?: DevToolsProperties;
+    dataType: "marker";
+};
+export declare function trackEntryPayload(options: Omit<TrackEntryPayload, 'dataType'>): {
+    color?: DevToolsColor | undefined;
+    tooltipText?: string | undefined;
+    properties?: DevToolsProperties | undefined;
+    trackGroup?: string | undefined;
+    dataType: "track-entry";
+    track: string;
+};
+export declare function markerErrorPayload<T extends DevToolsColor>(options?: Omit<MarkerPayload, 'dataType' | 'color'>): {
+    tooltipText?: string;
+    properties?: DevToolsProperties;
+    dataType: "marker";
+    color: T;
+};
+export declare function trackEntryErrorPayload<T extends string, C extends DevToolsColor>(options: Omit<TrackEntryPayload, 'color' | 'dataType'> & {
+    track: T;
+    color?: C;
+}): {
+    tooltipText?: string | undefined;
+    properties?: DevToolsProperties | undefined;
+    trackGroup?: string | undefined;
+    dataType: "track-entry";
+    color: DevToolsColor;
+    track: T;
+};
+export declare function errorToDevToolsProperties(e: unknown): (["Error Type", string] | ["Error Message", string])[];
+export declare function errorToEntryMeta(e: unknown, options?: {
+    tooltipText?: string;
+    properties?: DevToolsProperties;
+}): {
+    tooltipText?: string | undefined;
+    properties: [string, string | number | boolean | object | undefined][];
+};
+export declare function errorToTrackEntryPayload<T extends string>(error: unknown, detail: Omit<TrackEntryPayload, 'color' | 'dataType'> & {
+    track: T;
+}): {
+    tooltipText?: string | undefined;
+    properties: [string, string | number | boolean | object | undefined][];
+    track: T;
+    trackGroup?: string | undefined;
+    dataType: "track-entry";
+    color: "error";
+};
+export declare function errorToMarkerPayload(error: unknown, detail?: Omit<MarkerPayload, 'color' | 'dataType'>): {
+    tooltipText?: string | undefined;
+    properties: [string, string | number | boolean | object | undefined][];
+    dataType: "marker";
+    color: "error";
+};
+/**
+ * asOptions wraps a DevTools payload into the `detail` property of User Timing entry options.
+ *
+ * @example
+ * profiler.mark('mark', asOptions({
+ *   dataType: 'marker',
+ *   color: 'error',
+ *   tooltipText: 'This is a marker',
+ *   properties: [
+ *     ['str', 'This is a detail property']
+ *   ],
+ * }));
+ */
+export declare function asOptions<T extends MarkerPayload>(devtools?: T | null): MarkOptionsWithDevtools<T>;
+export declare function asOptions<T extends TrackEntryPayload>(devtools?: T | null): MeasureOptionsWithDevtools<T>;

package/src/lib/user-timing-extensibility-api-utils.js

@@ -0,0 +1,80 @@
+const dataTypeTrackEntry = 'track-entry';
+const dataTypeMarker = 'marker';
+export function mergePropertiesWithOverwrite(baseProperties, overrideProperties) {
+    return [
+        ...new Map([...(baseProperties ?? []), ...(overrideProperties ?? [])]),
+    ];
+}
+export function markerPayload(options) {
+    return {
+        dataType: dataTypeMarker,
+        ...options,
+    };
+}
+export function trackEntryPayload(options) {
+    const { track, ...rest } = options;
+    return {
+        dataType: dataTypeTrackEntry,
+        track,
+        ...rest,
+    };
+}
+export function markerErrorPayload(options) {
+    return {
+        dataType: dataTypeMarker,
+        color: 'error',
+        ...options,
+    };
+}
+export function trackEntryErrorPayload(options) {
+    const { track, color = 'error', ...restOptions } = options;
+    return {
+        dataType: dataTypeTrackEntry,
+        color,
+        track,
+        ...restOptions,
+    };
+}
+export function errorToDevToolsProperties(e) {
+    const name = e instanceof Error ? e.name : 'UnknownError';
+    const message = e instanceof Error ? e.message : String(e);
+    return [
+        ['Error Type', name],
+        ['Error Message', message],
+    ];
+}
+export function errorToEntryMeta(e, options) {
+    const { properties, tooltipText } = options ?? {};
+    const props = mergePropertiesWithOverwrite(errorToDevToolsProperties(e), properties);
+    return {
+        properties: props,
+        ...(tooltipText ? { tooltipText } : {}),
+    };
+}
+export function errorToTrackEntryPayload(error, detail) {
+    const { properties, tooltipText, ...trackPayload } = detail;
+    return {
+        dataType: dataTypeTrackEntry,
+        color: 'error',
+        ...trackPayload,
+        ...errorToEntryMeta(error, {
+            properties,
+            tooltipText,
+        }),
+    };
+}
+export function errorToMarkerPayload(error, detail) {
+    const { properties, tooltipText } = detail ?? {};
+    return {
+        dataType: dataTypeMarker,
+        color: 'error',
+        ...errorToEntryMeta(error, {
+            properties,
+            tooltipText,
+        }),
+    };
+}
+export function asOptions(devtools) {
+    return devtools == null ? { detail: {} } : { detail: { devtools } };
+}
+//# sourceMappingURL=user-timing-extensibility-api-utils.js.map

package/src/lib/user-timing-extensibility-api-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-timing-extensibility-api-utils.js","sourceRoot":"","sources":["../../../src/lib/user-timing-extensibility-api-utils.ts"],"names":[],"mappings":"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"}

package/src/lib/user-timing-extensibility-api.type.d.ts

@@ -0,0 +1,128 @@
+import type { MarkOptions, MeasureOptions } from 'node:perf_hooks';
+/**
+ * Color options for feedback states in DevTools.
+ * Used for error and warning states on marker and track entries.
+ * @example
+ * - 'error' - red
+ * - 'warning' - yellow
+ */
+export type DevToolsFeedbackColor = 'error' | 'warning';
+/**
+ * Color options for action states in DevTools.
+ * Used for valid states on marker and track entries.
+ * @example
+ * - 'primary' - blue (default)
+ * - 'primary-dark' - dark blue
+ * - 'primary-light' - light blue
+ * - 'secondary' - purple
+ * - 'secondary-dark' - dark purple
+ * - 'secondary-light' - light purple
+ * - 'tertiary' - green
+ * - 'tertiary-dark' - dark green
+ * - 'tertiary-light' - light green
+ */
+export type DevToolsActionColor = 'primary' | 'primary-dark' | 'primary-light' | 'secondary' | 'secondary-dark' | 'secondary-light' | 'tertiary' | 'tertiary-dark' | 'tertiary-light';
+/**
+ * Union type of all available DevTools color options.
+ */
+export type DevToolsColor = DevToolsFeedbackColor | DevToolsActionColor;
+/**
+ * Array of key-value pairs for detailed DevTools properties.
+ */
+export type DevToolsProperties = [
+    key: string,
+    value: string | number | boolean | object | undefined
+][];
+/**
+ * EntryMeta is used to store metadata about a track entry.
+ * @property {string} [tooltipText] - Short description for tooltip on hover
+ * @property {DevToolsProperties} [properties] - Key-value pairs for detailed view on click.
+ * It provides better styling of values including features like automatic links rendering.
+ */
+export type EntryMeta = {
+    tooltipText?: string;
+    properties?: DevToolsProperties;
+};
+/**
+ * Styling options for track entries in DevTools.
+ * @property {DevToolsColor} [color] - rendered color of background and border, defaults to "primary"
+ */
+export type TrackStyle = {
+    color?: DevToolsColor;
+};
+/**
+ * Metadata for organizing track entries in DevTools.
+ * @property {string} track - Name of the custom track
+ * @property {string} [trackGroup] - Group for organizing tracks
+ */
+export type TrackMeta = {
+    track: string;
+    trackGroup?: string;
+};
+/**
+ * Base type combining entry metadata and styling for DevTools tracks.
+ */
+export type TrackBase = EntryMeta & TrackStyle;
+/**
+ * Payload for track entries in DevTools Performance panel.
+ * @property {'track-entry'} [dataType] - Defaults to "track-entry"
+ *
+ * This type is visible in a custom track with name defined in `track` property.
+ */
+export type TrackEntryPayload = {
+    dataType?: 'track-entry';
+} & TrackBase & TrackMeta;
+/**
+ * Payload for marker entries in DevTools Performance panel.
+ * @property {'marker'} dataType - Identifies as a marker
+ * This type is visible as a marker on top of all tracks and in addition creates a vertical line spanning all lanes in the performance palen.
+ */
+export type MarkerPayload = {
+    dataType: 'marker';
+} & TrackBase;
+/**
+ * Utility type that forces a color property to be 'error'.
+ */
+export type WithErrorColor<T extends {
+    color?: DevToolsColor;
+}> = Omit<T, 'color'> & {
+    color: 'error';
+};
+/**
+ * Utility type that adds an optional devtools payload property.
+ */
+export type WithDevToolsPayload<T extends TrackEntryPayload | MarkerPayload> = {
+    devtools?: T;
+};
+/**
+ * Extended MarkOptions that supports DevTools payload in detail.
+ * @example
+ * const options: MarkOptionsWithDevtools = {
+ *    detail: {
+ *      devtools: {
+ *        dataType: 'marker',
+ *        color: 'error',
+ *      },
+ *   },
+ * }
+ * profiler.mark('start-program', options);
+ */
+export type MarkOptionsWithDevtools<T extends TrackEntryPayload | MarkerPayload> = {
+    detail?: WithDevToolsPayload<T>;
+} & Omit<MarkOptions, 'detail'>;
+/**
+ * Extended MeasureOptions that supports DevTools payload in detail.
+ * @example
+ * const options: MeasureOptionsWithDevtools = {
+ *   detail: {
+ *     devtools: {
+ *       dataType: 'track-entry',
+ *       color: 'primary',
+ *       }
+ *     }
+ *   }
+ *   profiler.measure('load-program', 'start-program', 'end-program', options);
+ */
+export type MeasureOptionsWithDevtools<T extends TrackEntryPayload> = {
+    detail?: WithDevToolsPayload<T>;
+} & Omit<MeasureOptions, 'detail'>;

package/src/lib/user-timing-extensibility-api.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=user-timing-extensibility-api.type.js.map

package/src/lib/user-timing-extensibility-api.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-timing-extensibility-api.type.js","sourceRoot":"","sources":["../../../src/lib/user-timing-extensibility-api.type.ts"],"names":[],"mappings":""}