@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/dispose.mjs

@@ -0,0 +1,107 @@
+import { asyncExitHook } from "exit-hook";
+// src/dispose.ts
+/**
+* 资源释放管理器。
+*
+* 用于集中管理一组同步/异步清理函数，并在退出时统一、可靠地释放，
+* 适用于数据库连接、文件句柄、定时器、子进程等资源的生命周期管理。
+*
+* 主要行为：
+* - 通过 `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();
+*/
+var XDispose = class XDispose {
+	options;
+	/** 已注册的清理函数列表，按注册顺序存放。 */
+	disposes = [];
+	/** 是否已完成清理，保证 `dispose()` 幂等。 */
+	disposed = false;
+	/**
+	* 创建资源释放管理器。
+	*
+	* @param options 构造配置；`disposeOnExit` 为 `true` 时立即注册
+	*                进程退出钩子（见 {@link XDisposeOptions}）。
+	*/
+	constructor(options) {
+		this.options = options;
+		if (this.options?.disposeOnExit) asyncExitHook(() => this.dispose().catch((err) => {
+			console.error("进程退出清理失败", err);
+		}), { wait: 3e3 });
+	}
+	/**
+	* 注册一个清理函数。
+	*
+	* 清理函数支持同步或异步返回值，`dispose()` 执行时会 `await` 其结果。
+	* 已调用过 `dispose()` 后再注册会抛错，因为此时资源已释放完毕。
+	*
+	* @param fn 清理函数，按注册顺序在 `dispose()` 中依次执行。
+	*
+	* @example
+	* dispose.add(() => server.close());
+	*/
+	add(fn) {
+		if (this.disposed) throw new Error("XDispose 已完成清理，不能再注册新的清理函数");
+		this.disposes.push(fn);
+	}
+	/**
+	* 释放所有已注册的资源。
+	*
+	* 幂等：首次调用按注册顺序依次执行全部清理函数并清空列表，之后的
+	* 调用直接返回。单个清理函数抛错不会中断后续执行，全部执行完后若
+	* 存在错误则以 `AggregateError` 汇总抛出。
+	*
+	* @returns 全部清理函数成功执行后 resolve；存在失败时 reject，
+	*          错误为聚合了全部失败项的 `AggregateError`。
+	*/
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		const errors = [];
+		for (const fn of this.disposes) try {
+			await fn();
+		} catch (err) {
+			errors.push(err);
+		}
+		this.disposes = [];
+		if (errors.length > 0) throw new AggregateError(errors, "XDispose 清理过程中发生错误");
+	}
+	/**
+	* `await using` 支持。
+	*
+	* 等价于调用 `dispose()`，用于在 `using` 语句作用域结束时自动释放。
+	*/
+	async [Symbol.asyncDispose]() {
+		await this.dispose();
+	}
+	/**
+	* 进程级共享的释放管理器实例。
+	*
+	* 该实例已开启 `disposeOnExit`，进程退出时会自动执行注册到其上的全部
+	* 清理函数。适用于不希望手动创建并持有 `XDispose` 实例的场景，直接
+	* 通过 `XDispose.exit.add(...)` 注册清理函数即可，进程退出时统一释放。
+	*
+	* 注意：作为进程级单例，该实例被 `dispose()` 后无法再注册清理函数，
+	* 通常无需手动调用，进程退出时由退出钩子自动处理。
+	*
+	* @example
+	* XDispose.exit.add(() => db.close());
+	*/
+	static exit = new XDispose({ disposeOnExit: true });
+};
+export { XDispose };

package/lib/file_store.d.mts

