@crawlee/browser-pool 4.0.0-beta.67 → 4.0.0-beta.68

package/remote-browser-pool.js

@@ -0,0 +1,192 @@
+import { serviceLocator } from '@crawlee/core';
+import { BrowserPool } from './browser-pool.js';
+import { RemoteBrowserProvider } from './remote-browser-provider.js';
+/**
+ * Owns the lifecycle of remote browser sessions for a single {@link RemoteBrowserPool}: endpoint
+ * resolution, the user's `release()` callback, and a release-at-most-once guarantee. Implements
+ * {@link RemoteConnection} so it can be injected into a plugin.
+ */
+class RemoteSessionRegistry {
+    endpoint;
+    onRelease;
+    log;
+    sessions = new Map();
+    nextToken = 0;
+    constructor(endpoint, onRelease, log) {
+        this.endpoint = endpoint;
+        this.onRelease = onRelease;
+        this.log = log;
+    }
+    async resolve(options) {
+        const resolved = typeof this.endpoint === 'function' ? await this.endpoint(options) : this.endpoint;
+        let result;
+        if (typeof resolved === 'string') {
+            if (!resolved)
+                throw new Error('Remote browser endpoint resolved to an empty string.');
+            result = { url: resolved };
+        }
+        else if (!resolved?.url) {
+            throw new Error("Remote browser endpoint() must return a URL string or an object with a non-empty 'url'.");
+        }
+        else {
+            result = resolved;
+        }
+        const token = this.nextToken++;
+        this.sessions.set(token, { url: result.url, context: result.context, released: false });
+        return { url: result.url, token };
+    }
+    async release(token) {
+        const session = this.sessions.get(token);
+        // Release at most once per session — guards a close()/teardown race (the `released` flag is set
+        // synchronously before the awaited onRelease, so releaseAll() can't double-fire an in-flight release).
+        if (!session || session.released)
+            return;
+        session.released = true;
+        try {
+            await this.onRelease?.({ endpoint: session.url, context: session.context });
+        }
+        catch (err) {
+            this.log.warning('Remote browser release() failed.', { error: err?.message });
+        }
+        finally {
+            this.sessions.delete(token);
+        }
+    }
+    /** Releases every session that is still open. Called on pool teardown so no remote session leaks. */
+    async releaseAll() {
+        await Promise.all([...this.sessions.keys()].map(async (token) => this.release(token)));
+    }
+}
+/**
+ * An {@link IBrowserPool} implementation for remote browser services.
+ *
+ * Unlike configuring a remote browser through a crawler's `launchContext`, this pool is the single owner
+ * of all remote-session concerns:
+ * - **endpoint resolution** — static URL, per-launch function, or {@link RemoteBrowserProvider};
+ * - **release lifecycle** — `release()` fires exactly once per session on close/crash/teardown (no leaks,
+ *   no double-release);
+ * - **concurrency** — {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers} is enforced inside
+ *   {@link RemoteBrowserPool.newPage|newPage}, which waits for a free slot rather than overshooting.
+ *
+ * The wrapped {@link BrowserPool} and its plugin only perform the library-specific `connect()` call.
+ *
+ * Pass an instance as the crawler's `browserPool` option:
+ *
+ * ```typescript
+ * import { PlaywrightPlugin, RemoteBrowserPool } from '@crawlee/browser-pool';
+ * import { PlaywrightCrawler } from 'crawlee';
+ * import playwright from 'playwright';
+ *
+ * const browserPool = new RemoteBrowserPool({
+ *     browserPlugins: [new PlaywrightPlugin(playwright.chromium)],
+ *     endpoint: 'wss://production-sfo.browserless.io?token=xxx',
+ *     maxOpenBrowsers: 2,
+ * });
+ *
+ * const crawler = new PlaywrightCrawler({ browserPool });
+ * ```
+ *
+ * @category Browser management
+ */
+export class RemoteBrowserPool {
+    /** The wrapped pool that performs the remote connections and serves pages. */
+    browserPool;
+    /** The wrapped pool viewed through the {@link IBrowserPool} contract (the bare type widens pages to `never`). */
+    pool;
+    registry;
+    slotPollIntervalMillis;
+    log;
+    /** Shared by all `newPage` callers waiting for a free slot, so they don't each register their own listeners. */
+    _capacityChange;
+    constructor(options) {
+        const { browserPlugins, endpoint, release, maxOpenBrowsers, connection = {}, browserPoolOptions = {}, slotPollIntervalMillis = 500, } = options;
+        this.log = serviceLocator.getLogger().child({ prefix: 'RemoteBrowserPool' });
+        this.slotPollIntervalMillis = slotPollIntervalMillis;
+        // A RemoteBrowserProvider carries its own endpoint, release, and maxOpenBrowsers.
+        const provider = endpoint instanceof RemoteBrowserProvider ? endpoint : undefined;
+        const resolvedEndpoint = provider
+            ? (opts) => provider.connect(opts)
+            : endpoint;
+        const resolvedRelease = provider
+            ? ({ context }) => provider.release(context)
+            : release;
+        const resolvedMax = maxOpenBrowsers ?? provider?.maxOpenBrowsers;
+        this.registry = new RemoteSessionRegistry(resolvedEndpoint, resolvedRelease, this.log);
+        // Wire every plugin for remote connection.
+        for (const plugin of browserPlugins) {
+            plugin.useRemoteConnection(this.registry, connection);
+        }
+        this.browserPool = new BrowserPool({ ...browserPoolOptions, browserPlugins });
+        this.pool = this.browserPool;
+        // Release a browser's remote session once it closes. The registry dedupes (close() schedules a delayed
+        // kill(), so BROWSER_CLOSED can fire twice), and destroy()'s releaseAll() backstops any that never close.
+        this.browserPool.on("browserLaunched" /* BROWSER_POOL_EVENTS.BROWSER_LAUNCHED */, (controller) => {
+            controller.once("browserClosed" /* BROWSER_CONTROLLER_EVENTS.BROWSER_CLOSED */, () => {
+                const token = controller.launchContext._remoteToken;
+                if (token !== undefined)
+                    void this.registry.release(token);
+            });
+        });
+        if (resolvedMax !== undefined) {
+            this.browserPool.maxOpenBrowsers = resolvedMax;
+        }
+    }
+    /** Maximum number of remote browsers that may be open at the same time. */
+    get maxOpenBrowsers() {
+        return this.browserPool.maxOpenBrowsers;
+    }
+    set maxOpenBrowsers(value) {
+        this.browserPool.maxOpenBrowsers = value;
+    }
+    /**
+     * Opens a new page, waiting first until {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers}
+     * allows it (either a new browser slot is free, or an active browser still has page capacity).
+     */
+    async newPage(options) {
+        await this._waitForFreeSlot();
+        return this.pool.newPage(options);
+    }
+    async closePage(page, options) {
+        return this.pool.closePage(page, options);
+    }
+    async extractPageState(page) {
+        return this.pool.extractPageState(page);
+    }
+    async injectPageState(page, state) {
+        return this.pool.injectPageState(page, state);
+    }
+    /** Closes all browsers, releases any still-open remote sessions, and tears down the wrapped pool. */
+    async destroy() {
+        await this.browserPool.destroy();
+        // Backstop: release any sessions whose browser never emitted a close (e.g. dropped on teardown).
+        await this.registry.releaseAll();
+    }
+    /** Resolves once the wrapped pool can serve another page without exceeding `maxOpenBrowsers`. */
+    async _waitForFreeSlot() {
+        while (!this.browserPool.hasFreeBrowserSlot() && !this.browserPool.hasActiveBrowserWithFreeCapacity()) {
+            await this._nextCapacityChange();
+        }
+    }
+    /**
+     * 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.
+     */
+    _nextCapacityChange() {
+        this._capacityChange ??= new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.browserPool.off("browserRetired" /* BROWSER_POOL_EVENTS.BROWSER_RETIRED */, done);
+                this.browserPool.off("pageClosed" /* BROWSER_POOL_EVENTS.PAGE_CLOSED */, done);
+                this._capacityChange = undefined;
+                resolve();
+            };
+            const timer = setTimeout(done, this.slotPollIntervalMillis);
+            timer.unref?.();
+            this.browserPool.once("browserRetired" /* BROWSER_POOL_EVENTS.BROWSER_RETIRED */, done);
+            this.browserPool.once("pageClosed" /* BROWSER_POOL_EVENTS.PAGE_CLOSED */, done);
+        });
+        return this._capacityChange;
+    }
+}
+//# sourceMappingURL=remote-browser-pool.js.map

