@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/crawler.d.mts

@@ -0,0 +1,330 @@
+import { XPuppeteerGetPageHtmlOptions } from "./puppeteer.mjs";
+import { EventBus } from "vtils";
+import { HTMLElement } from "node-html-parser";
+import { VaeObjectSchemaShapeOf, v } from "vtils/vae";
+import { AsyncOrSync, OneOrMore } from "vtils/types";
+export type XCrawlerData = Record<any, any>;
+export type XCrawlerDataFieldSelectSelector = string;
+export type XCrawlerDataFieldSelectFilter = [string, string | RegExp | ((el: HTMLElement) => boolean)];
+export type XCrawlerDataFieldSelectFunction = (el: HTMLElement) => AsyncOrSync<string | HTMLElement | undefined>;
+export type XCrawlerDataFieldSelect = XCrawlerDataFieldSelectSelector | XCrawlerDataFieldSelectFilter | XCrawlerDataFieldSelectFunction;
+export type XCrawlerDataFieldExtractExtract = 'getPlainText' | 'getHTML' | 'getFirstImageUrl' | 'getFirstLinkUrl';
+export type XCrawlerDataFieldExtract<V> = {
+  /**
+   * 选择元素
+   *
+   * - 可以是一个选择器字符串；
+   * - 可以是一个筛选器数组，[选择器, 筛选条件]；
+   * - 也可以是一个返回元素的函数；
+   * - 也可以是一个返回文本的函数，若此，将跳过 ocr 和 action。
+   */
+  select?: XCrawlerDataFieldSelect;
+  /**
+   * 识别选中内容中的图片为文本并替换
+   */
+  ocr?: (imgUrl: string) => AsyncOrSync<string>;
+  /**
+   * 对选中元素导出结果文本
+   *
+   * @default 'getPlainText'
+   */
+  extract?: XCrawlerDataFieldExtractExtract;
+  /**
+   * 若有需要，可对结果文本进行转换
+   *
+   * @param text 结果文本
+   */
+  transform?: (text: string) => AsyncOrSync<V>;
+};
+export type XCrawlerDataExtract<T extends XCrawlerData> = { [K in keyof T]?: XCrawlerDataFieldSelect | XCrawlerDataFieldExtract<T[K]>; };
+export type XCrawlerEngine = 'headless' | 'headful' | 'request';
+export type XCrawlerContentType = 'html' | 'json';
+/**
+ * `XCrawlerNext.element` 选择函数回调的附加信息。
+ */
+export interface XCrawlerElementExtra {
+  /**
+   * 当前元素在结果列表中的索引（从 0 开始）
+   */
+  index: number;
+  /**
+   * 当前页面的根元素
+   */
+  root: HTMLElement;
+}
+/**
+ * `XCrawlerNext.url` 提取函数的入参。
+ */
+export interface XCrawlerUrlPayload<T extends XCrawlerData> {
+  /**
+   * 当前已收集的数据
+   */
+  data: T;
+  /**
+   * 当前页面元素
+   */
+  el: HTMLElement;
+}
+/**
+ * `XCrawlerNext.nextPageUrl` 分页函数的入参。
+ */
+export interface XCrawlerNextPageUrlPayload<T extends XCrawlerData> {
+  /**
+   * 当前已收集的数据
+   */
+  data: T;
+  /**
+   * 当前页面元素
+   */
+  el: HTMLElement;
+  /**
+   * 当前页面网址
+   */
+  url: string;
+}
+export type XCrawlerNext<T extends XCrawlerData> = {
+  /**
+   * ID，可给其他 next 跳转以实现逻辑复用
+   */
+  id?: string;
+  /**
+   * 过滤
+   */
+  filter?: (data: T) => AsyncOrSync<boolean>;
+  /**
+   * 内容类型
+   */
+  contentType?: XCrawlerContentType;
+  /**
+   * 通过元素
+   */
+  element?: string | ((el: HTMLElement, extra: XCrawlerElementExtra) => AsyncOrSync<OneOrMore<HTMLElement>>);
+  /**
+   * 通过字段(json)
+   */
+  field?: string | ((json: any) => AsyncOrSync<any>);
+  /**
+   * 通过网址
+   */
+  url?: keyof T | ((payload: XCrawlerUrlPayload<T>) => AsyncOrSync<OneOrMore<string>>);
+  /**
+   * 下一页网址（有分页时用）
+   *
+   * 返回空字符串或跟当前页面网址相同的网址时将跳过
+   */
+  nextPageUrl?: (payload: XCrawlerNextPageUrlPayload<T>) => AsyncOrSync<string | undefined>;
+  /** @inner */
+  _url?: string[];
+  /**
+   * 抓取引擎
+   */
+  engine?: XCrawlerEngine;
+  engineOptions?: XPuppeteerGetPageHtmlOptions;
+  /**
+   * 数据提取
+   */
+  extract?: XCrawlerDataExtract<T>;
+  /**
+   * 下一步
+   */
+  next?: OneOrMore<string | XCrawlerNext<T>>;
+};
+export type XCrawlerConfig<T extends XCrawlerData> = {
+  /**
+   * 入口页链接
+   */
+  entry: string;
+  /**
+   * 使用代理
+   */
+  proxy?: string;
+  /**
+   * 内容类型
+   */
+  contentType?: XCrawlerContentType;
+  /**
+   * 抓取引擎
+   */
+  engine?: XCrawlerEngine;
+  engineOptions?: XPuppeteerGetPageHtmlOptions;
+  /**
+   * 数据格式
+   */
+  schema: (_: typeof v) => VaeObjectSchemaShapeOf<T>;
+  /**
+   * 数据提取
+   */
+  extract?: XCrawlerDataExtract<T>;
+  /**
+   * 下一步
+   */
+  next?: OneOrMore<XCrawlerNext<T>>;
+  /**
+   * 数据监听
+   */
+  listen?: (data: T) => any;
+};
+/**
+ * `XCrawler.next` 递归调用的参数列表。
+ *
+ * 提取为独立类型，便于在构建下一级参数与递归调用之间复用，
+ * 避免直接使用 `Parameters<XCrawler<T>['next']>` 这类不稳定写法。
+ */
+export type XCrawlerNextParams<T extends XCrawlerData> = [
+/**
+ * 当前页面网址
+ */
+pageUrl: string,
+/**
+ * 内容类型（html / json）
+ */
+contentType: XCrawlerContentType,
+/**
+ * 抓取引擎（headless / headful / request）
+ */
+engine: XCrawlerEngine,
+/**
+ * 当前处理对象：
+ * - html 时为页面元素（`HTMLElement`）；
+ * - json 时为字段值（任意）。
+ */
+elOrField: any,
+/**
+ * 当前已收集的数据（可能尚未完整）
+ */
+data: Partial<T>,
+/**
+ * 当前步骤的下一步配置
+ */
+next: XCrawlerNext<T>,
+/**
+ * 当前元素在结果列表中的索引
+ */
+index: number,
+/**
+ * 入口页面的根元素（html 时有效）
+ */
+rootElement: HTMLElement];
+/**
+ * 网页/接口抓取器。
+ *
+ * 工作流程：
+ * 1. `start()` 按 `contentType` 抓取 `entry` 入口：
+ *    - `html`：解析为 DOM 元素（`HTMLElement`）；
+ *    - `json`：解析为 JSON 值；
+ * 2. 依据 `config.next` 逐级深入：
+ *    - `html`：通过 `element`（选择器/函数）在当前元素下选取一批子元素，
+ *      或通过 `url` 跳转到新页面并抓取；
+ *    - `json`：通过 `field`（字段路径）或 `url` 选取一批字段值；
+ * 3. 对每个选中的元素/字段执行 `extract`，把结果写入数据对象；
+ * 4. 若仍有 `next`，继续递归处理；否则通过 `newData` 事件（即 `listen`
+ *    回调）逐条产出最终数据。
+ *
+ * 数据流说明：
+ * - 每一级递归都会 `cloneDeepFast` 复制上一级数据，避免相互污染；
+ * - 同名字段在数组 schema 下会按出现顺序累加，用于收集列表；
+ * - 抓取过程中相对网址都会基于当前页网址归一化为绝对网址。
+ */
+export declare class XCrawler<T extends XCrawlerData> extends EventBus<{
+  newData: (data: T) => any;
+}> {
+  private config;
+  /** 解析后的数据 schema 映射（字段名 → schema），用于对提取结果做 cast 校验。 */
+  private schemaMap;
+  /** 实例 ID，用于 headless/headful 引擎复用浏览器实例。 */
+  private id;
+  /**
+   * 创建抓取器。
+   *
+   * @param config 抓取配置，含入口、schema、提取规则与监听回调
+   */
+  constructor(config: XCrawlerConfig<T>);
+  /**
+   * 将相对/绝对网址归一化为绝对网址。
+   *
+   * 规则：
+   * - 去除首尾空白后为空时，返回空字符串；
+   * - 已是绝对网址（`isUrl`）时原样返回；
+   * - 相对路径以当前页网址为基准拼接：
+   *   - 以 `.` 或 `/` 开头则直接拼接；
+   *   - 否则补前导 `/` 再拼接（视为站点根相对路径）。
+   */
+  private normalizeUrl;
+  /**
+   * 使用无头浏览器抓取页面 HTML。
+   *
+   * 统一传入了 `proxy`、`blockAssets`、`instanceId` 等公共配置，
+   * 调用方传入的 `options` 会覆盖这些默认值。
+   */
+  private fetchUrlHeadless;
+  /**
+   * 使用有头浏览器抓取页面 HTML。
+   *
+   * 与 `fetchUrlHeadless` 仅 `headful` 取值不同，其余行为一致。
+   */
+  private fetchUrlHeadful;
+  /**
+   * 使用普通 HTTP 请求抓取页面文本。
+   *
+   * 适用场景：目标页面不需要执行 JS、无浏览器指纹校验等。
+   */
+  private fetchUrlRequest;
+  /**
+   * 按引擎抓取页面文本。
+   *
+   * 兜底说明：未知引擎会走 `request` 分支（三元表达式最后一项），
+   * 因此调用方传入非法引擎值不会抛错，而是按 request 处理。
+   */
+  private fetchUrl;
+  /**
+   * 抓取页面并解析为 DOM 元素（html 内容类型）。
+   */
+  private fetchUrlAsHTMLElement;
+  /**
+   * 抓取页面并解析为 JSON 值（json 内容类型）。
+   */
+  private fetchUrlAsJSON;
+  /**
+   * 将元素内所有图片识别为文本并替换到原位置。
+   *
+   * 仅处理带 `src` 的 `img`，识别结果通过 `escape` 转义后写入占位 `div`，
+   * 供后续 `getPlainText` 提取时包含 OCR 文本。
+   */
+  private ocr;
+  /**
+   * 按 ID 在 `next` 树中查找可复用的下一步配置。
+   *
+   * 结果被 `memoize` 缓存，同一 ID 只做一次深度遍历。
+   */
+  private findNextById;
+  /**
+   * 已访问网址缓存，用于去重，避免重复抓取同一页面。
+   */
+  private pageUrlCache;
+  /**
+   * 递归抓取核心方法。
+   *
+   * 主要分支：
+   * - `json` 内容类型：通过 `field` / `url` 取得下一级字段值，再执行
+   *   `extract`（字符串 select 用 `get` 取路径，其余形式暂未实现，留 TODO）；
+   * - `html` 内容类型：通过 `element` / `url` 取得下一级元素集合，再执行
+   *   `extract`（支持 `select` 选择器/筛选器/函数，`extract` 导出方式，
+   *   `ocr` 图片识别与 `transform` 转换）。
+   *
+   * 出口：
+   * - 无 `next.next` 时，当前 `newData` 即为一条最终数据，通过 `newData`
+   *   事件（`listen` 回调）对外抛出；
+   * - 有 `next.next` 时，逐个构建下一级参数并递归调用，随后处理
+   *   `nextPageUrl` 分页。
+   */
+  next(pageUrl: string, contentType: XCrawlerContentType, engine: XCrawlerEngine, elOrField: any, data: Partial<T>, next: XCrawlerNext<T>, index: number, rootElement: HTMLElement): Promise<void>;
+  /**
+   * 启动抓取。
+   *
+   * - 默认 `contentType` 为 `'html'`、`engine` 为 `'request'`；
+   * - 抓取入口后开始逐级处理 `config.extract` 与 `config.next`；
+   * - 最终数据通过 `newData` 事件（`listen` 回调）逐条抛出，
+   *   本方法自身不返回数据，仅用于驱动整个抓取流程完成。
+   */
+  start(): Promise<void>;
+}

