core(lantern): put types in namespace

.eslintrc.cjs

@@ -76,7 +76,7 @@ module.exports = {
       vars: 'all',
       args: 'after-used',
       argsIgnorePattern: '(^reject$|^_+$)',
-      varsIgnorePattern: '(^_$|^LH$|^Lantern$)',
+      varsIgnorePattern: '(^_$|^LH$)',
     }],
     'no-cond-assign': 2,
     'space-infix-ops': 2,

core/lib/lantern/lantern.js

@@ -4,8 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-const NetworkRequest = /** @type {import('../../../types/internal/lantern').NetworkRequest} */({});
-
 /** @type {LH.Util.SelfMap<LH.Crdp.Network.ResourceType>} */
 const NetworkRequestTypes = {
   XHR: 'XHR',
@@ -29,6 +27,5 @@ const NetworkRequestTypes = {
 };
 
 export {
-  NetworkRequest,
   NetworkRequestTypes,
 };

core/lib/lantern/network-node.js

@@ -4,7 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from './lantern.js';
+/** @template T @typedef {import('../../../types/internal/lantern.js').Lantern.NetworkRequest<T>} NetworkRequest */
+
+import {NetworkRequestTypes} from './lantern.js';
 import {BaseNode} from './base-node.js';
 // TODO(15841): bring impl of isNonNetworkRequest inside lantern and remove this.
 import UrlUtils from '../url-utils.js';
@@ -15,7 +17,7 @@ import UrlUtils from '../url-utils.js';
  */
 class NetworkNode extends BaseNode {
   /**
-   * @param {Lantern.NetworkRequest<T>} networkRequest
+   * @param {NetworkRequest<T>} networkRequest
    */
   constructor(networkRequest) {
     super(networkRequest.requestId);
@@ -49,7 +51,7 @@ class NetworkNode extends BaseNode {
   }
 
   /**
-   * @return {Lantern.NetworkRequest<T>}
+   * @return {NetworkRequest<T>}
    */
   get request() {
     return this._request;
@@ -93,8 +95,8 @@ class NetworkNode extends BaseNode {
    */
   hasRenderBlockingPriority() {
     const priority = this._request.priority;
-    const isScript = this._request.resourceType === Lantern.NetworkRequestTypes.Script;
-    const isDocument = this._request.resourceType === Lantern.NetworkRequestTypes.Document;
+    const isScript = this._request.resourceType === NetworkRequestTypes.Script;
+    const isDocument = this._request.resourceType === NetworkRequestTypes.Document;
     const isBlockingScript = priority === 'High' && isScript;
     const isBlockingHtmlImport = priority === 'High' && isDocument;
     return priority === 'VeryHigh' || isBlockingScript || isBlockingHtmlImport;

core/lib/lantern/simulator/connection-pool.js

@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as LH from '../../../../types/lh.js';
-import * as Lantern from '../lantern.js';
+/** @typedef {import('../../../../types/internal/lantern.js').Lantern.NetworkRequest} NetworkRequest */
+/** @typedef {import('../../../../types/internal/lantern.js').Lantern.Simulation.Options} SimulationOptions */
+
 import {NetworkAnalyzer} from './network-analyzer.js';
 import {TcpConnection} from './tcp-connection.js';
 
@@ -18,16 +19,16 @@ const CONNECTIONS_PER_ORIGIN = 6;
 
 export class ConnectionPool {
   /**
-   * @param {Lantern.NetworkRequest[]} records
-   * @param {Required<LH.Gatherer.Simulation.Options>} options
+   * @param {NetworkRequest[]} records
+   * @param {Required<SimulationOptions>} options
    */
   constructor(records, options) {
     this._options = options;
 
     this._records = records;
     /** @type {Map<string, TcpConnection[]>} */
     this._connectionsByOrigin = new Map();
-    /** @type {Map<Lantern.NetworkRequest, TcpConnection>} */
+    /** @type {Map<NetworkRequest, TcpConnection>} */
     this._connectionsByRecord = new Map();
     this._connectionsInUse = new Set();
     this._connectionReusedByRequestId = NetworkAnalyzer.estimateIfConnectionWasReused(records, {
@@ -125,7 +126,7 @@ export class ConnectionPool {
    * If ignoreConnectionReused is true, acquire will consider all connections not in use as available.
    * Otherwise, only connections that have matching "warmth" are considered available.
    *
-   * @param {Lantern.NetworkRequest} record
+   * @param {NetworkRequest} record
    * @param {{ignoreConnectionReused?: boolean}} options
    * @return {?TcpConnection}
    */
@@ -151,7 +152,7 @@ export class ConnectionPool {
    * Return the connection currently being used to fetch a record. If no connection
    * currently being used for this record, an error will be thrown.
    *
-   * @param {Lantern.NetworkRequest} record
+   * @param {NetworkRequest} record
    * @return {TcpConnection}
    */
   acquireActiveConnectionFromRecord(record) {
@@ -162,7 +163,7 @@ export class ConnectionPool {
   }
 
   /**
-   * @param {Lantern.NetworkRequest} record
+   * @param {NetworkRequest} record
    */
   release(record) {
     const connection = this._connectionsByRecord.get(record);

core/lib/lantern/simulator/dns-cache.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from '../lantern.js';
+/** @typedef {import('../../../../types/internal/lantern.js').Lantern.NetworkRequest} NetworkRequest */
 
 // A DNS lookup will usually take ~1-2 roundtrips of connection latency plus the extra DNS routing time.
 // Example: https://www.webpagetest.org/result/180703_3A_e33ec79747c002ed4d7bcbfc81462203/1/details/#waterfall_view_step1
@@ -25,7 +25,7 @@ class DNSCache {
   }
 
   /**
-   * @param {Lantern.NetworkRequest} request
+   * @param {NetworkRequest} request
    * @param {{requestedAt: number, shouldUpdateCache: boolean}=} options
    * @return {number}
    */
@@ -47,7 +47,7 @@ class DNSCache {
   }
 
   /**
-   * @param {Lantern.NetworkRequest} request
+   * @param {NetworkRequest} request
    * @param {number} resolvedAt
    */
   _updateCacheResolvedAtIfNeeded(request, resolvedAt) {

core/lib/lantern/simulator/network-analyzer.js

@@ -4,7 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from '../lantern.js';
+/** @typedef {import('../../../../types/internal/lantern.js').Lantern.NetworkRequest} NetworkRequest */
+
 import UrlUtils from '../../url-utils.js';
 
 const INITIAL_CWD = 14 * 1024;
@@ -32,8 +33,8 @@ class NetworkAnalyzer {
   }
 
   /**
-   * @param {Lantern.NetworkRequest[]} records
-   * @return {Map<string, Lantern.NetworkRequest[]>}
+   * @param {NetworkRequest[]} records
+   * @return {Map<string, NetworkRequest[]>}
    */
   static groupByOrigin(records) {
     const grouped = new Map();
@@ -88,10 +89,10 @@ class NetworkAnalyzer {
     return summaryByKey;
   }
 
-  /** @typedef {{record: Lantern.NetworkRequest, timing: LH.Crdp.Network.ResourceTiming, connectionReused?: boolean}} RequestInfo */
+  /** @typedef {{record: NetworkRequest, timing: LH.Crdp.Network.ResourceTiming, connectionReused?: boolean}} RequestInfo */
 
   /**
-   * @param {Lantern.NetworkRequest[]} records
+   * @param {NetworkRequest[]} records
    * @param {(e: RequestInfo) => number | number[] | undefined} iteratee
    * @return {Map<string, number[]>}
    */
@@ -250,7 +251,7 @@ class NetworkAnalyzer {
   /**
    * Given the RTT to each origin, estimates the observed server response times.
    *
-   * @param {Lantern.NetworkRequest[]} records
+   * @param {NetworkRequest[]} records
    * @param {Map<string, number>} rttByOrigin
    * @return {Map<string, number[]>}
    */
@@ -271,7 +272,7 @@ class NetworkAnalyzer {
   }
 
   /**
-   * @param {Lantern.NetworkRequest[]} records
+   * @param {NetworkRequest[]} records
    * @return {boolean}
    */
   static canTrustConnectionInformation(records) {
@@ -291,7 +292,7 @@ class NetworkAnalyzer {
    * Returns a map of requestId -> connectionReused, estimating the information if the information
    * available in the records themselves appears untrustworthy.
    *
-   * @param {Lantern.NetworkRequest[]} records
+   * @param {NetworkRequest[]} records
    * @param {{forceCoarseEstimates: boolean}} [options]
    * @return {Map<string, boolean>}
    */
@@ -335,7 +336,7 @@ class NetworkAnalyzer {
    * Attempts to use the most accurate information first and falls back to coarser estimates when it
    * is unavailable.
    *
-   * @param {Lantern.NetworkRequest[]} records
+   * @param {NetworkRequest[]} records
    * @param {RTTEstimateOptions} [options]
    * @return {Map<string, Summary>}
    */
@@ -416,7 +417,7 @@ class NetworkAnalyzer {
    * Estimates the server response time of each origin. RTT times can be passed in or will be
    * estimated automatically if not provided.
    *
-   * @param {Lantern.NetworkRequest[]} records
+   * @param {NetworkRequest[]} records
    * @param {RTTEstimateOptions & {rttByOrigin?: Map<string, number>}} [options]
    * @return {Map<string, Summary>}
    */
@@ -442,7 +443,7 @@ class NetworkAnalyzer {
    * Excludes data URI, failed or otherwise incomplete, and cached requests.
    * Returns Infinity if there were no analyzable network records.
    *
-   * @param {Array<Lantern.NetworkRequest>} networkRecords
+   * @param {Array<NetworkRequest>} networkRecords
    * @return {number}
    */
   static estimateThroughput(networkRecords) {
@@ -495,7 +496,7 @@ class NetworkAnalyzer {
   }
 
   /**
-   * @template {Lantern.NetworkRequest} T
+   * @template {NetworkRequest} T
    * @param {Array<T>} records
    * @param {string} resourceUrl
    * @return {T|undefined}
@@ -509,7 +510,7 @@ class NetworkAnalyzer {
   }
 
   /**
-   * @template {Lantern.NetworkRequest} T
+   * @template {NetworkRequest} T
    * @param {Array<T>} records
    * @param {string} resourceUrl
    * @return {T|undefined}
@@ -529,7 +530,7 @@ class NetworkAnalyzer {
    * Resolves redirect chain given a main document.
    * See: {@link NetworkAnalyzer.findLastDocumentForUrl}) for how to retrieve main document.
    *
-   * @template {Lantern.NetworkRequest} T
+   * @template {NetworkRequest} T
    * @param {T} request
    * @return {T}
    */

core/lib/lantern/simulator/simulator.js

@@ -4,8 +4,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from '../lantern.js';
-import * as LH from '../../../../types/lh.js';
+// 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 */
+/** @typedef {import('../../../../types/internal/lantern.js').Lantern.Simulation.Result} SimulationResult */
+
 import {BaseNode} from '../base-node.js';
 import {TcpConnection} from './tcp-connection.js';
 import {ConnectionPool} from './connection-pool.js';
@@ -49,10 +54,10 @@ const ALL_SIMULATION_NODE_TIMINGS = new Map();
 
 class Simulator {
   /**
-   * @param {LH.Gatherer.Simulation.Options} [options]
+   * @param {SimulationOptions} [options]
    */
   constructor(options) {
-    /** @type {Required<LH.Gatherer.Simulation.Options>} */
+    /** @type {Required<SimulationOptions>} */
     this._options = Object.assign(
       {
         rtt: mobileSlow4G.rttMs,
@@ -102,7 +107,7 @@ class Simulator {
    * @param {Node} graph
    */
   _initializeConnectionPool(graph) {
-    /** @type {Lantern.NetworkRequest[]} */
+    /** @type {NetworkRequest[]} */
     const records = [];
     graph.getRootNode().traverse(node => {
       if (node.type === BaseNode.TYPES.NETWORK) {
@@ -191,7 +196,7 @@ class Simulator {
   }
 
   /**
-   * @param {Lantern.NetworkRequest} record
+   * @param {NetworkRequest} record
    * @return {?TcpConnection}
    */
   _acquireConnection(record) {
@@ -385,7 +390,7 @@ class Simulator {
   }
 
   /**
-   * @return {{nodeTimings: Map<Node, LH.Gatherer.Simulation.NodeTiming>, completeNodeTimings: Map<Node, CompleteNodeTiming>}}
+   * @return {{nodeTimings: Map<Node, SimulationNodeTiming>, completeNodeTimings: Map<Node, CompleteNodeTiming>}}
    */
   _computeFinalNodeTimings() {
     /** @type {Array<[Node, CompleteNodeTiming]>} */
@@ -396,8 +401,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 `LH.Gatherer.Simulation.NodeTiming`.
-    /** @type {Array<[Node, LH.Gatherer.Simulation.NodeTiming]>} */
+    // Trimmed version of type `SimulationNodeTiming`.
+    /** @type {Array<[Node, SimulationNodeTiming]>} */
     const nodeTimingEntries = completeNodeTimingEntries.map(([node, timing]) => {
       return [node, {
         startTime: timing.startTime,
@@ -413,7 +418,7 @@ class Simulator {
   }
 
   /**
-   * @return {Required<LH.Gatherer.Simulation.Options>}
+   * @return {Required<SimulationOptions>}
    */
   getOptions() {
     return this._options;
@@ -430,7 +435,7 @@ class Simulator {
    *
    * @param {Node} graph
    * @param {{flexibleOrdering?: boolean, label?: string}=} options
-   * @return {LH.Gatherer.Simulation.Result}
+   * @return {SimulationResult}
    */
   simulate(graph, options) {
     if (BaseNode.hasCycle(graph)) {

core/lib/network-request.js

@@ -53,9 +53,10 @@
  */
 
 import * as LH from '../../types/lh.js';
-import * as Lantern from './lantern/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.
@@ -571,7 +572,7 @@ class NetworkRequest {
 
   /**
    * @param {NetworkRequest} record
-   * @return {Lantern.NetworkRequest<NetworkRequest>}
+   * @return {LanternNetworkRequest<NetworkRequest>}
    */
   static asLanternNetworkRequest(record) {
     return {

types/gatherer.d.ts

@@ -132,6 +132,7 @@ declare module Gatherer {
       GathererInstance<Exclude<TDependencies, DefaultDependenciesKey>>
   type AnyGathererInstance = GathererInstanceExpander<Gatherer.DependencyKey>
 
+  // TODO(15841): use from lantern.d.ts
   namespace Simulation {
     type GraphNode = import('../core/lib/lantern/base-node.js').Node<Artifacts.NetworkRequest>;
     type GraphNetworkNode = _NetworkNode<Artifacts.NetworkRequest>;