@anjianshi/utils 1.2.7 → 1.3.0

package/src/validators/base.ts

@@ -0,0 +1,49 @@
+import { success, failed, type MaySuccess } from '../lang/index.js'
+
+export interface BaseOptions {
+  /**
+   * 是否允许 null 值
+   * @default false
+   */
+  null: boolean
+
+  /**
+   * 字段是否必须有值（不能是 undefined）
+   * @default true
+   */
+  required: boolean
+
+  /**
+   * 默认值，字段无值（或值为 undefined）时生效，值为 null 不会生效。
+   * 指定后 required 选项将失去作用。
+   */
+  defaults: unknown
+}
+
+export class Validator<ExtraOptions = unknown> {
+  readonly options: BaseOptions & ExtraOptions
+
+  constructor(options: Partial<BaseOptions> & ExtraOptions) {
+    this.options = {
+      null: false,
+      required: true,
+      defaults: undefined,
+      ...options,
+    }
+  }
+
+  /**
+   * 各子类继承此方法补充验证逻辑
+   */
+  validate(field: string, value: unknown): MaySuccess<unknown> {
+    if (typeof value === 'undefined') {
+      if (typeof this.options.defaults !== 'undefined') {
+        value = this.options.defaults
+      } else if (this.options.required) {
+        return failed(`${field} is required`)
+      }
+    }
+    if (value === null && !this.options.null) return failed(`${field} cannot be null`)
+    return success(value)
+  }
+}

package/src/validators/boolean.ts

@@ -0,0 +1,24 @@
+import { success, failed } from '../lang/index.js'
+import { Validator } from './base.js'
+
+export class BooleanValidator extends Validator {
+  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
+
+    if (typeof value === 'string') {
+      const str = value.trim().toLowerCase()
+      if (['1', 'true', 'on', 'yes'].includes(str)) value = true
+      else if (['0', 'false', 'off', 'no'].includes(str)) value = false
+    } else if (typeof value === 'number') {
+      if (value === 1) value = true
+      else if (value === 0) value = false
+    }
+
+    if (typeof value !== 'boolean') return failed(`${field} must be true or false`)
+    return success(value)
+  }
+}

package/src/validators/factories.ts

@@ -0,0 +1,47 @@
+/**
+ * 创建 validator 的快捷方式
+ */
+import { ArrayValidator, type ArrayOptions } from './array.js'
+import { Validator, type BaseOptions } from './base.js'
+import { BooleanValidator } from './boolean.js'
+import { NumberValidator } from './number.js'
+import { ObjectValidator, type RecordOptions } from './object.js'
+import { StringValidator } from './string.js'
+
+/** 仅进行基本检查（如检查空值），不检查具体格式 */
+export function any(options?: Partial<BaseOptions>) {
+  return new Validator(options ?? {})
+}
+
+export function string(...args: ConstructorParameters<typeof StringValidator>) {
+  return new StringValidator(...args)
+}
+
+export function number(...args: ConstructorParameters<typeof NumberValidator>) {
+  return new NumberValidator(...args)
+}
+
+export function boolean(options: Partial<BaseOptions> = {}) {
+  return new BooleanValidator(options)
+}
+
+export function array(options: Validator | (ArrayOptions & Partial<BaseOptions>)) {
+  if (options instanceof Validator) options = { item: options }
+  return new ArrayValidator(options)
+}
+
+export function tuple(validators: Validator[], baseOptions?: Partial<BaseOptions>) {
+  return new ArrayValidator({
+    ...(baseOptions ?? {}),
+    tuple: validators,
+  })
+}
+
+export function struct(validators: Record<string, Validator>, options: Partial<BaseOptions> = {}) {
+  return new ObjectValidator({ ...options, struct: validators })
+}
+
+export function record(options: Validator | (RecordOptions & Partial<BaseOptions>)) {
+  if (options instanceof Validator) options = { record: options }
+  return new ObjectValidator(options)
+}

package/src/validators/index.ts

@@ -0,0 +1,9 @@
+export * from './base.js'
+
+export * from './array.js'
+export * from './boolean.js'
+export * from './number.js'
+export * from './object.js'
+export * from './string.js'
+
+export * as validators from './factories.js'

package/src/validators/number.ts