package/lib/crawler.mjs

@@ -0,0 +1,313 @@
+import { XPuppeteer } from "./puppeteer.mjs";
+import { xr } from "@jayfong/x-request";
+import { EventBus, castArray, cloneDeepFast, escape, get, isRegExp, isUrl, keysStrict, memoize, omitStrict } from "vtils";
+import { parse } from "node-html-parser";
+import { v } from "vtils/vae";
+// src/crawler.ts
+/**
+* 网页/接口抓取器。
+*
+* 工作流程：
+* 1. `start()` 按 `contentType` 抓取 `entry` 入口：
+*    - `html`：解析为 DOM 元素（`HTMLElement`）；
+*    - `json`：解析为 JSON 值；
+* 2. 依据 `config.next` 逐级深入：
+*    - `html`：通过 `element`（选择器/函数）在当前元素下选取一批子元素，
+*      或通过 `url` 跳转到新页面并抓取；
+*    - `json`：通过 `field`（字段路径）或 `url` 选取一批字段值；
+* 3. 对每个选中的元素/字段执行 `extract`，把结果写入数据对象；
+* 4. 若仍有 `next`，继续递归处理；否则通过 `newData` 事件（即 `listen`
+*    回调）逐条产出最终数据。
+*
+* 数据流说明：
+* - 每一级递归都会 `cloneDeepFast` 复制上一级数据，避免相互污染；
+* - 同名字段在数组 schema 下会按出现顺序累加，用于收集列表；
+* - 抓取过程中相对网址都会基于当前页网址归一化为绝对网址。
+*/
+var XCrawler = class extends EventBus {
+	config;
+	/** 解析后的数据 schema 映射（字段名 → schema），用于对提取结果做 cast 校验。 */
+	schemaMap;
+	/** 实例 ID，用于 headless/headful 引擎复用浏览器实例。 */
+	id = Date.now().toString(36);
+	/**
+	* 创建抓取器。
+	*
+	* @param config 抓取配置，含入口、schema、提取规则与监听回调
+	*/
+	constructor(config) {
+		super();
+		this.config = config;
+		this.schemaMap = config.schema(v);
+		if (config.listen) this.on("newData", (newData) => {
+			config.listen(newData);
+		});
+	}
+	/**
+	* 将相对/绝对网址归一化为绝对网址。
+	*
+	* 规则：
+	* - 去除首尾空白后为空时，返回空字符串；
+	* - 已是绝对网址（`isUrl`）时原样返回；
+	* - 相对路径以当前页网址为基准拼接：
+	*   - 以 `.` 或 `/` 开头则直接拼接；
+	*   - 否则补前导 `/` 再拼接（视为站点根相对路径）。
+	*/
+	normalizeUrl(pageUrl, url) {
+		url = url.trim();
+		return !url ? "" : isUrl(url) ? url : new URL(url.startsWith(".") || url.startsWith("/") ? url : `/${url}`, pageUrl).toString();
+	}
+	/**
+	* 使用无头浏览器抓取页面 HTML。
+	*
+	* 统一传入了 `proxy`、`blockAssets`、`instanceId` 等公共配置，
+	* 调用方传入的 `options` 会覆盖这些默认值。
+	*/
+	async fetchUrlHeadless(pageUrl, url, options) {
+		return await XPuppeteer.getPageHtml(this.normalizeUrl(pageUrl, url), {
+			headful: false,
+			proxy: this.config.proxy,
+			blockAssets: true,
+			instanceId: this.id,
+			...options
+		});
+	}
+	/**
+	* 使用有头浏览器抓取页面 HTML。
+	*
+	* 与 `fetchUrlHeadless` 仅 `headful` 取值不同，其余行为一致。
+	*/
+	async fetchUrlHeadful(pageUrl, url, options) {
+		return await XPuppeteer.getPageHtml(this.normalizeUrl(pageUrl, url), {
+			headful: true,
+			proxy: this.config.proxy,
+			blockAssets: true,
+			instanceId: this.id,
+			...options
+		});
+	}
+	/**
+	* 使用普通 HTTP 请求抓取页面文本。
+	*
+	* 适用场景：目标页面不需要执行 JS、无浏览器指纹校验等。
+	*/
+	async fetchUrlRequest(pageUrl, url) {
+		const absoluteUrl = this.normalizeUrl(pageUrl, url);
+		const { data: text } = await xr.getText({
+			url: absoluteUrl,
+			autoReferer: true,
+			proxyUrl: this.config.proxy
+		});
+		return text;
+	}
+	/**
+	* 按引擎抓取页面文本。
+	*
+	* 兜底说明：未知引擎会走 `request` 分支（三元表达式最后一项），
+	* 因此调用方传入非法引擎值不会抛错，而是按 request 处理。
+	*/
+	async fetchUrl(pageUrl, url, engine, options) {
+		return engine === "headless" ? await this.fetchUrlHeadless(pageUrl, url, options) : engine === "headful" ? await this.fetchUrlHeadful(pageUrl, url, options) : await this.fetchUrlRequest(pageUrl, url);
+	}
+	/**
+	* 抓取页面并解析为 DOM 元素（html 内容类型）。
+	*/
+	async fetchUrlAsHTMLElement(pageUrl, url, engine, options) {
+		const text = await this.fetchUrl(pageUrl, url, engine, options);
+		return parse(text);
+	}
+	/**
+	* 抓取页面并解析为 JSON 值（json 内容类型）。
+	*/
+	async fetchUrlAsJSON(pageUrl, url, engine) {
+		const text = await this.fetchUrl(pageUrl, url, engine);
+		return JSON.parse(text);
+	}
+	/**
+	* 将元素内所有图片识别为文本并替换到原位置。
+	*
+	* 仅处理带 `src` 的 `img`，识别结果通过 `escape` 转义后写入占位 `div`，
+	* 供后续 `getPlainText` 提取时包含 OCR 文本。
+	*/
+	async ocr(pageUrl, el, ocr) {
+		const imgDocs = el.querySelectorAll("img");
+		for (const imgDoc of imgDocs) {
+			const imgUrl = imgDoc.getAttribute("src");
+			if (imgUrl) {
+				const ocrText = await ocr(this.normalizeUrl(pageUrl, imgUrl));
+				imgDoc.replaceWith(`<div>${escape(ocrText)} </div>`);
+			}
+		}
+	}
+	/**
+	* 按 ID 在 `next` 树中查找可复用的下一步配置。
+	*
+	* 结果被 `memoize` 缓存，同一 ID 只做一次深度遍历。
+	*/
+	findNextById = memoize((id) => {
+		const findNextById = (nexts) => {
+			for (const next of castArray(nexts)) if (typeof next !== "string") {
+				if (next.id === id) return next;
+				if (next.next) {
+					const _next = findNextById(next.next);
+					if (_next) return _next;
+				}
+			}
+		};
+		return this.config.next && findNextById(this.config.next);
+	});
+	/**
+	* 已访问网址缓存，用于去重，避免重复抓取同一页面。
+	*/
+	pageUrlCache = /* @__PURE__ */ new Set();
+	/**
+	* 递归抓取核心方法。
+	*
+	* 主要分支：
+	* - `json` 内容类型：通过 `field` / `url` 取得下一级字段值，再执行
+	*   `extract`（字符串 select 用 `get` 取路径，其余形式暂未实现，留 TODO）；
+	* - `html` 内容类型：通过 `element` / `url` 取得下一级元素集合，再执行
+	*   `extract`（支持 `select` 选择器/筛选器/函数，`extract` 导出方式，
+	*   `ocr` 图片识别与 `transform` 转换）。
+	*
+	* 出口：
+	* - 无 `next.next` 时，当前 `newData` 即为一条最终数据，通过 `newData`
+	*   事件（`listen` 回调）对外抛出；
+	* - 有 `next.next` 时，逐个构建下一级参数并递归调用，随后处理
+	*   `nextPageUrl` 分页。
+	*/
+	async next(pageUrl, contentType, engine, elOrField, data, next, index, rootElement) {
+		if (next.filter && !await next.filter(data)) return;
+		contentType = next.contentType || contentType;
+		engine = next.engine || engine;
+		if (contentType === "json") {
+			const field = elOrField;
+			const nextFields = next.url ? await Promise.all(castArray(typeof next.url === "function" ? await next.url(data) : data[next.url]).map((url) => this.fetchUrlAsJSON(pageUrl, url, engine))) : !next.field || next.field === "." ? [field] : typeof next.field === "string" ? get(field, next.field) : castArray(await next.field(field));
+			for (const nextField of nextFields) {
+				const newData = cloneDeepFast(data);
+				if (next.extract) {
+					const fieldKeys = keysStrict(next.extract);
+					for (const fieldKey of fieldKeys) {
+						const fieldConfig = typeof next.extract[fieldKey] === "string" || typeof next.extract[fieldKey] === "function" || Array.isArray(next.extract[fieldKey]) ? { select: next.extract[fieldKey] } : next.extract[fieldKey];
+						let fieldValue = !fieldConfig.select || fieldConfig.select === "." ? nextField : typeof fieldConfig.select === "string" ? get(nextField, fieldConfig.select) : Array.isArray(fieldConfig.select) ? "TODO" : "TODO";
+						if (fieldValue != null) {
+							fieldValue = fieldConfig.transform ? await fieldConfig.transform(fieldValue) : fieldValue;
+							fieldValue = this.schemaMap[fieldKey].cast(fieldValue);
+							newData[fieldKey] = fieldValue;
+						}
+					}
+				}
+				if (next.next) for (const nextItem of castArray(next.next)) await this.next(pageUrl, contentType, engine, nextField, newData, typeof nextItem === "string" ? this.findNextById(nextItem) : nextItem, 0, rootElement);
+				else this.emit("newData", newData);
+			}
+		} else {
+			const el = elOrField;
+			const nextEls = next.url ? await Promise.all(next._url.map((fullUrl) => this.fetchUrlAsHTMLElement(pageUrl, fullUrl, engine, next.engineOptions))) : !next.element || next.element === "." ? [el] : typeof next.element === "string" ? el.querySelectorAll(next.element) : castArray(await next.element(el, {
+				index,
+				root: rootElement
+			}));
+			const nextParamsList = [];
+			let nextElIndex = 0;
+			for (const nextEl of nextEls) {
+				const newData = cloneDeepFast(data);
+				if (next.extract) {
+					const fieldKeys = keysStrict(next.extract);
+					for (const fieldKey of fieldKeys) {
+						const fieldConfig = typeof next.extract[fieldKey] === "string" || typeof next.extract[fieldKey] === "function" || Array.isArray(next.extract[fieldKey]) ? { select: next.extract[fieldKey] } : next.extract[fieldKey];
+						const fieldEl = !fieldConfig.select || fieldConfig.select === "." ? nextEl : typeof fieldConfig.select === "string" ? nextEl.querySelector(fieldConfig.select) : Array.isArray(fieldConfig.select) ? nextEl.querySelectorAll(fieldConfig.select[0]).find((item) => {
+							const filter = fieldConfig.select[1];
+							return typeof filter === "string" ? item.text.includes(filter) : isRegExp(filter) ? filter.test(item.text) : filter(item);
+						}) : await fieldConfig.select(nextEl);
+						if (fieldEl != null) {
+							let fieldText = "";
+							if (typeof fieldEl === "string") fieldText = fieldEl.trim();
+							else {
+								if (fieldConfig.ocr) await this.ocr(pageUrl, fieldEl, fieldConfig.ocr);
+								switch (fieldConfig.extract) {
+									case "getHTML":
+										fieldText = fieldEl.outerHTML;
+										break;
+									case "getFirstImageUrl":
+										fieldText = this.normalizeUrl(pageUrl, fieldEl.getAttribute("src") || fieldEl.querySelector("img")?.getAttribute("src") || "");
+										break;
+									case "getFirstLinkUrl":
+										fieldText = this.normalizeUrl(pageUrl, fieldEl.getAttribute("href") || fieldEl.querySelector("a")?.getAttribute("href") || "");
+										break;
+									default: fieldText = fieldEl.text.trim();
+								}
+							}
+							let fieldValue = fieldConfig.transform ? await fieldConfig.transform(fieldText) : fieldText;
+							const fieldSchema = this.schemaMap[fieldKey];
+							if (fieldSchema.options.type !== "array") fieldValue = fieldSchema.cast(fieldValue);
+							else fieldValue = fieldSchema.cast([...newData[fieldKey] || [], fieldValue]);
+							newData[fieldKey] = fieldValue;
+						}
+					}
+				}
+				if (next.next) {
+					const nexts = await Promise.all(castArray(next.next).map(async (nextItem) => {
+						nextItem = cloneDeepFast(typeof nextItem === "string" ? this.findNextById(nextItem) : nextItem);
+						if (nextItem.url) nextItem._url = castArray(typeof nextItem.url === "function" ? await nextItem.url({
+							data: newData,
+							el: nextEl
+						}) : newData[nextItem.url]).map((url) => this.normalizeUrl(pageUrl, url)).filter((fullUrl) => !this.pageUrlCache.has(fullUrl)).map((fullUrl) => {
+							this.pageUrlCache.add(fullUrl);
+							return fullUrl;
+						});
+						return nextItem;
+					}));
+					let i = 0;
+					for (const nextItem of nexts) {
+						nextParamsList.push([
+							nextItem.url && nextItem._url[i] || pageUrl,
+							contentType,
+							engine,
+							nextEl,
+							newData,
+							nextItem,
+							nextElIndex,
+							rootElement
+						]);
+						i++;
+					}
+				} else this.emit("newData", newData);
+				nextElIndex++;
+			}
+			for (const nextParams of nextParamsList) {
+				await this.next(...nextParams);
+				if (next.nextPageUrl) {
+					const nextPageUrl = await next.nextPageUrl({
+						data: nextParams[4],
+						el: nextParams[3],
+						url: nextParams[0]
+					});
+					if (nextPageUrl) {
+						const nextPageAbsoluteUrl = this.normalizeUrl(nextParams[0], nextPageUrl);
+						if (nextPageAbsoluteUrl !== nextParams[0]) {
+							const nextPageElement = await this.fetchUrlAsHTMLElement(nextPageAbsoluteUrl, nextPageAbsoluteUrl, engine, this.config.engineOptions);
+							await this.next(nextPageAbsoluteUrl, contentType, engine, nextPageElement, nextParams[4], omitStrict(next, ["url"]), index, rootElement);
+						}
+					}
+				}
+			}
+		}
+	}
+	/**
+	* 启动抓取。
+	*
+	* - 默认 `contentType` 为 `'html'`、`engine` 为 `'request'`；
+	* - 抓取入口后开始逐级处理 `config.extract` 与 `config.next`；
+	* - 最终数据通过 `newData` 事件（`listen` 回调）逐条抛出，
+	*   本方法自身不返回数据，仅用于驱动整个抓取流程完成。
+	*/
+	async start() {
+		const initialContentType = this.config.contentType || "html";
+		const initialEngine = this.config.engine || "request";
+		const rootElement = initialContentType === "json" ? await this.fetchUrlAsJSON(this.config.entry, this.config.entry, initialEngine) : await this.fetchUrlAsHTMLElement(this.config.entry, this.config.entry, initialEngine, this.config.engineOptions);
+		await this.next(this.config.entry, initialContentType, initialEngine, rootElement, {}, {
+			extract: this.config.extract,
+			next: this.config.next
+		}, 0, rootElement);
+	}
+};
+export { XCrawler };