@@ -0,0 +1,167 @@
+import { MsValue } from "vtils";
+/**
+ * `XFileStore` 的初始化配置。
+ *
+ * 面向腾讯云 COS 等兼容 S3 协议的对象存储：通过预签名 URL 让客户端
+ * 直传文件，文件内容不经过业务服务器中转。
+ */
+export interface XFileStoreOptions {
+  /** 对象存储访问密钥 ID（如腾讯云 SecretId）。 */
+  accessKey: string;
+  /** 对象存储访问密钥 Key（如腾讯云 SecretKey）。 */
+  secretKey: string;
+  /**
+   * 对象存储服务端点，可带或不带协议前缀。
+   *
+   * - 不含协议（如 `cos.ap-guangzhou.myqcloud.com`）时，自动补全为
+   *   `https://`；
+   * - 已是完整 URL（如 `https://cos.ap-guangzhou.myqcloud.com`）时
+   *   原样保留。
+   */
+  endpoint: string;
+  /** 存储桶名称，例如 `image-311111`。 */
+  bucket: string;
+  /**
+   * 存储目录前缀，可为空字符串，表示上传到桶根目录。
+   *
+   * 构造时会去除首尾的 `/`，例如 `/images/` 会被规范化为 `images`。
+   */
+  dir: string;
+  /**
+   * 文件公开访问的基础地址（通常为 CDN 域名），可带或不带协议前缀。
+   *
+   * 构造时会去除末尾的 `/`；最终公开地址为
+   * `${cdnUrl}/${dir}/${fileName}`。
+   */
+  cdnUrl: string;
+}
+/**
+ * `getUploadUrl` 的入参。
+ */
+export interface XFileStoreGetUploadUrlPayload {
+  /**
+   * 原始文件名，仅用于推导 MIME 类型与生成最终文件名。
+   *
+   * - `keepName` 为 `false`（默认）时，最终文件名会被替换为
+   *   `${XRandom.cuid2()}.${扩展名}`，原始文件名只参与 MIME 推导；
+   * - `keepName` 为 `true` 时，最终文件名与原始文件名完全一致。
+   */
+  fileName: string;
+  /**
+   * 预签名 URL 的有效时长，需大于 0。
+   *
+   * 支持毫秒数字（如 `60000`）或时长字符串（如 `'1m'`、`'2h'`），
+   * 内部统一换算为秒后传给 AWS SDK。
+   */
+  ttl: MsValue;
+  /**
+   * 是否保留原始文件名。
+   *
+   * @default false 默认生成随机文件名，避免同名覆盖与外部可控路径写入。
+   */
+  keepName?: boolean;
+}
+/**
+ * `getUploadUrl` 的结果。
+ */
+export interface XFileStoreGetUploadUrlResult {
+  /** 文件 MIME 类型，例如 `image/png`。 */
+  contentType: string;
+  /** 预签名上传地址，客户端可直接对其发起 PUT 上传。 */
+  uploadUrl: string;
+  /** 文件上传后的公开访问地址。 */
+  publicUrl: string;
+}
+/**
+ * `upload` 的入参。
+ */
+export interface XFileStoreUploadPayload {
+  /** 文件名，语义与 `XFileStoreGetUploadUrlPayload.fileName` 一致。 */
+  fileName: string;
+  /** 文件二进制内容。 */
+  content: Buffer;
+  /**
+   * 是否保留原始文件名。
+   *
+   * @default false 默认生成随机文件名。
+   */
+  keepName?: boolean;
+}
+/**
+ * `upload` 的结果。
+ *
+ * 与 `getUploadUrl` 返回结构一致：上传完成后返回与预签名阶段相同的
+ * 内容类型、上传地址与公开访问地址。
+ */
+export interface XFileStoreUploadResult extends XFileStoreGetUploadUrlResult {}
+/**
+ * 基于 S3 协议对象存储（如腾讯云 COS）的文件直传工具。
+ *
+ * 提供两条链路：
+ * 1. `getUploadUrl`：只生成预签名上传地址，由客户端自行 PUT 上传；
+ * 2. `upload`：内部生成预签名地址后，直接上传 `Buffer` 内容。
+ *
+ * @example
+ * const fileStore = new XFileStore({
+ *   accessKey: '...',
+ *   secretKey: '...',
+ *   endpoint: 'cos.ap-guangzhou.myqcloud.com',
+ *   bucket: 'image-311111',
+ *   dir: 'x',
+ *   cdnUrl: 'cdn.example.com',
+ * });
+ *
+ * const { uploadUrl, publicUrl } = await fileStore.getUploadUrl({
+ *   fileName: 'avatar.png',
+ *   ttl: '10m',
+ * });
+ *
+ * @remarks
+ * - `endpoint`、`cdnUrl` 缺省协议时自动补全 `https://`，`dir` 去除首尾 `/`；
+ * - 随机文件名使用 24 位 CUID2，碰撞概率极低，适合作为对象 Key；
+ * - 无法识别的文件类型兜底为 `application/octet-stream`。
+ */
+export declare class XFileStore {
+  private options;
+  private endpoint;
+  private dir;
+  private cdnUrl;
+  constructor(options: XFileStoreOptions);
+  /**
+   * 生成文件上传的预签名 URL。
+   *
+   * 处理流程：
+   * 1. 依据 `fileName` 推断 MIME 类型，推断失败时兜底为
+   *    `application/octet-stream`；
+   * 2. 依据 `keepName` 决定沿用原始文件名或生成随机文件名；
+   * 3. 拼接 `dir` 前缀作为对象 Key，并生成带签名的 PUT 地址；
+   * 4. 依据 `cdnUrl` 与 Key 组装公开访问地址。
+   *
+   * @param payload 上传参数，见 {@link XFileStoreGetUploadUrlPayload}。
+   * @returns 内容类型、预签名上传地址与公开访问地址。
+   *
+   * @example
+   * const { uploadUrl, publicUrl } = await fileStore.getUploadUrl({
+   *   fileName: 'avatar.png',
+   *   ttl: '10m',
+   * });
+   */
+  getUploadUrl(payload: XFileStoreGetUploadUrlPayload): Promise<XFileStoreGetUploadUrlResult>;
+  /**
+   * 生成预签名 URL 并直接上传文件内容。
+   *
+   * 先复用 {@link XFileStore.getUploadUrl} 生成预签名地址（默认有效期
+   * 1 分钟），再以 PUT 方式将 `content` 上传到该地址，最后返回与
+   * `getUploadUrl` 一致的结果。
+   *
+   * @param payload 上传参数，见 {@link XFileStoreUploadPayload}。
+   * @returns 内容类型、预签名上传地址与公开访问地址。
+   *
+   * @example
+   * const result = await fileStore.upload({
+   *   fileName: 'avatar.png',
+   *   content: Buffer.from('...'),
+   * });
+   */
+  upload(payload: XFileStoreUploadPayload): Promise<XFileStoreUploadResult>;
+}

