Validation API Reference

The validation is a central piece of this library, below you will find the API reference for the validation.

Adapter

An adapter is an object that provides two functions to turn a given schema into a sync or async validator. It also declares a ValidatorSchemaType which is a Typescript limitation and is used to infer the schema type.

interface ValidatorAdapter {
  sync<TValue, TMixins extends readonly any[] = never[]>(
    schema: any,
  ): ValidatorSync<TValue, TMixins>

  async<TValue, TMixins extends readonly any[] = never[]>(
    schema: any,
  ): ValidatorAsync<TValue, TMixins>
}

The return type of the ValidatorSchemaType is the schema to use for a given adapter and value.

interface ValidatorSchemaType<TValue, TMixin> {
  (): never
}

INFO

If you are creating your own adapter, make sure to declare the ValidatorSchemaType for your adapter.

declare module '@formsignals/form-core' {
  interface ValidatorSchemaType<TValue, TMixin> {
    (): number
  }
}

The adapter receives the schema as an input during validation. The schema is what is given to the validator option if an adapter is configured.

Validator (sync)

A sync validator is a function that receives a value and returns a ValidationError if the value is invalid. If there are mixins defined, the value will be an array with the value and the mixins.

export type ValidatorSync<
  TValue,
  TMixins extends readonly any[] = never[],
> = TMixins extends never[]
  ? (value: TValue) => ValidationError
  : (value: [TValue, ...TMixins]) => ValidationError

ValidatorOptions (sync)

The ValidatorOptions is an object that contains the options used during the validation.

interface ValidatorOptions {
  disableOnChangeValidation?: boolean
  disableOnBlurValidation?: boolean
  validateOnMount?: boolean
  validateOnChangeIfTouched?: boolean
}

Option	Description	Default
disableOnChangeValidation	Disables the validation on change.	false
disableOnBlurValidation	Disables the validation on blur.	false
validateOnMount	Enables the field validation on mount.	false
validateOnChangeIfTouched	Only runs the on change validation if the field is touched.	false

Validator (async)

An async validator is a function that receives a value and returns a Promise that resolves to a ValidationError if the value is invalid. The validator also receives an AbortSignal that can be used to determine whether the validation should be aborted. Mixins work the same as with the sync validator.

type ValidatorAsync<
  TValue,
  TMixins extends readonly any[] = never[],
> = TMixins extends never[]
  ? (
    value: TValue,
    abortSignal: AbortSignal,
  ) => Promise<ValidationError> | ValidationError
  : (
    value: [TValue, ...TMixins],
    abortSignal: AbortSignal,
  ) => Promise<ValidationError> | ValidationError

ValidatorOptions (async)

The ValidatorOptions for async validators extend the sync options and add options for async validation.

interface ValidatorAsyncOptions extends ValidatorOptions {
  debounceMs?: number
  accumulateErrors?: boolean
}

Option	Description	Default
debounceMs	The debounce time in milliseconds.	undefined
accumulateErrors	Accumulates the errors instead of stopping at the first one.	false

ErrorTransformers

This is a collection of functions, that can be used to transform the error messages form a schema validation library to a format that is used by this library.

interface ErrorTransformers {
  zod: (issues: ZodIssue[]) => Record<string, string>
}

INFO

Currently only zod is supported.