@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/data_set.mjs

@@ -0,0 +1,104 @@
+import { XCsv } from "./csv.mjs";
+import { XDispose } from "./dispose.mjs";
+import { XJson } from "./json.mjs";
+import { XYaml } from "./yaml.mjs";
+import { keyBy, keysStrict, pickStrict } from "vtils";
+import { v } from "vtils/vae";
+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);
+			XDispose.exit.add(async () => {
+				clearInterval(timer);
+				await this.write();
+			});
+		}
+	}
+	/**
+	* 从 `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/db_value.d.mts

@@ -0,0 +1,213 @@
+/**
+ * `XDbValue.SimpleArray` 的配置项。
+ */
+export interface XDbValueSimpleArrayOptions {
+  /**
+   * 元素之间的分隔符。
+   *
+   * @default ','
+   */
+  separator?: string;
+  /**
+   * 存储值的统一前后缀（成对包裹在序列化结果两侧）。
+   *
+   * 例如传入 `"` 后，`['a', 'b']` 会被写为 `"a,b"`。
+   * 读取时仅当值同时以该前后缀开头和结尾时才会被剥离，否则按原始文本解析，
+   * 避免误伤没有前后缀的历史数据。
+   *
+   * @default ''
+   */
+  affix?: string;
+  /**
+   * 是否将数组元素转换为数字。
+   *
+   * @default false
+   */
+  number?: boolean;
+}
+/**
+ * `XDbValue.JsonObject` 的转换钩子配置。
+ *
+ * @template T 对象值的类型。
+ */
+export interface XDbValueJsonObjectOptions<T> {
+  /**
+   * 可选的转换钩子，分别在写入（add）、读取（get）、更新（update）时对值做预处理。
+   */
+  transform?: {
+    /** 写入（add）前对值做转换。 */
+    add?: (value: T) => T;
+    /** 读取（get）后对值做转换。 */
+    get?: (value: T) => T;
+    /** 更新（update）前对值做转换。 */
+    update?: (value: T) => T;
+  };
+}
+/**
+ * 数据库字段值的序列化与反序列化工具。
+ *
+ * 适用于把数组或对象以字符串形式存储到数据库字段（如 VARCHAR / TEXT）的场景，
+ * 内置三种存储格式：
+ * - {@link XDbValue.SimpleArray}：以分隔符连接的数组，支持前后缀与数字模式；
+ * - {@link XDbValue.JsonArray}：JSON 数组；
+ * - {@link XDbValue.JsonObject}：JSON 对象，支持读写转换钩子。
+ *
+ * 每种格式都提供 `add`（写入）、`get`（读取）、`update`（更新）三个方法：
+ * - `add` 返回序列化后的字符串，入参非法时使用默认值兜底；
+ * - `get` 将存储字符串反序列化为目标类型，空值返回空数组或空对象；
+ * - `update` 返回用于更新的字符串，入参非法时返回 `undefined`，便于调用方跳过该字段。
+ *
+ * @example
+ * const sa = new XDbValue.SimpleArray();
+ * sa.add(['a', 'b']);
+ * // 'a,b'
+ * sa.get('a,b');
+ * // ['a', 'b']
+ */
+export declare class XDbValue {
+  /**
+   * 分隔符数组格式：`'a,b'` ↔ `['a', 'b']`。
+   *
+   * @template T 数组元素类型，仅支持 `string` 或 `number`。
+   */
+  static SimpleArray: {
+    new <T extends string | number = string>(options?: XDbValueSimpleArrayOptions): {
+      /** 元素之间的分隔符。 */
+      separator: string;
+      /** 存储值的统一前后缀，空字符串表示不包裹。 */
+      affix: string;
+      /** 是否将数组元素转换为数字。 */
+      number: boolean;
+      /**
+       * 将数组序列化为适合存储的字符串。
+       *
+       * - `value` 不是数组时，使用 `defaultValue` 兜底；
+       * - 过滤掉 `null`、`undefined` 与空字符串元素；
+       * - 结果非空且设置了 `affix` 时在首尾包裹前后缀；结果为空时返回空字符串（不包裹）。
+       *
+       * @param value 要序列化的数组。
+       * @param defaultValue `value` 非法时使用的兜底数组。
+       * @returns 序列化后的字符串。
+       *
+       * @example
+       * const sa = new XDbValue.SimpleArray();
+       * sa.add(['a', 'b']);
+       * // 'a,b'
+       */
+      add: (value?: T[], defaultValue?: T[]) => string;
+      /**
+       * 将存储字符串反序列化为数组。
+       *
+       * - 值为空时返回空数组；
+       * - 设置了 `affix` 时，仅当值同时以该前后缀开头和结尾才会剥离，否则按原始文本解析；
+       * - 按 `separator` 分割并过滤掉空字符串；
+       * - `number` 为 `true` 时，将每个元素转换为数字。
+       *
+       * @param value 存储字符串。
+       * @returns 反序列化后的数组。
+       *
+       * @example
+       * const sa = new XDbValue.SimpleArray();
+       * sa.get('a,b');
+       * // ['a', 'b']
+       */
+      get: (value?: string) => T[];
+      /**
+       * 将数组序列化为用于更新的字符串。
+       *
+       * 与 {@link add} 的区别在于：`value` 不是数组时返回 `undefined`，
+       * 便于调用方在更新数据库时跳过该字段；`value` 是数组但过滤后为空时返回空字符串。
+       *
+       * @param value 要序列化的数组。
+       * @returns 序列化后的字符串；`value` 不是数组时返回 `undefined`。
+       */
+      update: (value?: T[]) => string | undefined;
+    };
+  };
+  /**
+   * JSON 数组格式：`'[{"a":1}]'` ↔ `[{ a: 1 }]`。
+   *
+   * @template T 数组元素类型。
+   */
+  static JsonArray: {
+    new <T = string>(): {
+      /**
+       * 将数组序列化为 JSON 字符串。
+       *
+       * @param value 要序列化的数组。
+       * @param defaultValue `value` 非法时使用的兜底数组。
+       * @returns JSON 字符串。
+       */
+      add: (value?: T[], defaultValue?: T[]) => string;
+      /**
+       * 将 JSON 字符串反序列化为数组。
+       *
+       * - 值为空时返回空数组；
+       * - 值不是合法 JSON 时抛出 `SyntaxError`。
+       *
+       * @param value JSON 字符串。
+       * @returns 反序列化后的数组。
+       */
+      get: (value?: string) => T[];
+      /**
+       * 将数组序列化为用于更新的 JSON 字符串。
+       *
+       * @param value 要序列化的数组。
+       * @returns JSON 字符串；`value` 不是数组时返回 `undefined`。
+       */
+      update: (value?: T[]) => string | undefined;
+    };
+  };
+  /**
+   * JSON 对象格式：`'{"name":"x"}'` ↔ `{ name: 'x' }`。
+   *
+   * 相比 {@link XDbValue.JsonArray}，额外支持 {@link XDbValueJsonObjectOptions.transform}
+   * 转换钩子，适合在读写时统一处理日期、默认值等字段。
+   *
+   * @template T 对象值的类型。
+   */
+  static JsonObject: {
+    new <T>(options?: XDbValueJsonObjectOptions<T>): {
+      /** 构造时传入的转换钩子配置。 */
+      options?: XDbValueJsonObjectOptions<T>;
+      /** 是否配置了 add 转换钩子。 */
+      hasTransformAdd: boolean;
+      /** 是否配置了 get 转换钩子。 */
+      hasTransformGet: boolean;
+      /** 是否配置了 update 转换钩子。 */
+      hasTransformUpdate: boolean;
+      /**
+       * 将对象序列化为 JSON 字符串。
+       *
+       * - 配置 `transform.add` 时，先对值做转换；
+       * - `value` 不是普通对象时，使用 `defaultValue` 兜底。
+       *
+       * @param value 要序列化的对象。
+       * @param defaultValue `value` 非法时使用的兜底对象。
+       * @returns JSON 字符串。
+       */
+      add: (value?: T, defaultValue?: T) => string;
+      /**
+       * 将 JSON 字符串反序列化为对象。
+       *
+       * - 值为空时返回空对象 `{}`；
+       * - 值不是合法 JSON 时抛出 `SyntaxError`；
+       * - 配置 `transform.get` 时对结果做转换，空值解析出的 `{}` 同样会经过该钩子。
+       *
+       * @param value JSON 字符串。
+       * @returns 反序列化后的对象。
+       */
+      get: (value?: string) => T;
+      /**
+       * 将对象序列化为用于更新的 JSON 字符串。
+       *
+       * - 配置 `transform.update` 时，先对值做转换；
+       * - `value` 不是普通对象时返回 `undefined`。
+       *
+       * @param value 要序列化的对象。
+       * @returns JSON 字符串；`value` 不是普通对象时返回 `undefined`。
+       */
+      update: (value?: T) => string | undefined;
+    };
+  };
+}

