@stdex/validator 0.0.0-stage → 1.2.0

package/dist/one-of.d.ts

@@ -0,0 +1,10 @@
+import { type CommonOptions, type Validator } from './base.js';
+/** 要求返回值通过其中一个验证器的检查 */
+export interface OneOfOptions extends CommonOptions {
+    /** 验证数组各元素 */
+    validators: Validator<unknown, CommonOptions>[];
+}
+export type OneOfValue<Options extends OneOfOptions> = Options extends {
+    validators: Validator<infer T, CommonOptions>[];
+} ? T : never;
+export declare function getOneOfValidator<const Options extends OneOfOptions>(options?: Options): Validator<OneOfValue<Options>, Options>;

package/dist/one-of.js

@@ -0,0 +1,15 @@
+import { failure } from '@stdex/utils';
+import { getValidatorGenerator, } from './base.js';
+export function getOneOfValidator(options = {}) {
+    return getValidatorGenerator(function validate(field, value) {
+        const errors = [];
+        for (const validator of options.validators) {
+            const result = validator(field, value);
+            if (result.success)
+                return result;
+            else
+                errors.push(result.message);
+        }
+        return failure(`${field} do not match any valid format：\n- ` + errors.join('\n- '));
+    })(options);
+}

package/dist/string.d.ts

@@ -0,0 +1,22 @@
+import { type CommonOptions } from './base.js';
+export interface StringOptions extends CommonOptions<string> {
+    /** 字符串最小长度。defaults='' 时默认为 0，否则默认为 1 */
+    min?: number;
+    /** 字符串最大长度。 */
+    max?: number;
+    /** 字符串需匹配此正则，也可传入关键词使用预置的正则。正则通常应以 ^ 和 $ 开头结尾。 */
+    pattern?: RegExp | 'uuid' | 'mobile';
+    /**
+     * 指定一个数组或 TypeScript enum，字段值必须在此 enum 之中。
+     * 若指定，前几个选项将不再生效。
+     */
+    choices?: string[] | Record<string, string>;
+    /** 验证之前，是否先清除两侧空白字符 @default true */
+    trim?: boolean;
+}
+export type StringValueWithChoices<Options extends StringOptions> = Options extends {
+    choices: (infer T)[];
+} ? T : Options extends {
+    choices: Record<string, infer T>;
+} ? T : string;
+export declare function getStringValidator<const Options extends StringOptions>(options?: Options): import("./base.js").Validator<StringValueWithChoices<Options>, Options>;

package/dist/string.js

@@ -0,0 +1,35 @@
+import { success, failure } from '@stdex/utils';
+import { getValidatorGenerator } from './base.js';
+export function getStringValidator(options = {}) {
+    return getValidatorGenerator(function validate(field, value) {
+        if (typeof value !== 'string')
+            return failure(`${field} must be a string`);
+        const trim = options.trim ?? true;
+        const formatted = trim ? value.trim() : value;
+        if ('choices' in options && options.choices) {
+            const validValues = Array.isArray(options.choices)
+                ? options.choices
+                : Object.values(options.choices);
+            if (!validValues.includes(formatted))
+                return failure(`${field} can only be one of ${validValues.join(', ')}.`);
+        }
+        else {
+            const { min = options.defaults === '' ? 0 : 1, max, pattern } = options;
+            if (typeof min === 'number' && formatted.length < min)
+                return failure(`${field}'s length must >= ${min}`);
+            if (typeof max === 'number' && formatted.length > max)
+                return failure(`${field}'s length must <= ${max}`);
+            if (pattern !== undefined) {
+                if (pattern instanceof RegExp && !pattern.exec(formatted))
+                    return failure(`${field} does not match the pattern`);
+                if (pattern === 'mobile' && !/^1\d{10}$/.test(formatted))
+                    return failure(`${field} is not a valid mobile number`);
+                if (pattern === 'uuid') {
+                    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(formatted))
+                        return failure(`${field} is not a valid uuid`);
+                }
+            }
+        }
+        return success(formatted);
+    })(options);
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@stdex/validator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "description": "数据验证、格式化工具，支持自动类型推理",
+  "homepage": "https://github.com/anjianshi/stdex-packages/validator",
+  "bugs": {
+    "url": "https://github.com/anjianshi/stdex-packages/issues",
+    "email": "anjianshi@gmail.com"
+  },
+  "license": "MIT",
+  "author": "anjianshi <anjianshi@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anjianshi/stdex-packages.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist/"
+  ],
+  "dependencies": {
+    "@stdex/utils": "1.2.0",
+    "dayjs": "^1.11.23",
+    "lodash": "^4.18.1"
+  },
+  "devDependencies": {
+    "@stdex/presets-eslint-typescript": "1.2.0",
+    "@stdex/presets-prettier": "1.2.0",
+    "@stdex/presets-typescript": "1.2.0",
+    "@types/lodash": "^4.17.27",
+    "eslint": "^10.6.0",
+    "typescript": "^6.0.3"
+  },
+  "prettier": "@stdex/presets-prettier/prettierrc",
+  "scripts": {
+    "build": "npm run clear && tsc",
+    "watch": "npm run clear && tsc --watch",
+    "clear": "rm -rf dist",
+    "lint": "tsc --noEmit && eslint './src/'"
+  }
 }

package/src/array.ts

@@ -0,0 +1,97 @@
+import { success, failure } from '@stdex/utils'
+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 failure(`${field} should be an array`)
+      }
+
+      let formatted = []
+      if (typeof options.min === 'number' && value.length < options.min)
+        return failure(`array ${field}'s length should >= ${options.min}`)
+
+      if (typeof options.max === 'number' && value.length > options.max)
+        return failure(`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 failure(`${field} should be an array`)
+      if (value.length > options.tuple.length)
+        return failure(`${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/base.ts

@@ -0,0 +1,145 @@
+import { success, failure, type Result } from '@stdex/utils'
+
+/**
+ * 支持传入进行验证的值类型
+ */
+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) => Result<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): Result<Validated<Value, InputOptions>>
+  (field: string, input: AllowedInputValue): Result<Validated<Value, InputOptions>>
+}
+
+// -----------------------------------
+
+/**
+ * 返回支持指定格式的 options、并按照传入的逻辑进行验证的 validator 的生成器。
+ * 对 CommonOptions 相关内容的验证以自动包含在里面，只需要传入额外的验证逻辑即可。
+ */
+export function getValidatorGenerator<Value, Options extends CommonOptions>(
+  validate: (
+    field: string,
+    input: PrimitiveType | Validated<Value, Options>,
+    options: Options,
+  ) => Result<Value>,
+) {
+  return function validatorGenerator<const InputOptions extends Options>(
+    inputOptions: InputOptions,
+  ): Validator<Value, InputOptions> {
+    type Return = Result<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 failure(`${field} is required`)
+        }
+      }
+      if (value === null && !allowNull) return failure(`${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/boolean.ts

@@ -0,0 +1,21 @@
+import { success, failure } from '@stdex/utils'
+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 ? failure(`${field} must be true or false`) : success(value)
+  },
+)

package/src/datetime.ts

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