@jayfong/x-utils 3.3.0 → 3.4.0

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

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