Async Validation

Ctrovalidate provides a first-class asynchronous validation engine. It handles remote checks (like username availability or ZIP code lookups) with race-condition protection and automatic cancellation of stale requests.

How it Works

Async rules return a Promise<boolean>. The engine ensures:

1. Race Protection: When a field is re-validated before a previous async rule resolves, the previous AbortController is aborted.
2. Pending States: The UI is notified via pendingClass (browser) or isValidating flags (framework hooks).
3. Sequential Execution: Rules within a field run in order. The engine awaits each async rule before moving to the next.

The AbortSignal Pattern

Every async rule receives an AbortSignal as its 4th parameter. Pass this to fetch so that stale requests are canceled when the field is re-validated.

import { Ctrovalidate } from 'ctrovalidate-browser';
 
Ctrovalidate.addAsyncRule('checkUsername', async (value, params, element, signal) => {
  try {
    const response = await fetch(`/api/check?u=${value}`, { signal });
    const { available } = await response.json();
    return available;
  } catch (error) {
    // AbortError is expected when re-validation cancels the previous request
    if (error.name === 'AbortError') return true;
    return false;
  }
});

What happens on abort

1. User types "john" → validation starts with signal A
2. User types "johndoe" before previous completes → signal A is aborted, signal B starts
3. The fetch from step 1 throws AbortError
4. The engine catches it silently and returns true (no false error shown)
5. Step 2's validation completes normally

Async Validation in Core

The core package provides validateValueAsync and validateAsync for server-side or framework use. Custom rules are passed via the customRules option:

import { validateAsync } from 'ctrovalidate-core';
 
const results = await validateAsync(
  { username: 'john' },
  { username: 'required|checkUsername' },
  {
    customRules: {
      checkUsername: async (value, params, ctx, signal) => {
        const res = await fetch(`/api/check?u=${value}`, { signal });
        return (await res.json()).available;
      },
    },
  }
);

Best Practices

• Propagate the Signal: Always pass signal to fetch or other abortable APIs.
• Loading Indicators: Show visual feedback during async validation via pendingClass (browser) or isValidating state (React, Vue, Svelte).
• Timeout Protection: Wrap fetch calls with AbortSignal.timeout() if your server might be slow.
• AbortError Handling: Catch AbortError and return true to prevent false error messages.