@code-pushup/utils 0.104.0 → 0.106.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/utils",
-  "version": "0.104.0",
+  "version": "0.106.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.104.0",
+    "@code-pushup/models": "0.106.0",
     "ansis": "^3.3.0",
     "build-md": "^0.4.2",
     "bundle-require": "^5.1.0",

package/src/index.d.ts

@@ -17,8 +17,8 @@ export { hasNoNullableProps, isPromiseFulfilledResult, isPromiseRejectedResult,
 export { interpolate } from './lib/interpolate.js';
 export { Logger, logger } from './lib/logger.js';
 export { mergeConfigs } from './lib/merge-configs.js';
-export { addIndex, ContextValidationError, createCategoryRefs, expandAuditsForUrls, expandCategoryRefs, expandGroupsForUrls, removeIndex, shouldExpandForUrls, validateUrlContext, } from './lib/plugin-url-aggregation.js';
-export { getUrlIdentifier, normalizeUrlInput, type PluginUrlContext, } from './lib/plugin-url-config.js';
+export { addIndex, expandAuditsForUrls, expandCategoryRefs, expandGroupsForUrls, extractGroupSlugs, shouldExpandForUrls, } from './lib/plugin-url-aggregation.js';
+export { getUrlIdentifier, normalizeUrlInput, pluginUrlContextSchema, type PluginUrlContext, } from './lib/plugin-url-config.js';
 export { asyncSequential, groupByStatus, settlePromise, } from './lib/promises.js';
 export { generateRandomId } from './lib/random.js';
 export { CODE_PUSHUP_DOMAIN, CODE_PUSHUP_UNICODE_LOGO, FOOTER_PREFIX, README_LINK, } from './lib/reports/constants.js';

package/src/index.js

@@ -17,8 +17,8 @@ export { hasNoNullableProps, isPromiseFulfilledResult, isPromiseRejectedResult,
 export { interpolate } from './lib/interpolate.js';
 export { Logger, logger } from './lib/logger.js';
 export { mergeConfigs } from './lib/merge-configs.js';
-export { addIndex, ContextValidationError, createCategoryRefs, expandAuditsForUrls, expandCategoryRefs, expandGroupsForUrls, removeIndex, shouldExpandForUrls, validateUrlContext, } from './lib/plugin-url-aggregation.js';
-export { getUrlIdentifier, normalizeUrlInput, } from './lib/plugin-url-config.js';
+export { addIndex, expandAuditsForUrls, expandCategoryRefs, expandGroupsForUrls, extractGroupSlugs, shouldExpandForUrls, } from './lib/plugin-url-aggregation.js';
+export { getUrlIdentifier, normalizeUrlInput, pluginUrlContextSchema, } from './lib/plugin-url-config.js';
 export { asyncSequential, groupByStatus, settlePromise, } from './lib/promises.js';
 export { generateRandomId } from './lib/random.js';
 export { CODE_PUSHUP_DOMAIN, CODE_PUSHUP_UNICODE_LOGO, FOOTER_PREFIX, README_LINK, } from './lib/reports/constants.js';

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,oBAAoB,EACpB,SAAS,EACT,cAAc,EACd,WAAW,EACX,SAAS,GACV,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,mBAAmB,EAEnB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAa,MAAM,eAAe,CAAC;AAC9E,OAAO,EACL,kBAAkB,EAClB,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,cAAc,EACd,YAAY,GAIb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,uBAAuB,EACvB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,cAAc,EACd,aAAa,EACb,wBAAwB,EACxB,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,qBAAqB,EACrB,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,GAEd,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,aAAa,EACb,UAAU,EACV,wBAAwB,EACxB,YAAY,EACZ,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,QAAQ,GACT,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,aAAa,EACb,WAAW,GACZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EACL,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAMtD,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,cAAc,6BAA6B,CAAC;AAC5C,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,4BAA4B,EAC5B,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,cAAc,EACd,UAAU,GAEX,MAAM,oBAAoB,CAAC"}

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/plugin-url-aggregation.d.ts

@@ -1,14 +1,14 @@
-import type { Audit, CategoryRef, Group, PluginConfig } from '@code-pushup/models';
+import type { Audit, CategoryRef, Group } from '@code-pushup/models';
 import { type PluginUrlContext } from './plugin-url-config.js';
 export declare function shouldExpandForUrls(urlCount: number): boolean;
 export declare function addIndex(slug: string, index: number): string;
 export declare function removeIndex(slug: string): string;
+export declare function extractGroupSlugs(groups: Group[]): string[];
 export declare function resolveUrlWeight(weights: PluginUrlContext['weights'], index: number, userDefinedWeight?: number): number;
 export declare function expandAuditsForUrls(audits: Audit[], urls: string[]): Audit[];
 export declare function expandGroupsForUrls(groups: Group[], urls: string[]): Group[];
-export declare function createCategoryRefs(groupSlug: string, pluginSlug: string, context: PluginUrlContext): CategoryRef[];
-export declare function expandCategoryRefs(ref: CategoryRef, context: PluginUrlContext): CategoryRef[];
-export declare class ContextValidationError extends Error {
-    constructor(message: string);
-}
-export declare function validateUrlContext(context: PluginConfig['context']): asserts context is PluginUrlContext;
+type CategoryRefInput = Omit<CategoryRef, 'weight'> & {
+    weight?: number;
+};
+export declare function expandCategoryRefs(ref: CategoryRefInput, context: PluginUrlContext): CategoryRef[];
+export {};

package/src/lib/plugin-url-aggregation.js

@@ -8,8 +8,16 @@ export function addIndex(slug, index) {
 export function removeIndex(slug) {
     return slug.replace(/-\d+$/, '');
 }
+export function extractGroupSlugs(groups) {
+    const slugs = groups.map(({ slug }) => removeIndex(slug));
+    return [...new Set(slugs)];
+}
 export function resolveUrlWeight(weights, index, userDefinedWeight) {
-    return weights[index + 1] ?? userDefinedWeight ?? 1;
+    const urlWeight = weights[index + 1] ?? 1;
+    if (userDefinedWeight == null) {
+        return urlWeight;
+    }
+    return (urlWeight + userDefinedWeight) / 2;
 }
 export function expandAuditsForUrls(audits, urls) {
     return urls.flatMap((url, index) => audits.map(audit => ({
@@ -29,16 +37,6 @@ export function expandGroupsForUrls(groups, urls) {
         })),
     })));
 }
-export function createCategoryRefs(groupSlug, pluginSlug, context) {
-    return Array.from({ length: context.urlCount }, (_, i) => ({
-        plugin: pluginSlug,
-        slug: shouldExpandForUrls(context.urlCount)
-            ? addIndex(groupSlug, i)
-            : groupSlug,
-        type: 'group',
-        weight: resolveUrlWeight(context.weights, i),
-    }));
-}
 export function expandCategoryRefs(ref, context) {
     return Array.from({ length: context.urlCount }, (_, i) => ({
         ...ref,
@@ -48,24 +46,4 @@ export function expandCategoryRefs(ref, context) {
         weight: resolveUrlWeight(context.weights, i, ref.weight),
     }));
 }
-export class ContextValidationError extends Error {
-    constructor(message) {
-        super(`Invalid plugin context: ${message}`);
-    }
-}
-export function validateUrlContext(context) {
-    if (!context || typeof context !== 'object') {
-        throw new ContextValidationError('must be an object');
-    }
-    const { urlCount, weights } = context;
-    if (typeof urlCount !== 'number' || urlCount < 0) {
-        throw new ContextValidationError('urlCount must be a non-negative number');
-    }
-    if (!weights || typeof weights !== 'object') {
-        throw new ContextValidationError('weights must be an object');
-    }
-    if (Object.keys(weights).length !== urlCount) {
-        throw new ContextValidationError('weights count must match urlCount');
-    }
-}
 //# sourceMappingURL=plugin-url-aggregation.js.map

package/src/lib/plugin-url-aggregation.js.map

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

package/src/lib/plugin-url-config.d.ts

@@ -1,8 +1,10 @@
-import type { PluginUrls } from '@code-pushup/models';
-export type PluginUrlContext = {
-    urlCount: number;
-    weights: Record<string, number>;
-};
+import { z } from 'zod';
+import { type PluginUrls } from '@code-pushup/models';
+export declare const pluginUrlContextSchema: z.ZodObject<{
+    urlCount: z.ZodNumber;
+    weights: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginUrlContext = z.infer<typeof pluginUrlContextSchema>;
 export declare const SINGLE_URL_THRESHOLD = 1;
 export declare function normalizeUrlInput(input: PluginUrls): {
     urls: string[];

package/src/lib/plugin-url-config.js

@@ -1,3 +1,14 @@
+import { z } from 'zod';
+import { nonnegativeNumberSchema, weightSchema, } from '@code-pushup/models';
+export const pluginUrlContextSchema = z
+    .object({
+    urlCount: nonnegativeNumberSchema,
+    weights: z.record(z.string(), weightSchema),
+})
+    .refine(({ urlCount, weights }) => Object.keys(weights).length === urlCount, {
+    message: 'weights count must match urlCount',
+})
+    .meta({ title: 'PluginUrlContext' });
 export const SINGLE_URL_THRESHOLD = 1;
 export function normalizeUrlInput(input) {
     if (typeof input === 'string') {

package/src/lib/plugin-url-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-url-config.js","sourceRoot":"","sources":["../../../src/lib/plugin-url-config.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IAIjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,CAAC,KAAK,CAAC;YACb,OAAO,EAAE;gBACP,QAAQ,EAAE,CAAC;gBACX,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE;aAClB;SACF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,KAAK;YACX,OAAO,EAAE;gBACP,QAAQ,EAAE,KAAK,CAAC,MAAM;gBACtB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;aAC7D;SACF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC;QACjC,OAAO,EAAE;YACP,QAAQ,EAAE,OAAO,CAAC,MAAM;YACxB,OAAO,EAAE,MAAM,CAAC,WAAW,CACzB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAChD;SACF;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,CAAC;QACH,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC9C,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC"}
+{"version":3,"file":"plugin-url-config.js","sourceRoot":"","sources":["../../../src/lib/plugin-url-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,uBAAuB,EACvB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,CAAC;IACN,QAAQ,EAAE,uBAAuB;IACjC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC;CAC5C,CAAC;KACD,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE;IAC3E,OAAO,EAAE,mCAAmC;CAC7C,CAAC;KACD,IAAI,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;AAIvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IAIjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,CAAC,KAAK,CAAC;YACb,OAAO,EAAE;gBACP,QAAQ,EAAE,CAAC;gBACX,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE;aAClB;SACF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,KAAK;YACX,OAAO,EAAE;gBACP,QAAQ,EAAE,KAAK,CAAC,MAAM;gBACtB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;aAC7D;SACF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC;QACjC,OAAO,EAAE;YACP,QAAQ,EAAE,OAAO,CAAC,MAAM;YACxB,OAAO,EAAE,MAAM,CAAC,WAAW,CACzB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAChD;SACF;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,CAAC;QACH,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC9C,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC"}

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

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

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

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

@@ -141,3 +141,9 @@ export type MarkOptionsWithDevtools<T extends TrackEntryPayload | MarkerPayload>
 export type MeasureOptionsWithDevtools<T extends TrackEntryPayload> = {
     detail?: WithDevToolsPayload<T>;
 } & Omit<MeasureOptions, 'detail'>;
+/**
+ * Detail object containing DevTools payload for user timing events.
+ * Extends WithDevToolsPayload to include track entry or marker payload.
+ * This can be used in trace event arguments to provide additional context in DevTools.
+ */
+export type UserTimingDetail = WithDevToolsPayload<TrackEntryPayload | MarkerPayload>;