Vest Documentation

Vest can be used alongside schema validators to combine structural parsing with stateful validation workflows.

• Schema Validators (Zod, Enforce, Valibot): Best for one-shot structural validation, data transformation, and parsing unknown input at boundaries.
• Vest Suites: Best for managing validation over time, handling async checks, coordinating dependent fields, and providing progressive UX (warnings, pending states).

You can attach a schema to a Vest suite so that the parsed, transformed values are used during the suite's execution.

const accountSchema = enforce.shape({
  age: enforce.isNumeric().toNumber(),
  email: enforce.isString().trim(),
});

// Attach the schema to the suite to use parsed values
const accountSuite = create(parsedAccount => {
  test('age', 'Must be an adult', () => {
    enforce(parsedAccount.age).greaterThanOrEquals(18);
  });
}, accountSchema);

// Run the suite with input
const result = accountSuite.runStatic(input);
if (result.isValid()) persist(result.value);

To handle multi-step forms (wizards), model each step as a Vest group. This allows you to validate the current step independently while maintaining the state of previously completed steps.

When a user attempts to move to the next step, use .focus({ onlyGroup: stepName }) to run validation only for that specific group. This ensures that errors in future steps do not block progress in the current step.

Key considerations:

• Step Navigation: Use result.isValidByGroup(stepName) to determine if a user can proceed.
• Final Submission: Always run the full suite using .run(data) at the end of the workflow to ensure the entire form is valid.
• Top-level tests: The onlyGroup option excludes ungrouped top-level tests. Ensure all step-specific requirements are contained within their respective groups.

import { create, enforce, group, test } from 'vest';

type Step = 'account' | 'profile' | 'billing';

type OnboardingData = {
  displayName: string;
  email: string;
  plan: string;
};

// 1. Define the suite with groups representing steps
export const onboardingSuite = create<{ 
  fields: keyof OnboardingData; 
  groups: Step; 
}>((data: OnboardingData) => {
  group('account', () => {
    test('email', 'Email is required', () => {
      enforce(data.email).isNotBlank();
    });
  });

  group('profile', () => {
    test('displayName', 'Display name is required', () => {
      enforce(data.displayName).isNotBlank();
    });
  });

  group('billing', () => {
    test('plan', 'Choose a plan', () => {
      enforce(data.plan).isNotBlank();
    });
  });
});

// 2. Validate only the current step for navigation
async function canContinue(step: Step, data: OnboardingData) {
  const result = await onboardingSuite.focus({ onlyGroup: step }).run(data);
  return result.isValidByGroup(step);
}

// 3. Validate the entire suite for final submission
async function submitForm(data: OnboardingData) {
  const result = await onboardingSuite.run(data);

  if (!result.isValid()) {
    // Handle errors (e.g., navigate to first invalid step)
    return;
  }
  // Proceed with submission
}

If you are migrating a large codebase, you can use the following prompt with an LLM to automate the refactoring of Vest 5 suites to Vest 6:

I am migrating my Vest validation suites from version 5 to version 6. Please refactor the following code according to these rules:

1.  **Suite Creation**: `create` now returns a Suite Object, not a function.
    - Change `const suite = create(...)` to keep the same variable name.
    - Remove any suite name passed as the first argument to `create`.

2.  **Running Suites**:
    - Change `suite(data)` to `suite.run(data)`.
    - Change `staticSuite(...)` to `create(...)` and run it with `suite.runStatic(data)`.

3.  **Async Handling**:
    - Remove `import { promisify } from 'vest'`.
    - Remove `promisify(suite)`.
    - Change `await suite(data)` or `promisified(data)` to `await suite.run(data)`.
    - Remove `.done()` callbacks. Use `await suite.afterField('fieldName', callback)` or `suite.afterEach(callback)`.

4.  **Memoization**:
    - Change `test.memo(...)` to `memo(() => { test(...) }, deps)`.
    - Ensure `memo` is imported from 'vest/memo': `import { memo } from 'vest/memo';`.

5.  **Field-Focused Validation**:
    - If the suite callback accepts a second argument used with `only(fieldName)` inside the callback, refactor it to use `suite.only(fieldName).run(data)` or `suite.focus({ only: fieldName }).run(data)` at the call site instead.
    - Remove the extra callback parameter and the `only()` / `skip()` call from inside the callback body.
    - For group-level skipping, replace `skip(true)` inside `group()` with `suite.focus({ skipGroup: 'groupName' }).run(data)`.

6.  **General**:
    - Keep all validation logic intact.
    - Preserve comments.