@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/sms.mjs

@@ -0,0 +1,100 @@
+import * as TencentCloud from "tencentcloud-sdk-nodejs-sms";
+// src/sms.ts
+/**
+* 短信服务提供商。
+*/
+let SmsServiceProvider = /* @__PURE__ */ function(SmsServiceProvider) {
+	/** 腾讯云短信。 */
+	SmsServiceProvider["TencentCloud"] = "TencentCloud";
+	return SmsServiceProvider;
+}({});
+/**
+* 短信发送工具。
+*
+* 统一封装各云厂商的短信发送接口，将厂商原始返回转换为统一的
+* {@link XSmsSendResult}。当前支持腾讯云短信（
+* {@link SmsServiceProvider.TencentCloud}），后续可在此基础上扩展更多
+* 厂商。
+*
+* 腾讯云实现的几个关键点：
+* 1. 使用 `tencentcloud-sdk-nodejs-sms` 的 `v20210111` 版本客户端；
+* 2. 客户端构造必须显式传入 `region`（否则报错缺少 `Region` 参数），
+*    短信用途下该值不参与实际路由，统一使用 `ap-beijing`；
+* 3. 手机号规范化：以 `+` 开头视为 E.164 号码原样使用，否则自动补
+*    `+86` 前缀；
+* 4. 单次发送一个号码，取返回的 `SendStatusSet[0]` 作为发送结果，
+*    `Code === 'Ok'` 视为成功；若服务商未返回任何状态则抛出错误。
+*
+* @example
+* const sms = new XSms({
+*   provider: SmsServiceProvider.TencentCloud,
+*   secretId: 'your-secret-id',
+*   secretKey: 'your-secret-key',
+*   appId: '1400000000',
+* });
+*
+* const result = await sms.send({
+*   provider: SmsServiceProvider.TencentCloud,
+*   signature: '我的签名',
+*   templateId: '1234567',
+*   templateParamValues: ['123456', '5'],
+*   phoneNumber: '13800138000',
+* });
+* // result = { success: true, message: 'send success', smsId: '...' }
+*/
+var XSms = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 发送短信。
+	*
+	* 根据 `payload.provider` 路由到对应厂商：
+	* - {@link SmsServiceProvider.TencentCloud}：创建腾讯云短信客户端并调用
+	*   `SendSms`，将返回的首条发送状态映射为 {@link XSmsSendResult}；
+	* - 其他未知提供商：抛出错误。
+	*
+	* 手机号规范化：以 `+` 开头视为 E.164 号码原样使用，否则自动补
+	* `+86` 前缀后发送（与腾讯云「境内号码默认 +86」的规则一致）。
+	*
+	* @param payload 发送参数，见 {@link XSmsSendPayload}。
+	* @returns 发送结果，见 {@link XSmsSendResult}。
+	* @throws 当提供商不受支持，或服务商未返回任何发送状态时抛出错误。
+	*
+	* @example
+	* await sms.send({
+	*   provider: SmsServiceProvider.TencentCloud,
+	*   signature: '我的签名',
+	*   templateId: '1234567',
+	*   templateParamValues: ['123456'],
+	*   phoneNumber: '13800138000',
+	* });
+	*/
+	async send(payload) {
+		if (payload.provider === "TencentCloud") {
+			const SmsClient = TencentCloud.sms.v20210111.Client;
+			const sendStatus = (await new SmsClient({
+				region: "ap-beijing",
+				credential: {
+					secretId: this.options.secretId,
+					secretKey: this.options.secretKey
+				}
+			}).SendSms({
+				SmsSdkAppId: this.options.appId,
+				SignName: payload.signature,
+				TemplateId: payload.templateId,
+				TemplateParamSet: payload.templateParamValues,
+				PhoneNumberSet: [payload.phoneNumber[0] === "+" ? payload.phoneNumber : `+86${payload.phoneNumber}`]
+			})).SendStatusSet?.[0];
+			if (!sendStatus) throw new Error("腾讯云短信发送失败：服务商未返回发送状态");
+			return {
+				success: sendStatus.Code === "Ok",
+				message: sendStatus.Message,
+				smsId: sendStatus.SerialNo
+			};
+		}
+		throw new Error(`no sms provider: ${payload.provider}`);
+	}
+};
+export { SmsServiceProvider, XSms };

