@jayfong/x-utils 3.3.0 → 3.4.0

package/lib/crypto.d.mts

@@ -0,0 +1,158 @@
+/**
+ * 常用加解密与摘要工具。
+ *
+ * 提供 Base64 / Base64URL 编解码、常见哈希摘要（MD5、SHA-1、
+ * SHA-256、SHA-512），以及 AES-128-ECB 对称加解密能力，所有方法
+ * 均为静态方法，可直接通过 `XCrypto.xxx()` 调用。
+ *
+ * @example
+ * XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+ * XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+ *
+ * @remarks
+ * - MD5 与 SHA-1 已被视为不安全算法，仅建议用于校验等非安全场景；
+ * - AES 采用 ECB 模式，相同明文加密结果固定，不适用于需要语义安全的
+ *   场景（建议改用 CBC / GCM 等带随机 IV 的模式）；
+ * - 加解密密钥会自动规范化为 16 字节（不足补零、超出截断）。
+ */
+export declare class XCrypto {
+  /**
+   * 将文本编码为 Base64 字符串。
+   *
+   * @param text 需要编码的原始文本。
+   * @returns Base64 编码后的字符串。
+   *
+   * @example
+   * XCrypto.base64Encode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0='
+   * XCrypto.base64Encode('🐲') // '8J+Qsg=='
+   */
+  static base64Encode(text: string): string;
+  /**
+   * 将 Base64 字符串解码为 UTF-8 文本。
+   *
+   * @param text Base64 编码的字符串。
+   * @returns 解码后的 UTF-8 文本。
+   *
+   * @example
+   * XCrypto.base64Decode('eyJ1c2VySWQiOiJkb2l0In0=') // '{"userId":"doit"}'
+   * XCrypto.base64Decode('8J+Qsg==') // '🐲'
+   */
+  static base64Decode(text: string): string;
+  /**
+   * 将文本编码为 URL 安全的 Base64（Base64URL）字符串。
+   *
+   * 与标准 Base64 的区别：`+` 替换为 `-`、`/` 替换为 `_`，并去除
+   * 末尾的 `=` 填充，使其可直接用于 URL 查询参数等场景。
+   *
+   * @param text 需要编码的原始文本。
+   * @returns Base64URL 编码后的字符串。
+   *
+   * @example
+   * XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+   * XCrypto.base64UrlEncode('🐲') // '8J-Qsg'
+   */
+  static base64UrlEncode(text: string): string;
+  /**
+   * 将 Base64URL 字符串解码为 UTF-8 文本。
+   *
+   * @param text Base64URL 编码的字符串。
+   * @returns 解码后的 UTF-8 文本。
+   *
+   * @example
+   * XCrypto.base64UrlDecode('eyJ1c2VySWQiOiJkb2l0In0') // '{"userId":"doit"}'
+   * XCrypto.base64UrlDecode('8J-Qsg') // '🐲'
+   */
+  static base64UrlDecode(text: string): string;
+  /**
+   * 计算文本的 MD5 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 32 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+   */
+  static md5(text: string): string;
+  /**
+   * 计算文本的 SHA-1 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 40 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.sha1('123456') // '7c4a8d09ca3762af61e59520943dc26494f8941b'
+   */
+  static sha1(text: string): string;
+  /**
+   * 计算文本的 SHA-256 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 64 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.sha256('123456') // '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92'
+   */
+  static sha256(text: string): string;
+  /**
+   * 计算文本的 SHA-512 摘要。
+   *
+   * @param text 待摘要的文本。
+   * @returns 128 位小写十六进制字符串。
+   *
+   * @example
+   * XCrypto.sha512('123456') // 'ba3253876aed6bc22d4a6ff53d8406c6ad864195ed144ab5c87621b6c233b548baeae6956df346ec8c17f5ea10f35ee3cbc514797ed7ddd3145464e2a0bab413'
+   */
+  static sha512(text: string): string;
+  /**
+   * 使用 AES-128-ECB（PKCS7 填充）对文本进行加密。
+   *
+   * @param text 需要加密的文本。
+   * @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+   * @returns Base64 编码的密文。
+   *
+   * @example
+   * XCrypto.aesEncrypt('{"userId":"doit"}', 'hj7Wer8V3epukzV7')
+   * // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+   */
+  static aesEncrypt(text: string, key: string): string;
+  /**
+   * 使用 AES-128-ECB（PKCS7 填充）对文本进行解密。
+   *
+   * @param text Base64 编码的密文。
+   * @param key 解密密钥，需与加密时使用的密钥一致，会自动规范化为 16 字节。
+   * @returns 解密后的 UTF-8 文本。
+   *
+   * @example
+   * XCrypto.aesDecrypt('fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=', 'hj7Wer8V3epukzV7')
+   * // '{"userId":"doit"}'
+   */
+  static aesDecrypt(text: string, key: string): string;
+  /**
+   * 将对象序列化为 JSON 后使用 AES 加密。
+   *
+   * 适用于传输或存储敏感结构化数据前的加密处理。
+   *
+   * @param payload 需要加密的任意数据，内部会先 `JSON.stringify` 序列化。
+   * @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+   * @returns Base64 编码的密文。
+   *
+   * @example
+   * XCrypto.aesEncryptJson({ userId: 'doit' }, 'hj7Wer8V3epukzV7')
+   * // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+   */
+  static aesEncryptJson(payload: unknown, key: string): string;
+  /**
+   * 解密文本并将结果解析为 JSON 对象。
+   *
+   * @param text Base64 编码的密文。
+   * @param key 解密密钥，需与加密时使用的密钥一致。
+   * @returns 解密并解析后的 JSON 对象，类型由泛型 `T` 指定。
+   *
+   * @example
+   * XCrypto.aesDecryptJson<{ userId: string }>(
+   *   'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=',
+   *   'hj7Wer8V3epukzV7',
+   * ) // { userId: 'doit' }
+   */
+  static aesDecryptJson<T>(text: string, key: string): T;
+}

