ph-utils 0.3.1 → 0.3.3

package/README.md

@@ -1,11 +1,11 @@
-## ph-utils
-
-整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
-
-### 后端(node server)
-
-包含了一些 node 后端开发(web server) 时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`file` 文件操作相关工具类、`server` 一些只适用于后端的工具(使用了后端的 API 列表)、`validator` 数据验证
-
-### 前端(web)
-
-包含了一些前端网站开发时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`dom` 浏览器节点操作相关、`web` 一些只适用于前端相关的工具、`validator` 数据验证
+## ph-utils
+
+整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
+
+### 后端(node server)
+
+包含了一些 node 后端开发(web server) 时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`file` 文件操作相关工具类、`server` 一些只适用于后端的工具(使用了后端的 API 列表)、`validator` 数据验证
+
+### 前端(web)
+
+包含了一些前端网站开发时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`dom` 浏览器节点操作相关、`web` 一些只适用于前端相关的工具、`validator` 数据验证

package/lib/crypto.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 将原始的二进制数据转换为 Hex String
+ * @param bf 待转换的原始数据
+ * @param upper 是否需要转换为大写
+ * @returns
+ */
+export declare function bufferToHex(bf: ArrayBuffer | Uint8Array, upper?: boolean): string;
+/**
+ * SHA 哈希算法
+ * @param message     待进行 hash 的数据
+ * @param upper       是否转换为大写, 默认为: false
+ * @param algorithm   hash算法, 支持: SHA-1、SHA-256、SHA-384、SHA-512; 默认为: SHA-256
+ * @returns
+ */
+export declare function sha(message: string, upper?: boolean, algorithm?: string): Promise<string>;
+/** 返回结果类似 */
+type AlgorithmResType = 'hex' | 'hexUpper' | 'base64' | 'raw';
+/**
+ * AES 加密
+ * @param message 待加密的数据
+ * @param key 加解密密钥
+ * @param encode 加密后的数据转换的形式, hex - 转换为16进制字符串, hexUpper - 转换为16进制且大写, base64 - 转换为 base64 形式
+ * @param iv 加解密向量
+ * @returns [加密数据,向量]
+ */
+export declare function aesEncrypt(message: string, key: string, encode?: AlgorithmResType, iv?: null | Uint8Array | string): Promise<{
+    ciphertext: string | ArrayBuffer;
+    iv: string;
+    key: string;
+}>;
+/**
+ * AES 解密
+ * @param message 加密后的数据
+ * @param key     解密密钥
+ * @param iv      向量
+ * @param encode  加密后数据的形式: hex | base64
+ * @returns
+ */
+export declare function aesDecrypt(message: Uint8Array | string, key: string, iv: string, encode?: AlgorithmResType): Promise<string>;
+/**
+ * RSA 加密
+ * @param key     公钥
+ * @param message 待加密数据
+ * @param encode  返回类型
+ * @returns
+ */
+export declare function rsaEncrypt(message: string, publicKey: string, encode?: AlgorithmResType): Promise<string | ArrayBuffer>;
+/**
+ * RSA 解密
+ * @param key     私钥, 根据私钥解密
+ * @param message 加密后的数据
+ * @param encode  加密后的数据形式
+ * @returns
+ */
+export declare function rsaDecrypt(privateKey: string, message: Uint8Array | string, encode?: AlgorithmResType): Promise<string>;
+export {};

package/lib/crypto.js

