Documentation / zerotal / validator / StringRule

Class: StringRule

Defined in: packages/validator/src/FieldRule.ts:228

Extends

FieldRule

Constructors

Constructor

new StringRule(): StringRule

Returns

StringRule

Inherited from

FieldRule.constructor

Properties

_def

readonly _def: StringDef

Defined in: packages/validator/src/FieldRule.ts:229

Overrides

FieldRule._def

Methods

required()

required(message?): this

Defined in: packages/validator/src/FieldRule.ts:36

Mark this field as required (the default). Useful for readability, for re-asserting after .optional(), or to attach a custom "is required" message:

rule.string().required("Please enter your name").min(2)

Parameters

message?

string

Returns

this

Inherited from

FieldRule.required

optional()

optional(): this

Defined in: packages/validator/src/FieldRule.ts:42

Returns

this

Inherited from

FieldRule.optional

nullable()

nullable(): this

Defined in: packages/validator/src/FieldRule.ts:47

Returns

this

Inherited from

FieldRule.nullable

default()

default(value): this

Defined in: packages/validator/src/FieldRule.ts:52

Parameters

value

unknown

Returns

this

Inherited from

FieldRule.default

sometimes()

sometimes(): this

Defined in: packages/validator/src/FieldRule.ts:66

Only run this field's rules if the field is present in the input. Absent fields are silently skipped and excluded from the output. Use for optional PATCH fields that should only be validated when provided.

Returns

this

Example

bio: rules.string().sometimes().max(500)

Inherited from

FieldRule.sometimes

requiredIf()

requiredIf(fieldOrFn, value?): this

Defined in: packages/validator/src/FieldRule.ts:79

Make this field required only when another field equals a specific value.

Parameters

fieldOrFn

string | ((input) => boolean)

value?

unknown

Returns

this

Example

address: rules.string().requiredIf('hasShipping', true)
address: rules.string().requiredIf(input => input.method === 'pickup')

Inherited from

FieldRule.requiredIf

requiredUnless()

requiredUnless(fieldOrFn, value?): this

Defined in: packages/validator/src/FieldRule.ts:98

Make this field required unless another field equals a specific value.

Parameters

fieldOrFn

string | ((input) => boolean)

value?

unknown

Returns

this

Example

phone: rules.string().requiredUnless('contactMethod', 'email')

Inherited from

FieldRule.requiredUnless

accepted()

accepted(message?): this

Defined in: packages/validator/src/FieldRule.ts:118

The value must be truthy: true, 1, '1', 'yes', 'on', 'true'. Use for "agree to terms" checkboxes.

Parameters

message?

string

Returns

this

Example

terms: rules.boolean().accepted()

Inherited from

FieldRule.accepted

declined()

declined(message?): this

Defined in: packages/validator/src/FieldRule.ts:129

The value must be falsy: false, 0, '0', 'no', 'off', 'false'.

Parameters

message?

string

Returns

this

Example

newsletter: rules.boolean().declined()

Inherited from

FieldRule.declined

custom()

custom(fn, message?): this

Defined in: packages/validator/src/FieldRule.ts:144

Run a custom synchronous or asynchronous validation function. Return true to pass, false for a generic error, or a string as the error message.

Parameters

fn

CustomFn

message?

string

Returns

this

Example

username: rules.string().custom(async (value) => {
  const taken = await Username.isTaken(value as string);
  return taken ? 'This username is already taken.' : true;
})

Inherited from

FieldRule.custom

requiredWith()

requiredWith(fields): this

Defined in: packages/validator/src/FieldRule.ts:157

This field is required when ANY of the listed fields are present in input.

Parameters

fields

string[]

Returns

this

Example

cardCvv: rules.string().requiredWith(['cardNumber', 'cardExpiry'])

Inherited from

FieldRule.requiredWith

requiredWithout()

requiredWithout(fields): this

Defined in: packages/validator/src/FieldRule.ts:169

This field is required when ANY of the listed fields are absent from input.

Parameters

fields

string[]

Returns

this

Example

email: rules.string().requiredWithout(['phone'])

Inherited from

FieldRule.requiredWithout

requiredWithAll()

requiredWithAll(fields): this

Defined in: packages/validator/src/FieldRule.ts:178

This field is required when ALL of the listed fields are present.

Parameters

fields

string[]

Returns

this

Inherited from

FieldRule.requiredWithAll

requiredWithoutAll()

requiredWithoutAll(fields): this

Defined in: packages/validator/src/FieldRule.ts:187

This field is required when ALL of the listed fields are absent.

Parameters

fields

string[]

Returns

this

Inherited from

FieldRule.requiredWithoutAll

prohibitedIf()

prohibitedIf(field, value): this

Defined in: packages/validator/src/FieldRule.ts:199

This field must be absent when another field equals the given value.

Parameters

field

string

value

unknown

Returns

this

Example

adminCode: rules.string().prohibitedIf('role', 'guest')

Inherited from

FieldRule.prohibitedIf

prohibitedUnless()

prohibitedUnless(field, value): this

Defined in: packages/validator/src/FieldRule.ts:210

This field must be absent unless another field equals the given value.

Parameters

field

string

value

unknown

Returns

this

Example

discount: rules.number().prohibitedUnless('role', 'admin')

Inherited from

FieldRule.prohibitedUnless

bail()

bail(): this

Defined in: packages/validator/src/FieldRule.ts:222

Stop validating this field after the first failing rule. Without bail(), all rules are checked and all errors collected.

Returns

this

Example

email: rules.string().email().unique('users', 'email').bail()

Inherited from

FieldRule.bail

min()

min(length, message?): this

Defined in: packages/validator/src/FieldRule.ts:237

Parameters

length

number

