Class VineString

VineString represents a string value in the validation schema. It provides comprehensive string validation with built-in rules for common patterns like email, URL, UUID, and more.

Example

const schema = vine.string()
  .email()
  .minLength(5)
  .maxLength(100)

const result = await vine.validate({
  schema,
  data: 'user@example.com'
})

Hierarchy (View Summary)

BaseLiteralType<string, string, string>
- VineString

Constructors

constructor

new VineString(
options?: FieldOptions,
validations?: Validation<any>[],
): VineString
Creates a new VineString instance with optional configuration.
Parameters
- Optionaloptions: FieldOptions
  Field options like bail mode and nullability
- Optionalvalidations: Validation<any>[]
  Initial set of validations to apply
Returns VineString
Overrides BaseLiteralType.constructor
- Defined in src/schema/string/main.ts:148

Properties

[ITYPE]

"[ITYPE]": string

Define the input type of the schema for TypeScript inference

[OTYPE]

"[OTYPE]": string

The output value type of the field after validation. The property points to a type only and not the real value.

[COTYPE]

"[COTYPE]": string

Type marker for camelCase output type inference

`Optional`dataTypeValidator

dataTypeValidator?: Validation<any>

The validation to use for validating the schema data type. Using a data type validator guards custom rules to only run when the data type validation passes.

Example

class StringSchema extends BaseLiteralType {
  dataTypeValidator = stringDataTypeRule
}

options

options: FieldOptions

Configuration options for this field including bail mode, nullability, and parsing

`Static`rules

rules: {
    in: (
        ...options: [
            options: { choices: string[]
            | ((field: FieldContext) => string[]) },
        ],
    ) => Validation<
        { choices: string[]
        | ((field: FieldContext) => string[]) },
    >;
    jwt: (...options: [options?: undefined]) => Validation<undefined>;
    url: (
        ...options: [options?: IsURLOptions],
    ) => Validation<IsURLOptions | undefined>;
    iban: (...options: [options?: undefined]) => Validation<undefined>;
    uuid: (
        ...options: [options?: { version?: (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8)[] }],
    ) => Validation<
        { version?: (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8)[] }
        | undefined,
    >;
    ulid: (...options: [options?: undefined]) => Validation<undefined>;
    trim: (...options: [options?: undefined]) => Validation<undefined>;
    email: (
        ...options: [options?: IsEmailOptions],
    ) => Validation<IsEmailOptions | undefined>;
    alpha: (
        ...options: [options?: AlphaOptions],
    ) => Validation<AlphaOptions | undefined>;
    ascii: (...options: [options?: undefined]) => Validation<undefined>;
    notIn: (
        ...options: [
            options: { list: string[]
            | ((field: FieldContext) => string[]) },
        ],
    ) => Validation<{ list: string[] | ((field: FieldContext) => string[]) }>;
    regex: (...options: [options: RegExp]) => Validation<RegExp>;
    escape: (...options: [options?: undefined]) => Validation<undefined>;
    sameAs: (
        ...options: [options: { otherField: string }],
    ) => Validation<{ otherField: string }>;
    mobile: (
        ...options: [
            options?: | MobileOptions
            | ((field: FieldContext) => MobileOptions | undefined),
        ],
    ) => Validation<
        | MobileOptions
        | ((field: FieldContext) => MobileOptions | undefined)
        | undefined,
    >;
    string: (...options: [options?: undefined]) => Validation<undefined>;
    hexCode: (...options: [options?: undefined]) => Validation<undefined>;
    passport: (
        ...options: [
            options: PassportOptions
            | ((field: FieldContext) => PassportOptions),
        ],
    ) => Validation<
        PassportOptions
        | ((field: FieldContext) => PassportOptions),
    >;
    endsWith: (
        ...options: [options: { substring: string }],
    ) => Validation<{ substring: string }>;
    confirmed: (
        ...options: [
            options?: { confirmationField?: string }
            | { as?: string },
        ],
    ) => Validation<
        { confirmationField?: string }
        | { as?: string }
        | undefined,
    >;
    activeUrl: (...options: [options?: undefined]) => Validation<undefined>;
    minLength: (
        ...options: [options: { min: number }],
    ) => Validation<{ min: number }>;
    notSameAs: (
        ...options: [options: { otherField: string }],
    ) => Validation<{ otherField: string }>;
    maxLength: (
        ...options: [options: { max: number }],
    ) => Validation<{ max: number }>;
    vat: (
        ...options: [
            options: VATOptions
            | ((field: FieldContext) => VATOptions),
        ],
    ) => Validation<VATOptions | ((field: FieldContext) => VATOptions)>;
    ipAddress: (
        ...options: [options?: { version: 4 | 6 }],
    ) => Validation<{ version: 4 | 6 } | undefined>;
    creditCard: (
        ...options: [
            options?: | CreditCardOptions
            | ((field: FieldContext) => void | CreditCardOptions | undefined),
        ],
    ) => Validation<
        | CreditCardOptions
        | ((field: FieldContext) => void | CreditCardOptions | undefined)
        | undefined,
    >;
    postalCode: (
        ...options: [
            options?: | PostalCodeOptions
            | ((field: FieldContext) => void | PostalCodeOptions | undefined),
        ],
    ) => Validation<
        | PostalCodeOptions
        | ((field: FieldContext) => void | PostalCodeOptions | undefined)
        | undefined,
    >;
    startsWith: (
        ...options: [options: { substring: string }],
    ) => Validation<{ substring: string }>;
    toUpperCase: (
        ...options: [options?: string | string[]],
    ) => Validation<string | string[] | undefined>;
    toLowerCase: (
        ...options: [options?: string | string[]],
    ) => Validation<string | string[] | undefined>;
    toCamelCase: (...options: [options?: undefined]) => Validation<undefined>;
    fixedLength: (
        ...options: [options: { size: number }],
    ) => Validation<{ size: number }>;
    coordinates: (...options: [options?: undefined]) => Validation<undefined>;
    normalizeUrl: (
        ...options: [options?: Options],
    ) => Validation<Options | undefined>;
    alphaNumeric: (
        ...options: [options?: AlphaOptions],
    ) => Validation<AlphaOptions | undefined>;
    normalizeEmail: (
        ...options: [options?: NormalizeEmailOptions],
    ) => Validation<NormalizeEmailOptions | undefined>;
} = ...

Static collection of all available validation rules for strings

[SUBTYPE]

"[SUBTYPE]": string = 'string'

The subtype identifier for the literal schema field

[UNIQUE_NAME]

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

Unique name identifier for union type resolution

Methods

toJSONSchema

toJSONSchema(): JSONSchema7
Transforms your schema type into JSONSchema7

Returns JSONSchema7
Inherited from BaseLiteralType.toJSONSchema
- Defined in src/schema/base/literal.ts:661

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 it.
Parameters
- callback: ParseFn
Returns this
Inherited from BaseLiteralType.parse
- Defined in src/schema/base/literal.ts:684

use

use(validation: Validation<any> | RuleBuilder): this
Adds a validation rule to the schema's validation chain. Rules are executed in the order they are added.
Parameters
- validation: Validation<any> | RuleBuilder
  The validation rule or rule builder to add
Returns this
This schema instance for method chaining
Example
```
vine.string().use(minLength({ length: 3 }))
vine.number().use(customRule({ strict: true }))
```
Inherited from BaseLiteralType.use
- Defined in src/schema/base/literal.ts:700

bail

bail(state: boolean): VineString
Enable/disable bail mode for this field. In bail mode, field validations stop after the first error.
Parameters
- state: boolean
  Whether to enable bail mode
Returns VineString
This schema instance for method chaining
Example
```
vine.string().bail(false) // Continue validation after first error
vine.number().bail(true)  // Stop after first error (default)
```
Inherited from BaseLiteralType.bail
- Defined in src/schema/base/literal.ts:716

optional

optional(): OptionalModifier<VineString>
Mark the field under validation as optional. An optional field allows both null and undefined values.

Returns OptionalModifier<VineString>
Inherited from BaseLiteralType.optional
- Defined in src/schema/base/literal.ts:725

nullable

nullable(): NullableModifier<VineString>
Mark the field under validation to be null. The null value will be written to the output as well.

If optional and nullable are used together, then both undefined and null values will be allowed.

Returns NullableModifier<VineString>
Inherited from BaseLiteralType.nullable
- Defined in src/schema/base/literal.ts:736

transform

transform<TransformedOutput>(
transformer: Transformer<VineString, TransformedOutput>,
): TransformModifier<VineString, TransformedOutput>
Apply transform on the final validated value. The transform method may convert the value to any new datatype.
Type Parameters
- TransformedOutput
Parameters
- transformer: Transformer<VineString, TransformedOutput>
Returns TransformModifier<VineString, TransformedOutput>
Inherited from BaseLiteralType.transform
- Defined in src/schema/base/literal.ts:752

