@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/crypto.d.mts

@@ -0,0 +1,158 @@
+/**
+ * 常用加解密与摘要工具。
+ *
+ * 提供 Base64 / Base64URL 编解码、常见哈希摘要（MD5、SHA-1、
+ * SHA-256、SHA-512），以及 AES-128-ECB 对称加解密能力，所有方法
+ * 均为静态方法，可直接通过 `XCrypto.xxx()` 调用。
+ *
+ * @example
+ * XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+ * XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+ *
+ * @remarks
+ * - MD5 与 SHA-1 已被视为不安全算法，仅建议用于校验等非安全场景；
+ * - AES 采用 ECB 模式，相同明文加密结果固定，不适用于需要语义安全的
+ *   场景（建议改用 CBC / GCM 等带随机 IV 的模式）；
+ * - 加解密密钥会自动规范化为 16 字节（不足补零、超出截断）。
+ */
+export declare class XCrypto {
+  /**
+   * 将文本编码为 Base64 字符串。
+   *
+   * @param text 需要编码的原始文本。
+   * @returns Base64 编码后的字符串。
+   *
+   * @example
+   * XCrypto.base64Encode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0='
+   * XCrypto.base64Encode('🐲') // '8J+Qsg=='
+   */
+  static base64Encode(text: string): string;
+  /**
+   * 将 Base64 字符串解码为 UTF-8 文本。
+   *
+   * @param text Base64 编码的字符串。
+   * @returns 解码后的 UTF-8 文本。
+   *
+   * @example
+   * XCrypto.base64Decode('eyJ1c2VySWQiOiJkb2l0In0=') // '{"userId":"doit"}'
+   * XCrypto.base64Decode('8J+Qsg==') // '🐲'
+   */
+  static base64Decode(text: string): string;
+  /**
+   * 将文本编码为 URL 安全的 Base64（Base64URL）字符串。
+   *
+   * 与标准 Base64 的区别：`+` 替换为 `-`、`/` 替换为 `_`，并去除
+   * 末尾的 `=` 填充，使其可直接用于 URL 查询参数等场景。
+   *
+   * @param text 需要编码的原始文本。
+   * @returns Base64URL 编码后的字符串。
+   *
+   * @example
+   * XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+   * XCrypto.base64UrlEncode('🐲') // '8J-Qsg'
+   */
+  static base64UrlEncode(text: string): string;
+  /**
+   * 将 Base64URL 字符串解码为 UTF-8 文本。
+   *
+   * @param text Base64URL 编码的字符串。
+   * @returns 解码后的 UTF-8 文本。
+   *
+   * @example
+   * XCrypto.base64UrlDecode('eyJ1c2VySWQiOiJkb2l0In0') // '{"userId":"doit"}'
+   * XCrypto.base64UrlDecode('8J-Qsg') // '🐲'
+   */
+  static base64UrlDecode(text: string): string;
+  /**
+   * 计算文本的 MD5 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 32 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+   */
+  static md5(text: string): string;
+  /**
+   * 计算文本的 SHA-1 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 40 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.sha1('123456') // '7c4a8d09ca3762af61e59520943dc26494f8941b'
+   */
+  static sha1(text: string): string;
+  /**
+   * 计算文本的 SHA-256 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 64 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.sha256('123456') // '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92'
+   */
+  static sha256(text: string): string;
+  /**
+   * 计算文本的 SHA-512 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 128 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.sha512('123456') // 'ba3253876aed6bc22d4a6ff53d8406c6ad864195ed144ab5c87621b6c233b548baeae6956df346ec8c17f5ea10f35ee3cbc514797ed7ddd3145464e2a0bab413'
+   */
+  static sha512(text: string): string;
+  /**
+   * 使用 AES-128-ECB（PKCS7 填充）对文本进行加密。
+   *
+   * @param text 需要加密的文本。
+   * @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+   * @returns Base64 编码的密文。
+   *
+   * @example
+   * XCrypto.aesEncrypt('{"userId":"doit"}', 'hj7Wer8V3epukzV7')
+   * // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+   */
+  static aesEncrypt(text: string, key: string): string;
+  /**
+   * 使用 AES-128-ECB（PKCS7 填充）对文本进行解密。
+   *
+   * @param text Base64 编码的密文。
+   * @param key 解密密钥，需与加密时使用的密钥一致，会自动规范化为 16 字节。
+   * @returns 解密后的 UTF-8 文本。
+   *
+   * @example
+   * XCrypto.aesDecrypt('fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=', 'hj7Wer8V3epukzV7')
+   * // '{"userId":"doit"}'
+   */
+  static aesDecrypt(text: string, key: string): string;
+  /**
+   * 将对象序列化为 JSON 后使用 AES 加密。
+   *
+   * 适用于传输或存储敏感结构化数据前的加密处理。
+   *
+   * @param payload 需要加密的任意数据，内部会先 `JSON.stringify` 序列化。
+   * @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+   * @returns Base64 编码的密文。
+   *
+   * @example
+   * XCrypto.aesEncryptJson({ userId: 'doit' }, 'hj7Wer8V3epukzV7')
+   * // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+   */
+  static aesEncryptJson(payload: unknown, key: string): string;
+  /**
+   * 解密文本并将结果解析为 JSON 对象。
+   *
+   * @param text Base64 编码的密文。
+   * @param key 解密密钥，需与加密时使用的密钥一致。
+   * @returns 解密并解析后的 JSON 对象，类型由泛型 `T` 指定。
+   *
+   * @example
+   * XCrypto.aesDecryptJson<{ userId: string }>(
+   *   'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=',
+   *   'hj7Wer8V3epukzV7',
+   * ) // { userId: 'doit' }
+   */
+  static aesDecryptJson<T>(text: string, key: string): T;
+}

