Libraries (v1.1.10)
    Preparing search index...

    Class UnionSchemaBuilder<TOptions, TRequired, TExplicitType>

    Union schema builder class. Allows to create schemas containing alternatives. E.g. string | number | Date. Use it when you want to define a schema for a value that can be of different types. The type of the value will be determined by the first schema that succeeds validation. Any schema type can be supplied as variant. Which means that you are not limited to primitive types and can construct complex types as well, e.g. object | array.

    NOTE this class is exported only to give opportunity to extend it by inheriting. It is not recommended to create an instance of this class directly. Use union() function instead.

    const schema = union(string('foo')).or(string('bar'));
    const result = await schema.validate('foo');
    // result.valid === true
    // result.object === 'foo'

    const schema = union(string('foo')).or(string('bar'));
    const result = await schema.validate('baz');
    // result.valid === false

    const schema = union(string('yes')).or(string('no')).or(number(0)).or(number(1));
    // equals to 'yes' | 'no' | 0 | 1 in TS
    const result = await schema.validate('yes');
    // result.valid === true
    // result.object === 'yes'

    const result2 = await schema.validate(0);
    // result2.valid === true
    // result2.object === 0

    const result3 = await schema.validate('baz');
    // result3.valid === false

    const result4 = await schema.validate(2);
    // result4.valid === false

    union

    Type Parameters

    • TOptions extends readonly SchemaBuilder<any, any>[]
    • TRequired extends boolean = true
    • TExplicitType = undefined

    Hierarchy (View Summary)

    Index

    Accessors

    isRequired preprocessors type validators

    Methods

    addPreprocessor addValidator assureValidationErrorMessageProvider clearHasType clearPreprocessors clearValidators createFromProps getValidationErrorMessage hasType introspect or preValidate removeFirstOption removeOption reset validate

    Accessors

    • get isRequired(): TRequired

      Whether the schema requires a non-null/non-undefined value.

      Returns TRequired

    • set isRequired(value: boolean): void

      Sets the requirement flag. Must be a boolean.

      Parameters

      • value: boolean

      Returns void

    • get preprocessors(): Preprocessor<TResult>[]

      A list of preprocessors associated with the Builder

      Returns Preprocessor<TResult>[]

    • get type(): string

      The string identifier of the schema type (e.g. 'string', 'number', 'object').

      Returns string

    • set type(value: string): void

      Sets the schema type identifier. Must be a non-empty string.

      Parameters

      • value: string

      Returns void

    • get validators(): Validator<TResult>[]

      A list of validators associated with the Builder

      Returns Validator<TResult>[]

    Methods

    • Ensures a ValidationErrorMessageProvider is valid. If provider is undefined, falls back to defaultValue. Function providers are bound to this for access to schema state.

      Parameters

      • provider: ValidationErrorMessageProvider<any> | undefined

        the provider to validate, or undefined

      • defaultValue: ValidationErrorMessageProvider<any>

        fallback provider when provider is not supplied

      Returns ValidationErrorMessageProvider<any>

      a valid ValidationErrorMessageProvider

    • Protected method used to create a new instance of the Builder defined by the props object. Should be used to instantiate new builders to keep builder's immutability.

      Type Parameters

      Parameters

      • props: UnionSchemaBuilderCreateProps<T, TReq>

        arbitrary props object

      Returns this

    • Resolves a ValidationErrorMessageProvider to a string error message. Handles both string providers and function providers (sync or async).

      Parameters

      • provider: ValidationErrorMessageProvider<any>

        the error message provider (string or function)

      • seenValue: TExplicitType extends undefined ? SchemaArrayToUnion<TOptions> : TExplicitType

        the value that caused the validation error

      Returns Promise<string>

      the resolved error message string

    • Generates a serializable object describing the defined schema

      Returns {
          isRequired: boolean;
          options: TOptions;
          preprocessors: readonly Preprocessor<
              TExplicitType extends undefined
                  ? SchemaArrayToUnion<TOptions>
                  : TExplicitType,
          >[];
          requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<
              SchemaBuilder<any, any>,
          >;
          type: string;
          validators: readonly Validator<
              TExplicitType extends undefined
                  ? SchemaArrayToUnion<TOptions>
                  : TExplicitType,
          >[];
      }

      • isRequired: boolean

        If set to false, schema will be optional (null or undefined values will be considered as valid).

      • options: TOptions

        Array of schemas participating in the union.

      • preprocessors: readonly Preprocessor<
            TExplicitType extends undefined
                ? SchemaArrayToUnion<TOptions>
                : TExplicitType,
        >[]

        Array of preprocessor functions

      • requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any>>

        Custom error message provider for the 'is required' validation error.

      • type: string

        String id of schema type, e.g. string', numberorobject`.

      • validators: readonly Validator<
            TExplicitType extends undefined
                ? SchemaArrayToUnion<TOptions>
                : TExplicitType,
        >[]

        Array of validator functions

    • Runs preprocessors, validators, and the required/optional check on object. Subclasses call this at the start of their validate() implementation to get a preprocessed value wrapped in a transaction, along with any early errors.

      Parameters

      • object: any

        the value to pre-validate

      • Optionalcontext: ValidationContext<SchemaBuilder<any, any>>

        optional validation context settings

      Returns Promise<PreValidationResult<any, { validatedObject: any }>>

      a PreValidationResult containing the preprocessed transaction, context, and any errors

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods