@crawlee/browser-pool 4.0.0-beta.98 → 4.0.0-rc.0

package/fingerprinting/types.d.ts

@@ -36,7 +36,7 @@ export interface BrowserSpecification {
      */
     httpVersion?: HttpVersion;
 }
-export declare const enum OperatingSystemsName {
+export declare enum OperatingSystemsName {
     linux = "linux",
     macos = "macos",
     windows = "windows",
@@ -49,7 +49,7 @@ export declare const enum OperatingSystemsName {
      */
     ios = "ios"
 }
-export declare const enum DeviceCategory {
+export declare enum DeviceCategory {
     /**
      * Describes mobile devices (mobile phones, tablets...). These devices usually have smaller, vertical screens and load lighter versions of websites.
      * > Note: Generating `android` and `ios` devices will not work without setting the device to `mobile` first.

package/fingerprinting/utils.js

@@ -1,10 +1,10 @@
 import { PlaywrightPlugin } from '../playwright/playwright-plugin.js';
 import { PuppeteerPlugin } from '../puppeteer/puppeteer-plugin.js';
-import { BrowserName } from './types.js';
+import { BrowserName, DeviceCategory, OperatingSystemsName } from './types.js';
 export const getGeneratorDefaultOptions = (launchContext) => {
     const { browserPlugin, launchOptions } = launchContext;
     const options = {
-        devices: ["desktop" /* DeviceCategory.desktop */],
+        devices: [DeviceCategory.desktop],
         locales: ['en-US'],
         browsers: [getBrowserName(browserPlugin, launchOptions)],
         operatingSystems: [getOperatingSystem()],
@@ -34,11 +34,11 @@ const getOperatingSystem = () => {
     switch (platform) {
         case 'win32':
             // platform is win32 even for 64-bit
-            return "windows" /* OperatingSystemsName.windows */;
+            return OperatingSystemsName.windows;
         case 'darwin':
-            return "macos" /* OperatingSystemsName.macos */;
+            return OperatingSystemsName.macos;
         default:
             // consider everything else a linux
-            return "linux" /* OperatingSystemsName.linux */;
+            return OperatingSystemsName.linux;
     }
 };

package/launch-context.d.ts

@@ -56,6 +56,7 @@ export interface LaunchContextOptions<Library extends CommonLibrary = CommonLibr
     isRemote?: boolean;
 }
 export declare class LaunchContext<Library extends CommonLibrary = CommonLibrary, LibraryOptions extends Dictionary | undefined = Parameters<Library['launch']>[0], LaunchResult extends CommonBrowser = UnwrapPromise<ReturnType<Library['launch']>>, NewPageOptions = Parameters<LaunchResult['newPage']>[0], NewPageResult = UnwrapPromise<ReturnType<LaunchResult['newPage']>>> {
+    #private;
     id?: string;
     browserPlugin: BrowserPlugin<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult>;
     launchOptions: LibraryOptions;
@@ -64,15 +65,13 @@ export declare class LaunchContext<Library extends CommonLibrary = CommonLibrary
     userDataDir: string;
     readonly isRemote: boolean;
     ignoreProxyCertificate?: boolean;
-    private _proxyUrl?;
-    private readonly _reservedFieldNames;
     fingerprint?: BrowserFingerprintWithHeaders;
     /**
      * Token identifying the remote browser session this context connected to, set by the plugin and read by
      * the {@link RemoteBrowserPool} to release the session on close. Only present for remote connections.
      * @internal
      */
-    _remoteToken?: number;
+    remoteToken?: number;
     [K: PropertyKey]: unknown;
     constructor(options: LaunchContextOptions<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult>);
     /**

package/launch-context.js

@@ -7,15 +7,15 @@ export class LaunchContext {
     userDataDir;
     isRemote;
     ignoreProxyCertificate;
-    _proxyUrl;
-    _reservedFieldNames = [...Reflect.ownKeys(this), 'extend'];
+    #proxyUrl;
+    #reservedFieldNames;
     fingerprint;
     /**
      * Token identifying the remote browser session this context connected to, set by the plugin and read by
      * the {@link RemoteBrowserPool} to release the session on close. Only present for remote connections.
      * @internal
      */
-    _remoteToken;
+    remoteToken;
     constructor(options) {
         const { id, browserPlugin, launchOptions, proxyUrl, useIncognitoPages, browserPerProxy, userDataDir = '', ignoreProxyCertificate, isRemote, } = options;
         this.id = id;
@@ -26,7 +26,10 @@ export class LaunchContext {
         this.userDataDir = userDataDir;
         this.ignoreProxyCertificate = ignoreProxyCertificate ?? false;
         this.isRemote = isRemote ?? false;
-        this._proxyUrl = proxyUrl;
+        this.#proxyUrl = proxyUrl;
+        // Computed here (not in a field initializer) so that all fields already exist; the accessors live on
+        // the prototype, so they are never own keys and have to be listed explicitly.
+        this.#reservedFieldNames = [...Reflect.ownKeys(this), 'proxyUrl', 'remoteToken', 'extend'];
     }
     /**
      * Extend the launch context with any extra fields.
@@ -37,7 +40,7 @@ export class LaunchContext {
      */
     extend(fields) {
         Object.entries(fields).forEach(([key, value]) => {
-            if (this._reservedFieldNames.includes(key)) {
+            if (this.#reservedFieldNames.includes(key)) {
                 throw new Error(`Cannot extend LaunchContext with key: ${key}, because it's reserved.`);
             }
             else {
@@ -51,7 +54,7 @@ export class LaunchContext {
      */
     set proxyUrl(url) {
         if (!url) {
-            this._proxyUrl = undefined;
+            this.#proxyUrl = undefined;
             return;
         }
         const urlInstance = new URL(url);
@@ -59,12 +62,12 @@ export class LaunchContext {
         urlInstance.search = '';
         urlInstance.hash = '';
         // https://www.chromium.org/developers/design-documents/network-settings/#command-line-options-for-proxy-settings
-        this._proxyUrl = urlInstance.href.slice(0, -1);
+        this.#proxyUrl = urlInstance.href.slice(0, -1);
     }
     /**
      * Returns the proxy URL of the browser.
      */
     get proxyUrl() {
-        return this._proxyUrl;
+        return this.#proxyUrl;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/browser-pool",
-    "version": "4.0.0-beta.98",
+    "version": "4.0.0-rc.0",
     "description": "Rotate multiple browsers using popular automation libraries such as Playwright or Puppeteer.",
     "engines": {
         "node": ">=22.0.0"
@@ -31,18 +31,18 @@
     },
     "dependencies": {
         "@apify/timeout": "^0.4.4",
-        "@crawlee/core": "4.0.0-beta.98",
-        "@crawlee/types": "4.0.0-beta.98",
+        "@crawlee/core": "4.0.0-rc.0",
+        "@crawlee/types": "4.0.0-rc.0",
         "fingerprint-generator": "^2.1.68",
         "fingerprint-injector": "^2.1.68",
         "lodash.merge": "^4.6.2",
         "nanoid": "^5.1.5",
-        "ow": "^2.0.0",
         "p-limit": "^6.2.0",
         "proxy-chain": "^2.5.8",
         "quick-lru": "^7.0.1",
         "tiny-typed-emitter": "^2.1.0",
-        "tslib": "^2.8.1"
+        "tslib": "^2.8.1",
+        "zod": "^4.4.3"
     },
     "peerDependencies": {
         "playwright": "*",
@@ -63,5 +63,5 @@
             }
         }
     },
-    "gitHead": "3b8cd86b13e253ab5fc71e631e12a68f7465cee5"
+    "gitHead": "79ab33dacdacb83e0197e6516d145f3aceef80c7"
 }

package/playwright/playwright-browser.d.ts

@@ -9,10 +9,7 @@ export interface BrowserOptions {
  * Browser wrapper created to have consistent API with persistent and non-persistent contexts.
  */
 export declare class PlaywrightBrowser extends EventEmitter {
-    private _browserContext;
-    private _version;
-    private _isConnected;
-    private _browserType?;
+    #private;
     constructor(options: BrowserOptions);
     [Symbol.asyncDispose](): Promise<void>;
     close(): Promise<void>;
@@ -20,7 +17,7 @@ export declare class PlaywrightBrowser extends EventEmitter {
     isConnected(): boolean;
     version(): string;
     /** @internal */
-    _setBrowserType(browserType: BrowserType): void;
+    setBrowserType(browserType: BrowserType): void;
     browserType(): BrowserType;
     newPage(...args: Parameters<BrowserContext['newPage']>): ReturnType<BrowserContext['newPage']>;
     newContext(): Promise<never>;

package/playwright/playwright-browser.js

@@ -3,17 +3,17 @@ import { EventEmitter } from 'node:events';
  * Browser wrapper created to have consistent API with persistent and non-persistent contexts.
  */
 export class PlaywrightBrowser extends EventEmitter {
-    _browserContext;
-    _version;
-    _isConnected = true;
-    _browserType;
+    #browserContext;
+    #version;
+    #isConnected = true;
+    #browserType;
     constructor(options) {
         super();
         const { browserContext, version } = options;
-        this._browserContext = browserContext;
-        this._version = version;
-        this._browserContext.once('close', () => {
-            this._isConnected = false;
+        this.#browserContext = browserContext;
+        this.#version = version;
+        this.#browserContext.once('close', () => {
+            this.#isConnected = false;
             this.emit('disconnected');
         });
     }
@@ -21,26 +21,26 @@ export class PlaywrightBrowser extends EventEmitter {
         await this.close();
     }
     async close() {
-        await this._browserContext.close();
+        await this.#browserContext.close();
     }
     contexts() {
-        return [this._browserContext];
+        return [this.#browserContext];
     }
     isConnected() {
-        return this._isConnected;
+        return this.#isConnected;
     }
     version() {
-        return this._version;
+        return this.#version;
     }
     /** @internal */
-    _setBrowserType(browserType) {
-        this._browserType = browserType;
+    setBrowserType(browserType) {
+        this.#browserType = browserType;
     }
     browserType() {
-        return this._browserType;
+        return this.#browserType;
     }
     async newPage(...args) {
-        return this._browserContext.newPage(...args);
+        return this.#browserContext.newPage(...args);
     }
     async newContext() {
         throw new Error('Function `newContext()` is not available in incognito mode');

package/playwright/playwright-plugin.d.ts

@@ -6,15 +6,15 @@ import type { RemoteConnection, RemoteConnectionParameters } from '../remote-bro
 import type { SafeParameters } from '../utils.js';
 import { PlaywrightController } from './playwright-controller.js';
 export declare class PlaywrightPlugin extends BrowserPlugin<BrowserType, SafeParameters<BrowserType['launch']>[0], PlaywrightBrowser> {
-    private _browserVersion?;
+    #private;
     /**
      * Playwright remote connections only support incognito pages — `connect()` / `connectOverCDP()` don't
      * accept persistent contexts. Force it on (and inform the user) when wired for a remote connection.
      */
     useRemoteConnection(connection: RemoteConnection, parameters?: RemoteConnectionParameters): void;
     protected _launch(launchContext: LaunchContext<BrowserType>): Promise<PlaywrightBrowser>;
-    private _throwOnFailedLaunch;
+    private throwOnFailedLaunch;
     createController(): PlaywrightController;
-    protected _addProxyToLaunchOptions(launchContext: LaunchContext<BrowserType>): Promise<void>;
-    protected _isChromiumBasedBrowser(): boolean;
+    protected addProxyToLaunchOptions(launchContext: LaunchContext<BrowserType>): Promise<void>;
+    protected isChromiumBasedBrowser(): boolean;
 }

package/playwright/playwright-plugin.js

@@ -5,7 +5,7 @@ import { getLocalProxyAddress } from '../proxy-server.js';
 import { PlaywrightBrowser as PlaywrightBrowserWithPersistentContext } from './playwright-browser.js';
 import { PlaywrightController } from './playwright-controller.js';
 export class PlaywrightPlugin extends BrowserPlugin {
-    _browserVersion;
+    #browserVersion;
     /**
      * Playwright remote connections only support incognito pages — `connect()` / `connectOverCDP()` don't
      * accept persistent contexts. Force it on (and inform the user) when wired for a remote connection.
@@ -20,7 +20,7 @@ export class PlaywrightPlugin extends BrowserPlugin {
     }
     async _launch(launchContext) {
         if (this.remoteConnection) {
-            return this._connectToRemoteBrowser(launchContext, async (url) => {
+            return this.connectToRemoteBrowser(launchContext, async (url) => {
                 const connectOptions = (this.remoteConnectionParameters?.connectOptions ?? {});
                 if (this.remoteConnectionParameters?.protocol === 'playwright') {
                     this.log.info('Connecting to remote browser via connect (Playwright WebSocket).');
@@ -53,7 +53,7 @@ export class PlaywrightPlugin extends BrowserPlugin {
         try {
             if (useIncognitoPages) {
                 browser = await this.library.launch(launchOptions).catch((error) => {
-                    return this._throwOnFailedLaunch(launchContext, error);
+                    return this.throwOnFailedLaunch(launchContext, error);
                 });
                 if (anonymizedProxyUrl) {
                     browser.on('disconnected', async () => {
@@ -65,7 +65,7 @@ export class PlaywrightPlugin extends BrowserPlugin {
                 const browserContext = await this.library
                     .launchPersistentContext(userDataDir, launchOptions)
                     .catch((error) => {
-                    return this._throwOnFailedLaunch(launchContext, error);
+                    return this.throwOnFailedLaunch(launchContext, error);
                 });
                 browserContext.once('close', () => {
                     if (userDataDir.includes('apify-playwright-firefox-taac-')) {
@@ -80,18 +80,20 @@ export class PlaywrightPlugin extends BrowserPlugin {
                         await close();
                     });
                 }
-                if (!this._browserVersion) {
+                if (!this.#browserVersion) {
                     // Launches unused browser just to get the browser version.
                     const inactiveBrowser = await this.library.launch(launchOptions);
-                    this._browserVersion = inactiveBrowser.version();
+                    this.#browserVersion = inactiveBrowser.version();
                     inactiveBrowser.close().catch((error) => {
                         this.log.exception(error, 'Failed to close browser.');
                     });
                 }
-                browser = new PlaywrightBrowserWithPersistentContext({
+                const persistentBrowser = new PlaywrightBrowserWithPersistentContext({
                     browserContext,
-                    version: this._browserVersion,
+                    version: this.#browserVersion,
                 });
+                persistentBrowser.setBrowserType(this.library);
+                browser = persistentBrowser;
             }
         }
         catch (error) {
@@ -100,13 +102,13 @@ export class PlaywrightPlugin extends BrowserPlugin {
         }
         return browser;
     }
-    _throwOnFailedLaunch(launchContext, cause) {
-        this._throwAugmentedLaunchError(cause, launchContext.launchOptions?.executablePath, '`apify/actor-node-playwright-*` (with a correct browser name)', 'Try installing the required dependencies by running `npx playwright install --with-deps` (https://playwright.dev/docs/browsers).');
+    throwOnFailedLaunch(launchContext, cause) {
+        this.throwAugmentedLaunchError(cause, launchContext.launchOptions?.executablePath, '`apify/actor-node-playwright-*` (with a correct browser name)', 'Try installing the required dependencies by running `npx playwright install --with-deps` (https://playwright.dev/docs/browsers).');
     }
     createController() {
         return new PlaywrightController(this);
     }
-    async _addProxyToLaunchOptions(launchContext) {
+    async addProxyToLaunchOptions(launchContext) {
         launchContext.launchOptions ??= {};
         const { launchOptions, proxyUrl } = launchContext;
         if (proxyUrl) {
@@ -118,7 +120,7 @@ export class PlaywrightPlugin extends BrowserPlugin {
             };
         }
     }
-    _isChromiumBasedBrowser() {
+    isChromiumBasedBrowser() {
         const name = this.library.name();
         return name === 'chromium';
     }

package/puppeteer/puppeteer-plugin.d.ts

@@ -12,6 +12,6 @@ export declare class PuppeteerPlugin extends BrowserPlugin<typeof Puppeteer, Pup
     useRemoteConnection(connection: RemoteConnection, parameters?: RemoteConnectionParameters): void;
     protected _launch(launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): Promise<PuppeteerTypes.Browser>;
     createController(): PuppeteerController;
-    protected _addProxyToLaunchOptions(_launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): Promise<void>;
-    protected _isChromiumBasedBrowser(_launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): boolean;
+    protected addProxyToLaunchOptions(_launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): Promise<void>;
+    protected isChromiumBasedBrowser(_launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): boolean;
 }

package/puppeteer/puppeteer-plugin.js

@@ -27,7 +27,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
         const { useIncognitoPages, proxyUrl, ignoreProxyCertificate } = launchContext;
         let browser;
         if (this.remoteConnection) {
-            browser = await this._connectToRemoteBrowser(launchContext, async (url) => {
+            browser = await this.connectToRemoteBrowser(launchContext, async (url) => {
                 const connectOptions = this.remoteConnectionParameters?.connectOptions ?? {};
                 this.log.info('Connecting to remote browser via connect (CDP).');
                 return this.library.connect({ ...connectOptions, browserWSEndpoint: url });
@@ -73,7 +73,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
                 }
                 catch (error) {
                     await close();
-                    this._throwAugmentedLaunchError(error, launchContext.launchOptions?.executablePath, '`apify/actor-node-puppeteer-chrome`', "Try installing a browser, if it's missing, by running `npx @puppeteer/browsers install chromium --path [path]` and pointing `executablePath` to the downloaded executable (https://pptr.dev/browsers-api)");
+                    this.throwAugmentedLaunchError(error, launchContext.launchOptions?.executablePath, '`apify/actor-node-puppeteer-chrome`', "Try installing a browser, if it's missing, by running `npx @puppeteer/browsers install chromium --path [path]` and pointing `executablePath` to the downloaded executable (https://pptr.dev/browsers-api)");
                 }
             }
         }
@@ -177,7 +177,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
     createController() {
         return new PuppeteerController(this);
     }
-    async _addProxyToLaunchOptions(_launchContext) {
+    async addProxyToLaunchOptions(_launchContext) {
         /*
         // DO NOT USE YET! DOING SO DISABLES CACHE WHICH IS 50% PERFORMANCE HIT!
         launchContext.launchOptions ??= {};
@@ -204,7 +204,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
         }
         */
     }
-    _isChromiumBasedBrowser(_launchContext) {
+    isChromiumBasedBrowser(_launchContext) {
         return true;
     }
 }

package/remote-browser-pool.d.ts

@@ -32,8 +32,6 @@ export type RemoteBrowserEndpoint = string | ((options?: {
  * the pool. The plugin calls {@link RemoteConnection.resolve|resolve} before connecting, stores the
  * returned `token` on its launch context, and the controller later calls
  * {@link RemoteConnection.release|release} with that token when the browser closes.
- *
- * @internal
  */
 export interface RemoteConnection {
     /** Resolves the endpoint for a single browser launch. The `token` identifies the session for release. */
@@ -97,10 +95,10 @@ export interface RemoteBrowserPoolOptions {
     slotPollIntervalMillis?: number;
 }
 /**
- * The remote-connection configuration a browser crawler accepts on its `remoteBrowser` option. It is the
- * {@link RemoteBrowserPoolOptions} a user supplies *minus* the parts the crawler provides itself — the
- * `browserPlugins` (the crawler builds the correct one for its browser) and `browserPoolOptions` (taken from
- * the crawler's own `browserPoolOptions`). This is what makes the crawler path both terse and mismatch-proof.
+ * The remote-connection configuration a browser crawler accepts on its `remoteBrowser` option: the
+ * {@link RemoteBrowserPoolOptions} minus the `browserPlugins` (the crawler builds the correct one for its
+ * browser, which is what makes this path mismatch-proof) and minus `browserPoolOptions` — tuning the wrapping
+ * pool means building the pool yourself, through the `remote*BrowserPool()` factory for your crawler.
  */
 export type CrawlerRemoteBrowserOptions = Omit<RemoteBrowserPoolOptions, 'browserPlugins' | 'browserPoolOptions'>;
 /**
@@ -136,15 +134,9 @@ export type CrawlerRemoteBrowserOptions = Omit<RemoteBrowserPoolOptions, 'browse
  * @category Browser management
  */
 export declare class RemoteBrowserPool<Page = unknown> implements IBrowserPool<Page> {
+    #private;
     /** The wrapped pool that performs the remote connections and serves pages. */
     readonly browserPool: BrowserPool;
-    /** The wrapped pool viewed through the {@link IBrowserPool} contract (the bare type widens pages to `never`). */
-    private readonly pool;
-    private readonly registry;
-    private readonly slotPollIntervalMillis;
-    private readonly log;
-    /** Shared by all `newPage` callers waiting for a free slot, so they don't each register their own listeners. */
-    private _capacityChange?;
     constructor(options: RemoteBrowserPoolOptions);
     /** Maximum number of remote browsers that may be open at the same time. */
     get maxOpenBrowsers(): number;
@@ -162,11 +154,11 @@ export declare class RemoteBrowserPool<Page = unknown> implements IBrowserPool<P
     /** Closes all browsers, releases any still-open remote sessions, and tears down the wrapped pool. */
     destroy(): Promise<void>;
     /** Resolves once the wrapped pool can serve another page without exceeding `maxOpenBrowsers`. */
-    private _waitForFreeSlot;
+    private waitForFreeSlot;
     /**
      * Resolves on the next browser-retired / page-closed event, or after `slotPollIntervalMillis`. All
      * concurrently-waiting `newPage` calls share a single promise (and a single pair of event listeners)
      * per tick, so a fleet of saturated callers doesn't fan out into N listener pairs on the pool.
      */
-    private _nextCapacityChange;
+    private nextCapacityChange;
 }