devtools-tracing 1.0.0

package/lib/front_end/core/platform/TypedArrayUtilities.ts

@@ -0,0 +1,189 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * An object which provides functionality similar to Uint32Array. It may be
+ * implemented as:
+ * 1. A Uint32Array,
+ * 2. An array of Uint32Arrays, to support more data than Uint32Array, or
+ * 3. A plain array, in which case the length may change by setting values.
+ */
+export interface BigUint32Array {
+  get length(): number;
+  getValue(index: number): number;
+  setValue(index: number, value: number): void;
+  asUint32ArrayOrFail(): Uint32Array;
+  asArrayOrFail(): number[];
+}
+
+/**
+ * @returns A BigUint32Array implementation which is based on Array.
+ * This means that its length automatically expands to include the highest index
+ * used, and asArrayOrFail will succeed.
+ */
+export function createExpandableBigUint32Array(): BigUint32Array {
+  return new ExpandableBigUint32ArrayImpl();
+}
+
+/**
+ * @returns A BigUint32Array implementation which is based on Uint32Array.
+ * If the length is small enough to fit in a single Uint32Array, then
+ * asUint32ArrayOrFail will succeed. Otherwise, it will throw an exception.
+ */
+export function createFixedBigUint32Array(length: number, maxLengthForTesting?: number): BigUint32Array {
+  try {
+    if (maxLengthForTesting !== undefined && length > maxLengthForTesting) {
+      // Simulate allocation failure.
+      throw new RangeError();
+    }
+    return new BasicBigUint32ArrayImpl(length);
+  } catch {
+    // We couldn't allocate a big enough ArrayBuffer.
+    return new SplitBigUint32ArrayImpl(length, maxLengthForTesting);
+  }
+}
+
+class BasicBigUint32ArrayImpl extends Uint32Array implements BigUint32Array {
+  getValue(index: number): number {
+    return this[index];
+  }
+  setValue(index: number, value: number): void {
+    this[index] = value;
+  }
+  asUint32ArrayOrFail(): Uint32Array {
+    return this;
+  }
+  asArrayOrFail(): number[] {
+    throw new Error('Not an array');
+  }
+}
+
+class SplitBigUint32ArrayImpl implements BigUint32Array {
+  #data: Uint32Array[];
+  #partLength: number;
+  length: number;
+
+  constructor(length: number, maxLengthForTesting?: number) {
+    this.#data = [];
+    this.length = length;
+    let partCount = 1;
+    while (true) {
+      partCount *= 2;
+      this.#partLength = Math.ceil(length / partCount);
+      try {
+        if (maxLengthForTesting !== undefined && this.#partLength > maxLengthForTesting) {
+          // Simulate allocation failure.
+          throw new RangeError();
+        }
+        for (let i = 0; i < partCount; ++i) {
+          this.#data[i] = new Uint32Array(this.#partLength);
+        }
+        return;
+      } catch (e) {
+        if (this.#partLength < 1e6) {
+          // The length per part is already small, so continuing to subdivide it
+          // will probably not help.
+          throw e;
+        }
+      }
+    }
+  }
+
+  getValue(index: number): number {
+    if (index >= 0 && index < this.length) {
+      const partLength = this.#partLength;
+      return this.#data[Math.floor(index / partLength)][index % partLength];
+    }
+    // On out-of-bounds accesses, match the behavior of Uint32Array: return an
+    // undefined value that's incorrectly typed as number.
+    return this.#data[0][-1];
+  }
+
+  setValue(index: number, value: number): void {
+    if (index >= 0 && index < this.length) {
+      const partLength = this.#partLength;
+      this.#data[Math.floor(index / partLength)][index % partLength] = value;
+    }
+    // Attempting to set a value out of bounds does nothing, like Uint32Array.
+  }
+
+  asUint32ArrayOrFail(): Uint32Array {
+    throw new Error('Not a Uint32Array');
+  }
+  asArrayOrFail(): number[] {
+    throw new Error('Not an array');
+  }
+}
+
+class ExpandableBigUint32ArrayImpl extends Array<number> implements BigUint32Array {
+  getValue(index: number): number {
+    return this[index];
+  }
+  setValue(index: number, value: number): void {
+    this[index] = value;
+  }
+  asUint32ArrayOrFail(): Uint32Array {
+    throw new Error('Not a Uint32Array');
+  }
+  asArrayOrFail(): number[] {
+    return this;
+  }
+}
+
+export interface BitVector {
+  getBit(index: number): boolean;
+  setBit(index: number): void;
+  clearBit(index: number): void;
+  // Returns the last bit before `index` which is set, or -1 if there are none.
+  previous(index: number): number;
+  get buffer(): ArrayBuffer;
+}
+
+export function createBitVector(lengthOrBuffer: number|ArrayBuffer): BitVector {
+  return new BitVectorImpl(lengthOrBuffer);
+}
+
+class BitVectorImpl extends Uint8Array {
+  constructor(lengthOrBuffer: number|ArrayBuffer) {
+    if (typeof lengthOrBuffer === 'number') {
+      super(Math.ceil(lengthOrBuffer / 8));
+    } else {
+      super(lengthOrBuffer);
+    }
+  }
+  getBit(index: number): boolean {
+    const value = this[index >> 3] & (1 << (index & 7));
+    return value !== 0;
+  }
+  setBit(index: number): void {
+    this[index >> 3] |= (1 << (index & 7));
+  }
+  clearBit(index: number): void {
+    this[index >> 3] &= ~(1 << (index & 7));
+  }
+  previous(index: number): number {
+    // First, check for more bits in the current byte.
+    while (index !== ((index >> 3) << 3)) {
+      --index;
+      if (this.getBit(index)) {
+        return index;
+      }
+    }
+    // Next, iterate by bytes to skip over ranges of zeros.
+    let byteIndex: number = (index >> 3) - 1;
+    while (byteIndex >= 0 && this[byteIndex] === 0) {
+      --byteIndex;
+    }
+    if (byteIndex < 0) {
+      return -1;
+    }
+    // Finally, iterate the nonzero byte to find the highest bit.
+    for (index = (byteIndex << 3) + 7; index >= (byteIndex << 3); --index) {
+      if (this.getBit(index)) {
+        return index;
+      }
+    }
+    throw new Error('Unreachable');
+  }
+}

