@anjianshi/utils 2.5.0 → 2.7.0

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://')
+}

package/src/validators/array.ts

@@ -0,0 +1,97 @@
+import { success, failed } from '../lang/index.js'
+import {
+  getValidatorGenerator,
+  type CommonOptions,
+  type Validator,
+  type Validated,
+  type PrimitiveType,
+} from './base.js'
+
+/** 验证元素数量任意、元素类型相同的数组 */
+export interface ArrayOptions extends CommonOptions {
+  /** 验证数组各元素 */
+  item: Validator<unknown, CommonOptions>
+
+  /** 数组最小长度 */
+  min?: number
+
+  /** 数组最大长度 */
+  max?: number
+
+  /** 是否对数组元素进行去重 @defaults false */
+  unique?: boolean
+
+  /** 如果传入的不是数组，是否要将其视为数组内元素，包裹成数组 */
+  toArray?: boolean
+}
+
+type ArrayValues<Options extends ArrayOptions> = Validated<
+  Options extends { item: Validator<infer T, CommonOptions> } ? T : never,
+  Options extends { item: Validator<unknown, infer T> } ? T : never
+>[]
+
+export function getArrayValidator<Options extends ArrayOptions>(options: Options) {
+  return getValidatorGenerator<ArrayValues<Options>, Options>(
+    function validate(field, value, options) {
+      if (!Array.isArray(value)) {
+        if (options.toArray) value = [value as PrimitiveType]
+        else return failed(`${field} should be an array`)
+      }
+
+      let formatted = []
+      if (typeof options.min === 'number' && value.length < options.min)
+        return failed(`array ${field}'s length should >= ${options.min}`)
+
+      if (typeof options.max === 'number' && value.length > options.max)
+        return failed(`array ${field}'s length should <= ${options.max}`)
+
+      const itemValidator = options.item
+      for (let i = 0; i < value.length; i++) {
+        const itemResult = itemValidator(`${field}[${i}]`, value[i])
+        if (itemResult.success) formatted.push(itemResult.data)
+        else return itemResult
+      }
+
+      if (options.unique === true) formatted = [...new Set(formatted)]
+
+      return success(formatted as ArrayValues<Options>)
+    },
+  )(options)
+}
+
+// ---------------------------------------------------
+
+/** 验证元素数量固定、类型可以不同的数组 */
+export interface TupleOptions extends CommonOptions {
+  /** 验证数组各元素（validator 与元素一一对应） */
+  tuple: Validator<unknown, CommonOptions>[]
+}
+
+type TupleValues<Options extends TupleOptions> = {
+  [Key in keyof Options['tuple']]: Options['tuple'][Key] extends Validator<
+    infer Value,
+    infer Options
+  >
+    ? Validated<Value, Options>
+    : never
+}
+
+export function getTupleValidator<const Options extends TupleOptions>(options: Options) {
+  return getValidatorGenerator<TupleValues<Options>, Options>(
+    function validate(field, value, options) {
+      if (!Array.isArray(value)) return failed(`${field} should be an array`)
+      if (value.length > options.tuple.length)
+        return failed(`${field} should be a tuple with ${options.tuple.length} items`)
+
+      const formatted = []
+      // 这种情况不能遍历 value，因为它的长度可能小于 opt.tuple
+      for (let i = 0; i < options.tuple.length; i++) {
+        const itemValidator = options.tuple[i]!
+        const itemResult = itemValidator(`${field}[${i}]`, value[i])
+        if (itemResult.success) formatted.push(itemResult.data)
+        else return itemResult
+      }
+      return success(formatted as TupleValues<Options>)
+    },
+  )(options)
+}

package/src/validators/base.ts

