Class ObjectSchemaBuilder<TProperties, TRequired, TExplicitType>

Object schema builder class. Similar to the object type in JS. Allows to define a schema for object value. Should be used to validate objects with specific properties. Properties should be defined as their own schema builders. You can use any SchemaBuilder e.g. string(), number(), boolean(), array(), object(), etc. to define properties. Which means that you can define nested objects and arrays of any complexity.

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 () function instead.

Example

const schema = object({
   name: string(),
   age: number()
});

const result = await schema.validate({
  name: 'John',
  age: 30
});

// result.valid === true
// result.object === { name: 'John', age: 30 }

Example

const schema = object({
  name: string(),
  age: number().optional()
});

const result = await schema.validate({
 name: 'John'
});
// result.valid === true
// result.object === { name: 'John' }

Example

const schema = object({
 name: string(),
 age: number();
});
const result = await schema.validate({
 name: 'John'
});

// result.valid === false
// result.errors[0].message === "is expected to have property 'age'"

Example

const schema = object({
name: string(),
address: object({
    city: string(),
    country: string()
  })
});
const result = await schema.validate({
name: 'John',
address: {
   city: 'New York',
   country: 'USA'
 }
});
// result.valid === true
// result.object === {
//   name: 'John',
//   address: {
//     city: 'New York',
//     country: 'USA'
//   }
// }

See

object

Type Parameters

  • TProperties extends Record<string, SchemaBuilder<any, any>> = {}

  • TRequired extends boolean = true

  • TExplicitType = undefined

Hierarchy

  • SchemaBuilder<undefined extends TExplicitType
        ? RespectPropsOptionality<TProperties>
        : TExplicitType, TRequired>
    • ObjectSchemaBuilder

Accessors

isRequired preprocessors type validators

Methods

acceptUnknownProps addPreprocessor addProp addProps addValidator clearPreprocessors clearValidators createFromProps intersect introspect makeAllPropsOptional makeAllPropsRequired makePropOptional makePropRequired modifyPropSchema notAcceptUnknownProps omit partial pick preValidate validate create

Accessors

Protected isRequired

Protected preprocessors

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

  • A list of preprocessors associated with the Builder

    Returns Preprocessor<TResult>[]

Protected type

Protected validators

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

  • A list of validators associated with the Builder

    Returns Validator<TResult>[]

Methods

acceptUnknownProps

addPreprocessor

addProp

  • Adds a new property to the object schema. The new property will be validated according to the provided schema.

    Type Parameters

    Parameters

    • propName: TName

      name of the new property

    • schema: TType

      schema builder of the new property

    Returns ObjectSchemaBuilder<TProperties & {
        [k in string]: TType
    }, TRequired, TExplicitType>

addProps

  • Adds new properties to the object schema. The same as .addProp() but allows to add multiple properties with one call. The new properties will be validated according to the provided schemas.

    Type Parameters

    Parameters

    • props: TProps

      a key/schema object map.

    Returns ObjectSchemaBuilder<TProperties & TProps, true, undefined>

  • Adds all properties from the schema object schema to the current schema.

    Type Parameters

    Parameters

    • schema: K

      an instance of ObjectSchemaBuilder

    Returns K extends ObjectSchemaBuilder<TProp, TReq, TExpType>
        ? ObjectSchemaBuilder<Omit<TProperties, keyof TProp> & TProp, TRequired, TExplicitType>
        : never

addValidator

clearPreprocessors

clearValidators

Protected createFromProps

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

    Type Parameters

    • T extends Record<string, SchemaBuilder<any, true>>

    • R extends boolean = true

    Parameters

    • props: Partial<{
          acceptUnknownProps: boolean;
          isRequired: boolean;
          preprocessors: readonly Preprocessor<RespectPropsOptionality<T>>[];
          properties: T;
          type: string;
          validators: readonly Validator<RespectPropsOptionality<T>>[];
      }>

      arbitrary props object

    Returns ObjectSchemaBuilder<TProperties, TRequired, TExplicitType>

intersect

  • Adds all properties from schema to the current schema. TSchema & TAnotherSchema is a good example of the similar concept in the TS type system.

    Type Parameters

    Parameters

    • schema: T

      an object schema to take properties from

    Returns T extends ObjectSchemaBuilder<TProps, TReq, TExplType>
        ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps> & TProps, TRequired, TExplType>
        : never

introspect

  • Generates a serializable object describing the defined schema

    Returns {
        acceptUnknownProps: boolean;
        isRequired: boolean;
        preprocessors: readonly Preprocessor<undefined extends TExplicitType
            ? RespectPropsOptionality<TProperties>
            : TExplicitType>[];
        properties: TProperties;
        type: string;
        validators: readonly Validator<undefined extends TExplicitType
            ? RespectPropsOptionality<TProperties>
            : TExplicitType>[];
    }

    • acceptUnknownProps: boolean

      If set to true, schema validation will not return errors if object contains fields which are not defined in the schema properties. Set to false by default

    • isRequired: boolean

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

    • preprocessors: readonly Preprocessor<undefined extends TExplicitType
          ? RespectPropsOptionality<TProperties>
          : TExplicitType>[]

      Array of preprocessor functions

    • properties: TProperties

      Properties defined in schema

    • type: string

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

    • validators: readonly Validator<undefined extends TExplicitType
          ? RespectPropsOptionality<TProperties>
          : TExplicitType>[]

      Array of validator functions

