@jayfong/x-utils 3.3.0 → 3.4.0

package/lib/fs.d.mts

@@ -1,8 +1,10 @@
 import fs from "fs-extra";
+import { globby, globbyStream, globbySync } from "globby";
 /**
- * 额外的文件类型辅助方法：
+ * 额外的文件系统辅助方法：
  * - `getMimeType`：将扩展名 / 文件名 / MIME 字符串统一转换为 MIME 类型；
- * - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名。
+ * - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名；
+ * - `globby` / `globbySync` / `globbyStream`：按 glob 模式查找文件与目录。
  *
  * 这些方法会被合并到 `XFs` 中，与 `fs-extra` 的 API 一起导出。
  */
@@ -38,6 +40,66 @@ declare const XFsExtra: {
    * 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` + 轻量文件类型工具。

package/lib/fs.mjs

@@ -1,10 +1,12 @@
 import fs from "fs-extra";
 import mime from "mime";
+import { globby, globbyStream, globbySync } from "globby";
 // src/fs.ts
 /**
-* 额外的文件类型辅助方法：
+* 额外的文件系统辅助方法：
 * - `getMimeType`：将扩展名 / 文件名 / MIME 字符串统一转换为 MIME 类型；
-* - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名。
+* - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名；
+* - `globby` / `globbySync` / `globbyStream`：按 glob 模式查找文件与目录。
 *
 * 这些方法会被合并到 `XFs` 中，与 `fs-extra` 的 API 一起导出。
 */
@@ -50,7 +52,67 @@ const XFsExtra = {
 		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` + 轻量文件类型工具。

package/lib/html.d.mts

@@ -0,0 +1,103 @@
+import { HTMLElement } from "node-html-parser";
+/**
+ * HTML 转义与反转义工具。
+ *
+ * 基于 `fast-escape-html` 实现，用于在把不可信文本嵌入 HTML 前进行转义，
+ * 或将已转义的 HTML 实体还原为原始字符，避免标签错乱与 XSS 注入。
+ *
+ * 转义字符对照：
+ * | 原字符 | 转义结果 |
+ * | ------ | -------- |
+ * | `&`    | `&`  |
+ * | `<`    | `&lt;`   |
+ * | `>`    | `&gt;`   |
+ * | `"`    | `&quot;` |
+ * | `'`    | `&#39;`  |
+ *
+ * @example
+ * const html = new XHtml();
+ * html.escape('<a href="x">\'</a>') // '&lt;a href=&quot;x&quot;&gt;&#39;&lt;/a&gt;'
+ * html.unescape('&lt;a&amp;b&gt;') // '<a&b>'
+ *
+ * @remarks
+ * - `escape` 是无状态转义：已含实体的文本会再次被转义（如 `&lt;` →
+ *   `&amp;lt;`），因此不要对同一段文本重复调用；
+ * - `unescape` 只还原本工具转义出的实体（`&amp;`、`&lt;`、`&gt;`、
+ *   `&quot;`、`&#39;`、`&apos;`），不处理 `&nbsp;`、`&copy;` 等其它命名
+ *   实体，也不处理 `&#65;`、`&#x41;` 这类十进制/十六进制数字实体；
+ * - 本工具面向 HTML 文本节点/属性值的转义场景，不负责 URL 编码，也不保证
+ *   脚本、样式等非 HTML 上下文的安全。
+ */
+export declare class XHtml {
+  /**
+   * 将字符串转义为可安全嵌入 HTML 的实体文本。
+   *
+   * 处理规则：
+   * - `&`、`<`、`>`、`"`、`'` 会被替换为对应实体；
+   * - 其余字符（中文、字母、数字、换行、空白等）原样保留；
+   * - 空字符串返回空字符串。
+   *
+   * 边界与意外场景：
+   * - 已转义文本会被二次转义（如 `&lt;` → `&amp;lt;`），调用方需自行保证
+   *   同一段文本只转义一次。
+   *
+   * @param html 待转义的原始字符串。
+   * @returns 转义后的字符串。
+   *
+   * @example
+   * new XHtml().escape('<a href="x">') // '&lt;a href=&quot;x&quot;&gt;'
+   * new XHtml().escape('') // ''
+   */
+  static escape(html: string): string;
+  /**
+   * 将 HTML 实体还原为原始字符。
+   *
+   * 处理规则：
+   * - 还原 `&amp;`、`&lt;`、`&gt;`、`&quot;`、`&#39;`、`&apos;`；
+   * - 未匹配到上述实体的文本原样保留；
+   * - 空字符串返回空字符串。
+   *
+   * 边界与意外场景：
+   * - `&nbsp;`、`&copy;` 等其它命名实体不会被还原；
+   * - `&#65;`、`&#x41;` 等数字实体不会被还原；
+   * - 反转义是一次性替换而非循环展开，例如 `&amp;amp;` 还原后得到 `&amp;`
+   *   而不会继续还原成 `&`。
+   *
+   * @param html 含 HTML 实体的字符串。
+   * @returns 还原后的字符串。
+   *
+   * @example
+   * new XHtml().unescape('&lt;a&amp;b&gt;') // '<a&b>'
+   * new XHtml().unescape('&apos;ok&apos;') // "'ok'"
+   * new XHtml().unescape('') // ''
+   */
+  static unescape(html: string): string;
+  /**
+   * 将 HTML 字符串解析为可查询的节点树。
+   *
+   * 基于 `node-html-parser` 实现，返回的根节点是一个“文档容器”：
+   * - 根节点自身不携带标签名（`tagName` / `rawTagName` 为 `null`），
+   *   真正解析出的元素位于 `childNodes` 中；
+   * - 同时支持完整文档与 HTML 片段（多个顶层节点）；
+   * - 元素节点与文本节点会被保留，注释节点默认被丢弃；
+   * - 属性可通过 `getAttribute` / `rawAttributes` 读取，元素可通过
+   *   `querySelector` / `querySelectorAll` / `getElementById` /
+   *   `getElementsByTagName` 等方法查询。
+   *
+   * 边界与意外场景：
+   * - 空字符串解析为空树（`childNodes` 为空、`textContent` 为空字符串）；
+   * - 查询不到匹配元素时，选择器方法返回 `null` / 空数组，而不会抛出异常；
+   * - 本方法不负责 HTML 清理与消毒，不可信输入需先经过 `escape` 或其它
+   *   消毒流程后再使用；
+   * - 底层解析失败时会直接抛出异常，本方法不做兜底转换。
+   *
+   * @param html 待解析的 HTML 字符串。
+   * @returns 解析得到的根节点（HTMLElement），其子节点为实际解析出的元素。
+   *
+   * @example
+   * const root = new XHtml().parse('<div class="box">hi<span>!</span></div>');
+   * root.querySelector('.box')?.textContent // 'hi!'
+   * root.querySelectorAll('span').length // 1
+   */
+  static parse(html: string): HTMLElement;
+}

package/lib/html.mjs

@@ -0,0 +1,112 @@
+import { parse } from "node-html-parser";
+import { escapeHTML, unescapeHTML } from "fast-escape-html";
+// src/html.ts
+/**
+* HTML 转义与反转义工具。
+*
+* 基于 `fast-escape-html` 实现，用于在把不可信文本嵌入 HTML 前进行转义，
+* 或将已转义的 HTML 实体还原为原始字符，避免标签错乱与 XSS 注入。
+*
+* 转义字符对照：
+* | 原字符 | 转义结果 |
+* | ------ | -------- |
+* | `&`    | `&`  |
+* | `<`    | `&lt;`   |
+* | `>`    | `&gt;`   |
+* | `"`    | `&quot;` |
+* | `'`    | `&#39;`  |
+*
+* @example
+* const html = new XHtml();
+* html.escape('<a href="x">\'</a>') // '&lt;a href=&quot;x&quot;&gt;&#39;&lt;/a&gt;'
+* html.unescape('&lt;a&amp;b&gt;') // '<a&b>'
+*
+* @remarks
+* - `escape` 是无状态转义：已含实体的文本会再次被转义（如 `&lt;` →
+*   `&amp;lt;`），因此不要对同一段文本重复调用；
+* - `unescape` 只还原本工具转义出的实体（`&amp;`、`&lt;`、`&gt;`、
+*   `&quot;`、`&#39;`、`&apos;`），不处理 `&nbsp;`、`&copy;` 等其它命名
+*   实体，也不处理 `&#65;`、`&#x41;` 这类十进制/十六进制数字实体；
+* - 本工具面向 HTML 文本节点/属性值的转义场景，不负责 URL 编码，也不保证
+*   脚本、样式等非 HTML 上下文的安全。
+*/
+var XHtml = class {
+	/**
+	* 将字符串转义为可安全嵌入 HTML 的实体文本。
+	*
+	* 处理规则：
+	* - `&`、`<`、`>`、`"`、`'` 会被替换为对应实体；
+	* - 其余字符（中文、字母、数字、换行、空白等）原样保留；
+	* - 空字符串返回空字符串。
+	*
+	* 边界与意外场景：
+	* - 已转义文本会被二次转义（如 `&lt;` → `&amp;lt;`），调用方需自行保证
+	*   同一段文本只转义一次。
+	*
+	* @param html 待转义的原始字符串。
+	* @returns 转义后的字符串。
+	*
+	* @example
+	* new XHtml().escape('<a href="x">') // '&lt;a href=&quot;x&quot;&gt;'
+	* new XHtml().escape('') // ''
+	*/
+	static escape(html) {
+		return escapeHTML(html);
+	}
+	/**
+	* 将 HTML 实体还原为原始字符。
+	*
+	* 处理规则：
+	* - 还原 `&amp;`、`&lt;`、`&gt;`、`&quot;`、`&#39;`、`&apos;`；
+	* - 未匹配到上述实体的文本原样保留；
+	* - 空字符串返回空字符串。
+	*
+	* 边界与意外场景：
+	* - `&nbsp;`、`&copy;` 等其它命名实体不会被还原；
+	* - `&#65;`、`&#x41;` 等数字实体不会被还原；
+	* - 反转义是一次性替换而非循环展开，例如 `&amp;amp;` 还原后得到 `&amp;`
+	*   而不会继续还原成 `&`。
+	*
+	* @param html 含 HTML 实体的字符串。
+	* @returns 还原后的字符串。
+	*
+	* @example
+	* new XHtml().unescape('&lt;a&amp;b&gt;') // '<a&b>'
+	* new XHtml().unescape('&apos;ok&apos;') // "'ok'"
+	* new XHtml().unescape('') // ''
+	*/
+	static unescape(html) {
+		return unescapeHTML(html);
+	}
+	/**
+	* 将 HTML 字符串解析为可查询的节点树。
+	*
+	* 基于 `node-html-parser` 实现，返回的根节点是一个“文档容器”：
+	* - 根节点自身不携带标签名（`tagName` / `rawTagName` 为 `null`），
+	*   真正解析出的元素位于 `childNodes` 中；
+	* - 同时支持完整文档与 HTML 片段（多个顶层节点）；
+	* - 元素节点与文本节点会被保留，注释节点默认被丢弃；
+	* - 属性可通过 `getAttribute` / `rawAttributes` 读取，元素可通过
+	*   `querySelector` / `querySelectorAll` / `getElementById` /
+	*   `getElementsByTagName` 等方法查询。
+	*
+	* 边界与意外场景：
+	* - 空字符串解析为空树（`childNodes` 为空、`textContent` 为空字符串）；
+	* - 查询不到匹配元素时，选择器方法返回 `null` / 空数组，而不会抛出异常；
+	* - 本方法不负责 HTML 清理与消毒，不可信输入需先经过 `escape` 或其它
+	*   消毒流程后再使用；
+	* - 底层解析失败时会直接抛出异常，本方法不做兜底转换。
+	*
+	* @param html 待解析的 HTML 字符串。
+	* @returns 解析得到的根节点（HTMLElement），其子节点为实际解析出的元素。
+	*
+	* @example
+	* const root = new XHtml().parse('<div class="box">hi<span>!</span></div>');
+	* root.querySelector('.box')?.textContent // 'hi!'
+	* root.querySelectorAll('span').length // 1
+	*/
+	static parse(html) {
+		return parse(html);
+	}
+};
+export { XHtml };

package/lib/jwt.d.mts

@@ -0,0 +1,128 @@
+import { MsValue } from "vtils";
+import jwt from "jsonwebtoken";
+import { LRUCache } from "lru-cache";
+import { RequiredBy } from "vtils/types";
+import { IncomingHttpHeaders } from "node:http";
+/**
+ * JWT 载荷。
+ *
+ * 即签入 token 的自定义数据；`jsonwebtoken` 签发时会额外写入
+ * `iat`（签发时间，Unix 秒）与 `exp`（过期时间，Unix 秒）两个标准字段。
+ *
+ * 该接口只是宽松约束，实际载荷可包含任意字段，
+ * 调用方通过 `sign` / `verify` 的泛型参数指定具体形状。
+ */
+export interface XJwtPayload extends Record<string, any> {}
+/**
+ * `XJwt` 的构造选项。
+ */
+export interface XJwtOptions {
+  /**
+   * 签名密钥。
+   *
+   * 用于签发与校验 token，必须保密；一旦泄露，
+   * 任何人都可以伪造出能被校验通过的 token。
+   */
+  secret: string;
+  /**
+   * 默认有效期。
+   *
+   * 支持字符串（如 `'1s'`、`'30m'`、`'7d'`）或数字（毫秒）。
+   * 当 `sign` 未显式传入 `ttl` 时使用该值。
+   *
+   * 说明：token 的 `exp` 字段精度为秒（`jsonwebtoken` 的限制），
+   * 换算时不足 1 秒的部分会四舍五入；缓存的有效期则使用毫秒精度。
+   */
+  ttl: MsValue;
+  /**
+   * 可选的内存缓存配置。
+   *
+   * 传入后启用“先查缓存、命中即返回”的快速校验路径，
+   * 可避免对同一 token 重复执行 `jsonwebtoken` 验签。
+   */
+  cache?: LRUCache.Options<string, XJwtPayload, any>;
+  /**
+   * 校验通过后的钩子。
+   *
+   * 在 token 校验成功（或命中缓存）后、`verify` 返回前调用，
+   * 可用于记录日志、更新活跃状态等；若钩子抛出异常，
+   * `verify` 会以该异常拒绝。
+   */
+  onVerify?: (payload: XJwtPayload & RequiredBy<jwt.JwtPayload, 'iat' | 'exp'> & {
+    token: string;
+  }) => any;
+}
+/**
+ * `XJwt.verify` 的返回结果。
+ *
+ * 在自定义载荷的基础上，合并 `jsonwebtoken` 校验后的标准字段
+ * （`iat` / `exp` 等）以及本次校验所用的 `token` 字段。
+ */
+export type XJwtVerifyResult<T extends XJwtPayload> = T & RequiredBy<jwt.JwtPayload, 'iat' | 'exp'> & {
+  token: string;
+};
+/**
+ * JWT 签发与校验工具。
+ *
+ * 封装 `jsonwebtoken`，提供统一的签发（`sign`）与校验（`verify`），
+ * 并额外支持：
+ * - 可选的内存缓存（`LRUCache`），命中缓存时跳过重复验签；
+ * - 从 HTTP 或 WebSocket 升级请求头中提取 token（`verifyFromHttpHeaders`）。
+ *
+ * @example
+ * const xJwt = new XJwt({ secret: 'xx', ttl: '1h' });
+ *
+ * const token = xJwt.sign({ userId: 1 });
+ * // 'header.payload.signature'
+ *
+ * await xJwt.verify(token);
+ * // { userId: 1, iat: 1730000000, exp: 1730003600, token: 'header.payload.signature' }
+ */
+export declare class XJwt {
+  private options;
+  private cache;
+  constructor(options: XJwtOptions);
+  /**
+   * 签发 JWT。
+   *
+   * 使用 `secret` 对 `payload` 签名，并写入 `iat` 与 `exp`。
+   * 若启用了缓存，会将原始 `payload` 以 token 为 key 写入缓存，
+   * 有效期与 token 一致，供 `verify` 快速命中。
+   *
+   * @param payload 要签入 token 的自定义载荷。
+   * @param ttl 有效期，默认使用构造时传入的 `options.ttl`；
+   *            支持字符串（如 `'1s'`）或数字（毫秒）。
+   * @returns 签名后的 JWT 字符串。
+   */
+  sign<T extends XJwtPayload>(payload: T, ttl?: MsValue): string;
+  /**
+   * 校验 JWT。
+   *
+   * 主要分支：
+   * - 启用了缓存且 token 命中缓存：直接返回缓存中的载荷（补上 `token` 字段），
+   *   不再执行验签；
+   * - 否则调用 `jsonwebtoken.verify` 验签，要求载荷中存在 `iat` 与 `exp`
+   *   且未过期；验签通过后写入缓存（有效期 = token 剩余时长）并返回。
+   *
+   * 校验通过后，会先执行 `options.onVerify`（若已配置），再返回结果。
+   *
+   * @param token 待校验的 JWT 字符串。
+   * @returns 载荷与 `token` 字段合并后的对象（含 `iat` / `exp` 等标准字段）。
+   * @throws 当 token 无效、格式错误、已过期，或 `onVerify` 钩子抛出异常时拒绝。
+   */
+  verify<T extends XJwtPayload>(token: string): Promise<XJwtVerifyResult<T>>;
+  /**
+   * 从请求头中提取 token 并校验。
+   *
+   * 依次尝试以下来源：
+   * 1. `authorization` 头：支持 `Bearer <token>` 形式，也兼容不带 scheme 的
+   *    原始 token（按空格拆分后，若只有一段则直接作为 token）；
+   * 2. `sec-websocket-protocol` 头（WebSocket 升级请求）：其值为原始 token，
+   *    会被包装成 `Bearer <token>` 后按相同逻辑解析。
+   *
+   * @param headers Node HTTP 请求头对象。
+   * @returns `verify` 的校验结果。
+   * @throws 当两个头都缺失或为空时抛出异常。
+   */
+  verifyFromHttpHeaders<T extends XJwtPayload>(headers: IncomingHttpHeaders): Promise<XJwtVerifyResult<T>>;
+}

package/lib/jwt.mjs

@@ -0,0 +1,104 @@
+import { ms } from "vtils";
+import { differenceInMilliseconds, fromUnixTime } from "vtils/date";
+import jwt from "jsonwebtoken";
+import { LRUCache } from "lru-cache";
+// src/jwt.ts
+/**
+* JWT 签发与校验工具。
+*
+* 封装 `jsonwebtoken`，提供统一的签发（`sign`）与校验（`verify`），
+* 并额外支持：
+* - 可选的内存缓存（`LRUCache`），命中缓存时跳过重复验签；
+* - 从 HTTP 或 WebSocket 升级请求头中提取 token（`verifyFromHttpHeaders`）。
+*
+* @example
+* const xJwt = new XJwt({ secret: 'xx', ttl: '1h' });
+*
+* const token = xJwt.sign({ userId: 1 });
+* // 'header.payload.signature'
+*
+* await xJwt.verify(token);
+* // { userId: 1, iat: 1730000000, exp: 1730003600, token: 'header.payload.signature' }
+*/
+var XJwt = class {
+	options;
+	cache;
+	constructor(options) {
+		this.options = options;
+		if (options.cache) this.cache = new LRUCache(options.cache);
+	}
+	/**
+	* 签发 JWT。
+	*
+	* 使用 `secret` 对 `payload` 签名，并写入 `iat` 与 `exp`。
+	* 若启用了缓存，会将原始 `payload` 以 token 为 key 写入缓存，
+	* 有效期与 token 一致，供 `verify` 快速命中。
+	*
+	* @param payload 要签入 token 的自定义载荷。
+	* @param ttl 有效期，默认使用构造时传入的 `options.ttl`；
+	*            支持字符串（如 `'1s'`）或数字（毫秒）。
+	* @returns 签名后的 JWT 字符串。
+	*/
+	sign(payload, ttl = this.options.ttl) {
+		const token = jwt.sign(payload, this.options.secret, { expiresIn: ms(ttl, true) });
+		if (this.cache) this.cache.set(token, payload, { ttl: ms(ttl) });
+		return token;
+	}
+	/**
+	* 校验 JWT。
+	*
+	* 主要分支：
+	* - 启用了缓存且 token 命中缓存：直接返回缓存中的载荷（补上 `token` 字段），
+	*   不再执行验签；
+	* - 否则调用 `jsonwebtoken.verify` 验签，要求载荷中存在 `iat` 与 `exp`
+	*   且未过期；验签通过后写入缓存（有效期 = token 剩余时长）并返回。
+	*
+	* 校验通过后，会先执行 `options.onVerify`（若已配置），再返回结果。
+	*
+	* @param token 待校验的 JWT 字符串。
+	* @returns 载荷与 `token` 字段合并后的对象（含 `iat` / `exp` 等标准字段）。
+	* @throws 当 token 无效、格式错误、已过期，或 `onVerify` 钩子抛出异常时拒绝。
+	*/
+	async verify(token) {
+		const data = await new Promise((resolve, reject) => {
+			if (this.cache && this.cache.has(token)) {
+				resolve({
+					...this.cache.get(token),
+					token
+				});
+				return;
+			}
+			jwt.verify(token, this.options.secret, { ignoreExpiration: false }, (err, decoded) => {
+				if (err || !decoded || typeof decoded === "string" || !decoded.iat || !decoded.exp) {
+					reject(/* @__PURE__ */ new Error("JWT 校验失败：token 无效、格式错误或已过期"));
+					return;
+				}
+				decoded.token = token;
+				if (this.cache) this.cache.set(token, decoded, { ttl: differenceInMilliseconds(fromUnixTime(decoded.exp), /* @__PURE__ */ new Date()) });
+				resolve(decoded);
+			});
+		});
+		await this.options.onVerify?.(data);
+		return data;
+	}
+	/**
+	* 从请求头中提取 token 并校验。
+	*
+	* 依次尝试以下来源：
+	* 1. `authorization` 头：支持 `Bearer <token>` 形式，也兼容不带 scheme 的
+	*    原始 token（按空格拆分后，若只有一段则直接作为 token）；
+	* 2. `sec-websocket-protocol` 头（WebSocket 升级请求）：其值为原始 token，
+	*    会被包装成 `Bearer <token>` 后按相同逻辑解析。
+	*
+	* @param headers Node HTTP 请求头对象。
+	* @returns `verify` 的校验结果。
+	* @throws 当两个头都缺失或为空时抛出异常。
+	*/
+	async verifyFromHttpHeaders(headers) {
+		const authorization = headers.authorization || headers["sec-websocket-protocol"] && `Bearer ${headers["sec-websocket-protocol"]}` || "";
+		if (!authorization) throw new Error("缺少认证信息：请提供 Authorization 或 Sec-WebSocket-Protocol 请求头");
+		const [scheme, token = scheme] = authorization.split(" ");
+		return this.verify(token);
+	}
+};
+export { XJwt };