package/lib/db_value.mjs

@@ -0,0 +1,208 @@
+import { isPlainObject } from "vtils";
+// src/db_value.ts
+/**
+* 数据库字段值的序列化与反序列化工具。
+*
+* 适用于把数组或对象以字符串形式存储到数据库字段（如 VARCHAR / TEXT）的场景，
+* 内置三种存储格式：
+* - {@link XDbValue.SimpleArray}：以分隔符连接的数组，支持前后缀与数字模式；
+* - {@link XDbValue.JsonArray}：JSON 数组；
+* - {@link XDbValue.JsonObject}：JSON 对象，支持读写转换钩子。
+*
+* 每种格式都提供 `add`（写入）、`get`（读取）、`update`（更新）三个方法：
+* - `add` 返回序列化后的字符串，入参非法时使用默认值兜底；
+* - `get` 将存储字符串反序列化为目标类型，空值返回空数组或空对象；
+* - `update` 返回用于更新的字符串，入参非法时返回 `undefined`，便于调用方跳过该字段。
+*
+* @example
+* const sa = new XDbValue.SimpleArray();
+* sa.add(['a', 'b']);
+* // 'a,b'
+* sa.get('a,b');
+* // ['a', 'b']
+*/
+var XDbValue = class {
+	/**
+	* 分隔符数组格式：`'a,b'` ↔ `['a', 'b']`。
+	*
+	* @template T 数组元素类型，仅支持 `string` 或 `number`。
+	*/
+	static SimpleArray = class {
+		/** 元素之间的分隔符。 */
+		separator;
+		/** 存储值的统一前后缀，空字符串表示不包裹。 */
+		affix;
+		/** 是否将数组元素转换为数字。 */
+		number;
+		/**
+		* @param options 配置项，详见 {@link XDbValueSimpleArrayOptions}。
+		*/
+		constructor(options) {
+			this.separator = options?.separator || ",";
+			this.affix = options?.affix || "";
+			this.number = !!options?.number;
+		}
+		/**
+		* 将数组序列化为适合存储的字符串。
+		*
+		* - `value` 不是数组时，使用 `defaultValue` 兜底；
+		* - 过滤掉 `null`、`undefined` 与空字符串元素；
+		* - 结果非空且设置了 `affix` 时在首尾包裹前后缀；结果为空时返回空字符串（不包裹）。
+		*
+		* @param value 要序列化的数组。
+		* @param defaultValue `value` 非法时使用的兜底数组。
+		* @returns 序列化后的字符串。
+		*
+		* @example
+		* const sa = new XDbValue.SimpleArray();
+		* sa.add(['a', 'b']);
+		* // 'a,b'
+		*/
+		add = (value, defaultValue = []) => {
+			const text = (!value || !Array.isArray(value) ? defaultValue : value.filter((v) => v != null && v !== "")).join(this.separator);
+			return !text || !this.affix ? text : `${this.affix}${text}${this.affix}`;
+		};
+		/**
+		* 将存储字符串反序列化为数组。
+		*
+		* - 值为空时返回空数组；
+		* - 设置了 `affix` 时，仅当值同时以该前后缀开头和结尾才会剥离，否则按原始文本解析；
+		* - 按 `separator` 分割并过滤掉空字符串；
+		* - `number` 为 `true` 时，将每个元素转换为数字。
+		*
+		* @param value 存储字符串。
+		* @returns 反序列化后的数组。
+		*
+		* @example
+		* const sa = new XDbValue.SimpleArray();
+		* sa.get('a,b');
+		* // ['a', 'b']
+		*/
+		get = (value) => {
+			if (!value) return [];
+			const res = (this.affix && value.startsWith(this.affix) && value.endsWith(this.affix) ? value.slice(this.affix.length, -this.affix.length) : value).split(this.separator).filter((v) => v !== "");
+			return this.number ? res.map(Number) : res;
+		};
+		/**
+		* 将数组序列化为用于更新的字符串。
+		*
+		* 与 {@link add} 的区别在于：`value` 不是数组时返回 `undefined`，
+		* 便于调用方在更新数据库时跳过该字段；`value` 是数组但过滤后为空时返回空字符串。
+		*
+		* @param value 要序列化的数组。
+		* @returns 序列化后的字符串；`value` 不是数组时返回 `undefined`。
+		*/
+		update = (value) => {
+			const text = !value || !Array.isArray(value) ? void 0 : value.filter((v) => v != null && v !== "").join(this.separator);
+			return !text || !this.affix ? text : `${this.affix}${text}${this.affix}`;
+		};
+	};
+	/**
+	* JSON 数组格式：`'[{"a":1}]'` ↔ `[{ a: 1 }]`。
+	*
+	* @template T 数组元素类型。
+	*/
+	static JsonArray = class {
+		/**
+		* 将数组序列化为 JSON 字符串。
+		*
+		* @param value 要序列化的数组。
+		* @param defaultValue `value` 非法时使用的兜底数组。
+		* @returns JSON 字符串。
+		*/
+		add = (value, defaultValue = []) => {
+			return JSON.stringify(!value || !Array.isArray(value) ? defaultValue : value);
+		};
+		/**
+		* 将 JSON 字符串反序列化为数组。
+		*
+		* - 值为空时返回空数组；
+		* - 值不是合法 JSON 时抛出 `SyntaxError`。
+		*
+		* @param value JSON 字符串。
+		* @returns 反序列化后的数组。
+		*/
+		get = (value) => {
+			return !value ? [] : JSON.parse(value);
+		};
+		/**
+		* 将数组序列化为用于更新的 JSON 字符串。
+		*
+		* @param value 要序列化的数组。
+		* @returns JSON 字符串；`value` 不是数组时返回 `undefined`。
+		*/
+		update = (value) => {
+			return !value || !Array.isArray(value) ? void 0 : JSON.stringify(value);
+		};
+	};
+	/**
+	* JSON 对象格式：`'{"name":"x"}'` ↔ `{ name: 'x' }`。
+	*
+	* 相比 {@link XDbValue.JsonArray}，额外支持 {@link XDbValueJsonObjectOptions.transform}
+	* 转换钩子，适合在读写时统一处理日期、默认值等字段。
+	*
+	* @template T 对象值的类型。
+	*/
+	static JsonObject = class {
+		/** 构造时传入的转换钩子配置。 */
+		options;
+		/** 是否配置了 add 转换钩子。 */
+		hasTransformAdd = false;
+		/** 是否配置了 get 转换钩子。 */
+		hasTransformGet = false;
+		/** 是否配置了 update 转换钩子。 */
+		hasTransformUpdate = false;
+		/**
+		* @param options 转换钩子配置，详见 {@link XDbValueJsonObjectOptions}。
+		*/
+		constructor(options) {
+			this.options = options;
+			this.hasTransformAdd = !!options?.transform?.add;
+			this.hasTransformGet = !!options?.transform?.get;
+			this.hasTransformUpdate = !!options?.transform?.update;
+		}
+		/**
+		* 将对象序列化为 JSON 字符串。
+		*
+		* - 配置 `transform.add` 时，先对值做转换；
+		* - `value` 不是普通对象时，使用 `defaultValue` 兜底。
+		*
+		* @param value 要序列化的对象。
+		* @param defaultValue `value` 非法时使用的兜底对象。
+		* @returns JSON 字符串。
+		*/
+		add = (value, defaultValue = {}) => {
+			if (value && this.hasTransformAdd) value = this.options.transform.add(value);
+			return JSON.stringify(!value || !isPlainObject(value) ? defaultValue : value);
+		};
+		/**
+		* 将 JSON 字符串反序列化为对象。
+		*
+		* - 值为空时返回空对象 `{}`；
+		* - 值不是合法 JSON 时抛出 `SyntaxError`；
+		* - 配置 `transform.get` 时对结果做转换，空值解析出的 `{}` 同样会经过该钩子。
+		*
+		* @param value JSON 字符串。
+		* @returns 反序列化后的对象。
+		*/
+		get = (value) => {
+			let result = !value ? {} : JSON.parse(value);
+			if (result && this.hasTransformGet) result = this.options.transform.get(result);
+			return result;
+		};
+		/**
+		* 将对象序列化为用于更新的 JSON 字符串。
+		*
+		* - 配置 `transform.update` 时，先对值做转换；
+		* - `value` 不是普通对象时返回 `undefined`。
+		*
+		* @param value 要序列化的对象。
+		* @returns JSON 字符串；`value` 不是普通对象时返回 `undefined`。
+		*/
+		update = (value) => {
+			if (value && this.hasTransformUpdate) value = this.options.transform.update(value);
+			return !value || !isPlainObject(value) ? void 0 : JSON.stringify(value);
+		};
+	};
+};
+export { XDbValue };

