Skip to main content

Scalar Validators

Scalar validators check value membership, acceptance, and conditional validation for scalar values.

All Validators​

enum()
in()
oneOf()
allowsOnly()
forbids()
notIn()
accepted()
acceptedIf()
acceptedUnless()
acceptedIfRequired()
acceptedIfPresent()
acceptedWithout()
declined()
declinedIf()
declinedUnless()
declinedIfRequired()
declinedIfPresent()
declinedWithout()

Value Selection​

enum(enumObject)​

Value must be one of the given enum values. Accepts a TypeScript enum object.

enum Status {
  Active = "active",
  Inactive = "inactive",
  Pending = "pending"
}

v.scalar().enum(Status)
// Input: "active" → Valid ✅
// Input: "unknown" → Invalid ❌

in(values)​

Value must be in the given array

v.scalar().in(["admin", "user", "guest"])
// Input: "admin" → Valid ✅
// Input: "unknown" → Invalid ❌

oneOf(values)​

Alias for in(). Value must be one of the given values

v.scalar().oneOf(["option1", "option2", "option3"])
// Input: "option1" → Valid ✅
// Input: "option4" → Invalid ❌

allowsOnly(values)​

Value must be one of the allowed values

v.scalar().allowsOnly(["value1", "value2", "value3"])
// Input: "value1" → Valid ✅
// Input: "value4" → Invalid ❌

forbids(values)​

Value must not be one of the forbidden values

v.scalar().forbids(["spam", "test", "admin"])
// Input: "user" → Valid ✅
// Input: "spam" → Invalid ❌

notIn(values)​

Alias for forbids(). Value must not be in the given array

v.scalar().notIn(["spam", "test"])
// Input: "user" → Valid ✅
// Input: "spam" → Invalid ❌

Accepted Values​

accepted()​

Value must be accepted (1, "1", true, "true", "yes", "y", "on")

v.scalar().accepted()
// Input: true, "yes", "1", "on" → Valid ✅
// Input: false, "no", "0" → Invalid ❌

acceptedIf(field, value)​

Accepted if another field equals a specific value

v.scalar().acceptedIf("subscribe", true)
// If subscribe === true: accepts "yes" → Valid ✅
// If subscribe === false: any value → Valid ✅

acceptedUnless(field, value)​

Accepted unless another field equals a specific value

v.scalar().acceptedUnless("premium", true)
// If premium !== true: accepts "yes" → Valid ✅
// If premium === true: any value → Valid ✅

acceptedIfRequired(field)​

Accepted if another field is required

v.scalar().acceptedIfRequired("newsletter")
// If newsletter is required: accepts "yes" → Valid ✅
// If newsletter is optional: any value → Valid ✅

acceptedIfPresent(field)​

Accepted if another field is present

v.scalar().acceptedIfPresent("newsletter")
// If newsletter exists: accepts "yes" → Valid ✅
// If newsletter missing: any value → Valid ✅

acceptedWithout(field)​

Accepted if another field is missing

v.scalar().acceptedWithout("newsletter")
// If newsletter missing: accepts "yes" → Valid ✅
// If newsletter exists: any value → Valid ✅

Declined Values​

declined()​

Value must be declined (0, "0", false, "false", "no", "n", "off")

v.scalar().declined()
// Input: false, "no", "0", "off" → Valid ✅
// Input: true, "yes", "1" → Invalid ❌

declinedIf(field, value)​

Declined if another field equals a specific value

v.scalar().declinedIf("subscribe", false)
// If subscribe === false: declines "yes" → Valid ✅
// If subscribe === true: any value → Valid ✅

declinedUnless(field, value)​

Declined unless another field equals a specific value

v.scalar().declinedUnless("premium", false)
// If premium !== false: declines "yes" → Valid ✅
// If premium === false: any value → Valid ✅

declinedIfRequired(field)​

Declined if another field is required

v.scalar().declinedIfRequired("newsletter")
// If newsletter is required: declines "yes" → Valid ✅
// If newsletter is optional: any value → Valid ✅

declinedIfPresent(field)​

Declined if another field is present

v.scalar().declinedIfPresent("newsletter")
// If newsletter exists: declines "yes" → Valid ✅
// If newsletter missing: any value → Valid ✅

declinedWithout(field)​

Declined if another field is missing

v.scalar().declinedWithout("newsletter")
// If newsletter missing: declines "yes" → Valid ✅
// If newsletter exists: any value → Valid ✅

Examples​

Status Selection​

enum Status {
  Active = "active",
  Inactive = "inactive",
  Pending = "pending"
}

const statusSchema = v.scalar()
  .required()
  .enum(Status);

const result = await validate(statusSchema, "active");
// Result: { isValid: true, data: "active" }

Role Validation​

const roleSchema = v.scalar()
  .required()
  .in(["admin", "user", "guest"]);

const result = await validate(roleSchema, "admin");
// Result: { isValid: true, data: "admin" }

Terms Acceptance​

const termsSchema = v.scalar()
  .required()
  .accepted();

const result = await validate(termsSchema, "yes");
// Result: { isValid: true, data: "yes" }

Conditional Newsletter​

const newsletterSchema = v.scalar()
  .acceptedIf("subscribe", true);

const result = await validate(newsletterSchema, "yes", {
  subscribe: true
});
// Result: { isValid: true, data: "yes" }

Forbidden Values​

const usernameSchema = v.scalar()
  .required()
  .forbids(["admin", "root", "system"]);

const result = await validate(usernameSchema, "john");
// Result: { isValid: true, data: "john" }

See Also​