package/lib/task.d.mts

@@ -0,0 +1,37 @@
+/**
+ * 可复用任务基类。
+ *
+ * 封装了进程退出时的资源清理与退出码处理：
+ * 1. `run()` 启动前注册退出钩子，进程退出时自动调用 `dispose()` 释放资源；
+ * 2. `start()` 成功后以退出码 `0` 优雅退出；
+ * 3. `start()` 失败时记录错误日志，并以退出码 `1` 优雅退出。
+ *
+ * 使用方式：
+ * - 继承并实现 `start()`，将任务主逻辑放入其中；
+ * - 可选地覆写 `dispose()` 以释放连接、文件句柄等资源。
+ */
+export declare abstract class XTask {
+  /** 日志实例，子类可直接通过 `this.log` 输出日志。 */
+  log: import("consola").ConsolaInstance;
+  /**
+   * 任务主入口，子类必须实现。
+   *
+   * 成功 resolve 视为任务成功；抛错（reject）则触发错误日志与失败退出码。
+   */
+  abstract start(): Promise<void>;
+  /**
+   * 进程退出前的资源清理钩子，默认无操作。
+   *
+   * 子类可覆写以释放数据库连接、临时文件等资源；退出钩子最多等待 3000ms。
+   */
+  dispose(): Promise<void>;
+  /**
+   * 运行任务。
+   *
+   * 行为说明：
+   * 1. 注册退出钩子：进程退出时调用 `dispose()`，等待时长 3000ms；
+   * 2. 执行 `start()`，成功后以退出码 `0` 优雅退出；
+   * 3. 执行失败时记录错误并以退出码 `1` 优雅退出。
+   */
+  run(): Promise<never>;
+}

package/lib/task.mjs

@@ -0,0 +1,43 @@
+import { XDispose } from "./dispose.mjs";
+import { consola } from "consola";
+// src/task.ts
+/**
+* 可复用任务基类。
+*
+* 封装了进程退出时的资源清理与退出码处理：
+* 1. `run()` 启动前注册退出钩子，进程退出时自动调用 `dispose()` 释放资源；
+* 2. `start()` 成功后以退出码 `0` 优雅退出；
+* 3. `start()` 失败时记录错误日志，并以退出码 `1` 优雅退出。
+*
+* 使用方式：
+* - 继承并实现 `start()`，将任务主逻辑放入其中；
+* - 可选地覆写 `dispose()` 以释放连接、文件句柄等资源。
+*/
+var XTask = class {
+	/** 日志实例，子类可直接通过 `this.log` 输出日志。 */
+	log = consola;
+	/**
+	* 进程退出前的资源清理钩子，默认无操作。
+	*
+	* 子类可覆写以释放数据库连接、临时文件等资源；退出钩子最多等待 3000ms。
+	*/
+	async dispose() {}
+	/**
+	* 运行任务。
+	*
+	* 行为说明：
+	* 1. 注册退出钩子：进程退出时调用 `dispose()`，等待时长 3000ms；
+	* 2. 执行 `start()`，成功后以退出码 `0` 优雅退出；
+	* 3. 执行失败时记录错误并以退出码 `1` 优雅退出。
+	*/
+	run() {
+		XDispose.exit.add(() => this.dispose());
+		return this.start().then(() => {
+			process.exit(0);
+		}).catch((err) => {
+			consola.error(err);
+			process.exit(1);
+		});
+	}
+};
+export { XTask };

package/lib/text.d.mts

