@anjianshi/utils 1.2.6 → 1.3.0

package/src/lang/types.ts

@@ -16,24 +16,16 @@ export function tuple<T extends unknown[]>(...elements: T) {
   return elements
 }
 
-/**
- * 将一个对象中的指定 key 设为必须的
- */
+/** 将一个对象中的指定 key 设为必须的 */
 export type RequiredFields<T, K extends keyof T> = Omit<T, K> & Pick<Required<T>, K>
 
-/**
- * 将一个对象中的指定 key 设为非必须的
- */
+/** 将一个对象中的指定 key 设为非必须的 */
 export type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
 
-/**
- * 用 ReplaceT 中的字段定义代替 T 中的
- */
+/** 用 ReplaceT 中的字段定义代替 T 中的 */
 export type ReplaceFields<T, ReplaceT> = Omit<T, keyof ReplaceT> & ReplaceT
 
-/**
- * 获取一个对象所有 value 的集合
- */
+/** 获取一个对象所有 value 的集合 */
 export type ValueOf<T> = T extends { [_ in keyof T]: infer U } ? U : never
 
 /**
@@ -49,60 +41,25 @@ export type KnownKeys<T> = ValueOf<{
   [K in keyof T]: string extends K ? never : number extends K ? never : K
 }>
 
-/**
- * 排除对象中指定类型的项目
- */
+/** 排除对象中指定类型的项目 */
 export type ExcludePropertiesOfType<T, ExcludeValueT> = Pick<
   T,
   { [K in keyof T]: T[K] extends ExcludeValueT ? never : K }[keyof T]
 >
 
 /**
- * 排除对象的方法（仅保留属性）
+ * 生成不包含指定 key 的类型
+ * 与 Omit<T, Keys> 的区别是
  */
+export type ExcludeKeys<T, ExcludeKeys> = Pick<
+  T,
+  { [K in keyof T]: K extends ExcludeKeys ? never : K }[keyof T]
+>
+
+/** 排除对象的方法（仅保留属性） */
 // eslint-disable-next-line @typescript-eslint/ban-types
 export type ExcluceMethods<T> = ExcludePropertiesOfType<T, Function>
 
-/**
- * 所有“可能失败”的操作都可使用此类型作为返回值
- */
-export interface Success<T = void> {
-  success: true
-  data: T
-}
-export interface Failed<ET = string> {
-  success: false
-  error: ET
-  code?: number | string
-}
-export type MaySuccess<T = void, ET = string> = Success<T> | Failed<ET>
-
-function success(): Success
-function success<T>(data: T): Success<T>
-function success<T = void>(data?: T) {
-  return { success: true, data }
-}
-export { success }
-
-export function failed<ET>(error: ET, code?: number | string): Failed<ET> {
-  return { success: false, error, code }
-}
-
-/**
- * 若传入值为 success，格式化其 data；否则原样返回错误
- * 支持传入会返回 MaySuccess 的 Promise
- */
-function formatSuccess<T, ET, FT>(item: MaySuccess<T, ET>, formatter: (data: T) => FT): MaySuccess<FT, ET> // prettier-ignore
-function formatSuccess<T, ET, FT>(item: Promise<MaySuccess<T, ET>>, formatter: (data: T) => FT): Promise<MaySuccess<FT, ET>> // prettier-ignore
-function formatSuccess<T, ET, FT>(
-  item: MaySuccess<T, ET> | Promise<MaySuccess<T, ET>>,
-  formatter: (data: T) => FT
-) {
-  if ('then' in item) return item.then(finalItem => formatSuccess(finalItem, formatter))
-  return item.success ? { ...item, data: formatter(item.data) } : item
-}
-export { formatSuccess }
-
 /**
  * 确认变量是否有值
  * 注意：空字符串和数字 0 也会判定为没有值
@@ -118,9 +75,7 @@ function truthy<T>(value: T | string | number | boolean | null | undefined) {
 }
 export { truthy }
 
-/**
- * 定义 JSON 数据
- */
+/** 定义 JSON 数据 */
 export type JSONData = number | boolean | string | null | JSONData[] | { [key: string]: JSONData }
 
 /**

package/src/logging/index.ts

@@ -44,7 +44,7 @@ export class Logger {
 
   static getRealLevel(raw: LogLevel | string) {
     if (typeof raw === 'string') {
-      raw = raw.toLocaleLowerCase()
+      raw = raw.toLowerCase()
       if (logLevelMap[raw] === undefined) throw new Error('Not supported log level: ' + raw)
       return logLevelMap[raw]!
     }

package/src/md5.ts

@@ -0,0 +1,319 @@
+/* eslint-disable no-multi-assign, @typescript-eslint/restrict-plus-operands */
+/**
+ * MD5 算法来自：https://github.com/emn178/js-md5
+ */
+
+export function md5(content: string | ArrayBuffer) {
+  const md5 = new MD5()
+  md5.update(content)
+  return md5.hex()
+}
+
+// -------------------------------------------------------------------
+
+/**
+ * 使用方法：
+ * const md5 = new MD5()
+ * md5.update(xxx)  // 对于大文件，可以拆分开，多次调用 md5.update()
+ * const hash = md5.hex()
+ */
+export class MD5 {
+  private readonly buffer8: Uint8Array
+  private readonly blocks: Uint32Array
+
+  private h0 = 0
+  private h1 = 0
+  private h2 = 0
+  private h3 = 0
+  private start = 0
+  private bytes = 0
+  private hBytes = 0
+  private lastByteIndex = 0
+
+  private finalized = false
+  private hashed = false
+  private first = true
+
+  constructor() {
+    const buffer = new ArrayBuffer(68)
+    this.buffer8 = new Uint8Array(buffer)
+    this.blocks = new Uint32Array(buffer)
+  }
+
+  update(message: string | number[] | Uint8Array | ArrayBuffer) {
+    if (this.finalized) return
+
+    if (message instanceof ArrayBuffer) {
+      message = new Uint8Array(message)
+    }
+    if (typeof message !== 'string' && !Array.isArray(message) && !ArrayBuffer.isView(message)) {
+      throw new Error('input is invalid type')
+    }
+
+    const length = message.length
+    const { blocks, buffer8 } = this
+
+    let code: number
+    let index = 0
+    let i: number
+
+    while (index < length) {
+      if (this.hashed) {
+        this.hashed = false
+        blocks[0] = blocks[16]!
+        // prettier-ignore
+        blocks[16] = blocks[1] = blocks[2] = blocks[3] = blocks[4] = blocks[5] =
+          blocks[6] = blocks[7] = blocks[8] = blocks[9] = blocks[10] =
+          blocks[11] = blocks[12] = blocks[13] = blocks[14] = blocks[15] = 0
+      }
+
+      if (typeof message !== 'string') {
+        for (i = this.start; index < length && i < 64; ++index) {
+          buffer8[i++] = message[index]!
+        }
+      } else {
+        for (i = this.start; index < length && i < 64; ++index) {
+          code = message.charCodeAt(index)
+          if (code < 0x80) {
+            buffer8[i++] = code
+          } else if (code < 0x800) {
+            buffer8[i++] = 0xc0 | (code >> 6)
+            buffer8[i++] = 0x80 | (code & 0x3f)
+          } else if (code < 0xd800 || code >= 0xe000) {
+            buffer8[i++] = 0xe0 | (code >> 12)
+            buffer8[i++] = 0x80 | ((code >> 6) & 0x3f)
+            buffer8[i++] = 0x80 | (code & 0x3f)
+          } else {
+            code = 0x10000 + (((code & 0x3ff) << 10) | (message.charCodeAt(++index) & 0x3ff))
+            buffer8[i++] = 0xf0 | (code >> 18)
+            buffer8[i++] = 0x80 | ((code >> 12) & 0x3f)
+            buffer8[i++] = 0x80 | ((code >> 6) & 0x3f)
+            buffer8[i++] = 0x80 | (code & 0x3f)
+          }
+        }
+      }
+      this.lastByteIndex = i
+      this.bytes += i - this.start
+      if (i >= 64) {
+        this.start = i - 64
+        this.hash()
+        this.hashed = true
+      } else {
+        this.start = i
+      }
+    }
+    if (this.bytes > 4294967295) {
+      this.hBytes += (this.bytes / 4294967296) << 0
+      this.bytes = this.bytes % 4294967296
+    }
+  }
+
+  private finalize() {
+    if (this.finalized) return
+    this.finalized = true
+    const { blocks } = this
+    const i = this.lastByteIndex
+    const EXTRA = [128, 32768, 8388608, -2147483648]
+    blocks[i >> 2] |= EXTRA[i & 3]!
+    if (i >= 56) {
+      if (!this.hashed) this.hash()
+      blocks[0] = blocks[16]!
+      // prettier-ignore
+      blocks[16] = blocks[1] = blocks[2] = blocks[3] = blocks[4] = blocks[5] =
+        blocks[6] = blocks[7] = blocks[8] = blocks[9] = blocks[10] =
+        blocks[11] = blocks[12] = blocks[13] = blocks[14] = blocks[15] = 0
+    }
+    blocks[14] = this.bytes << 3
+    blocks[15] = (this.hBytes << 3) | (this.bytes >>> 29)
+    this.hash()
+  }
+
+  private hash() {
+    let a: number, b: number, c: number, d: number, bc: number, da: number
+    const { blocks } = this
+
+    if (this.first) {
+      a = blocks[0]! - 680876937
+      a = (((a << 7) | (a >>> 25)) - 271733879) << 0
+      d = (-1732584194 ^ (a & 2004318071)) + blocks[1]! - 117830708
+      d = (((d << 12) | (d >>> 20)) + a) << 0
+      c = (-271733879 ^ (d & (a ^ -271733879))) + blocks[2]! - 1126478375
+      c = (((c << 17) | (c >>> 15)) + d) << 0
+      b = (a ^ (c & (d ^ a))) + blocks[3]! - 1316259209
+      b = (((b << 22) | (b >>> 10)) + c) << 0
+    } else {
+      a = this.h0
+      b = this.h1
+      c = this.h2
+      d = this.h3
+      a += (d ^ (b & (c ^ d))) + blocks[0]! - 680876936
+      a = (((a << 7) | (a >>> 25)) + b) << 0
+      d += (c ^ (a & (b ^ c))) + blocks[1]! - 389564586
+      d = (((d << 12) | (d >>> 20)) + a) << 0
+      c += (b ^ (d & (a ^ b))) + blocks[2]! + 606105819
+      c = (((c << 17) | (c >>> 15)) + d) << 0
+      b += (a ^ (c & (d ^ a))) + blocks[3]! - 1044525330
+      b = (((b << 22) | (b >>> 10)) + c) << 0
+    }
+
+    a += (d ^ (b & (c ^ d))) + blocks[4]! - 176418897
+    a = (((a << 7) | (a >>> 25)) + b) << 0
+    d += (c ^ (a & (b ^ c))) + blocks[5]! + 1200080426
+    d = (((d << 12) | (d >>> 20)) + a) << 0
+    c += (b ^ (d & (a ^ b))) + blocks[6]! - 1473231341
+    c = (((c << 17) | (c >>> 15)) + d) << 0
+    b += (a ^ (c & (d ^ a))) + blocks[7]! - 45705983
+    b = (((b << 22) | (b >>> 10)) + c) << 0
+    a += (d ^ (b & (c ^ d))) + blocks[8]! + 1770035416
+    a = (((a << 7) | (a >>> 25)) + b) << 0
+    d += (c ^ (a & (b ^ c))) + blocks[9]! - 1958414417
+    d = (((d << 12) | (d >>> 20)) + a) << 0
+    c += (b ^ (d & (a ^ b))) + blocks[10]! - 42063
+    c = (((c << 17) | (c >>> 15)) + d) << 0
+    b += (a ^ (c & (d ^ a))) + blocks[11]! - 1990404162
+    b = (((b << 22) | (b >>> 10)) + c) << 0
+    a += (d ^ (b & (c ^ d))) + blocks[12]! + 1804603682
+    a = (((a << 7) | (a >>> 25)) + b) << 0
+    d += (c ^ (a & (b ^ c))) + blocks[13]! - 40341101
+    d = (((d << 12) | (d >>> 20)) + a) << 0
+    c += (b ^ (d & (a ^ b))) + blocks[14]! - 1502002290
+    c = (((c << 17) | (c >>> 15)) + d) << 0
+    b += (a ^ (c & (d ^ a))) + blocks[15]! + 1236535329
+    b = (((b << 22) | (b >>> 10)) + c) << 0
+    a += (c ^ (d & (b ^ c))) + blocks[1]! - 165796510
+    a = (((a << 5) | (a >>> 27)) + b) << 0
+    d += (b ^ (c & (a ^ b))) + blocks[6]! - 1069501632
+    d = (((d << 9) | (d >>> 23)) + a) << 0
+    c += (a ^ (b & (d ^ a))) + blocks[11]! + 643717713
+    c = (((c << 14) | (c >>> 18)) + d) << 0
+    b += (d ^ (a & (c ^ d))) + blocks[0]! - 373897302
+    b = (((b << 20) | (b >>> 12)) + c) << 0
+    a += (c ^ (d & (b ^ c))) + blocks[5]! - 701558691
+    a = (((a << 5) | (a >>> 27)) + b) << 0
+    d += (b ^ (c & (a ^ b))) + blocks[10]! + 38016083
+    d = (((d << 9) | (d >>> 23)) + a) << 0
+    c += (a ^ (b & (d ^ a))) + blocks[15]! - 660478335
+    c = (((c << 14) | (c >>> 18)) + d) << 0
+    b += (d ^ (a & (c ^ d))) + blocks[4]! - 405537848
+    b = (((b << 20) | (b >>> 12)) + c) << 0
+    a += (c ^ (d & (b ^ c))) + blocks[9]! + 568446438
+    a = (((a << 5) | (a >>> 27)) + b) << 0
+    d += (b ^ (c & (a ^ b))) + blocks[14]! - 1019803690
+    d = (((d << 9) | (d >>> 23)) + a) << 0
+    c += (a ^ (b & (d ^ a))) + blocks[3]! - 187363961
+    c = (((c << 14) | (c >>> 18)) + d) << 0
+    b += (d ^ (a & (c ^ d))) + blocks[8]! + 1163531501
+    b = (((b << 20) | (b >>> 12)) + c) << 0
+    a += (c ^ (d & (b ^ c))) + blocks[13]! - 1444681467
+    a = (((a << 5) | (a >>> 27)) + b) << 0
+    d += (b ^ (c & (a ^ b))) + blocks[2]! - 51403784
+    d = (((d << 9) | (d >>> 23)) + a) << 0
+    c += (a ^ (b & (d ^ a))) + blocks[7]! + 1735328473
+    c = (((c << 14) | (c >>> 18)) + d) << 0
+    b += (d ^ (a & (c ^ d))) + blocks[12]! - 1926607734
+    b = (((b << 20) | (b >>> 12)) + c) << 0
+    bc = b ^ c
+    a += (bc ^ d) + blocks[5]! - 378558
+    a = (((a << 4) | (a >>> 28)) + b) << 0
+    d += (bc ^ a) + blocks[8]! - 2022574463
+    d = (((d << 11) | (d >>> 21)) + a) << 0
+    da = d ^ a
+    c += (da ^ b) + blocks[11]! + 1839030562
+    c = (((c << 16) | (c >>> 16)) + d) << 0
+    b += (da ^ c) + blocks[14]! - 35309556
+    b = (((b << 23) | (b >>> 9)) + c) << 0
+    bc = b ^ c
+    a += (bc ^ d) + blocks[1]! - 1530992060
+    a = (((a << 4) | (a >>> 28)) + b) << 0
+    d += (bc ^ a) + blocks[4]! + 1272893353
+    d = (((d << 11) | (d >>> 21)) + a) << 0
+    da = d ^ a
+    c += (da ^ b) + blocks[7]! - 155497632
+    c = (((c << 16) | (c >>> 16)) + d) << 0
+    b += (da ^ c) + blocks[10]! - 1094730640
+    b = (((b << 23) | (b >>> 9)) + c) << 0
+    bc = b ^ c
+    a += (bc ^ d) + blocks[13]! + 681279174
+    a = (((a << 4) | (a >>> 28)) + b) << 0
+    d += (bc ^ a) + blocks[0]! - 358537222
+    d = (((d << 11) | (d >>> 21)) + a) << 0
+    da = d ^ a
+    c += (da ^ b) + blocks[3]! - 722521979
+    c = (((c << 16) | (c >>> 16)) + d) << 0
+    b += (da ^ c) + blocks[6]! + 76029189
+    b = (((b << 23) | (b >>> 9)) + c) << 0
+    bc = b ^ c
+    a += (bc ^ d) + blocks[9]! - 640364487
+    a = (((a << 4) | (a >>> 28)) + b) << 0
+    d += (bc ^ a) + blocks[12]! - 421815835
+    d = (((d << 11) | (d >>> 21)) + a) << 0
+    da = d ^ a
+    c += (da ^ b) + blocks[15]! + 530742520
+    c = (((c << 16) | (c >>> 16)) + d) << 0
+    b += (da ^ c) + blocks[2]! - 995338651
+    b = (((b << 23) | (b >>> 9)) + c) << 0
+    a += (c ^ (b | ~d)) + blocks[0]! - 198630844
+    a = (((a << 6) | (a >>> 26)) + b) << 0
+    d += (b ^ (a | ~c)) + blocks[7]! + 1126891415
+    d = (((d << 10) | (d >>> 22)) + a) << 0
+    c += (a ^ (d | ~b)) + blocks[14]! - 1416354905
+    c = (((c << 15) | (c >>> 17)) + d) << 0
+    b += (d ^ (c | ~a)) + blocks[5]! - 57434055
+    b = (((b << 21) | (b >>> 11)) + c) << 0
+    a += (c ^ (b | ~d)) + blocks[12]! + 1700485571
+    a = (((a << 6) | (a >>> 26)) + b) << 0
+    d += (b ^ (a | ~c)) + blocks[3]! - 1894986606
+    d = (((d << 10) | (d >>> 22)) + a) << 0
+    c += (a ^ (d | ~b)) + blocks[10]! - 1051523
+    c = (((c << 15) | (c >>> 17)) + d) << 0
+    b += (d ^ (c | ~a)) + blocks[1]! - 2054922799
+    b = (((b << 21) | (b >>> 11)) + c) << 0
+    a += (c ^ (b | ~d)) + blocks[8]! + 1873313359
+    a = (((a << 6) | (a >>> 26)) + b) << 0
+    d += (b ^ (a | ~c)) + blocks[15]! - 30611744
+    d = (((d << 10) | (d >>> 22)) + a) << 0
+    c += (a ^ (d | ~b)) + blocks[6]! - 1560198380
+    c = (((c << 15) | (c >>> 17)) + d) << 0
+    b += (d ^ (c | ~a)) + blocks[13]! + 1309151649
+    b = (((b << 21) | (b >>> 11)) + c) << 0
+    a += (c ^ (b | ~d)) + blocks[4]! - 145523070
+    a = (((a << 6) | (a >>> 26)) + b) << 0
+    d += (b ^ (a | ~c)) + blocks[11]! - 1120210379
+    d = (((d << 10) | (d >>> 22)) + a) << 0
+    c += (a ^ (d | ~b)) + blocks[2]! + 718787259
+    c = (((c << 15) | (c >>> 17)) + d) << 0
+    b += (d ^ (c | ~a)) + blocks[9]! - 343485551
+    b = (((b << 21) | (b >>> 11)) + c) << 0
+
+    if (this.first) {
+      this.h0 = (a + 1732584193) << 0
+      this.h1 = (b - 271733879) << 0
+      this.h2 = (c - 1732584194) << 0
+      this.h3 = (d + 271733878) << 0
+      this.first = false
+    } else {
+      this.h0 = (this.h0 + a) << 0
+      this.h1 = (this.h1 + b) << 0
+      this.h2 = (this.h2 + c) << 0
+      this.h3 = (this.h3 + d) << 0
+    }
+  }
+
+  hex() {
+    this.finalize()
+
+    const { h0, h1, h2, h3 } = this
+    const HEX_CHARS = '0123456789abcdef'.split('')
+    return (
+      // prettier-ignore
+      // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+      HEX_CHARS[(h0 >> 4) & 0x0f] + HEX_CHARS[h0 & 0x0f]! + HEX_CHARS[(h0 >> 12) & 0x0f] + HEX_CHARS[(h0 >> 8) & 0x0f] + HEX_CHARS[(h0 >> 20) & 0x0f] +
+      HEX_CHARS[(h0 >> 16) & 0x0f] + HEX_CHARS[(h0 >> 28) & 0x0f] + HEX_CHARS[(h0 >> 24) & 0x0f] + HEX_CHARS[(h1 >> 4) & 0x0f] + HEX_CHARS[h1 & 0x0f] +
+      HEX_CHARS[(h1 >> 12) & 0x0f] + HEX_CHARS[(h1 >> 8) & 0x0f] + HEX_CHARS[(h1 >> 20) & 0x0f] + HEX_CHARS[(h1 >> 16) & 0x0f] + HEX_CHARS[(h1 >> 28) & 0x0f] +
+      HEX_CHARS[(h1 >> 24) & 0x0f] + HEX_CHARS[(h2 >> 4) & 0x0f] + HEX_CHARS[h2 & 0x0f] + HEX_CHARS[(h2 >> 12) & 0x0f] + HEX_CHARS[(h2 >> 8) & 0x0f] +
+      HEX_CHARS[(h2 >> 20) & 0x0f] + HEX_CHARS[(h2 >> 16) & 0x0f] + HEX_CHARS[(h2 >> 28) & 0x0f] + HEX_CHARS[(h2 >> 24) & 0x0f] + HEX_CHARS[(h3 >> 4) & 0x0f] +
+      HEX_CHARS[h3 & 0x0f] + HEX_CHARS[(h3 >> 12) & 0x0f] + HEX_CHARS[(h3 >> 8) & 0x0f] + HEX_CHARS[(h3 >> 20) & 0x0f] + HEX_CHARS[(h3 >> 16) & 0x0f] +
+      HEX_CHARS[(h3 >> 28) & 0x0f] + HEX_CHARS[(h3 >> 24) & 0x0f]
+    )
+  }
+}

package/src/url.ts

@@ -9,47 +9,43 @@
  */
 import isPlainObject from 'lodash/isPlainObject.js'
 
-/*
-从字符串中解析出 query 对象
-
-array:
-- 若开启，支持解析 a[]=1&a[]=2 格式的参数，会解析成一个数组 { a: ['1', '2'] }
-- 否则把 `a[]` 整体当做一个参数名 { 'a[]': '2' }
-
-strict:
-是否开启“严格模式”（默认不开启）。
-在非严格模式下，会做很多兼容处理：
-1. 支持直接传入 query string（a=1&b=2）；严格模式下，则需在开头补充一个 ?（?a=1&b=2）
-2. hash 里的内容也会被解析，以兼容拼接错误的 URL（把 query 拼到了 hash 后面）。
-3. 出现多个 ? 符号时，会把 ? 也当做 & 分隔符（index.html?a=1&b=2?c=3）
-
-小技巧：
-在非严格模式下，如果明确只想解析 hash 或 search 里的内容，可以传入 location.search / hash 而不是传入整个 location.href
-
-此函数不会对 query 值进行 decode，需自定处理
-*/
-function parseQuery(url: string, options?: { array?: false, strict?: boolean }): Record<string, string> // prettier-ignore
-function parseQuery(url: string, options: { array: true, strict?: boolean }): Record<string, string | string[]> // prettier-ignore
+/**
+ * 从 URL 中解析出 query 对象
+ * 注意：不带 ? 号的纯 query 内容需手动加上 ? 再传入。
+ *
+ * [array]
+ * 是否把重复出现的 key 保存为数组（默认不开启）
+ * a=1&a=2 => { a: [1,2] }
+ *
+ * [loose]
+ * 是否开启“宽松模式”（默认不开启）
+ * 1. hash 里的内容也会被解析，以兼容拼接错误的 URL（把 query 拼到了 hash 后面）。
+ * 2. 出现多个 ? 符号时，会把 ? 也当做 & 分隔符（index.html?a=1&b=2?c=3）
+ *
+ * [decode]
+ * 是否对 query 值进行 decode（默认开启）
+ */
+function parseQuery(url: string, options?: { array?: false, loose?: boolean, decode?: boolean }): Record<string, string> // prettier-ignore
+function parseQuery(url: string, options: { array: true, loose?: boolean, decode?: boolean }): Record<string, string | string[]> // prettier-ignore
 function parseQuery(
   url: string,
-  options?: { array?: boolean; strict?: boolean }
+  options?: { array?: boolean; loose?: boolean; decode?: boolean }
 ): Record<string, string | string[]> {
-  if (!url) return {}
-  const { array = false, strict = false } = options ?? {}
+  const { array = false, loose = false, decode = true } = options ?? {}
 
-  const queryString = strict
-    ? (/^[^?#]*\?(.+?)(\?|#|$)/.exec(url) ?? ['', ''])[1] // 排除 hash、重复的 ? 符号
-    : url
+  // 正常状态下，将仅剩 a=1&b=1（即不会再有 ? 和 #）；loose 模型下，可能为 a=1&b=2#c=3?d=4
+  const queryString = (loose ? /(\?|#)(.+)/ : /(\?)(.+?)(#|$)/).exec(url)?.[2] ?? ''
+  if (!queryString) return {}
 
   const query: { [name: string]: string | string[] } = {}
   const reg = /([^#?&]*)=([^#?&]*)/g
   let re = reg.exec(queryString)
   while (re) {
-    const [name, value] = [re[1]!, re[2]!]
-    if (name.endsWith('[]') && array) {
-      const realName = name.slice(0, -2)
-      if (Array.isArray(query[realName])) (query[realName] as string[]).push(value)
-      else query[realName] = [value]
+    const [name, rawValue] = [re[1]!, re[2]!] as [string, string]
+    const value = decode ? safeDecode(rawValue) : rawValue
+    if (array && query[name] !== undefined) {
+      const prev = query[name]!
+      query[name] = Array.isArray(prev) ? [...prev, value] : [prev, value]
     } else {
       query[name] = value
     }
@@ -59,35 +55,35 @@ function parseQuery(
 }
 export { parseQuery }
 
-/**
- * 取 query 中指定参数的值
- * - 参数存在，返回参数值（可能是空字符串）；不存在返回 null
- * - 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
- * - 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
- */
-export function getQueryParam(name: string, url: string): string | null {
-  const query = parseQuery(url)
-  return typeof query[name] === 'string' ? query[name]! : null
-}
-
 /**
  * 把对象合并成 query string。
- * 支持字符串、数值、布尔值（不建议，考虑用 0 和 1 代替），数组会转换成 name[]=value 的格式
+ * - 支持字符串、数值、布尔值、数组。
+ * - 布尔值会替换成 0 和 1。
+ * - 数组会多次赋值：{ a: [1,2,3] } => 'a=1&a=2&a=3'，不支持嵌套数组
+ * - encode 为 true 时会对 value 执行 encodeURIComponent（默认为 true）
  */
 type StringifyVal = string | number | boolean
-export function stringifyQuery(obj: { [key: string]: StringifyVal | StringifyVal[] | undefined }) {
+type StringifyQuery = { [key: string]: StringifyVal | StringifyVal[] | undefined }
+export function stringifyQuery(obj: StringifyQuery, encode = true) {
   if (!isPlainObject(obj)) return ''
   return (
     Object.entries(obj)
       // 过滤值为 undefined 的项目，使其完全不出现在最终的 query 中
       .filter((entry): entry is [string, StringifyVal | StringifyVal[]] => entry[1] !== undefined)
-      .map(([name, value]) => stringifyQueryItem(name, value))
+      .map(([name, value]) => stringifyQueryItem(name, value, encode))
       .join('&')
   )
 }
-function stringifyQueryItem(name: string, value: StringifyVal | StringifyVal[]): string {
+function stringifyQueryItem(
+  name: string,
+  value: StringifyVal | StringifyVal[],
+  encode: boolean
+): string {
   if (Array.isArray(value))
-    return value.map(subValue => stringifyQueryItem(`${name}[]`, subValue)).join('&')
+    return value.map(subValue => stringifyQueryItem(name, subValue, encode)).join('&')
+  if (typeof value === 'boolean') value = value ? '1' : '0'
+  if (typeof value === 'number') value = value.toString()
+  if (encode) value = encodeURIComponent(value)
   return `${name}=${value}`
 }
 
@@ -96,6 +92,7 @@ function stringifyQueryItem(name: string, value: StringifyVal | StringifyVal[]):
  *
  * bare 为 true，则 search 不带 '?'，hash 不带 '#'
  * 否则和 location.search / hash 一样
+ * （默认为 true）
  */
 export function splitUrl(url: string, bare = true): { base: string; search: string; hash: string } {
   let hashIndex = url.indexOf('#')
@@ -114,16 +111,12 @@ export function splitUrl(url: string, bare = true): { base: string; search: stri
 }
 
 /**
- * 把指定 query 和 hash 内容合并到 url 上
+ * 把 query 和 hash 内容合并到 url 上
  *
  * query   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
- * hash    string    若 url 已有 hash，会用此值代替。带不带开头的 '?' 皆可。
+ * hash    string    带不带开头的 '#' 皆可。会代替 url 已有的 hash。
  */
-export function combineUrl(
-  origUrl: string,
-  query: Record<string, string | string[]> = {},
-  hash: string = ''
-) {
+export function combineUrl(origUrl: string, query: StringifyQuery = {}, hash: string = '') {
   if (hash.startsWith('#')) hash = hash.slice(1)
 
   // 拆分原 url 的 search、hash

package/src/validators/array.ts

@@ -0,0 +1,62 @@
+import { success, failed } from '../lang/index.js'
+import { Validator } from './base.js'
+
+/** 验证元素数量任意、元素类型相同的数组 */
+export type ArrayOptions = {
+  /** 验证数组各元素 */
+  item: Validator
+  /** 数组最小长度 */
+  min?: number
+  /** 数组最大长度 */
+  max?: number
+  /** 是否对数组元素进行去重 @defaults false */
+  unique?: boolean
+}
+
+/** 验证元素数量固定、类型可以不同的数组 */
+export type TupleOptions = {
+  /** 验证数组各元素（validator 与元素一一对应） */
+  tuple: Validator[]
+}
+
+export class ArrayValidator extends Validator<ArrayOptions | TupleOptions> {
+  validate(field: string, value: unknown) {
+    const superResult = super.validate(field, value)
+    if (!superResult.success) return superResult
+
+    value = superResult.data
+    if (value === null || value === undefined) return superResult
+    const opt = this.options
+
+    if (!Array.isArray(value)) return failed(`${field} should be an array`)
+
+    let formatted = []
+    if ('item' in opt) {
+      if (typeof opt.min === 'number' && value.length < opt.min)
+        return failed(`array ${field}'s length should >= ${opt.min}`)
+
+      if (typeof opt.max === 'number' && value.length > opt.max)
+        return failed(`array ${field}'s length should <= ${opt.max}`)
+
+      for (let i = 0; i < value.length; i++) {
+        const itemResult = opt.item.validate(`${field}[${i}]`, value[i])
+        if (itemResult.success) formatted.push(itemResult.data)
+        else return itemResult
+      }
+
+      if (opt.unique === true) formatted = [...new Set(formatted)]
+    } else {
+      if (value.length > opt.tuple.length)
+        return failed(`${field} should be a tuple with ${opt.tuple.length} items`)
+
+      // 这种情况不能遍历 value，因为它的长度可能小于 opt.tuple
+      for (let i = 0; i < opt.tuple.length; i++) {
+        const itemResult = opt.tuple[i]!.validate(`${field}[${i}]`, value[i])
+        if (itemResult.success) formatted.push(itemResult.data)
+        else return itemResult
+      }
+    }
+
+    return success(formatted)
+  }
+}