@jayfong/x-utils 1.0.0-202510061015 → 3.3.0

package/lib/crawler.mjs

@@ -0,0 +1,313 @@
+import { XPuppeteer } from "./puppeteer.mjs";
+import { xr } from "@jayfong/x-request";
+import { parse } from "node-html-parser";
+import { EventBus, castArray, cloneDeepFast, escape, get, isRegExp, isUrl, keysStrict, memoize, omitStrict } from "vtils";
+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 };

package/lib/csv.d.mts

@@ -0,0 +1,67 @@
+/**
+ * CSV 解析/序列化的配置项。
+ *
+ * 这些字段用于在 CSV 与对象之间做更强的类型转换：
+ * - `arrayFieldNames`：按分隔符拆分/组装数组字段；
+ * - `objectFieldNames`：将 JSON 字符串恢复为对象，或写出为字符串；
+ * - `booleanFieldNames`：将 `1/0` 这类值恢复为布尔值；
+ * - `dateFieldNames`：将日期字符串转换为 `Date` 对象，写出时按指定格式格式化。
+ */
+export interface XCsvParseOptions {
+  /** 需要按 `arrayDelimiter` 拆分为数组的字段名列表。 */
+  arrayFieldNames?: string[];
+  /** 数组字段的分隔符；仅在 `arrayFieldNames` 生效时使用。 */
+  arrayDelimiter?: string;
+  /** 需要 JSON 解析为对象的字段名列表。 */
+  objectFieldNames?: string[];
+  /** 需要转换为布尔值的字段名列表；CSV 中常见 `1/0` 形式。 */
+  booleanFieldNames?: string[];
+  /** 需要转换为 `Date` 的字段名列表。 */
+  dateFieldNames?: string[];
+}
+/**
+ * CSV 序列化配置与解析配置相同，因此直接复用同一组字段定义。
+ */
+export interface XCsvStringifyOptions extends XCsvParseOptions {}
+/**
+ * CSV 数据的通用读写工具。
+ *
+ * 设计目标：
+ * - 让对象字段在 CSV 与 JavaScript/TypeScript 之间可互转；
+ * - 在常见场景中自动处理数组、对象、布尔值和日期；
+ * - 提供与文件系统统一的 `read` / `write` 能力，方便配置和报表场景使用。
+ */
+export declare class XCsv {
+  /**
+   * 解析 CSV 文本为对象数组。
+   *
+   * 当启用 `arrayFieldNames` / `objectFieldNames` / `booleanFieldNames` /
+   * `dateFieldNames` 这些选项时，会对相应字段执行类型转换；否则直接返回
+   * 原始解析结果。
+   */
+  static parse<T>(value: string, options?: XCsvParseOptions): Promise<T[]>;
+  /**
+   * 将对象数组序列化为 CSV 文本。
+   *
+   * 对于数组、对象、布尔和日期字段，会在输出前做统一转换：
+   * - 数组字段以 `arrayDelimiter` 拼接；
+   * - 对象字段使用 `JSON.stringify`；
+   * - 布尔字段输出 `1/0`；
+   * - 日期字段按 `yyyy-mm-dd hh:ii:ss` 输出。
+   */
+  static stringify(value: any[], options?: XCsvStringifyOptions): Promise<string>;
+  /**
+   * 读取 CSV 文件并立即解析为对象数组。
+   *
+   * 传入的 `options` 会应用到 `parse` 中，因此开发者可以用同一套规则在
+   * 文件读取和内存对象转换两种场景中保持行为一致。
+   */
+  static read<T>(file: string, options?: XCsvParseOptions): Promise<T[]>;
+  /**
+   * 将对象数组写入 CSV 文件。
+   *
+   * 这里会先走 `stringify`，再将结果写到目标文件。调用方可传入相同的
+   * `XCsvStringifyOptions` 以控制数组、对象、布尔和日期字段输出格式。
+   */
+  static write(file: string, value: any, options?: XCsvStringifyOptions): Promise<void>;
+}