makeAllPropsOptional

makeAllPropsRequired

makePropOptional

  • An alias for .partial(prop: string)

    Type Parameters

    • K extends string | number | symbol

    Parameters

    • prop: K

      name of the property

    Returns ObjectSchemaBuilder<MakeChildOptional<TProperties, K>, TRequired, TExplicitType>

makePropRequired

  • Marks prop as required property. If prop does not exists in the current schema, an error will be thrown.

    Type Parameters

    • K extends string | number | symbol

    Parameters

    • prop: K

      name of the property

    Returns ObjectSchemaBuilder<MakeChildRequired<TProperties, K>, TRequired, TExplicitType>

modifyPropSchema

  • Modify schema for propName and return a new schema. Could be useful if you want to leave all schema intact, but change a type of one property.

    Type Parameters

    • K extends string | number | symbol

    • R extends SchemaBuilder<any, any>

    Parameters

    • propName: K

      name of the property (string)

    • callback: ((builder) => R)

      callback function returning a new schema fo the propName. As a first parameter you will receive an old schema for propName.

        • (builder): R

        • Parameters

          • builder: TProperties[K]

          Returns R

    Returns ObjectSchemaBuilder<ModifyPropSchema<TProperties, K, R>, TRequired, TExplicitType>

notAcceptUnknownProps

omit

  • Omits properties listed in properties from the schema. Consider Omit<Type, 'prop1'|'prop2'...> as a good illustration from the TS world.

    Type Parameters

    • K extends string | number | symbol

    Parameters

    • properties: K[]

      array of property names (strings) to remove from the schema.

    Returns ObjectSchemaBuilder<Omit<TProperties, K>, TRequired, TExplicitType>

  • Removes propName from the list of properties.

    Type Parameters

    • TProperty extends string | number | symbol

    Parameters

    • propName: TProperty

      property name to remove. Schema should contain this property. An error will be thrown otherwise.

    Returns ObjectSchemaBuilder<Omit<TProperties, TProperty>, TRequired, TExplicitType>

  • Removes all properties of schema from the current schema. Omit<TSchema, keyof TAnotherSchema> as a good illustration from the TS world.

    Type Parameters

    • T

    Parameters

    • schema: T

      schema builder to take properties from.

    Returns T extends ObjectSchemaBuilder<TProps, TRequired, TExplicitType>
        ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps>, TRequired, TExplicitType>
        : never

partial

  • Marks all properties in the current schema as optional. It is the same as call .optional('propname') where propname is the name of every property in the schema.

    Returns ObjectSchemaBuilder<MakeChildrenOptional<TProperties>, TRequired, TExplicitType>

  • Marks all properties from properties as optional in the schema.

    Type Parameters

    • K extends string | number | symbol

    Parameters

    • properties: K[]

      list of property names (string) to make optional

    Returns ObjectSchemaBuilder<Omit<TProperties, K> & Pick<MakeChildrenOptional<TProperties>, K>, TRequired, TExplicitType>

  • Marks property propName as optional in the schema.

    Type Parameters

    • TProperty extends string | number | symbol

    Parameters

    • propName: TProperty

      the name of the property (string).

    Returns ObjectSchemaBuilder<Omit<TProperties, TProperty> & Pick<MakeChildrenOptional<TProperties>, TProperty>, TRequired, TExplicitType>

pick

  • Returns a new schema containing only properties listed in properties array.

    Type Parameters

    • K extends string | number | symbol

    Parameters

    • properties: K[]

      array of property names (strings)

    Returns ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, undefined>

  • Returns new schema based on the current schema. This new schema will consists only from properties which names are taken from the schema object schema.

    Type Parameters

    Parameters

    • schema: K

      schema to take property names list from

    Returns K extends ObjectSchemaBuilder<TProps, T1, T2>
        ? ObjectSchemaBuilder<Omit<TProperties, Exclude<keyof TProperties, keyof TProps>>, TRequired, undefined>
        : never

  • Returns a new schema consisting of only one property (taken from the property property name). If the property does not exists in the current schema, an error will be thrown.

    Type Parameters

    • K extends string | number | symbol

    Parameters

    • property: K

      the name of the property (string).

    Returns ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, undefined>

Protected preValidate

  • Parameters

    • object: any

      Object to validate

    • Optional context: ValidationContext

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

validate

  • Performs validion of object schema over the object.

    Parameters

    • object: undefined extends TExplicitType
          ? RespectPropsOptionality<TProperties>
          : TExplicitType
    • Optional context: ValidationContext

      Optional ValidationContext settings.

    Returns Promise<ValidationResult<undefined extends TExplicitType
        ? RespectPropsOptionality<TProperties>
        : TExplicitType>>

Static create

  • Type Parameters

    • P extends Record<string, SchemaBuilder<any, true>>

    • R extends boolean

    Parameters

    • props: Partial<{
          acceptUnknownProps: boolean;
          isRequired: boolean;
          preprocessors: readonly Preprocessor<RespectPropsOptionality<P>>[];
          properties: P;
          type: string;
          validators: readonly Validator<RespectPropsOptionality<P>>[];
      }>

    Returns ObjectSchemaBuilder<{}, true, undefined>

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc