Asynchronous Validation Strategies

export type ValidationState =
  | 'idle'        // no check has run or field is empty
  | 'validating'  // a request is in flight
  | 'valid'       // server confirmed the value is acceptable
  | 'error'       // server rejected the value (shows message)
  | 'retryable';  // network failure — user can retry without retyping

export type ValidationState =
  | 'idle'
  | 'validating'
  | 'valid'
  | 'error'
  | 'retryable';

export interface AsyncValidatorOptions {
  /** The remote check: receives the current value plus the AbortSignal.
   *  Return true if the value is acceptable. */
  fetchFn: (value: string, signal: AbortSignal) => Promise<boolean>;
  /** Milliseconds to wait after the last keystroke before firing the request.
   *  Defaults to 300 ms — increase for expensive endpoints. */
  debounceMs?: number;
  /** Hard deadline for the fetch. On expiry the state moves to 'retryable'
   *  and the in-flight request is cancelled via the same AbortController. */
  timeoutMs?: number;
  /** Called on every state transition so the UI layer can re-render. */
  onStateChange?: (state: ValidationState) => void;
}

export function createAsyncValidator({
  fetchFn,
  debounceMs = 300,
  timeoutMs = 5000,
  onStateChange,
}: AsyncValidatorOptions) {
  let currentState: ValidationState = 'idle';

  // Timers are stored so cleanup() can cancel them from outside.
  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
  let timeoutTimer: ReturnType<typeof setTimeout> | null = null;

  // One AbortController per request cycle.
  // Keeping a reference lets us cancel the previous cycle when a new one starts.
  let currentController: AbortController | null = null;

  function setState(state: ValidationState): void {
    currentState = state;
    onStateChange?.(state);
  }

  async function validate(value: string): Promise<ValidationState> {
    // Cancel any pending debounce from the previous keystroke.
    if (debounceTimer) clearTimeout(debounceTimer);

    // Abort the in-flight request from the previous cycle.
    // The fetch will throw a DOMException with name 'AbortError', caught below.
    if (currentController) currentController.abort();

    // Clear any existing timeout guard.
    if (timeoutTimer) clearTimeout(timeoutTimer);

    setState('validating');

    // Fresh controller for this cycle — passed into fetchFn so it can
    // attach to fetch() directly: fetch(url, { signal }).
    currentController = new AbortController();
    const { signal } = currentController;

    return new Promise<ValidationState>((resolve) => {
      debounceTimer = setTimeout(async () => {
        // Timeout guard: if fetchFn takes longer than timeoutMs, abort it
        // and surface a retryable state instead of an indefinite spinner.
        timeoutTimer = setTimeout(() => {
          currentController?.abort();
          setState('retryable');
          resolve('retryable');
        }, timeoutMs);

        try {
          const isValid = await fetchFn(value, signal);

          // Clear the timeout guard — the request returned in time.
          if (timeoutTimer) clearTimeout(timeoutTimer);

          // If the signal was aborted between the fetch completing and this
          // line, a newer request is already running — do not overwrite its state.
          if (signal.aborted) return resolve('idle');

          const next: ValidationState = isValid ? 'valid' : 'error';
          setState(next);
          resolve(next);
        } catch (err) {
          if (timeoutTimer) clearTimeout(timeoutTimer);

          // AbortError means this cycle was superseded — not a real failure.
          if (err instanceof DOMException && err.name === 'AbortError') {
            return resolve('idle');
          }

          setState('error');
          resolve('error');
        }
      }, debounceMs);
    });
  }

  function cleanup(): void {
    if (debounceTimer) clearTimeout(debounceTimer);
    if (timeoutTimer) clearTimeout(timeoutTimer);
    // Cancel any in-flight request so it does not resolve after unmount.
    if (currentController) currentController.abort();
    setState('idle');
  }

  return { validate, getState: () => currentState, cleanup };
}

import { useEffect, useRef, useState } from 'react';
import { createAsyncValidator, ValidationState } from './createAsyncValidator';

export function UsernameField() {
  const [state, setState] = useState<ValidationState>('idle');
  const validatorRef = useRef(
    createAsyncValidator({
      fetchFn: async (value, signal) => {
        const res = await fetch(`/api/username-available?q=${encodeURIComponent(value)}`, { signal });
        const data = await res.json();
        return data.available as boolean;
      },
      onStateChange: setState,
    })
  );

  // Abort in-flight request on unmount — prevents state updates on dead components.
  useEffect(() => () => validatorRef.current.cleanup(), []);

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    validatorRef.current.validate(e.target.value);
  };

  return (
    <div>
      <input
        id="username"
        type="text"
        onChange={handleChange}
        aria-busy={state === 'validating'}
        aria-invalid={state === 'error'}
        aria-describedby="username-hint"
      />
      <span id="username-hint" role="status" aria-live="polite">
        {state === 'validating' && 'Checking availability…'}
        {state === 'valid' && 'Username is available.'}
        {state === 'error' && 'Username is taken.'}
        {state === 'retryable' && 'Network error — please try again.'}
      </span>
    </div>
  );
}

import { z } from 'zod';

// Sync rules run first; the async refinement only fires when they pass.
const usernameSchema = z
  .string()
  .min(3, 'At least 3 characters')
  .max(30, 'At most 30 characters')
  .regex(/^[a-z0-9_]+$/, 'Lowercase letters, numbers, and underscores only')
  // async .refine() requires .parseAsync() / .safeParseAsync() — see below.
  .refine(
    async (value) => {
      const res = await fetch(`/api/username-available?q=${encodeURIComponent(value)}`);
      const data = await res.json();
      return data.available as boolean;
    },
    { message: 'Username is already taken' }
  );

// MUST use safeParseAsync — regular safeParse() ignores async refinements.
const result = await usernameSchema.safeParseAsync(inputValue);

function mapValidationState(
  state: ValidationState,
  schemaError?: string
): { message: string | null; pending: boolean } {
  if (state === 'validating') return { message: null, pending: true };
  if (state === 'error') return { message: schemaError ?? 'Value is invalid', pending: false };
  if (state === 'retryable') return { message: 'Network error — tap to retry', pending: false };
  return { message: null, pending: false };
}

// Rendered by the field component
<div
  data-field="username"
  data-validation-state={state}  // 'idle' | 'validating' | 'valid' | 'error' | 'retryable'
>
  <input ... />
  <span role="status">...</span>
</div>

// Playwright test
await expect(page.locator('[data-field="username"][data-validation-state="valid"]')).toBeVisible();

import { createAsyncValidator } from './createAsyncValidator';

test('transitions to valid when server returns true', async () => {
  const states: string[] = [];
  const validator = createAsyncValidator({
    fetchFn: async () => true,            // mock: always available
    debounceMs: 0,                        // skip debounce in tests
    onStateChange: (s) => states.push(s),
  });

  await validator.validate('newuser');
  expect(states).toEqual(['validating', 'valid']);
  validator.cleanup();
});

test('transitions to retryable on timeout', async () => {
  const states: string[] = [];
  const validator = createAsyncValidator({
    fetchFn: () => new Promise(() => {}),  // never resolves — simulates hang
    debounceMs: 0,
    timeoutMs: 10,
    onStateChange: (s) => states.push(s),
  });

  await validator.validate('anyvalue');
  expect(states).toContain('retryable');
  validator.cleanup();
});