@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/captcha.d.mts

@@ -0,0 +1,259 @@
+import { XCache } from "./cache.mjs";
+import { MsValue } from "vtils";
+/**
+ * {@link XCaptcha} 的配置项。
+ */
+export interface XCaptchaOptions {
+  /**
+   * 缓存服务实例。
+   *
+   * 用于保存与读取验证码数据：生成时写入，校验时按 token 读取。建议为验证码
+   * 单独使用一个 {@link XCache} 实例，便于统一管理前缀、TTL 与序列化方式，
+   * 避免与其他业务缓存相互干扰。
+   */
+  cache: XCache;
+}
+/**
+ * 验证码字符集。
+ *
+ * 由若干字符段组合而成，各字符段含义：
+ * - `0`：数字 0-9；
+ * - `1`：数字 1-9（不含 0）；
+ * - `a` / `z`：小写字母 a-z；
+ * - `A` / `Z`：大写字母 A-Z。
+ *
+ * 完整取值：
+ * - `09`：0-9；
+ * - `19`：1-9；
+ * - `az`：小写字母；
+ * - `AZ`：大写字母；
+ * - `aZ`：小写 + 大写字母；
+ * - `0z`：0-9 + 小写字母；
+ * - `0Z`：0-9 + 小写 + 大写字母；
+ * - `1z`：1-9 + 小写字母；
+ * - `1Z`：1-9 + 小写 + 大写字母。
+ */
+export type XCaptchaGenerateCharset = '09' | '19' | 'az' | 'AZ' | 'aZ' | '0z' | '0Z' | '1z' | '1Z';
+/**
+ * {@link XCaptcha.generate} 与 {@link XCaptcha.generateDataUrl} 的入参。
+ */
+export interface XCaptchaGeneratePayload<T> {
+  /**
+   * 场景值。
+   *
+   * 用于区分验证码用途，防止后台验证码图片登录时误用其他场景（如短信）
+   * 下生成的验证码。校验时场景值不一致会直接判定失败。
+   */
+  scene: string;
+  /**
+   * 验证码长度，即生成的字符个数，应为正整数。
+   */
+  size: number;
+  /**
+   * 验证码存活时长。
+   *
+   * 与 `vtils` 的 `ms` 解析规则一致，可为毫秒数或时间字符串
+   * （如 `'5m'`、`'10s'`）。到期后验证码自动失效。
+   */
+  ttl: MsValue;
+  /**
+   * 字符集，决定验证码由哪些字符组成。
+   */
+  charset: XCaptchaGenerateCharset;
+  /**
+   * 可重试次数。
+   *
+   * - 大于 0：每次校验（无论成败）扣减一次，扣到 0 后验证码失效；
+   * - 等于 0：首次校验（无论成败）后即失效；
+   * - 缺省为 0。
+   */
+  retryCount?: number;
+  /**
+   * 其他附加信息。
+   *
+   * 随验证码一起写入缓存，校验时可通过
+   * {@link XCaptchaVerifyOptions.extra} 自定义比对逻辑。
+   */
+  extra?: T;
+}
+/**
+ * {@link XCaptcha.generate} 的返回结果。
+ */
+export interface XCaptchaGenerateResult {
+  /**
+   * 校验凭证。
+   *
+   * 随机生成且 URL 友好，用于在缓存中定位验证码；校验时需原样传回。
+   */
+  token: string;
+  /**
+   * 生成的验证码明文。
+   *
+   * 主要用于调试或日志；生产环境通常只向客户端返回图片
+   * （见 {@link XCaptchaGenerateDataUrlResult.dataUrl}），不应回传明文。
+   */
+  code: string;
+}
+/**
+ * {@link XCaptcha.generateDataUrl} 的返回结果。
+ */
+export interface XCaptchaGenerateDataUrlResult {
+  /**
+   * 校验凭证，语义同 {@link XCaptchaGenerateResult.token}。
+   */
+  token: string;
+  /**
+   * 生成的验证码明文，语义同 {@link XCaptchaGenerateResult.code}。
+   */
+  code: string;
+  /**
+   * 验证码图片的 Data URL。
+   *
+   * 形如 `data:image/svg+xml,...`，可直接作为 `<img>` 的 `src` 展示。
+   */
+  dataUrl: string;
+}
+/**
+ * {@link XCaptcha.verify} 的入参。
+ */
+export interface XCaptchaVerifyOptions<T> {
+  /**
+   * 校验凭证，来自生成结果中的 `token`。
+   */
+  token: string;
+  /**
+   * 待校验的验证码明文。
+   */
+  code: string;
+  /**
+   * 场景值，须与生成时一致。
+   */
+  scene: string;
+  /**
+   * 附加信息比对函数。
+   *
+   * 接收生成时存入缓存的 `extra`，返回是否通过。仅在场景值与验证码均通过
+   * 后才会执行；缺省时不校验附加信息。若生成时未提供 `extra`，回调入参为
+   * `undefined`。
+   */
+  extra?: (extra: T) => boolean;
+}
+/**
+ * 验证码生成与校验工具。
+ *
+ * 提供两种生成方式：
+ * - {@link XCaptcha.generate}：仅生成验证码文本，适合短信、邮件等无需图片的
+ *   场景；
+ * - {@link XCaptcha.generateDataUrl}：生成验证码文本与 SVG 图片 Data URL，
+ *   适合 Web 页面图片验证码。
+ *
+ * 生成时按指定字符集与长度随机拼接验证码，并将验证码明文、场景值、可重试
+ * 次数与附加信息一并写入缓存；校验时依次检查：
+ * 1. token 是否存在；
+ * 2. 场景值是否一致；
+ * 3. 验证码是否一致（大小写不敏感）；
+ * 4. 附加信息是否通过（可选）。
+ *
+ * 任意一项不通过即返回 `false`，且每次校验都会消耗一次重试次数或使验证码
+ * 失效（见 {@link XCaptchaGeneratePayload.retryCount}）。
+ *
+ * @example
+ * const captcha = new XCaptcha({ cache });
+ *
+ * const { token, code, dataUrl } = await captcha.generateDataUrl({
+ *   scene: 'login',
+ *   size: 4,
+ *   ttl: '5m',
+ *   charset: '09',
+ *   retryCount: 3,
+ * });
+ * // dataUrl 形如 'data:image/svg+xml,...'
+ *
+ * await captcha.verify({ token, code, scene: 'login' });
+ * // true
+ */
+export declare class XCaptcha {
+  private readonly cache;
+  /**
+   * 创建验证码工具实例。
+   *
+   * @param options 配置项，包含缓存服务实例。
+   */
+  constructor(options: XCaptchaOptions);
+  /**
+   * 各字符集对应的字符数组。
+   *
+   * 键为 {@link XCaptchaGenerateCharset} 取值，值为可从中随机取样的字符列表；
+   * `generate` 从中逐个 `sample`，`generateDataUrl` 则将其拼接为 svg-captcha
+   * 的 `charPreset`。
+   */
+  private charsetMap;
+  /**
+   * 生成验证码文本。
+   *
+   * 从 {@link XCaptchaGeneratePayload.charset} 对应的字符集中随机抽取
+   * `size` 个字符组成验证码，与场景值、可重试次数、附加信息一起写入缓存，
+   * 并返回缓存 token 与验证码明文。
+   *
+   * 适用于短信、邮件等不需要图片的验证码场景；若需要图片请使用
+   * {@link XCaptcha.generateDataUrl}。
+   *
+   * @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+   * @returns 包含 `token` 与验证码明文 `code` 的结果对象。
+   *
+   * @example
+   * const { token, code } = await captcha.generate({
+   *   scene: 'sms-login',
+   *   size: 6,
+   *   ttl: '5m',
+   *   charset: '09',
+   * });
+   * // token 形如 'X__xxxx'，code 为 6 位数字
+   */
+  generate<T extends Record<string, any>>(payload: XCaptchaGeneratePayload<T>): Promise<XCaptchaGenerateResult>;
+  /**
+   * 生成验证码文本与 SVG 图片 Data URL。
+   *
+   * 使用 svg-captcha 依据 {@link XCaptchaGeneratePayload.charset} 与 `size`
+   * 生成图片，并将验证码文本按与 {@link XCaptcha.generate} 相同的规则写入
+   * 缓存；随后将 SVG 转为 Data URL 一并返回。
+   *
+   * 适用于 Web 页面图片验证码，`dataUrl` 可直接作为 `<img>` 的 `src`。
+   *
+   * @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+   * @returns 包含 `token`、验证码明文 `code` 与图片 `dataUrl` 的结果对象。
+   *
+   * @example
+   * const { token, dataUrl } = await captcha.generateDataUrl({
+   *   scene: 'login',
+   *   size: 4,
+   *   ttl: '5m',
+   *   charset: 'aZ',
+   * });
+   * // dataUrl 形如 'data:image/svg+xml,...'
+   */
+  generateDataUrl<T extends Record<string, any>>(payload: XCaptchaGeneratePayload<T>): Promise<XCaptchaGenerateDataUrlResult>;
+  /**
+   * 校验验证码。
+   *
+   * 按顺序执行以下检查，任意一项不通过即返回 `false`：
+   * 1. token 存在：缓存中找不到 token 对应数据时直接失败；
+   * 2. 场景一致：`scene` 与生成时不一致时失败，防止跨场景误用；
+   * 3. 验证码一致：`code` 与生成时一致（大小写不敏感）；
+   * 4. 附加信息：提供了 `extra` 时执行其回调，返回 `false` 则失败。
+   *
+   * 注意：每次校验（无论最终是否通过）都会消耗一次重试次数——可重试次数
+   * 大于 0 时扣减并写回缓存，等于 0 时直接删除缓存，此后该 token 不可再用。
+   *
+   * @param options 校验参数，包含 token、验证码明文、场景值与可选的附加信息
+   *   比对函数。
+   * @returns 校验是否通过。
+   *
+   * @example
+   * await captcha.verify({ token, code, scene: 'login' });
+   * // true
+   * await captcha.verify({ token, code, scene: 'login' });
+   * // false：该 token 已失效
+   */
+  verify<T extends Record<string, any>>(options: XCaptchaVerifyOptions<T>): Promise<boolean>;
+}

