API Reference

Below is a list of all the API functions exposed by Vest.

Vest's main export API

create(callback, schema?)

Creates a new validation suite. Returns a Suite Object.

• Read more about create

• Read more about Schema Validation

• callback: The validation logic.

• schema (Optional): An enforce schema definition.

Suite Object Methods

suite.run(...args)

Runs the suite. Passes arguments to the suite callback.

• Returns: A SuiteResult object.
  • If the suite contains async tests, the result object also implements the Promise interface, allowing you to await it.
  • You can always access synchronous result data immediately (e.g., result.hasErrors()), even if the promise is pending.
• Read more about suite.run

suite.runStatic(...args)

Runs the suite in stateless mode. Useful for server-side validation.

• Read more about Server Side Validation

suite.reset()

Resets the suite state (clears all results).

• Read more about suite.reset

suite.remove(fieldName)

Removes a specific field from the suite result state.

• Read more about suite.remove

suite.resetField(fieldName)

Resets the state of a specific field (clears errors/warnings but keeps it in the result).

• Read more about suite.resetField

suite.focus(config)

Prepares a focused run.

• config: { only?: string | string[], skip?: string | string[] }
• Read more about Focused Updates

suite.afterEach(callback)

Registers a callback to run after each test completes (including the initial sync run and every async completion).

• Read more about suite.afterEach

suite.afterField(fieldName, callback)

Registers a callback to run when a specific field finishes execution.

• Read more about suite.afterField

suite.get()

Returns the current result object of the suite without running it. Useful for accessing the state inside UI components or subscribers.

• Read more about suite.get

SuiteSerializer.serialize(suite)

Returns a minified, serialized representation of the suite's state. Useful for SSR hydration.

• Read more about SSR Hydration

SuiteSerializer.resume(suite, data)

Hydrates the suite with a serialized state.

• suite: The suite to resume.
• data: The serialized state object.
• Read more about SSR Hydration

suite.validate(data)

Runs the suite and returns a result compatible with the Standard Schema specification.

• Read more about Standard Schema Support

Top-Level Exports

enforce.context()

Retrieves the current validation context during a suite run. Useful within custom rules to access other fields in the data object.

• Returns: { data: Object, value: any, ... }
• Read more about Context Aware Rules

enforce.extend(customRules)

Extends Vest's enforce with custom validation rules.

• Tip: To add TypeScript support for your custom rules, see TypeScript Support.

memo(callback, deps)

Memoizes a block of tests.

• Read more about memo

compose(...rules)

Combines multiple enforce rules.

• Read more about compose

test(fieldName, message, callback)

A single validation test inside your suite.

• Read more about test

enforce(value)

Asserts that a value matches your desired result.

• Read more about enforce

warn()

Sets the test's severity to warning.

• Read more about warn

only(fieldName)

Makes Vest only run the provided field names.

• Read more about only

skip(fieldName)

Makes Vest skip the provided field names.

• Read more about skip

include(fieldName).when(condition)

Link fields by running them together based on a criteria.

• Read more about include

skipWhen(condition, callback)

Skips a portion of the suite when the provided condition is met.

• Read more about skipWhen

omitWhen(condition, callback)

Omits a portion of the suite when the provided condition is met.

• Read more about omitWhen

optional(fieldName)

Allows you to mark a field as optional.

• Read more about optional

group(groupName, callback)

Allows grouping multiple tests with a given name.

• Read more about group

each(list, callback)

Allows iteration over an array of values to dynamically run tests.

• Read more about each

mode(mode)

Determines whether Vest should continue running tests after a field has failed.

• Read more about mode

Suite Result API

After running your suite, the results object is returned. It has the following functions:

• Read more about the Result Object

• hasErrors(fieldName?): Returns true if the suite or the provided field has errors.

• hasWarnings(fieldName?): Returns true if the suite or the provided field has warnings.

• getErrors(fieldName?): Returns an object with errors in the suite, or an array of objects for a specific field.

• getWarnings(fieldName?): Returns an object with warnings in the suite, or an array of objects for a specific field.

• hasErrorsByGroup(groupName): Returns true if the provided group has errors.

• hasWarningByGroup(groupName): Returns true if the provided group has warnings.

• getErrorsByGroup(groupName): Returns an object with errors in the provided group.

• getWarningsByGroup(groupName): Returns an object with warnings in the provided group.

• isPending(fieldName?): Returns true if the suite has pending async tests.

• isTested(fieldName): Returns true if the provided field has been tested.

• isValid(fieldName?): Returns true if the suite or the provided field is valid.

• isValidByGroup(groupName): Returns true if a certain group or a field in a group is valid or not.