package/lib/csv.mjs

@@ -0,0 +1,76 @@
+import { mapValues } from "vtils";
+import * as fs from "node:fs";
+import * as csv from "csv";
+import { formatDate } from "vtils/date";
+// src/csv.ts
+/**
+* CSV 数据的通用读写工具。
+*
+* 设计目标：
+* - 让对象字段在 CSV 与 JavaScript/TypeScript 之间可互转；
+* - 在常见场景中自动处理数组、对象、布尔值和日期；
+* - 提供与文件系统统一的 `read` / `write` 能力，方便配置和报表场景使用。
+*/
+var XCsv = class XCsv {
+	/**
+	* 解析 CSV 文本为对象数组。
+	*
+	* 当启用 `arrayFieldNames` / `objectFieldNames` / `booleanFieldNames` /
+	* `dateFieldNames` 这些选项时，会对相应字段执行类型转换；否则直接返回
+	* 原始解析结果。
+	*/
+	static async parse(value, options = {}) {
+		const res = [];
+		for await (const item of csv.parse(value, { columns: true })) res.push(options.objectFieldNames?.length || options.booleanFieldNames?.length || options.dateFieldNames?.length || options.arrayFieldNames?.length && options.arrayDelimiter ? mapValues(item, (v, k) => {
+			if (options.arrayFieldNames.includes(k)) return v.split(options.arrayDelimiter).filter(Boolean);
+			if (options.objectFieldNames?.includes(k)) return v ? JSON.parse(v) : {};
+			if (options.booleanFieldNames?.includes(k)) {
+				if (v === "" || v == null) return;
+				return v === true || v === "1" || v === 1 || v === "true";
+			}
+			if (options.dateFieldNames?.includes(k)) return v ? new Date(v) : void 0;
+			return v;
+		}) : item);
+		return res;
+	}
+	/**
+	* 将对象数组序列化为 CSV 文本。
+	*
+	* 对于数组、对象、布尔和日期字段，会在输出前做统一转换：
+	* - 数组字段以 `arrayDelimiter` 拼接；
+	* - 对象字段使用 `JSON.stringify`；
+	* - 布尔字段输出 `1/0`；
+	* - 日期字段按 `yyyy-mm-dd hh:ii:ss` 输出。
+	*/
+	static async stringify(value, options = {}) {
+		let res = "";
+		for await (const line of csv.stringify(options.objectFieldNames?.length || options.booleanFieldNames?.length || options.dateFieldNames?.length || options.arrayFieldNames?.length && options.arrayDelimiter ? value.map((item) => mapValues(item, (v, k) => {
+			if (options.arrayFieldNames.includes(k)) return v ? v.join(options.arrayDelimiter) : "";
+			if (options.objectFieldNames?.includes(k)) return JSON.stringify(v || {});
+			if (options.booleanFieldNames?.includes(k)) return v ? "1" : "0";
+			if (options.dateFieldNames?.includes(k)) return v ? formatDate(v, "yyyy-mm-dd hh:ii:ss") : v;
+			return v;
+		})) : value, { header: true })) res += line;
+		return res;
+	}
+	/**
+	* 读取 CSV 文件并立即解析为对象数组。
+	*
+	* 传入的 `options` 会应用到 `parse` 中，因此开发者可以用同一套规则在
+	* 文件读取和内存对象转换两种场景中保持行为一致。
+	*/
+	static async read(file, options = {}) {
+		const value = await fs.promises.readFile(file, "utf8");
+		return XCsv.parse(value, options);
+	}
+	/**
+	* 将对象数组写入 CSV 文件。
+	*
+	* 这里会先走 `stringify`，再将结果写到目标文件。调用方可传入相同的
+	* `XCsvStringifyOptions` 以控制数组、对象、布尔和日期字段输出格式。
+	*/
+	static async write(file, value, options = {}) {
+		await fs.promises.writeFile(file, await XCsv.stringify(value, options));
+	}
+};
+export { XCsv };

