@stdex/validator 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 安坚实
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+通用数据格式验证模块，支持自动类型推理

package/dist/array.d.ts

@@ -0,0 +1,30 @@
+import { type CommonOptions, type Validator, type Validated } 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 declare function getArrayValidator<Options extends ArrayOptions>(options: Options): Validator<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 declare function getTupleValidator<const Options extends TupleOptions>(options: Options): Validator<TupleValues<Options>, Options>;
+export {};

package/dist/array.js

@@ -0,0 +1,47 @@
+import { success, failure } from '@stdex/utils/result.js';
+import { getValidatorGenerator, } from './base.js';
+export function getArrayValidator(options) {
+    return getValidatorGenerator(function validate(field, value, options) {
+        if (!Array.isArray(value)) {
+            if (options.toArray)
+                value = [value];
+            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);
+    })(options);
+}
+export function getTupleValidator(options) {
+    return getValidatorGenerator(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);
+    })(options);
+}

package/dist/base.d.ts

@@ -0,0 +1,82 @@
+import { type Result } from '@stdex/utils/result.js';
+/**
+ * 支持传入进行验证的值类型
+ */
+export type AllowedInputValue = PrimitiveType | null | undefined;
+/**
+ * JavaScript 基础值类型
+ */
+export type PrimitiveType = string | boolean | number | PrimitiveType[] | [...PrimitiveType[]] | {
+    [key: string]: PrimitiveType;
+};
+/**
+ * validator 通用参数
+ */
+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>;
+    [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 declare function getValidatorGenerator<Value, Options extends CommonOptions>(validate: (field: string, input: PrimitiveType | Validated<Value, Options>, options: Options) => Result<Value>): <const InputOptions extends Options>(inputOptions: InputOptions) => Validator<Value, InputOptions>;
+/**
+ * 返回只进行基本检查，不带定制的验证逻辑的 validator。
+ * 同时也是定制 validator 最小化实现的例子。
+ */
+export declare const getAnyValidator: <const InputOptions extends CommonOptions<any>>(inputOptions: InputOptions) => Validator<unknown, InputOptions>;
+export {};

package/dist/base.js

@@ -0,0 +1,42 @@
+import { success, failure } from '@stdex/utils/result.js';
+// -----------------------------------
+/**
+ * 返回支持指定格式的 options、并按照传入的逻辑进行验证的 validator 的生成器。
+ * 对 CommonOptions 相关内容的验证以自动包含在里面，只需要传入额外的验证逻辑即可。
+ */
+export function getValidatorGenerator(validate) {
+    return function validatorGenerator(inputOptions) {
+        function validator(field, input) {
+            // 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 = input;
+            if (typeof value === 'undefined') {
+                if (typeof defaults !== 'undefined') {
+                    value = defaults;
+                }
+                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(function validate(field, input) {
+    return success(input);
+});

package/dist/boolean.d.ts

@@ -0,0 +1,3 @@
+import { type CommonOptions } from './base.js';
+export type BooleanOptions = CommonOptions<boolean>;
+export declare const getBooleanValidator: <const InputOptions extends BooleanOptions>(inputOptions: InputOptions) => import("./base.js").Validator<boolean, InputOptions>;

package/dist/boolean.js

@@ -0,0 +1,22 @@
+import { success, failure } from '@stdex/utils/result.js';
+import { getValidatorGenerator } from './base.js';
+export const getBooleanValidator = getValidatorGenerator(function validate(field, input) {
+    let value = 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/dist/datetime.d.ts

@@ -0,0 +1,9 @@
+import { type Dayjs } from 'dayjs';
+import { type CommonOptions } from './base.js';
+export interface DatetimeOptions extends CommonOptions<number> {
+    dayjs?: boolean;
+}
+export type DatetimeValue<Options extends DatetimeOptions> = Options extends {
+    dayjs: true;
+} ? Dayjs : Date;
+export declare function getDatetimeValidator<const Options extends DatetimeOptions>(options?: Options): import("./base.js").Validator<DatetimeValue<Options>, Options>;

package/dist/datetime.js

@@ -0,0 +1,30 @@
+/**
+ * 验证日期时间类型的值，依赖 dayjs
+ */
+import { success, failure } from '@stdex/utils/result.js';
+import dayjs from 'dayjs';
+import { getValidatorGenerator } from './base.js';
+export function getDatetimeValidator(options = {}) {
+    return getValidatorGenerator(function validate(field, value) {
+        let dayjsValue;
+        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()));
+    })(options);
+}

package/dist/factory.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 实现创建 validator 的快捷方式
+ */
+import { type ArrayOptions, type TupleOptions } from './array.js';
+import { type Validator, type CommonOptions, type Validated } from './base.js';
+import { type BooleanOptions } from './boolean.js';
+import { type DatetimeOptions, type DatetimeValue } from './datetime.js';
+import { type NumberOptions, type NumberValueWithChoices } from './number.js';
+import { type RecordOptions, type StructOptions } from './object.js';
+import { type OneOfOptions } from './one-of.js';
+import { type StringOptions, type StringValueWithChoices } from './string.js';
+export interface AnyDefinition extends CommonOptions {
+    type: 'any';
+}
+export interface BooleanDefinition extends BooleanOptions {
+    type: 'boolean';
+}
+export interface NumberDefinition extends NumberOptions {
+    type: 'number';
+}
+export interface StringDefinition extends StringOptions {
+    type: 'string';
+}
+export interface DatetimeDefinition extends DatetimeOptions {
+    type: 'datetime';
+}
+export interface ArrayDefinition extends Omit<ArrayOptions, 'item'> {
+    type: 'array';
+    item: Definition;
+}
+export interface TupleDefinition extends Omit<TupleOptions, 'tuple'> {
+    type: 'tuple';
+    tuple: Definition[];
+}
+export interface StructDefinition extends Omit<StructOptions, 'struct'> {
+    type: 'struct';
+    struct: Record<string, Definition>;
+}
+export interface RecordDefinition extends Omit<RecordOptions, 'record'> {
+    type: 'record';
+    record: Definition;
+}
+export interface OneOfDefinition extends Omit<OneOfOptions, 'validators'> {
+    type: 'oneOf';
+    validators: Definition[];
+}
+export type Definition = AnyDefinition | BooleanDefinition | NumberDefinition | StringDefinition | DatetimeDefinition | ArrayDefinition | TupleDefinition | StructDefinition | RecordDefinition | OneOfDefinition;
+export type ValueOfDefinition<Def extends Definition> = Def extends AnyDefinition ? unknown : Def extends BooleanDefinition ? boolean : Def extends NumberDefinition ? NumberValueWithChoices<Def> : Def extends StringDefinition ? StringValueWithChoices<Def> : Def extends DatetimeDefinition ? DatetimeValue<Def> : Def extends ArrayDefinition ? Validated<ValueOfDefinition<Def['item']>, Def['item']>[] : Def extends TupleDefinition ? {
+    [Key in keyof Def['tuple']]: Def['tuple'][Key] extends Definition ? Validated<ValueOfDefinition<Def['tuple'][Key]>, Def['tuple'][Key]> : Def['tuple'][Key];
+} : Def extends StructDefinition ? {
+    [Key in keyof Def['struct']]: Validated<ValueOfDefinition<Def['struct'][Key]>, Def['struct'][Key]>;
+} : Def extends RecordDefinition ? Record<string, Validated<ValueOfDefinition<Def['record']>, Def['record']>> : Def extends OneOfDefinition ? {
+    [Key in keyof Def['validators']]: Def['validators'][Key] extends Definition ? Validated<ValueOfDefinition<Def['validators'][Key]>, Def['validators'][Key]> : Def['validators'][Key];
+}[number] : never;
+export type OptionsFromDefinition<Def extends Definition> = Def extends ArrayDefinition ? Omit<Def, 'item'> & {
+    item: ValidatorForDefinition<Def['item']>;
+} : Def extends TupleDefinition ? Omit<Def, 'tuple'> & {
+    tuple: {
+        [Key in keyof Def['tuple']]: Def['tuple'][Key] extends Definition ? ValidatorForDefinition<Def['tuple'][Key]> : never;
+    };
+} : Def extends StructDefinition ? Omit<Def, 'struct'> & {
+    struct: {
+        [Key in keyof Def['struct']]: ValidatorForDefinition<Def['struct'][Key]>;
+    };
+} : Def extends RecordDefinition ? Omit<Def, 'record'> & {
+    record: ValidatorForDefinition<Def['record']>;
+} : Def;
+export type ValidatorForDefinition<Def extends Definition> = Validator<ValueOfDefinition<Def>, OptionsFromDefinition<Def>>;
+export type ResultForDefinition<Def extends Definition> = ReturnType<ValidatorForDefinition<Def>>;
+export declare function getValidator<const InputDefinition extends Definition>(definition: InputDefinition): ValidatorForDefinition<InputDefinition>;

package/dist/factory.js

@@ -0,0 +1,122 @@
+/**
+ * 实现创建 validator 的快捷方式
+ */
+import { getArrayValidator, getTupleValidator, } from './array.js';
+import { getAnyValidator } from './base.js';
+import { getBooleanValidator } from './boolean.js';
+import { getDatetimeValidator } from './datetime.js';
+import { getNumberValidator } from './number.js';
+import { getRecordValidator, getStructValidator, } from './object.js';
+import { getOneOfValidator } from './one-of.js';
+import { getStringValidator } from './string.js';
+export function getValidator(definition) {
+    switch (definition.type) {
+        case 'any':
+            return getAnyValidator(definition);
+        case 'boolean':
+            return getBooleanValidator(definition);
+        case 'number':
+            return getNumberValidator(definition);
+        case 'string':
+            return getStringValidator(definition);
+        case 'datetime':
+            return getDatetimeValidator(definition);
+        case 'array':
+            // @ts-ignore 允许递归类型推断
+            return getArrayValidator({
+                // @ts-ignore 允许递归类型推断
+                ...definition,
+                item: getValidator(definition.item),
+            });
+        case 'tuple':
+            return getTupleValidator({
+                ...definition,
+                tuple: definition.tuple.map(def => getValidator(def)),
+            });
+        case 'struct': {
+            const struct = {};
+            for (const [key, def] of Object.entries(definition.struct))
+                struct[key] = getValidator(def);
+            // @ts-ignore 允许递归类型推断
+            return getStructValidator({ ...definition, struct });
+        }
+        case 'record':
+            return getRecordValidator({
+                ...definition,
+                record: getValidator(definition.record),
+            });
+        case 'oneOf':
+            return getOneOfValidator({
+                ...definition,
+                validators: definition.validators.map(def => getValidator(def)),
+            });
+    }
+}
+// ---------------- 测试用例 -----------------
+// const v1 = getValidator({ type: 'string' })(1)
+// const v2 = getValidator({ type: 'string', null: true })(1)
+// const v3 = getValidator({ type: 'string', null: true, required: false })(1)
+// const v4 = getValidator({ type: 'string', null: true, required: false, choices: ['a', 'b', 'c'] })(
+//   1,
+// )
+// const v5 = getValidator({
+//   type: 'string',
+//   null: true,
+//   required: false,
+//   choices: ['a', 'b', 'c'],
+//   defaults: 'd',
+// })(1)
+// const v6 = getValidator({
+//   type: 'array',
+//   null: true,
+//   required: false,
+//   item: { type: 'string', null: true, choices: ['a', 'b', 'c'] },
+// })(1)
+// const v7 = getValidator({
+//   type: 'tuple',
+//   tuple: [
+//     { type: 'string', choices: ['a', 'b', 'c'] },
+//     { type: 'string', null: true },
+//   ],
+// })(1)
+// if (v7.success) {
+//   const [a, b] = v7.data
+// }
+// const v8 = getValidator({
+//   type: 'struct',
+//   struct: {
+//     x: { type: 'string', choices: ['a', 'b', 'c'] },
+//     y: { type: 'string', null: true },
+//   },
+// })(1)
+// if (v8.success) {
+//   const { x, y } = v8.data
+// }
+// const v9 = getValidator({
+//   type: 'record',
+//   record: { type: 'string', null: true, choices: ['a', 'b', 'c'] },
+// })(1)
+// const v10 = getValidator({
+//   type: 'oneOf',
+//   validators: [
+//     { type: 'string', choices: ['a', 'b', 'c'] },
+//     { type: 'number', null: true },
+//   ],
+//   defaults: true,
+// })(1)
+// const v11 = getValidator({
+//   type: 'string',
+//   custom(value) {
+//     return { success: true, data: value }
+//   },
+//   defaults: 'some text',
+// })(1)
+// const v12 = getValidator({
+//   type: 'datetime',
+//   null: true,
+//   required: false,
+// })(1)
+// const v13 = getValidator({
+//   type: 'datetime',
+//   raw: true,
+// })(1)

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 通用验证器实现
+ *
+ * 使用前提：
+ * - 因为涉及时间对象解析，需安装 dayjs 依赖
+ */
+export * from './base.js';
+export * from './boolean.js';
+export * from './number.js';
+export * from './string.js';
+export * from './datetime.js';
+export * from './array.js';
+export * from './object.js';
+export * from './one-of.js';
+export * from './factory.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * 通用验证器实现
+ *
+ * 使用前提：
+ * - 因为涉及时间对象解析，需安装 dayjs 依赖
+ */
+export * from './base.js';
+export * from './boolean.js';
+export * from './number.js';
+export * from './string.js';
+export * from './datetime.js';
+export * from './array.js';
+export * from './object.js';
+export * from './one-of.js';
+export * from './factory.js';

package/dist/number.d.ts

@@ -0,0 +1,19 @@
+import { type CommonOptions } from './base.js';
+export interface NumberOptions extends CommonOptions<number> {
+    /** 数值最小值 */
+    min?: number;
+    /** 数值最大值 */
+    max?: number;
+    /** 是否允许小数 @default false */
+    float?: boolean;
+    /**
+     * 指定可选值
+     * 若指定，前几个选项将不再生效 */
+    choices?: number[] | Record<number, string>;
+}
+export type NumberValueWithChoices<Options extends NumberOptions> = Options extends {
+    choices: (infer T)[];
+} ? T : Options extends {
+    choices: Record<number, string>;
+} ? Options['choices'][keyof Options['choices']] : number;
+export declare function getNumberValidator<const Options extends NumberOptions>(options?: Options): import("./base.js").Validator<NumberValueWithChoices<Options>, Options>;

package/dist/number.js

@@ -0,0 +1,27 @@
+import { success, failure } from '@stdex/utils/result.js';
+import { truthy } from '@stdex/utils/types.js';
+import { getValidatorGenerator } from './base.js';
+export function getNumberValidator(options = {}) {
+    return getValidatorGenerator(function validate(field, value) {
+        if (typeof value === 'string')
+            value = parseFloat(value);
+        if (typeof value !== 'number' || !isFinite(value))
+            return failure(`${field} must be a valid number`);
+        if ('choices' in options && options.choices) {
+            const choices = Array.isArray(options.choices)
+                ? options.choices
+                : Object.values(options.choices).map(v => parseInt(v, 10));
+            if (!choices.includes(value))
+                return failure(`${field} can only be one of ${choices.join(', ')}.`);
+        }
+        else {
+            if (!truthy(options.float) && value % 1 !== 0)
+                return failure(`${field} must be a integer`);
+            if (typeof options.min === 'number' && value < options.min)
+                return failure(`${field} must >= ${options.min}`);
+            if (typeof options.max === 'number' && value > options.max)
+                return failure(`${field} must <= ${options.max}`);
+        }
+        return success(value);
+    })(options);
+}

package/dist/object.d.ts

@@ -0,0 +1,28 @@
+import { type CommonOptions, type Validator, type Validated } from './base.js';
+/** 验证有明确键值对结构的对象 */
+export interface StructOptions extends CommonOptions {
+    /** 定义对象结构，及各个值的验证规则 */
+    struct: Record<string, Validator<unknown, CommonOptions>>;
+}
+type StructValues<Options extends StructOptions> = {
+    [Key in keyof Options['struct']]: Options['struct'][Key] extends Validator<infer Value, infer Options> ? Validated<Value, Options> : never;
+};
+export declare function getStructValidator<const Options extends StructOptions>(options: Options): Validator<StructValues<Options>, Options>;
+/**
+ * 验证有任意多个 key，但值的类型固定的对象
+ */
+export interface RecordOptions extends CommonOptions {
+    /** 验证单个值  */
+    record: Validator<unknown, CommonOptions>;
+    /** 对象至少要有几项 */
+    min?: number;
+    /** 对象最多有几项 */
+    max?: number;
+}
+type RecordValues<Options extends RecordOptions> = Record<string, Validated<Options extends {
+    record: Validator<infer T, CommonOptions>;
+} ? T : never, Options extends {
+    record: Validator<unknown, infer T>;
+} ? T : never>>;
+export declare function getRecordValidator<Options extends RecordOptions>(options: Options): Validator<RecordValues<Options>, Options>;
+export {};

package/dist/object.js

@@ -0,0 +1,49 @@
+import { success, failure } from '@stdex/utils/result.js';
+import isPlainObject from 'lodash/isPlainObject.js';
+import { getValidatorGenerator, } from './base.js';
+export function getStructValidator(options) {
+    return getValidatorGenerator(function validate(field, value, options) {
+        if (!isPlainObject(value))
+            return failure(`${field} should be a plain object`);
+        const formatted = {};
+        for (const [key, itemValidator] of Object.entries(options.struct)) {
+            const itemResult = itemValidator(`${field}["${key}"]`, value[key]);
+            if (itemResult.success) {
+                if (itemResult.data !== undefined)
+                    formatted[key] = itemResult.data;
+            }
+            else {
+                return itemResult;
+            }
+        }
+        return success(formatted);
+    })(options);
+}
+export function getRecordValidator(options) {
+    return getValidatorGenerator(function validate(field, value, options) {
+        if (!isPlainObject(value))
+            return failure(`${field} should be a plain object`);
+        const formatted = {};
+        for (const [key, itemValue] of Object.entries(value)) {
+            // record 场景下，值为 undefined 的项目视为不存在，不保留在验证结果里，
+            // 不然一些因为不想赋值而填充了 undefined 值的项目可能意外触发验证失败，或意外得到了默认值。
+            // （因此 validator 的 required 选项和 defaults 选项也没有意义了）
+            if (itemValue === undefined)
+                continue;
+            const itemResult = options.record(`${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 options.min === 'number' && length < options.min)
+            return failure(`size of ${field} should >= ${options.min}`);
+        if (typeof options.max === 'number' && length > options.max)
+            return failure(`size of ${field} should <= ${options.max}`);
+        return success(formatted);
+    })(options);
+}