@crawlee/utils 4.0.0-beta.15 → 4.0.0-beta.151

package/internals/schemas.js

@@ -0,0 +1,114 @@
+import { BaseHttpClient } from '@crawlee/http-client';
+import { z } from 'zod';
+/**
+ * Accepts any object (including arrays and functions).
+ * @internal
+ */
+export const anyObject = z.custom((value) => (typeof value === 'object' && value !== null) || typeof value === 'function', { message: 'Invalid input: expected object' });
+/**
+ * Accepts any array without validating its items (cheap for huge arrays).
+ * @internal
+ */
+export const anyArray = z.custom(Array.isArray, { message: 'Invalid input: expected array' });
+/**
+ * Accepts any function.
+ * @internal
+ */
+export const anyFunction = z.custom((value) => typeof value === 'function', {
+    message: 'Invalid input: expected function',
+});
+/**
+ * Mirrors `ow.number`: `Infinity` is a valid number, `NaN` is not.
+ * @internal
+ */
+export const anyNumber = z.custom((value) => typeof value === 'number' && !Number.isNaN(value), {
+    message: 'Invalid input: expected number',
+});
+/**
+ * Accepts any object (including functions) that has all the given keys, own or inherited.
+ * @internal
+ */
+export function objectWithKeys(keys, message) {
+    return z.custom((value) => ((typeof value === 'object' && value !== null) || typeof value === 'function') &&
+        keys.every((key) => key in value), {
+        message: message ?? `Invalid input: expected an object with keys ${keys.map((key) => `'${key}'`).join(', ')}`,
+    });
+}
+/**
+ * Accepts only instances of {@link BaseHttpClient} (all Crawlee HTTP clients extend it).
+ * @internal
+ */
+export const httpClient = z.instanceof(BaseHttpClient);
+/**
+ * Accepts any object implementing the CrawleeLogger interface.
+ * @internal
+ */
+export const logger = objectWithKeys(['child', 'info', 'error', 'warning'], "Expected an object implementing the CrawleeLogger interface (missing one of 'child', 'info', 'error', 'warning'), got something else.");
+/**
+ * Accepts any typed array (`Uint8Array`, `Float64Array`, ...), but not a `DataView`.
+ * @internal
+ */
+export const typedArray = z.custom((value) => ArrayBuffer.isView(value) && !(value instanceof DataView), { message: 'Invalid input: expected a typed array' });
+/**
+ * Accepts any non-null, non-array object.
+ * @internal
+ */
+export const plainObject = z.custom((value) => typeof value === 'object' && value !== null && !Array.isArray(value), { message: 'Invalid input: expected an object' });
+/**
+ * Shape of a request stored in a request queue.
+ * @internal
+ */
+export const storageRequest = z.looseObject({
+    id: z.string(),
+    url: z.url({ protocol: /^https?$/ }),
+    uniqueKey: z.string(),
+    method: z.string().optional(),
+    retryCount: z.number().int().optional(),
+    handledAt: z.union([z.string(), z.date()]).optional(),
+});
+/**
+ * {@link storageRequest} before an id is assigned.
+ * @internal
+ */
+export const storageRequestWithoutId = storageRequest.omit({ id: true });
+/**
+ * `z.array(item)` whose top-level type error names the element type — ``expected an array of numbers`` —
+ * instead of zod's bare `expected array`. Element failures keep zod's per-index messages, and `elements`
+ * is a human-readable plural (`'numbers'`, `'URL patterns'`), since element types cannot be introspected.
+ * @internal
+ */
+export function arrayOf(item, elements) {
+    return z.array(item, {
+        error: (issue) => issue.code === 'invalid_type' ? `Invalid input: expected an array of ${elements}` : undefined,
+    });
+}
+/**
+ * Batch of {@link storageRequestWithoutId}.
+ * @internal
+ */
+export const storageRequestBatch = arrayOf(storageRequestWithoutId, 'requests');
+/**
+ * Options of request queue add/update operations.
+ * @internal
+ */
+export const requestQueueOperationOptions = z.object({
+    forefront: z.boolean().optional(),
+});
+/**
+ * Options of key-value store `listKeys`.
+ * @internal
+ */
+export const keyValueStoreListKeysOptions = z.object({
+    prefix: z.string().optional(),
+    exclusiveStartKey: z.string().optional(),
+    limit: z.number().int().gt(0).optional(),
+});
+/**
+ * Options of dataset item listing.
+ * @internal
+ */
+export const datasetListItemsOptions = z.object({
+    desc: z.boolean().optional(),
+    limit: z.number().int().optional(),
+    offset: z.number().int().optional(),
+});

package/internals/sitemap.d.ts

@@ -1,5 +1,6 @@
-// @ts-ignore optional peer dependency or compatibility with es2022
-import type { Delays } from 'got-scraping';
+import type { BaseHttpClient } from '@crawlee/http-client';
+import type { CrawleeLogger } from '@crawlee/types';
+import { type EnqueueStrategy } from './url.js';
 interface SitemapUrlData {
     loc: string;
     lastmod?: Date;
@@ -36,14 +37,36 @@ 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;
+    /**
+     * Keep only sitemap-derived URLs (nested `<sitemap>` and `<url>` entries) matching this strategy
+     * relative to the parent sitemap URL; non-`http(s)` schemes are always dropped. Skipped for raw string
+     * sources (no parent URL). Pass `'all'` to disable host filtering.
+     * @default 'same-hostname'
+     */
+    enqueueStrategy?: EnqueueStrategy | `${EnqueueStrategy}`;
+    /**
+     * 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>;
 /**
@@ -67,7 +90,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)
@@ -79,8 +102,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>;
-    protected static parse(sources: SitemapSource[], proxyUrl?: string, parseSitemapOptions?: ParseSitemapOptions): Promise<Sitemap>;
+    static fromXmlString(content: string, proxyUrl?: string, parseSitemapOptions?: ParseSitemapOptions): Promise<Sitemap>;
+    private static parse;
 }
+/**
+ * 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