@anjianshi/utils 2.9.1 → 3.0.0

package/src/md5.ts

@@ -0,0 +1,318 @@
+/* eslint-disable no-multi-assign */
+/**
+ * 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
+      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/safe-request.ts

@@ -0,0 +1,193 @@
+import { sleep } from './lang/async.js'
+import { failed, handleException, type Result } from './lang/result.js'
+import { getLogger, type Logger } from './logging/index.js'
+import { combineUrl } from './url.js'
+
+export type { Options as RequestOptions, FormattedOptions as RequestFormattedOptions }
+
+interface Options {
+  urlPrefix?: string
+  url?: string
+  query?: Record<string, string | number | undefined>
+  method?: string
+  headers?: Record<string, string>
+  body?: string | FormData | null
+
+  /**
+   * 向后端传递的数据。对于 GET 请求，会合并到 query 中；对于 POST 请求，会作为 POST body，代替 body 参数
+   * 注意：为了支持传入 interface 类型的值，Record 只能定义成 Record<string, any>
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data?: FormData | Record<string, any>
+
+  /** 超时时间，不指定或设为 0 代表不限 */
+  timeout?: number
+}
+
+type FormattedOptions = Required<Pick<Options, 'url' | 'method' | 'headers' | 'body' | 'timeout'>>
+
+type PredefinedOptions = Pick<Options, 'urlPrefix' | 'method' | 'headers' | 'timeout'>
+
+/**
+ * 建立一个请求发起器，并可预设部分选项。
+ * 可以继承此类来自定义默认的错误处理逻辑。
+ *
+ * 请求失败时的 Failed 对象，其 code 为 HTTP status，没有 status 时为 0
+ * data 为解析出的响应内容，没有或解析失败则为 undefined
+ */
+export class SafeRequestClient {
+  readonly logger: Logger
+  readonly prefefinedOptions: PredefinedOptions
+
+  constructor(options: PredefinedOptions & { loggerName?: string } = {}) {
+    this.logger = getLogger(options.loggerName ?? 'request')
+    this.prefefinedOptions = options
+  }
+
+  /** 生成一个快捷方式函数，调用它相当于调用 client.request() */
+  asFunction() {
+    return async <T>(inputUrl: string, inputOptions?: Options) =>
+      this.request<T>(inputUrl, inputOptions)
+  }
+
+  async request<T>(inputUrl: string, inputOptions?: Options): Promise<Result<T>> {
+    const options = await this.formatOptions({
+      url: inputUrl,
+      ...(inputOptions ?? {}),
+    })
+    const { url, method, headers, body, timeout } = options
+
+    try {
+      // 发起请求
+      const request = fetch(url, { method, headers, body })
+      let response: Response | undefined
+      try {
+        response = await (typeof timeout === 'number'
+          ? Promise.race([request, sleep(timeout)])
+          : request)
+      } catch (error) {
+        // 处理“请求发起失败”
+        return this.onRequestError(error as Error, url)
+      }
+
+      // 处理超时
+      if (response === undefined) {
+        return this.onTimeout(url)
+      }
+
+      // 处理“服务端返回失败状态”
+      if (!response.status.toString().startsWith('2')) {
+        // 此时服务端仍可能输出一些内容，试着解析出来
+        const responseDataRes = await this.parseResponse<T>(options, response)
+        const responseData = responseDataRes.success ? responseDataRes.data : undefined
+        return await this.onResponseError(url, response, responseData)
+      }
+
+      // 解析响应内容
+      return await this.parseResponse<T>(options, response)
+    } catch (error) {
+      this.logger.error('Unexpected error', error)
+      return failed('Request handle failed.')
+    }
+  }
+
+  async formatOptions(input: Options): Promise<FormattedOptions> {
+    const predefined = this.prefefinedOptions
+    const {
+      urlPrefix = predefined.urlPrefix ?? '',
+      url: rawUrl,
+      query = {},
+      method = predefined.method ?? 'GET',
+      headers: rawHeaders = {},
+      body: rawBody = null,
+      data,
+      timeout = predefined.timeout ?? 0,
+    } = input
+
+    const headers = {
+      ...(predefined.headers ?? {}),
+      ...rawHeaders,
+    }
+
+    let body: string | FormData | null = rawBody
+    if (data !== undefined) {
+      if (method === 'GET') {
+        Object.assign(query, data)
+      } else {
+        body = data instanceof FormData ? data : JSON.stringify(data)
+        headers['Content-Type'] = 'application/json; charset=utf-8'
+      }
+    }
+
+    const url = combineUrl(urlPrefix + (rawUrl ?? ''), query)
+
+    const options = {
+      method,
+      url,
+      headers,
+      body,
+      timeout,
+    }
+    Object.assign(options.headers, await this.getHeaders(options, input))
+    return options
+  }
+
+  /** 请求发起前调用此方法补充 Headers 内容 */
+  protected getHeaders(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options: FormattedOptions,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    inputOptions: Options,
+  ): Record<string, string> | undefined | Promise<Record<string, string> | undefined> {
+    return undefined
+  }
+
+  protected async parseResponse<T>(options: FormattedOptions, response: Response) {
+    let result: Result<T>
+    result = await handleException(response.json())
+    if (result.success) return result
+
+    const contentType = (response.headers.get('Content-Type') ?? '').toLowerCase().trim()
+    if (contentType.startsWith('text/') || contentType === '') {
+      result = (await handleException(response.text())) as Result<T>
+      if (result.success) return result
+    }
+
+    result = (await handleException(response.arrayBuffer())) as Result<T>
+    return result
+  }
+
+  /** 若请求未成功发起，会触发此回调来生成失败信息 */
+  protected onRequestError(error: Error, url: string) {
+    this.logger.error('Request Failed', { url, error })
+    return failed('Request Failed', 0, undefined)
+  }
+
+  /** 请求成功发起，但服务端返回失败状态（如 500），会触发此回调来生成失败信息 */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  protected async onResponseError(url: string, response: Response, responseData: unknown) {
+    this.logger.error('Response Error Status', {
+      url,
+      status: response.status,
+      data: responseData,
+    })
+    return failed(`Response Error Status - ${response.status}`, response.status, responseData)
+  }
+
+  /** 服务端返回内容解析失败时，会触发此回调来生成失败信息 */
+  protected onParseFailed(error: Error, response: Response, url: string) {
+    this.logger.error('Response Parse Failed', { url, response, error })
+    return failed('Response Parse Failed', response.status, undefined)
+  }
+
+  /** 处理超时 */
+  protected onTimeout(url: string) {
+    this.logger.warn('Request Timeout', url)
+    return failed('Request Timeout', 0, undefined)
+  }
+}
+
+/**
+ * 模块自带一个可直接调用发起请求的函数，跳过初始化实例
+ */
+export const safeRequest = new SafeRequestClient().asFunction()