[PARSE]

"[PARSE]"(
    propertyName: string,
    refs: RefsStore,
    options: ParserOptions,
): FieldNode & {} & { subtype: string }
Compiles the literal schema type into a compiler node. This method transforms the schema definition into a format that the validation compiler can process.
Parameters
- propertyName: string
  Name of the property being compiled
- refs: RefsStore
  Reference store for the compiler
- options: ParserOptions
  Parser options including camelCase conversion
Returns FieldNode & {} & { subtype: string }
Compiled literal node with subtype information
Inherited from BaseLiteralType.[PARSE]
- Defined in src/schema/base/literal.ts:768

[IS_OF_TYPE]

"[IS_OF_TYPE]"(value: unknown): value is string
Type checker function to determine if a value is a string. Required for "unionOfTypes" functionality.
Parameters
- value: unknown
  The value to check
Returns value is string
True if the value is a string
- Defined in src/schema/string/main.ts:138

url

url(...args: [options?: IsURLOptions]): VineString
Validates the value to be a valid URL.
Parameters
- ...args: [options?: IsURLOptions]
  Optional URL validation options
Returns VineString
This string schema instance for method chaining
- Defined in src/schema/string/main.ts:159

activeUrl

activeUrl(): VineString
Validates the value to be an active URL by making an HTTP request.

Returns VineString
This string schema instance for method chaining
- Defined in src/schema/string/main.ts:168

email

email(...args: [options?: IsEmailOptions]): VineString
Validates the value to be a valid email address.
Parameters
- ...args: [options?: IsEmailOptions]
  Optional email validation options
Returns VineString
This string schema instance for method chaining
- Defined in src/schema/string/main.ts:178

mobile

mobile(
    ...args: [
        options?: | MobileOptions
        | ((field: FieldContext) => MobileOptions | undefined),
    ],
): VineString
Validates the value to be a valid mobile phone number for specified locales.
Parameters
- ...args: [options?: MobileOptions | ((field: FieldContext) => MobileOptions | undefined)]
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().mobile({ locale: ['en-US', 'en-GB'] })
```
- Defined in src/schema/string/main.ts:191

vat

vat(
...args: [options: VATOptions | ((field: FieldContext) => VATOptions)],
): VineString
Validates the value to be a valid VAT (Value Added Tax) number for specified countries.
Parameters
- ...args: [options: VATOptions | ((field: FieldContext) => VATOptions)]
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().vat({ countryCode: ['FR', 'CH', 'VE'] })
```
- Defined in src/schema/string/main.ts:204

ipAddress

ipAddress(version?: 4 | 6): VineString
Validates the value to be a valid IP address (IPv4 or IPv6).
Parameters
- Optionalversion: 4 | 6
  Optional IP version (4 for IPv4, 6 for IPv6). Omit to allow both.
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().ipAddress()     // Allows IPv4 and IPv6
vine.string().ipAddress(4)    // Only IPv4
vine.string().ipAddress(6)    // Only IPv6
```
- Defined in src/schema/string/main.ts:219

hexCode

hexCode(): VineString
Validates the value to be a valid hexadecimal color code.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().hexCode()  // Accepts #FFF, #FFFFFF, etc.
```
- Defined in src/schema/string/main.ts:231

regex

regex(expression: RegExp): VineString
Validates the value against a custom regular expression pattern.
Parameters
- expression: RegExp
  The regular expression to match against
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().regex(/^[A-Z]{3}\d{3}$/)  // Matches ABC123 pattern
```
- Defined in src/schema/string/main.ts:244

alpha

alpha(options?: AlphaOptions): VineString
Validates the value to contain only alphabetic characters.
Parameters
- Optionaloptions: AlphaOptions
  Options to allow spaces, underscores, or dashes
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().alpha()
vine.string().alpha({ allowSpaces: true })
vine.string().alpha({ allowSpaces: true, allowDashes: true })
```
- Defined in src/schema/string/main.ts:259

alphaNumeric

