tsbuffer-validator/index.d.ts

Validator for TSBuffer values

/*!
 * TSBuffer Validator v2.1.2
 * -----------------------------------------
 * MIT LICENSE
 * KingWorks (C) Copyright 2023
 * https://github.com/k8w/tsbuffer-validator
 */
import { InterfaceReference } from 'tsbuffer-schema';
import { InterfaceTypeSchema } from 'tsbuffer-schema';
import { IntersectionTypeSchema } from 'tsbuffer-schema';
import { OmitTypeSchema } from 'tsbuffer-schema';
import { OverwriteTypeSchema } from 'tsbuffer-schema';
import { PartialTypeSchema } from 'tsbuffer-schema';
import { PickTypeSchema } from 'tsbuffer-schema';
import { TSBufferProto } from 'tsbuffer-schema';
import { TSBufferSchema } from 'tsbuffer-schema';
import { TypeReference } from 'tsbuffer-schema';
import { UnionTypeSchema } from 'tsbuffer-schema';

/** @public */
export declare interface FlatInterfaceTypeSchema {
    type: InterfaceTypeSchema['type'];
    properties: NonNullable<InterfaceTypeSchema['properties']>;
    indexSignature?: InterfaceTypeSchema['indexSignature'];
}

export declare class ProtoHelper {
    readonly proto: TSBufferProto;
    constructor(proto: TSBufferProto);
    /** 将ReferenceTypeSchema层层转换为它最终实际引用的类型 */
    parseReference(schema: TSBufferSchema): Exclude<TSBufferSchema, TypeReference>;
    isInterface(schema: TSBufferSchema, excludeReference?: boolean): schema is InterfaceTypeSchema | InterfaceReference;
    isMappedType(schema: TSBufferSchema): schema is Exclude<InterfaceReference, TypeReference>;
    isTypeReference(schema: TSBufferSchema): schema is TypeReference;
    getUnionProperties(schema: UnionTypeSchema | IntersectionTypeSchema): string[];
    /**
     * unionProperties: 在Union或Intersection类型中，出现在任意member中的字段
     */
    /**
     * 将unionProperties 扩展到 InterfaceTypeSchema中（optional的any类型）
     * 以此来跳过对它们的检查（用于Intersection/Union）
     */
    applyUnionProperties(schema: FlatInterfaceTypeSchema, unionProperties: string[]): FlatInterfaceTypeSchema;
    /**
     * 将interface及其引用转换为展平的schema
     */
    getFlatInterfaceSchema(schema: InterfaceTypeSchema | InterfaceReference): FlatInterfaceTypeSchema;
    /**
     * 展平interface
     */
    /** 将MappedTypeSchema转换为展平的Interface
     */
    parseMappedType(schema: PickTypeSchema | OmitTypeSchema | PartialTypeSchema | OverwriteTypeSchema): InterfaceTypeSchema | UnionTypeSchema | IntersectionTypeSchema;
}

/** @public */
export declare type PruneOutput<T> = {
    isSucc: true;
    pruneOutput: T;
    errMsg?: undefined;
} | {
    isSucc: false;
    errMsg: string;
    pruneOutput?: undefined;
};

/**
 * TSBuffer Schema Validator
 * @public
 */
export declare class TSBufferValidator<Proto extends TSBufferProto = TSBufferProto> {
    /**
     * Default options
     */
    options: TSBufferValidatorOptions;
    proto: Proto;
    readonly protoHelper: ProtoHelper;
    constructor(proto: Proto, options?: Partial<TSBufferValidatorOptions>);
    /**
     * Validate whether the value is valid to the schema
     * @param value - Value to be validated.
     * @param schemaId - Schema or schema ID.
     * For example, the schema ID for type `Test` in `a/b.ts` may be `a/b/Test`.
     */
    validate(value: any, schemaOrId: keyof Proto | TSBufferSchema, options?: Partial<ValidateOptions>): ValidateOutput;
    /**
     * 修剪 Object，移除 Schema 中未定义的 Key
     * 需要确保 value 类型合法
     * @param value - value to be validated
     * @param schemaOrId -Schema or schema ID.
     * @returns Validate result and pruned value. if validate failed, `pruneOutput` would be undefined.
     */
    prune<T>(value: T, schemaOrId: string | TSBufferSchema, options?: Partial<ValidateOptions>): PruneOutput<T>;
}

/** @public */
export declare interface TSBufferValidatorOptions {
    /**
     * 检查interface中是否包含Schema之外的字段
     *
     * 例1：
     * ```
     * type AB = { a: string, b: string };
     * let ab: AB = { a: 'x', b: 'x', c: 'x' }
     * ```
     * 字段 `c` 为 excess property，当 `excessPropertyChecks` 启用时将会报错。
     *
     * 例2：
     * ```
     * type AB = { a: string} | { b: string };
     * let ab: AB = { a: 'x', b: 'x', c: 'x' }
     * ```
     * 字段 `c` 为 excess property，当 `excessPropertyChecks` 启用时将会报错。
     *
     * 默认：`true`
     */
    excessPropertyChecks: boolean;
    /**
     * 同 `tsconfig.json` 中的 `strictNullChecks`
     * 是否使用严格等于去判定 `undefined` 和 `null`
     * @defaultValue false
     */
    strictNullChecks: boolean;
    /**
     * Clone the proto, don't change this if you don't know what it is.
     * @defaultValue true
     */
    cloneProto?: boolean;
}

/**
 * 单次validate的选项，会向下透传
 * @public
 */
export declare interface ValidateOptions extends TSBufferValidatorOptions {
    /**
     * Common properties from Union/Intersection type
     * ( In case of they are treated as excess property and lead to validation error )
     */
    unionProperties?: string[];
}

/** @public */
export declare type ValidateOutput = {
    isSucc: true;
    errMsg?: undefined;
} | {
    isSucc: false;
    errMsg: string;
};

export { }