package/lib/file_store.mjs

@@ -0,0 +1,120 @@
+import { XRandom } from "./random.mjs";
+import { xr } from "@jayfong/x-request";
+import { isUrl, ms } from "vtils";
+import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import mime from "mime";
+// src/file_store.ts
+/**
+* 基于 S3 协议对象存储（如腾讯云 COS）的文件直传工具。
+*
+* 提供两条链路：
+* 1. `getUploadUrl`：只生成预签名上传地址，由客户端自行 PUT 上传；
+* 2. `upload`：内部生成预签名地址后，直接上传 `Buffer` 内容。
+*
+* @example
+* const fileStore = new XFileStore({
+*   accessKey: '...',
+*   secretKey: '...',
+*   endpoint: 'cos.ap-guangzhou.myqcloud.com',
+*   bucket: 'image-311111',
+*   dir: 'x',
+*   cdnUrl: 'cdn.example.com',
+* });
+*
+* const { uploadUrl, publicUrl } = await fileStore.getUploadUrl({
+*   fileName: 'avatar.png',
+*   ttl: '10m',
+* });
+*
+* @remarks
+* - `endpoint`、`cdnUrl` 缺省协议时自动补全 `https://`，`dir` 去除首尾 `/`；
+* - 随机文件名使用 24 位 CUID2，碰撞概率极低，适合作为对象 Key；
+* - 无法识别的文件类型兜底为 `application/octet-stream`。
+*/
+var XFileStore = class {
+	options;
+	endpoint = "";
+	dir = "";
+	cdnUrl = "";
+	constructor(options) {
+		this.options = options;
+		this.endpoint = isUrl(this.options.endpoint) ? this.options.endpoint : `https://${this.options.endpoint}`;
+		this.dir = this.options.dir ? `${this.options.dir.replace(/^\/+/, "").replace(/\/+$/, "")}` : "";
+		this.cdnUrl = (isUrl(this.options.cdnUrl) ? this.options.cdnUrl : `https://${this.options.cdnUrl}`).replace(/\/+$/, "");
+	}
+	/**
+	* 生成文件上传的预签名 URL。
+	*
+	* 处理流程：
+	* 1. 依据 `fileName` 推断 MIME 类型，推断失败时兜底为
+	*    `application/octet-stream`；
+	* 2. 依据 `keepName` 决定沿用原始文件名或生成随机文件名；
+	* 3. 拼接 `dir` 前缀作为对象 Key，并生成带签名的 PUT 地址；
+	* 4. 依据 `cdnUrl` 与 Key 组装公开访问地址。
+	*
+	* @param payload 上传参数，见 {@link XFileStoreGetUploadUrlPayload}。
+	* @returns 内容类型、预签名上传地址与公开访问地址。
+	*
+	* @example
+	* const { uploadUrl, publicUrl } = await fileStore.getUploadUrl({
+	*   fileName: 'avatar.png',
+	*   ttl: '10m',
+	* });
+	*/
+	async getUploadUrl(payload) {
+		const s3Client = new S3Client({
+			credentials: {
+				accessKeyId: this.options.accessKey,
+				secretAccessKey: this.options.secretKey
+			},
+			endpoint: this.endpoint,
+			region: "x"
+		});
+		const contentType = mime.getType(payload.fileName) || "application/octet-stream";
+		const extension = mime.getExtension(contentType) || "bin";
+		const fileName = payload.keepName ? payload.fileName : `${XRandom.cuid2()}.${extension}`;
+		const dir = this.dir ? `${this.dir}/` : "";
+		const command = new PutObjectCommand({
+			Bucket: this.options.bucket,
+			Key: `${dir}${fileName}`,
+			ContentType: contentType
+		});
+		return {
+			contentType,
+			uploadUrl: await getSignedUrl(s3Client, command, { expiresIn: ms(payload.ttl, true) }),
+			publicUrl: `${this.cdnUrl}/${dir}${fileName}`
+		};
+	}
+	/**
+	* 生成预签名 URL 并直接上传文件内容。
+	*
+	* 先复用 {@link XFileStore.getUploadUrl} 生成预签名地址（默认有效期
+	* 1 分钟），再以 PUT 方式将 `content` 上传到该地址，最后返回与
+	* `getUploadUrl` 一致的结果。
+	*
+	* @param payload 上传参数，见 {@link XFileStoreUploadPayload}。
+	* @returns 内容类型、预签名上传地址与公开访问地址。
+	*
+	* @example
+	* const result = await fileStore.upload({
+	*   fileName: 'avatar.png',
+	*   content: Buffer.from('...'),
+	* });
+	*/
+	async upload(payload) {
+		const res = await this.getUploadUrl({
+			fileName: payload.fileName,
+			ttl: ms("1m"),
+			keepName: payload.keepName
+		});
+		await xr.post({
+			url: res.uploadUrl,
+			method: "PUT",
+			headers: { "Content-Type": res.contentType },
+			data: payload.content
+		});
+		return res;
+	}
+};
+export { XFileStore };

