@crawlee/browser-pool 3.0.0-alpha.8 → 3.0.0-beta.1

package/abstract-classes/browser-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-plugin.js","sourceRoot":"","sources":["../../src/abstract-classes/browser-plugin.ts"],"names":[],"mappings":"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"}

package/abstract-classes/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function throwImplementationNeeded(methodName: string): never;
+//# sourceMappingURL=utils.d.ts.map

package/abstract-classes/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/abstract-classes/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAEnE"}

package/abstract-classes/utils.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwImplementationNeeded = void 0;
+function throwImplementationNeeded(methodName) {
+    throw new Error(`You need to implement method ${methodName}.`);
+}
+exports.throwImplementationNeeded = throwImplementationNeeded;
+//# sourceMappingURL=utils.js.map

package/abstract-classes/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/abstract-classes/utils.ts"],"names":[],"mappings":";;;AAAA,SAAgB,yBAAyB,CAAC,UAAkB;IACxD,MAAM,IAAI,KAAK,CAAC,gCAAgC,UAAU,GAAG,CAAC,CAAC;AACnE,CAAC;AAFD,8DAEC"}

package/anonymize-proxy.d.ts

@@ -0,0 +1,4 @@
+declare type PromiseVoid = () => Promise<void>;
+export declare const anonymizeProxySugar: (proxyUrl?: string, username?: string, password?: string) => Promise<[string | undefined, PromiseVoid]>;
+export {};
+//# sourceMappingURL=anonymize-proxy.d.ts.map

package/anonymize-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymize-proxy.d.ts","sourceRoot":"","sources":["../src/anonymize-proxy.ts"],"names":[],"mappings":"AAEA,aAAK,WAAW,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvC,eAAO,MAAM,mBAAmB,cACjB,MAAM,aACN,MAAM,aACN,MAAM,KAClB,QAAQ,CAAC,MAAM,GAAG,SAAS,EAAE,WAAW,CAAC,CAgC3C,CAAC"}

package/anonymize-proxy.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anonymizeProxySugar = void 0;
+const proxy_chain_1 = require("proxy-chain");
+const anonymizeProxySugar = async (proxyUrl, username, password) => {
+    if (proxyUrl) {
+        const url = new URL(proxyUrl);
+        if (username || password) {
+            url.username = username ?? '';
+            url.password = password ?? '';
+        }
+        if (url.username || url.password) {
+            const anonymized = await (0, proxy_chain_1.anonymizeProxy)(url.href);
+            return [
+                anonymized,
+                async () => {
+                    await (0, proxy_chain_1.closeAnonymizedProxy)(anonymized, true);
+                },
+            ];
+        }
+        return [
+            undefined,
+            // eslint-disable-next-line @typescript-eslint/no-empty-function
+            async () => { },
+        ];
+    }
+    return [
+        undefined,
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        async () => { },
+    ];
+};
+exports.anonymizeProxySugar = anonymizeProxySugar;
+//# sourceMappingURL=anonymize-proxy.js.map

package/anonymize-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymize-proxy.js","sourceRoot":"","sources":["../src/anonymize-proxy.ts"],"names":[],"mappings":";;;AAAA,6CAAmE;AAI5D,MAAM,mBAAmB,GAAG,KAAK,EACpC,QAAiB,EACjB,QAAiB,EACjB,QAAiB,EACyB,EAAE;IAC5C,IAAI,QAAQ,EAAE;QACV,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;QAE9B,IAAI,QAAQ,IAAI,QAAQ,EAAE;YACtB,GAAG,CAAC,QAAQ,GAAG,QAAQ,IAAI,EAAE,CAAC;YAC9B,GAAG,CAAC,QAAQ,GAAG,QAAQ,IAAI,EAAE,CAAC;SACjC;QAED,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE;YAC9B,MAAM,UAAU,GAAG,MAAM,IAAA,4BAAc,EAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAElD,OAAO;gBACH,UAAU;gBACV,KAAK,IAAI,EAAE;oBACP,MAAM,IAAA,kCAAoB,EAAC,UAAU,EAAE,IAAI,CAAC,CAAC;gBACjD,CAAC;aACJ,CAAC;SACL;QAED,OAAO;YACH,SAAS;YACT,gEAAgE;YAChE,KAAK,IAAI,EAAE,GAAE,CAAC;SACjB,CAAC;KACL;IAED,OAAO;QACH,SAAS;QACT,gEAAgE;QAChE,KAAK,IAAI,EAAE,GAAE,CAAC;KACjB,CAAC;AACN,CAAC,CAAC;AApCW,QAAA,mBAAmB,uBAoC9B"}

