Class VineOptional<Output>

VineOptional represents an optional value inside a union or schema. It allows both null and undefined values to pass validation.

This type is typically used with unions to make certain branches optional, or to explicitly mark a field as allowing undefined/null values.

Example

const schema = vine.object({
  name: vine.string().optional()
})

Example

const schema = vine.unionOfTypes([
  vine.string(),
  vine.optional()
])

Type Parameters

Output
The output type when the value is defined

Hierarchy (View Summary)

ConditionalValidations
- VineOptional

Implements

ConstructableSchema<null | undefined, Output, Output>

Index

Constructors

constructor

new VineOptional<Output>(
options?: Partial<FieldOptions>,
validations?: Validation<any>[],
): VineOptional<Output>
Creates a new VineOptional instance.
Type Parameters
- Output
  The output type when the value is defined
Parameters
- Optionaloptions: Partial<FieldOptions>
  Field options like bail mode and nullability
- Optionalvalidations: Validation<any>[]
  Initial set of validations to apply
Returns VineOptional<Output>
Overrides ConditionalValidations.constructor
- Defined in src/schema/optional/main.ts:108

Properties

[ITYPE]

"[ITYPE]": null | undefined

The input type of the schema (null or undefined)

[OTYPE]

"[OTYPE]": Output

The output type of the schema when value is defined

[COTYPE]

"[COTYPE]": Output

The camelCase output type of the schema

[SUBTYPE]

"[SUBTYPE]": string = 'optional'

The subtype identifier for the literal schema field

[UNIQUE_NAME]

"[UNIQUE_NAME]": string = 'vine.optional'

Unique name identifier for union type resolution

Methods

requiredWhen

requiredWhen<Operator extends ComparisonOperators>(
    otherField: string,
    operator: Operator,
    expectedValue: Operator extends ArrayComparisonOperators
        ? (string | number | boolean)[]
        : Operator extends NumericComparisonOperators
            ? number
            : string
            | number
            | boolean,
): this
Marks the field as required when a condition is met. Can be used with a callback or with comparison operators to compare another field's value.
Type Parameters
- Operator extends ComparisonOperators
Parameters
- otherField: string
  Field name to compare or callback function
- operator: Operator
  Comparison operator (=, !=, in, notIn, >, <, >=, <=)
- expectedValue: Operator extends ArrayComparisonOperators
      ? (string | number | boolean)[]
      : Operator extends NumericComparisonOperators
          ? number
          : string
          | number
          | boolean
  Expected value to compare against
Returns this
Example
```
vine.string().optional().requiredWhen('role', '=', 'admin')
```
Example
```
vine.string().optional().requiredWhen('age', '>', 18)
```
Example
```
vine.string().optional().requiredWhen((field) => field.data.isAdmin === true)
```
Inherited from ConditionalValidations.requiredWhen
- Defined in src/schema/base/conditional_rules.ts:46
requiredWhen(callback: (field: FieldContext) => boolean): this
Marks the field as required when a condition is met. Can be used with a callback or with comparison operators to compare another field's value.
Parameters
- callback: (field: FieldContext) => boolean
Returns this
Example
```
vine.string().optional().requiredWhen('role', '=', 'admin')
```
Example
```
vine.string().optional().requiredWhen('age', '>', 18)
```
Example
```
vine.string().optional().requiredWhen((field) => field.data.isAdmin === true)
```
Inherited from ConditionalValidations.requiredWhen
- Defined in src/schema/base/conditional_rules.ts:55

requiredIfExists

requiredIfExists(fields: string | string[]): VineOptional<Output>
Marks the field as required when all specified fields exist (are not undefined or null).
Parameters
- fields: string | string[]
  Field name or array of field names to check for existence
Returns VineOptional<Output>
Example
```
vine.string().optional().requiredIfExists('email')
```
Example
```
vine.string().optional().requiredIfExists(['firstName', 'lastName'])
```
Inherited from ConditionalValidations.requiredIfExists
- Defined in src/schema/base/conditional_rules.ts:121

requiredIfAnyExists

requiredIfAnyExists(fields: string[]): VineOptional<Output>
Marks the field as required when any one of the specified fields exists (is not undefined or null).
Parameters
- fields: string[]
  Array of field names to check for existence
Returns VineOptional<Output>
Example
```
vine.string().optional().requiredIfAnyExists(['email', 'phone'])
```
Inherited from ConditionalValidations.requiredIfAnyExists
- Defined in src/schema/base/conditional_rules.ts:140

requiredIfMissing