package/src/url.ts

@@ -0,0 +1,185 @@
+/**
+ * URL 工具函数
+ * 部分灵感来自：https://www.npmjs.com/package/qs
+ *
+ * [名词定义]
+ * query: 指 a=1&b=2 格式的“查询字符串”或此类字符串的解析结果。
+ * search: URL 中的 search 部分，与 location.search 一致，空字符串或以 '?' 开头。
+ * hash: URL 中的 hash 部分，与 location.hash 一直，空字符串或以 '#' 开头。
+ */
+import isPlainObject from 'lodash/isPlainObject.js'
+
+/**
+ * 从 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; loose?: boolean; decode?: boolean },
+): Record<string, string | string[]> {
+  const { array = false, loose = false, decode = true } = options ?? {}
+
+  // 正常状态下，将仅剩 a=1&b=1（即不会再有 ? 和 #）；loose 模式下，可能为 a=1&b=2#c=3?d=4
+  const queryString = (loose ? /(\?|#)(.+)/ : /(\?)(.+?)(#|$)/).exec(url)?.[2] ?? ''
+  if (!queryString) return {}
+
+  const query: Record<string, string | string[]> = {}
+  const reg = /([^#?&]*)=([^#?&]*)/g
+  let re = reg.exec(queryString)
+  while (re) {
+    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
+    }
+    re = reg.exec(queryString)
+  }
+  return query
+}
+export { parseQuery }
+
+/**
+ * 把对象合并成 query string。
+ * - 支持字符串、数值、布尔值、数组。
+ * - 布尔值会替换成 0 和 1。
+ * - 数组会多次赋值：{ a: [1,2,3] } => 'a=1&a=2&a=3'，不支持嵌套数组
+ * - encode 为 true 时会对 value 执行 encodeURIComponent（默认为 true）
+ */
+export type StringifyVal = string | number | boolean
+export type StringifyQuery = Record<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, encode))
+      .join('&')
+  )
+}
+function stringifyQueryItem(
+  name: string,
+  value: StringifyVal | StringifyVal[],
+  encode: boolean,
+): string {
+  if (Array.isArray(value))
+    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}`
+}
+
+/**
+ * 拆分 URL 的各个部分
+ *
+ * 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('#')
+  if (hashIndex === -1) hashIndex = url.length
+  const bareHash = url.slice(hashIndex + 1)
+
+  let searchIndex = url.slice(0, hashIndex).indexOf('?')
+  if (searchIndex === -1) searchIndex = hashIndex
+  const bareSearch = url.slice(searchIndex + 1, hashIndex)
+
+  return {
+    base: url.slice(0, searchIndex),
+    search: bare ? bareSearch : bareSearch ? '?' + bareSearch : '',
+    hash: bare ? bareHash : bareHash ? '#' + bareHash : '',
+  }
+}
+
+/**
+ * 把 query 和 hash 内容合并到 url 上
+ *
+ * query   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
+ * hash    string    带不带开头的 '#' 皆可。会代替 url 已有的 hash。
+ */
+export function combineUrl(origUrl: string, query: StringifyQuery = {}, hash = '') {
+  if (hash.startsWith('#')) hash = hash.slice(1)
+
+  // 拆分原 url 的 search、hash
+  const { base, search: origSearch, hash: origHash } = splitUrl(origUrl)
+
+  // 拼接新 URL
+  let newUrl = base
+  const newSearch = stringifyQuery({ ...parseQuery(origSearch), ...query })
+  const newHash = hash || origHash
+  if (newSearch) newUrl += `?${newSearch}`
+  if (newHash) newUrl += `#${newHash}`
+  return newUrl
+}
+
+/**
+ * 移除路径中所有非必须的 "/"
+ * 清理后的字符串只有这几种可能的格式：''、'abc'、'abc/def'
+ * 例如 /abc/def 和 abc/def/ 都会变成 abc/def
+ *
+ * 注意：此操作不会统一大小写，因此不保证处理后两个字符串在代码层面全等（a === b）
+ */
+export function clearSlash(path: string) {
+  if (path.startsWith('/')) path = path.slice(1)
+  if (path.endsWith('/')) path = path.slice(0, -1)
+  path = path.replace(/\/+/g, '/')
+  return path
+}
+
+/**
+ * 合并几段路径，保证合并处只有一个斜杠
+ */
+export function joinPath(...nodes: string[]) {
+  // - node 为 '' 时忽略 node
+  // - path 可能的格式：'' 'a' 'a/' ‘/a/'
+  //   - path 为 ''，则 node 开头 '/' 保持原样
+  //   - 否则，根据 path 结尾有没有 '/'，决定 node 开头带不带 '/'
+  // - node 开头、结尾若有多个 '/' 均替换成单个
+  return nodes.reduce((path, node) => {
+    if (!node) return path
+    type Matched = RegExpExecArray & { 1: string; 2: string; 3: string }
+    const [, origPrefix, content, origSuffix] = /^(\/*)(.*?)(\/*)$/.exec(node)! as Matched
+    const prefix = (path === '' ? !!origPrefix : !path.endsWith('/')) ? '/' : ''
+    const suffix = origSuffix ? '/' : ''
+    const result = `${path}${prefix}${content}${suffix}`
+    return result
+  }, '')
+}
+
+/**
+ * decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
+ * 用此函数代替可避免此问题
+ */
+export function safeDecode(content: string) {
+  try {
+    return decodeURIComponent(content)
+  } catch (e) {
+    return content
+  }
+}
+
+/**
+ * 将 URL 中的 http:// 协议改成 https://
+ */
+export function ensureHttps(url: string | undefined) {
+  return url?.replace(/http:\/\//g, 'https://')
+}