vanilla-jui 1.6.6 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-jui",
-  "version": "1.6.6",
+  "version": "1.7.0",
   "private": false,
   "description": "A lightweight, reactive, and fully customizable vanilla JS UI library.",
   "keywords": [

package/src/utilities/id.ts

@@ -55,3 +55,76 @@ export function randomId(length: number = 8): string {
 
   return base64.substring(0, length).replace(/\+/g, '-').replace(/\//g, '_');
 }
+
+/**
+ * 查询参数值类型
+ */
+type QueryParamValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | QueryParamValue[]
+  | { [key: string]: QueryParamValue };
+
+/**
+ * 查询参数对象类型
+ */
+type QueryParams = Record<string, QueryParamValue>;
+
+/**
+ * 对查询参数进行 SHA-256 哈希编码，生成用于缓存的 key
+ *
+ * @param params - 查询参数对象
+ * @param bytes - 取哈希前 N 字节，默认为 8，范围 1-32
+ * @returns 36 进制哈希字符串
+ *
+ * @example
+ * ```typescript
+ * const key = await hashQueryParams({ page: 1, sort: 'desc' });
+ * // 返回: "2k7x9f3m4n5p"
+ * ```
+ */
+export async function hashQueryParams(
+  params: QueryParams,
+  bytes: number = 8
+): Promise<string> {
+  // 1. 参数验证
+  if (typeof params !== 'object' || params === null) {
+    throw new TypeError('params must be a non-null object');
+  }
+
+  if (bytes < 1 || bytes > 32) {
+    throw new RangeError('bytes must be between 1 and 32');
+  }
+
+  // 2. 排序并规范化参数
+  const normalized: QueryParams = {};
+  const sortedKeys = Object.keys(params).sort();
+
+  for (const key of sortedKeys) {
+    const value = params[key];
+    // 字符串 trim 处理
+    normalized[key] = typeof value === 'string' ? value.trim() : value;
+  }
+
+  // 3. 序列化
+  const str = JSON.stringify(normalized);
+  const buffer = new TextEncoder().encode(str);
+
+  // 4. SHA-256 哈希
+  const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
+
+  // 5. 取前 N 字节（防越界）
+  const safeBytes = Math.min(bytes, hashBuffer.byteLength);
+  const slice = new Uint8Array(hashBuffer, 0, safeBytes);
+
+  // 6. 转为 BigInt 再转 36 进制
+  let num = 0n;
+  for (const byte of slice) {
+    num = (num << 8n) | BigInt(byte);
+  }
+
+  return num.toString(36);
+}