@fast-china/utils 1.0.37 → 2.0.0

package/dist/color/index.d.mts

@@ -0,0 +1,90 @@
+//#region src/color/index.d.ts
+/** 0 至 255 范围的 RGB 颜色。 */
+interface RgbColor {
+  /** 蓝色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  blue: number;
+  /** 绿色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  green: number;
+  /** 红色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  red: number;
+}
+/** 带 0 至 1 Alpha 通道的 RGB 颜色。 */
+interface RgbaColor extends RgbColor {
+  /** 不透明度；必须是闭区间 `[0, 1]` 内的有限数，`0` 完全透明，`1` 完全不透明。 */
+  alpha: number;
+}
+/**
+ * 解析可带可不带 `#` 的 `rgb`、`rgba`、`rrggbb` 或 `rrggbbaa`。
+ *
+ * @param value - 十六进制颜色文本。
+ * @returns 标准化的 RGBA 对象；省略 Alpha 时为 1。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+declare function parseHexColor(value: string): RgbaColor;
+/**
+ * 把 RGB 或 RGBA 对象格式化为小写十六进制颜色。
+ *
+ * @param color - 颜色通道；RGB 会四舍五入到最近整数。
+ * @param includeAlpha - 是否输出 Alpha；默认只在传入 Alpha 且小于 1 时输出。
+ * @returns 小写 `#rrggbb` 或 `#rrggbbaa` 文本。
+ * @throws 通道或 Alpha 非法时抛出 `RangeError`。
+ */
+declare function formatHexColor(color: RgbColor | RgbaColor, includeAlpha?: boolean): string;
+/**
+ * 线性混合两种十六进制颜色，包括 Alpha 通道。
+ *
+ * @param first - `amount = 0` 时的颜色。
+ * @param second - `amount = 1` 时的颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 小写十六进制颜色；任一输入含透明度时保留 Alpha。
+ * @throws 颜色非法时抛出 `TypeError`；比例非法时抛出 `RangeError`。
+ */
+declare function mixHexColors(first: string, second: string, amount: number): string;
+/**
+ * 按比例向黑色混合。
+ *
+ * @param color - 合法十六进制颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 混入黑色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+ */
+declare function mixHexColorWithBlack(color: string, amount: number): string;
+/**
+ * 按比例向白色混合。
+ *
+ * @param color - 合法十六进制颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 混入白色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+ */
+declare function mixHexColorWithWhite(color: string, amount: number): string;
+/**
+ * 计算 WCAG sRGB 相对亮度。
+ *
+ * @remarks Alpha 通道不会参与计算；半透明颜色应先与实际背景混合。
+ * @param color - 合法十六进制颜色。
+ * @returns 0 至 1 的相对亮度。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+declare function relativeLuminance(color: string): number;
+/**
+ * 计算两种不透明颜色的 WCAG 对比度，范围 1 至 21。
+ *
+ * @remarks 返回比值本身，不代表特定字号或 WCAG 等级必然通过。
+ * @param first - 第一种十六进制颜色。
+ * @param second - 第二种十六进制颜色。
+ * @returns 较亮颜色与较暗颜色的对比度。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+declare function contrastRatio(first: string, second: string): number;
+/**
+ * 从两个候选颜色中选择与背景对比度更高的一项。
+ *
+ * @param background - 实际不透明背景色。
+ * @param first - 第一候选，默认黑色。
+ * @param second - 第二候选，默认白色。
+ * @returns 对比度较高的原始候选字符串；相同时返回 `first`。
+ * @throws 任一颜色非法时抛出 `TypeError`。
+ */
+declare function pickHigherContrastColor(background: string, first?: string, second?: string): string;
+//#endregion
+export { RgbColor, RgbaColor, contrastRatio, formatHexColor, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, parseHexColor, pickHigherContrastColor, relativeLuminance };
+//# sourceMappingURL=index.d.mts.map

package/dist/color/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/color/index.ts"],"mappings":";;UACiB;;EAEhB;;EAEA;;EAEA;;;UAIgB,kBAAkB;;EAElC;;;;;;;;;iBA0De,cAAc,gBAAgB;;;;;;;;;iBAkB9B,eAAe,OAAO,WAAW,WAAW;;;;;;;;;;iBAmB5C,aAAa,eAAe,gBAAgB;;;;;;;;iBAgC5C,qBAAqB,eAAe;;;;;;;;iBAWpC,qBAAqB,eAAe;;;;;;;;;iBAuBpC,kBAAkB;;;;;;;;;;iBAclB,cAAc,eAAe;;;;;;;;;;iBAiB7B,wBAAwB,oBAAoB,gBAAmB"}

package/dist/color/index.mjs

@@ -0,0 +1,178 @@
+//#region src/color/index.ts
+/**
+* 校验 RGB 颜色通道。
+*
+* @param value - 待校验通道值。
+* @param channel - 用于错误消息的通道名称。
+* @throws `RangeError` 当值非有限或超出 0 至 255。
+*/
+const assertRgbChannel = (value, channel) => {
+	if (!Number.isFinite(value) || value < 0 || value > 255) throw new RangeError(`${channel} must be a finite number from 0 through 255.`);
+};
+/**
+* 校验透明度通道。
+*
+* @param value - 待校验 Alpha 值。
+* @throws `RangeError` 当值非有限或超出闭区间 `[0, 1]`。
+*/
+const assertAlpha = (value) => {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw new RangeError("alpha must be a finite number from 0 through 1.");
+};
+/**
+* 规范化十六进制颜色文本。
+*
+* @param value - 可带 `#` 的 3、4、6 或 8 位颜色文本。
+* @returns 不带 `#` 的 6 或 8 位文本。
+* @throws `TypeError` 当长度或字符不符合十六进制颜色格式。
+*/
+const normalizeHexColor = (value) => {
+	const normalized = value.startsWith("#") ? value.slice(1) : value;
+	if (![
+		3,
+		4,
+		6,
+		8
+	].includes(normalized.length) || !/^[\dA-F]+$/iu.test(normalized)) throw new TypeError("Expected a 3, 4, 6, or 8 digit hexadecimal color.");
+	return normalized.length <= 4 ? Array.from(normalized, (character) => `${character}${character}`).join("") : normalized;
+};
+/**
+* 格式化单个颜色通道。
+*
+* @param value - 已校验的 0 至 255 通道值。
+* @returns 舍入后的两位小写十六进制文本。
+*/
+const formatHexChannel = (value) => Math.round(value).toString(16).padStart(2, "0");
+/**
+* 解析可带可不带 `#` 的 `rgb`、`rgba`、`rrggbb` 或 `rrggbbaa`。
+*
+* @param value - 十六进制颜色文本。
+* @returns 标准化的 RGBA 对象；省略 Alpha 时为 1。
+* @throws 输入非法时抛出 `TypeError`。
+*/
+function parseHexColor(value) {
+	const normalized = normalizeHexColor(value);
+	return {
+		red: Number.parseInt(normalized.slice(0, 2), 16),
+		green: Number.parseInt(normalized.slice(2, 4), 16),
+		blue: Number.parseInt(normalized.slice(4, 6), 16),
+		alpha: normalized.length === 8 ? Number.parseInt(normalized.slice(6, 8), 16) / 255 : 1
+	};
+}
+/**
+* 把 RGB 或 RGBA 对象格式化为小写十六进制颜色。
+*
+* @param color - 颜色通道；RGB 会四舍五入到最近整数。
+* @param includeAlpha - 是否输出 Alpha；默认只在传入 Alpha 且小于 1 时输出。
+* @returns 小写 `#rrggbb` 或 `#rrggbbaa` 文本。
+* @throws 通道或 Alpha 非法时抛出 `RangeError`。
+*/
+function formatHexColor(color, includeAlpha = "alpha" in color && color.alpha < 1) {
+	assertRgbChannel(color.red, "red");
+	assertRgbChannel(color.green, "green");
+	assertRgbChannel(color.blue, "blue");
+	const alpha = "alpha" in color ? color.alpha : 1;
+	assertAlpha(alpha);
+	return `#${`${formatHexChannel(color.red)}${formatHexChannel(color.green)}${formatHexChannel(color.blue)}`}${includeAlpha ? formatHexChannel(alpha * 255) : ""}`;
+}
+/**
+* 线性混合两种十六进制颜色，包括 Alpha 通道。
+*
+* @param first - `amount = 0` 时的颜色。
+* @param second - `amount = 1` 时的颜色。
+* @param amount - 0 至 1 的混合比例。
+* @returns 小写十六进制颜色；任一输入含透明度时保留 Alpha。
+* @throws 颜色非法时抛出 `TypeError`；比例非法时抛出 `RangeError`。
+*/
+function mixHexColors(first, second, amount) {
+	if (!Number.isFinite(amount) || amount < 0 || amount > 1) throw new RangeError("amount must be a finite number from 0 through 1.");
+	const left = parseHexColor(first);
+	const right = parseHexColor(second);
+	/**
+	* 在单个 RGBA 通道上执行与外层相同权重的线性混合。
+	*
+	* @param start - 第一个颜色的通道值。
+	* @param end - 第二个颜色的通道值。
+	* @returns 按外层 `amount` 线性混合后的通道值。
+	*/
+	const mix = (start, end) => start + (end - start) * amount;
+	return formatHexColor({
+		red: mix(left.red, right.red),
+		green: mix(left.green, right.green),
+		blue: mix(left.blue, right.blue),
+		alpha: mix(left.alpha, right.alpha)
+	}, left.alpha < 1 || right.alpha < 1);
+}
+/**
+* 按比例向黑色混合。
+*
+* @param color - 合法十六进制颜色。
+* @param amount - 0 至 1 的混合比例。
+* @returns 混入黑色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+*/
+function mixHexColorWithBlack(color, amount) {
+	return mixHexColors(color, "#000000", amount);
+}
+/**
+* 按比例向白色混合。
+*
+* @param color - 合法十六进制颜色。
+* @param amount - 0 至 1 的混合比例。
+* @returns 混入白色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+*/
+function mixHexColorWithWhite(color, amount) {
+	return mixHexColors(color, "#ffffff", amount);
+}
+/**
+* 按 WCAG sRGB 转换曲线线性化颜色通道。
+*
+* @param channel - 已校验的 0 至 255 通道值。
+* @returns 0 至 1 的线性光值。
+*/
+const linearizeSrgbChannel = (channel) => {
+	const value = channel / 255;
+	return value <= .04045 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4;
+};
+/**
+* 计算 WCAG sRGB 相对亮度。
+*
+* @remarks Alpha 通道不会参与计算；半透明颜色应先与实际背景混合。
+* @param color - 合法十六进制颜色。
+* @returns 0 至 1 的相对亮度。
+* @throws 输入非法时抛出 `TypeError`。
+*/
+function relativeLuminance(color) {
+	const { red, green, blue } = parseHexColor(color);
+	return .2126 * linearizeSrgbChannel(red) + .7152 * linearizeSrgbChannel(green) + .0722 * linearizeSrgbChannel(blue);
+}
+/**
+* 计算两种不透明颜色的 WCAG 对比度，范围 1 至 21。
+*
+* @remarks 返回比值本身，不代表特定字号或 WCAG 等级必然通过。
+* @param first - 第一种十六进制颜色。
+* @param second - 第二种十六进制颜色。
+* @returns 较亮颜色与较暗颜色的对比度。
+* @throws 输入非法时抛出 `TypeError`。
+*/
+function contrastRatio(first, second) {
+	const firstLuminance = relativeLuminance(first);
+	const secondLuminance = relativeLuminance(second);
+	const lighter = Math.max(firstLuminance, secondLuminance);
+	const darker = Math.min(firstLuminance, secondLuminance);
+	return (lighter + .05) / (darker + .05);
+}
+/**
+* 从两个候选颜色中选择与背景对比度更高的一项。
+*
+* @param background - 实际不透明背景色。
+* @param first - 第一候选，默认黑色。
+* @param second - 第二候选，默认白色。
+* @returns 对比度较高的原始候选字符串；相同时返回 `first`。
+* @throws 任一颜色非法时抛出 `TypeError`。
+*/
+function pickHigherContrastColor(background, first = "#000000", second = "#ffffff") {
+	return contrastRatio(background, first) >= contrastRatio(background, second) ? first : second;
+}
+//#endregion
+export { contrastRatio, formatHexColor, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, parseHexColor, pickHigherContrastColor, relativeLuminance };
+
+//# sourceMappingURL=index.mjs.map

package/dist/color/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/color/index.ts"],"sourcesContent":["/** 0 至 255 范围的 RGB 颜色。 */\nexport interface RgbColor {\n\t/** 蓝色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */\n\tblue: number;\n\t/** 绿色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */\n\tgreen: number;\n\t/** 红色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */\n\tred: number;\n}\n\n/** 带 0 至 1 Alpha 通道的 RGB 颜色。 */\nexport interface RgbaColor extends RgbColor {\n\t/** 不透明度；必须是闭区间 `[0, 1]` 内的有限数，`0` 完全透明，`1` 完全不透明。 */\n\talpha: number;\n}\n\n/**\n * 校验 RGB 颜色通道。\n *\n * @param value - 待校验通道值。\n * @param channel - 用于错误消息的通道名称。\n * @throws `RangeError` 当值非有限或超出 0 至 255。\n */\nconst assertRgbChannel = (value: number, channel: string): void => {\n\tif (!Number.isFinite(value) || value < 0 || value > 255) {\n\t\tthrow new RangeError(`${channel} must be a finite number from 0 through 255.`);\n\t}\n};\n\n/**\n * 校验透明度通道。\n *\n * @param value - 待校验 Alpha 值。\n * @throws `RangeError` 当值非有限或超出闭区间 `[0, 1]`。\n */\nconst assertAlpha = (value: number): void => {\n\tif (!Number.isFinite(value) || value < 0 || value > 1) {\n\t\tthrow new RangeError(\"alpha must be a finite number from 0 through 1.\");\n\t}\n};\n\n/**\n * 规范化十六进制颜色文本。\n *\n * @param value - 可带 `#` 的 3、4、6 或 8 位颜色文本。\n * @returns 不带 `#` 的 6 或 8 位文本。\n * @throws `TypeError` 当长度或字符不符合十六进制颜色格式。\n */\nconst normalizeHexColor = (value: string): string => {\n\tconst normalized = value.startsWith(\"#\") ? value.slice(1) : value;\n\tif (![3, 4, 6, 8].includes(normalized.length) || !/^[\\dA-F]+$/iu.test(normalized)) {\n\t\tthrow new TypeError(\"Expected a 3, 4, 6, or 8 digit hexadecimal color.\");\n\t}\n\treturn normalized.length <= 4 ? Array.from(normalized, (character) => `${character}${character}`).join(\"\") : normalized;\n};\n\n/**\n * 格式化单个颜色通道。\n *\n * @param value - 已校验的 0 至 255 通道值。\n * @returns 舍入后的两位小写十六进制文本。\n */\nconst formatHexChannel = (value: number): string => Math.round(value).toString(16).padStart(2, \"0\");\n\n/**\n * 解析可带可不带 `#` 的 `rgb`、`rgba`、`rrggbb` 或 `rrggbbaa`。\n *\n * @param value - 十六进制颜色文本。\n * @returns 标准化的 RGBA 对象；省略 Alpha 时为 1。\n * @throws 输入非法时抛出 `TypeError`。\n */\nexport function parseHexColor(value: string): RgbaColor {\n\tconst normalized = normalizeHexColor(value);\n\treturn {\n\t\tred: Number.parseInt(normalized.slice(0, 2), 16),\n\t\tgreen: Number.parseInt(normalized.slice(2, 4), 16),\n\t\tblue: Number.parseInt(normalized.slice(4, 6), 16),\n\t\talpha: normalized.length === 8 ? Number.parseInt(normalized.slice(6, 8), 16) / 255 : 1,\n\t};\n}\n\n/**\n * 把 RGB 或 RGBA 对象格式化为小写十六进制颜色。\n *\n * @param color - 颜色通道；RGB 会四舍五入到最近整数。\n * @param includeAlpha - 是否输出 Alpha；默认只在传入 Alpha 且小于 1 时输出。\n * @returns 小写 `#rrggbb` 或 `#rrggbbaa` 文本。\n * @throws 通道或 Alpha 非法时抛出 `RangeError`。\n */\nexport function formatHexColor(color: RgbColor | RgbaColor, includeAlpha: boolean = \"alpha\" in color && color.alpha < 1): string {\n\tassertRgbChannel(color.red, \"red\");\n\tassertRgbChannel(color.green, \"green\");\n\tassertRgbChannel(color.blue, \"blue\");\n\tconst alpha = \"alpha\" in color ? color.alpha : 1;\n\tassertAlpha(alpha);\n\tconst rgb = `${formatHexChannel(color.red)}${formatHexChannel(color.green)}${formatHexChannel(color.blue)}`;\n\treturn `#${rgb}${includeAlpha ? formatHexChannel(alpha * 255) : \"\"}`;\n}\n\n/**\n * 线性混合两种十六进制颜色，包括 Alpha 通道。\n *\n * @param first - `amount = 0` 时的颜色。\n * @param second - `amount = 1` 时的颜色。\n * @param amount - 0 至 1 的混合比例。\n * @returns 小写十六进制颜色；任一输入含透明度时保留 Alpha。\n * @throws 颜色非法时抛出 `TypeError`；比例非法时抛出 `RangeError`。\n */\nexport function mixHexColors(first: string, second: string, amount: number): string {\n\tif (!Number.isFinite(amount) || amount < 0 || amount > 1) {\n\t\tthrow new RangeError(\"amount must be a finite number from 0 through 1.\");\n\t}\n\tconst left = parseHexColor(first);\n\tconst right = parseHexColor(second);\n\t/**\n\t * 在单个 RGBA 通道上执行与外层相同权重的线性混合。\n\t *\n\t * @param start - 第一个颜色的通道值。\n\t * @param end - 第二个颜色的通道值。\n\t * @returns 按外层 `amount` 线性混合后的通道值。\n\t */\n\tconst mix = (start: number, end: number): number => start + (end - start) * amount;\n\treturn formatHexColor(\n\t\t{\n\t\t\tred: mix(left.red, right.red),\n\t\t\tgreen: mix(left.green, right.green),\n\t\t\tblue: mix(left.blue, right.blue),\n\t\t\talpha: mix(left.alpha, right.alpha),\n\t\t},\n\t\tleft.alpha < 1 || right.alpha < 1\n\t);\n}\n\n/**\n * 按比例向黑色混合。\n *\n * @param color - 合法十六进制颜色。\n * @param amount - 0 至 1 的混合比例。\n * @returns 混入黑色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。\n */\nexport function mixHexColorWithBlack(color: string, amount: number): string {\n\treturn mixHexColors(color, \"#000000\", amount);\n}\n\n/**\n * 按比例向白色混合。\n *\n * @param color - 合法十六进制颜色。\n * @param amount - 0 至 1 的混合比例。\n * @returns 混入白色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。\n */\nexport function mixHexColorWithWhite(color: string, amount: number): string {\n\treturn mixHexColors(color, \"#ffffff\", amount);\n}\n\n/**\n * 按 WCAG sRGB 转换曲线线性化颜色通道。\n *\n * @param channel - 已校验的 0 至 255 通道值。\n * @returns 0 至 1 的线性光值。\n */\nconst linearizeSrgbChannel = (channel: number): number => {\n\tconst value = channel / 255;\n\treturn value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;\n};\n\n/**\n * 计算 WCAG sRGB 相对亮度。\n *\n * @remarks Alpha 通道不会参与计算；半透明颜色应先与实际背景混合。\n * @param color - 合法十六进制颜色。\n * @returns 0 至 1 的相对亮度。\n * @throws 输入非法时抛出 `TypeError`。\n */\nexport function relativeLuminance(color: string): number {\n\tconst { red, green, blue } = parseHexColor(color);\n\treturn 0.2126 * linearizeSrgbChannel(red) + 0.7152 * linearizeSrgbChannel(green) + 0.0722 * linearizeSrgbChannel(blue);\n}\n\n/**\n * 计算两种不透明颜色的 WCAG 对比度，范围 1 至 21。\n *\n * @remarks 返回比值本身，不代表特定字号或 WCAG 等级必然通过。\n * @param first - 第一种十六进制颜色。\n * @param second - 第二种十六进制颜色。\n * @returns 较亮颜色与较暗颜色的对比度。\n * @throws 输入非法时抛出 `TypeError`。\n */\nexport function contrastRatio(first: string, second: string): number {\n\tconst firstLuminance = relativeLuminance(first);\n\tconst secondLuminance = relativeLuminance(second);\n\tconst lighter = Math.max(firstLuminance, secondLuminance);\n\tconst darker = Math.min(firstLuminance, secondLuminance);\n\treturn (lighter + 0.05) / (darker + 0.05);\n}\n\n/**\n * 从两个候选颜色中选择与背景对比度更高的一项。\n *\n * @param background - 实际不透明背景色。\n * @param first - 第一候选，默认黑色。\n * @param second - 第二候选，默认白色。\n * @returns 对比度较高的原始候选字符串；相同时返回 `first`。\n * @throws 任一颜色非法时抛出 `TypeError`。\n */\nexport function pickHigherContrastColor(background: string, first = \"#000000\", second = \"#ffffff\"): string {\n\treturn contrastRatio(background, first) >= contrastRatio(background, second) ? first : second;\n}\n"],"mappings":"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"}

package/dist/crypto/index.d.mts

@@ -0,0 +1,157 @@
+//#region src/crypto/index.d.ts
+/** 可直接哈希或比较的二进制输入。 */
+type TextOrBytes = string | Uint8Array;
+/** {@link encryptTextWithPassword} 的密钥派生选项。 */
+interface PasswordEncryptionOptions {
+  /**
+   * PBKDF2-HMAC-SHA-256 迭代次数，默认 `600_000`，允许 100,000 至 5,000,000。
+   * 低于默认值需要调用方基于目标硬件完成明确的安全与性能评估。
+   */
+  iterations?: number;
+}
+/** CryptoJS 兼容 AES 模式。 */
+type LegacyAesCipherMode = "CBC" | "ECB";
+/** Web Crypto 导出的 PEM 公私钥对。 */
+interface PemKeyPair {
+  /** 未加密的 PKCS#8 PEM 私钥，包含标准 `PRIVATE KEY` 头尾和 64 字符换行。 */
+  privateKey: string;
+  /** SubjectPublicKeyInfo PEM 公钥，包含标准 `PUBLIC KEY` 头尾和 64 字符换行。 */
+  publicKey: string;
+}
+/** RSA-OAEP 密钥生成选项。 */
+interface RsaKeyPairOptions {
+  /** RSA 模数位数，默认 2048；必须是不小于 2048 的 256 倍数。 */
+  modulusLength?: number;
+}
+/** 本模块支持的 Web Crypto 椭圆曲线。 */
+type EcNamedCurve = "P-256" | "P-384" | "P-521";
+/**
+ * 生成安全随机字节。
+ *
+ * @param length - 0 至 65,536 的安全整数；上限来自 Web Crypto 单次请求限制。
+ * @returns 新建的 `Uint8Array`。
+ * @throws 参数非法时抛出 `RangeError`；缺少 Web Crypto 时抛出 `Error`。
+ */
+declare function generateRandomBytes(length: number): Uint8Array;
+/**
+ * 计算 SHA-256 摘要。
+ *
+ * @remarks SHA-256 是快速摘要，不适合直接存储或校验密码。
+ * @param value - UTF-8 字符串或原始字节。
+ * @returns 32 字节摘要。
+ * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+declare function sha256Bytes(value: TextOrBytes): Promise<Uint8Array>;
+/**
+ * 计算 SHA-256 并格式化为十六进制。
+ *
+ * @param value - UTF-8 字符串或原始字节。
+ * @returns 64 字符小写十六进制文本。
+ * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+declare function sha256Hex(value: TextOrBytes): Promise<string>;
+/**
+ * 计算 MD5 摘要并返回小写十六进制文本。
+ *
+ * @remarks MD5 仅用于历史协议和非安全校验，不得用于密码、签名或抗碰撞场景。
+ * @param value - UTF-8 文本。
+ * @returns 32 字符小写十六进制摘要。
+ */
+declare function md5Hex(value: string): string;
+/**
+ * 计算 SHA-1 摘要并返回小写十六进制文本。
+ *
+ * @remarks SHA-1 仅用于旧系统互通；新用途应使用 {@link sha256Hex}。
+ * @param value - UTF-8 文本。
+ * @returns 40 字符小写十六进制摘要。
+ */
+declare function sha1Hex(value: string): string;
+/**
+ * 使用 AES-256-CBC 与 PKCS#7 填充加密文本。
+ *
+ * @remarks 密钥按 UTF-8 文本补齐或截断为 32 个字符，IV 补齐或截断为 16 个字符。
+ * 该格式不包含认证标签；新数据优先使用 {@link encryptTextWithPassword}。
+ * @param plaintext - UTF-8 明文。
+ * @param key - 兼容密钥文本。
+ * @param vector - 兼容初始化向量文本。
+ * @returns CryptoJS Base64 密文。
+ */
+declare function encryptLegacyAesCbc(plaintext: string, key: string, vector: string): string;
+/** 解密 {@link encryptLegacyAesCbc} 生成的 CryptoJS Base64 密文。 */
+declare function decryptLegacyAesCbc(ciphertext: string, key: string, vector: string): string;
+/**
+ * 使用 AES-256-ECB 与 PKCS#7 填充加密文本。
+ *
+ * @remarks ECB 会暴露重复明文块结构，只能用于必须兼容的旧协议，不得用于新数据设计。
+ * @param plaintext - UTF-8 明文。
+ * @param key - 兼容密钥文本，补齐或截断为 32 个字符。
+ * @returns CryptoJS Base64 密文。
+ */
+declare function encryptLegacyAesEcb(plaintext: string, key: string): string;
+/** 解密 {@link encryptLegacyAesEcb} 生成的 CryptoJS Base64 密文。 */
+declare function decryptLegacyAesEcb(ciphertext: string, key: string): string;
+/** 生成可导出的 RSA-OAEP/SHA-256 PEM 密钥对。 */
+declare function generateRsaOaepKeyPair(options?: RsaKeyPairOptions): Promise<PemKeyPair>;
+/** 使用 RSA-OAEP/SHA-256 公钥加密 UTF-8 文本，并返回 Base64 密文。 */
+declare function encryptRsaOaep(plaintext: string, publicKeyPem: string): Promise<string>;
+/** 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。 */
+declare function decryptRsaOaep(ciphertext: string, privateKeyPem: string): Promise<string>;
+/** 生成 ECDSA PEM 签名密钥对。 */
+declare function generateEcdsaKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/** 使用 ECDSA 私钥签名文本或字节，并返回 Base64 签名。 */
+declare function signEcdsa(value: TextOrBytes, privateKeyPem: string, namedCurve?: EcNamedCurve): Promise<string>;
+/** 使用 ECDSA 公钥验证 Base64 签名。 */
+declare function verifyEcdsa(value: TextOrBytes, signature: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<boolean>;
+/** 生成 ECDH PEM 密钥协商密钥对。 */
+declare function generateEcdhKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/**
+ * 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
+ *
+ * @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
+ */
+declare function deriveEcdhSecret(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
+/**
+ * 以不提前退出的方式比较两个字节数组。
+ *
+ * @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
+ * 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
+ * @param left - 第一字节序列。
+ * @param right - 第二字节序列。
+ * @returns 长度和每个字节均相同时返回 `true`。
+ */
+declare function areBytesEqualWithoutEarlyExit(left: Uint8Array, right: Uint8Array): boolean;
+/**
+ * 使用 PBKDF2-HMAC-SHA-256 派生密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
+ *
+ * @remarks 每次调用生成独立 16 字节盐与 12 字节 IV。输出是本库 v2 自描述载荷，
+ * 不应被拆分、修改或当作跨语言标准格式。密码加密不替代密钥管理；长期高价值数据
+ * 应使用平台 KMS 或专门的加密方案。
+ * @param plaintext - 原始文本，不进行 JSON 推断；UTF-8 编码后最大 8 MiB。
+ * @param password - 1 至 1024 UTF-8 字节的秘密口令。
+ * @param options - PBKDF2 工作因子。
+ * @returns 认证密文字符串；相同输入每次产生不同结果。
+ * @throws 口令非法时抛出 `TypeError` 或 `RangeError`；明文过大时抛出 `RangeError`；
+ * 运行时缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+declare function encryptTextWithPassword(plaintext: string, password: string, options?: PasswordEncryptionOptions): Promise<string>;
+/**
+ * 解密 {@link encryptTextWithPassword} 生成的 v2 认证载荷。
+ *
+ * @param payload - 未修改的 v2 载荷，最大约 16 MiB 文本。
+ * @param password - 加密时使用的口令。
+ * @returns 原始 UTF-8 文本。
+ * @throws 格式或字段非法时抛出 `TypeError`，载荷过大时抛出 `RangeError`，认证或密码
+ * 失败及缺少平台能力时抛出 `Error`。
+ */
+declare function decryptTextWithPassword(payload: string, password: string): Promise<string>;
+/** 解密历史 AES-CBC/ECB 字符串，并优先解析 JSON 结果。 */
+declare function decryptLegacyAesValue<Result = string>(dataStr: string, key: string, vector: string, cipherMode?: LegacyAesCipherMode): Result | null;
+/** 按指定 CBC/ECB 模式加密历史 AES 字符串。 */
+declare function encryptLegacyAes(dataStr: string, key: string, vector: string, cipherMode?: LegacyAesCipherMode): string;
+/** 返回历史兼容的大写 MD5 十六进制摘要。 */
+declare function md5UpperHex(value: string): string;
+/** 返回历史兼容的大写 SHA-1 十六进制摘要。 */
+declare function sha1UpperHex(value: string): string;
+//#endregion
+export { EcNamedCurve, LegacyAesCipherMode, PasswordEncryptionOptions, PemKeyPair, RsaKeyPairOptions, TextOrBytes, areBytesEqualWithoutEarlyExit, decryptLegacyAesCbc, decryptLegacyAesEcb, decryptLegacyAesValue, decryptRsaOaep, decryptTextWithPassword, deriveEcdhSecret, encryptLegacyAes, encryptLegacyAesCbc, encryptLegacyAesEcb, encryptRsaOaep, encryptTextWithPassword, generateEcdhKeyPair, generateEcdsaKeyPair, generateRandomBytes, generateRsaOaepKeyPair, md5Hex, md5UpperHex, sha1Hex, sha1UpperHex, sha256Bytes, sha256Hex, signEcdsa, verifyEcdsa };
+//# sourceMappingURL=index.d.mts.map

package/dist/crypto/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/crypto/index.ts"],"mappings":";;KAyCY,uBAAuB;;UAGlB;;;;;EAKhB;;;KAIW;;UAGK;;EAEhB;;EAEA;;;UAIgB;;EAEhB;;;KAIW;;;;;;;;iBAqPI,oBAAoB,iBAAiB;;;;;;;;;iBAe/B,YAAY,OAAO,cAAc,QAAQ;;;;;;;;iBAYzC,UAAU,OAAO,cAAc;;;;;;;;iBAYrC,OAAO;;;;;;;;iBAWP,QAAQ;;;;;;;;;;;iBAcR,oBAAoB,mBAAmB,aAAa;;iBASpD,oBAAoB,oBAAoB,aAAa;;;;;;;;;iBAgBrD,oBAAoB,mBAAmB;;iBASvC,oBAAoB,oBAAoB;;iBASlC,uBAAuB,UAAS,oBAAyB,QAAQ;;iBAsBjE,eAAe,mBAAmB,uBAAuB;;iBAUzD,eAAe,oBAAoB,wBAAwB;;iBAU3D,qBAAqB,aAAY,eAAyB,QAAQ;;iBAOlE,UAAU,OAAO,aAAa,uBAAuB,aAAY,eAAyB;;iBAQ1F,YAAY,OAAO,aAAa,mBAAmB,sBAAsB,aAAY,eAAyB;;iBAY9G,oBAAoB,aAAY,eAAyB,QAAQ;;;;;;iBAWjE,iBAAiB,uBAAuB,sBAAsB,aAAY,eAAyB,QAAQ;;;;;;;;;;iBAmBjH,8BAA8B,MAAM,YAAY,OAAO;;;;;;;;;;;;;;iBAqBjD,wBAAwB,mBAAmB,kBAAkB,UAAS,4BAAiC;;;;;;;;;;iBAoCvG,wBAAwB,iBAAiB,mBAAmB;;iBAwDlE,sBAAsB,iBACrC,iBACA,aACA,gBACA,aAAa,sBACX;;iBAiBa,iBAAiB,iBAAiB,aAAa,gBAAgB,aAAa;;iBAM5E,YAAY;;iBAKZ,aAAa"}