@@ -0,0 +1,84 @@
+export declare class XText {
+  private text;
+  /**
+   * 将字符串按“用户可见字符（grapheme）”分割为数组。
+   *
+   * 与 `text.split('')` 不同，这里会正确处理 Emoji、组合字符等场景，
+   * 例如 `👍🏽` 会被视为一个字符而不是多个 code unit。
+   *
+   * @see https://stackoverflow.com/a/71619350
+   */
+  static split(text: string): string[];
+  /**
+   * HTML 模板字符串辅助函数。
+   *
+   * 该方法不做任何转义，仅用于让书写 HTML 片段时有模板字符串提示。
+   * 若插值来自不可信输入，应在调用前自行做转义/清洗。
+   */
+  static html(literals: TemplateStringsArray, ...interpolations: unknown[]): string;
+  /**
+   * 提取 `start` 与 `end` 之间的内容。
+   *
+   * 规则：
+   * - 若 `start` 或 `end` 任一边界不存在，返回空字符串；
+   * - 仅提取从第一个 `start` 开始、到其后第一个 `end` 之前的内容；
+   * - 不包含边界本身。
+   */
+  static cut(text: string, start: string, end: string): string;
+  /**
+   * 移除全部空白字符（含空格、换行、制表符等）。
+   */
+  static stripWhitespace(text: string): string;
+  /**
+   * 移除首尾空白字符，保留中间内容。
+   */
+  static stripMarginWhitespace(text: string): string;
+  /**
+   * HTML 实体编码。
+   */
+  static encodeHtmlEntity(text: string): string;
+  /**
+   * HTML 实体解码。
+   */
+  static decodeHtmlEntity(text: string): string;
+  /**
+   * 移除 HTML 标签内容，包含 `script/style` 标签块。
+   *
+   * 注意：
+   * - 该方法面向轻量文本清洗，不是完整的 HTML 解析器；
+   * - 对复杂畸形 HTML 不能保证 100% 精确。
+   */
+  static stripHtml(text: string): string;
+  /**
+   * 创建一个可链式处理的文本实例。
+   */
+  constructor(text: string);
+  /**
+   * 链式版本：提取 `start` 与 `end` 之间的内容。
+   */
+  cut(start: string, end: string): this;
+  /**
+   * 链式版本：移除全部空白字符。
+   */
+  stripWhitespace(): this;
+  /**
+   * 链式版本：移除首尾空白字符。
+   */
+  stripMarginWhitespace(): this;
+  /**
+   * 链式版本：HTML 实体编码。
+   */
+  encodeHtmlEntity(): this;
+  /**
+   * 链式版本：HTML 实体解码。
+   */
+  decodeHtmlEntity(): this;
+  /**
+   * 链式版本：移除 HTML 代码。
+   */
+  stripHtml(): this;
+  /**
+   * 返回当前链式处理后的文本。
+   */
+  toString(): string;
+}

package/lib/text.mjs