@@ -0,0 +1,145 @@
+import { success, failed, type MaySuccess } from '../lang/index.js'
+
+/**
+ * 支持传入进行验证的值类型
+ */
+export type AllowedInputValue = PrimitiveType | null | undefined
+
+/**
+ * JavaScript 基础值类型
+ */
+export type PrimitiveType =
+  | string
+  | boolean
+  | number
+  | PrimitiveType[]
+  | [...PrimitiveType[]]
+  | { [key: string]: PrimitiveType }
+
+/**
+ * validator 通用参数
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface CommonOptions<Value = any> {
+  /** 是否允许 null 值 @default false */
+  null?: boolean
+
+  /** 字段是否必须有值（不能是 undefined） @default true */
+  required?: boolean
+
+  /**
+   * 默认值，字段无值（或值为 undefined）时生效，值为 null 不会生效。
+   * 指定后 required 选项将失去作用。
+   */
+  defaults?: Value
+
+  custom?: (input: Value) => MaySuccess<Value>
+
+  // 用来保证传入定制过的 Options 时 TypeScript 不会报不匹配的错
+  // 例如不加这句时， `{ other: boolean } extends CommonOptions` 是会被 TypeScript 判定为不匹配的：
+  // error TS2559: Type '{ other: boolean }' has no properties in common with type 'CommonOptions<unknown>'
+  // 此解决办法来自：https://mariusschulz.com/blog/weak-type-detection-in-typescript
+  [key: string]: unknown
+}
+
+/**
+ * 补全了的 Options
+ */
+type FullfiledOptions<Options extends Partial<CommonOptions>> = Omit<
+  Options,
+  keyof CommonOptions
+> & {
+  null: Options['null'] extends true ? true : false
+  required: Options['required'] extends false ? false : true
+  defaults: Options extends { defaults: infer T } ? T : undefined
+  custom: Options extends { custom: infer T } ? T : undefined
+}
+
+/**
+ * 验证完成后能得到的值类型
+ */
+export type Validated<Value, InputOptions extends CommonOptions> =
+  FullfiledOptions<InputOptions> extends { defaults: undefined }
+    ? FullfiledOptions<InputOptions> extends { required: false; null: false }
+      ? Value | undefined
+      : FullfiledOptions<InputOptions> extends { required: false; null: true }
+        ? Value | undefined | null
+        : FullfiledOptions<InputOptions> extends { required: true; null: false }
+          ? Value
+          : FullfiledOptions<InputOptions> extends { required: true; null: true }
+            ? Value | null
+            : Value
+    : FullfiledOptions<InputOptions> extends {
+          defaults: infer T
+          null: false
+        }
+      ? Value | T
+      : FullfiledOptions<InputOptions> extends { defaults: infer T; null: true }
+        ? Value | T | null
+        : never
+
+/**
+ * 最终生成的 validator 函数类型
+ */
+export interface Validator<Value, InputOptions extends CommonOptions> {
+  (input: AllowedInputValue): MaySuccess<Validated<Value, InputOptions>>
+  (field: string, input: AllowedInputValue): MaySuccess<Validated<Value, InputOptions>>
+}
+
+// -----------------------------------
+
+/**
+ * 返回支持指定格式的 options、并按照传入的逻辑进行验证的 validator 的生成器。
+ * 对 CommonOptions 相关内容的验证以自动包含在里面，只需要传入额外的验证逻辑即可。
+ */
+export function getValidatorGenerator<Value, Options extends CommonOptions>(
+  validate: (
+    field: string,
+    input: PrimitiveType | Validated<Value, Options>,
+    options: Options,
+  ) => MaySuccess<Value>,
+) {
+  return function validatorGenerator<const InputOptions extends Options>(
+    inputOptions: InputOptions,
+  ): Validator<Value, InputOptions> {
+    type Return = MaySuccess<Validated<Value, InputOptions>>
+    function validator(input: AllowedInputValue): Return
+    function validator(field: string, input: AllowedInputValue): Return
+    function validator(field: string | AllowedInputValue, input?: AllowedInputValue) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const { null: allowNull = false, required = true, defaults, custom } = inputOptions
+
+      if (typeof field !== 'string') {
+        input = field
+        field = 'value'
+      }
+
+      let value: AllowedInputValue | Validated<Value, Options> = input
+      if (typeof value === 'undefined') {
+        if (typeof defaults !== 'undefined') {
+          value = defaults as Validated<Value, Options>
+        } else if (required) {
+          return failed(`${field} is required`)
+        }
+      }
+      if (value === null && !allowNull) return failed(`${field} cannot be null`)
+      if (value === null || value === undefined) return success(value)
+
+      const validated = validate(field, value, inputOptions)
+      return validated.success && custom ? custom(validated.data) : validated
+    }
+    return validator
+  }
+}
+
+// -----------------------------------
+
+/**
+ * 返回只进行基本检查，不带定制的验证逻辑的 validator。
+ * 同时也是定制 validator 最小化实现的例子。
+ */
+export const getAnyValidator = getValidatorGenerator<unknown, CommonOptions>(
+  function validate(field, input) {
+    return success(input)
+  },
+)

package/src/validators/boolean.ts

@@ -0,0 +1,21 @@
+import { success, failed } from '../lang/index.js'
+import { getValidatorGenerator, type CommonOptions } from './base.js'
+
+export type BooleanOptions = CommonOptions<boolean>
+
+export const getBooleanValidator = getValidatorGenerator<boolean, BooleanOptions>(
+  function validate(field, input) {
+    let value: boolean | null = null
+    if (typeof input === 'boolean') {
+      value = input
+    } else if (typeof input === 'string') {
+      const str = input.trim().toLowerCase()
+      if (['1', 'true', 'on', 'yes'].includes(str)) value = true
+      else if (['0', 'false', 'off', 'no'].includes(str)) value = false
+    } else if (typeof input === 'number') {
+      if (input === 1) value = true
+      else if (input === 0) value = false
+    }
+    return value === null ? failed(`${field} must be true or false`) : success(value)
+  },
+)

package/src/validators/datetime.ts

@@ -0,0 +1,39 @@
+/**
+ * 验证日期时间类型的值，依赖 dayjs
+ */
+import dayjs, { Dayjs } from 'dayjs'
+import { success, failed } from '../lang/index.js'
+import { getValidatorGenerator, type CommonOptions } from './base.js'
+
+export interface DatetimeOptions extends CommonOptions<number> {
+  raw?: boolean // 为 true 则返回原生 Date 对象；否则返回 Dayjs 对象（默认）
+}
+
+export type DatetimeValue<Options extends DatetimeOptions> = Options extends {
+  raw: true
+}
+  ? Date
+  : Dayjs
+
+export function getDatetimeValidator<const Options extends DatetimeOptions>(
+  options: Options = {} as Options
+) {
+  return getValidatorGenerator<DatetimeValue<Options>, Options>(function validate(field, value) {
+    let dayjsValue: Dayjs
+
+    if (typeof value === 'number') {
+      dayjsValue = dayjs.unix(value)
+      if (!dayjsValue.isValid()) return failed(`${field} must be a valid unix timestamp`)
+    } else if (typeof value === 'string') {
+      dayjsValue = dayjs(value)
+      if (!dayjsValue.isValid()) return failed(`${field} must be a valid datetime string`)
+    } else if (value instanceof Date || value instanceof Dayjs) {
+      dayjsValue = dayjs(value)
+      if (!dayjsValue.isValid()) return failed(`${field} must be a valid Date or Dayjs object`)
+    } else {
+      return failed(`${field} must be a datetime string or unix timestamp`)
+    }
+
+    return success((options.raw ? dayjsValue.toDate() : dayjsValue) as DatetimeValue<Options>)
+  })(options)
+}