ctrovalidate-svelte

The useCtrovalidate function returns Svelte stores (writable/derived) for form state, errors, dirty tracking, and async validation status. Integrates with ctrovalidate-core's validateAsync.

useCtrovalidate<T>(options)

function useCtrovalidate<T extends object>(options: UseCtrovalidateOptions<T>): {
  values: Writable<T>;
  errors: Writable<Partial<Record<keyof T, string>>>;
  isDirty: Writable<Partial<Record<keyof T, boolean>>>;
  isValidating: Writable<Partial<Record<keyof T, boolean>>>;
  isValid: Readable<boolean>;
  validateField: (name: keyof T, value?: T[keyof T]) => Promise<boolean>;
  validateForm: () => Promise<boolean>;
  reset: (newValues?: Partial<T>) => void;
  handleChange: (name: keyof T, value: T[keyof T]) => void;
  handleBlur: (name: keyof T) => void;
}

Options

interface UseCtrovalidateOptions<T extends object> {
  schema: ValidationSchema;
  initialValues?: T;
  validateOnBlur?: boolean;
  validateOnChange?: boolean;
  customRules?: Record<string, RuleLogic | AsyncRuleLogic>;
  aliases?: Record<string, SchemaRule>;
  messages?: Record<string, string>;
  locale?: string;
}

Return Values

Stores (use $ prefix in templates)

Methods

Behavior Details

handleChange(name, value)

<input value={$values.email} on:input={(e) => handleChange('email', e.target.value)} />

1. Updates values store via .update()
2. Marks isDirty[name] = true
3. Calls validateField(name) if validateOnChange is enabled

handleBlur(name)

<input on:blur={() => handleBlur('email')} />

1. Marks isDirty[name] = true
2. Calls validateField(name) if validateOnBlur is enabled

validateField(name, value?)

1. Returns true if no schema rule exists for the field
2. Aborts any in-flight async rule for that field (via AbortController)
3. Sets isValidating[name] = true
4. Calls validateAsync with the field value and signal
5. Sets errors[name] to error string (or undefined if valid)
6. Sets isValidating[name] = false
7. Returns true if valid

If the async rule throws AbortError, returns false silently. Other errors are logged and return false.

validateForm()

1. Reads current values via get(values)
2. Calls validateAsync with full data and schema
3. Replaces errors store with fresh results
4. Returns true only if every field passes

reset(newValues?)

Re-initializes all stores: values to merged initialValues + newValues, errors/dirty/validating to fresh objects with all schema keys set to undefined/false.

Abort Lifecycle

Each field has its own AbortController stored in a closure. When validateField is called again before the previous call completes, the old controller is aborted. All controllers are aborted on component destroy via onDestroy.

Usage Patterns

Recommended: handleChange + handleBlur

<script lang="ts">
  const { values, errors, handleChange, handleBlur, validateForm } =
    useCtrovalidate<{ email: string }>({
      initialValues: { email: '' },
      schema: { email: 'required|email' },
    });
</script>
 
<input
  value={$values.email}
  on:input={(e) => handleChange('email', e.target.value)}
  on:blur={() => handleBlur('email')}
/>
{#if $errors.email}
  <span>{$errors.email}</span>
{/if}

Direct store mutation (without handleChange)

<input
  value={$values.email}
  on:input={(e) => $values.email = e.target.value}
/>

Note: Direct store mutation does NOT mark the field dirty or trigger validation. Use handleChange for automatic validation.

Exports

import { useCtrovalidate } from 'ctrovalidate-svelte';
import type { UseCtrovalidateOptions } from 'ctrovalidate-svelte';