@@ -0,0 +1,141 @@
+import { decode, encode } from "html-entities";
+// src/text.ts
+var XText = class XText {
+	text;
+	/**
+	* 将字符串按“用户可见字符（grapheme）”分割为数组。
+	*
+	* 与 `text.split('')` 不同，这里会正确处理 Emoji、组合字符等场景，
+	* 例如 `👍🏽` 会被视为一个字符而不是多个 code unit。
+	*
+	* @see https://stackoverflow.com/a/71619350
+	*/
+	static split(text) {
+		return [...new Intl.Segmenter().segment(text)].map((x) => x.segment);
+	}
+	/**
+	* HTML 模板字符串辅助函数。
+	*
+	* 该方法不做任何转义，仅用于让书写 HTML 片段时有模板字符串提示。
+	* 若插值来自不可信输入，应在调用前自行做转义/清洗。
+	*/
+	static html(literals, ...interpolations) {
+		let result = "";
+		for (let i = 0; i < interpolations.length; i++) {
+			result += literals[i];
+			result += interpolations[i];
+		}
+		result += literals[literals.length - 1];
+		return result;
+	}
+	/**
+	* 提取 `start` 与 `end` 之间的内容。
+	*
+	* 规则：
+	* - 若 `start` 或 `end` 任一边界不存在，返回空字符串；
+	* - 仅提取从第一个 `start` 开始、到其后第一个 `end` 之前的内容；
+	* - 不包含边界本身。
+	*/
+	static cut(text, start, end) {
+		const startIndex = text.indexOf(start);
+		if (startIndex < 0) return "";
+		const contentStartIndex = startIndex + start.length;
+		const endIndex = text.indexOf(end, contentStartIndex);
+		if (endIndex < 0) return "";
+		return text.slice(contentStartIndex, endIndex);
+	}
+	/**
+	* 移除全部空白字符（含空格、换行、制表符等）。
+	*/
+	static stripWhitespace(text) {
+		text = text.replace(/\s+/g, "");
+		return text;
+	}
+	/**
+	* 移除首尾空白字符，保留中间内容。
+	*/
+	static stripMarginWhitespace(text) {
+		text = text.trim();
+		return text;
+	}
+	/**
+	* HTML 实体编码。
+	*/
+	static encodeHtmlEntity(text) {
+		text = encode(text);
+		return text;
+	}
+	/**
+	* HTML 实体解码。
+	*/
+	static decodeHtmlEntity(text) {
+		text = decode(text);
+		return text;
+	}
+	/**
+	* 移除 HTML 标签内容，包含 `script/style` 标签块。
+	*
+	* 注意：
+	* - 该方法面向轻量文本清洗，不是完整的 HTML 解析器；
+	* - 对复杂畸形 HTML 不能保证 100% 精确。
+	*/
+	static stripHtml(text) {
+		text = text.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<\/?[^>]+>/g, "");
+		return text;
+	}
+	/**
+	* 创建一个可链式处理的文本实例。
+	*/
+	constructor(text) {
+		this.text = text;
+	}
+	/**
+	* 链式版本：提取 `start` 与 `end` 之间的内容。
+	*/
+	cut(start, end) {
+		this.text = XText.cut(this.text, start, end);
+		return this;
+	}
+	/**
+	* 链式版本：移除全部空白字符。
+	*/
+	stripWhitespace() {
+		this.text = XText.stripWhitespace(this.text);
+		return this;
+	}
+	/**
+	* 链式版本：移除首尾空白字符。
+	*/
+	stripMarginWhitespace() {
+		this.text = XText.stripMarginWhitespace(this.text);
+		return this;
+	}
+	/**
+	* 链式版本：HTML 实体编码。
+	*/
+	encodeHtmlEntity() {
+		this.text = XText.encodeHtmlEntity(this.text);
+		return this;
+	}
+	/**
+	* 链式版本：HTML 实体解码。
+	*/
+	decodeHtmlEntity() {
+		this.text = XText.decodeHtmlEntity(this.text);
+		return this;
+	}
+	/**
+	* 链式版本：移除 HTML 代码。
+	*/
+	stripHtml() {
+		this.text = XText.stripHtml(this.text);
+		return this;
+	}
+	/**
+	* 返回当前链式处理后的文本。
+	*/
+	toString() {
+		return this.text;
+	}
+};
+export { XText };

package/lib/yaml.d.mts

@@ -0,0 +1,51 @@
+/**
+ * 封装常用 YAML 文本处理逻辑，统一提供解析、序列化、文件读写入口。
+ *
+ * 设计目标：
+ * - 让调用方无需直接接触 `yaml` 依赖细节；
+ * - 统一使用 UTF-8 文本读取/写入；
+ * - 通过 `blockQuote: 'literal'` 保持多行文本块更稳定的输出格式，避免
+ *   长文本在 YAML 中被错误地折叠或渲染为普通单行字符串。
+ *
+ * 典型用法：
+ * - `const cfg = XYaml.parse<{ name: string }>(content)`
+ * - `await XYaml.write('/tmp/app.yaml', { name: 'demo' })`
+ */
+export declare class XYaml {
+  /**
+   * 解析 YAML 文本为目标类型。
+   *
+   * 适用场景包括配置文件、表单内容、轻量结构化描述等。由于 YAML 语法
+   * 允许解析为对象、数组、布尔值、数字、字符串等原始值，因此这里使用
+   * 泛型让调用方在类型层面明确期望值。
+   *
+   * 例子：
+   * ```ts
+   * const config = XYaml.parse<{ name: string; port: number }>(`\nname: demo\nport: 3000\n`);
+   * ```
+   */
+  static parse<T>(value: string): T;
+  /**
+   * 将任意值转换成 YAML 文本。
+   *
+   * 这里固定使用 `blockQuote: 'literal'`，这样当值中包含多行字符串时，
+   * 输出会优先采用 `|` 形式的 literal block，与普通单行折叠输出相比更
+   * 稳定，也更符合配置文件/说明文档场景的阅读习惯。
+   */
+  static stringify(value: unknown): string;
+  /**
+   * 读取 YAML 文件并立即解析为指定类型。
+   *
+   * 读取时使用 UTF-8 编码，适合配置文件、模板文件或脚本状态容器。若
+   * 文件为空，`yaml.parse` 可能返回 `null`，调用方需要按业务规则处理。
+   */
+  static read<T>(file: string): Promise<T>;
+  /**
+   * 将对象写入 YAML 文件。
+   *
+   * 这里不额外指定缩进或换行策略，使用 `stringify` 的统一默认行为；
+   * 一旦调用方传入 `undefined`，`yaml.stringify` 会输出空文档，调用方应在
+   * 业务层避免该情况，或在必要时进行显式校验。
+   */
+  static write(file: string, value: unknown): Promise<void>;
+}