package/lib/data_set.d.mts

@@ -0,0 +1,76 @@
+import { VaeObjectSchemaShapeOf, v } from "vtils/vae";
+import { OmitStrict } from "vtils/types";
+/**
+ * 基于本地文件（JSON / YAML / CSV）的轻量数据集存储。
+ *
+ * `XDataSet` 将一组可通过 vae 校验的对象持久化为单个文件，并提供以下能力：
+ * - 以 `dataKey` 字段作为主键，内存中以 `Map` 形式维护记录，便于快速定位与去重；
+ * - 通过 `dataSchema` 在读写时对数据做类型转换与校验；
+ * - 根据文件扩展名自动选择 JSON、YAML 或 CSV 读写方式；
+ * - 可选地按固定间隔自动落盘，并在进程退出前做最后一次写入。
+ */
+export interface XDataSetOptions<T extends Record<string, any>, K extends keyof T> {
+  /** 数据文件路径；扩展名决定存储格式：`.csv`、`.yaml`/`.yml`，其余按 JSON 处理。 */
+  storeFile: string;
+  /** 记录结构的 vae schema，入参为 `v`，返回各字段 schema；用于读写时的类型转换与校验。 */
+  dataSchema: (_: typeof v) => VaeObjectSchemaShapeOf<T>;
+  /** 作为记录主键的字段名，`currentMap` 以该字段值作为键。 */
+  dataKey: K;
+  /** CSV 存储时数组字段的分隔符。 */
+  csvArrayDelimiter?: string;
+  /** 自动写入间隔（毫秒），仅在未关闭自动写入时生效。 @default 5000 */
+  autoWriteInterval?: number;
+  /** 是否关闭自动写入。 @default false */
+  noAutoWrite?: boolean;
+}
+/**
+ * 数据集实例，负责将记录数组映射到 `storeFile` 并做类型转换。
+ *
+ * @template T 数据集中的单条记录类型。
+ * @template K `T` 中作为主键的字段名。
+ */
+export declare class XDataSet<T extends Record<string, any>, K extends keyof T> {
+  private options;
+  /** 存储格式，由 `storeFile` 扩展名推导得出。 */
+  private storeType;
+  /** 记录结构的 vae schema 形状（字段名 → 字段 schema）。 */
+  private dataShapeSchema;
+  /** 由 `dataShapeSchema` 组合得到的对象 schema，用于整体转换与校验。 */
+  private dataSchema;
+  /** 根据 schema 推导出的 CSV 解析/序列化配置。 */
+  private csvOptions;
+  /** 以 `dataKey` 字段值为键的记录映射，值为去掉主键后的记录。 */
+  currentMap: Record<T[K], OmitStrict<T, K>>;
+  /**
+   * 将 `currentMap` 还原为记录数组。
+   *
+   * 每条记录会按 schema 定义的字段顺序重组，并执行一次 schema 转换，
+   * 保证返回结构与 `dataSchema` 声明一致。
+   */
+  get current(): T[];
+  /**
+   * @param options 数据集配置，详见 {@link XDataSetOptions}。
+   *
+   * 构造函数会先根据 `storeFile` 扩展名确定存储格式，再基于 `dataSchema`
+   * 生成 CSV 所需的字段类型转换配置。若未设置 `noAutoWrite`，则启动定时器
+   * 周期性调用 {@link write}，并在进程退出时做最后一次写入。
+   */
+  constructor(options: XDataSetOptions<T, K>);
+  /**
+   * 从 `storeFile` 读取数据集。
+   *
+   * - 文件不存在或读取/解析失败时返回空数组（不会抛错）；
+   * - 读取成功后对每条记录执行 schema 转换，并重建 `currentMap`。
+   *
+   * @returns 读取并转换后的记录数组。
+   */
+  read(): Promise<T[]>;
+  /**
+   * 将数据集写入 `storeFile`。
+   *
+   * 写入前会确保父目录存在；未显式传入 `dataSet` 时使用 `current` 作为数据源。
+   *
+   * @param dataSet 要写入的记录数组，默认取 `current`。
+   */
+  write(dataSet?: T[]): Promise<void>;
+}