package/lib/front_end/core/platform/TypescriptUtilities.ts

@@ -0,0 +1,86 @@
+// Copyright 2020 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * This is useful to keep TypeScript happy in a test - if you have a value
+ * that's potentially `null` you can use this function to assert that it isn't,
+ * and satisfy TypeScript that the value is present.
+ */
+export function assertNotNullOrUndefined<T>(val: T, message?: string): asserts val is NonNullable<T> {
+  if (val === null || val === undefined) {
+    throw new Error(`Expected given value to not be null/undefined but it was: ${val}${message ? `\n${message}` : ''}`);
+  }
+}
+
+export function assertNever(_type: never, message: string): never {
+  throw new Error(message);
+}
+
+/**
+ * This is useful to check on the type-level that the unhandled cases of
+ * a switch are exactly `T` (where T is usually a union type of enum values).
+ * @param caseVariable
+ */
+export function assertUnhandled<T>(_caseVariable: T): T {
+  return _caseVariable;
+}
+
+export type FieldsThatExtend<Type, Selector> = {
+  [Key in keyof Type]: Type[Key] extends Selector ? Key : never;
+}[keyof Type];
+
+export type PickFieldsThatExtend<Type, Selector> = Pick<Type, FieldsThatExtend<Type, Selector>>;
+
+/**
+ * Turns a Union type (a | b) into an Intersection type (a & b).
+ * This is a helper type to implement the "NoUnion" guard.
+ *
+ * Adapted from https://stackoverflow.com/a/50375286.
+ *
+ * The tautological `T extends any` is necessary to trigger distributivity for
+ * plain unions, e.g. in IntersectionFromUnion<'a'|'b'> TypeScript expands it
+ * to  ('a' extends any ? (arg: 'a') => void : never)
+ *  |  ('b' extends any ? (arg: 'b') => void : never)
+ *
+ * The second extends clause then asks TypeScript to find a type of the form
+ * `(arg: infer U) => void` that upper-bounds the union, i.e., intuitively,
+ * a type that converts to each of the union members. This forces U to be the
+ * intersection of 'a' and 'b' in the example.
+ *
+ * Please note that some intersection types are simply impossible, e.g.
+ * `string & number`. There is no type that fulfills both at the same time. A
+ * union of this kind is reduced to `never`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type IntersectionFromUnion<T> = (T extends any ? (arg: T) => void : never) extends((arg: infer U) => void) ? U : never;
+
+/**
+ * When writing generic code it may be desired to disallow Union types from
+ * being passed. This type can be used in those cases.
+ *
+ *   function foo<T>(argument: NoUnion<T>) {...}
+ *
+ * Would result in a compile error for foo<a|b>(...); invocations as `argument`
+ * would be typed as `never`.
+ *
+ * Adapted from https://stackoverflow.com/a/50641073.
+ *
+ * Conditional types become distributive when receiving a union type. To
+ * prevent this from happening, we use `[T] extends [IntersectionFromUnion<T>]`
+ * instead of `T extends IntersectionFromUnion<T>`.
+ * See: https://www.typescriptlang.org/docs/handbook/2/conditional-types.html
+ */
+export type NoUnion<T> = [T] extends [IntersectionFromUnion<T>] ? T : never;
+
+export type RecursivePartial<T> = {
+  [P in keyof T]?: RecursivePartial<T[P]>;
+};
+
+/**
+ * Note this does not recursively
+ * make Array items readonly at the moment
+ */
+export type RecursiveReadonly<T> = {
+  [P in keyof T]: Readonly<RecursiveReadonly<T[P]>>;
+};