@@ -0,0 +1,232 @@
+/* eslint-disable no-undef */
+/**
+ * 将原始的二进制数据转换为 Hex String
+ * @param bf 待转换的原始数据
+ * @param upper 是否需要转换为大写
+ * @returns
+ */
+export function bufferToHex(bf, upper = false) {
+    const u8Array = bf instanceof Uint8Array ? bf : new Uint8Array(bf);
+    const hashArray = Array.from(u8Array);
+    return hashArray
+        .map((b) => {
+        let hx = b.toString(16).padStart(2, '0');
+        return upper === true ? hx.toUpperCase() : hx;
+    })
+        .join('');
+}
+/**
+ * 将16进制的数据转换为 UInt8Array
+ * @param data 16进制的数据
+ * @returns
+ */
+function hexToBuffer(data) {
+    const len = data.length / 2;
+    const uint8Array = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        const byteHex = data.substring(i * 2, i * 2 + 2);
+        const byte = parseInt(byteHex.toLocaleLowerCase(), 16);
+        uint8Array[i] = byte;
+    }
+    return uint8Array;
+}
+/**
+ * 将原始数据转换为 Base64 编码
+ * @param bf 待转换的原始数据
+ * @returns
+ */
+function bufferToBase64(bf) {
+    const u8Array = bf instanceof Uint8Array ? bf : new Uint8Array(bf);
+    const hashArray = Array.from(u8Array);
+    return window.btoa(String.fromCharCode.apply(null, hashArray));
+}
+/**
+ * 将 Base64 转换为 UInt8Array 数据
+ * @param data
+ * @returns
+ */
+function base64ToBuffer(data) {
+    return new Uint8Array(window
+        .atob(data)
+        .split('')
+        .map((char) => char.charCodeAt(0)));
+}
+/**
+ * SHA 哈希算法
+ * @param message     待进行 hash 的数据
+ * @param upper       是否转换为大写, 默认为: false
+ * @param algorithm   hash算法, 支持: SHA-1、SHA-256、SHA-384、SHA-512; 默认为: SHA-256
+ * @returns
+ */
+export async function sha(message, upper = false, algorithm = 'SHA-256') {
+    const msgUint8 = new TextEncoder().encode(message);
+    const hashBuffer = await window.crypto.subtle.digest(algorithm || 'SHA-256', msgUint8);
+    return bufferToHex(hashBuffer, upper);
+}
+function parseRsaKey(pem) {
+    const pemHeader = '-----BEGIN PUBLIC KEY-----';
+    const pemFooter = '-----END PUBLIC KEY-----';
+    if (pem.indexOf(pemHeader) !== -1 && pem.indexOf(pemFooter) !== -1) {
+        pem = pem.substring(pemHeader.length, pem.indexOf(pemFooter)).trim();
+    }
+    return pem;
+}
+/**
+ * 导入上下文密钥
+ * @param key           导入的密钥
+ * @param algorithmName 算法名称
+ * @param usages        该密钥可以用于哪些函数使用
+ * @returns
+ */
+// eslint-disable-next-line no-undef
+async function importKey(key, algorithmName, usages, encoding = 'hex') {
+    let name = 'AES-CBC';
+    if (algorithmName == null) {
+        name = 'AES-CBC';
+    }
+    else {
+        if (algorithmName.toUpperCase() === 'AES') {
+            name = 'AES-CBC';
+        }
+        else if (algorithmName.toUpperCase() === 'RSA') {
+            name = 'RSA-OAEP';
+        }
+    }
+    name = name.toUpperCase();
+    if (usages == null || usages.length === 0) {
+        usages = ['encrypt'];
+    }
+    let format = 'raw';
+    let algorithm = { name };
+    if (name.includes('RSA')) {
+        format = 'spki';
+        algorithm.hash = { name: 'SHA-256' };
+        key = parseRsaKey(key);
+    }
+    const keyBuf = encoding === 'base64' ? base64ToBuffer(key) : hexToBuffer(key);
+    // importKey时传 false 表明该密钥不能被导出
+    return Promise.all([
+        window.crypto.subtle.importKey(format, keyBuf, algorithm, false, usages),
+        Promise.resolve({ name }),
+    ]);
+}
+/**
+ * 加密
+ * @param algorithm  算法参数, 算法名称、向量等
+ * @param key        算法密钥
+ * @param message    待加密的数据
+ * @param encode     解密后返回数据格式
+ * @returns
+ */
+async function encrypt(algorithm, key, message, encode = 'hex') {
+    if (typeof message === 'string') {
+        message = new TextEncoder().encode(message);
+    }
+    const encrypted = await window.crypto.subtle.encrypt(algorithm, key, message);
+    if (encode === 'hex') {
+        return bufferToHex(encrypted);
+    }
+    else if (encode === 'hexUpper') {
+        return bufferToHex(encrypted, true);
+    }
+    else if (encode === 'base64') {
+        return bufferToBase64(encrypted);
+    }
+    else {
+        return encrypted;
+    }
+}
+/**
+ * 数据解密
+ * @param algorithm 解密算法
+ * @param key       解密密钥
+ * @param message   加密后的数据
+ * @returns
+ */
+async function decrypt(algorithm, key, message) {
+    const decrypted = await window.crypto.subtle.decrypt(algorithm, key, message);
+    return new TextDecoder('utf-8').decode(decrypted);
+}
+/**
+ * AES 加密
+ * @param message 待加密的数据
+ * @param key 加解密密钥
+ * @param encode 加密后的数据转换的形式, hex - 转换为16进制字符串, hexUpper - 转换为16进制且大写, base64 - 转换为 base64 形式
+ * @param iv 加解密向量
+ * @returns [加密数据,向量]
+ */
+export async function aesEncrypt(message, key, encode = 'hex', iv = null) {
+    let ciphertext = '';
+    let resIv = '';
+    // 导入密钥
+    const [cryptoKey, algorithm] = await importKey(key, 'aes', ['encrypt']);
+    if (iv == null) {
+        iv = window.crypto.getRandomValues(new Uint8Array(16));
+    }
+    else if (typeof iv === 'string') {
+        iv = hexToBuffer(iv);
+    }
+    const encodeData = await encrypt({ ...algorithm, iv }, cryptoKey, message, encode);
+    ciphertext = encodeData;
+    resIv = bufferToHex(iv);
+    return { ciphertext, iv: resIv, key };
+}
+/**
+ * 根据加密后的数据类型使用对应函数最终转换为 UInt8Array
+ * @param message 原始加密后的数据
+ * @param type    类型: hex | base64
+ * @returns
+ */
+function parseEncryptData(message, type) {
+    let input;
+    if (typeof message === 'string') {
+        if (type === 'hex' || type === 'hexUpper') {
+            input = hexToBuffer(message);
+        }
+        else {
+            input = base64ToBuffer(message);
+        }
+    }
+    else {
+        input = message;
+    }
+    return input;
+}
+/**
+ * AES 解密
+ * @param message 加密后的数据
+ * @param key     解密密钥
+ * @param iv      向量
+ * @param encode  加密后数据的形式: hex | base64
+ * @returns
+ */
+export async function aesDecrypt(message, key, iv, encode = 'hex') {
+    // 导入密钥
+    const [cryptoKey, algorithm] = await importKey(key, 'aes', ['decrypt']);
+    const input = parseEncryptData(message, encode);
+    return await decrypt({ ...algorithm, iv: hexToBuffer(iv) }, cryptoKey, input);
+}
+/**
+ * RSA 加密
+ * @param key     公钥
+ * @param message 待加密数据
+ * @param encode  返回类型
+ * @returns
+ */
+export async function rsaEncrypt(message, publicKey, encode = 'hex') {
+    // 导入密钥
+    const [cryptoKey, algorithm] = await importKey(publicKey, 'rsa', ['encrypt'], 'base64');
+    return await encrypt(algorithm, cryptoKey, message, encode);
+}
+/**
+ * RSA 解密
+ * @param key     私钥, 根据私钥解密
+ * @param message 加密后的数据
+ * @param encode  加密后的数据形式
+ * @returns
+ */
+export async function rsaDecrypt(privateKey, message, encode = 'hex') {
+    // 导入密钥
+    const [cryptoKey, algorithm] = await importKey(privateKey, 'rsa', ['decrypt']);
+    return await decrypt({ ...algorithm }, cryptoKey, parseEncryptData(message, encode));
+}