package/lib/crypto.mjs

@@ -0,0 +1,213 @@
+import crypto from "node:crypto";
+// src/crypto.ts
+/**
+* 将任意长度的密钥规范化为 AES-128 所需的 16 字节密钥。
+*
+* 规则：密钥先按 UTF-8 编码为字节序列；不足 16 字节时在右侧补 0，
+* 超过 16 字节时截取前 16 字节。
+*
+* 对于纯 ASCII 密钥，结果与 `key.substring(0, 16)` 完全一致；
+* 同时修复了原实现按字符截取导致多字节字符密钥字节数超长而抛错的问题。
+*/
+function resolveAesKey(key) {
+	return Buffer.concat([Buffer.from(key, "utf8"), Buffer.alloc(16)]).subarray(0, 16);
+}
+/**
+* 计算文本的十六进制摘要。
+*
+* @param text 待摘要的文本。
+* @param algorithm 摘要算法名称（如 md5、sha1、sha256、sha512）。
+* @returns 小写十六进制形式的摘要字符串。
+*/
+function digest(text, algorithm) {
+	return crypto.createHash(algorithm).update(text, "utf8").digest("hex");
+}
+/**
+* 常用加解密与摘要工具。
+*
+* 提供 Base64 / Base64URL 编解码、常见哈希摘要（MD5、SHA-1、
+* SHA-256、SHA-512），以及 AES-128-ECB 对称加解密能力，所有方法
+* 均为静态方法，可直接通过 `XCrypto.xxx()` 调用。
+*
+* @example
+* XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+* XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+*
+* @remarks
+* - MD5 与 SHA-1 已被视为不安全算法，仅建议用于校验等非安全场景；
+* - AES 采用 ECB 模式，相同明文加密结果固定，不适用于需要语义安全的
+*   场景（建议改用 CBC / GCM 等带随机 IV 的模式）；
+* - 加解密密钥会自动规范化为 16 字节（不足补零、超出截断）。
+*/
+var XCrypto = class XCrypto {
+	/**
+	* 将文本编码为 Base64 字符串。
+	*
+	* @param text 需要编码的原始文本。
+	* @returns Base64 编码后的字符串。
+	*
+	* @example
+	* XCrypto.base64Encode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0='
+	* XCrypto.base64Encode('🐲') // '8J+Qsg=='
+	*/
+	static base64Encode(text) {
+		return Buffer.from(text, "utf8").toString("base64");
+	}
+	/**
+	* 将 Base64 字符串解码为 UTF-8 文本。
+	*
+	* @param text Base64 编码的字符串。
+	* @returns 解码后的 UTF-8 文本。
+	*
+	* @example
+	* XCrypto.base64Decode('eyJ1c2VySWQiOiJkb2l0In0=') // '{"userId":"doit"}'
+	* XCrypto.base64Decode('8J+Qsg==') // '🐲'
+	*/
+	static base64Decode(text) {
+		return Buffer.from(text, "base64").toString("utf8");
+	}
+	/**
+	* 将文本编码为 URL 安全的 Base64（Base64URL）字符串。
+	*
+	* 与标准 Base64 的区别：`+` 替换为 `-`、`/` 替换为 `_`，并去除
+	* 末尾的 `=` 填充，使其可直接用于 URL 查询参数等场景。
+	*
+	* @param text 需要编码的原始文本。
+	* @returns Base64URL 编码后的字符串。
+	*
+	* @example
+	* XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+	* XCrypto.base64UrlEncode('🐲') // '8J-Qsg'
+	*/
+	static base64UrlEncode(text) {
+		return Buffer.from(text, "utf8").toString("base64url");
+	}
+	/**
+	* 将 Base64URL 字符串解码为 UTF-8 文本。
+	*
+	* @param text Base64URL 编码的字符串。
+	* @returns 解码后的 UTF-8 文本。
+	*
+	* @example
+	* XCrypto.base64UrlDecode('eyJ1c2VySWQiOiJkb2l0In0') // '{"userId":"doit"}'
+	* XCrypto.base64UrlDecode('8J-Qsg') // '🐲'
+	*/
+	static base64UrlDecode(text) {
+		return Buffer.from(text, "base64url").toString("utf8");
+	}
+	/**
+	* 计算文本的 MD5 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 32 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+	*/
+	static md5(text) {
+		return digest(text, "md5");
+	}
+	/**
+	* 计算文本的 SHA-1 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 40 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.sha1('123456') // '7c4a8d09ca3762af61e59520943dc26494f8941b'
+	*/
+	static sha1(text) {
+		return digest(text, "sha1");
+	}
+	/**
+	* 计算文本的 SHA-256 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 64 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.sha256('123456') // '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92'
+	*/
+	static sha256(text) {
+		return digest(text, "sha256");
+	}
+	/**
+	* 计算文本的 SHA-512 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 128 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.sha512('123456') // 'ba3253876aed6bc22d4a6ff53d8406c6ad864195ed144ab5c87621b6c233b548baeae6956df346ec8c17f5ea10f35ee3cbc514797ed7ddd3145464e2a0bab413'
+	*/
+	static sha512(text) {
+		return digest(text, "sha512");
+	}
+	/**
+	* 使用 AES-128-ECB（PKCS7 填充）对文本进行加密。
+	*
+	* @param text 需要加密的文本。
+	* @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+	* @returns Base64 编码的密文。
+	*
+	* @example
+	* XCrypto.aesEncrypt('{"userId":"doit"}', 'hj7Wer8V3epukzV7')
+	* // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+	*/
+	static aesEncrypt(text, key) {
+		const cipher = crypto.createCipheriv("aes-128-ecb", resolveAesKey(key), null);
+		let encrypted = cipher.update(text, "utf8", "base64");
+		encrypted += cipher.final("base64");
+		return encrypted;
+	}
+	/**
+	* 使用 AES-128-ECB（PKCS7 填充）对文本进行解密。
+	*
+	* @param text Base64 编码的密文。
+	* @param key 解密密钥，需与加密时使用的密钥一致，会自动规范化为 16 字节。
+	* @returns 解密后的 UTF-8 文本。
+	*
+	* @example
+	* XCrypto.aesDecrypt('fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=', 'hj7Wer8V3epukzV7')
+	* // '{"userId":"doit"}'
+	*/
+	static aesDecrypt(text, key) {
+		const decipher = crypto.createDecipheriv("aes-128-ecb", resolveAesKey(key), null);
+		let decrypted = decipher.update(text, "base64", "utf8");
+		decrypted += decipher.final("utf8");
+		return decrypted;
+	}
+	/**
+	* 将对象序列化为 JSON 后使用 AES 加密。
+	*
+	* 适用于传输或存储敏感结构化数据前的加密处理。
+	*
+	* @param payload 需要加密的任意数据，内部会先 `JSON.stringify` 序列化。
+	* @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+	* @returns Base64 编码的密文。
+	*
+	* @example
+	* XCrypto.aesEncryptJson({ userId: 'doit' }, 'hj7Wer8V3epukzV7')
+	* // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+	*/
+	static aesEncryptJson(payload, key) {
+		return XCrypto.aesEncrypt(JSON.stringify(payload), key);
+	}
+	/**
+	* 解密文本并将结果解析为 JSON 对象。
+	*
+	* @param text Base64 编码的密文。
+	* @param key 解密密钥，需与加密时使用的密钥一致。
+	* @returns 解密并解析后的 JSON 对象，类型由泛型 `T` 指定。
+	*
+	* @example
+	* XCrypto.aesDecryptJson<{ userId: string }>(
+	*   'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=',
+	*   'hj7Wer8V3epukzV7',
+	* ) // { userId: 'doit' }
+	*/
+	static aesDecryptJson(text, key) {
+		return JSON.parse(XCrypto.aesDecrypt(text, key));
+	}
+};
+export { XCrypto };

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>;
+}