refactor: wip

Author: BioPhoton

packages/utils/src/lib/profiler/trace-file.type.ts

@@ -6,7 +6,9 @@ import type {
 /** DevTools payload type for trace events. */
 export type DevToolsPayload = TrackEntryPayload | MarkerPayload;
 
-/** Unified trace event type for Chrome DevTools trace format. */
+/**
+ * Unified trace event type for Chrome DevTools trace format.
+ */
 export type TraceEvent = {
   cat: string;
   ph: string;
@@ -24,66 +26,101 @@ export type TraceEvent = {
   };
 };
 
-// ─────────────────────────────────────────────────────────────
-// DevTools metadata and annotations
-// ─────────────────────────────────────────────────────────────
-
-/** Time window bounds in trace time units. */
+/**
+ * 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 trace entry. */
+/**
+ * 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 between two trace entries. */
+/**
+ * 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;
 };
 
-/** Time range annotated with a label. */
+/**
+ * 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. */
+/**
+ * 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. */
+/**
+ * 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 (labels, links, time ranges). */
+/**
+ * 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 in DevTools export. */
+/**
+ * Modifications made to trace data or UI in DevTools export
+ */
 export type Modifications = {
   entriesModifications: EntriesModifications;
   initialBreadcrumb: InitialBreadcrumb;
   annotations: Annotations;
 };
 
-/** Top-level metadata for Chrome DevTools trace files. */
+/**
+ * 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;
@@ -99,18 +136,25 @@ export type TraceMetadata = {
   networkThrottling?: string;
   enhancedTraceVersion?: number;
 
-  /** DevTools may add new fields over time */
+  /** Allow additional custom metadata properties */
   [key: string]: unknown;
 };
 
-/** Structured container for trace events with metadata. */
+/**
+ * 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: array of events or structured container. */
+/**
+ * Trace file format - either an array of events or a structured container.
+ */
 export type TraceFile = TraceEventContainer;
 
 /** Options for creating a tracing started in browser event. */