Skip to main content

Object Mutators

Object mutators transform objects before validation. They handle unknown properties, trim values, and manage object structure.

All Mutators​

stripUnknown()
allow()
trim()
allowUnknown()

Property Management​

stripUnknown()​

Remove properties that are not defined in the schema

v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .stripUnknown()

// Input: { name: "John", email: "john@example.com", extra: "value" }
// Output: { name: "John", email: "john@example.com" }

Note: This mutator removes unknown properties but doesn't validate them. Use with allowUnknown() to control behavior.

allow(...keys)​

Allow specific properties that are not defined in the schema

v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .allow("extraField", "anotherField")

// Input: { name: "John", email: "john@example.com", extraField: "value", unknown: "removed" }
// Output: { name: "John", email: "john@example.com", extraField: "value" }

Parameters:

  • ...keys: Variable number of property names to allow

Data Cleaning​

trim(recursive?)​

Trim whitespace from all string values in the object

v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .trim()

// Input: { name: "  John  ", email: "  john@example.com  " }
// Output: { name: "John", email: "john@example.com" }

Parameters:

  • recursive (optional): Whether to trim nested objects (default: true)

Recursive trimming:

v.object({
  name: v.string().required(),
  address: v.object({
    street: v.string().required(),
    city: v.string().required()
  })
})
  .trim()

// Input: { name: "  John  ", address: { street: "  123 Main St  ", city: "  New York  " } }
// Output: { name: "John", address: { street: "123 Main St", city: "New York" } }

Unknown Handling​

allowUnknown(allow?)​

Control whether unknown properties are allowed

v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .allowUnknown(true)

// Input: { name: "John", email: "john@example.com", extra: "value" }
// Output: { name: "John", email: "john@example.com", extra: "value" }

Parameters:

  • allow (optional): Whether to allow unknown properties (default: true)

Default behavior:

  • allowUnknown() - Allow unknown properties
  • allowUnknown(false) - Reject unknown properties
  • allowUnknown(true) - Allow unknown properties

Examples​

Strip Unknown Properties​

const schema = v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .stripUnknown();

const result = await validate(schema, {
  name: "John Doe",
  email: "john@example.com",
  extraField: "This will be removed",
  anotherExtra: "This too"
});
// Result: { isValid: true, data: { name: "John Doe", email: "john@example.com" } }

Allow Specific Extra Fields​

const schema = v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .allow("extraField", "anotherField");

const result = await validate(schema, {
  name: "John Doe",
  email: "john@example.com",
  extraField: "This will be kept",
  anotherField: "This too",
  unknownField: "This will be removed"
});
// Result: { isValid: true, data: { name: "John Doe", email: "john@example.com", extraField: "This will be kept", anotherField: "This too" } }

Trim String Values​

const schema = v.object({
  name: v.string().required(),
  email: v.string().email().required(),
  address: v.object({
    street: v.string().required(),
    city: v.string().required()
  })
})
  .trim();

const result = await validate(schema, {
  name: "  John Doe  ",
  email: "  john@example.com  ",
  address: {
    street: "  123 Main St  ",
    city: "  New York  "
  }
});
// Result: { isValid: true, data: { name: "John Doe", email: "john@example.com", address: { street: "123 Main St", city: "New York" } } }

Allow Unknown Properties​

const schema = v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .allowUnknown();

const result = await validate(schema, {
  name: "John Doe",
  email: "john@example.com",
  extraField: "This will be kept",
  anotherExtra: "This too"
});
// Result: { isValid: true, data: { name: "John Doe", email: "john@example.com", extraField: "This will be kept", anotherExtra: "This too" } }

Mutator Chain​

const schema = v.object({
  name: v.string().required(),
  email: v.string().email().required()
})
  .trim()                    // Trim string values
  .stripUnknown()            // Remove unknown properties
  .allow("extraField");      // But allow specific extra fields

const result = await validate(schema, {
  name: "  John Doe  ",
  email: "  john@example.com  ",
  extraField: "  This will be kept and trimmed  ",
  unknownField: "This will be removed"
});
// Result: { isValid: true, data: { name: "John Doe", email: "john@example.com", extraField: "This will be kept and trimmed" } }

Important Notes​

Mutators Run Before Validation​

v.object({...})
  .trim()            // Mutator: Trim values
  .stripUnknown()    // Mutator: Remove unknown properties
  .required()        // Validator: Check object is present

Unknown Property Behavior​

MethodBehavior
stripUnknown()Remove unknown properties
allowUnknown()Keep unknown properties
allow("field")Allow specific extra fields

Recursive Trimming​

v.object({...}).trim()           // Trim all strings recursively
v.object({...}).trim(false)      // Only trim top-level strings

See Also​