lighthouse 11.6.0-dev.20240306 → 11.6.0-dev.20240307

package/core/lib/lantern/simulator/simulator.d.ts

@@ -1,7 +1,3 @@
-export type NetworkRequest = import('../../../../types/internal/lantern.js').Lantern.NetworkRequest;
-export type SimulationOptions = import('../../../../types/internal/lantern.js').Lantern.Simulation.Options;
-export type SimulationNodeTiming = import('../../../../types/internal/lantern.js').Lantern.Simulation.NodeTiming;
-export type SimulationResult<T> = import('../../../../types/internal/lantern.js').Lantern.Simulation.Result<T>;
 export type Node = import('../base-node.js').Node;
 export type NetworkNode = import('../network-node.js').NetworkNode;
 export type CpuNode = import('../cpu-node.js').CPUNode;
@@ -21,11 +17,11 @@ export class Simulator<T = any> {
      */
     static _computeNodeStartPosition(node: Node): number;
     /**
-     * @param {SimulationOptions} [options]
+     * @param {Lantern.Simulation.Options} [options]
      */
-    constructor(options?: import("../../../../types/internal/lantern.js").Lantern.Simulation.Options | undefined);
-    /** @type {Required<SimulationOptions>} */
-    _options: Required<SimulationOptions>;
+    constructor(options?: Lantern.Simulation.Options | undefined);
+    /** @type {Required<Lantern.Simulation.Options>} */
+    _options: Required<Lantern.Simulation.Options>;
     _rtt: number;
     _throughput: number;
     _maximumConcurrentRequests: number;
@@ -74,10 +70,10 @@ export class Simulator<T = any> {
      */
     _markNodeAsComplete(node: Node, endTime: number, connectionTiming?: import("./simulator-timing-map.js").ConnectionTiming | undefined): void;
     /**
-     * @param {NetworkRequest} record
+     * @param {Lantern.NetworkRequest} record
      * @return {?TcpConnection}
      */
-    _acquireConnection(record: NetworkRequest): TcpConnection | null;
+    _acquireConnection(record: Lantern.NetworkRequest): TcpConnection | null;
     /**
      * @return {Node[]}
      */
@@ -121,16 +117,16 @@ export class Simulator<T = any> {
      */
     _updateProgressMadeInTimePeriod(node: Node, timePeriodLength: number, totalElapsedTime: number): number | void;
     /**
-     * @return {{nodeTimings: Map<Node, SimulationNodeTiming>, completeNodeTimings: Map<Node, CompleteNodeTiming>}}
+     * @return {{nodeTimings: Map<Node, Lantern.Simulation.NodeTiming>, completeNodeTimings: Map<Node, CompleteNodeTiming>}}
      */
     _computeFinalNodeTimings(): {
-        nodeTimings: Map<Node, SimulationNodeTiming>;
+        nodeTimings: Map<Node, Lantern.Simulation.NodeTiming>;
         completeNodeTimings: Map<Node, CompleteNodeTiming>;
     };
     /**
-     * @return {Required<SimulationOptions>}
+     * @return {Required<Lantern.Simulation.Options>}
      */
-    getOptions(): Required<SimulationOptions>;
+    getOptions(): Required<Lantern.Simulation.Options>;
     /**
      * Estimates the time taken to process all of the graph's nodes, returns the overall time along with
      * each node annotated by start/end times.
@@ -142,17 +138,18 @@ export class Simulator<T = any> {
      *
      * @param {Node} graph
      * @param {{flexibleOrdering?: boolean, label?: string}=} options
-     * @return {SimulationResult<T>}
+     * @return {Lantern.Simulation.Result<T>}
      */
     simulate(graph: Node, options?: {
         flexibleOrdering?: boolean;
         label?: string;
-    } | undefined): SimulationResult<T>;
+    } | undefined): Lantern.Simulation.Result<T>;
     /**
      * @param {number} wastedBytes
      */
     computeWastedMsFromWastedBytes(wastedBytes: number): number;
 }