@@ -0,0 +1,43 @@
+import { success, failed } from '../lang/index.js'
+import { type BaseOptions, Validator } from './base.js'
+
+export interface NumberOptions {
+  /** 数值最小值 */
+  min?: number
+  /** 数值最大值 */
+  max?: number
+  /** 是否允许小数 @default false */
+  float: boolean
+  /** 指定可选值 */
+  enum?: number[]
+}
+
+export class NumberValidator extends Validator<NumberOptions> {
+  constructor(options: Partial<BaseOptions & NumberOptions> = {}) {
+    super({
+      float: false,
+      ...options,
+    })
+  }
+
+  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 (typeof value === 'string') value = parseFloat(value)
+
+    if (typeof value !== 'number' || !isFinite(value))
+      return failed(`${field} must be a valid number`)
+    if (opt.enum !== undefined && !opt.enum.includes(value))
+      return failed(`${field} can only be one of ${opt.enum.join(', ')}.`)
+    if (!opt.float && value % 1 !== 0) return failed(`${field} must be a integer`)
+    if (typeof opt.min === 'number' && value < opt.min) return failed(`${field} must >= ${opt.min}`)
+    if (typeof opt.max === 'number' && value > opt.max) return failed(`${field} must <= ${opt.max}`)
+
+    return success(value)
+  }
+}

package/src/validators/object.ts

@@ -0,0 +1,70 @@
+import isPlainObject from 'lodash/isPlainObject.js'
+import { success, failed } from '../lang/index.js'
+import { Validator } from './base.js'
+
+/** 验证有明确键值对结构的对象 */
+export type StructOptions = {
+  /** 定义对象结构，及各个值的验证规则 */
+  struct: Record<string, Validator>
+}
+
+/**
+ * 验证有任意多个 key，但值的类型固定的对象
+ */
+export type RecordOptions = {
+  /** 验证单个值  */
+  record: Validator
+  /** 对象至少要有几项 */
+  min?: number
+  /** 对象最多有几项 */
+  max?: number
+}
+
+export class ObjectValidator extends Validator<StructOptions | RecordOptions> {
+  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 (!isPlainObject(value)) return failed(`${field} should be a plain object`)
+
+    const formatted: Record<string, unknown> = {}
+    if ('struct' in opt) {
+      for (const [key, itemValidator] of Object.entries(opt.struct)) {
+        const itemResult = itemValidator.validate(
+          `${field}["${key}"]`,
+          (value as Record<string, unknown>)[key]
+        )
+        if (itemResult.success) {
+          if (itemResult.data !== undefined) formatted[key] = itemResult.data
+        } else {
+          return itemResult
+        }
+      }
+    } else {
+      for (const [key, itemValue] of Object.entries(value as Record<string, unknown>)) {
+        // record 场景下，值为 undefined 的项目视为不存在，不保留在验证结果里，
+        // 不然一些因为不想赋值而填充了 undefined 值的项目可能意外触发验证失败，或意外得到了默认值。
+        // （因此 validator 的 required 选项和 defaults 选项也没有意义了）
+        if (itemValue === undefined) continue
+
+        const itemResult = opt.record.validate(`${field}["${key}"]`, itemValue)
+        if (itemResult.success) {
+          if (itemResult.data !== undefined) formatted[key] = itemResult.data
+        } else {
+          return itemResult
+        }
+      }
+
+      const length = Object.keys(formatted).length
+      if (typeof opt.min === 'number' && length < opt.min)
+        return failed(`size of ${field} should >= ${opt.min}`)
+      if (typeof opt.max === 'number' && length > opt.max)
+        return failed(`size of ${field} should <= ${opt.max}`)
+    }
+    return success(formatted)
+  }
+}

package/src/validators/string.ts

@@ -0,0 +1,55 @@
+import { success, failed } from '../lang/index.js'
+import { type BaseOptions, Validator } from './base.js'
+
+export interface StringOptions {
+  /** 字符串最小长度。defaults='' 时默认为 0，否则默认为 1 */
+  min: number
+  /** 字符串最大长度。 */
+  max?: number
+  /** 字符串需匹配此正则 */
+  pattern?: RegExp
+  /** 指定一个数组或 TypeScript enum，字段值必须在此 enum 之中 */
+  enum?: string[] | Record<string, string>
+  /** 验证之前，是否先清除两侧空白字符（默认开启） */
+  trim: boolean
+}
+
+export class StringValidator extends Validator<StringOptions> {
+  constructor(options: Partial<BaseOptions & StringOptions> = {}) {
+    super({
+      min: options.defaults === '' ? 0 : 1,
+      trim: true,
+      ...options,
+    })
+  }
+
+  validate(field: string, value: unknown) {
+    const opt = this.options
+
+    const superResult = super.validate(field, value)
+    if (!superResult.success) return superResult
+
+    value = superResult.data
+    if (value === null || value === undefined) return superResult
+    if (typeof value !== 'string') return failed(`${field} must be a string`)
+
+    const formatted = opt.trim ? value.trim() : value
+
+    if (typeof opt.min === 'number' && formatted.length < opt.min)
+      return failed(`${field}'s length must >= ${opt.min}`)
+
+    if (typeof opt.max === 'number' && formatted.length > opt.max)
+      return failed(`${field}'s length must <= ${opt.max}`)
+
+    if (opt.pattern && !opt.pattern.exec(formatted))
+      return failed(`${field} does not match the pattern.`)
+
+    if (opt.enum !== undefined) {
+      const validValues = Array.isArray(opt.enum) ? opt.enum : Object.values(opt.enum)
+      if (!validValues.includes(formatted))
+        return failed(`${field} can only be one of ${validValues.join(', ')}.`)
+    }
+
+    return success(formatted)
+  }
+}