package/lib/crypto.mjs

@@ -0,0 +1,213 @@
+import crypto from "node:crypto";
+// src/crypto.ts
+/**
+* 将任意长度的密钥规范化为 AES-128 所需的 16 字节密钥。
+*
+* 规则：密钥先按 UTF-8 编码为字节序列；不足 16 字节时在右侧补 0，
+* 超过 16 字节时截取前 16 字节。
+*
+* 对于纯 ASCII 密钥，结果与 `key.substring(0, 16)` 完全一致；
+* 同时修复了原实现按字符截取导致多字节字符密钥字节数超长而抛错的问题。
+*/
+function resolveAesKey(key) {
+	return Buffer.concat([Buffer.from(key, "utf8"), Buffer.alloc(16)]).subarray(0, 16);
+}
+/**
+* 计算文本的十六进制摘要。
+*
+* @param text 待摘要的文本。
+* @param algorithm 摘要算法名称（如 md5、sha1、sha256、sha512）。
+* @returns 小写十六进制形式的摘要字符串。
+*/
+function digest(text, algorithm) {
+	return crypto.createHash(algorithm).update(text, "utf8").digest("hex");
+}
+/**
+* 常用加解密与摘要工具。
+*
+* 提供 Base64 / Base64URL 编解码、常见哈希摘要（MD5、SHA-1、
+* SHA-256、SHA-512），以及 AES-128-ECB 对称加解密能力，所有方法
+* 均为静态方法，可直接通过 `XCrypto.xxx()` 调用。
+*
+* @example
+* XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+* XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+*
+* @remarks
+* - MD5 与 SHA-1 已被视为不安全算法，仅建议用于校验等非安全场景；
+* - AES 采用 ECB 模式，相同明文加密结果固定，不适用于需要语义安全的
+*   场景（建议改用 CBC / GCM 等带随机 IV 的模式）；
+* - 加解密密钥会自动规范化为 16 字节（不足补零、超出截断）。
+*/
+var XCrypto = class XCrypto {
+	/**
+	* 将文本编码为 Base64 字符串。
+	*
+	* @param text 需要编码的原始文本。
+	* @returns Base64 编码后的字符串。
+	*
+	* @example
+	* XCrypto.base64Encode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0='
+	* XCrypto.base64Encode('🐲') // '8J+Qsg=='
+	*/
+	static base64Encode(text) {
+		return Buffer.from(text, "utf8").toString("base64");
+	}
+	/**
+	* 将 Base64 字符串解码为 UTF-8 文本。
+	*
+	* @param text Base64 编码的字符串。
+	* @returns 解码后的 UTF-8 文本。
+	*
+	* @example
+	* XCrypto.base64Decode('eyJ1c2VySWQiOiJkb2l0In0=') // '{"userId":"doit"}'
+	* XCrypto.base64Decode('8J+Qsg==') // '🐲'
+	*/
+	static base64Decode(text) {
+		return Buffer.from(text, "base64").toString("utf8");
+	}
+	/**
+	* 将文本编码为 URL 安全的 Base64（Base64URL）字符串。
+	*
+	* 与标准 Base64 的区别：`+` 替换为 `-`、`/` 替换为 `_`，并去除
+	* 末尾的 `=` 填充，使其可直接用于 URL 查询参数等场景。
+	*
+	* @param text 需要编码的原始文本。
+	* @returns Base64URL 编码后的字符串。
+	*
+	* @example
+	* XCrypto.base64UrlEncode('{"userId":"doit"}') // 'eyJ1c2VySWQiOiJkb2l0In0'
+	* XCrypto.base64UrlEncode('🐲') // '8J-Qsg'
+	*/
+	static base64UrlEncode(text) {
+		return Buffer.from(text, "utf8").toString("base64url");
+	}
+	/**
+	* 将 Base64URL 字符串解码为 UTF-8 文本。
+	*
+	* @param text Base64URL 编码的字符串。
+	* @returns 解码后的 UTF-8 文本。
+	*
+	* @example
+	* XCrypto.base64UrlDecode('eyJ1c2VySWQiOiJkb2l0In0') // '{"userId":"doit"}'
+	* XCrypto.base64UrlDecode('8J-Qsg') // '🐲'
+	*/
+	static base64UrlDecode(text) {
+		return Buffer.from(text, "base64url").toString("utf8");
+	}
+	/**
+	* 计算文本的 MD5 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 32 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.md5('123456') // 'e10adc3949ba59abbe56e057f20f883e'
+	*/
+	static md5(text) {
+		return digest(text, "md5");
+	}
+	/**
+	* 计算文本的 SHA-1 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 40 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.sha1('123456') // '7c4a8d09ca3762af61e59520943dc26494f8941b'
+	*/
+	static sha1(text) {
+		return digest(text, "sha1");
+	}
+	/**
+	* 计算文本的 SHA-256 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 64 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.sha256('123456') // '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92'
+	*/
+	static sha256(text) {
+		return digest(text, "sha256");
+	}
+	/**
+	* 计算文本的 SHA-512 摘要。
+	*
+	* @param text 待摘要的文本。
+	* @returns 128 位小写十六进制字符串。
+	*
+	* @example
+	* XCrypto.sha512('123456') // 'ba3253876aed6bc22d4a6ff53d8406c6ad864195ed144ab5c87621b6c233b548baeae6956df346ec8c17f5ea10f35ee3cbc514797ed7ddd3145464e2a0bab413'
+	*/
+	static sha512(text) {
+		return digest(text, "sha512");
+	}
+	/**
+	* 使用 AES-128-ECB（PKCS7 填充）对文本进行加密。
+	*
+	* @param text 需要加密的文本。
+	* @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+	* @returns Base64 编码的密文。
+	*
+	* @example
+	* XCrypto.aesEncrypt('{"userId":"doit"}', 'hj7Wer8V3epukzV7')
+	* // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+	*/
+	static aesEncrypt(text, key) {
+		const cipher = crypto.createCipheriv("aes-128-ecb", resolveAesKey(key), null);
+		let encrypted = cipher.update(text, "utf8", "base64");
+		encrypted += cipher.final("base64");
+		return encrypted;
+	}
+	/**
+	* 使用 AES-128-ECB（PKCS7 填充）对文本进行解密。
+	*
+	* @param text Base64 编码的密文。
+	* @param key 解密密钥，需与加密时使用的密钥一致，会自动规范化为 16 字节。
+	* @returns 解密后的 UTF-8 文本。
+	*
+	* @example
+	* XCrypto.aesDecrypt('fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=', 'hj7Wer8V3epukzV7')
+	* // '{"userId":"doit"}'
+	*/
+	static aesDecrypt(text, key) {
+		const decipher = crypto.createDecipheriv("aes-128-ecb", resolveAesKey(key), null);
+		let decrypted = decipher.update(text, "base64", "utf8");
+		decrypted += decipher.final("utf8");
+		return decrypted;
+	}
+	/**
+	* 将对象序列化为 JSON 后使用 AES 加密。
+	*
+	* 适用于传输或存储敏感结构化数据前的加密处理。
+	*
+	* @param payload 需要加密的任意数据，内部会先 `JSON.stringify` 序列化。
+	* @param key 加密密钥，会自动规范化为 16 字节（不足补零、超出截断）。
+	* @returns Base64 编码的密文。
+	*
+	* @example
+	* XCrypto.aesEncryptJson({ userId: 'doit' }, 'hj7Wer8V3epukzV7')
+	* // 'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc='
+	*/
+	static aesEncryptJson(payload, key) {
+		return XCrypto.aesEncrypt(JSON.stringify(payload), key);
+	}
+	/**
+	* 解密文本并将结果解析为 JSON 对象。
+	*
+	* @param text Base64 编码的密文。
+	* @param key 解密密钥，需与加密时使用的密钥一致。
+	* @returns 解密并解析后的 JSON 对象，类型由泛型 `T` 指定。
+	*
+	* @example
+	* XCrypto.aesDecryptJson<{ userId: string }>(
+	*   'fCH/NJMbVFVDjL73irkG40HP19muCpVcrrUrx22GuEc=',
+	*   'hj7Wer8V3epukzV7',
+	* ) // { userId: 'doit' }
+	*/
+	static aesDecryptJson(text, key) {
+		return JSON.parse(XCrypto.aesDecrypt(text, key));
+	}
+};
+export { XCrypto };