package/lib/data_set.mjs

@@ -0,0 +1,104 @@
+import { XCsv } from "./csv.mjs";
+import { XJson } from "./json.mjs";
+import { XYaml } from "./yaml.mjs";
+import { keyBy, keysStrict, pickStrict } from "vtils";
+import { v } from "vtils/vae";
+import { asyncExitHook } from "exit-hook";
+import * as path from "node:path";
+import fs from "fs-extra";
+// src/data_set.ts
+/**
+* 数据集实例，负责将记录数组映射到 `storeFile` 并做类型转换。
+*
+* @template T 数据集中的单条记录类型。
+* @template K `T` 中作为主键的字段名。
+*/
+var XDataSet = class {
+	options;
+	/** 存储格式，由 `storeFile` 扩展名推导得出。 */
+	storeType;
+	/** 记录结构的 vae schema 形状（字段名 → 字段 schema）。 */
+	dataShapeSchema;
+	/** 由 `dataShapeSchema` 组合得到的对象 schema，用于整体转换与校验。 */
+	dataSchema;
+	/** 根据 schema 推导出的 CSV 解析/序列化配置。 */
+	csvOptions;
+	/** 以 `dataKey` 字段值为键的记录映射，值为去掉主键后的记录。 */
+	currentMap;
+	/**
+	* 将 `currentMap` 还原为记录数组。
+	*
+	* 每条记录会按 schema 定义的字段顺序重组，并执行一次 schema 转换，
+	* 保证返回结构与 `dataSchema` 声明一致。
+	*/
+	get current() {
+		const orderedDataFieldNames = keysStrict(this.dataShapeSchema);
+		return keysStrict(this.currentMap).map((dataKeyValue) => {
+			const data = {
+				...this.currentMap[dataKeyValue],
+				[this.options.dataKey]: dataKeyValue
+			};
+			return this.dataSchema.cast(pickStrict(data, orderedDataFieldNames));
+		});
+	}
+	/**
+	* @param options 数据集配置，详见 {@link XDataSetOptions}。
+	*
+	* 构造函数会先根据 `storeFile` 扩展名确定存储格式，再基于 `dataSchema`
+	* 生成 CSV 所需的字段类型转换配置。若未设置 `noAutoWrite`，则启动定时器
+	* 周期性调用 {@link write}，并在进程退出时做最后一次写入。
+	*/
+	constructor(options) {
+		this.options = options;
+		this.storeType = options.storeFile.endsWith(".csv") ? "csv" : options.storeFile.endsWith(".yaml") || options.storeFile.endsWith(".yml") ? "yaml" : "json";
+		this.dataShapeSchema = options.dataSchema(v);
+		this.dataSchema = v.object(this.dataShapeSchema);
+		this.csvOptions = {
+			arrayDelimiter: options.csvArrayDelimiter,
+			arrayFieldNames: keysStrict(this.dataShapeSchema).filter((key) => this.dataShapeSchema[key].options.type === "array"),
+			objectFieldNames: keysStrict(this.dataShapeSchema).filter((key) => this.dataShapeSchema[key].options.type === "object"),
+			booleanFieldNames: keysStrict(this.dataShapeSchema).filter((key) => this.dataShapeSchema[key].options.type === "boolean"),
+			dateFieldNames: keysStrict(this.dataShapeSchema).filter((key) => this.dataShapeSchema[key].options.type === "date")
+		};
+		if (!options.noAutoWrite) {
+			const timer = setInterval(() => {
+				this.write();
+			}, options.autoWriteInterval || 5e3);
+			asyncExitHook(async () => {
+				clearInterval(timer);
+				await this.write();
+			}, { wait: 1e4 });
+		}
+	}
+	/**
+	* 从 `storeFile` 读取数据集。
+	*
+	* - 文件不存在或读取/解析失败时返回空数组（不会抛错）；
+	* - 读取成功后对每条记录执行 schema 转换，并重建 `currentMap`。
+	*
+	* @returns 读取并转换后的记录数组。
+	*/
+	async read() {
+		let dataSet = [];
+		try {
+			dataSet = await (this.storeType === "csv" ? XCsv.read(this.options.storeFile, this.csvOptions) : this.storeType === "yaml" ? XYaml.read(this.options.storeFile) : XJson.read(this.options.storeFile));
+		} catch {}
+		dataSet = dataSet.map((data) => this.dataSchema.cast(data));
+		this.currentMap = keyBy(dataSet, (data) => data[this.options.dataKey]);
+		return dataSet;
+	}
+	/**
+	* 将数据集写入 `storeFile`。
+	*
+	* 写入前会确保父目录存在；未显式传入 `dataSet` 时使用 `current` 作为数据源。
+	*
+	* @param dataSet 要写入的记录数组，默认取 `current`。
+	*/
+	async write(dataSet = this.current) {
+		console.log(`💥 写入 ${this.options.storeFile}`);
+		await fs.ensureDir(path.dirname(this.options.storeFile));
+		await (this.storeType === "csv" ? XCsv.write(this.options.storeFile, dataSet, this.csvOptions) : this.storeType === "yaml" ? XYaml.write(this.options.storeFile, dataSet) : XJson.write(this.options.storeFile, dataSet));
+		console.log(`✅ 写入 ${this.options.storeFile}`);
+	}
+};
+export { XDataSet };