package/url.d.ts

@@ -1,32 +1,48 @@
+/**
+ * 从 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（默认开启）
+ */
 declare function parseQuery(url: string, options?: {
     array?: false;
-    strict?: boolean;
+    loose?: boolean;
+    decode?: boolean;
 }): Record<string, string>;
 declare function parseQuery(url: string, options: {
     array: true;
-    strict?: boolean;
+    loose?: boolean;
+    decode?: boolean;
 }): Record<string, string | string[]>;
 export { parseQuery };
-/**
- * 取 query 中指定参数的值
- * - 参数存在，返回参数值（可能是空字符串）；不存在返回 null
- * - 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
- * - 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
- */
-export declare function getQueryParam(name: string, url: string): string | 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 declare function stringifyQuery(obj: {
+type StringifyQuery = {
     [key: string]: StringifyVal | StringifyVal[] | undefined;
-}): string;
+};
+export declare function stringifyQuery(obj: StringifyQuery, encode?: boolean): string;
 /**
  * 拆分 URL 的各个部分
  *
  * bare 为 true，则 search 不带 '?'，hash 不带 '#'
  * 否则和 location.search / hash 一样
+ * （默认为 true）
  */
 export declare function splitUrl(url: string, bare?: boolean): {
     base: string;
@@ -34,12 +50,12 @@ export declare function splitUrl(url: string, bare?: boolean): {
     hash: string;
 };
 /**
- * 把指定 query 和 hash 内容合并到 url 上
+ * 把 query 和 hash 内容合并到 url 上
  *
  * query   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
- * hash    string    若 url 已有 hash，会用此值代替。带不带开头的 '?' 皆可。
+ * hash    string    带不带开头的 '#' 皆可。会代替 url 已有的 hash。
  */
-export declare function combineUrl(origUrl: string, query?: Record<string, string | string[]>, hash?: string): string;
+export declare function combineUrl(origUrl: string, query?: StringifyQuery, hash?: string): string;
 /**
  * decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
  * 用此函数代替可避免此问题

package/url.js

@@ -9,23 +9,20 @@
  */
 import isPlainObject from 'lodash/isPlainObject.js';
 function parseQuery(url, options) {
-    if (!url)
+    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 { array = false, strict = false } = options ?? {};
-    const queryString = strict
-        ? (/^[^?#]*\?(.+?)(\?|#|$)/.exec(url) ?? ['', ''])[1] // 排除 hash、重复的 ? 符号
-        : url;
     const query = {};
     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].push(value);
-            else
-                query[realName] = [value];
+        const [name, rawValue] = [re[1], re[2]];
+        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;
@@ -35,28 +32,24 @@ function parseQuery(url, options) {
     return query;
 }
 export { parseQuery };
-/**
- * 取 query 中指定参数的值
- * - 参数存在，返回参数值（可能是空字符串）；不存在返回 null
- * - 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
- * - 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
- */
-export function getQueryParam(name, url) {
-    const query = parseQuery(url);
-    return typeof query[name] === 'string' ? query[name] : null;
-}
-export function stringifyQuery(obj) {
+export function stringifyQuery(obj, encode = true) {
     if (!isPlainObject(obj))
         return '';
     return (Object.entries(obj)
         // 过滤值为 undefined 的项目，使其完全不出现在最终的 query 中
         .filter((entry) => entry[1] !== undefined)
-        .map(([name, value]) => stringifyQueryItem(name, value))
+        .map(([name, value]) => stringifyQueryItem(name, value, encode))
         .join('&'));
 }
-function stringifyQueryItem(name, value) {
+function stringifyQueryItem(name, value, encode) {
     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}`;
 }
 /**
@@ -64,6 +57,7 @@ function stringifyQueryItem(name, value) {
  *
  * bare 为 true，则 search 不带 '?'，hash 不带 '#'
  * 否则和 location.search / hash 一样
+ * （默认为 true）
  */
 export function splitUrl(url, bare = true) {
     let hashIndex = url.indexOf('#');
@@ -81,10 +75,10 @@ export function splitUrl(url, bare = true) {
     };
 }
 /**
- * 把指定 query 和 hash 内容合并到 url 上
+ * 把 query 和 hash 内容合并到 url 上
  *
  * query   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
- * hash    string    若 url 已有 hash，会用此值代替。带不带开头的 '?' 皆可。
+ * hash    string    带不带开头的 '#' 皆可。会代替 url 已有的 hash。
  */
 export function combineUrl(origUrl, query = {}, hash = '') {
     if (hash.startsWith('#'))

package/validators/array.d.ts

@@ -0,0 +1,20 @@
+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 declare class ArrayValidator extends Validator<ArrayOptions | TupleOptions> {
+    validate(field: string, value: unknown): import("../lang/may-success.js").Failed<void> | import("../lang/may-success.js").Success<unknown>;
+}

package/validators/array.js

@@ -0,0 +1,44 @@
+import { success, failed } from '../lang/index.js';
+import { Validator } from './base.js';
+export class ArrayValidator extends Validator {
+    validate(field, value) {
+        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);
+    }
+}

package/validators/base.d.ts

@@ -0,0 +1,26 @@
+import { type MaySuccess } from '../lang/index.js';
+export interface BaseOptions {
+    /**
+     * 是否允许 null 值
+     * @default false
+     */
+    null: boolean;
+    /**
+     * 字段是否必须有值（不能是 undefined）
+     * @default true
+     */
+    required: boolean;
+    /**
+     * 默认值，字段无值（或值为 undefined）时生效，值为 null 不会生效。
+     * 指定后 required 选项将失去作用。
+     */
+    defaults: unknown;
+}
+export declare class Validator<ExtraOptions = unknown> {
+    readonly options: BaseOptions & ExtraOptions;
+    constructor(options: Partial<BaseOptions> & ExtraOptions);
+    /**
+     * 各子类继承此方法补充验证逻辑
+     */
+    validate(field: string, value: unknown): MaySuccess<unknown>;
+}

package/validators/base.js

@@ -0,0 +1,28 @@
+import { success, failed } from '../lang/index.js';
+export class Validator {
+    options;
+    constructor(options) {
+        this.options = {
+            null: false,
+            required: true,
+            defaults: undefined,
+            ...options,
+        };
+    }
+    /**
+     * 各子类继承此方法补充验证逻辑
+     */
+    validate(field, value) {
+        if (typeof value === 'undefined') {
+            if (typeof this.options.defaults !== 'undefined') {
+                value = this.options.defaults;
+            }
+            else if (this.options.required) {
+                return failed(`${field} is required`);
+            }
+        }
+        if (value === null && !this.options.null)
+            return failed(`${field} cannot be null`);
+        return success(value);
+    }
+}

package/validators/boolean.d.ts

@@ -0,0 +1,4 @@
+import { Validator } from './base.js';
+export declare class BooleanValidator extends Validator {
+    validate(field: string, value: unknown): import("../lang/may-success.js").Failed<void> | import("../lang/may-success.js").Success<unknown>;
+}

package/validators/boolean.js

@@ -0,0 +1,28 @@
+import { success, failed } from '../lang/index.js';
+import { Validator } from './base.js';
+export class BooleanValidator extends Validator {
+    validate(field, value) {
+        const superResult = super.validate(field, value);
+        if (!superResult.success)
+            return superResult;
+        value = superResult.data;
+        if (value === null || value === undefined)
+            return superResult;
+        if (typeof value === 'string') {
+            const str = value.trim().toLowerCase();
+            if (['1', 'true', 'on', 'yes'].includes(str))
+                value = true;
+            else if (['0', 'false', 'off', 'no'].includes(str))
+                value = false;
+        }
+        else if (typeof value === 'number') {
+            if (value === 1)
+                value = true;
+            else if (value === 0)
+                value = false;
+        }
+        if (typeof value !== 'boolean')
+            return failed(`${field} must be true or false`);
+        return success(value);
+    }
+}

package/validators/factories.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 创建 validator 的快捷方式
+ */
+import { ArrayValidator, type ArrayOptions } from './array.js';
+import { Validator, type BaseOptions } from './base.js';
+import { BooleanValidator } from './boolean.js';
+import { NumberValidator } from './number.js';
+import { ObjectValidator, type RecordOptions } from './object.js';
+import { StringValidator } from './string.js';
+/** 仅进行基本检查（如检查空值），不检查具体格式 */
+export declare function any(options?: Partial<BaseOptions>): Validator<unknown>;
+export declare function string(...args: ConstructorParameters<typeof StringValidator>): StringValidator;
+export declare function number(...args: ConstructorParameters<typeof NumberValidator>): NumberValidator;
+export declare function boolean(options?: Partial<BaseOptions>): BooleanValidator;
+export declare function array(options: Validator | (ArrayOptions & Partial<BaseOptions>)): ArrayValidator;
+export declare function tuple(validators: Validator[], baseOptions?: Partial<BaseOptions>): ArrayValidator;
+export declare function struct(validators: Record<string, Validator>, options?: Partial<BaseOptions>): ObjectValidator;
+export declare function record(options: Validator | (RecordOptions & Partial<BaseOptions>)): ObjectValidator;