requiredIfMissing(fields: string | string[]): VineOptional<Output>
Marks the field as required when all specified fields are missing (undefined or null).
Parameters
- fields: string | string[]
  Field name or array of field names to check for absence
Returns VineOptional<Output>
Example
```
vine.string().optional().requiredIfMissing('addressId')
```
Example
```
vine.string().optional().requiredIfMissing(['street', 'city'])
```
Inherited from ConditionalValidations.requiredIfMissing
- Defined in src/schema/base/conditional_rules.ts:161

requiredIfAnyMissing

requiredIfAnyMissing(fields: string[]): VineOptional<Output>
Marks the field as required when any one of the specified fields is missing (undefined or null).
Parameters
- fields: string[]
  Array of field names to check for absence
Returns VineOptional<Output>
Example
```
vine.string().optional().requiredIfAnyMissing(['street', 'city', 'zipCode'])
```
Inherited from ConditionalValidations.requiredIfAnyMissing
- Defined in src/schema/base/conditional_rules.ts:180

[IS_OF_TYPE]

"[IS_OF_TYPE]"(value: unknown): value is null | undefined
Type checker function to determine if a value is optional (null or undefined). Required for "unionOfTypes" functionality.
Parameters
- value: unknown
  The value to check
Returns value is null | undefined
Implementation of ConstructableSchema.[IS_OF_TYPE]
- Defined in src/schema/optional/main.ts:88

parse

parse(callback: ParseFn): this
Define a method to parse the input value. The method is invoked before any validation and hence you must perform type-checking to know the value you are working with.
Parameters
- callback: ParseFn
  Parser function to transform the input value
Returns this
- Defined in src/schema/optional/main.ts:168

use

use(validation: Validation<any> | RuleBuilder): this
Push a validation to the validations chain.
Parameters
- validation: Validation<any> | RuleBuilder
  Validation rule or rule builder to add
Returns this
Overrides ConditionalValidations.use
- Defined in src/schema/optional/main.ts:178

bail

bail(state: boolean): VineOptional<Output>
Enable/disable the bail mode. In bail mode, the field validations are stopped after the first error.
Parameters
- state: boolean
  True to enable bail mode, false to disable
Returns VineOptional<Output>
- Defined in src/schema/optional/main.ts:189

clone

clone(): this
Clones the VineOptional schema type. The applied options and validations are copied to the new instance.

Returns this
A cloned instance of this VineOptional schema
Implementation of ConstructableSchema.clone
- Defined in src/schema/optional/main.ts:200

nullable

nullable(): VineOptional<null | undefined>
Mark the field under validation to be nullable. The null value will be written to the output as well. When combined with optional, both null and undefined values are allowed.

Returns VineOptional<null | undefined>
- Defined in src/schema/optional/main.ts:209

toJSONSchema

toJSONSchema(): JSONSchema7
Transforms into JSON Schema format.

Returns JSONSchema7
Implementation of ConstructableSchema.toJSONSchema
- Defined in src/schema/optional/main.ts:219

[PARSE]

"[PARSE]"(
    propertyName: string,
    refs: RefsStore,
    options: ParserOptions,
): FieldNode & {} & { subtype: string }
Compiles the schema type to a compiler node.
Parameters
- propertyName: string
  The name of the property being validated
- refs: RefsStore
  Reference store for tracking validators and parsers
- options: ParserOptions
  Parser options including camelCase transformation
Returns FieldNode & {} & { subtype: string }
Implementation of ConstructableSchema.[PARSE]
- Defined in src/schema/optional/main.ts:230

Class VineOptional<Output>

Example

Example

Type Parameters

Hierarchy (View Summary)

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Type Parameters

Parameters

Returns VineOptional<Output>

Properties

[ITYPE]

[OTYPE]

[COTYPE]

[SUBTYPE]

[UNIQUE_NAME]

Methods

requiredWhen

Type Parameters

Parameters

Returns this

Example

Example

Example

Parameters

Returns this

Example

Example

Example

requiredIfExists

Parameters

Returns VineOptional<Output>

Example

Example

requiredIfAnyExists

Parameters

Returns VineOptional<Output>

Example

requiredIfMissing

Parameters

Returns VineOptional<Output>

Example

Example

requiredIfAnyMissing

Parameters

Returns VineOptional<Output>

Example

[IS_OF_TYPE]

Parameters

Returns value is null | undefined

parse

Parameters

Returns this

use

Parameters

Returns this

bail

Parameters

Returns VineOptional<Output>

clone

Returns this

nullable

Returns VineOptional<null | undefined>

toJSONSchema

Returns JSONSchema7

[PARSE]

Parameters

Returns FieldNode & {} & { subtype: string }

Settings

On This Page