message?

string

Returns

this

max()

max(length, message?): this

Defined in: packages/validator/src/FieldRule.ts:242

Parameters

length

number

message?

string

Returns

this

email()

email(message?): this

Defined in: packages/validator/src/FieldRule.ts:247

Parameters

message?

string

Returns

this

url()

url(message?): this

Defined in: packages/validator/src/FieldRule.ts:252

Parameters

message?

string

Returns

this

regex()

regex(pattern, message?): this

Defined in: packages/validator/src/FieldRule.ts:257

Parameters

pattern

RegExp

message?

string

Returns

this

uuid()

uuid(message?): this

Defined in: packages/validator/src/FieldRule.ts:262

Parameters

message?

string

Returns

this

trim()

trim(): this

Defined in: packages/validator/src/FieldRule.ts:269

Returns

this

lowercase()

lowercase(): this

Defined in: packages/validator/src/FieldRule.ts:274

Returns

this

uppercase()

uppercase(): this

Defined in: packages/validator/src/FieldRule.ts:279

Returns

this

in()

in(values, message?): this

Defined in: packages/validator/src/FieldRule.ts:284

Parameters

values

string[]

message?

string

Returns

this

confirmed()

confirmed(message?): this

Defined in: packages/validator/src/FieldRule.ts:289

Parameters

message?

string

Returns

this

notIn()

notIn(values, message?): this

Defined in: packages/validator/src/FieldRule.ts:295

Value must NOT be in the given list.

Parameters

values

string[]

message?

string

Returns

this

sameAs()

sameAs(field, message?): this

Defined in: packages/validator/src/FieldRule.ts:301

Value must equal another field in the input (e.g. password confirmation).

Parameters

field

string

message?

string

Returns

this

alpha()

alpha(message?): this

Defined in: packages/validator/src/FieldRule.ts:307

Only letters (a–z, A–Z).

Parameters

message?

string

Returns

this

alphaNum()

alphaNum(message?): this

Defined in: packages/validator/src/FieldRule.ts:313

Letters and digits only.

Parameters

message?

string

Returns

this

alphaDash()

alphaDash(message?): this

Defined in: packages/validator/src/FieldRule.ts:319

Letters, digits, hyphens, and underscores.

Parameters

message?

string

Returns

this

startsWith()

startsWith(prefix, message?): this

Defined in: packages/validator/src/FieldRule.ts:325

String must start with the given prefix.

Parameters

prefix

string

message?

string

Returns

this

endsWith()

endsWith(suffix, message?): this

Defined in: packages/validator/src/FieldRule.ts:331

String must end with the given suffix.

Parameters

suffix

string

message?

string

Returns

this

size()

size(n, message?): this

Defined in: packages/validator/src/FieldRule.ts:337

Exact character count.

Parameters

n

number

message?

string

Returns

this

unique()

unique(table, column, ignoreOrOpts?, message?): this

Defined in: packages/validator/src/FieldRule.ts:354

Assert the value does not already exist in table.column. Requires DatabaseProvider to be registered.

Pass the current record's ID as the third argument to ignore it on update (accepts a plain ID or a full UniqueOptions object for advanced cases).

Parameters

table

string

column

string

ignoreOrOpts?

string | number | UniqueOptions

message?

string

Returns

this

Example

email: rules.string().email().unique('users', 'email')
email: rules.string().email().unique('users', 'email', user.id)   // ignore on update
email: rules.string().email().unique('users', 'email', { ignoreId: user.id })

exists()

exists(table, column, message?): this

Defined in: packages/validator/src/FieldRule.ts:377

Assert the value already exists in table.column. Requires DatabaseProvider to be registered.

Parameters

table

string

column

string

message?

string

Returns

this

Example

role: rules.string().exists('roles', 'name')

matches()

matches(pattern, message?): this

Defined in: packages/validator/src/FieldRule.ts:390

Alias for regex() — matches the given pattern.

Parameters

pattern

RegExp

message?

string

Returns

this

Example

rules.string().matches(/^[A-Z]{2}\d{4}$/, 'Invalid format')

password()

password(): this

Defined in: packages/validator/src/FieldRule.ts:403

Mark this field as a password. A semantic signal — use it as the starting point then chain your specific constraints (min, max, matches, etc.).

Returns

this

Example

password: rules.string().password().min(8).max(128)
  .matches(/^(?=.*[A-Z])(?=.*\d).+$/, 'Must contain uppercase and digit')

ip()

ip(message?): this

Defined in: packages/validator/src/FieldRule.ts:408

Must be a valid IPv4 or IPv6 address.

Parameters

message?

string

Returns

this

json()

json(message?): this

Defined in: packages/validator/src/FieldRule.ts:414

Must be a valid JSON string (parseable).

Parameters

message?

string

Returns

this

digits()

digits(n, message?): this

Defined in: packages/validator/src/FieldRule.ts:420

Must consist of exactly n digits.

Parameters

n

number

message?

string

Returns

this

digitsBetween()

digitsBetween(min, max, message?): this

Defined in: packages/validator/src/FieldRule.ts:426

Digit count must be between min and max (inclusive).

Parameters

min

number

max

number

message?

string

Returns

this

numeric()

numeric(message?): this

Defined in: packages/validator/src/FieldRule.ts:432

Must be numeric (digits only, optional leading minus).

Parameters

message?

string

Returns

this

prohibited()

prohibited(message?): this

Defined in: packages/validator/src/FieldRule.ts:438

Field must be absent from the input (the key must not be present).

Parameters

message?

string

Returns

this

present()

present(message?): this

Defined in: packages/validator/src/FieldRule.ts:444

Field must be present in the input (but may be empty).

Parameters

message?

string

Returns

this