package/lib/crypto_node.d.ts

@@ -0,0 +1,44 @@
+type HashAlgorithmName = 'md5' | 'sha1' | 'sha256';
+/**
+ * 进行 md5|sha1|sha256 数据摘要签名
+ * @param d 待加密的数据
+ * @param algorithm 签名算法, md5、sha1. Defaults to "md5".
+ * @param upper 返回的结果是否需要大写. Defaults to False.
+ */
+export declare function hashDigest(d: string, algorithm?: HashAlgorithmName, upper?: boolean): string;
+/**
+ * 生成 RSA 签名密钥对
+ * @returns: [公钥, 私钥]
+ */
+export declare function keyPair(): Promise<[string, string]>;
+/**
+ * AES 加密
+ * @param key   加密密钥
+ * @param input 待加密的数据
+ * @param upper 是否转换为大写
+ * @returns [加密数据, 向量]
+ */
+export declare function aesEncrypt(key: string, input: string, upper?: boolean): [string, string];
+/**
+ * AES 解密
+ * @param input 加密后的数据
+ * @param key   密钥
+ * @param iv    向量
+ * @returns
+ */
+export declare function aesDecrypt(input: string, key: string, iv: string): string;
+/**
+ * RSA 公钥加密
+ * @param input 待加密字符串
+ * @param publicKey 公钥
+ * @returns
+ */
+export declare function rsaEncrypt(input: string, publicKey: string): string;
+/**
+ * RSA 解密
+ * @param encrtypData RSA加密后的数据
+ * @param privateKey  私钥
+ * @returns
+ */
+export declare function rsaDecrypt(encrtypData: string, privateKey: string): string;
+export {};

