@code-pushup/utils 0.103.0 → 0.105.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/utils",
-  "version": "0.103.0",
+  "version": "0.105.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",
@@ -24,10 +24,10 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=17.0.0"
+    "node": ">=18.2.0"
   },
   "dependencies": {
-    "@code-pushup/models": "0.103.0",
+    "@code-pushup/models": "0.105.0",
     "ansis": "^3.3.0",
     "build-md": "^0.4.2",
     "bundle-require": "^5.1.0",

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

@@ -26,6 +26,11 @@ export declare function epochClock(init?: EpochClockOptions): {
     fromEpochMs: (ms: number) => Microseconds;
     fromEpochUs: (us: number) => Microseconds;
     fromPerfMs: (perfMs: Milliseconds) => Microseconds;
+    fromEntry: (entry: {
+        startTime: Milliseconds;
+        entryType: string;
+        duration: Milliseconds;
+    }, useEndTime?: boolean) => number;
     fromEntryStartTimeMs: (perfMs: Milliseconds) => Microseconds;
     fromDateNowMs: (ms: number) => Microseconds;
 };
@@ -39,6 +44,11 @@ export declare const defaultClock: {
     fromEpochMs: (ms: number) => Microseconds;
     fromEpochUs: (us: number) => Microseconds;
     fromPerfMs: (perfMs: Milliseconds) => Microseconds;
+    fromEntry: (entry: {
+        startTime: Milliseconds;
+        entryType: string;
+        duration: Milliseconds;
+    }, useEndTime?: boolean) => number;
     fromEntryStartTimeMs: (perfMs: Milliseconds) => Microseconds;
     fromDateNowMs: (ms: number) => Microseconds;
 };

package/src/lib/clock-epoch.js

@@ -17,6 +17,8 @@ export function epochClock(init = {}) {
     const fromEpochMs = msToUs;
     const fromPerfMs = (perfMs) => msToUs(timeOriginMs + perfMs);
     const fromEntryStartTimeMs = fromPerfMs;
+    const fromEntry = (entry, useEndTime = false) => fromPerfMs(entry.startTime +
+        (entry.entryType === 'measure' && useEndTime ? entry.duration : 0));
     const fromDateNowMs = fromEpochMs;
     return {
         timeOriginMs,
@@ -28,6 +30,7 @@ export function epochClock(init = {}) {
         fromEpochMs,
         fromEpochUs,
         fromPerfMs,
+        fromEntry,
         fromEntryStartTimeMs,
         fromDateNowMs,
     };

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

@@ -1 +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"}
+{"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,SAAS,GAAG,CAChB,KAIC,EACD,UAAU,GAAG,KAAK,EAClB,EAAE,CACF,UAAU,CACR,KAAK,CAAC,SAAS;QACb,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CACrE,CAAC;IACJ,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,SAAS;QACT,oBAAoB;QACpB,aAAa;KACd,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,EAAE,CAAC"}

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

@@ -1,5 +1,5 @@
 import { type PerformanceEntry } from 'node:perf_hooks';
-import type { Buffered, Encoder, Observer, Sink } from './sink-source.types.js';
+import type { Buffered, Encoder, Observer, Sink } from './sink-source.type';
 export declare const DEFAULT_FLUSH_THRESHOLD = 20;
 export type PerformanceObserverOptions<T> = {
     sink: Sink<T, unknown>;

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

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

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

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

package/src/lib/trace-file-utils.d.ts

@@ -0,0 +1,133 @@
+import type { PerformanceMark, PerformanceMeasure } from 'node:perf_hooks';
+import type { BeginEvent, CompleteEvent, EndEvent, InstantEvent, InstantEventArgs, InstantEventTracingStartedInBrowser, SpanEventArgs, TraceEvent, TraceEventContainer } from './trace-file.type.js';
+/**
+ * Generates a unique ID for linking begin and end span events in Chrome traces.
+ * @returns Object with local ID string for the id2 field
+ */
+export declare const nextId2: () => {
+    local: string;
+};
+/**
+ * Generates a unique frame tree node ID from process and thread IDs.
+ * @param pid - Process ID
+ * @param tid - Thread ID
+ * @returns Combined numeric ID
+ */
+export declare const frameTreeNodeId: (pid: number, tid: number) => number;
+/**
+ * Generates a frame name string from process and thread IDs.
+ * @param pid - Process ID
+ * @param tid - Thread ID
+ * @returns Formatted frame name
+ */
+export declare const frameName: (pid: number, tid: number) => string;
+/**
+ * Creates an instant trace event for marking a point in time.
+ * @param opt - Event configuration options
+ * @returns InstantEvent object
+ */
+export declare const getInstantEvent: (opt: {
+    name: string;
+    ts?: number;
+    pid?: number;
+    tid?: number;
+    args?: InstantEventArgs;
+}) => InstantEvent;
+/**
+ * Creates a start tracing event with frame information.
+ * This event is needed at the beginning of the traceEvents array to make tell the UI profiling has started, and it should visualize the data.
+ * @param opt - Tracing configuration options
+ * @returns StartTracingEvent object
+ */
+export declare const getInstantEventTracingStartedInBrowser: (opt: {
+    url: string;
+    ts?: number;
+    pid?: number;
+    tid?: number;
+}) => InstantEventTracingStartedInBrowser;
+/**
+ * Creates a complete trace event with duration.
+ * @param opt - Event configuration with name and duration
+ * @returns CompleteEvent object
+ */
+export declare const getCompleteEvent: (opt: {
+    name: string;
+    dur: number;
+    ts?: number;
+    pid?: number;
+    tid?: number;
+}) => CompleteEvent;
+/** Options for creating span events */
+type SpanOpt = {
+    name: string;
+    id2: {
+        local: string;
+    };
+    ts?: number;
+    pid?: number;
+    tid?: number;
+    args?: SpanEventArgs;
+};
+/**
+ * Creates a begin span event.
+ * @param ph - Phase ('b' for begin)
+ * @param opt - Span event options
+ * @returns BeginEvent object
+ */
+export declare function getSpanEvent(ph: 'b', opt: SpanOpt): BeginEvent;
+/**
+ * Creates an end span event.
+ * @param ph - Phase ('e' for end)
+ * @param opt - Span event options
+ * @returns EndEvent object
+ */
+export declare function getSpanEvent(ph: 'e', opt: SpanOpt): EndEvent;
+/**
+ * Creates a pair of begin and end span events.
+ * @param opt - Span configuration with start/end timestamps
+ * @returns Tuple of BeginEvent and EndEvent
+ */
+export declare const getSpan: (opt: {
+    name: string;
+    tsB: number;
+    tsE: number;
+    id2?: {
+        local: string;
+    };
+    pid?: number;
+    tid?: number;
+    args?: SpanEventArgs;
+    tsMarkerPadding?: number;
+}) => [BeginEvent, EndEvent];
+/**
+ * Converts a PerformanceMark to an instant trace event.
+ * @param entry - Performance mark entry
+ * @param opt - Optional overrides for name, pid, and tid
+ * @returns InstantEvent object
+ */
+export declare const markToInstantEvent: (entry: PerformanceMark, opt?: {
+    name?: string;
+    pid?: number;
+    tid?: number;
+}) => InstantEvent;
+/**
+ * Converts a PerformanceMeasure to a pair of span events.
+ * @param entry - Performance measure entry
+ * @param opt - Optional overrides for name, pid, and tid
+ * @returns Tuple of BeginEvent and EndEvent
+ */
+export declare const measureToSpanEvents: (entry: PerformanceMeasure, opt?: {
+    name?: string;
+    pid?: number;
+    tid?: number;
+}) => [BeginEvent, EndEvent];
+/**
+ * Creates a complete trace file container with metadata.
+ * @param opt - Trace file configuration
+ * @returns TraceEventContainer with events and metadata
+ */
+export declare const getTraceFile: (opt: {
+    traceEvents: TraceEvent[];
+    startTime?: string;
+}) => TraceEventContainer;
+export {};

package/src/lib/trace-file-utils.js

@@ -0,0 +1,179 @@
+import os from 'node:os';
+import { threadId } from 'node:worker_threads';
+import { defaultClock } from './clock-epoch.js';
+/** Global counter for generating unique span IDs within a trace */
+// eslint-disable-next-line functional/no-let
+let id2Count = 0;
+/**
+ * Generates a unique ID for linking begin and end span events in Chrome traces.
+ * @returns Object with local ID string for the id2 field
+ */
+export const nextId2 = () => ({ local: `0x${++id2Count}` });
+/**
+ * Provides default values for trace event properties.
+ * @param opt - Optional overrides for pid, tid, and timestamp
+ * @returns Object with pid, tid, and timestamp
+ */
+const defaults = (opt) => ({
+    pid: opt?.pid ?? process.pid,
+    tid: opt?.tid ?? threadId,
+    ts: opt?.ts ?? defaultClock.epochNowUs(),
+});
+/**
+ * Generates a unique frame tree node ID from process and thread IDs.
+ * @param pid - Process ID
+ * @param tid - Thread ID
+ * @returns Combined numeric ID
+ */
+export const frameTreeNodeId = (pid, tid) => Number.parseInt(`${pid}0${tid}`, 10);
+/**
+ * Generates a frame name string from process and thread IDs.
+ * @param pid - Process ID
+ * @param tid - Thread ID
+ * @returns Formatted frame name
+ */
+export const frameName = (pid, tid) => `FRAME0P${pid}T${tid}`;
+/**
+ * Creates an instant trace event for marking a point in time.
+ * @param opt - Event configuration options
+ * @returns InstantEvent object
+ */
+export const getInstantEvent = (opt) => ({
+    cat: 'blink.user_timing',
+    ph: 'i',
+    name: opt.name,
+    ...defaults(opt),
+    args: opt.args ?? {},
+});
+/**
+ * Creates a start tracing event with frame information.
+ * This event is needed at the beginning of the traceEvents array to make tell the UI profiling has started, and it should visualize the data.
+ * @param opt - Tracing configuration options
+ * @returns StartTracingEvent object
+ */
+export const getInstantEventTracingStartedInBrowser = (opt) => {
+    const { pid, tid, ts } = defaults(opt);
+    const id = frameTreeNodeId(pid, tid);
+    return {
+        cat: 'devtools.timeline',
+        ph: 'i',
+        name: 'TracingStartedInBrowser',
+        pid,
+        tid,
+        ts,
+        args: {
+            data: {
+                frameTreeNodeId: id,
+                frames: [
+                    {
+                        frame: frameName(pid, tid),
+                        isInPrimaryMainFrame: true,
+                        isOutermostMainFrame: true,
+                        name: '',
+                        processId: pid,
+                        url: opt.url,
+                    },
+                ],
+                persistentIds: true,
+            },
+        },
+    };
+};
+/**
+ * Creates a complete trace event with duration.
+ * @param opt - Event configuration with name and duration
+ * @returns CompleteEvent object
+ */
+export const getCompleteEvent = (opt) => ({
+    cat: 'devtools.timeline',
+    ph: 'X',
+    name: opt.name,
+    dur: opt.dur,
+    ...defaults(opt),
+    args: {},
+});
+/**
+ * Creates a span event (begin or end).
+ * @param ph - Phase ('b' or 'e')
+ * @param opt - Span event options
+ * @returns SpanEvent object
+ */
+export function getSpanEvent(ph, opt) {
+    return {
+        cat: 'blink.user_timing',
+        ph,
+        name: opt.name,
+        id2: opt.id2,
+        ...defaults(opt),
+        args: opt.args?.data?.detail
+            ? { data: { detail: opt.args.data.detail } }
+            : {},
+    };
+}
+/**
+ * Creates a pair of begin and end span events.
+ * @param opt - Span configuration with start/end timestamps
+ * @returns Tuple of BeginEvent and EndEvent
+ */
+export const getSpan = (opt) => {
+    // tsMarkerPadding is here to make the measure slightly smaller so the markers align perfectly.
+    // Otherwise, the marker is visible at the start of the measure below the frame
+    //       No padding   Padding
+    // spans: ========   |======|
+    // marks: |      |
+    const pad = opt.tsMarkerPadding ?? 1;
+    // b|e need to share the same id2
+    const id2 = opt.id2 ?? nextId2();
+    return [
+        getSpanEvent('b', {
+            ...opt,
+            id2,
+            ts: opt.tsB + pad,
+        }),
+        getSpanEvent('e', {
+            ...opt,
+            id2,
+            ts: opt.tsE - pad,
+        }),
+    ];
+};
+/**
+ * Converts a PerformanceMark to an instant trace event.
+ * @param entry - Performance mark entry
+ * @param opt - Optional overrides for name, pid, and tid
+ * @returns InstantEvent object
+ */
+export const markToInstantEvent = (entry, opt) => getInstantEvent({
+    ...opt,
+    name: opt?.name ?? entry.name,
+    ts: defaultClock.fromEntry(entry),
+    args: entry.detail ? { detail: entry.detail } : undefined,
+});
+/**
+ * Converts a PerformanceMeasure to a pair of span events.
+ * @param entry - Performance measure entry
+ * @param opt - Optional overrides for name, pid, and tid
+ * @returns Tuple of BeginEvent and EndEvent
+ */
+export const measureToSpanEvents = (entry, opt) => getSpan({
+    ...opt,
+    name: opt?.name ?? entry.name,
+    tsB: defaultClock.fromEntry(entry),
+    tsE: defaultClock.fromEntry(entry, true),
+    args: entry.detail ? { data: { detail: entry.detail } } : undefined,
+});
+/**
+ * Creates a complete trace file container with metadata.
+ * @param opt - Trace file configuration
+ * @returns TraceEventContainer with events and metadata
+ */
+export const getTraceFile = (opt) => ({
+    traceEvents: opt.traceEvents,
+    displayTimeUnit: 'ms',
+    metadata: {
+        source: 'Node.js UserTiming',
+        startTime: opt.startTime ?? new Date().toISOString(),
+        hardwareConcurrency: os.cpus().length,
+    },
+});
+//# sourceMappingURL=trace-file-utils.js.map

package/src/lib/trace-file-utils.js.map

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

package/src/lib/trace-file.type.d.ts

@@ -0,0 +1,279 @@
+import type { UserTimingDetail } from './user-timing-extensibility-api.type.js';
+/**
+ * Arguments for instant trace events.
+ * @property {UserTimingDetail} [detail] - Optional user timing detail with DevTools payload
+ */
+export type InstantEventArgs = {
+    detail?: UserTimingDetail;
+} & {
+    [key: string]: unknown;
+};
+/**
+ * Arguments for span trace events (begin/end events).
+ * @property {object} [data] - Optional data object
+ * @property {UserTimingDetail} [data.detail] - Optional user timing detail with DevTools payload
+ */
+export type SpanEventArgs = {
+    data?: {
+        detail?: UserTimingDetail;
+    };
+} & {
+    [key: string]: unknown;
+};
+/**
+ * Arguments for complete trace events.
+ * @property {Record<string, unknown>} [detail] - Optional detail object with arbitrary properties
+ */
+export type CompleteEventArgs = {
+    detail?: Record<string, unknown>;
+};
+/**
+ * Arguments for start tracing events.
+ * @property {object} data - Tracing initialization data
+ * @property {number} data.frameTreeNodeId - Frame tree node identifier
+ * @property {Array} data.frames - Array of frame information
+ * @property {boolean} data.persistentIds - Whether IDs are persistent
+ */
+export type InstantEventTracingStartedInBrowserArgs = {
+    data: {
+        frameTreeNodeId: number;
+        frames: {
+            frame: string;
+            isInPrimaryMainFrame: boolean;
+            isOutermostMainFrame: boolean;
+            name: string;
+            processId: number;
+            url: string;
+        }[];
+        persistentIds: boolean;
+    };
+};
+/**
+ * Union type of all possible trace event arguments.
+ */
+export type TraceArgs = InstantEventArgs | SpanEventArgs | CompleteEventArgs | InstantEventTracingStartedInBrowserArgs;
+/**
+ * Base properties shared by all trace events.
+ * @property {string} cat - Event category
+ * @property {string} name - Event name
+ * @property {number} pid - Process ID
+ * @property {number} tid - Thread ID
+ * @property {number} ts - Timestamp in epoch microseconds
+ * @property {TraceArgs} [args] - Optional event arguments
+ */
+export type BaseTraceEvent = {
+    cat: string;
+    name: string;
+    pid: number;
+    tid: number;
+    ts: number;
+    args: TraceArgs;
+};
+/**
+ * Start tracing event for Chrome DevTools tracing.
+ */
+export type InstantEventTracingStartedInBrowser = BaseTraceEvent & {
+    cat: 'devtools.timeline';
+    ph: 'i';
+    name: 'TracingStartedInBrowser';
+    args: InstantEventTracingStartedInBrowserArgs;
+};
+/**
+ * Complete trace event with duration.
+ * Represents a complete operation with start time and duration.
+ * @property {'X'} ph - Phase indicator for complete events
+ * @property {number} dur - Duration in microseconds
+ */
+export type CompleteEvent = BaseTraceEvent & {
+    ph: 'X';
+    dur: number;
+};
+/**
+ * Instant trace event representing a single point in time.
+ * Used for user timing marks and other instantaneous events.
+ * @property {'blink.user_timing'} cat - Fixed category for user timing events
+ * @property {'i'} ph - Phase indicator for instant events
+ * @property {never} [dur] - Duration is not applicable for instant events
+ * @property {InstantEventArgs} [args] - Optional event arguments
+ */
+export type InstantEvent = Omit<BaseTraceEvent, 'cat' | 'args'> & {
+    cat: 'blink.user_timing';
+    ph: 'i';
+    dur?: never;
+    args: InstantEventArgs;
+};
+/**
+ * Core properties for span trace events (begin/end pairs).
+ * @property {object} id2 - Span identifier
+ * @property {string} id2.local - Local span ID (unique to the process, same for b and e events)
+ * @property {SpanEventArgs} [args] - Optional event arguments
+ */
+type SpanCore = Omit<BaseTraceEvent, 'args'> & {
+    id2: {
+        local: string;
+    };
+    args: SpanEventArgs;
+};
+/**
+ * Begin event for a span (paired with an end event).
+ * @property {'b'} ph - Phase indicator for begin events
+ * @property {never} [dur] - Duration is not applicable for begin events
+ */
+export type BeginEvent = SpanCore & {
+    ph: 'b';
+    dur?: never;
+};
+/**
+ * End event for a span (paired with a begin event).
+ * @property {'e'} ph - Phase indicator for end events
+ * @property {never} [dur] - Duration is not applicable for end events
+ */
+export type EndEvent = SpanCore & {
+    ph: 'e';
+    dur?: never;
+};
+/**
+ * Union type for span events (begin or end).
+ */
+export type SpanEvent = BeginEvent | EndEvent;
+/**
+ * Union type of all trace event types.
+ */
+export type TraceEvent = InstantEvent | CompleteEvent | SpanEvent | InstantEventTracingStartedInBrowser;
+/**
+ * Raw arguments format for trace events before processing.
+ * Either contains a detail string directly or nested in a data object.
+ */
+type RawArgs = {
+    detail?: string;
+    [key: string]: unknown;
+} | {
+    data?: {
+        detail?: string;
+    };
+    [key: string]: unknown;
+};
+/**
+ * Raw trace event format before type conversion.
+ * Similar to TraceEvent but with unprocessed arguments.
+ */
+export type TraceEventRaw = Omit<TraceEvent, 'args'> & {
+    args: RawArgs;
+};
+/**
+ * Time window bounds (min, max) in trace time units (e.g. microseconds).
+ * @property {number} min - Minimum timestamp in the window
+ * @property {number} max - Maximum timestamp in the window
+ * @property {number} range - Calculated range (max - min)
+ */
+export type BreadcrumbWindow = {
+    min: number;
+    max: number;
+    range: number;
+};
+/**
+ * Custom label for a specific trace entry.
+ * @property {number | string} entryId - ID or index of the trace entry
+ * @property {string} label - Label text for the entry
+ * @property {string} [color] - Optional display color for the label
+ */
+export type EntryLabel = {
+    entryId: number | string;
+    label: string;
+    color?: string;
+};
+/**
+ * Link or relation between two trace entries.
+ * @property {number | string} fromEntryId - Source entry ID for the link
+ * @property {number | string} toEntryId - Target entry ID for the link
+ * @property {string} [linkType] - Optional type or description of the link
+ */
+export type EntryLink = {
+    fromEntryId: number | string;
+    toEntryId: number | string;
+    linkType?: string;
+};
+/**
+ * A time range annotated with a label.
+ * @property {number} startTime - Start timestamp of the range (microseconds)
+ * @property {number} endTime - End timestamp of the range (microseconds)
+ * @property {string} label - Annotation label for the time range
+ * @property {string} [color] - Optional display color for the range
+ */
+export type LabelledTimeRange = {
+    startTime: number;
+    endTime: number;
+    label: string;
+    color?: string;
+};
+/**
+ * Hidden or expandable entries information.
+ * @property {unknown[]} hiddenEntries - IDs or indexes of hidden entries
+ * @property {unknown[]} expandableEntries - IDs or indexes of expandable entries
+ */
+export type EntriesModifications = {
+    hiddenEntries: unknown[];
+    expandableEntries: unknown[];
+};
+/**
+ * Initial breadcrumb information for time ranges and window.
+ * @property {BreadcrumbWindow} window - Time window bounds
+ * @property {unknown | null} child - Child breadcrumb or null
+ */
+export type InitialBreadcrumb = {
+    window: BreadcrumbWindow;
+    child: unknown | null;
+};
+/**
+ * Annotations such as labels and links between entries.
+ * @property {EntryLabel[]} entryLabels - Custom labels for entries
+ * @property {LabelledTimeRange[]} labelledTimeRanges - Time ranges annotated with labels
+ * @property {EntryLink[]} linksBetweenEntries - Links or relations between entries
+ */
+export type Annotations = {
+    entryLabels: EntryLabel[];
+    labelledTimeRanges: LabelledTimeRange[];
+    linksBetweenEntries: EntryLink[];
+};
+/**
+ * Modifications made to trace data or UI in DevTools export
+ */
+export type Modifications = {
+    entriesModifications: EntriesModifications;
+    initialBreadcrumb: InitialBreadcrumb;
+    annotations: Annotations;
+};
+/**
+ * Top-level metadata for a trace file exported by Chrome DevTools.
+ * DevTools may add new fields over time.
+ */
+export type TraceMetadata = {
+    /** Usually "DevTools" for exports from the Performance panel */
+    source: string;
+    /** ISO timestamp when trace was recorded */
+    startTime: string;
+    /** May be present when recorded with throttling settings */
+    hardwareConcurrency?: number;
+    /** Common fields found in DevTools traces */
+    cpuThrottling?: number;
+    networkThrottling?: string;
+    enhancedTraceVersion?: number;
+    /** Allow additional custom metadata properties */
+    [key: string]: unknown;
+};
+/**
+ * Structured container for trace events with metadata.
+ * @property {TraceEvent[]} traceEvents - Array of trace events
+ * @property {'ms' | 'ns'} [displayTimeUnit] - Time unit for display (milliseconds or nanoseconds)
+ * @property {TraceMetadata} [metadata] - Optional metadata about the trace
+ */
+export type TraceEventContainer = {
+    traceEvents: TraceEvent[];
+    displayTimeUnit?: 'ms' | 'ns';
+    metadata?: TraceMetadata;
+};
+/**
+ * Trace file format - either an array of events or a structured container.
+ */
+export type TraceFile = TraceEvent[] | TraceEventContainer;
+export {};

package/src/lib/trace-file.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trace-file.type.js.map