package/browser-pool.d.ts

@@ -0,0 +1,406 @@
+import { TypedEmitter } from 'tiny-typed-emitter';
+import { Fingerprint, FingerprintInjector } from 'fingerprint-injector';
+import QuickLRU from 'quick-lru';
+import { BrowserController } from './abstract-classes/browser-controller';
+import { BrowserPlugin } from './abstract-classes/browser-plugin';
+import { BROWSER_POOL_EVENTS } from './events';
+import { LaunchContext } from './launch-context';
+import { InferBrowserPluginArray, UnwrapPromise } from './utils';
+import { FingerprintGeneratorOptions } from './fingerprinting/types';
+export interface BrowserPoolEvents<BC extends BrowserController, Page> {
+    [BROWSER_POOL_EVENTS.PAGE_CREATED]: (page: Page) => void | Promise<void>;
+    [BROWSER_POOL_EVENTS.PAGE_CLOSED]: (page: Page) => void | Promise<void>;
+    [BROWSER_POOL_EVENTS.BROWSER_RETIRED]: (browserController: BC) => void | Promise<void>;
+    [BROWSER_POOL_EVENTS.BROWSER_LAUNCHED]: (browserController: BC) => void | Promise<void>;
+}
+export interface FingerprintsOptions {
+    fingerprintGeneratorOptions?: FingerprintGeneratorOptions;
+    /**
+     * @default true
+     */
+    useFingerprintPerProxyCache?: boolean;
+    /**
+    * @default 10000
+    */
+    fingerprintPerProxyCacheSize?: number;
+}
+export interface BrowserPoolOptions<Plugin extends BrowserPlugin = BrowserPlugin> {
+    /**
+     * Browser plugins are wrappers of browser automation libraries that
+     * allow `BrowserPool` to control browsers with those libraries.
+     * `browser-pool` comes with a `PuppeteerPlugin` and a `PlaywrightPlugin`.
+     */
+    browserPlugins: readonly Plugin[];
+    /**
+     * Sets the maximum number of pages that can be open in a browser at the
+     * same time. Once reached, a new browser will be launched to handle the excess.
+     *
+     * @default 20
+     */
+    maxOpenPagesPerBrowser?: number;
+    /**
+     * Browsers tend to get bloated after processing a lot of pages. This option
+     * configures the number of processed pages after which the browser will
+     * automatically retire and close. A new browser will launch in its place.
+     *
+     * @default 100
+     */
+    retireBrowserAfterPageCount?: number;
+    /**
+     * As we know from experience, async operations of the underlying libraries,
+     * such as launching a browser or opening a new page, can get stuck.
+     * To prevent `BrowserPool` from getting stuck, we add a timeout
+     * to those operations and you can configure it with this option.
+     *
+     * @default 15
+     */
+    operationTimeoutSecs?: number;
+    /**
+     * Browsers normally close immediately after their last page is processed.
+     * However, there could be situations where this does not happen. Browser Pool
+     * makes sure all inactive browsers are closed regularly, to free resources.
+     *
+     * @default 300
+     */
+    closeInactiveBrowserAfterSecs?: number;
+    /**
+     * @default true
+     */
+    useFingerprints?: boolean;
+    fingerprintsOptions?: FingerprintsOptions;
+}
+/**
+ * Pre-launch hooks are executed just before a browser is launched and provide
+ * a good opportunity to dynamically change the launch options.
+ * The hooks are called with two arguments:
+ * `pageId`: `string` and `launchContext`: {@link LaunchContext}
+ */
+export declare type PreLaunchHook<LC extends LaunchContext> = (pageId: string, launchContext: LC) => void | Promise<void>;
+/**
+ * Post-launch hooks are executed as soon as a browser is launched.
+ * The hooks are called with two arguments:
+ * `pageId`: `string` and `browserController`: {@link BrowserController}
+ * To guarantee order of execution before other hooks in the same browser,
+ * the {@link BrowserController} methods cannot be used until the post-launch
+ * hooks complete. If you attempt to call `await browserController.close()` from
+ * a post-launch hook, it will deadlock the process. This API is subject to change.
+ */
+export declare type PostLaunchHook<BC extends BrowserController> = (pageId: string, browserController: BC) => void | Promise<void>;
+/**
+ * Pre-page-create hooks are executed just before a new page is created. They
+ * are useful to make dynamic changes to the browser before opening a page.
+ * The hooks are called with three arguments:
+ * `pageId`: `string`, `browserController`: {@link BrowserController} and
+ * `pageOptions`: `object|undefined` - This only works if the underlying `BrowserController` supports new page options.
+ * So far, new page options are only supported by `PlaywrightController`.
+ * If the page options are not supported by `BrowserController` the `pageOptions` argument is `undefined`.
+ */
+export declare type PrePageCreateHook<BC extends BrowserController, PO = Parameters<BC['newPage']>[0]> = (pageId: string, browserController: BC, pageOptions?: PO) => void | Promise<void>;
+/**
+ * Post-page-create hooks are called right after a new page is created
+ * and all internal actions of Browser Pool are completed. This is the
+ * place to make changes to a page that you would like to apply to all
+ * pages. Such as injecting a JavaScript library into all pages.
+ * The hooks are called with two arguments:
+ * `page`: `Page` and `browserController`: {@link BrowserController}
+ */
+export declare type PostPageCreateHook<BC extends BrowserController, Page = UnwrapPromise<ReturnType<BC['newPage']>>> = (page: Page, browserController: BC) => void | Promise<void>;
+/**
+ * Pre-page-close hooks give you the opportunity to make last second changes
+ * in a page that's about to be closed, such as saving a snapshot or updating
+ * state.
+ * The hooks are called with two arguments:
+ * `page`: `Page` and `browserController`: {@link BrowserController}
+ */
+export declare type PrePageCloseHook<BC extends BrowserController, Page = UnwrapPromise<ReturnType<BC['newPage']>>> = (page: Page, browserController: BC) => void | Promise<void>;
+/**
+ * Post-page-close hooks allow you to do page related clean up.
+ * The hooks are called with two arguments:
+ * `pageId`: `string` and `browserController`: {@link BrowserController}
+ */
+export declare type PostPageCloseHook<BC extends BrowserController> = (pageId: string, browserController: BC) => void | Promise<void>;
+export interface BrowserPoolHooks<BC extends BrowserController, LC extends LaunchContext, PR extends UnwrapPromise<ReturnType<BC['newPage']>> = UnwrapPromise<ReturnType<BC['newPage']>>> {
+    /**
+     * Pre-launch hooks are executed just before a browser is launched and provide
+     * a good opportunity to dynamically change the launch options.
+     * The hooks are called with two arguments:
+     * `pageId`: `string` and `launchContext`: {@link LaunchContext}
+     */
+    preLaunchHooks?: PreLaunchHook<LC>[];
+    /**
+     * Post-launch hooks are executed as soon as a browser is launched.
+     * The hooks are called with two arguments:
+     * `pageId`: `string` and `browserController`: {@link BrowserController}
+     * To guarantee order of execution before other hooks in the same browser,
+     * the {@link BrowserController} methods cannot be used until the post-launch
+     * hooks complete. If you attempt to call `await browserController.close()` from
+     * a post-launch hook, it will deadlock the process. This API is subject to change.
+     */
+    postLaunchHooks?: PostLaunchHook<BC>[];
+    /**
+     * Pre-page-create hooks are executed just before a new page is created. They
+     * are useful to make dynamic changes to the browser before opening a page.
+     * The hooks are called with three arguments:
+     * `pageId`: `string`, `browserController`: {@link BrowserController} and
+     * `pageOptions`: `object|undefined` - This only works if the underlying `BrowserController` supports new page options.
+     * So far, new page options are only supported by `PlaywrightController`.
+     * If the page options are not supported by `BrowserController` the `pageOptions` argument is `undefined`.
+     */
+    prePageCreateHooks?: PrePageCreateHook<BC>[];
+    /**
+     * Post-page-create hooks are called right after a new page is created
+     * and all internal actions of Browser Pool are completed. This is the
+     * place to make changes to a page that you would like to apply to all
+     * pages. Such as injecting a JavaScript library into all pages.
+     * The hooks are called with two arguments:
+     * `page`: `Page` and `browserController`: {@link BrowserController}
+     */
+    postPageCreateHooks?: PostPageCreateHook<BC, PR>[];
+    /**
+     * Pre-page-close hooks give you the opportunity to make last second changes
+     * in a page that's about to be closed, such as saving a snapshot or updating
+     * state.
+     * The hooks are called with two arguments:
+     * `page`: `Page` and `browserController`: {@link BrowserController}
+     */
+    prePageCloseHooks?: PrePageCloseHook<BC, PR>[];
+    /**
+     * Post-page-close hooks allow you to do page related clean up.
+     * The hooks are called with two arguments:
+     * `pageId`: `string` and `browserController`: {@link BrowserController}
+     */
+    postPageCloseHooks?: PostPageCloseHook<BC>[];
+}
+/**
+ * The `BrowserPool` class is the most important class of the `browser-pool` module.
+ * It manages opening and closing of browsers and their pages and its constructor
+ * options allow easy configuration of the browsers' and pages' lifecycle.
+ *
+ * The most important and useful constructor options are the various lifecycle hooks.
+ * Those allow you to sequentially call a list of (asynchronous) functions at each
+ * stage of the browser / page lifecycle.
+ *
+ * **Example:**
+ * ```js
+ * const { BrowserPool, PlaywrightPlugin } = require('@crawlee/browser-pool');
+// @ts-ignore optional peer dependency
+ * const playwright = require('playwright');
+ *
+ * const browserPool = new BrowserPool({
+ *     browserPlugins: [ new PlaywrightPlugin(playwright.chromium)],
+ *     preLaunchHooks: [(pageId, launchContext) => {
+ *         // do something before a browser gets launched
+ *         launchContext.launchOptions.headless = false;
+ *     }],
+ *     postLaunchHooks: [(pageId, browserController) => {
+ *         // manipulate the browser right after launch
+ *         console.dir(browserController.browser.contexts());
+ *     }],
+ *     prePageCreateHooks: [(pageId, browserController) => {
+ *         if (pageId === 'my-page') {
+ *             // make changes right before a specific page is created
+ *         }
+ *     }],
+ *     postPageCreateHooks: [async (page, browserController) => {
+ *         // update some or all new pages
+ *         await page.evaluate(() => {
+ *             // now all pages will have 'foo'
+ *             window.foo = 'bar'
+ *         })
+ *     }],
+ *     prePageCloseHooks: [async (page, browserController) => {
+ *         // collect information just before a page closes
+ *         await page.screenshot();
+ *     }],
+ *     postPageCloseHooks: [(pageId, browserController) => {
+ *         // clean up or log after a job is done
+ *         console.log('Page closed: ', pageId)
+ *     }]
+ * });
+ * ```
+ */
+export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoolOptions, BrowserPlugins extends BrowserPlugin[] = InferBrowserPluginArray<Options['browserPlugins']>, BrowserControllerReturn extends BrowserController = ReturnType<BrowserPlugins[number]['createController']>, LaunchContextReturn extends LaunchContext = ReturnType<BrowserPlugins[number]['createLaunchContext']>, PageOptions = Parameters<BrowserControllerReturn['newPage']>[0], PageReturn extends UnwrapPromise<ReturnType<BrowserControllerReturn['newPage']>> = UnwrapPromise<ReturnType<BrowserControllerReturn['newPage']>>> extends TypedEmitter<BrowserPoolEvents<BrowserControllerReturn, PageReturn>> {
+    browserPlugins: BrowserPlugins;
+    maxOpenPagesPerBrowser: number;
+    retireBrowserAfterPageCount: number;
+    operationTimeoutMillis: number;
+    closeInactiveBrowserAfterMillis: number;
+    useFingerprints?: boolean;
+    fingerprintsOptions: FingerprintsOptions;
+    preLaunchHooks: PreLaunchHook<LaunchContextReturn>[];
+    postLaunchHooks: PostLaunchHook<BrowserControllerReturn>[];
+    prePageCreateHooks: PrePageCreateHook<BrowserControllerReturn, PageOptions>[];
+    postPageCreateHooks: PostPageCreateHook<BrowserControllerReturn, PageReturn>[];
+    prePageCloseHooks: PrePageCloseHook<BrowserControllerReturn, PageReturn>[];
+    postPageCloseHooks: PostPageCloseHook<BrowserControllerReturn>[];
+    pageCounter: number;
+    pages: Map<string, PageReturn>;
+    pageIds: WeakMap<PageReturn, string>;
+    activeBrowserControllers: Set<BrowserControllerReturn>;
+    retiredBrowserControllers: Set<BrowserControllerReturn>;
+    pageToBrowserController: WeakMap<PageReturn, BrowserControllerReturn>;
+    fingerprintInjector?: FingerprintInjector;
+    fingerprintGenerator?: any;
+    fingerprintCache?: QuickLRU<string, Fingerprint>;
+    private browserKillerInterval?;
+    private limiter;
+    constructor(options: Options & BrowserPoolHooks<BrowserControllerReturn, LaunchContextReturn, PageReturn>);
+    /**
+     * Opens a new page in one of the running browsers or launches
+     * a new browser and opens a page there, if no browsers are active,
+     * or their page limits have been exceeded.
+     */
+    newPage(options?: BrowserPoolNewPageOptions<PageOptions, BrowserPlugins[number]>): Promise<PageReturn>;
+    /**
+     * Unlike {@link newPage}, `newPageInNewBrowser` always launches a new
+     * browser to open the page in. Use the `launchOptions` option to
+     * configure the new browser.
+     */
+    newPageInNewBrowser(options?: BrowserPoolNewPageInNewBrowserOptions<PageOptions, BrowserPlugins[number]>): Promise<PageReturn>;
+    /**
+     * Opens new pages with all available plugins and returns an array
+     * of pages in the same order as the plugins were provided to `BrowserPool`.
+     * This is useful when you want to run a script in multiple environments
+     * at the same time, typically in testing or website analysis.
+     *
+     * **Example:**
+     * ```js
+     * const browserPool = new BrowserPool({
+     *     browserPlugins: [
+     *         new PlaywrightPlugin(playwright.chromium),
+     *         new PlaywrightPlugin(playwright.firefox),
+     *         new PlaywrightPlugin(playwright.webkit),
+     *         new PuppeteerPlugin(puppeteer),
+     *     ]
+     * });
+     *
+     * const pages = await browserPool.newPageWithEachPlugin();
+     * const [chromiumPage, firefoxPage, webkitPage, puppeteerPage] = pages;
+     * ```
+     */
+    newPageWithEachPlugin(optionsList?: Omit<BrowserPoolNewPageOptions<PageOptions, BrowserPlugins[number]>, 'browserPlugin'>[]): Promise<PageReturn[]>;
+    /**
+     * Retrieves a {@link BrowserController} for a given page. This is useful
+     * when you're working only with pages and need to access the browser
+     * manipulation functionality.
+     *
+     * You could access the browser directly from the page,
+     * but that would circumvent `BrowserPool` and most likely
+     * cause weird things to happen, so please always use `BrowserController`
+     * to control your browsers. The function returns `undefined` if the
+     * browser is closed.
+     *
+     * @param page - Browser plugin page
+     */
+    getBrowserControllerByPage(page: PageReturn): BrowserControllerReturn | undefined;
+    /**
+     * If you provided a custom ID to one of your pages or saved the
+     * randomly generated one, you can use this function to retrieve
+     * the page. If the page is no longer open, the function will
+     * return `undefined`.
+     */
+    getPage(id: string): PageReturn | undefined;
+    /**
+     * Page IDs are used throughout `BrowserPool` as a method of linking
+     * events. You can use a page ID to track the full lifecycle of the page.
+     * It is created even before a browser is launched and stays with the page
+     * until it's closed.
+     */
+    getPageId(page: PageReturn): string | undefined;
+    private _createPageForBrowser;
+    /**
+     * Removes a browser controller from the pool. The underlying
+     * browser will be closed after all its pages are closed.
+     *
+     */
+    retireBrowserController(browserController: BrowserControllerReturn): void;
+    /**
+     * Removes a browser from the pool. It will be
+     * closed after all its pages are closed.
+     */
+    retireBrowserByPage(page: PageReturn): void;
+    /**
+     * Removes all active browsers from the pool. The browsers will be
+     * closed after all their pages are closed.
+     */
+    retireAllBrowsers(): void;
+    /**
+     * Closes all managed browsers without waiting for pages to close.
+     * @return {Promise<void>}
+     */
+    closeAllBrowsers(): Promise<void>;
+    /**
+     * Closes all managed browsers and tears down the pool.
+     */
+    destroy(): Promise<void>;
+    private _teardown;
+    private _getAllBrowserControllers;
+    private _launchBrowser;
+    /**
+     * Picks plugins round robin.
+     * @private
+     */
+    private _pickBrowserPlugin;
+    private _pickBrowserWithFreeCapacity;
+    private _closeInactiveRetiredBrowsers;
+    private _overridePageClose;
+    private _executeHooks;
+    private _closeRetiredBrowserWithNoPages;
+    private _initializeFingerprinting;
+    private _addFingerprintHooks;
+}
+export interface BrowserPoolNewPageOptions<PageOptions, BP extends BrowserPlugin> {
+    /**
+     * Assign a custom ID to the page. If you don't a random string ID
+     * will be generated.
+     */
+    id?: string;
+    /**
+     * Some libraries (Playwright) allow you to open new pages with specific
+     * options. Use this property to set those options.
+     */
+    pageOptions?: PageOptions;
+    /**
+     * Choose a plugin to open the page with. If none is provided,
+     * one of the pool's available plugins will be used.
+     *
+     * It must be one of the plugins browser pool was created with.
+     * If you wish to start a browser with a different configuration,
+     * see the `newPageInNewBrowser` function.
+     */
+    browserPlugin?: BP;
+    /**
+     * Proxy URL.
+     */
+    proxyUrl?: string;
+}
+export interface BrowserPoolNewPageInNewBrowserOptions<PageOptions, BP extends BrowserPlugin> {
+    /**
+     * Assign a custom ID to the page. If you don't a random string ID
+     * will be generated.
+     */
+    id?: string;
+    /**
+     * Some libraries (Playwright) allow you to open new pages with specific
+     * options. Use this property to set those options.
+     */
+    pageOptions?: PageOptions;
+    /**
+     *  Provide a plugin to launch the browser. If none is provided,
+     *  one of the pool's available plugins will be used.
+     *
+     *  If you configured `BrowserPool` to rotate multiple libraries,
+     *  such as both Puppeteer and Playwright, you should always set
+     *  the `browserPlugin` when using the `launchOptions` option.
+     *
+     *  The plugin will not be added to the list of plugins used by
+     *  the pool. You can either use one of those, to launch a specific
+     *  browser, or provide a completely new configuration.
+     */
+    browserPlugin?: BP;
+    /**
+     * Options that will be used to launch the new browser.
+     */
+    launchOptions?: BP['launchOptions'];
+}
+//# sourceMappingURL=browser-pool.d.ts.map

package/browser-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.d.ts","sourceRoot":"","sources":["../src/browser-pool.ts"],"names":[],"mappings":"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"}