package/lib/front_end/core/platform/UIString.ts

@@ -0,0 +1,39 @@
+// Copyright 2021 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/*
+ * Copyright (C) 2011 Google Inc.  All rights reserved.
+ * Copyright (C) 2006, 2007, 2008 Apple Inc.  All rights reserved.
+ * Copyright (C) 2007 Matt Lilek (pewtermoose@gmail.com).
+ * Copyright (C) 2009 Joseph Pecoraro
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1.  Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ * 2.  Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
+ *     its contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+import type {Brand} from './Brand.js';
+
+export type LocalizedString = Brand<string, 'LocalizedString'>;
+export const LocalizedEmptyString = '' as LocalizedString;

package/lib/front_end/core/platform/UserVisibleError.ts

@@ -0,0 +1,28 @@
+// Copyright 2021 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import type {LocalizedString} from './UIString.js';
+
+/**
+ * Represents an error that might become visible to the user. Where errors
+ * might be surfaced to the user (such as by displaying the message to the
+ * console), this class should be used to enforce that the message is
+ * localized on the way in.
+ */
+export class UserVisibleError extends Error {
+  override readonly message: LocalizedString;
+
+  constructor(message: LocalizedString) {
+    super(message);
+    this.message = message;
+  }
+}
+
+export function isUserVisibleError(error: unknown): error is UserVisibleError {
+  if (typeof error === 'object' && error !== null) {
+    return error instanceof UserVisibleError;
+  }
+
+  return false;
+}

package/lib/front_end/core/platform/platform.ts

@@ -0,0 +1,45 @@
+// Copyright 2019 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as ArrayUtilities from './ArrayUtilities.js';
+import * as Brand from './Brand.js';
+import * as Constructor from './Constructor.js';
+import * as DateUtilities from './DateUtilities.js';
+import * as DevToolsPath from './DevToolsPath.js';
+import * as DOMUtilities from './DOMUtilities.js';
+import * as KeyboardUtilities from './KeyboardUtilities.js';
+import * as MapUtilities from './MapUtilities.js';
+import * as MimeType from './MimeType.js';
+import * as NumberUtilities from './NumberUtilities.js';
+import * as StringUtilities from './StringUtilities.js';
+import * as Timing from './Timing.js';
+import * as TypedArrayUtilities from './TypedArrayUtilities.js';
+import * as TypeScriptUtilities from './TypescriptUtilities.js';
+import * as UIString from './UIString.js';
+import * as UserVisibleError from './UserVisibleError.js';
+
+/* `assertNotNullOrUndefined` also need to be exposed, as TypeScript does
+ * not allow `asserts` functions to be used with qualified access (e.g.
+ * `Platform.TypeScriptUtilities.assertNotNullOrUndefined` causes a compile
+ * error).
+ */
+export {assertNever, assertNotNullOrUndefined, assertUnhandled} from './TypescriptUtilities.js';
+export {
+  ArrayUtilities,
+  Brand,
+  Constructor,
+  DateUtilities,
+  DevToolsPath,
+  DOMUtilities,
+  KeyboardUtilities,
+  MapUtilities,
+  MimeType,
+  NumberUtilities,
+  StringUtilities,
+  Timing,
+  TypedArrayUtilities,
+  TypeScriptUtilities,
+  UIString,
+  UserVisibleError,
+};

package/lib/front_end/core/protocol_client/ConnectionTransport.ts

@@ -0,0 +1,26 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+let connectionFactory: () => ConnectionTransport;
+
+export abstract class ConnectionTransport {
+  declare onMessage: ((arg0: Object) => void)|null;
+
+  // on message from browser
+  abstract setOnMessage(onMessage: (arg0: Object|string) => void): void;
+  abstract setOnDisconnect(onDisconnect: (arg0: string) => void): void;
+
+  // send raw CDP message to browser
+  abstract sendRawMessage(message: string): void;
+
+  abstract disconnect(): Promise<void>;
+
+  static setFactory(factory: () => ConnectionTransport): void {
+    connectionFactory = factory;
+  }
+
+  static getFactory(): () => ConnectionTransport {
+    return connectionFactory;
+  }
+}