package/lib/data_set.mjs

@@ -1,9 +1,9 @@
 import { XCsv } from "./csv.mjs";
+import { XDispose } from "./dispose.mjs";
 import { XJson } from "./json.mjs";
 import { XYaml } from "./yaml.mjs";
 import { keyBy, keysStrict, pickStrict } from "vtils";
 import { v } from "vtils/vae";
-import { asyncExitHook } from "exit-hook";
 import * as path from "node:path";
 import fs from "fs-extra";
 // src/data_set.ts
@@ -64,10 +64,10 @@ var XDataSet = class {
 			const timer = setInterval(() => {
 				this.write();
 			}, options.autoWriteInterval || 5e3);
-			asyncExitHook(async () => {
+			XDispose.exit.add(async () => {
 				clearInterval(timer);
 				await this.write();
-			}, { wait: 1e4 });
+			});
 		}
 	}
 	/**

package/lib/db_value.d.mts

@@ -0,0 +1,213 @@
+/**
+ * `XDbValue.SimpleArray` 的配置项。
+ */
+export interface XDbValueSimpleArrayOptions {
+  /**
+   * 元素之间的分隔符。
+   *
+   * @default ','
+   */
+  separator?: string;
+  /**
+   * 存储值的统一前后缀（成对包裹在序列化结果两侧）。
+   *
+   * 例如传入 `"` 后，`['a', 'b']` 会被写为 `"a,b"`。
+   * 读取时仅当值同时以该前后缀开头和结尾时才会被剥离，否则按原始文本解析，
+   * 避免误伤没有前后缀的历史数据。
+   *
+   * @default ''
+   */
+  affix?: string;
+  /**
+   * 是否将数组元素转换为数字。
+   *
+   * @default false
+   */
+  number?: boolean;
+}
+/**
+ * `XDbValue.JsonObject` 的转换钩子配置。
+ *
+ * @template T 对象值的类型。
+ */
+export interface XDbValueJsonObjectOptions<T> {
+  /**
+   * 可选的转换钩子，分别在写入（add）、读取（get）、更新（update）时对值做预处理。
+   */
+  transform?: {
+    /** 写入（add）前对值做转换。 */
+    add?: (value: T) => T;
+    /** 读取（get）后对值做转换。 */
+    get?: (value: T) => T;
+    /** 更新（update）前对值做转换。 */
+    update?: (value: T) => T;
+  };
+}
+/**
+ * 数据库字段值的序列化与反序列化工具。
+ *
+ * 适用于把数组或对象以字符串形式存储到数据库字段（如 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']
+ */
+export declare class XDbValue {
+  /**
+   * 分隔符数组格式：`'a,b'` ↔ `['a', 'b']`。
+   *
+   * @template T 数组元素类型，仅支持 `string` 或 `number`。
+   */
+  static SimpleArray: {
+    new <T extends string | number = string>(options?: XDbValueSimpleArrayOptions): {
+      /** 元素之间的分隔符。 */
+      separator: string;
+      /** 存储值的统一前后缀，空字符串表示不包裹。 */
+      affix: string;
+      /** 是否将数组元素转换为数字。 */
+      number: boolean;
+      /**
+       * 将数组序列化为适合存储的字符串。
+       *
+       * - `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?: T[], defaultValue?: T[]) => string;
+      /**
+       * 将存储字符串反序列化为数组。
+       *
+       * - 值为空时返回空数组；
+       * - 设置了 `affix` 时，仅当值同时以该前后缀开头和结尾才会剥离，否则按原始文本解析；
+       * - 按 `separator` 分割并过滤掉空字符串；
+       * - `number` 为 `true` 时，将每个元素转换为数字。
+       *
+       * @param value 存储字符串。
+       * @returns 反序列化后的数组。
+       *
+       * @example
+       * const sa = new XDbValue.SimpleArray();
+       * sa.get('a,b');
+       * // ['a', 'b']
+       */
+      get: (value?: string) => T[];
+      /**
+       * 将数组序列化为用于更新的字符串。
+       *
+       * 与 {@link add} 的区别在于：`value` 不是数组时返回 `undefined`，
+       * 便于调用方在更新数据库时跳过该字段；`value` 是数组但过滤后为空时返回空字符串。
+       *
+       * @param value 要序列化的数组。
+       * @returns 序列化后的字符串；`value` 不是数组时返回 `undefined`。
+       */
+      update: (value?: T[]) => string | undefined;
+    };
+  };
+  /**
+   * JSON 数组格式：`'[{"a":1}]'` ↔ `[{ a: 1 }]`。
+   *
+   * @template T 数组元素类型。
+   */
+  static JsonArray: {
+    new <T = string>(): {
+      /**
+       * 将数组序列化为 JSON 字符串。
+       *
+       * @param value 要序列化的数组。
+       * @param defaultValue `value` 非法时使用的兜底数组。
+       * @returns JSON 字符串。
+       */
+      add: (value?: T[], defaultValue?: T[]) => string;
+      /**
+       * 将 JSON 字符串反序列化为数组。
+       *
+       * - 值为空时返回空数组；
+       * - 值不是合法 JSON 时抛出 `SyntaxError`。
+       *
+       * @param value JSON 字符串。
+       * @returns 反序列化后的数组。
+       */
+      get: (value?: string) => T[];
+      /**
+       * 将数组序列化为用于更新的 JSON 字符串。
+       *
+       * @param value 要序列化的数组。
+       * @returns JSON 字符串；`value` 不是数组时返回 `undefined`。
+       */
+      update: (value?: T[]) => string | undefined;
+    };
+  };
+  /**
+   * JSON 对象格式：`'{"name":"x"}'` ↔ `{ name: 'x' }`。
+   *
+   * 相比 {@link XDbValue.JsonArray}，额外支持 {@link XDbValueJsonObjectOptions.transform}
+   * 转换钩子，适合在读写时统一处理日期、默认值等字段。
+   *
+   * @template T 对象值的类型。
+   */
+  static JsonObject: {
+    new <T>(options?: XDbValueJsonObjectOptions<T>): {
+      /** 构造时传入的转换钩子配置。 */
+      options?: XDbValueJsonObjectOptions<T>;
+      /** 是否配置了 add 转换钩子。 */
+      hasTransformAdd: boolean;
+      /** 是否配置了 get 转换钩子。 */
+      hasTransformGet: boolean;
+      /** 是否配置了 update 转换钩子。 */
+      hasTransformUpdate: boolean;
+      /**
+       * 将对象序列化为 JSON 字符串。
+       *
+       * - 配置 `transform.add` 时，先对值做转换；
+       * - `value` 不是普通对象时，使用 `defaultValue` 兜底。
+       *
+       * @param value 要序列化的对象。
+       * @param defaultValue `value` 非法时使用的兜底对象。
+       * @returns JSON 字符串。
+       */
+      add: (value?: T, defaultValue?: T) => string;
+      /**
+       * 将 JSON 字符串反序列化为对象。
+       *
+       * - 值为空时返回空对象 `{}`；
+       * - 值不是合法 JSON 时抛出 `SyntaxError`；
+       * - 配置 `transform.get` 时对结果做转换，空值解析出的 `{}` 同样会经过该钩子。
+       *
+       * @param value JSON 字符串。
+       * @returns 反序列化后的对象。
+       */
+      get: (value?: string) => T;
+      /**
+       * 将对象序列化为用于更新的 JSON 字符串。
+       *
+       * - 配置 `transform.update` 时，先对值做转换；
+       * - `value` 不是普通对象时返回 `undefined`。
+       *
+       * @param value 要序列化的对象。
+       * @returns JSON 字符串；`value` 不是普通对象时返回 `undefined`。
+       */
+      update: (value?: T) => string | undefined;
+    };
+  };
+}