tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

Puppeteer.ts (3155B)

      1 /**
      2 * @license
      3 * Copyright 2017 Google Inc.
      4 * SPDX-License-Identifier: Apache-2.0
      5 */
      6 
      7 import type {Browser} from '../api/Browser.js';
      8 
      9 import {_connectToBrowser} from './BrowserConnector.js';
     10 import type {ConnectOptions} from './ConnectOptions.js';
     11 import {
     12  type CustomQueryHandler,
     13  customQueryHandlers,
     14 } from './CustomQueryHandler.js';
     15 
     16 /**
     17 * Settings that are common to the Puppeteer class, regardless of environment.
     18 *
     19 * @internal
     20 */
     21 export interface CommonPuppeteerSettings {
     22  isPuppeteerCore: boolean;
     23 }
     24 
     25 /**
     26 * The main Puppeteer class.
     27 *
     28 * IMPORTANT: if you are using Puppeteer in a Node environment, you will get an
     29 * instance of {@link PuppeteerNode} when you import or require `puppeteer`.
     30 * That class extends `Puppeteer`, so has all the methods documented below as
     31 * well as all that are defined on {@link PuppeteerNode}.
     32 *
     33 * @public
     34 */
     35 export class Puppeteer {
     36  /**
     37   * Operations for {@link CustomQueryHandler | custom query handlers}. See
     38   * {@link CustomQueryHandlerRegistry}.
     39   *
     40   * @internal
     41   */
     42  static customQueryHandlers = customQueryHandlers;
     43 
     44  /**
     45   * Registers a {@link CustomQueryHandler | custom query handler}.
     46   *
     47   * @remarks
     48   * After registration, the handler can be used everywhere where a selector is
     49   * expected by prepending the selection string with `<name>/`. The name is only
     50   * allowed to consist of lower- and upper case latin letters.
     51   *
     52   * @example
     53   *
     54   * ```
     55   * import {Puppeteer}, puppeteer from 'puppeteer';
     56   *
     57   * Puppeteer.registerCustomQueryHandler('text', { … });
     58   * const aHandle = await page.$('text/…');
     59   * ```
     60   *
     61   * @param name - The name that the custom query handler will be registered
     62   * under.
     63   * @param queryHandler - The {@link CustomQueryHandler | custom query handler}
     64   * to register.
     65   *
     66   * @public
     67   */
     68  static registerCustomQueryHandler(
     69    name: string,
     70    queryHandler: CustomQueryHandler,
     71  ): void {
     72    return this.customQueryHandlers.register(name, queryHandler);
     73  }
     74 
     75  /**
     76   * Unregisters a custom query handler for a given name.
     77   */
     78  static unregisterCustomQueryHandler(name: string): void {
     79    return this.customQueryHandlers.unregister(name);
     80  }
     81 
     82  /**
     83   * Gets the names of all custom query handlers.
     84   */
     85  static customQueryHandlerNames(): string[] {
     86    return this.customQueryHandlers.names();
     87  }
     88 
     89  /**
     90   * Unregisters all custom query handlers.
     91   */
     92  static clearCustomQueryHandlers(): void {
     93    return this.customQueryHandlers.clear();
     94  }
     95 
     96  /**
     97   * @internal
     98   */
     99  _isPuppeteerCore: boolean;
    100  /**
    101   * @internal
    102   */
    103  protected _changedBrowsers = false;
    104 
    105  /**
    106   * @internal
    107   */
    108  constructor(settings: CommonPuppeteerSettings) {
    109    this._isPuppeteerCore = settings.isPuppeteerCore;
    110 
    111    this.connect = this.connect.bind(this);
    112  }
    113 
    114  /**
    115   * This method attaches Puppeteer to an existing browser instance.
    116   *
    117   * @remarks
    118   *
    119   * @param options - Set of configurable options to set on the browser.
    120   * @returns Promise which resolves to browser instance.
    121   */
    122  connect(options: ConnectOptions): Promise<Browser> {
    123    return _connectToBrowser(options);
    124  }
    125 }