package/lib/dispose.d.mts

@@ -0,0 +1,98 @@
+/**
+ * `XDispose` 的构造配置。
+ */
+export interface XDisposeOptions {
+  /**
+   * 是否在进程退出时自动调用 `dispose()` 进行资源清理。
+   *
+   * - 默认 `false`：不注册退出钩子，仅支持手动调用 `dispose()` 或通过
+   *   `await using` 触发 `Symbol.asyncDispose`；
+   * - 为 `true` 时：通过 `asyncExitHook` 注册异步退出钩子，进程因
+   *   `SIGINT`、`SIGTERM`、`beforeExit` 等场景退出时自动执行清理，
+   *   清理总时长最多等待 3000ms，超时后由退出钩子强制结束进程。
+   */
+  disposeOnExit?: boolean;
+}
+/**
+ * 资源释放管理器。
+ *
+ * 用于集中管理一组同步/异步清理函数，并在退出时统一、可靠地释放，
+ * 适用于数据库连接、文件句柄、定时器、子进程等资源的生命周期管理。
+ *
+ * 主要行为：
+ * - 通过 `add()` 按注册顺序追加清理函数；
+ * - `dispose()` 幂等：首次调用按注册顺序依次执行全部清理函数，执行后
+ *   清空列表，之后再次调用直接返回，不会重复执行；
+ * - 清理函数逐个执行，单个抛错不会中断后续清理，全部执行完后将错误
+ *   以 `AggregateError` 汇总抛出（无错误则不抛）；
+ * - 实现 `Symbol.asyncDispose`，可直接配合 `await using` 使用；
+ * - 开启 `disposeOnExit` 时自动注册进程退出钩子，退出时调用 `dispose()`。
+ *
+ * @example
+ * const dispose = new XDispose({ disposeOnExit: true });
+ *
+ * dispose.add(() => db.close());
+ * dispose.add(async () => {
+ *   await fs.rm(tmpDir, { recursive: true, force: true });
+ * });
+ *
+ * // 进程退出时自动清理，也可手动触发
+ * await dispose.dispose();
+ */
+export declare class XDispose {
+  private options?;
+  /** 已注册的清理函数列表，按注册顺序存放。 */
+  private disposes;
+  /** 是否已完成清理，保证 `dispose()` 幂等。 */
+  private disposed;
+  /**
+   * 创建资源释放管理器。
+   *
+   * @param options 构造配置；`disposeOnExit` 为 `true` 时立即注册
+   *                进程退出钩子（见 {@link XDisposeOptions}）。
+   */
+  constructor(options?: XDisposeOptions | undefined);
+  /**
+   * 注册一个清理函数。
+   *
+   * 清理函数支持同步或异步返回值，`dispose()` 执行时会 `await` 其结果。
+   * 已调用过 `dispose()` 后再注册会抛错，因为此时资源已释放完毕。
+   *
+   * @param fn 清理函数，按注册顺序在 `dispose()` 中依次执行。
+   *
+   * @example
+   * dispose.add(() => server.close());
+   */
+  add(fn: () => any): void;
+  /**
+   * 释放所有已注册的资源。
+   *
+   * 幂等：首次调用按注册顺序依次执行全部清理函数并清空列表，之后的
+   * 调用直接返回。单个清理函数抛错不会中断后续执行，全部执行完后若
+   * 存在错误则以 `AggregateError` 汇总抛出。
+   *
+   * @returns 全部清理函数成功执行后 resolve；存在失败时 reject，
+   *          错误为聚合了全部失败项的 `AggregateError`。
+   */
+  dispose(): Promise<void>;
+  /**
+   * `await using` 支持。
+   *
+   * 等价于调用 `dispose()`，用于在 `using` 语句作用域结束时自动释放。
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+  /**
+   * 进程级共享的释放管理器实例。
+   *
+   * 该实例已开启 `disposeOnExit`，进程退出时会自动执行注册到其上的全部
+   * 清理函数。适用于不希望手动创建并持有 `XDispose` 实例的场景，直接
+   * 通过 `XDispose.exit.add(...)` 注册清理函数即可，进程退出时统一释放。
+   *
+   * 注意：作为进程级单例，该实例被 `dispose()` 后无法再注册清理函数，
+   * 通常无需手动调用，进程退出时由退出钩子自动处理。
+   *
+   * @example
+   * XDispose.exit.add(() => db.close());
+   */
+  static exit: XDispose;
+}