@paulirish/trace_engine 0.0.36 → 0.0.37

package/models/trace/insights/types.d.ts

@@ -1,7 +1,7 @@
 import type * as Handlers from '../handlers/handlers.js';
 import type * as Lantern from '../lantern/lantern.js';
 import type * as Types from '../types/types.js';
-import type * as InsightsRunners from './InsightRunners.js';
+import type * as Models from './Models.js';
 /**
  * Context for the portion of the trace an insight should look at.
  */
@@ -23,7 +23,7 @@ export interface LanternContext {
     simulator: Lantern.Simulation.Simulator<Types.Events.SyntheticNetworkRequest>;
     metrics: Record<string, Lantern.Metrics.MetricResult>;
 }
-export type InsightRunnersType = typeof InsightsRunners;
+export type InsightModelsType = typeof Models;
 export declare enum InsightWarning {
     NO_FP = "NO_FP",
     NO_LCP = "NO_LCP",
@@ -37,7 +37,7 @@ export interface MetricSavings {
     CLS?: number;
     INP?: Types.Timing.MilliSeconds;
 }
-export type InsightResult<R extends Record<string, unknown>> = R & {
+export type InsightModel<R extends Record<string, unknown>> = R & {
     relatedEvents?: Types.Events.Event[];
     warnings?: InsightWarning[];
     metricSavings?: MetricSavings;
@@ -47,21 +47,21 @@ export type InsightResult<R extends Record<string, unknown>> = R & {
  * this could instead represent the duration from the beginning of the trace up to the first recorded
  * navigation (or the end of the trace).
  */
-export type InsightSets = {
+export type InsightSet = {
     /** If for a navigation, this is the navigationId. Else it is Trace.Types.Events.NO_NAVIGATION. */
     id: Types.Events.NavigationId;
     /** The URL to show in the accordion list. */
     url: URL;
     frameId: string;
     bounds: Types.Timing.TraceWindowMicroSeconds;
-    data: InsightResults;
+    model: InsightModels;
     navigation?: Types.Events.NavigationStart;
 };
 /**
- * Contains insights for a specific navigation.
+ * Contains insights for a specific insight set.
  */
-export type InsightResults = {
-    [I in keyof InsightRunnersType]: ReturnType<InsightRunnersType[I]['generateInsight']>;
+export type InsightModels = {
+    [I in keyof InsightModelsType]: ReturnType<InsightModelsType[I]['generateInsight']>;
 };
 /**
  * Contains insights for the entire trace. Insights are mostly grouped by `navigationId`, with one exception:
@@ -69,7 +69,7 @@ export type InsightResults = {
  * If the analyzed trace started after the navigation, and has meaningful work with that span, there is no
  * navigation to map it to. In this case `Types.Events.NO_NAVIGATION` is used for the key.
  */
-export type TraceInsightSets = Map<Types.Events.NavigationId, InsightSets>;
+export type TraceInsightSets = Map<Types.Events.NavigationId, InsightSet>;
 /**
  * Represents the narrow set of dependencies defined by an insight's `deps()` function. `Meta` is always included regardless of `deps()`.
  */

package/models/trace/insights/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../front_end/models/trace/insights/types.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AAmC7B,MAAM,CAAN,IAAY,cAMX;AAND,WAAY,cAAc;IACxB,iCAAe,CAAA;IACf,mCAAiB,CAAA;IACjB,uEAAuE;IACvE,6DAA2C,CAAA;IAC3C,yCAAuB,CAAA;AACzB,CAAC,EANW,cAAc,KAAd,cAAc,QAMzB","sourcesContent":["// Copyright 2024 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nimport type * as Handlers from '../handlers/handlers.js';\nimport type * as Lantern from '../lantern/lantern.js';\nimport type * as Types from '../types/types.js';\n\nimport type * as InsightsRunners from './InsightRunners.js';\n\n/**\n * Context for the portion of the trace an insight should look at.\n */\nexport type InsightSetContext = InsightSetContextWithoutNavigation|InsightSetContextWithNavigation;\n\nexport interface InsightSetContextWithoutNavigation {\n  bounds: Types.Timing.TraceWindowMicroSeconds;\n  frameId: string;\n  navigation?: never;\n}\n\nexport interface InsightSetContextWithNavigation {\n  bounds: Types.Timing.TraceWindowMicroSeconds;\n  frameId: string;\n  navigation: Types.Events.NavigationStart;\n  navigationId: string;\n  lantern?: LanternContext;\n}\n\nexport interface LanternContext {\n  graph: Lantern.Graph.Node<Types.Events.SyntheticNetworkRequest>;\n  simulator: Lantern.Simulation.Simulator<Types.Events.SyntheticNetworkRequest>;\n  metrics: Record<string, Lantern.Metrics.MetricResult>;\n}\n\nexport type InsightRunnersType = typeof InsightsRunners;\n\nexport enum InsightWarning {\n  NO_FP = 'NO_FP',\n  NO_LCP = 'NO_LCP',\n  // No network request could be identified as the primary HTML document.\n  NO_DOCUMENT_REQUEST = 'NO_DOCUMENT_REQUEST',\n  NO_LAYOUT = 'NO_LAYOUT',\n}\n\nexport interface MetricSavings {\n  /* eslint-disable @typescript-eslint/naming-convention */\n  FCP?: Types.Timing.MilliSeconds;\n  LCP?: Types.Timing.MilliSeconds;\n  TBT?: Types.Timing.MilliSeconds;\n  CLS?: number;\n  INP?: Types.Timing.MilliSeconds;\n  /* eslint-enable @typescript-eslint/naming-convention */\n}\n\nexport type InsightResult<R extends Record<string, unknown>> = R&{\n  relatedEvents?: Types.Events.Event[],\n  warnings?: InsightWarning[],\n  metricSavings?: MetricSavings,\n};\n\n/**\n * Contains insights for a specific navigation. If a trace began after a navigation already started,\n * this could instead represent the duration from the beginning of the trace up to the first recorded\n * navigation (or the end of the trace).\n */\nexport type InsightSets = {\n  /** If for a navigation, this is the navigationId. Else it is Trace.Types.Events.NO_NAVIGATION. */\n  id: Types.Events.NavigationId,\n  /** The URL to show in the accordion list. */\n  url: URL,\n  frameId: string,\n  bounds: Types.Timing.TraceWindowMicroSeconds,\n  data: InsightResults,\n  navigation?: Types.Events.NavigationStart,\n};\n\n/**\n * Contains insights for a specific navigation.\n */\nexport type InsightResults = {\n  [I in keyof InsightRunnersType]: ReturnType<InsightRunnersType[I]['generateInsight']>;\n};\n\n/**\n * Contains insights for the entire trace. Insights are mostly grouped by `navigationId`, with one exception:\n *\n * If the analyzed trace started after the navigation, and has meaningful work with that span, there is no\n * navigation to map it to. In this case `Types.Events.NO_NAVIGATION` is used for the key.\n */\nexport type TraceInsightSets = Map<Types.Events.NavigationId, InsightSets>;\n\n/**\n * Represents the narrow set of dependencies defined by an insight's `deps()` function. `Meta` is always included regardless of `deps()`.\n */\nexport type RequiredData<D extends() => Array<keyof typeof Handlers.ModelHandlers>> =\n    Handlers.Types.EnabledHandlerDataWithMeta<Pick<typeof Handlers.ModelHandlers, ReturnType<D>[number]>>;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../front_end/models/trace/insights/types.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AAmC7B,MAAM,CAAN,IAAY,cAMX;AAND,WAAY,cAAc;IACxB,iCAAe,CAAA;IACf,mCAAiB,CAAA;IACjB,uEAAuE;IACvE,6DAA2C,CAAA;IAC3C,yCAAuB,CAAA;AACzB,CAAC,EANW,cAAc,KAAd,cAAc,QAMzB","sourcesContent":["// Copyright 2024 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nimport type * as Handlers from '../handlers/handlers.js';\nimport type * as Lantern from '../lantern/lantern.js';\nimport type * as Types from '../types/types.js';\n\nimport type * as Models from './Models.js';\n\n/**\n * Context for the portion of the trace an insight should look at.\n */\nexport type InsightSetContext = InsightSetContextWithoutNavigation|InsightSetContextWithNavigation;\n\nexport interface InsightSetContextWithoutNavigation {\n  bounds: Types.Timing.TraceWindowMicroSeconds;\n  frameId: string;\n  navigation?: never;\n}\n\nexport interface InsightSetContextWithNavigation {\n  bounds: Types.Timing.TraceWindowMicroSeconds;\n  frameId: string;\n  navigation: Types.Events.NavigationStart;\n  navigationId: string;\n  lantern?: LanternContext;\n}\n\nexport interface LanternContext {\n  graph: Lantern.Graph.Node<Types.Events.SyntheticNetworkRequest>;\n  simulator: Lantern.Simulation.Simulator<Types.Events.SyntheticNetworkRequest>;\n  metrics: Record<string, Lantern.Metrics.MetricResult>;\n}\n\nexport type InsightModelsType = typeof Models;\n\nexport enum InsightWarning {\n  NO_FP = 'NO_FP',\n  NO_LCP = 'NO_LCP',\n  // No network request could be identified as the primary HTML document.\n  NO_DOCUMENT_REQUEST = 'NO_DOCUMENT_REQUEST',\n  NO_LAYOUT = 'NO_LAYOUT',\n}\n\nexport interface MetricSavings {\n  /* eslint-disable @typescript-eslint/naming-convention */\n  FCP?: Types.Timing.MilliSeconds;\n  LCP?: Types.Timing.MilliSeconds;\n  TBT?: Types.Timing.MilliSeconds;\n  CLS?: number;\n  INP?: Types.Timing.MilliSeconds;\n  /* eslint-enable @typescript-eslint/naming-convention */\n}\n\nexport type InsightModel<R extends Record<string, unknown>> = R&{\n  relatedEvents?: Types.Events.Event[],\n  warnings?: InsightWarning[],\n  metricSavings?: MetricSavings,\n};\n\n/**\n * Contains insights for a specific navigation. If a trace began after a navigation already started,\n * this could instead represent the duration from the beginning of the trace up to the first recorded\n * navigation (or the end of the trace).\n */\nexport type InsightSet = {\n  /** If for a navigation, this is the navigationId. Else it is Trace.Types.Events.NO_NAVIGATION. */\n  id: Types.Events.NavigationId,\n  /** The URL to show in the accordion list. */\n  url: URL,\n  frameId: string,\n  bounds: Types.Timing.TraceWindowMicroSeconds,\n  model: InsightModels,\n  navigation?: Types.Events.NavigationStart,\n};\n\n/**\n * Contains insights for a specific insight set.\n */\nexport type InsightModels = {\n  [I in keyof InsightModelsType]: ReturnType<InsightModelsType[I]['generateInsight']>;\n};\n\n/**\n * Contains insights for the entire trace. Insights are mostly grouped by `navigationId`, with one exception:\n *\n * If the analyzed trace started after the navigation, and has meaningful work with that span, there is no\n * navigation to map it to. In this case `Types.Events.NO_NAVIGATION` is used for the key.\n */\nexport type TraceInsightSets = Map<Types.Events.NavigationId, InsightSet>;\n\n/**\n * Represents the narrow set of dependencies defined by an insight's `deps()` function. `Meta` is always included regardless of `deps()`.\n */\nexport type RequiredData<D extends() => Array<keyof typeof Handlers.ModelHandlers>> =\n    Handlers.Types.EnabledHandlerDataWithMeta<Pick<typeof Handlers.ModelHandlers, ReturnType<D>[number]>>;\n"]}

package/models/trace/trace-tsconfig.json

@@ -47,6 +47,12 @@
     {
       "path": "../../core/sdk/bundle-tsconfig.json"
     },
+    {
+      "path": "../../generated/protocol-tsconfig.json"
+    },
+    {
+      "path": "../cpu_profile/bundle-tsconfig.json"
+    },
     {
       "path": "extras/bundle-tsconfig.json"
     },

package/models/trace/types/TraceEvents.d.ts

@@ -26,6 +26,9 @@ export declare const enum Phase {
     MARK = "R",
     CLOCK_SYNC = "c"
 }
+export type NonEmptyString = string & {
+    _tag: 'NonEmptyString';
+};
 export declare function isNestableAsyncPhase(phase: Phase): boolean;
 export declare function isPhaseAsync(phase: Phase): boolean;
 export declare function isFlowPhase(phase: Phase): boolean;
@@ -452,11 +455,12 @@ export interface ProcessName extends Metadata {
 export interface Mark extends Event {
     ph: Phase.MARK;
 }
-export interface NavigationStart extends Mark {
+export interface NavigationStartUnreliable extends Mark {
     name: 'navigationStart';
     args: Args & {
         data?: ArgsData & {
-            documentLoaderURL: string;
+            /** An empty documentLoaderURL means this navigationStart is unreliable noise and can be ignored. */
+            documentLoaderURL: never;
             isLoadingMainFrame: boolean;
             isOutermostMainFrame?: boolean;
             navigationId: string;
@@ -468,6 +472,14 @@ export interface NavigationStart extends Mark {
         frame: string;
     };
 }
+export interface NavigationStart extends NavigationStartUnreliable {
+    args: NavigationStartUnreliable['args'] & {
+        data: NavigationStartUnreliable['args']['data'] & {
+            /** This navigationStart is valid, as the documentLoaderURL isn't empty. */
+            documentLoaderURL: NonEmptyString;
+        };
+    };
+}
 export interface FirstContentfulPaint extends Mark {
     name: Name.MARK_FCP;
     args: Args & {
@@ -752,8 +764,9 @@ export interface ResourceChangePriority extends Instant {
         };
     };
 }
+/** Only sent for navigations. https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_instrumentation.cc;l=1612-1647;drc=ec7daf93d0479b758610c75f4e146fd4d2d6ed2b */
 export interface ResourceWillSendRequest extends Instant {
-    name: 'ResourceWillSendRequest';
+    name: Name.RESOURCE_WILL_SEND_REQUEST;
     args: Args & {
         data: ArgsData & {
             requestId: string;
@@ -782,6 +795,7 @@ export interface ResourceReceivedData extends Instant {
         };
     };
 }
+/** See https://mdn.github.io/shared-assets/images/diagrams/api/performance/timestamp-diagram.svg  */
 interface ResourceReceiveResponseTimingData {
     connectEnd: MilliSeconds;
     connectStart: MilliSeconds;
@@ -793,6 +807,7 @@ interface ResourceReceiveResponseTimingData {
     pushStart: MilliSeconds;
     receiveHeadersEnd: MilliSeconds;
     receiveHeadersStart: MilliSeconds;
+    /** When the network service is about to handle a request, ie. just before going to the HTTP cache or going to the network for DNS/connection setup. */
     requestTime: Seconds;
     sendEnd: MilliSeconds;
     sendStart: MilliSeconds;
@@ -1448,7 +1463,8 @@ export declare function isProcessName(event: Event): event is ProcessName;
 export declare function isTracingStartedInBrowser(event: Event): event is TracingStartedInBrowser;
 export declare function isFrameCommittedInBrowser(event: Event): event is FrameCommittedInBrowser;
 export declare function isCommitLoad(event: Event): event is CommitLoad;
-export declare function isNavigationStart(event: Event): event is NavigationStart;
+/** @deprecated You probably want `isNavigationStart` instead. */
+export declare function isNavigationStartUnreliable(event: Event): event is NavigationStartUnreliable;
 export declare function isAnimation(event: Event): event is Animation;
 export declare function isSyntheticAnimation(event: Event): event is SyntheticAnimationPair;
 export declare function isLayoutShift(event: Event): event is LayoutShift;
@@ -1479,7 +1495,8 @@ export declare function isSyntheticNetworkRequest(event: Event): event is Synthe
 export declare function isSyntheticWebSocketConnection(event: Event): event is SyntheticWebSocketConnection;
 export declare function isNetworkTrackEntry(event: Event): event is SyntheticWebSocketConnection | SyntheticNetworkRequest;
 export declare function isPrePaint(event: Event): event is PrePaint;
-export declare function isNavigationStartWithURL(event: Event): event is NavigationStart;
+/** A VALID navigation start (as it has a populated documentLoaderURL) */
+export declare function isNavigationStart(event: Event): event is NavigationStart;
 export declare function isMainFrameViewport(event: Event): event is MainFrameViewport;
 export declare function isSyntheticUserTiming(event: Event): event is SyntheticUserTimingPair;
 export declare function isSyntheticConsoleTiming(event: Event): event is SyntheticConsoleTimingPair;

package/models/trace/types/TraceEvents.js

@@ -246,7 +246,8 @@ export function isFrameCommittedInBrowser(event) {
 export function isCommitLoad(event) {
     return event.name === 'CommitLoad';
 }
-export function isNavigationStart(event) {
+/** @deprecated You probably want `isNavigationStart` instead. */
+export function isNavigationStartUnreliable(event) {
     return event.name === 'navigationStart';
 }
 export function isAnimation(event) {
@@ -347,8 +348,9 @@ export function isNetworkTrackEntry(event) {
 export function isPrePaint(event) {
     return event.name === 'PrePaint';
 }
-export function isNavigationStartWithURL(event) {
-    return Boolean(isNavigationStart(event) && event.args.data && event.args.data.documentLoaderURL !== '');
+/** A VALID navigation start (as it has a populated documentLoaderURL) */
+export function isNavigationStart(event) {
+    return Boolean(isNavigationStartUnreliable(event) && event.args.data && event.args.data.documentLoaderURL !== '');
 }
 export function isMainFrameViewport(event) {
     return event.name === 'PaintTimingVisualizer::Viewport';