Skip to main content
Version: 6.x

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.

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.
    • If another suite.run() of the same suite starts while an earlier run is pending, awaiting the earlier result resolves with the newer run's result instead of waiting on work the newer run replaced. runStatic() runs are independent of each other.
  • Read more about suite.run

suite.runStatic(...args)​

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

suite.reset()​

Resets the suite state (clears all results).

suite.remove(fieldName)​

Removes a specific field from the suite result state.

suite.resetField(fieldName)​

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

suite.focus(config)​

Prepares a focused run with combined modifiers. Use this when you need to combine only, skip, skipGroup, or onlyGroup in a single call.

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

suite.only(fieldName)​

Shorthand for suite.focus({ only: fieldName }). Restricts the next run to the specified field(s).

suite.afterEach(callback)​

Registers a callback to run after each test completes (including the initial sync run and every async completion). The callback receives no arguments; you should access the result using suite.get().

suite.afterField(fieldName, callback)​

Registers a callback to run when a specific field finishes execution. The callback receives no arguments; you should access the result using suite.get().

suite.get()​

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

SuiteSerializer.serialize(result)​

Returns a minified, serialized representation of a validation result. Useful for SSR hydration.

SuiteSerializer.resume(suite, data)​

Hydrates the suite with a serialized state.

suite['~standard'].validate(data)​

Implements the Standard Schema interoperability contract. Compatible consumers invoke this hook automatically. For application code, use the primary suite.run(data) stateful API or suite.runStatic(data) stateless API.

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.

enforce.extend(customRules)​

Extends Vest's enforce with custom validation rules.

memo(callback, deps, options?)​

Memoizes a block of tests.

  • callback: The function to execute if dependencies change.

  • deps: Array of dependencies determining if the callback executes.

  • options (Optional): Configuration object with cacheSize (max cached results) and ttl (Time-to-Live in ms).

  • Read more about memo

compose(...rules)​

Combines multiple enforce rules.

test(fieldName, message, callback)​

A single validation test inside your suite.

enforce(value)​

Asserts that a value matches your desired result.

warn()​

Sets the test's severity to warning in the synchronous part of a test.

useWarn()​

Returns a setter function that marks the current test as warning severity, including async flows after an await.

only(fieldName)​

Makes Vest only run the provided field names.

skip(fieldName)​

Makes Vest skip the provided field names.

include(fieldName).when(condition)​

Link fields by running them together based on a criteria.

skipWhen(condition, callback)​

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

omitWhen(condition, callback)​

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

optional(fieldName)​

Allows you to mark a field as optional.

group(groupName, callback)​

Allows grouping multiple tests with a given name.

each(list, callback)​

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

mode(mode)​

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

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.

  • getError(fieldName?): Without a field, returns the first summary object ({ fieldName, message, groupName }). With a field, returns that field's first error message string. Returns undefined when none exists.

  • getWarning(fieldName?): Without a field, returns the first summary object. With a field, returns that field's first warning message string. Returns undefined when none exists.

  • getMessage(fieldName): Returns the field's first error or warning message string, preferring an error when both exist.

  • getErrors(fieldName?): Without a field, returns an object whose keys are field names and values are arrays of message strings. With a field, returns that field's array of error message strings.

  • getWarnings(fieldName?): Without a field, returns an object whose keys are field names and values are arrays of message strings. With a field, returns that field's array of warning message strings.

  • 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.

  • value: The parsed schema output when the suite is valid. Typed as the schema's output type. undefined when invalid or when no schema is used.

  • types: When a schema is present, an object with input and output properties typed from the schema. undefined when no schema is used.

  • run: Metadata about the latest run, including run.data.raw (current run data), run.data.parsed (parsed data for the current run), and run.time (timestamp).