+import * as Lantern from '../types/lantern.js';
 import { SimulatorTimingMap } from './simulator-timing-map.js';
 import { DNSCache } from './dns-cache.js';
 import { ConnectionPool } from './connection-pool.js';

package/core/lib/lantern/simulator/simulator.js

@@ -4,13 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-// This could be replaced by jsdoc namespace import, when ready.
-// https://github.com/microsoft/TypeScript/issues/41825
-/** @typedef {import('../../../../types/internal/lantern.js').Lantern.NetworkRequest} NetworkRequest */
-/** @typedef {import('../../../../types/internal/lantern.js').Lantern.Simulation.Options} SimulationOptions */
-/** @typedef {import('../../../../types/internal/lantern.js').Lantern.Simulation.NodeTiming} SimulationNodeTiming */
-/** @template T @typedef {import('../../../../types/internal/lantern.js').Lantern.Simulation.Result<T>} SimulationResult */
-
+import * as Lantern from '../types/lantern.js';
 import {BaseNode} from '../base-node.js';
 import {TcpConnection} from './tcp-connection.js';
 import {ConnectionPool} from './connection-pool.js';
@@ -57,10 +51,10 @@ const ALL_SIMULATION_NODE_TIMINGS = new Map();
  */
 class Simulator {
   /**
-   * @param {SimulationOptions} [options]
+   * @param {Lantern.Simulation.Options} [options]
    */
   constructor(options) {
-    /** @type {Required<SimulationOptions>} */
+    /** @type {Required<Lantern.Simulation.Options>} */
     this._options = Object.assign(
       {
         rtt: mobileSlow4G.rttMs,
@@ -110,7 +104,7 @@ class Simulator {
    * @param {Node} graph
    */
   _initializeConnectionPool(graph) {
-    /** @type {NetworkRequest[]} */
+    /** @type {Lantern.NetworkRequest[]} */
     const records = [];
     graph.getRootNode().traverse(node => {
       if (node.type === BaseNode.TYPES.NETWORK) {
@@ -199,7 +193,7 @@ class Simulator {
   }
 
   /**
-   * @param {NetworkRequest} record
+   * @param {Lantern.NetworkRequest} record
    * @return {?TcpConnection}
    */
   _acquireConnection(record) {
@@ -393,7 +387,7 @@ class Simulator {
   }
 
   /**
-   * @return {{nodeTimings: Map<Node, SimulationNodeTiming>, completeNodeTimings: Map<Node, CompleteNodeTiming>}}
+   * @return {{nodeTimings: Map<Node, Lantern.Simulation.NodeTiming>, completeNodeTimings: Map<Node, CompleteNodeTiming>}}
    */
   _computeFinalNodeTimings() {
     /** @type {Array<[Node, CompleteNodeTiming]>} */
@@ -404,8 +398,8 @@ class Simulator {
     // Most consumers will want the entries sorted by startTime, so insert them in that order
     completeNodeTimingEntries.sort((a, b) => a[1].startTime - b[1].startTime);
 
-    // Trimmed version of type `SimulationNodeTiming`.
-    /** @type {Array<[Node, SimulationNodeTiming]>} */
+    // Trimmed version of type `Lantern.Simulation.NodeTiming`.
+    /** @type {Array<[Node, Lantern.Simulation.NodeTiming]>} */
     const nodeTimingEntries = completeNodeTimingEntries.map(([node, timing]) => {
       return [node, {
         startTime: timing.startTime,
@@ -421,7 +415,7 @@ class Simulator {
   }
 
   /**
-   * @return {Required<SimulationOptions>}
+   * @return {Required<Lantern.Simulation.Options>}
    */
   getOptions() {
     return this._options;
@@ -438,7 +432,7 @@ class Simulator {
    *
    * @param {Node} graph
    * @param {{flexibleOrdering?: boolean, label?: string}=} options
-   * @return {SimulationResult<T>}
+   * @return {Lantern.Simulation.Result<T>}
    */
   simulate(graph, options) {
     if (BaseNode.hasCycle(graph)) {

package/core/lib/lantern/types/lantern.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as LH from '../../../../types/lh.js';
+
+type ParsedURL = {
+    /**
+     * Equivalent to a `new URL(url).protocol` BUT w/o the trailing colon (:)
+     */
+    scheme: string;
+    /**
+     * Equivalent to a `new URL(url).hostname`
+     */
+    host: string;
+    securityOrigin: string;
+};
+type LightriderStatistics = {
+    /**
+     * The difference in networkEndTime between the observed Lighthouse networkEndTime and Lightrider's derived networkEndTime.
+     */
+    endTimeDeltaMs: number;
+    /**
+     * The time spent making a TCP connection (connect + SSL). Note: this is poorly named.
+     */
+    TCPMs: number;
+    /**
+     * The time spent requesting a resource from a remote server, we use this to approx RTT. Note: this is poorly names, it really should be "server response time".
+     */
+    requestMs: number;
+    /**
+     * Time to receive the entire response payload starting the clock on receiving the first fragment (first non-header byte).
+     */
+    responseMs: number;
+};
+
+export class NetworkRequest<T = any> {
+    /**
+     * The canonical network record.
+     * Users of Lantern must create NetworkRequests matching this interface,
+     * but can store the source-of-truth for their network model in this `record`
+     * property. This is then accessible as a read-only property on NetworkNode.
+     */
+    record?: T;
+
+    requestId: string;
+    connectionId: string;
+    connectionReused: boolean;
+    url: string;
+    protocol: string;
+    parsedURL: ParsedURL;
+    documentURL: string;
+    /** When the renderer process initially discovers a network request, in milliseconds. */
+    rendererStartTime: number;
+    /**
+     * 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, in milliseconds.
+     */
+    networkRequestTime: number;
+    /** When the last byte of the response headers is received, in milliseconds. */
+    responseHeadersEndTime: number;
+    /** When the last byte of the response body is received, in milliseconds. */
+    networkEndTime: number;
+    transferSize: number;
+    resourceSize: number;
+    fromDiskCache: boolean;
+    fromMemoryCache: boolean;
+    // TODO(15841): remove from lantern.
+    /** Extra timing information available only when run in Lightrider. */
+    lrStatistics: LightriderStatistics | undefined;
+    finished: boolean;
+    statusCode: number;
+    /** The network request that this one redirected to */
+    redirectDestination: NetworkRequest<T> | undefined;
+    failed: boolean;
+    initiator: LH.Crdp.Network.Initiator;
+    initiatorRequest: NetworkRequest<T> | undefined;
+    /** The chain of network requests that redirected to this one */
+    redirects: NetworkRequest[] | undefined;
+    timing: LH.Crdp.Network.ResourceTiming | undefined;
+    resourceType: LH.Crdp.Network.ResourceType | undefined;
+    mimeType: string;
+    priority: LH.Crdp.Network.ResourcePriority;
+    frameId: string | undefined;
+    sessionTargetType: LH.Protocol.TargetType | undefined;
+}
+
+export namespace Simulation {
+    type GraphNode<T> = import('../base-node.js').Node<T>;
+    type GraphNetworkNode<T> = import('../network-node.js').NetworkNode<T>;
+    type GraphCPUNode = import('../cpu-node.js').CPUNode;
+    type Simulator<T> = import('../simulator/simulator.js').Simulator<T>;
+
+    interface MetricCoefficients {
+        intercept: number;
+        optimistic: number;
+        pessimistic: number;
+    }
+
+    interface Options {
+        rtt?: number;
+        throughput?: number;
+        observedThroughput: number;
+        maximumConcurrentRequests?: number;
+        cpuSlowdownMultiplier?: number;
+        layoutTaskMultiplier?: number;
+        additionalRttByOrigin?: Map<string, number>;
+        serverResponseTimeByOrigin?: Map<string, number>;
+    }
+
+    interface NodeTiming {
+        startTime: number;
+        endTime: number;
+        duration: number;
+    }
+
+    interface Result<T = any> {
+        timeInMs: number;
+        nodeTimings: Map<GraphNode<T>, NodeTiming>;
+    }
+
+    interface MetricComputationDataInput {
+        simulator: Simulator<any>;
+        graph: GraphNode<any>;
+        processedNavigation: LH.Artifacts.ProcessedNavigation;
+    }
+}

package/core/lib/lantern/types/lantern.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export {};

package/core/lib/network-request.d.ts

@@ -1,4 +1,3 @@
-export type LanternNetworkRequest<T> = import('../../types/internal/lantern.js').Lantern.NetworkRequest<T>;
 export type HeaderEntry = {
     name: string;
     value: string;
@@ -50,9 +49,9 @@ export class NetworkRequest {
     static get TYPES(): LH.Util.SelfMap<LH.Crdp.Network.ResourceType>;
     /**
      * @param {NetworkRequest} record
-     * @return {LanternNetworkRequest<NetworkRequest>}
+     * @return {Lantern.NetworkRequest<NetworkRequest>}
      */
-    static asLanternNetworkRequest(record: NetworkRequest): LanternNetworkRequest<NetworkRequest>;
+    static asLanternNetworkRequest(record: NetworkRequest): Lantern.NetworkRequest<NetworkRequest>;
     /**
      * @param {NetworkRequest} record
      * @return {boolean}
@@ -259,7 +258,7 @@ export namespace NetworkRequest {
     export { HEADER_PROTOCOL_IS_H2 };
 }
 import * as LH from '../../types/lh.js';
-/** @template T @typedef {import('../../types/internal/lantern.js').Lantern.NetworkRequest<T>} LanternNetworkRequest */
+import * as Lantern from './lantern/types/lantern.js';
 declare const HEADER_TCP: "X-TCPMs";
 declare const HEADER_SSL: "X-SSLMs";
 declare const HEADER_REQ: "X-RequestMs";

package/core/lib/network-request.js

@@ -53,10 +53,9 @@
  */
 
 import * as LH from '../../types/lh.js';
+import * as Lantern from './lantern/types/lantern.js';
 import UrlUtils from './url-utils.js';
 
-/** @template T @typedef {import('../../types/internal/lantern.js').Lantern.NetworkRequest<T>} LanternNetworkRequest */
-
 // Lightrider X-Header names for timing information.
 // See: _updateTransferSizeForLightrider and _updateTimingsForLightrider.
 const HEADER_TCP = 'X-TCPMs'; // Note: this should have been called something like ConnectMs, as it includes SSL.
@@ -572,7 +571,7 @@ class NetworkRequest {
 
   /**
    * @param {NetworkRequest} record
-   * @return {LanternNetworkRequest<NetworkRequest>}
+   * @return {Lantern.NetworkRequest<NetworkRequest>}
    */
   static asLanternNetworkRequest(record) {
     return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lighthouse",
   "type": "module",
-  "version": "11.6.0-dev.20240306",
+  "version": "11.6.0-dev.20240307",
   "description": "Automated auditing, performance metrics, and best practices for the web.",
   "main": "./core/index.js",
   "bin": {

package/tsconfig.json

@@ -17,6 +17,7 @@
     "clients/**/*.js",
     "build/**/*.js",
     "./types/**/*.d.ts",
+    "./core/lib/lantern/types/**/*.d.ts",
     "eslint-local-rules.cjs",
     "third-party/axe/valid-langs.js",
     "third-party/esbuild-plugins-polyfills/esbuild-polyfills.js",

package/types/gatherer.d.ts

@@ -17,7 +17,7 @@ import Config from './config.js';
 import Result from './lhr/lhr.js';
 import Protocol from './protocol.js';
 import Puppeteer from './puppeteer.js';
-import {Lantern} from '../types/internal/lantern.js';
+import * as Lantern from '../core/lib/lantern/types/lantern.js';
 
 type CrdpEvents = CrdpMappings.Events;
 type CrdpCommands = CrdpMappings.Commands;

package/types/internal/lantern.d.ts

@@ -1,124 +0,0 @@
-/**
- * @license
- * Copyright 2024 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import * as LH from '../lh.js';
-
-declare namespace Lantern {
-    type ParsedURL = {
-        /**
-         * Equivalent to a `new URL(url).protocol` BUT w/o the trailing colon (:)
-         */
-        scheme: string;
-        /**
-         * Equivalent to a `new URL(url).hostname`
-         */
-        host: string;
-        securityOrigin: string;
-    };
-    type LightriderStatistics = {
-        /**
-         * The difference in networkEndTime between the observed Lighthouse networkEndTime and Lightrider's derived networkEndTime.
-         */
-        endTimeDeltaMs: number;
-        /**
-         * The time spent making a TCP connection (connect + SSL). Note: this is poorly named.
-         */
-        TCPMs: number;
-        /**
-         * The time spent requesting a resource from a remote server, we use this to approx RTT. Note: this is poorly names, it really should be "server response time".
-         */
-        requestMs: number;
-        /**
-         * Time to receive the entire response payload starting the clock on receiving the first fragment (first non-header byte).
-         */
-        responseMs: number;
-    };
-    class NetworkRequest<T = any> {
-        /**
-         * The canonical network record.
-         * Users of Lantern must create NetworkRequests matching this interface,
-         * but can store the source-of-truth for their network model in this `record`
-         * property. This is then accessible as a read-only property on NetworkNode.
-         */
-        record?: T;
-
-        requestId: string;
-        connectionId: string;
-        connectionReused: boolean;
-        url: string;
-        protocol: string;
-        parsedURL: ParsedURL;
-        documentURL: string;
-        /** When the renderer process initially discovers a network request, in milliseconds. */
-        rendererStartTime: number;
-        /**
-         * 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, in milliseconds.
-         */
-        networkRequestTime: number;
-        /** When the last byte of the response headers is received, in milliseconds. */
-        responseHeadersEndTime: number;
-        /** When the last byte of the response body is received, in milliseconds. */
-        networkEndTime: number;
-        transferSize: number;
-        resourceSize: number;
-        fromDiskCache: boolean;
-        fromMemoryCache: boolean;
-        // TODO(15841): remove from lantern.
-        /** Extra timing information available only when run in Lightrider. */
-        lrStatistics: LightriderStatistics | undefined;
-        finished: boolean;
-        statusCode: number;
-        /** The network request that this one redirected to */
-        redirectDestination: NetworkRequest<T> | undefined;
-        failed: boolean;
-        initiator: LH.Crdp.Network.Initiator;
-        initiatorRequest: NetworkRequest<T> | undefined;
-        /** The chain of network requests that redirected to this one */
-        redirects: NetworkRequest[] | undefined;
-        timing: LH.Crdp.Network.ResourceTiming | undefined;
-        resourceType: LH.Crdp.Network.ResourceType | undefined;
-        mimeType: string;
-        priority: LH.Crdp.Network.ResourcePriority;
-        frameId: string | undefined;
-        sessionTargetType: LH.Protocol.TargetType | undefined;
-    }
-
-    export namespace Simulation {
-        type GraphNode<T> = import('../../core/lib/lantern/base-node.js').Node<T>;
-        type GraphNetworkNode<T> = import('../../core/lib/lantern/network-node.js').NetworkNode<T>;
-        type GraphCPUNode = import('../../core/lib/lantern/cpu-node.js').CPUNode;
-        type Simulator<T> = import('../../core/lib/lantern/simulator/simulator.js').Simulator<T>;
-
-        interface MetricCoefficients {
-            intercept: number;
-            optimistic: number;
-            pessimistic: number;
-        }
-
-        interface Options {
-            rtt?: number;
-            throughput?: number;
-            observedThroughput: number;
-            maximumConcurrentRequests?: number;
-            cpuSlowdownMultiplier?: number;
-            layoutTaskMultiplier?: number;
-            additionalRttByOrigin?: Map<string, number>;
-            serverResponseTimeByOrigin?: Map<string, number>;
-        }
-
-        interface NodeTiming {
-            startTime: number;
-            endTime: number;
-            duration: number;
-        }
-
-        interface Result<T = any> {
-            timeInMs: number;
-            nodeTimings: Map<GraphNode<T>, NodeTiming>;
-        }
-    }
-}