package/remote-browser-pool.js.map

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

package/remote-browser-provider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Abstract base class for remote browser service providers.
+ *
+ * Implement this class to encapsulate the lifecycle of a remote browser session
+ * (creation, connection URL resolution, and cleanup). {@link RemoteBrowserPool}
+ * calls {@link connect} once per browser launch and {@link release} when the browser
+ * closes, crashes, the pool is destroyed, or the connection fails during launch.
+ *
+ * Pass the provider instance as the `endpoint` of a {@link RemoteBrowserPool}, then
+ * hand the pool to a crawler via its `browserPool` option:
+ *
+ * ```typescript
+ * const browserPool = new RemoteBrowserPool({
+ *     browserPlugins: [new PlaywrightPlugin(playwright.chromium)],
+ *     endpoint: new MyProvider(),
+ * });
+ *
+ * const crawler = new PlaywrightCrawler({ browserPool });
+ * ```
+ *
+ * **Example — simple static endpoint (e.g. Browserless):**
+ * ```typescript
+ * class BrowserlessProvider extends RemoteBrowserProvider {
+ *     maxOpenBrowsers = 2; // respect the service's concurrent session limit
+ *
+ *     async connect() {
+ *         return { url: `wss://production-sfo.browserless.io?token=${token}` };
+ *     }
+ * }
+ * ```
+ *
+ * **Example — session lifecycle with concurrency limit (e.g. Browserbase):**
+ * ```typescript
+ * class BrowserbaseProvider extends RemoteBrowserProvider<{ id: string }> {
+ *     maxOpenBrowsers = 2; // respect the service's concurrent session limit
+ *
+ *     async connect({ proxyUrl } = {}) {
+ *         const session = await createSession(apiKey, projectId, {
+ *             proxies: proxyUrl ? [{ type: 'external', server: proxyUrl }] : undefined,
+ *         });
+ *         return { url: session.connectUrl, context: { id: session.id } };
+ *     }
+ *
+ *     async release(context: { id: string }) {
+ *         await releaseSession(apiKey, context.id);
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class RemoteBrowserProvider<TContext extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Maximum number of browsers that can be open at the same time.
+     * Set this to your remote service's concurrent session limit to avoid 429 errors.
+     */
+    maxOpenBrowsers?: number;
+    /**
+     * Called once per browser launch. Return the WebSocket/CDP endpoint URL
+     * and an optional `context` object that will be passed back to {@link release}.
+     *
+     * @param options.proxyUrl - The proxy URL resolved by Crawlee's proxy configuration
+     * for this browser session. Pass it to your remote service's proxy API if supported.
+     */
+    abstract connect(options?: {
+        proxyUrl?: string;
+    }): Promise<{
+        url: string;
+        context?: TContext;
+    }> | {
+        url: string;
+        context?: TContext;
+    };
+    /**
+     * Called when the browser closes, crashes, the pool is destroyed, or the
+     * connection fails right after {@link connect} succeeds.
+     * Override this to clean up remote sessions, release API resources, etc.
+     *
+     * Errors thrown here are caught and logged as warnings — they never crash the crawler.
+     * Safe to assume this is called at most once per {@link connect} call.
+     *
+     * @param _context The same `context` object returned by {@link connect}.
+     */
+    release(_context: TContext): Promise<void>;
+}
+//# sourceMappingURL=remote-browser-provider.d.ts.map

package/remote-browser-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-browser-provider.d.ts","sourceRoot":"","sources":["../src/remote-browser-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,8BAAsB,qBAAqB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1G;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,QAAQ,CAAA;KAAE;IAEtF;;;;;;;;;OASG;IACG,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CACnD"}

package/remote-browser-provider.js

@@ -0,0 +1,68 @@
+/**
+ * Abstract base class for remote browser service providers.
+ *
+ * Implement this class to encapsulate the lifecycle of a remote browser session
+ * (creation, connection URL resolution, and cleanup). {@link RemoteBrowserPool}
+ * calls {@link connect} once per browser launch and {@link release} when the browser
+ * closes, crashes, the pool is destroyed, or the connection fails during launch.
+ *
+ * Pass the provider instance as the `endpoint` of a {@link RemoteBrowserPool}, then
+ * hand the pool to a crawler via its `browserPool` option:
+ *
+ * ```typescript
+ * const browserPool = new RemoteBrowserPool({
+ *     browserPlugins: [new PlaywrightPlugin(playwright.chromium)],
+ *     endpoint: new MyProvider(),
+ * });
+ *
+ * const crawler = new PlaywrightCrawler({ browserPool });
+ * ```
+ *
+ * **Example — simple static endpoint (e.g. Browserless):**
+ * ```typescript
+ * class BrowserlessProvider extends RemoteBrowserProvider {
+ *     maxOpenBrowsers = 2; // respect the service's concurrent session limit
+ *
+ *     async connect() {
+ *         return { url: `wss://production-sfo.browserless.io?token=${token}` };
+ *     }
+ * }
+ * ```
+ *
+ * **Example — session lifecycle with concurrency limit (e.g. Browserbase):**
+ * ```typescript
+ * class BrowserbaseProvider extends RemoteBrowserProvider<{ id: string }> {
+ *     maxOpenBrowsers = 2; // respect the service's concurrent session limit
+ *
+ *     async connect({ proxyUrl } = {}) {
+ *         const session = await createSession(apiKey, projectId, {
+ *             proxies: proxyUrl ? [{ type: 'external', server: proxyUrl }] : undefined,
+ *         });
+ *         return { url: session.connectUrl, context: { id: session.id } };
+ *     }
+ *
+ *     async release(context: { id: string }) {
+ *         await releaseSession(apiKey, context.id);
+ *     }
+ * }
+ * ```
+ */
+export class RemoteBrowserProvider {
+    /**
+     * Maximum number of browsers that can be open at the same time.
+     * Set this to your remote service's concurrent session limit to avoid 429 errors.
+     */
+    maxOpenBrowsers;
+    /**
+     * Called when the browser closes, crashes, the pool is destroyed, or the
+     * connection fails right after {@link connect} succeeds.
+     * Override this to clean up remote sessions, release API resources, etc.
+     *
+     * Errors thrown here are caught and logged as warnings — they never crash the crawler.
+     * Safe to assume this is called at most once per {@link connect} call.
+     *
+     * @param _context The same `context` object returned by {@link connect}.
+     */
+    async release(_context) { }
+}
+//# sourceMappingURL=remote-browser-provider.js.map

package/remote-browser-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-browser-provider.js","sourceRoot":"","sources":["../src/remote-browser-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,OAAgB,qBAAqB;IACvC;;;OAGG;IACH,eAAe,CAAU;IAazB;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,CAAC,QAAkB,IAAkB,CAAC;CACtD"}

package/utils.d.ts

@@ -3,6 +3,13 @@ import type { PlaywrightPlugin } from './playwright/playwright-plugin.js';
 import type { PuppeteerPlugin } from './puppeteer/puppeteer-plugin.js';
 export type UnwrapPromise<T> = T extends PromiseLike<infer R> ? UnwrapPromise<R> : T;
 export declare function noop(..._args: unknown[]): void;
+/**
+ * Strips secrets from a URL so it can be safely included in logs and error messages. Removes userinfo
+ * credentials and the entire query string and fragment — remote browser services routinely carry tokens
+ * there (e.g. Browserless `?token=…`), and we can't tell which params are sensitive. Keeps the
+ * protocol, host, port, and path, which are enough to diagnose connection failures.
+ */
+export declare function sanitizeEndpointForLog(endpoint: string): string;
 /**
  * This is required when using optional dependencies.
  * Importing a type gives `any`, but `Parameters<any>` gives `unknown[]` instead of `any`

package/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAErF,wBAAgB,IAAI,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAG;AAElD;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,IAAI,OAAO,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;AAEpH,MAAM,MAAM,uBAAuB,CAE/B,KAAK,SAAS,SAAS,OAAO,EAAE,EAEhC,MAAM,SAAS,aAAa,EAAE,GAAG,EAAE,IACnC,KAAK,SAAS,SAAS,CAAC,MAAM,UAAU,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,UAAU,EAAE,GAAG,MAAM,IAAI,CAAC,GAE1F,UAAU,SAAS,gBAAgB,GAE/B,uBAAuB,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAE5D,UAAU,SAAS,eAAe,GAEhC,uBAAuB,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,eAAe,CAAC,CAAC,GAE3D,KAAK,GAEX,KAAK,SAAS,EAAE,GAEd,MAAM,GAEN,KAAK,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAEhC;IAAC,CAAC;CAAC,SAAS,CAAC,eAAe,GAAG,gBAAgB,CAAC,GAE5C,CAAC,EAAE,GAEH,KAAK,GAET,MAAM,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAErF,wBAAgB,IAAI,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAG;AAElD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW/D;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,IAAI,OAAO,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;AAEpH,MAAM,MAAM,uBAAuB,CAE/B,KAAK,SAAS,SAAS,OAAO,EAAE,EAEhC,MAAM,SAAS,aAAa,EAAE,GAAG,EAAE,IACnC,KAAK,SAAS,SAAS,CAAC,MAAM,UAAU,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,UAAU,EAAE,GAAG,MAAM,IAAI,CAAC,GAE1F,UAAU,SAAS,gBAAgB,GAE/B,uBAAuB,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAE5D,UAAU,SAAS,eAAe,GAEhC,uBAAuB,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,eAAe,CAAC,CAAC,GAE3D,KAAK,GAEX,KAAK,SAAS,EAAE,GAEd,MAAM,GAEN,KAAK,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAEhC;IAAC,CAAC;CAAC,SAAS,CAAC,eAAe,GAAG,gBAAgB,CAAC,GAE5C,CAAC,EAAE,GAEH,KAAK,GAET,MAAM,CAAC"}

package/utils.js

@@ -1,2 +1,21 @@
 export function noop(..._args) { }
+/**
+ * Strips secrets from a URL so it can be safely included in logs and error messages. Removes userinfo
+ * credentials and the entire query string and fragment — remote browser services routinely carry tokens
+ * there (e.g. Browserless `?token=…`), and we can't tell which params are sensitive. Keeps the
+ * protocol, host, port, and path, which are enough to diagnose connection failures.
+ */
+export function sanitizeEndpointForLog(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        url.username = '';
+        url.password = '';
+        url.search = '';
+        url.hash = '';
+        return url.toString();
+    }
+    catch {
+        return '<invalid URL>';
+    }
+}
 //# sourceMappingURL=utils.js.map

package/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,IAAI,CAAC,GAAG,KAAgB,IAAS,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,IAAI,CAAC,GAAG,KAAgB,IAAS,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACnD,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;QAClB,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;QAClB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;QAChB,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;QACd,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,eAAe,CAAC;IAC3B,CAAC;AACL,CAAC"}