package/lib/crypto_node.js

@@ -0,0 +1,88 @@
+import { createHash, createCipheriv, randomBytes, generateKeyPair, createDecipheriv, privateDecrypt, publicEncrypt, } from 'node:crypto';
+/**
+ * 进行 md5|sha1|sha256 数据摘要签名
+ * @param d 待加密的数据
+ * @param algorithm 签名算法, md5、sha1. Defaults to "md5".
+ * @param upper 返回的结果是否需要大写. Defaults to False.
+ */
+export function hashDigest(d, algorithm = 'sha256', upper = false) {
+    const hashed = createHash(algorithm).update(d).digest('hex');
+    return upper ? hashed.toUpperCase() : hashed;
+}
+/**
+ * 生成 RSA 签名密钥对
+ * @returns: [公钥, 私钥]
+ */
+export async function keyPair() {
+    return new Promise((resolve, reject) => {
+        generateKeyPair('rsa', {
+            modulusLength: 2048,
+            publicKeyEncoding: {
+                type: 'spki',
+                format: 'pem',
+            },
+            privateKeyEncoding: {
+                type: 'pkcs8',
+                format: 'pem',
+            },
+        }, (err, publicKey, privateKey) => {
+            if (err == null) {
+                resolve([publicKey, privateKey]);
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+}
+/**
+ * AES 加密
+ * @param key   加密密钥
+ * @param input 待加密的数据
+ * @param upper 是否转换为大写
+ * @returns [加密数据, 向量]
+ */
+export function aesEncrypt(key, input, upper = false) {
+    const iv = randomBytes(16);
+    const cipher = createCipheriv('aes-256-cbc', Buffer.from(key, 'hex'), iv);
+    let encryptedData = cipher.update(input, 'utf-8', 'hex');
+    encryptedData += cipher.final('hex');
+    return [upper === true ? encryptedData.toUpperCase() : encryptedData, iv.toString('hex')];
+}
+/**
+ * AES 解密
+ * @param input 加密后的数据
+ * @param key   密钥
+ * @param iv    向量
+ * @returns
+ */
+export function aesDecrypt(input, key, iv) {
+    const cipher = createDecipheriv('aes-256-cbc', Buffer.from(key, 'hex'), Buffer.from(iv, 'hex'));
+    let decryptedData = cipher.update(input, 'hex', 'utf-8');
+    decryptedData += cipher.final('utf-8');
+    return decryptedData;
+}
+/**
+ * RSA 公钥加密
+ * @param input 待加密字符串
+ * @param publicKey 公钥
+ * @returns
+ */
+export function rsaEncrypt(input, publicKey) {
+    return publicEncrypt({
+        key: publicKey,
+        oaepHash: 'sha256',
+    }, Buffer.from(input)).toString('base64');
+}
+/**
+ * RSA 解密
+ * @param encrtypData RSA加密后的数据
+ * @param privateKey  私钥
+ * @returns
+ */
+export function rsaDecrypt(encrtypData, privateKey) {
+    return privateDecrypt({
+        key: privateKey,
+        oaepHash: 'sha256',
+    }, Buffer.from(encrtypData, 'base64')).toString('utf-8');
+}

package/lib/index.d.ts

@@ -74,20 +74,6 @@ export declare class BaseError extends Error {
      */
     constructor(name: string, message: string);
 }
-/**
- * 函数节流 - 每隔单位时间，只执行一次
- * @param cb    待节流的函数
- * @param wait  间隔时间
- * @returns
- */
-export declare function throttle<R extends any[], T>(fn: (...args: R) => T, wait?: number): (...args: R) => void;
-/**
- * 函数防抖 - 当重复触发某一个行为（事件时），只执行最后一次触发
- * @param fn        防抖函数
- * @param interval  间隔时间段
- * @returns
- */
-export declare function debounce<R extends any[], T>(fn: (...args: R) => T, interval?: number): (...args: R) => void;
 /**
  * 将金额数字格式化为金额格式显示并且会保留两位小数[去除多余的位数，不是四舍五入，而是直接舍去]  1234523432.23 => 123,123,123.23
  * @param {number} number 待转换的金额数字

package/lib/index.js

@@ -108,39 +108,6 @@ export class BaseError extends Error {
         }
     }
 }
-/**
- * 函数节流 - 每隔单位时间，只执行一次
- * @param cb    待节流的函数
- * @param wait  间隔时间
- * @returns
- */
-export function throttle(fn, wait = 500) {
-    // 上一次的请求时间
-    let last = 0;
-    return (...args) => {
-        // 当前时间戳
-        const now = Date.now();
-        if (now - last > wait) {
-            fn(...args);
-            last = now;
-        }
-    };
-}
-/**
- * 函数防抖 - 当重复触发某一个行为（事件时），只执行最后一次触发
- * @param fn        防抖函数
- * @param interval  间隔时间段
- * @returns
- */
-export function debounce(fn, interval = 500) {
-    let _t = -1;
-    return (...args) => {
-        clearTimeout(_t);
-        _t = setTimeout(() => {
-            fn(...args);
-        }, interval);
-    };
-}
 /**
  * 将金额数字格式化为金额格式显示并且会保留两位小数[去除多余的位数，不是四舍五入，而是直接舍去]  1234523432.23 => 123,123,123.23
  * @param {number} number 待转换的金额数字

package/lib/web.d.ts

@@ -11,3 +11,17 @@ export declare const formJson: <T>(form: HTMLFormElement) => T;
 export declare function query(search?: string): {
     [index: string]: string;
 };
+/**
+ * 函数节流 - 每隔单位时间，只执行一次
+ * @param cb    待节流的函数
+ * @param wait  间隔时间
+ * @returns
+ */
+export declare function throttle<R extends any[], T>(fn: (...args: R) => T, wait?: number): (...args: R) => void;
+/**
+ * 函数防抖 - 当重复触发某一个行为（事件时），只执行最后一次触发
+ * @param fn        防抖函数
+ * @param interval  间隔时间段
+ * @returns
+ */
+export declare function debounce<R extends any[], T>(fn: (...args: R) => T, interval?: number): (...args: R) => void;

package/lib/web.js

@@ -55,3 +55,36 @@ export function query(search) {
     }
     return query;
 }
+/**
+ * 函数节流 - 每隔单位时间，只执行一次
+ * @param cb    待节流的函数
+ * @param wait  间隔时间
+ * @returns
+ */
+export function throttle(fn, wait = 500) {
+    // 上一次的请求时间
+    let last = 0;
+    return (...args) => {
+        // 当前时间戳
+        const now = Date.now();
+        if (now - last > wait) {
+            fn(...args);
+            last = now;
+        }
+    };
+}
+/**
+ * 函数防抖 - 当重复触发某一个行为（事件时），只执行最后一次触发
+ * @param fn        防抖函数
+ * @param interval  间隔时间段
+ * @returns
+ */
+export function debounce(fn, interval = 500) {
+    let _t = -1;
+    return (...args) => {
+        clearTimeout(_t);
+        _t = setTimeout(() => {
+            fn(...args);
+        }, interval);
+    };
+}

package/package.json

@@ -5,7 +5,34 @@
   "module": "lib/index.js",
   "types": "lib/index.d.ts",
   "browser": "lib/index.js",
-  "version": "0.3.1",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./file": {
+      "types": "./lib/file.d.ts",
+      "import": "./lib/file.js"
+    },
+    "./date": {
+      "types": "./lib/date.d.ts",
+      "import": "./lib/date.js"
+    },
+    "./validator": {
+      "types": "./lib/validator.d.ts",
+      "import": "./lib/validator.js"
+    },
+    "./crypto": {
+      "types": "./lib/crypto.d.ts",
+      "import": "./lib/crypto.js"
+    },
+    "./crypto_node": {
+      "types": "./lib/crypto_node.d.ts",
+      "import": "./lib/crypto_node.js"
+    },
+    "./*": "./lib/*"
+  },
+  "version": "0.3.3",
   "type": "module",
   "repository": {
     "type": "git",