package/lib/captcha.mjs

@@ -0,0 +1,174 @@
+import { sample } from "vtils";
+import svgToDataUrl from "mini-svg-data-uri";
+import svgCaptcha from "svg-captcha";
+// src/captcha.ts
+/**
+* 验证码生成与校验工具。
+*
+* 提供两种生成方式：
+* - {@link XCaptcha.generate}：仅生成验证码文本，适合短信、邮件等无需图片的
+*   场景；
+* - {@link XCaptcha.generateDataUrl}：生成验证码文本与 SVG 图片 Data URL，
+*   适合 Web 页面图片验证码。
+*
+* 生成时按指定字符集与长度随机拼接验证码，并将验证码明文、场景值、可重试
+* 次数与附加信息一并写入缓存；校验时依次检查：
+* 1. token 是否存在；
+* 2. 场景值是否一致；
+* 3. 验证码是否一致（大小写不敏感）；
+* 4. 附加信息是否通过（可选）。
+*
+* 任意一项不通过即返回 `false`，且每次校验都会消耗一次重试次数或使验证码
+* 失效（见 {@link XCaptchaGeneratePayload.retryCount}）。
+*
+* @example
+* const captcha = new XCaptcha({ cache });
+*
+* const { token, code, dataUrl } = await captcha.generateDataUrl({
+*   scene: 'login',
+*   size: 4,
+*   ttl: '5m',
+*   charset: '09',
+*   retryCount: 3,
+* });
+* // dataUrl 形如 'data:image/svg+xml,...'
+*
+* await captcha.verify({ token, code, scene: 'login' });
+* // true
+*/
+var XCaptcha = class {
+	cache;
+	/**
+	* 创建验证码工具实例。
+	*
+	* @param options 配置项，包含缓存服务实例。
+	*/
+	constructor(options) {
+		this.cache = options.cache;
+	}
+	/**
+	* 各字符集对应的字符数组。
+	*
+	* 键为 {@link XCaptchaGenerateCharset} 取值，值为可从中随机取样的字符列表；
+	* `generate` 从中逐个 `sample`，`generateDataUrl` 则将其拼接为 svg-captcha
+	* 的 `charPreset`。
+	*/
+	charsetMap = {
+		"09": "0123456789".split(""),
+		"19": "123456789".split(""),
+		az: "abcdefghijklmnopqrstuvwxyz".split(""),
+		AZ: "ABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		aZ: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		"0z": "0123456789abcdefghijklmnopqrstuvwxyz".split(""),
+		"0Z": "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		"1z": "123456789abcdefghijklmnopqrstuvwxyz".split(""),
+		"1Z": "123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split("")
+	};
+	/**
+	* 生成验证码文本。
+	*
+	* 从 {@link XCaptchaGeneratePayload.charset} 对应的字符集中随机抽取
+	* `size` 个字符组成验证码，与场景值、可重试次数、附加信息一起写入缓存，
+	* 并返回缓存 token 与验证码明文。
+	*
+	* 适用于短信、邮件等不需要图片的验证码场景；若需要图片请使用
+	* {@link XCaptcha.generateDataUrl}。
+	*
+	* @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+	* @returns 包含 `token` 与验证码明文 `code` 的结果对象。
+	*
+	* @example
+	* const { token, code } = await captcha.generate({
+	*   scene: 'sms-login',
+	*   size: 6,
+	*   ttl: '5m',
+	*   charset: '09',
+	* });
+	* // token 形如 'X__xxxx'，code 为 6 位数字
+	*/
+	async generate(payload) {
+		const chars = this.charsetMap[payload.charset];
+		let code = "";
+		for (let i = 0; i < payload.size; i++) code += sample(chars);
+		return {
+			token: await this.cache.save({
+				code,
+				scene: payload.scene,
+				retryCount: payload.retryCount ?? 0,
+				extra: payload.extra
+			}, payload.ttl),
+			code
+		};
+	}
+	/**
+	* 生成验证码文本与 SVG 图片 Data URL。
+	*
+	* 使用 svg-captcha 依据 {@link XCaptchaGeneratePayload.charset} 与 `size`
+	* 生成图片，并将验证码文本按与 {@link XCaptcha.generate} 相同的规则写入
+	* 缓存；随后将 SVG 转为 Data URL 一并返回。
+	*
+	* 适用于 Web 页面图片验证码，`dataUrl` 可直接作为 `<img>` 的 `src`。
+	*
+	* @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+	* @returns 包含 `token`、验证码明文 `code` 与图片 `dataUrl` 的结果对象。
+	*
+	* @example
+	* const { token, dataUrl } = await captcha.generateDataUrl({
+	*   scene: 'login',
+	*   size: 4,
+	*   ttl: '5m',
+	*   charset: 'aZ',
+	* });
+	* // dataUrl 形如 'data:image/svg+xml,...'
+	*/
+	async generateDataUrl(payload) {
+		const { text: code, data: svg } = svgCaptcha.create({
+			size: payload.size,
+			charPreset: this.charsetMap[payload.charset].join("")
+		});
+		return {
+			token: await this.cache.save({
+				code,
+				scene: payload.scene,
+				retryCount: payload.retryCount ?? 0,
+				extra: payload.extra
+			}, payload.ttl),
+			code,
+			dataUrl: svgToDataUrl(svg)
+		};
+	}
+	/**
+	* 校验验证码。
+	*
+	* 按顺序执行以下检查，任意一项不通过即返回 `false`：
+	* 1. token 存在：缓存中找不到 token 对应数据时直接失败；
+	* 2. 场景一致：`scene` 与生成时不一致时失败，防止跨场景误用；
+	* 3. 验证码一致：`code` 与生成时一致（大小写不敏感）；
+	* 4. 附加信息：提供了 `extra` 时执行其回调，返回 `false` 则失败。
+	*
+	* 注意：每次校验（无论最终是否通过）都会消耗一次重试次数——可重试次数
+	* 大于 0 时扣减并写回缓存，等于 0 时直接删除缓存，此后该 token 不可再用。
+	*
+	* @param options 校验参数，包含 token、验证码明文、场景值与可选的附加信息
+	*   比对函数。
+	* @returns 校验是否通过。
+	*
+	* @example
+	* await captcha.verify({ token, code, scene: 'login' });
+	* // true
+	* await captcha.verify({ token, code, scene: 'login' });
+	* // false：该 token 已失效
+	*/
+	async verify(options) {
+		const expected = await this.cache.get(options.token);
+		if (expected == null) return false;
+		if (expected.retryCount === 0) await this.cache.remove(options.token);
+		else {
+			expected.retryCount--;
+			const ttl = await this.cache.ttl(options.token);
+			await this.cache.set(options.token, expected, ttl);
+		}
+		return expected.scene === options.scene && options.code.toLowerCase() === expected.code.toLowerCase() && (options.extra ? options.extra(expected.extra) : true);
+	}
+};
+export { XCaptcha };