package/lib/fs.d.mts

@@ -0,0 +1,49 @@
+import fs from "fs-extra";
+/**
+ * 额外的文件类型辅助方法：
+ * - `getMimeType`：将扩展名 / 文件名 / MIME 字符串统一转换为 MIME 类型；
+ * - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名。
+ *
+ * 这些方法会被合并到 `XFs` 中，与 `fs-extra` 的 API 一起导出。
+ */
+declare const XFsExtra: {
+  /**
+   * 获取 MIME 类型。
+   *
+   * 入参支持以下形式：
+   * - 扩展名：`json`、`png`
+   * - 文件名：`file.txt`、`archive.tar.gz`
+   * - MIME 字符串：`application/json`
+   *
+   * 处理规则：
+   * 1. 去除首尾空白后，如果为空，返回通用兜底值 `application/octet-stream`；
+   * 2. 如果已是 MIME 形式（包含 `/`），直接返回原值；
+   * 3. 否则交给 `mime.getType` 推断；
+   * 4. 推断失败时，返回 `application/octet-stream`。
+   */
+  getMimeType(extOrName: string): string;
+  /**
+   * 获取扩展名（不带 `.`）。
+   *
+   * 入参支持以下形式：
+   * - MIME 字符串：`image/png`、`text/plain`
+   * - 文件名：`file.txt`、`archive.tar.gz`
+   * - 扩展名：`json`
+   *
+   * 处理规则：
+   * 1. 去除首尾空白后，如果为空，返回空字符串；
+   * 2. 如果是 MIME 形式（包含 `/`），优先通过 `mime.getExtension` 推断，
+   *    若推断失败则退化为取 `/` 右侧片段；
+   * 3. 如果是文件名（包含 `.`），返回最后一段后缀；
+   * 4. 否则按扩展名/MIME 简写尝试 `mime.getExtension`，失败返回空字符串。
+   */
+  getExtension(typeOrName: string): string;
+};
+/**
+ * `XFs` = `fs-extra` + 轻量文件类型工具。
+ *
+ * 这样调用方既可以直接使用完整的文件系统 API（如 `readFile`、`writeFile`），
+ * 也可以在同一对象上使用 `getMimeType` 和 `getExtension`。
+ */
+export declare const XFs: typeof fs & typeof XFsExtra;
+export {};