package/lib/fs.d.mts

@@ -0,0 +1,111 @@
+import fs from "fs-extra";
+import { globby, globbyStream, globbySync } from "globby";
+/**
+ * 额外的文件系统辅助方法：
+ * - `getMimeType`：将扩展名 / 文件名 / MIME 字符串统一转换为 MIME 类型；
+ * - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名；
+ * - `globby` / `globbySync` / `globbyStream`：按 glob 模式查找文件与目录。
+ *
+ * 这些方法会被合并到 `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;
+  /**
+   * 按 glob 模式异步查找文件与目录。
+   *
+   * 转发自 `globby` 的异步版本，返回 `Promise`，适合 `await` 使用。
+   * 模式只支持正斜杠 `/`；拼接路径片段时请用 `path.posix.join`，
+   * Windows 上含反斜杠的模式会静默匹配失败。支持以 `!` 开头的取反
+   * 模式排除文件；当只传入取反模式（如 `['!*.json']`）时，会自动
+   * 前置一个匹配全部文件的兜底模式，再应用取反（可通过
+   * `options.expandNegationOnlyPatterns` 关闭）。
+   *
+   * @param patterns 一个 glob 模式或模式数组，支持取反排除。
+   * @param options 可选配置；除 `globby` 自身选项（如 `gitignore`、
+   *   `cwd`）外，其余选项透传给 `fast-glob`，默认在
+   *   `process.cwd()` 下查找。
+   * @returns 匹配到的路径数组；传入 `objectMode: true` 或
+   *   `stats: true` 时返回 `GlobEntry` 对象数组。
+   *
+   * @example
+   * await XFs.globby(['*.ts', '!*.test.ts']);
+   * // ['index.ts', 'utils.ts']
+   */
+  globby: typeof globby;
+  /**
+   * 按 glob 模式同步查找文件与目录。
+   *
+   * 转发自 `globby` 的同步版本，阻塞执行并直接返回结果，行为与
+   * `globby` 一致：模式只支持正斜杠 `/`，支持 `!` 取反排除，只传入
+   * 取反模式时自动前置匹配全部文件的兜底模式。
+   *
+   * @param patterns 一个 glob 模式或模式数组，支持取反排除。
+   * @param options 可选配置；除 `globby` 自身选项（如 `gitignore`、
+   *   `cwd`）外，其余选项透传给 `fast-glob`，默认在
+   *   `process.cwd()` 下查找。
+   * @returns 匹配到的路径数组；传入 `objectMode: true` 或
+   *   `stats: true` 时返回 `GlobEntry` 对象数组。
+   *
+   * @example
+   * XFs.globbySync(['*.ts', '!*.test.ts']);
+   * // ['index.ts', 'utils.ts']
+   */
+  globbySync: typeof globbySync;
+  /**
+   * 按 glob 模式流式查找文件与目录。
+   *
+   * 转发自 `globby` 的流式版本，返回可异步迭代的 `Readable` 流，
+   * 适合边匹配边处理，避免一次性在内存中持有全部结果。模式与选项
+   * 行为同 `globby`：只支持正斜杠 `/`，支持 `!` 取反排除。
+   *
+   * @param patterns 一个 glob 模式或模式数组，支持取反排除。
+   * @param options 可选配置；除 `globby` 自身选项外，其余选项
+   *   透传给 `fast-glob`，默认在 `process.cwd()` 下查找。
+   * @returns 逐个产出匹配路径的可读流；传入 `objectMode: true` 或
+   *   `stats: true` 时产出 `GlobEntry` 对象。
+   *
+   * @example
+   * for await (const path of XFs.globbyStream('*.ts')) {
+   *   console.log(path);
+   * }
+   */
+  globbyStream: typeof globbyStream;
+};
+/**
+ * `XFs` = `fs-extra` + 轻量文件类型工具。
+ *
+ * 这样调用方既可以直接使用完整的文件系统 API（如 `readFile`、`writeFile`），
+ * 也可以在同一对象上使用 `getMimeType` 和 `getExtension`。
+ */
+export declare const XFs: typeof fs & typeof XFsExtra;
+export {};