alphaNumeric(options?: AlphaOptions): VineString
Validates the value to contain only alphanumeric characters (letters and numbers).
Parameters
- Optionaloptions: AlphaOptions
  Options to allow spaces, underscores, or dashes
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().alphaNumeric()
vine.string().alphaNumeric({ allowSpaces: true, allowUnderscores: true })
```
- Defined in src/schema/string/main.ts:273

minLength

minLength(expectedLength: number): VineString
Enforce a minimum length on a string field.
Parameters
- expectedLength: number
  The minimum required length
Returns VineString
This string schema instance for method chaining
- Defined in src/schema/string/main.ts:283

maxLength

maxLength(expectedLength: number): VineString
Enforce a maximum length on a string field.
Parameters
- expectedLength: number
  The maximum allowed length
Returns VineString
This string schema instance for method chaining
- Defined in src/schema/string/main.ts:293

fixedLength

fixedLength(expectedLength: number): VineString
Enforce a fixed length on a string field.
Parameters
- expectedLength: number
  The exact required length
Returns VineString
This string schema instance for method chaining
- Defined in src/schema/string/main.ts:303

confirmed

confirmed(
options?: { confirmationField?: string } | { as?: string },
): VineString
Ensures the field is confirmed by having another field with "_confirmation" suffix (or a custom suffix). Useful for password confirmation fields.
Parameters
- Optionaloptions: { confirmationField?: string } | { as?: string }
  Optional configuration for the confirmation field name
  - { confirmationField?: string }
    OptionalconfirmationField?: string
    Deprecated
    Use "as" field instead
  - { as?: string }
Returns VineString
This string schema instance for method chaining
Example
```
// Validates that "password_confirmation" field matches "password"
vine.string().confirmed()
```
Example
```
// Custom confirmation field name
vine.string().confirmed({ as: 'passwordConfirm' })
```
- Defined in src/schema/string/main.ts:322

trim

trim(): VineString
Trims leading and trailing whitespace from the string value.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().trim()  // "  hello  " becomes "hello"
```
- Defined in src/schema/string/main.ts:346

normalizeEmail

normalizeEmail(options?: NormalizeEmailOptions): VineString
Normalizes the email address by applying transformations like lowercasing and removing dots from Gmail addresses.
Parameters
- Optionaloptions: NormalizeEmailOptions
  Email normalization options
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().email().normalizeEmail({ gmail_remove_dots: true })
```
- Defined in src/schema/string/main.ts:360

toUpperCase

toUpperCase(): VineString
Converts the field value to UPPERCASE.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().toUpperCase()  // "hello" becomes "HELLO"
```
- Defined in src/schema/string/main.ts:372

toLowerCase

toLowerCase(): VineString
Converts the field value to lowercase.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().toLowerCase()  // "HELLO" becomes "hello"
```
- Defined in src/schema/string/main.ts:384

toCamelCase

toCamelCase(): VineString
Converts the field value to camelCase.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().toCamelCase()  // "hello_world" becomes "helloWorld"
```
- Defined in src/schema/string/main.ts:396

escape

escape(): VineString
Escapes HTML entities in the string to prevent XSS attacks.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().escape()  // "<script>" becomes "&lt;script&gt;"
```
- Defined in src/schema/string/main.ts:408

normalizeUrl

normalizeUrl(...args: [options?: Options]): VineString
Normalizes a URL by applying standardization rules like removing trailing slashes, sorting query parameters, and stripping default ports.
Parameters
- ...args: [options?: Options]
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().url().normalizeUrl({ stripWWW: true })
```
- Defined in src/schema/string/main.ts:422

startsWith

startsWith(substring: string): VineString
Ensures the value starts with a specified substring.
Parameters
- substring: string
  The required starting substring
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().startsWith('https://')
```
- Defined in src/schema/string/main.ts:435

endsWith

endsWith(substring: string): VineString
Ensures the value ends with a specified substring.
Parameters
- substring: string
  The required ending substring
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().endsWith('.com')
```
- Defined in src/schema/string/main.ts:448

sameAs

sameAs(otherField: string): VineString
Ensures the value matches the value of another field in the data.
Parameters
- otherField: string
  The name of the field to compare with
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().sameAs('password')
```
- Defined in src/schema/string/main.ts:461

notSameAs

notSameAs(otherField: string): VineString
Ensures the value does not match the value of another field in the data.
Parameters
- otherField: string
  The name of the field to compare with
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().notSameAs('oldPassword')
```
- Defined in src/schema/string/main.ts:474

in

in(choices: string[] | ((field: FieldContext) => string[])): VineString
Ensures the field's value is one of the predefined choices.
Parameters
- choices: string[] | ((field: FieldContext) => string[])
  Array of allowed values or function returning allowed values
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().in(['red', 'green', 'blue'])
```
Example
```
// Dynamic choices based on metadata
vine.string().in((field) => getUserRoles(field.meta.userId))
```
- Defined in src/schema/string/main.ts:491

notIn

notIn(list: string[] | ((field: FieldContext) => string[])): VineString
Ensures the field's value is not in the predefined list.
Parameters
- list: string[] | ((field: FieldContext) => string[])
  Array of disallowed values or function returning disallowed values
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().notIn(['admin', 'root', 'system'])
```
- Defined in src/schema/string/main.ts:504

