refactor: add js-docs

Author: John Doe

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

@@ -15,20 +15,48 @@ import type {
   TraceEventContainer,
 } from './trace-file.type.js';
 
-// eslint-disable-next-line functional/no-let
+/** Global counter for generating unique local IDs */
 let id2Count = 0;
+
+/**
+ * Generates a unique local ID for span events, to link start and end with a id.
+ * @returns Object with local ID string
+ */
 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?: number; tid?: number; ts?: number }) => ({
   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: number, tid: number) =>
   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: number, tid: number) => `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: {
   name: string;
   ts?: number;
@@ -43,6 +71,12 @@ export const getInstantEvent = (opt: {
   args: opt.args ?? {},
 });
 
+/**
+ * Creates a start tracing event with frame information.
+ * This event is needed to make events in general show up and also colores the track better.
+ * @param opt - Tracing configuration options
+ * @returns StartTracingEvent object
+ */
 export const getStartTracing = (opt: {
   url: string;
   ts?: number;
@@ -78,6 +112,11 @@ export const getStartTracing = (opt: {
   };
 };
 
+/**
+ * Creates a complete trace event with duration.
+ * @param opt - Event configuration with name and duration
+ * @returns CompleteEvent object
+ */
 export const getCompleteEvent = (opt: {
   name: string;
   dur: number;
@@ -93,6 +132,7 @@ export const getCompleteEvent = (opt: {
   args: {},
 });
 
+/** Options for creating span events */
 type SpanOpt = {
   name: string;
   id2: { local: string };
@@ -102,8 +142,26 @@ type SpanOpt = {
   args?: SpanEventArgs;
 };
 
+/**
+ * Creates a begin span event.
+ * @param ph - Phase ('b' for begin)
+ * @param opt - Span event options
+ * @returns BeginEvent object
+ */
 export 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 function getSpanEvent(ph: 'e', opt: SpanOpt): EndEvent;
+/**
+ * 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: 'b' | 'e', opt: SpanOpt): SpanEvent {
   return {
     cat: 'blink.user_timing',
@@ -117,6 +175,11 @@ export function getSpanEvent(ph: 'b' | 'e', opt: SpanOpt): SpanEvent {
   };
 }
 
+/**
+ * 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: {
   name: string;
   tsB: number;
@@ -150,6 +213,12 @@ export const getSpan = (opt: {
   ];
 };
 
+/**
+ * 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: PerformanceMark,
   opt?: { name?: string; pid?: number; tid?: number },
@@ -161,6 +230,12 @@ export const markToInstantEvent = (
     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: PerformanceMeasure,
   opt?: { name?: string; pid?: number; tid?: number },
@@ -173,6 +248,11 @@ export const measureToSpanEvents = (
     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: TraceEvent[];
   startTime?: string;