package/lib/fs.mjs

@@ -0,0 +1,127 @@
+import fs from "fs-extra";
+import mime from "mime";
+import { globby, globbyStream, globbySync } from "globby";
+// src/fs.ts
+/**
+* 额外的文件系统辅助方法：
+* - `getMimeType`：将扩展名 / 文件名 / MIME 字符串统一转换为 MIME 类型；
+* - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名；
+* - `globby` / `globbySync` / `globbyStream`：按 glob 模式查找文件与目录。
+*
+* 这些方法会被合并到 `XFs` 中，与 `fs-extra` 的 API 一起导出。
+*/
+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) {
+		const value = extOrName.trim();
+		if (!value) return "application/octet-stream";
+		if (value.includes("/")) return value;
+		return mime.getType(value) || "application/octet-stream";
+	},
+	/**
+	* 获取扩展名（不带 `.`）。
+	*
+	* 入参支持以下形式：
+	* - MIME 字符串：`image/png`、`text/plain`
+	* - 文件名：`file.txt`、`archive.tar.gz`
+	* - 扩展名：`json`
+	*
+	* 处理规则：
+	* 1. 去除首尾空白后，如果为空，返回空字符串；
+	* 2. 如果是 MIME 形式（包含 `/`），优先通过 `mime.getExtension` 推断，
+	*    若推断失败则退化为取 `/` 右侧片段；
+	* 3. 如果是文件名（包含 `.`），返回最后一段后缀；
+	* 4. 否则按扩展名/MIME 简写尝试 `mime.getExtension`，失败返回空字符串。
+	*/
+	getExtension(typeOrName) {
+		const value = typeOrName.trim();
+		if (!value) return "";
+		if (value.includes("/")) return mime.getExtension(value) || value.split("/").pop() || "";
+		if (value.includes(".")) return value.split(".").pop();
+		return mime.getExtension(value) || "";
+	},
+	/**
+	* 按 glob 模式异步查找文件与目录。
+	*
+	* 转发自 `globby` 的异步版本，返回 `Promise`，适合 `await` 使用。
+	* 模式只支持正斜杠 `/`；拼接路径片段时请用 `path.posix.join`，
+	* Windows 上含反斜杠的模式会静默匹配失败。支持以 `!` 开头的取反
+	* 模式排除文件；当只传入取反模式（如 `['!*.json']`）时，会自动
+	* 前置一个匹配全部文件的兜底模式，再应用取反（可通过
+	* `options.expandNegationOnlyPatterns` 关闭）。
+	*
+	* @param patterns 一个 glob 模式或模式数组，支持取反排除。
+	* @param options 可选配置；除 `globby` 自身选项（如 `gitignore`、
+	*   `cwd`）外，其余选项透传给 `fast-glob`，默认在
+	*   `process.cwd()` 下查找。
+	* @returns 匹配到的路径数组；传入 `objectMode: true` 或
+	*   `stats: true` 时返回 `GlobEntry` 对象数组。
+	*
+	* @example
+	* await XFs.globby(['*.ts', '!*.test.ts']);
+	* // ['index.ts', 'utils.ts']
+	*/
+	globby,
+	/**
+	* 按 glob 模式同步查找文件与目录。
+	*
+	* 转发自 `globby` 的同步版本，阻塞执行并直接返回结果，行为与
+	* `globby` 一致：模式只支持正斜杠 `/`，支持 `!` 取反排除，只传入
+	* 取反模式时自动前置匹配全部文件的兜底模式。
+	*
+	* @param patterns 一个 glob 模式或模式数组，支持取反排除。
+	* @param options 可选配置；除 `globby` 自身选项（如 `gitignore`、
+	*   `cwd`）外，其余选项透传给 `fast-glob`，默认在
+	*   `process.cwd()` 下查找。
+	* @returns 匹配到的路径数组；传入 `objectMode: true` 或
+	*   `stats: true` 时返回 `GlobEntry` 对象数组。
+	*
+	* @example
+	* XFs.globbySync(['*.ts', '!*.test.ts']);
+	* // ['index.ts', 'utils.ts']
+	*/
+	globbySync,
+	/**
+	* 按 glob 模式流式查找文件与目录。
+	*
+	* 转发自 `globby` 的流式版本，返回可异步迭代的 `Readable` 流，
+	* 适合边匹配边处理，避免一次性在内存中持有全部结果。模式与选项
+	* 行为同 `globby`：只支持正斜杠 `/`，支持 `!` 取反排除。
+	*
+	* @param patterns 一个 glob 模式或模式数组，支持取反排除。
+	* @param options 可选配置；除 `globby` 自身选项外，其余选项
+	*   透传给 `fast-glob`，默认在 `process.cwd()` 下查找。
+	* @returns 逐个产出匹配路径的可读流；传入 `objectMode: true` 或
+	*   `stats: true` 时产出 `GlobEntry` 对象。
+	*
+	* @example
+	* for await (const path of XFs.globbyStream('*.ts')) {
+	*   console.log(path);
+	* }
+	*/
+	globbyStream
+};
+/**
+* `XFs` = `fs-extra` + 轻量文件类型工具。
+*
+* 这样调用方既可以直接使用完整的文件系统 API（如 `readFile`、`writeFile`），
+* 也可以在同一对象上使用 `getMimeType` 和 `getExtension`。
+*/
+const XFs = {
+	...fs,
+	...XFsExtra
+};
+export { XFs };