package/lib/yaml.mjs

@@ -0,0 +1,64 @@
+import * as fs from "node:fs";
+import yaml from "yaml";
+// src/yaml.ts
+/**
+* 封装常用 YAML 文本处理逻辑，统一提供解析、序列化、文件读写入口。
+*
+* 设计目标：
+* - 让调用方无需直接接触 `yaml` 依赖细节；
+* - 统一使用 UTF-8 文本读取/写入；
+* - 通过 `blockQuote: 'literal'` 保持多行文本块更稳定的输出格式，避免
+*   长文本在 YAML 中被错误地折叠或渲染为普通单行字符串。
+*
+* 典型用法：
+* - `const cfg = XYaml.parse<{ name: string }>(content)`
+* - `await XYaml.write('/tmp/app.yaml', { name: 'demo' })`
+*/
+var XYaml = class XYaml {
+	/**
+	* 解析 YAML 文本为目标类型。
+	*
+	* 适用场景包括配置文件、表单内容、轻量结构化描述等。由于 YAML 语法
+	* 允许解析为对象、数组、布尔值、数字、字符串等原始值，因此这里使用
+	* 泛型让调用方在类型层面明确期望值。
+	*
+	* 例子：
+	* ```ts
+	* const config = XYaml.parse<{ name: string; port: number }>(`\nname: demo\nport: 3000\n`);
+	* ```
+	*/
+	static parse(value) {
+		return yaml.parse(value);
+	}
+	/**
+	* 将任意值转换成 YAML 文本。
+	*
+	* 这里固定使用 `blockQuote: 'literal'`，这样当值中包含多行字符串时，
+	* 输出会优先采用 `|` 形式的 literal block，与普通单行折叠输出相比更
+	* 稳定，也更符合配置文件/说明文档场景的阅读习惯。
+	*/
+	static stringify(value) {
+		return yaml.stringify(value, { blockQuote: "literal" });
+	}
+	/**
+	* 读取 YAML 文件并立即解析为指定类型。
+	*
+	* 读取时使用 UTF-8 编码，适合配置文件、模板文件或脚本状态容器。若
+	* 文件为空，`yaml.parse` 可能返回 `null`，调用方需要按业务规则处理。
+	*/
+	static async read(file) {
+		const value = await fs.promises.readFile(file, "utf8");
+		return XYaml.parse(value);
+	}
+	/**
+	* 将对象写入 YAML 文件。
+	*
+	* 这里不额外指定缩进或换行策略，使用 `stringify` 的统一默认行为；
+	* 一旦调用方传入 `undefined`，`yaml.stringify` 会输出空文档，调用方应在
+	* 业务层避免该情况，或在必要时进行显式校验。
+	*/
+	static async write(file, value) {
+		await fs.promises.writeFile(file, XYaml.stringify(value));
+	}
+};
+export { XYaml };