package/lib/case.d.mts

@@ -0,0 +1,184 @@
+import { Options, PascalCaseOptions } from "change-case";
+/**
+ * `XCase.camel` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `PascalCaseOptions`，支持
+ * `mergeAmbiguousCharacters` 等全部配置项，属性语义与默认行为
+ * 同 change-case，调用时原样透传。
+ */
+export interface XCaseCamelOptions extends PascalCaseOptions {}
+/**
+ * `XCase.pascal` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `PascalCaseOptions`，支持
+ * `mergeAmbiguousCharacters` 等全部配置项，属性语义与默认行为
+ * 同 change-case，调用时原样透传。
+ */
+export interface XCasePascalOptions extends PascalCaseOptions {}
+/**
+ * `XCase.pascalSnake` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCasePascalSnakeOptions extends Options {}
+/**
+ * `XCase.capital` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseCapitalOptions extends Options {}
+/**
+ * `XCase.constant` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseConstantOptions extends Options {}
+/**
+ * `XCase.dot` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseDotOptions extends Options {}
+/**
+ * `XCase.kebab` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseKebabOptions extends Options {}
+/**
+ * `XCase.path` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCasePathOptions extends Options {}
+/**
+ * `XCase.sentence` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseSentenceOptions extends Options {}
+/**
+ * `XCase.snake` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseSnakeOptions extends Options {}
+/**
+ * `XCase.train` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseTrainOptions extends Options {}
+/**
+ * 字符串大小写风格转换工具。
+ *
+ * 所有方法均委托给 `change-case` 包实现，方法名去掉了原函数名的 `Case`
+ * 后缀（如 `camelCase` → `camel`，`pascalSnakeCase` → `pascalSnake`）。
+ *
+ * 各方法的 `options` 参数会原样透传给 `change-case` 对应函数，
+ * 类型分别为导出的 `XCaseCamelOptions`、`XCasePascalOptions`、
+ * `XCasePascalSnakeOptions`、`XCaseCapitalOptions`、`XCaseConstantOptions`、
+ * `XCaseDotOptions`、`XCaseKebabOptions`、`XCasePathOptions`、
+ * `XCaseSentenceOptions`、`XCaseSnakeOptions`、`XCaseTrainOptions`，
+ * 可配置 `locale`、`delimiter`、`split` 等（`camel`/`pascal` 额外支持
+ * `mergeAmbiguousCharacters`）。
+ *
+ * 以 `Hello World` 为例，各方法的输出：
+ * - `camel` → `helloWorld`
+ * - `pascal` → `HelloWorld`
+ * - `pascalSnake` → `Hello_World`
+ * - `capital` → `Hello World`
+ * - `constant` → `HELLO_WORLD`
+ * - `dot` → `hello.world`
+ * - `kebab` → `hello-world`
+ * - `path` → `hello/world`
+ * - `sentence` → `Hello world`
+ * - `snake` → `hello_world`
+ * - `train` → `Hello-World`
+ */
+export declare class XCase {
+  /**
+   * 转换为 camelCase（小驼峰）命名。
+   *
+   * @example XCase.camel('Hello World') // 'helloWorld'
+   */
+  static camel(text: string, options?: XCaseCamelOptions): string;
+  /**
+   * 转换为 PascalCase（大驼峰）命名。
+   *
+   * @example XCase.pascal('hello world') // 'HelloWorld'
+   */
+  static pascal(text: string, options?: XCasePascalOptions): string;
+  /**
+   * 转换为 Pascal_Snake_Case（大驼峰 + 下划线）命名。
+   *
+   * @example XCase.pascalSnake('hello world') // 'Hello_World'
+   */
+  static pascalSnake(text: string, options?: XCasePascalSnakeOptions): string;
+  /**
+   * 转换为 Capital Case（首字母大写的空格分隔）命名。
+   *
+   * @example XCase.capital('hello world') // 'Hello World'
+   */
+  static capital(text: string, options?: XCaseCapitalOptions): string;
+  /**
+   * 转换为 CONSTANT_CASE（全大写下划线）命名。
+   *
+   * @example XCase.constant('hello world') // 'HELLO_WORLD'
+   */
+  static constant(text: string, options?: XCaseConstantOptions): string;
+  /**
+   * 转换为 dot.case（点号分隔）命名。
+   *
+   * @example XCase.dot('hello world') // 'hello.world'
+   */
+  static dot(text: string, options?: XCaseDotOptions): string;
+  /**
+   * 转换为 kebab-case（短横线分隔）命名。
+   *
+   * @example XCase.kebab('Hello World') // 'hello-world'
+   */
+  static kebab(text: string, options?: XCaseKebabOptions): string;
+  /**
+   * 转换为 path/case（斜杠分隔）命名。
+   *
+   * @example XCase.path('hello world') // 'hello/world'
+   */
+  static path(text: string, options?: XCasePathOptions): string;
+  /**
+   * 转换为 Sentence case（首字母大写的句子）命名。
+   *
+   * @example XCase.sentence('hello world') // 'Hello world'
+   */
+  static sentence(text: string, options?: XCaseSentenceOptions): string;
+  /**
+   * 转换为 snake_case（小写下划线）命名。
+   *
+   * @example XCase.snake('Hello World') // 'hello_world'
+   */
+  static snake(text: string, options?: XCaseSnakeOptions): string;
+  /**
+   * 转换为 Train-Case（短横线分隔、各单词首字母大写）命名。
+   *
+   * @example XCase.train('hello world') // 'Hello-World'
+   */
+  static train(text: string, options?: XCaseTrainOptions): string;
+}