creditCard

creditCard(
    ...args: [
        options?: | CreditCardOptions
        | ((field: FieldContext) => void | CreditCardOptions | undefined),
    ],
): VineString
Validates the value to be a valid credit card number for specified providers.
Parameters
- ...args: [
  options?: | CreditCardOptions
  | ((field: FieldContext) => void | CreditCardOptions | undefined),
  ]
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().creditCard({ provider: ['visa', 'mastercard'] })
```
- Defined in src/schema/string/main.ts:517

passport

passport(
    ...args: [
        options: PassportOptions
        | ((field: FieldContext) => PassportOptions),
    ],
): VineString
Validates the value to be a valid passport number for specified countries.
Parameters
- ...args: [options: PassportOptions | ((field: FieldContext) => PassportOptions)]
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().passport({ countryCode: ['US', 'GB', 'CA'] })
```
- Defined in src/schema/string/main.ts:530

postalCode

postalCode(
    ...args: [
        options?: | PostalCodeOptions
        | ((field: FieldContext) => void | PostalCodeOptions | undefined),
    ],
): VineString
Validates the value to be a valid postal code for specified countries.
Parameters
- ...args: [
  options?: | PostalCodeOptions
  | ((field: FieldContext) => void | PostalCodeOptions | undefined),
  ]
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().postalCode({ countryCode: ['US', 'GB', 'CA'] })
```
- Defined in src/schema/string/main.ts:543

uuid

uuid(
...args: [options?: { version?: (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8)[] }],
): VineString
Validates the value to be a valid UUID (Universally Unique Identifier).
Parameters
- ...args: [options?: { version?: (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8)[] }]
Returns VineString
This string schema instance for method chaining
Example
```
vine.string().uuid()
vine.string().uuid({ version: 4 })
```
- Defined in src/schema/string/main.ts:557

ulid

ulid(): VineString
Validates the value to be a valid ULID (Universally Unique Lexicographically Sortable Identifier).

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().ulid()
```
- Defined in src/schema/string/main.ts:569

ascii

ascii(): VineString
Validates the value contains only ASCII characters.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().ascii()
```
- Defined in src/schema/string/main.ts:581

iban

iban(): VineString
Validates the value to be a valid IBAN (International Bank Account Number).

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().iban()
```
- Defined in src/schema/string/main.ts:593

jwt

jwt(): VineString
Validates the value to be a valid JWT (JSON Web Token).

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().jwt()
```
- Defined in src/schema/string/main.ts:605

coordinates

coordinates(): VineString
Validates the value to be a string containing latitude and longitude coordinates.

Returns VineString
This string schema instance for method chaining
Example
```
vine.string().coordinates()  // Accepts "40.7128,-74.0060"
```
- Defined in src/schema/string/main.ts:617

clone

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

Returns this
A cloned instance of this VineString schema
Overrides BaseLiteralType.clone
- Defined in src/schema/string/main.ts:627

Class VineString

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns VineString

Properties

[ITYPE]

[OTYPE]

[COTYPE]

OptionaldataTypeValidator

Example

options

Staticrules

[SUBTYPE]

[UNIQUE_NAME]

Methods

toJSONSchema

Returns JSONSchema7

parse

Parameters

Returns this

use

Parameters

Returns this

Example

bail

Parameters

Returns VineString

Example

optional

Returns OptionalModifier<VineString>

nullable

Returns NullableModifier<VineString>

meta

Parameters

Returns MetaModifier<VineString>

transform

Type Parameters

Parameters

Returns TransformModifier<VineString, TransformedOutput>

[PARSE]

Parameters

Returns FieldNode & {} & { subtype: string }

[IS_OF_TYPE]

Parameters

Returns value is string

url

Parameters

Returns VineString

activeUrl

Returns VineString

email

Parameters

Returns VineString

mobile

Parameters

Returns VineString

Example

vat

Parameters

Returns VineString

Example

ipAddress

Parameters

Returns VineString

Example

hexCode

Returns VineString

Example

regex

Parameters

Returns VineString

Example

alpha

`Optional`dataTypeValidator

`Static`rules

`Optional`confirmationField?: string