Open History to see the last commit
1import type { DeepKeys } from './deep-keys.public'
2import type { FormApi, OnSubmitError } from './FormApi/FormApi.public'
3import type { AnyFieldApi, FieldApi } from './FieldApi/FieldApi.public'
4import type { FormGroupApi } from './FormGroupApi/FormGroupApi.public'
5import type {
6 StandardSchemaV1,
7 StandardSchemaV1Issue,
8} from './standardSchema.public'
9import type { OneOrMany } from './types.public'
10import type { VALIDATION_OUTPUT } from './validationOutput.lib'
11β
12/**
13 * A validation function or Standard Schema with an optional rule to stop after earlier failures.
14 *
15 * @typeParam TValidator - Library-managed. Do not specify explicitly.
16 */
17export interface BaseValidator<
18 out TValidator extends StandardSchemaV1 | ValidatorFn<any, any>,
19> {
20 /** The function or Standard Schema that validates the value in this validator's scope. */
21 run: TValidator
22 /**
23 * If `true`, skips this and subsequent validators when earlier validation has failed.
24 *
25 * If `false`, earlier failures do not prevent this validator from running.
26 *
27 * @default false
28 */
29 bailIfInvalid?: boolean
30}
31β
32/**
33 * Configures validation for a form, form group, or field.
34 *
35 * @typeParam TFormData - Library-managed. Do not specify explicitly.
36 * @typeParam TValidator - Library-managed. Do not specify explicitly.
37 * @typeParam TContextValue - Library-managed. Do not specify explicitly.
38 * @typeParam TTrigger - Library-managed. Do not specify explicitly.
39 * @typeParam TScope - Library-managed. Do not specify explicitly.
40 */
41export interface Validator<
42 in out TFormData,
43 out TValidator extends StandardSchemaV1 | ValidatorFn<any, any>,
44 in out TContextValue,
45 in out TTrigger extends ValidatorTrigger = ValidatorTrigger,
46 in out TScope extends ValidatorScope = ValidatorScope,
47> extends BaseValidator<TValidator> {
48 /**
49 * Whether this validator runs during a submission attempt, independently of `triggers`.
50 *
51 * Pass a boolean directly, or pass a function that returns
52 * `true` to skip it for the current attempt.
53 *
54 * @default false
55 */
56 skipOnSubmit?:
57 boolean | ValidationPredicateFn<TFormData, TContextValue, TScope>
58 /**
59 * Whether this validator runs when the form is constructed or when its field
60 * or form group first mounts.
61 *
62 * @default false
63 */
64 runOnMount?: boolean
65 /**
66 * The delay in milliseconds before validation runs for change or blur events.
67 *
68 * Pass a number for a fixed delay, or pass a function that returns the delay
69 * for the current event. Repeated events restart the delay.
70 * Submission validation runs immediately.
71 *
72 * @default 0
73 */
74 triggerDebounceMs?:
75 number | ValidationDebounceFn<TFormData, TContextValue, TScope>
76 /**
77 * Change and blur events that can run this validator, optionally with conditions.
78 *
79 * An empty array disables change and blur validation. Configure submission
80 * separately with `skipOnSubmit` and initial validation with `runOnMount`.
81 */
82 triggers: Array<
83 ValidationTriggerOption<TFormData, TContextValue, TTrigger, TScope>
84 >
85}
86β
87/**
88 * Reusable scheduling and failure-handling options for `createValidator` or `createValidators`.
89 *
90 * @typeParam TFormData - Library-managed. Do not specify explicitly.
91 * @typeParam TContextValue - Library-managed. Do not specify explicitly.
92 * @typeParam TTrigger - Library-managed. Do not specify explicitly.
93 * @typeParam TScope - Library-managed. Do not specify explicitly.
94 */
95export type ValidatorOptions<
96 TFormData,
97 TContextValue,
98 TTrigger extends ValidatorTrigger = ValidatorTrigger,
99 TScope extends ValidatorScope = ValidatorScope,
100> = Omit<
101 Validator<
102 TFormData,
103 StandardSchemaV1<any, any> | ValidatorFn<any, any>,
104 TContextValue,
105 TTrigger,
106 TScope
107 >,
108 'run' | 'triggers'
109> & {
110 triggers: Array<FormValidationTriggerOption<TFormData, TContextValue, TScope>>
111}
112β
113type ValidatorRun = StandardSchemaV1<any, any> | ValidatorFn<any, any>
114β
115type ValidatorWithRun<
116 TFormData,
117 TContextValue,
118 TOptions extends ValidatorOptions<TFormData, TContextValue, any>,
119 TRun extends ValidatorRun,
120> = TOptions & Pick<Validator<TFormData, TRun, TContextValue>, 'run'>
121β
122type InferFormDataFromValidator<TValidator extends ValidatorRun> =
123 TValidator extends StandardSchemaV1<infer TFormData, any>
124 ? TFormData
125 : TValidator extends FormValidatorFn<infer TFormData>
126 ? TFormData
127 : TValidator extends ServerFormValidatorFn<infer TFormData>
128 ? TFormData
129 : TValidator extends FormGroupValidatorFn<infer TGroupValue>
130 ? TGroupValue
131 : any
132β
133/**
134 * A validator created by combining reusable options with a validation function
135 * or Standard Schema through `createValidator`.
136 *
137 * @typeParam TOptions - Library-managed. Do not specify explicitly.
138 * @typeParam TRun - Library-managed. Do not specify explicitly.
139 */
140export type CreatedValidator<
141 TOptions extends ValidatorOptions<any, any>,
142 TRun extends ValidatorRun,
143> = ValidatorWithRun<
144 InferFormDataFromValidator<TRun>,
145 InferFormDataFromValidator<TRun>,
146 TOptions,
147 TRun
148>
149β
150type ValidatorRunsFromOptions<
151 in out TOptions extends readonly [
152 ValidatorOptions<any, any, any>,
153 ...Array<ValidatorOptions<any, any, any>>,
154 ],
155> = {
156 readonly [TIndex in keyof TOptions]: ValidatorRun
157}
158β
159type ValidatorsFromOptionsAndRuns<
160 in out TFormData,
161 in out TContextValue,
162 in out TOptions extends readonly [
163 ValidatorOptions<TFormData, TContextValue, any>,
164 ...Array<ValidatorOptions<TFormData, TContextValue, any>>,
165 ],
166 in out TRuns extends ValidatorRunsFromOptions<TOptions>,
167> = {
168 readonly [TIndex in keyof TOptions]: ValidatorWithRun<
169 TFormData,
170 TContextValue,
171 TOptions[TIndex],
172 TRuns[TIndex]
173 >
174}
175β
176/**
177 * Creates a reusable configuration to apply to validation functions or Standard Schemas.
178 *
179 * @returns A function that combines `options` with its `run` argument, preserving
180 * the validator's inferred types. Its `TValidator` type argument is library-managed.
181 * Do not specify it explicitly.
182 * @typeParam TOptions - Library-managed. Do not specify explicitly.
183 *
184 * @example
185 * ```ts
186 * const afterSubmit = createValidator({
187 * triggers: [{
188 * trigger: 'change',
189 * when: ({ formApi }) => formApi.state.submissionAttempts > 0,
190 * }],
191 * })
192 * const validators = [afterSubmit(schema)]
193 * ```
194 */
195export function createValidator<
196 const TOptions extends ValidatorOptions<any, any>,
197>(
198 options: TOptions,
199): <const TValidator extends ValidatorRun>(
200 run: TValidator,
201) => CreatedValidator<TOptions, TValidator> {
202 return (run: ValidatorRun) => ({ ...options, run }) as never
203}
204β
205/**
206 * Creates a reusable configuration for an ordered set of validators.
207 *
208 * @param options - A nonempty tuple of configurations, one per validator.
209 * @returns A function that accepts one validation function or Standard Schema
210 * per configuration, in the same order. Its `TRuns` type argument is library-managed.
211 * Do not specify it explicitly.
212 * @typeParam TFormData - Library-managed. Do not specify explicitly.
213 * @typeParam TContextValue - Library-managed. Do not specify explicitly.
214 * @typeParam TOptions - Library-managed. Do not specify explicitly.
215 *
216 * @example
217 * ```ts
218 * const withChecks = createValidators([
219 * { triggers: ['change'] },
220 * { triggers: ['blur'], bailIfInvalid: true },
221 * ])
222 * const validators = withChecks(schema, () => 'Additional check failed')
223 * ```
224 */
225export function createValidators<
226 TFormData = any,
227 TContextValue = TFormData,
228 const TOptions extends readonly [
229 ValidatorOptions<TFormData, TContextValue>,
230 ...Array<ValidatorOptions<TFormData, TContextValue>>,
231 ] = readonly [
232 ValidatorOptions<TFormData, TContextValue>,
233 ...Array<ValidatorOptions<TFormData, TContextValue>>,
234 ],
235>(
236 options: TOptions,
237): <const TRuns extends ValidatorRunsFromOptions<TOptions>>(
238 ...runs: TRuns
239) => ValidatorsFromOptionsAndRuns<TFormData, TContextValue, TOptions, TRuns> {
240 return (...runs) =>
241 runs.map((run, index) => ({
242 ...options[index],
243 run,
244 })) as ValidatorsFromOptionsAndRuns<
245 TFormData,
246 TContextValue,
247 TOptions,
248 typeof runs
249 >
250}
251β
252/** Client validation events: value changes, field blur, and submission attempts. */
253export type ValidationTrigger = 'change' | 'blur' | 'submit'
254/** Selects a form validator for execution by `serverValidate`. */
255export type ServerValidationTrigger = 'server'
256/** Events reported to client-side validation callbacks. */
257export type ClientValidationTrigger = ValidationTrigger
258/** Events configured through `triggers`. Submission is controlled by `skipOnSubmit`. */
259export type ConfigurableValidationTrigger = Exclude<ValidationTrigger, 'submit'>
260/** Change and blur events accepted by shared validator configurations. */
261export type ValidatorTrigger = ConfigurableValidationTrigger
262/** The form, form group, or field whose value a validator checks. */
263export type ValidatorScope = 'form' | 'group' | 'field'
264β
265/** Descendant field state available when deciding whether to show errors. */
266export interface ErrorVisibilitySubfieldsMeta {
267 /** `true` when no descendant field is marked as dirty. */
268 isEveryPristine: boolean
269 /** `true` when at least one descendant field is marked as dirty. */
270 isSomeDirty: boolean
271 /** `true` when at least one descendant field is marked as touched. */
272 isSomeTouched: boolean
273 /** `true` while at least one descendant field is validating. */
274 isSomeValidating: boolean
275}
276β
277/** Field state flags available to an error visibility policy. */
278export interface ErrorVisibilityFieldMeta {
279 /** `true` when this field or a descendant is marked as touched. */
280 isTouched: boolean
281 /** `true` when this field itself is marked as touched. */
282 isSelfTouched: boolean
283 /** `true` when this field or a descendant is marked as dirty. */
284 isDirty: boolean
285 /** `true` when this field itself is marked as dirty. */
286 isSelfDirty: boolean
287 /** `true` when neither this field nor its descendants are marked as dirty. */
288 isPristine: boolean
289 /** `true` when the current value equals the field's default value. */
290 isDefaultValue: boolean
291 /** `true` when this field is marked as blurred. */
292 isBlurred: boolean
293 /** `true` while this field or a descendant is validating. */
294 isValidating: boolean
295 /** `true` while this field itself is validating. */
296 isSelfValidating: boolean
297 /** State flags for this field's descendants. */
298 subfields: ErrorVisibilitySubfieldsMeta
299}
300β
301/** The field value and state flags available to an error visibility policy. */
302export interface ErrorVisibilityFieldState {
303 /** The current value of the field whose errors the policy controls. */
304 value: any
305 /** State flags before the visibility policy is applied. */
306 meta: ErrorVisibilityFieldMeta
307}
308β
309/**
310 * Form and field state used to decide whether to show a field's errors.
311 *
312 * @typeParam TFormData - Library-managed. Do not specify explicitly.
313 * @typeParam TFormErrorTypes - Library-managed. Do not specify explicitly.
314 */
315export interface ErrorVisibilityContext<
316 in out TFormData,
317 in out TFormErrorTypes extends FormErrorTypes,
318> {
319 /**
320 * Current form state. For a field in a form group, flags and submission
321 * counters describe that group. `values` and `errors` describe the whole form.
322 */
323 state: FormApi<TFormData, TFormErrorTypes>['state']
324 /** The field whose errors the policy controls. */
325 fieldState: ErrorVisibilityFieldState
326}
327β
328/**
329 * Returns `true` to show a field's validation errors in `field.errors`.
330 *
331 * Hidden errors remain available in `field.meta.original.errors`.
332 *
333 * For fields inside a form group, `state` properties such as `isTouched` and
334 * `submissionAttempts` describe the containing group. `values` and `errors`
335 * still describe the whole form.
336 *
337 * @typeParam TFormData - Library-managed. Do not specify explicitly.
338 * @typeParam TFormErrorTypes - Library-managed. Do not specify explicitly.
339 */
340export type ErrorVisibility<
341 in out TFormData,
342 in out TFormErrorTypes extends FormErrorTypes,
343> = (context: ErrorVisibilityContext<TFormData, TFormErrorTypes>) => boolean
344β
345/**
346 * Form or group state available to a reusable error visibility policy.
347 *
348 * `values` is `unknown` because the policy can be used with different form shapes.
349 */
350export type ReusableErrorVisibilityState = Omit<
351 FormApi<any, any>['state'],
352 'values'
353> & {
354 /** Current form values, without assuming a particular form shape. */
355 values: unknown
356}
357β
358/** State available to a visibility policy shared across different form shapes. */
359export interface ReusableErrorVisibilityContext {
360 /** Form state with group-scoped flags and counters for fields in a form group. */
361 state: ReusableErrorVisibilityState
362 /** The field whose errors the policy controls. */
363 fieldState: ErrorVisibilityFieldState
364}
365β
366/**
367 * An error visibility policy that accepts forms with different value and error types.
368 *
369 * @typeParam TFormData - Library-managed. Do not specify explicitly.
370 * @typeParam TFormErrorTypes - Library-managed. Do not specify explicitly.
371 */
372export type ReusableErrorVisibility = <
373 TFormData,
374 TFormErrorTypes extends FormErrorTypes,
375>(
376 context: ErrorVisibilityContext<TFormData, TFormErrorTypes>,
377) => boolean
378β
379/**
380 * Creates an error visibility policy that can be shared across forms with different values.
381 *
382 * Use an inline `errorVisibility` callback instead when the policy needs
383 * strongly typed access to the consuming form's `values`.
384 *
385 * @param visibility - Returns `true` to show the field's errors, or `false` to hide them.
386 * @returns The policy to assign to a form or field's `errorVisibility` option.
387 */
388export function createErrorVisibility(
389 visibility: (context: ReusableErrorVisibilityContext) => boolean,
390): ReusableErrorVisibility {
391 return visibility
392}
393β
394interface BaseValidationPredicateContext<
395 in out TFormData,
396 out TValue,
397 out TScope extends ValidatorScope,
398> {
399 /** Identifies whether `value` belongs to a form, form group, or field. */
400 scope: TScope
401 /** The owning form, including its complete values and state. */
402 formApi: FormApi<TFormData, any>
403 /**
404 * The field associated with the validation event, when available.
405 *
406 * For form and group validators, this is the field that triggered the
407 * validation. For field validators, this is the field being validated.
408 */
409 fieldApi?: AnyFieldApi
410 /** The current value in this validator's scope when the callback is evaluated. */
411 value: TValue
412}
413β
414/**
415 * Current form state available to validator conditions and delay callbacks.
416 *
417 * @typeParam TFormData - Library-managed. Do not specify explicitly.
418 */
419export interface FormValidationPredicateContext<
420 in out TFormData,
421> extends BaseValidationPredicateContext<TFormData, TFormData, 'form'> {
422 groupApi?: never
423}
424β
425/**
426 * Current form group state available to validator conditions and delay callbacks.
427 *
428 * @typeParam TGroupValue - Library-managed. Do not specify explicitly.
429 */
430export interface FormGroupValidationPredicateContext<
431 in out TGroupValue,
432> extends BaseValidationPredicateContext<any, TGroupValue, 'group'> {
433 /** The form group whose value is being validated. */
434 groupApi: FormGroupApi<any, any, TGroupValue, any, any>
435}
436β
437/**
438 * Current field state available to validator conditions and delay callbacks.
439 *
440 * @typeParam TFormData - Library-managed. Do not specify explicitly.
441 * @typeParam TFieldValue - Library-managed. Do not specify explicitly.
442 */
443export interface FieldValidationPredicateContext<
444 in out TFormData,
445 out TFieldValue,
446> extends BaseValidationPredicateContext<TFormData, TFieldValue, 'field'> {
447 groupApi?: never
448 /** The field being validated. */
449 fieldApi: AnyFieldApi
450}
451β
452/**
453 * Context for validator conditions and delay callbacks, narrowed by `scope`.
454 *
455 * @typeParam TFormData - Library-managed. Do not specify explicitly.
456 * @typeParam TValue - Library-managed. Do not specify explicitly.
457 * @typeParam TScope - Library-managed. Do not specify explicitly.
458 */
459export type ValidationPredicateContext<
460 TFormData,
461 TValue,
462 TScope extends ValidatorScope = ValidatorScope,
463> = TScope extends 'form'
464 ? FormValidationPredicateContext<TFormData>
465 : TScope extends 'group'
466 ? FormGroupValidationPredicateContext<TValue>
467 : TScope extends 'field'
468 ? FieldValidationPredicateContext<TFormData, TValue>
469 : never
470β
471/**
472 * Returns `true` to enable validation for the current event or submission attempt.
473 *
474 * @typeParam TFormData - Library-managed. Do not specify explicitly.
475 * @typeParam TValue - Library-managed. Do not specify explicitly.
476 * @typeParam TScope - Library-managed. Do not specify explicitly.
477 */
478export type ValidationPredicateFn<
479 in out TFormData,
480 in out TValue,
481 in TScope extends ValidatorScope = ValidatorScope,
482> = (context: ValidationPredicateContext<TFormData, TValue, TScope>) => boolean
483β
484/**
485 * Chooses the delay in milliseconds before change or blur validation runs.
486 *
487 * @returns The delay for the current event. Zero or a negative value runs validation immediately.
488 * @typeParam TFormData - Library-managed. Do not specify explicitly.
489 * @typeParam TValue - Library-managed. Do not specify explicitly.
490 * @typeParam TScope - Library-managed. Do not specify explicitly.
491 */
492export type ValidationDebounceFn<
493 in out TFormData,
494 in out TValue,
495 in TScope extends ValidatorScope = ValidatorScope,
496> = (context: ValidationPredicateContext<TFormData, TValue, TScope>) => number
497β
498/**
499 * A change or blur event with an optional condition for running validation.
500 *
501 * @typeParam TFormData - Library-managed. Do not specify explicitly.
502 * @typeParam TValue - Library-managed. Do not specify explicitly.
503 * @typeParam TTrigger - Library-managed. Do not specify explicitly.
504 * @typeParam TScope - Library-managed. Do not specify explicitly.
505 */
506export interface ValidationTriggerConfig<
507 in out TFormData,
508 in out TValue,
509 in out TTrigger extends ValidatorTrigger = ValidatorTrigger,
510 in TScope extends ValidatorScope = ValidatorScope,
511> {
512 /** The event to match before evaluating `when`. */
513 trigger: TTrigger
514 /**
515 * Whether this trigger enables validation when its event occurs.
516 *
517 * Pass a boolean to enable or disable it, or pass a function that returns
518 * `true` to enable it for the current event.
519 *
520 * @default true
521 */
522 when?: boolean | ValidationPredicateFn<TFormData, TValue, TScope>
523}
524β
525/**
526 * A validation event, either unconditional or configured with a `when` condition.
527 *
528 * @typeParam TFormData - Library-managed. Do not specify explicitly.
529 * @typeParam TValue - Library-managed. Do not specify explicitly.
530 * @typeParam TTrigger - Library-managed. Do not specify explicitly.
531 * @typeParam TScope - Library-managed. Do not specify explicitly.
532 */
533export type ValidationTriggerOption<
534 TFormData,
535 TValue,
536 TTrigger extends ValidatorTrigger = ValidatorTrigger,
537 TScope extends ValidatorScope = ValidatorScope,
538> = TTrigger | ValidationTriggerConfig<TFormData, TValue, TTrigger, TScope>
539β
540/**
541 * A change or blur trigger, optionally enabled by a condition.
542 *
543 * @typeParam TFormData - Library-managed. Do not specify explicitly.
544 * @typeParam TValue - Library-managed. Do not specify explicitly.
545 * @typeParam TScope - Library-managed. Do not specify explicitly.
546 */
547export type ClientValidationTriggerOption<
548 TFormData,
549 TValue,
550 TScope extends ValidatorScope = ValidatorScope,
551> = ValidationTriggerOption<
552 TFormData,
553 TValue,
554 ConfigurableValidationTrigger,
555 TScope
556>
557β
558/**
559 * A client event with an optional condition, or the `'server'` event for a form validator.
560 *
561 * Server validation selects validators with a `'server'` trigger independently
562 * of `skipOnSubmit`.
563 *
564 * @typeParam TFormData - Library-managed. Do not specify explicitly.
565 * @typeParam TValue - Library-managed. Do not specify explicitly.
566 * @typeParam TScope - Library-managed. Do not specify explicitly.
567 */
568export type FormValidationTriggerOption<
569 TFormData,
570 TValue,
571 TScope extends ValidatorScope = ValidatorScope,
572> =
573 | ClientValidationTriggerOption<TFormData, TValue, TScope>
574 | ServerValidationTrigger
575β
576/**
577 * A validation error with a display message.
578 */
579export interface ValidationIssue {
580 /** The text to display for this error. */
581 message: string
582}
583/** An error supplied as an issue object or a string that becomes its `message`. */
584export type ValidationErrorValue = ValidationIssue | string
585/** One or more issue objects after string errors have been normalized. */
586export type ValidationError = OneOrMany<ValidationIssue>
587/** One or more errors accepted from a validator, including string messages. */
588export type ValidationErrorInput = OneOrMany<ValidationErrorValue>
589β
590/**
591 * Errors owned by a form or group and errors routed to its fields.
592 *
593 * @typeParam TFormData - Library-managed. Do not specify explicitly.
594 */
595export interface ValidationErrorMap<in out TFormData> {
596 /** Errors for the form or group that owns the validator. */
597 form?: ValidationErrorInput
598 /** Errors keyed by field path. Paths are relative to the group for group validators. */
599 fields: Partial<Record<DeepKeys<TFormData>, ValidationErrorInput>>
600}
601β
602/**
603 * Creates a mutable map of form errors and errors for individual field paths.
604 *
605 * Pass the completed map back from a form or group validator to report the errors.
606 *
607 * @param initial - An existing map to reuse. A missing `fields` object is added to it.
608 * @returns The initial map, if supplied, or a new map with an empty `fields` object.
609 * @typeParam TFormData - The form or group value shape whose field paths are
610 * accepted by the map. Specify it when calling this helper directly to restrict
611 * `fields` to that shape's paths. Without a known value shape, field paths are
612 * unrestricted. The validator context's `createErrorMap` already uses the form
613 * or group shape and needs no type argument.
614 */
615export function createErrorMap<TFormData>(
616 initial?: Partial<ValidationErrorMap<TFormData>>,
617): ValidationErrorMap<TFormData> {
618 if (!initial) return { fields: {} }
619β
620 initial.fields ??= {}
621 return initial as ValidationErrorMap<TFormData>
622}
623β
624/**
625 * Creates a mutable error map with field paths inferred from the validator's value shape.
626 *
627 * @typeParam TFormData - Library-managed. Do not specify explicitly.
628 */
629export type CreateErrorMapFn<in out TFormData> =
630 typeof createErrorMap<TFormData>
631β
632/**
633 * Standard Schema issues reported at form or group scope and routed to field paths.
634 *
635 * @typeParam TFormData - Library-managed. Do not specify explicitly.
636 */
637export interface ParsedStandardSchemaIssues<in out TFormData> {
638 /** All supplied issues, including those with field paths. */
639 form: Array<StandardSchemaV1Issue>
640 /** Issues with paths, grouped by field path relative to the validator's value. */
641 fields: Partial<Record<DeepKeys<TFormData>, Array<StandardSchemaV1Issue>>>
642}
643β
644/**
645 * Converts Standard Schema issues into errors owned by the field being validated.
646 *
647 * @returns A copy of the issue array. Issue paths do not route errors to other fields.
648 */
649export type ParseFieldIssuesFn = (
650 issues: ReadonlyArray<StandardSchemaV1Issue>,
651) => Array<StandardSchemaV1Issue>
652β
653/**
654 * Converts Standard Schema issues into a form or group error map to return from a validator.
655 *
656 * @returns All issues in `form`, with issues that have paths also grouped in `fields`.
657 * @typeParam TFormData - Library-managed. Do not specify explicitly.
658 */
659export type ParseFormIssuesFn<TFormData> = (
660 issues: ReadonlyArray<StandardSchemaV1Issue>,
661) => ParsedStandardSchemaIssues<TFormData>
662β
663/**
664 * A successful validation result that carries data for `validatorOutputs`.
665 *
666 * Return the result of the validator context's `createOutput` helper to provide
667 * data during submission or server validation.
668 *
669 * @typeParam TOutput - Library-managed. Do not specify explicitly.
670 */
671export interface ValidationOutput<out TOutput> {
672 readonly [VALIDATION_OUTPUT]: TOutput
673}
674β
675/**
676 * Creates a successful validation result with data for `validatorOutputs`.
677 *
678 * Return this result from a form or group validator. The payload appears at that
679 * validator's index during submission or server validation and is forwarded
680 * without mutation. Outputs from change, blur, and mount validation are **not**
681 * retained for later submission.
682 *
683 * @param value - The payload to expose at this validator's index.
684 * @returns A successful validator result containing the original payload.
685 * @typeParam TOutput - Library-managed. Do not specify explicitly.
686 *
687 * @example
688 * ```ts
689 * formOptions({
690 * defaultValues: { name: '' },
691 * validators: [{
692 * triggers: [],
693 * run: ({ value, createOutput }) => createOutput(value.name.trim()),
694 * }],
695 * onSubmit: ({ validatorOutputs }) => {
696 * const trimmedName = validatorOutputs[0]
697 * // ...
698 * },
699 * })
700 * ```
701 */
702export type CreateOutputFn = <TOutput>(
703 value: TOutput,
704) => ValidationOutput<TOutput>
705β
706/**
707 * Values and helpers passed to a form validation function.
708 *
709 * @typeParam TFormData - Library-managed. Do not specify explicitly.
710 */
711export interface FormValidatorContext<in out TFormData> {
712 /** The event that caused this validation run. */
713 event: ValidationTrigger | ServerValidationTrigger
714 /** Aborted when this run is cancelled. Pass it to asynchronous work such as `fetch`. */
715 signal: AbortSignal
716 /** The owning form on the client. `undefined` during server validation. */
717 formApi: FormApi<TFormData, any> | undefined
718 /** The field that caused validation, when available. */
719 triggerFieldApi?: AnyFieldApi
720 /** The complete form values being validated. */
721 value: TFormData
722 /** Converts Standard Schema issues into form and field errors to return from this validator. */
723 parseIssues: ParseFormIssuesFn<TFormData>
724 /** Creates an error map with field paths inferred from the form values. */
725 createErrorMap: CreateErrorMapFn<TFormData>
726 /** Creates a successful result to return data in this validator's `validatorOutputs` entry. */
727 createOutput: CreateOutputFn
728}
729β
730/**
731 * Values and helpers passed to a server form validation function.
732 *
733 * @typeParam TFormData - Library-managed. Do not specify explicitly.
734 */
735export interface ServerFormValidatorContext<in out TFormData> {
736 /** The validation event. `serverValidate` supplies `'server'`. */
737 event: ValidationTrigger | ServerValidationTrigger
738 /** Aborted when this run is cancelled. Pass it to asynchronous work such as `fetch`. */
739 signal: AbortSignal
740 /** `undefined` during server validation, where no client form instance exists. */
741 formApi: FormApi<TFormData, any> | undefined
742 /** Absent during server validation, which is not triggered by a client field. */
743 triggerFieldApi?: AnyFieldApi
744 /** The complete form values passed to server validation. */
745 value: TFormData
746 /** Converts Standard Schema issues into form and field errors to return from this validator. */
747 parseIssues: ParseFormIssuesFn<TFormData>
748 /** Creates an error map with field paths inferred from the form values. */
749 createErrorMap: CreateErrorMapFn<TFormData>
750 /** Creates a successful result to return data in this validator's server `validatorOutputs` entry. */
751 createOutput: CreateOutputFn
752}
753β
754/** A validator return value that indicates success without providing output data. */
755export type ValidValidationResult = null | undefined | false
756β
757/** A validator return value that indicates success, with or without output data. */
758export type SuccessfulValidationResult =
759 ValidValidationResult | ValidationOutput<unknown>
760β
761/**
762 * One or more validation errors, or `null`, `undefined`, or `false` for success.
763 */
764export type ValidationResult = ValidValidationResult | ValidationErrorInput
765β
766/**
767 * Errors for a form, optionally including errors routed to individual fields.
768 *
769 * @typeParam TFormData - Library-managed. Do not specify explicitly.
770 */
771export type FormValidationError<TFormData> =
772 ValidationErrorInput | ValidationErrorMap<TFormData>
773/**
774 * A form validator's success result, output data, or validation errors.
775 *
776 * @typeParam TFormData - Library-managed. Do not specify explicitly.
777 */
778export type FormValidateResult<TFormData> =
779 SuccessfulValidationResult | FormValidationError<TFormData>
780β
781/**
782 * A validation callback that can return a result immediately or asynchronously.
783 *
784 * @typeParam TParameter - Library-managed. Do not specify explicitly.
785 * @typeParam TReturn - Library-managed. Do not specify explicitly.
786 */
787export type ValidatorFn<in TParameter, out TReturn> = (
788 ...args: Array<TParameter>
789) => TReturn | Promise<TReturn>
790β
791/**
792 * Validates complete form values and can return form errors, field errors, or output data.
793 *
794 * @typeParam TFormData - Library-managed. Do not specify explicitly.
795 */
796export type FormValidatorFn<TFormData> = ValidatorFn<
797 FormValidatorContext<TFormData>,
798 FormValidateResult<TFormData>
799>
800β
801/**
802 * Validates submitted form values on the server without a client form instance.
803 *
804 * @typeParam TFormData - Library-managed. Do not specify explicitly.
805 */
806export type ServerFormValidatorFn<TFormData> = ValidatorFn<
807 ServerFormValidatorContext<TFormData>,
808 FormValidateResult<TFormData>
809>
810β
811/**
812 * Configures validation of complete form values on the client or server.
813 *
814 * @typeParam TFormData - Library-managed. Do not specify explicitly.
815 */
816export interface FormValidator<in out TFormData> extends BaseValidator<
817 FormValidatorFn<TFormData> | StandardSchemaV1<TFormData, any>
818> {
819 /**
820 * Whether this validator runs during a client submission attempt, independently of `triggers`.
821 *
822 * Pass a boolean or a function that returns
823 * `true` to skip it for the current attempt.
824 *
825 * @default false
826 */
827 skipOnSubmit?: boolean | ValidationPredicateFn<TFormData, TFormData, 'form'>
828 /**
829 * Whether this validator runs when the form is constructed.
830 *
831 * @default false
832 */
833 runOnMount?: boolean
834 /**
835 * The delay in milliseconds before validation runs for change or blur events.
836 *
837 * Pass a number for a fixed delay, or pass a function that returns the delay
838 * for the current event. Repeated events restart the delay.
839 * Submission and server validation run immediately.
840 *
841 * @default 0
842 */
843 triggerDebounceMs?:
844 number | ValidationDebounceFn<TFormData, TFormData, 'form'>
845 /**
846 * Change and blur events that can run this validator, optionally with conditions.
847 * Add `'server'` to include it in `serverValidate`.
848 *
849 * An empty array disables change, blur, and server validation. Configure client
850 * submission separately with `skipOnSubmit` and initial validation with `runOnMount`.
851 */
852 triggers: Array<FormValidationTriggerOption<TFormData, TFormData, 'form'>>
853}
854β
855/**
856 * Form validators in configuration order, which also determines their `validatorOutputs` indexes.
857 *
858 * @typeParam TFormData - Library-managed. Do not specify explicitly.
859 */
860export type FormValidators<TFormData> = ReadonlyArray<FormValidator<TFormData>>
861β
862/**
863 * Values and helpers passed to a form group validation function.
864 *
865 * @typeParam TGroupValue - Library-managed. Do not specify explicitly.
866 */
867export interface FormGroupValidatorContext<in out TGroupValue> {
868 /** The event that caused this validation run. */
869 event: ClientValidationTrigger
870 /** Aborted when this run is cancelled. Pass it to asynchronous work such as `fetch`. */
871 signal: AbortSignal
872 /** The owning form, including values outside this group. */
873 formApi: FormApi<any, any>
874 /** The group whose value is being validated. */
875 groupApi: FormGroupApi<any, any, TGroupValue, any, any>
876 /** The field that caused validation, when available. */
877 triggerFieldApi?: AnyFieldApi
878 /** The group's current value, without the surrounding form values. */
879 value: TGroupValue
880 /** Converts Standard Schema issues into group errors and errors at group-relative field paths. */
881 parseIssues: ParseFormIssuesFn<TGroupValue>
882 /** Creates an error map whose field paths are relative to this group. */
883 createErrorMap: CreateErrorMapFn<TGroupValue>
884 /** Creates a successful result to return data in this validator's `validatorOutputs` entry. */
885 createOutput: CreateOutputFn
886}
887β
888/**
889 * Errors for a form group, optionally including errors at group-relative field paths.
890 *
891 * @typeParam TGroupValue - Library-managed. Do not specify explicitly.
892 */
893export type FormGroupValidationError<TGroupValue> =
894 ValidationErrorInput | ValidationErrorMap<TGroupValue>
895/**
896 * A form group validator's success result, output data, or validation errors.
897 *
898 * @typeParam TGroupValue - Library-managed. Do not specify explicitly.
899 */
900export type FormGroupValidateResult<TGroupValue> =
901 SuccessfulValidationResult | FormGroupValidationError<TGroupValue>
902β
903/**
904 * Validates a group's value and can return group errors, field errors, or output data.
905 *
906 * @typeParam TGroupValue - Library-managed. Do not specify explicitly.
907 */
908export type FormGroupValidatorFn<TGroupValue> = ValidatorFn<
909 FormGroupValidatorContext<TGroupValue>,
910 FormGroupValidateResult<TGroupValue>
911>
912β
913/**
914 * Configures validation of a form group's value.
915 *
916 * @typeParam TGroupValue - Library-managed. Do not specify explicitly.
917 */
918export interface FormGroupValidator<in out TGroupValue> extends Validator<
919 TGroupValue,
920 FormGroupValidatorFn<TGroupValue> | StandardSchemaV1<TGroupValue, any>,
921 TGroupValue,
922 ConfigurableValidationTrigger,
923 'group'
924> {}
925β
926/**
927 * Group validators in configuration order, which also determines their `validatorOutputs` indexes.
928 *
929 * @typeParam TGroupValue - Library-managed. Do not specify explicitly.
930 */
931export type FormGroupValidators<TGroupValue> = ReadonlyArray<
932 FormGroupValidator<TGroupValue>
933>
934β
935/**
936 * Values and helpers passed to a field validation function.
937 *
938 * @typeParam TFieldName - Library-managed. Do not specify explicitly.
939 * @typeParam TFieldValue - Library-managed. Do not specify explicitly.
940 * @typeParam TFormData - Library-managed. Do not specify explicitly.
941 */
942export interface FieldValidatorContext<
943 in out TFieldName,
944 in out TFieldValue,
945 in out TFormData,
946> {
947 /** The event that caused this validation run. */
948 event: ClientValidationTrigger
949 /** Aborted when this run is cancelled. Pass it to asynchronous work such as `fetch`. */
950 signal: AbortSignal
951 /** The owning form. Read other field values here for cross-field validation. */
952 formApi: FormApi<TFormData, any>
953 /** The field being validated, including when a watched field caused the event. */
954 fieldApi: FieldApi<TFieldName, TFieldValue, any, TFormData, any>
955 /** The current value of the field being validated. */
956 value: TFieldValue
957 /** Converts Standard Schema issues into errors for this field, without routing their paths. */
958 parseIssues: ParseFieldIssuesFn
959}
960β
961/** A field validator's success result or errors. Field validators do not provide output data. */
962export type FieldValidateResult = ValidationResult
963β
964/**
965 * Validates a field's value and reports errors owned by that field.
966 *
967 * @typeParam TFormData - Library-managed. Do not specify explicitly.
968 * @typeParam TFieldName - Library-managed. Do not specify explicitly.
969 * @typeParam TFieldValue - Library-managed. Do not specify explicitly.
970 */
971export type FieldValidatorFn<TFormData, TFieldName, TFieldValue> = ValidatorFn<
972 FieldValidatorContext<TFieldName, TFieldValue, TFormData>,
973 FieldValidateResult
974>
975β
976/**
977 * Configures validation of a field's value, optionally reacting to related fields.
978 *
979 * @typeParam TFormData - Library-managed. Do not specify explicitly.
980 * @typeParam TFieldName - Library-managed. Do not specify explicitly.
981 * @typeParam TFieldValue - Library-managed. Do not specify explicitly.
982 */
983export interface FieldValidator<
984 in out TFormData,
985 in out TFieldName,
986 in out TFieldValue,
987> extends Validator<
988 TFormData,
989 | FieldValidatorFn<TFormData, TFieldName, TFieldValue>
990 | StandardSchemaV1<TFieldValue, any>,
991 TFieldValue,
992 ConfigurableValidationTrigger,
993 'field'
994> {
995 /**
996 * Other field paths whose change or blur events can run this validator.
997 *
998 * Events must still match an enabled entry in `triggers`. The validator
999 * receives its own field's value, even when a watched field caused the event.
1000 */
1001 watchFields?: Array<DeepKeys<TFormData>>
1002}
1003β
1004/**
1005 * Field validators in configuration order.
1006 *
1007 * @typeParam TFormData - Library-managed. Do not specify explicitly.
1008 * @typeParam TFieldName - Library-managed. Do not specify explicitly.
1009 * @typeParam TFieldValue - Library-managed. Do not specify explicitly.
1010 */
1011export type FieldValidators<TFormData, TFieldName, TFieldValue> = ReadonlyArray<
1012 FieldValidator<TFormData, TFieldName, TFieldValue>
1013>
1014β
1015type NormalizeValidationResult<TResult> = NormalizeValidationError<
1016 Exclude<TResult, SuccessfulValidationResult>
1017>
1018β
1019type NormalizeValidationError<TError> =
1020 TError extends ReadonlyArray<infer TItem>
1021 ? NormalizeValidationError<TItem>
1022 : TError extends string
1023 ? ValidationIssue
1024 : TError extends ValidationIssue
1025 ? TError
1026 : ValidationIssue
1027β
1028type ValidationErrorTarget = 'form' | 'field'
1029β
1030type ExtractErrorMap<
1031 TResult,
1032 TTarget extends ValidationErrorTarget,
1033> = TResult extends ValidationIssue
1034 ? NormalizeValidationResult<TResult>
1035 : TResult extends ValidationErrorMap<any>
1036 ? TTarget extends 'form'
1037 ? TResult extends { form?: infer TError }
1038 ? NormalizeValidationResult<TError>
1039 : never
1040 : TResult extends { fields: infer TFields }
1041 ? NormalizeValidationResult<TFields[keyof TFields]>
1042 : never
1043 : NormalizeValidationResult<TResult>
1044β
1045/**
1046 * Inferred issue types for errors owned by a form or group and errors routed to its fields.
1047 *
1048 * @typeParam TFormError - Library-managed. Do not specify explicitly.
1049 * @typeParam TFieldError - Library-managed. Do not specify explicitly.
1050 */
1051export interface FormErrorTypes<
1052 out TFormError = ValidationIssue,
1053 out TFieldError = ValidationIssue,
1054> {
1055 /** The issue type stored in the form or group's `state.errors`. */
1056 readonly formError: TFormError
1057 /** The issue type routed from form or group validation to individual fields. */
1058 readonly fieldError: TFieldError
1059}
1060β
1061type ExtractSubmitValidationError<TSubmitReturn> =
1062 Awaited<TSubmitReturn> extends infer TResolved
1063 ? TResolved extends OnSubmitError<infer TError>
1064 ? TError
1065 : never
1066 : never
1067β
1068type ParseSubmitFormError<TSubmitReturn> = ExtractErrorMap<
1069 ExtractSubmitValidationError<TSubmitReturn>,
1070 'form'
1071>
1072β
1073type ParseSubmitFieldError<TSubmitReturn> = ExtractErrorMap<
1074 ExtractSubmitValidationError<TSubmitReturn>,
1075 'field'
1076>
1077β
1078type ExtractSubmitFormError<TSubmitReturn> = unknown extends TSubmitReturn
1079 ? ValidationIssue
1080 : ParseSubmitFormError<TSubmitReturn>
1081β
1082type ExtractSubmitFieldError<TSubmitReturn> = unknown extends TSubmitReturn
1083 ? ValidationIssue
1084 : ParseSubmitFieldError<TSubmitReturn>
1085β
1086type ExtractFormError<TFormErrorTypes extends FormErrorTypes> =
1087 unknown extends TFormErrorTypes['formError']
1088 ? ValidationIssue
1089 : TFormErrorTypes['formError']
1090β
1091type ExtractFormFieldError<TFormErrorTypes extends FormErrorTypes> =
1092 unknown extends TFormErrorTypes['fieldError']
1093 ? never
1094 : TFormErrorTypes['fieldError']
1095β
1096/**
1097 * The form or group's error array, with string messages normalized to issue objects.
1098 *
1099 * @typeParam TFormErrorTypes - Library-managed. Do not specify explicitly.
1100 */
1101export type FormErrors<TFormErrorTypes extends FormErrorTypes> = Array<
1102 ExtractFormError<TFormErrorTypes>
1103>
1104β
1105/**
1106 * A field's error array, with string messages normalized to issue objects.
1107 *
1108 * @typeParam TFieldError - Library-managed. Do not specify explicitly.
1109 */
1110export type FieldErrors<TFieldError> = Array<
1111 unknown extends TFieldError ? ValidationIssue : TFieldError
1112>
1113β
1114type ValidationErrorValueFromType<TError> = unknown extends TError
1115 ? ValidationErrorValue
1116 : | Extract<TError, ValidationIssue>
1117 | (ValidationIssue extends TError ? string : never)
1118β
1119type ValidationErrorInputFromType<TError> = [TError] extends [never]
1120 ? never
1121 : OneOrMany<ValidationErrorValueFromType<TError>>
1122β
1123/**
1124 * Form validation results constrained to inferred issue types, as stored in server form state.
1125 *
1126 * @typeParam TFormData - Library-managed. Do not specify explicitly.
1127 * @typeParam TFormErrorTypes - Library-managed. Do not specify explicitly.
1128 */
1129export type FormValidateResultFromErrorTypes<
1130 TFormData,
1131 TFormErrorTypes extends FormErrorTypes,
1132> =
1133 | ValidValidationResult
1134 | ValidationErrorInputFromType<TFormErrorTypes['formError']>
1135 | {
1136 form?: ValidationErrorInputFromType<TFormErrorTypes['formError']>
1137 fields: Partial<
1138 Record<
1139 DeepKeys<TFormData>,
1140 ValidationErrorInputFromType<TFormErrorTypes['fieldError']>
1141 >
1142 >
1143 }
1144β
1145// Scalars and branded returns share the runtime success classification. Error
1146// collections additionally allow success when they contain no stored errors.
1147type SuccessWithoutOutput<TResult> =
1148 TResult extends SuccessfulValidationResult | void
1149 ? TResult extends ValidationOutput<unknown>
1150 ? never
1151 : undefined
1152 : TResult extends ReadonlyArray<unknown>
1153 ? [] extends TResult
1154 ? undefined
1155 : never
1156 : TResult extends ValidationIssue
1157 ? never
1158 : TResult extends ValidationErrorMap<any>
1159 ? TResult extends { form: infer TForm }
1160 ? [SuccessWithoutOutput<TForm>] extends [never]
1161 ? never
1162 : ErrorMapSuccess<TResult['fields']>
1163 : ErrorMapSuccess<TResult['fields']>
1164 : never
1165β
1166type RequiredErrorKeys<TFields> = {
1167 [K in keyof TFields]-?: {} extends Pick<TFields, K>
1168 ? never
1169 : [SuccessWithoutOutput<TFields[K]>] extends [never]
1170 ? K
1171 : never
1172}[keyof TFields]
1173β
1174type ErrorMapSuccess<TFields> = [RequiredErrorKeys<TFields>] extends [never]
1175 ? undefined
1176 : never
1177β
1178type OutputFromReturn<TReturn> = unknown extends TReturn
1179 ? unknown
1180 : [Extract<TReturn, ValidationOutput<unknown>>] extends [never]
1181 ? undefined
1182 : | (TReturn extends ValidationOutput<infer TOutput> ? TOutput : never)
1183 | SuccessWithoutOutput<TReturn>
1184β
1185type TryGetOutput<TValidator> = TValidator extends {
1186 readonly run: StandardSchemaV1<any, infer TOutput>
1187}
1188 ? TOutput
1189 : TValidator extends { readonly run: (...args: any) => infer TReturn }
1190 ? OutputFromReturn<Awaited<TReturn>>
1191 : undefined
1192β
1193type TryGetSubmitOutput<TValidator> =
1194 TryGetOutput<TValidator> extends infer TOutput
1195 ? TValidator extends { readonly skipOnSubmit: infer TSkipOnSubmit }
1196 ? [TSkipOnSubmit] extends [true]
1197 ? undefined // User explicitly set skipOnSubmit: false -> guaranteed undefined
1198 : TSkipOnSubmit extends (...args: Array<any>) => boolean
1199 ? TOutput | undefined // Callback could dynamically be true or false -> union
1200 : true extends TSkipOnSubmit
1201 ? TOutput | undefined // the explicit variable is boolean, so also dynamic -> union
1202 : TOutput
1203 : TOutput // default, which is guaranteed present
1204 : never
1205β
1206type ValidatorTriggers<TValidator> = TValidator extends {
1207 readonly triggers: infer TTriggers
1208}
1209 ? TTriggers extends ReadonlyArray<unknown>
1210 ? TTriggers[number]
1211 : never
1212 : never
1213β
1214type HasServerTrigger<TValidator> =
1215 ServerValidationTrigger extends ValidatorTriggers<TValidator> ? true : false
1216β
1217type TryGetFormError<TValidator> = TValidator extends {
1218 readonly run: StandardSchemaV1<any, any>
1219}
1220 ? StandardSchemaV1Issue
1221 : TValidator extends { readonly run: (...args: any) => infer TReturn }
1222 ? ExtractErrorMap<Awaited<TReturn>, 'form'>
1223 : never
1224β
1225type TryGetFieldError<TValidator> = TValidator extends {
1226 readonly run: StandardSchemaV1<any, any>
1227}
1228 ? StandardSchemaV1Issue
1229 : TValidator extends { readonly run: (...args: any) => infer TReturn }
1230 ? ExtractErrorMap<Awaited<TReturn>, 'field'>
1231 : never
1232β
1233type MappedOutputs<in out TValidators extends ReadonlyArray<unknown>> = {
1234 [K in keyof TValidators]: TValidators[K] extends {
1235 readonly run: any
1236 }
1237 ? TryGetSubmitOutput<TValidators[K]>
1238 : never
1239}
1240β
1241type ToOutputs<
1242 TValidators extends ReadonlyArray<unknown>,
1243 TBroadValidators extends ReadonlyArray<unknown>,
1244> = unknown extends TValidators
1245 ? Array<unknown>
1246 : TBroadValidators extends TValidators
1247 ? Array<unknown>
1248 : MappedOutputs<TValidators>
1249β
1250/**
1251 * Infers submission output slots from form validators in configuration order.
1252 *
1253 * Slots contain Standard Schema outputs or payloads returned through `createOutput`.
1254 * Validators disabled for submission have `undefined` slots. Conditional
1255 * submission or success without output can also make a slot `undefined`.
1256 *
1257 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
1258 */
1259export type ToFormOutputs<TFormValidators extends FormValidators<any>> =
1260 ToOutputs<TFormValidators, FormValidators<any>>
1261β
1262/**
1263 * Infers submission output slots from group validators in configuration order.
1264 *
1265 * Slots contain Standard Schema outputs or payloads returned through `createOutput`.
1266 * Validators disabled for submission have `undefined` slots. Conditional
1267 * submission or success without output can also make a slot `undefined`.
1268 *
1269 * @typeParam TGroupValidators - Library-managed. Do not specify explicitly.
1270 */
1271export type ToFormGroupOutputs<
1272 TGroupValidators extends FormGroupValidators<any>,
1273> = ToOutputs<TGroupValidators, FormGroupValidators<any>>
1274β
1275type ExtractValidatorFormError<
1276 TValidators extends ReadonlyArray<unknown>,
1277 TBroadValidators extends ReadonlyArray<unknown>,
1278> = unknown extends TValidators
1279 ? never
1280 : TBroadValidators extends TValidators
1281 ? never
1282 : TryGetFormError<TValidators[number]>
1283β
1284type ExtractValidatorFieldError<
1285 TValidators extends ReadonlyArray<unknown>,
1286 TBroadValidators extends ReadonlyArray<unknown>,
1287> = unknown extends TValidators
1288 ? never
1289 : TBroadValidators extends TValidators
1290 ? never
1291 : TryGetFieldError<TValidators[number]>
1292β
1293type ToValidatorErrorTypes<
1294 TValidators extends ReadonlyArray<unknown>,
1295 TBroadValidators extends ReadonlyArray<unknown>,
1296 TSubmitReturn,
1297> = FormErrorTypes<
1298 | ExtractValidatorFormError<TValidators, TBroadValidators>
1299 | ExtractSubmitFormError<TSubmitReturn>,
1300 | ExtractValidatorFieldError<TValidators, TBroadValidators>
1301 | ExtractSubmitFieldError<TSubmitReturn>
1302>
1303β
1304/**
1305 * Infers form and routed field issue types from validators and submission validation errors.
1306 *
1307 * String errors become `ValidationIssue` objects. Successful output payloads
1308 * are excluded from error types.
1309 *
1310 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
1311 * @typeParam TSubmitReturn - Library-managed. Do not specify explicitly.
1312 */
1313export type ToFormErrorTypes<
1314 TFormValidators extends FormValidators<any>,
1315 TSubmitReturn,
1316> = ToValidatorErrorTypes<TFormValidators, FormValidators<any>, TSubmitReturn>
1317β
1318/**
1319 * Infers group and routed field issue types from group validators.
1320 *
1321 * @typeParam TGroupValidators - Library-managed. Do not specify explicitly.
1322 */
1323export type ToFormGroupErrorTypes<
1324 TGroupValidators extends FormGroupValidators<any>,
1325> = ToValidatorErrorTypes<TGroupValidators, FormGroupValidators<any>, never>
1326β
1327type FallbackToValidationIssue<TFieldError> = [TFieldError] extends [never]
1328 ? ValidationIssue
1329 : TFieldError
1330β
1331/**
1332 * Combines a field's own issue types with errors routed from its group and form.
1333 *
1334 * Falls back to `ValidationIssue` when no specific error type is inferred.
1335 *
1336 * @typeParam TFieldValidators - Library-managed. Do not specify explicitly.
1337 * @typeParam TGroupFieldError - Library-managed. Do not specify explicitly.
1338 * @typeParam TFormErrorTypes - Library-managed. Do not specify explicitly.
1339 */
1340export type ToFieldError<
1341 TFieldValidators extends FieldValidators<any, any, any>,
1342 TGroupFieldError,
1343 TFormErrorTypes extends FormErrorTypes,
1344> = FallbackToValidationIssue<
1345 | ExtractValidatorFieldError<TFieldValidators, FieldValidators<any, any, any>>
1346 | (unknown extends TGroupFieldError ? never : TGroupFieldError)
1347 | ExtractFormFieldError<TFormErrorTypes>
1348>
1349β
1350type MappedServerFormValidators<
1351 in out TFormValidators extends FormValidators<any>,
1352> = {
1353 [K in keyof TFormValidators]: HasServerTrigger<
1354 TFormValidators[K]
1355 > extends true
1356 ? TFormValidators[K]
1357 : never
1358}
1359β
1360/**
1361 * Infers form and field issue types from validators with a `'server'` trigger.
1362 *
1363 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
1364 */
1365export type ToServerFormErrorTypes<
1366 TFormValidators extends FormValidators<any>,
1367> = unknown extends TFormValidators
1368 ? FormErrorTypes
1369 : FormValidators<any> extends TFormValidators
1370 ? FormErrorTypes
1371 : ToFormErrorTypes<MappedServerFormValidators<TFormValidators>, never>
1372β
1373type MappedServerOutputs<in out TFormValidators extends FormValidators<any>> = {
1374 [K in keyof TFormValidators]: HasServerTrigger<
1375 TFormValidators[K]
1376 > extends true
1377 ? TryGetOutput<TFormValidators[K]>
1378 : undefined
1379}
1380β
1381/**
1382 * Infers server validation output slots in form validator configuration order.
1383 *
1384 * Validators without a `'server'` trigger have `undefined` slots. Server
1385 * selection is independent of `skipOnSubmit`.
1386 *
1387 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
1388 */
1389export type ToServerFormOutputs<TFormValidators extends FormValidators<any>> =
1390 unknown extends TFormValidators
1391 ? Array<unknown>
1392 : FormValidators<any> extends TFormValidators
1393 ? Array<unknown>
1394 : MappedServerOutputs<TFormValidators>