refactor: impl feedback

Author: John Doe

packages/utils/src/lib/clock-epoch.ts

@@ -42,8 +42,15 @@ export function epochClock(init: EpochClockOptions = {}) {
     msToUs(timeOriginMs + perfMs);
 
   const fromEntryStartTimeMs = fromPerfMs;
-  const fromEntry = (entry: PerformanceEntry, useEndTime = false) =>
-    defaultClock.fromPerfMs(
+  const fromEntry = (
+    entry: {
+      startTime: Milliseconds;
+      entryType: string;
+      duration: Milliseconds;
+    },
+    useEndTime = false,
+  ) =>
+    fromPerfMs(
       entry.startTime +
         (entry.entryType === 'measure' && useEndTime ? entry.duration : 0),
     );

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

@@ -8,20 +8,20 @@ import type {
   EndEvent,
   InstantEvent,
   InstantEventArgs,
+  InstantEventTracingStartedInBrowser,
   SpanEvent,
   SpanEventArgs,
-  StartTracingEvent,
   TraceEvent,
   TraceEventContainer,
 } from './trace-file.type.js';
 
-/** Global counter for generating unique local IDs */
+/** Global counter for generating unique span IDs within a trace */
 // eslint-disable-next-line functional/no-let
 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
+ * 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}` });
 
@@ -74,16 +74,16 @@ export const getInstantEvent = (opt: {
 
 /**
  * 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.
+ * 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 getStartTracing = (opt: {
+export const getInstantEventTracingStartedInBrowser = (opt: {
   url: string;
   ts?: number;
   pid?: number;
   tid?: number;
-}): StartTracingEvent => {
+}): InstantEventTracingStartedInBrowser => {
   const { pid, tid, ts } = defaults(opt);
   const id = frameTreeNodeId(pid, tid);
 

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

@@ -5,9 +5,9 @@ import {
   frameTreeNodeId,
   getCompleteEvent,
   getInstantEvent,
+  getInstantEventTracingStartedInBrowser,
   getSpan,
   getSpanEvent,
-  getStartTracing,
   getTraceFile,
   markToInstantEvent,
   measureToSpanEvents,
@@ -103,9 +103,11 @@ describe('frameName', () => {
   });
 });
 
-describe('getStartTracing', () => {
+describe('getInstantEventTracingStartedInBrowser', () => {
   it('should create start tracing event with required url', () => {
-    expect(getStartTracing({ url: 'https://example.com' })).toStrictEqual({
+    expect(
+      getInstantEventTracingStartedInBrowser({ url: 'https://example.com' }),
+    ).toStrictEqual({
       cat: 'devtools.timeline',
       ph: 'i',
       name: 'TracingStartedInBrowser',
@@ -133,7 +135,7 @@ describe('getStartTracing', () => {
 
   it('should use custom pid and tid', () => {
     expect(
-      getStartTracing({
+      getInstantEventTracingStartedInBrowser({
         url: 'https://test.com',
         pid: 777,
         tid: 888,

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

@@ -1,3 +1,4 @@
+import { getInstantEventTracingStartedInBrowser } from './trace-file-utils';
 import type { UserTimingDetail } from './user-timing-extensibility-api.type';
 
 /**
@@ -30,7 +31,7 @@ export type CompleteEventArgs = { detail?: Record<string, unknown> };
  * @property {Array} data.frames - Array of frame information
  * @property {boolean} data.persistentIds - Whether IDs are persistent
  */
-export type StartTracingEventArgs = {
+export type InstantEventTracingStartedInBrowserArgs = {
   data: {
     frameTreeNodeId: number;
     frames: {
@@ -52,7 +53,7 @@ export type TraceArgs =
   | InstantEventArgs
   | SpanEventArgs
   | CompleteEventArgs
-  | StartTracingEventArgs;
+  | InstantEventTracingStartedInBrowserArgs;
 
 /**
  * Base properties shared by all trace events.
@@ -75,11 +76,11 @@ export type BaseTraceEvent = {
 /**
  * Start tracing event for Chrome DevTools tracing.
  */
-export type StartTracingEvent = BaseTraceEvent & {
+export type InstantEventTracingStartedInBrowser = BaseTraceEvent & {
   cat: 'devtools.timeline';
   ph: 'i';
   name: 'TracingStartedInBrowser';
-  args: StartTracingEventArgs;
+  args: InstantEventTracingStartedInBrowserArgs;
 };
 
 /**
@@ -118,7 +119,7 @@ type SpanCore = Omit<BaseTraceEvent, 'args'> & {
 /**
  * Begin event for a span (paired with an end event).
  * @property {'b'} ph - Phase indicator for begin events
- * @property {'t'} s - Scope indicator (thread)
+ * @property {'t'} s - Scope indicator ('t' is thread)
  * @property {never} [dur] - Duration is not applicable for begin events
  */
 export type BeginEvent = SpanCore & {
@@ -145,7 +146,7 @@ export type TraceEvent =
   | InstantEvent
   | CompleteEvent
   | SpanEvent
-  | StartTracingEvent;
+  | InstantEventTracingStartedInBrowser;
 
 /**
  * Raw arguments format for trace events before processing.