@crawlee/utils 4.0.0-beta.8 → 4.0.0-beta.80

package/internals/iterables.js

@@ -0,0 +1,230 @@
+import { inspect } from 'node:util';
+/**
+ * Type guard that checks if a value is iterable (has Symbol.iterator).
+ * @internal
+ *
+ * **Example usage:**
+ * ```ts
+ * if (isIterable(someValue)) {
+ *   for (const item of someValue) {
+ *     console.log(item);
+ *   }
+ * }
+ * ```
+ */
+export function isIterable(value) {
+    if (value == null || typeof value === 'string' || ArrayBuffer.isView(value)) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return true;
+    }
+    return typeof Object(value)[Symbol.iterator] === 'function';
+}
+/**
+ * Type guard that checks if a value is async iterable (has Symbol.asyncIterator).
+ * @internal
+ *
+ * **Example usage:**
+ * ```ts
+ * if (isAsyncIterable(someValue)) {
+ *   for await (const item of someValue) {
+ *     console.log(item);
+ *   }
+ * }
+ * ```
+ */
+export function isAsyncIterable(value) {
+    if (value == null || typeof value === 'string' || ArrayBuffer.isView(value)) {
+        return false;
+    }
+    return typeof Object(value)[Symbol.asyncIterator] === 'function';
+}
+/**
+ * Converts any iterable or async iterable to an async iterable.
+ * @internal
+ *
+ * @yields Each item from the input iterable
+ *
+ * **Example usage:**
+ * ```ts
+ * const syncArray = [1, 2, 3];
+ * for await (const item of asyncifyIterable(syncArray)) {
+ *   console.log(item); // 1, 2, 3
+ * }
+ * ```
+ */
+export async function* asyncifyIterable(iterable) {
+    yield* iterable;
+}
+/**
+ * Lazily splits the input async iterable into chunks of specified size.
+ * The last chunk may contain fewer items if the total number of items
+ * is not evenly divisible by the chunk size.
+ * @internal
+ *
+ * @yields Arrays of items, each containing up to chunkSize items
+ *
+ * **Example usage:**
+ * ```ts
+ * const numbers = async function* () {
+ *   for (let i = 1; i <= 10; i++) yield i;
+ * };
+ *
+ * for await (const chunk of chunkedAsyncIterable(numbers(), 3)) {
+ *   console.log(chunk); // [1, 2, 3], [4, 5, 6], [7, 8, 9], [10]
+ * }
+ * ```
+ */
+export async function* chunkedAsyncIterable(iterable, chunkSize) {
+    const getChunkSize = typeof chunkSize === 'function' ? chunkSize : () => chunkSize;
+    if (typeof chunkSize === 'number' && chunkSize < 1) {
+        throw new Error(`Chunk size must be a positive number (${inspect(chunkSize)}) received`);
+    }
+    const iterator = Symbol.asyncIterator in iterable
+        ? iterable[Symbol.asyncIterator]()
+        : iterable[Symbol.iterator]();
+    while (true) {
+        const currentSize = getChunkSize();
+        if (currentSize < 1)
+            break;
+        const chunk = [];
+        for (let i = 0; i < currentSize; i++) {
+            const next = await iterator.next();
+            if (next.done) {
+                break;
+            }
+            chunk.push(next.value);
+        }
+        if (chunk.length === 0)
+            break;
+        yield chunk;
+    }
+}
+/**
+ * Wraps an async iterable to provide peek functionality, allowing you to look at
+ * the next value without consuming it from the iterator.
+ * @internal
+ *
+ * @param iterable - The async iterable to make peekable
+ *
+ * **Example usage:**
+ * ```ts
+ * const numbers = async function* () {
+ *   yield 1; yield 2; yield 3;
+ * };
+ *
+ * const peekable = peekableAsyncIterable(numbers());
+ * const iterator = peekable[Symbol.asyncIterator]();
+ *
+ * console.log(await iterator.peek()); // 1 (doesn't consume)
+ * console.log(await iterator.peek()); // 1 (still doesn't consume)
+ * console.log(await iterator.next()); // { value: 1, done: false } (now consumed)
+ * console.log(await iterator.peek()); // 2 (next value)
+ * ```
+ */
+export function peekableAsyncIterable(iterable) {
+    const iterator = asyncifyIterable(iterable)[Symbol.asyncIterator]();
+    let peekedValue;
+    let isExhausted = false;
+    const peekableIterator = {
+        async next() {
+            // If we have peeked a value, return it and clear the peek
+            if (peekedValue !== undefined) {
+                const result = peekedValue;
+                peekedValue = undefined;
+                if (result.done) {
+                    isExhausted = true;
+                    return { done: true, value: undefined };
+                }
+                return { done: false, value: result.value };
+            }
+            if (isExhausted) {
+                return { done: true, value: undefined };
+            }
+            const result = await iterator.next();
+            if (result.done) {
+                isExhausted = true;
+            }
+            return result;
+        },
+        async peek() {
+            if (peekedValue !== undefined) {
+                return peekedValue.done ? undefined : peekedValue.value;
+            }
+            if (isExhausted) {
+                return undefined;
+            }
+            const result = await iterator.next();
+            peekedValue = { done: result.done ?? false, value: result.value };
+            if (result.done) {
+                isExhausted = true;
+                return undefined;
+            }
+            return result.value;
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+    return {
+        [Symbol.asyncIterator]() {
+            return peekableIterator;
+        },
+    };
+}
+// Source - https://stackoverflow.com/a/71288323
+/**
+ * Merges multiple async iterables into a single async iterable, yielding values concurrently.
+ *
+ * **Example usage:**
+ * ```ts
+ * const asyncIterable1 = async function* () {
+ *   yield 1; yield 3; yield 5;
+ * };
+ *
+ * const asyncIterable2 = async function* () {
+ *   yield 2; yield 4; yield 6;
+ * };
+ *
+ * for await (const value of mergeAsyncIterables(asyncIterable1(), asyncIterable2())) {
+ *   console.log(value);
+ * }
+ * ```
+ */
+export async function* mergeAsyncIterables(...iterables) {
+    const asyncIterators = iterables.map((iterable) => iterable[Symbol.asyncIterator]());
+    const results = [];
+    let count = asyncIterators.length;
+    const never = new Promise(() => { });
+    async function getNext(asyncIterator, index) {
+        const result = await asyncIterator.next();
+        return {
+            index,
+            result,
+        };
+    }
+    const nextPromises = asyncIterators.map(getNext);
+    try {
+        while (count) {
+            const { index, result } = await Promise.race(nextPromises);
+            if (result.done) {
+                nextPromises[index] = never;
+                results[index] = result.value;
+                count--;
+            }
+            else {
+                nextPromises[index] = getNext(asyncIterators[index], index);
+                yield result.value;
+            }
+        }
+    }
+    finally {
+        for (const [index, iterator] of asyncIterators.entries()) {
+            // no await here - see https://github.com/tc39/proposal-async-iteration/issues/126
+            if (nextPromises[index] !== never && iterator.return != null)
+                void iterator.return();
+        }
+    }
+    return results;
+}

package/internals/open_graph_parser.d.ts

@@ -14,7 +14,6 @@ type OpenGraphResult = string | string[] | Dictionary<string | Dictionary>;
  * Currently existing properties are kept up to date.
  * @returns Scraped OpenGraph properties as an object.
  */
-export declare function parseOpenGraph(raw: string, additionalProperties?: OpenGraphProperty[]): Dictionary<OpenGraphResult>;
-export declare function parseOpenGraph($: CheerioAPI, additionalProperties?: OpenGraphProperty[]): Dictionary<OpenGraphResult>;
+export declare function parseOpenGraph(raw: string, additionalProperties?: OpenGraphProperty[]): Promise<Dictionary<OpenGraphResult>>;
+export declare function parseOpenGraph($: CheerioAPI, additionalProperties?: OpenGraphProperty[]): Promise<Dictionary<OpenGraphResult>>;
 export {};
-//# sourceMappingURL=open_graph_parser.d.ts.map

package/internals/open_graph_parser.js

@@ -1,4 +1,3 @@
-import { load } from 'cheerio';
 /**
  * To be used with the spread operator. Ensures that the item is defined, and is not empty.
  *
@@ -255,32 +254,32 @@ const OPEN_GRAPH_PROPERTIES = [
         outputName: 'articleInfo',
         children: [
             {
-                name: 'music:published_time',
+                name: 'article:published_time',
                 outputName: 'publishedTime',
                 children: [],
             },
             {
-                name: 'music:modified_time',
+                name: 'article:modified_time',
                 outputName: 'modifiedTime',
                 children: [],
             },
             {
-                name: 'music:expiration_time',
+                name: 'article:expiration_time',
                 outputName: 'expirationTime',
                 children: [],
             },
             {
-                name: 'music:author',
+                name: 'article:author',
                 outputName: 'author',
                 children: [],
             },
             {
-                name: 'music:section',
+                name: 'article:section',
                 outputName: 'section',
                 children: [],
             },
             {
-                name: 'music:tag',
+                name: 'article:tag',
                 outputName: 'tag',
                 children: [],
             },
@@ -366,7 +365,8 @@ const parseOpenGraphProperty = (property, $) => {
         }, {}),
     };
 };
-export function parseOpenGraph(item, additionalProperties) {
+export async function parseOpenGraph(item, additionalProperties) {
+    const { load } = await import('cheerio');
     const $ = typeof item === 'string' ? load(item) : item;
     return [...(additionalProperties || []), ...OPEN_GRAPH_PROPERTIES].reduce((acc, curr) => {
         return {
@@ -375,4 +375,3 @@ export function parseOpenGraph(item, additionalProperties) {
         };
     }, {});
 }
-//# sourceMappingURL=open_graph_parser.js.map

package/internals/robots.d.ts

@@ -1,3 +1,4 @@
+import type { BaseHttpClient, CrawleeLogger } from '@crawlee/types';
 import { Sitemap } from './sitemap.js';
 /**
  * Loads and queries information from a [robots.txt file](https://en.wikipedia.org/wiki/Robots.txt).
@@ -20,13 +21,23 @@ import { Sitemap } from './sitemap.js';
 export declare class RobotsTxtFile {
     private robots;
     private proxyUrl?;
+    private logger?;
     private constructor();
     /**
      * Determine the location of a robots.txt file for a URL and fetch it.
      * @param url the URL to fetch robots.txt for
-     * @param [proxyUrl] a proxy to be used for fetching the robots.txt file
+     * @param [options] additional options
+     * @param [options.signal] an AbortSignal to cancel the request
+     * @param [options.timeoutMillis] timeout in milliseconds for the request
+     * @param [options.proxyUrl] a proxy to be used for fetching the robots.txt file
      */
-    static find(url: string, proxyUrl?: string): Promise<RobotsTxtFile>;
+    static find(url: string, options?: {
+        signal?: AbortSignal;
+        timeoutMillis?: number;
+        proxyUrl?: string;
+        httpClient?: BaseHttpClient;
+        logger?: CrawleeLogger;
+    }): Promise<RobotsTxtFile>;
     /**
      * Allows providing the URL and robots.txt content explicitly instead of loading it from the target site.
      * @param url the URL for robots.txt file
@@ -34,7 +45,13 @@ export declare class RobotsTxtFile {
      * @param [proxyUrl] a proxy to be used for fetching the robots.txt file
      */
     static from(url: string, content: string, proxyUrl?: string): RobotsTxtFile;
-    protected static load(url: string, proxyUrl?: string): Promise<RobotsTxtFile>;
+    protected static load(url: string, options?: {
+        signal?: AbortSignal;
+        timeoutMillis?: number;
+        proxyUrl?: string;
+        httpClient?: BaseHttpClient;
+        logger?: CrawleeLogger;
+    }): Promise<RobotsTxtFile>;
     /**
      * Check if a URL should be crawled by robots.
      * @param url the URL to check against the rules in robots.txt
@@ -55,4 +72,3 @@ export declare class RobotsTxtFile {
     parseUrlsFromSitemaps(): Promise<string[]>;
 }
 export { RobotsTxtFile as RobotsFile };
-//# sourceMappingURL=robots.d.ts.map

package/internals/robots.js

@@ -1,7 +1,6 @@
-import { gotScraping } from 'got-scraping';
+import { FetchHttpClient } from '@crawlee/http-client';
 import robotsParser from 'robots-parser';
 import { Sitemap } from './sitemap.js';
-let HTTPError;
 /**
  * Loads and queries information from a [robots.txt file](https://en.wikipedia.org/wiki/Robots.txt).
  *
@@ -23,20 +22,25 @@ let HTTPError;
 export class RobotsTxtFile {
     robots;
     proxyUrl;
-    constructor(robots, proxyUrl) {
+    logger;
+    constructor(robots, proxyUrl, logger) {
         this.robots = robots;
         this.proxyUrl = proxyUrl;
+        this.logger = logger;
     }
     /**
      * Determine the location of a robots.txt file for a URL and fetch it.
      * @param url the URL to fetch robots.txt for
-     * @param [proxyUrl] a proxy to be used for fetching the robots.txt file
+     * @param [options] additional options
+     * @param [options.signal] an AbortSignal to cancel the request
+     * @param [options.timeoutMillis] timeout in milliseconds for the request
+     * @param [options.proxyUrl] a proxy to be used for fetching the robots.txt file
      */
-    static async find(url, proxyUrl) {
+    static async find(url, options) {
         const robotsTxtFileUrl = new URL(url);
         robotsTxtFileUrl.pathname = '/robots.txt';
         robotsTxtFileUrl.search = '';
-        return RobotsTxtFile.load(robotsTxtFileUrl.toString(), proxyUrl);
+        return RobotsTxtFile.load(robotsTxtFileUrl.toString(), options);
     }
     /**
      * Allows providing the URL and robots.txt content explicitly instead of loading it from the target site.
@@ -48,33 +52,28 @@ export class RobotsTxtFile {
         // @ts-ignore
         return new RobotsTxtFile(robotsParser(url, content), proxyUrl);
     }
-    static async load(url, proxyUrl) {
-        if (!HTTPError) {
-            HTTPError = (await import('got-scraping')).HTTPError;
-        }
-        try {
-            const response = await gotScraping({
-                url,
-                proxyUrl,
-                method: 'GET',
-                responseType: 'text',
-            });
-            // @ts-ignore
-            return new RobotsTxtFile(robotsParser(url.toString(), response.body), proxyUrl);
+    static async load(url, options) {
+        const { proxyUrl, logger, httpClient = new FetchHttpClient() } = options || {};
+        const response = await httpClient.sendRequest(new Request(url, { method: 'GET' }), {
+            proxyUrl,
+            timeoutMillis: options?.timeoutMillis,
+            signal: options?.signal,
+        });
+        if (response.status < 200 || response.status >= 300) {
+            throw new Error(`Failed to load robots.txt from ${url}: HTTP ${response.status}`);
         }
-        catch (e) {
-            if (e instanceof HTTPError && e.response.statusCode === 404) {
-                return new RobotsTxtFile({
-                    isAllowed() {
-                        return true;
-                    },
-                    getSitemaps() {
-                        return [];
-                    },
-                }, proxyUrl);
-            }
-            throw e;
+        if (response.status === 404) {
+            return new RobotsTxtFile({
+                isAllowed() {
+                    return true;
+                },
+                getSitemaps() {
+                    return [];
+                },
+            }, proxyUrl, logger);
         }
+        // @ts-ignore
+        return new RobotsTxtFile(robotsParser(url.toString(), await response.text()), proxyUrl, logger);
     }
     /**
      * Check if a URL should be crawled by robots.
@@ -94,7 +93,7 @@ export class RobotsTxtFile {
      * Parse all the sitemaps referenced in the robots file.
      */
     async parseSitemaps() {
-        return Sitemap.load(this.robots.getSitemaps(), this.proxyUrl);
+        return Sitemap.load(this.robots.getSitemaps(), this.proxyUrl, { logger: this.logger });
     }
     /**
      * Get all URLs from all the sitemaps referenced in the robots file. A shorthand for `(await robots.parseSitemaps()).urls`.
@@ -105,4 +104,3 @@ export class RobotsTxtFile {
 }
 // to stay backwards compatible
 export { RobotsTxtFile as RobotsFile };
-//# sourceMappingURL=robots.js.map

package/internals/sitemap.d.ts

@@ -1,5 +1,4 @@
-// @ts-ignore optional peer dependency or compatibility with es2022
-import type { Delays } from 'got-scraping';
+import type { BaseHttpClient, CrawleeLogger } from '@crawlee/types';
 interface SitemapUrlData {
     loc: string;
     lastmod?: Date;
@@ -36,9 +35,29 @@ export interface ParseSitemapOptions {
      */
     sitemapRetries?: number;
     /**
-     * Network timeouts for sitemap fetching. See [Got documentation](https://github.com/sindresorhus/got/blob/main/documentation/6-timeout.md) for more details.
+     * Timeout settings for network requests when fetching sitemaps. By default this is `30000` milliseconds (30 seconds).
      */
-    networkTimeouts?: Delays;
+    timeoutMillis?: number;
+    /**
+     * If true, the parser will log a warning if it fails to fetch a sitemap due to a network error
+     * @default true
+     */
+    reportNetworkErrors?: boolean;
+    /**
+     * Custom HTTP client to be used for fetching sitemaps.
+     */
+    httpClient?: BaseHttpClient;
+    /**
+     * Optional filter for nested sitemap URLs discovered in sitemap index files.
+     * Called with the URL of each child sitemap before it is fetched.
+     * Return `true` to include the sitemap, `false` to skip it.
+     * If not provided, all nested sitemaps are followed.
+     */
+    nestedSitemapFilter?: (sitemapUrl: string) => boolean;
+    /**
+     * Optional logger for reporting warnings during sitemap parsing.
+     */
+    logger?: CrawleeLogger;
 }
 export declare function parseSitemap<T extends ParseSitemapOptions>(initialSources: SitemapSource[], proxyUrl?: string, options?: T): AsyncIterable<T['emitNestedSitemaps'] extends true ? SitemapUrl | NestedSitemap : SitemapUrl>;
 /**
@@ -62,7 +81,7 @@ export declare class Sitemap {
      * @param url The domain URL to fetch the sitemap for.
      * @param proxyUrl A proxy to be used for fetching the sitemap file.
      */
-    static tryCommonNames(url: string, proxyUrl?: string): Promise<Sitemap>;
+    static tryCommonNames(url: string, proxyUrl?: string, parseSitemapOptions?: ParseSitemapOptions): Promise<Sitemap>;
     /**
      * Fetch sitemap content from given URL or URLs and return URLs of referenced pages.
      * @param urls sitemap URL(s)
@@ -74,8 +93,46 @@ export declare class Sitemap {
      * @param content XML sitemap content
      * @param proxyUrl URL of a proxy to be used for fetching sitemap contents
      */
-    static fromXmlString(content: string, proxyUrl?: string): Promise<Sitemap>;
+    static fromXmlString(content: string, proxyUrl?: string, parseSitemapOptions?: ParseSitemapOptions): Promise<Sitemap>;
     protected static parse(sources: SitemapSource[], proxyUrl?: string, parseSitemapOptions?: ParseSitemapOptions): Promise<Sitemap>;
 }
+/**
+ * Given a list of URLs, discover related sitemap files for these domains by checking the `robots.txt` file,
+ * the default `sitemap.xml` & `sitemap.txt` files and the URLs themselves.
+ * @param `urls` The list of URLs to discover sitemaps for.
+ * @param `options` Options for sitemap discovery
+ * @returns An async iterable with the discovered sitemap URLs.
+ */
+export declare function discoverValidSitemaps(urls: string[], options?: {
+    /**
+     * Proxy URL to be used for network requests.
+     */
+    proxyUrl?: string;
+    /**
+     * Timeout in milliseconds for the entire `discoverValidSitemaps` call.
+     * An `AbortController` is created internally and its signal is passed to every HTTP request,
+     * so the whole discovery operation is cancelled once the timeout elapses.
+     * Defaults to `60_000` ms (60 seconds) to prevent indefinite hangs.
+     */
+    timeoutMillis?: number;
+    /**
+     * An external `AbortSignal` to cancel the entire discovery operation.
+     * If both `signal` and `timeout` are provided, the operation is cancelled
+     * when either the signal is aborted or the timeout elapses (whichever comes first).
+     */
+    signal?: AbortSignal;
+    /**
+     * Timeout in milliseconds for each individual HTTP request during discovery.
+     * Defaults to `20000` ms (20 seconds).
+     */
+    requestTimeoutMillis?: number;
+    /**
+     * HTTP client to be used for network requests.
+     */
+    httpClient?: BaseHttpClient;
+    /**
+     * Optional logger for reporting warnings during sitemap discovery.
+     */
+    logger?: CrawleeLogger;
+}): AsyncIterable<string>;
 export {};
-//# sourceMappingURL=sitemap.d.ts.map