Open History to see the last commit
1import { createOutput } from '../validationOutput.lib'
2import { createErrorMap } from '../validation.public'
3import {
4 isStandardSchema,
5 parseStandardSchema,
6 parseStandardSchemaIssues,
7} from '../standardSchema.lib'
8import { isPromiseLike } from '../utils.lib'
9import { isErrorResult } from './errors.lib'
10import {
11 createValidatorAbortContext,
12 normalizeValidatorResult,
13 parseFieldIssues,
14} from './execution.lib'
15import type { AnyInternalValidatorInstance } from '../ValidatorInstance.lib'
16import type { InternalFormApi } from '../FormApi/FormApi.lib'
17import type { AnyInternalFieldApi } from '../FieldApi/FieldApi.lib'
18import type { AnyInternalFormGroupApi } from '../FormGroupApi/FormGroupApi.lib'
19import type {
20 FieldValidateResult,
21 FormGroupValidateResult,
22 FormValidateResult,
23} from '../validation.public'
24import type {
25 AnyValidatorContext,
26 ValidateResult,
27 ValidatorExecutionResult,
28} from './execution.lib'
29import type { PipelineResult } from './pipeline.lib'
30β
31interface FormMountValidatorPipelineArgs {
32 pipeline: ReadonlyArray<AnyInternalValidatorInstance>
33 formApi: InternalFormApi<any, any, any>
34 onResult?: (result: PipelineResult<FormValidateResult<any>>) => void
35}
36β
37export interface FormMountValidatorPipelineResult {
38 didRun: boolean
39 asyncPromise: Promise<void> | null
40}
41β
42interface MountValidatorPipelineArgs<in out TResult extends ValidateResult> {
43 pipeline: ReadonlyArray<AnyInternalValidatorInstance>
44 getContext: (signal: AbortSignal) => AnyValidatorContext
45 scope: 'field' | 'form'
46 onResult?: (result: PipelineResult<TResult>) => void
47}
48β
49/**
50 * Creates the neutral result used when mount validation is aborted or throws.
51 */
52function createEmptyMountValidationResult<
53 TResult extends ValidateResult,
54>(): ValidatorExecutionResult<TResult> {
55 return normalizeValidatorResult(null as TResult)
56}
57β
58/**
59 * Publishes one mount execution result and reports whether it contains errors.
60 *
61 * Mount outputs remain on the immediate result and are not persisted on
62 * the validator instance.
63 */
64function processMountValidationExecutionResult<TResult extends ValidateResult>(
65 validatorInstance: AnyInternalValidatorInstance,
66 executionResult: ValidatorExecutionResult<TResult>,
67 onResult?: (result: PipelineResult<TResult>) => void,
68): boolean {
69 const result: PipelineResult<TResult> = {
70 validatorInstance,
71 result: executionResult.result,
72 output: executionResult.output,
73 hasOutput: executionResult.hasOutput,
74 }
75β
76 onResult?.(result)
77β
78 return isErrorResult(executionResult.result)
79}
80β
81/**
82 * Executes one mount validator immediately without trigger debounce.
83 *
84 * Aborted async results and thrown validators become neutral mount results;
85 * thrown errors are logged after execution resources are released.
86 */
87function executeMountValidator<TResult extends ValidateResult>(
88 getContext: MountValidatorPipelineArgs<TResult>['getContext'],
89 scope: 'field' | 'form',
90 validatorInstance: AnyInternalValidatorInstance,
91):
92 | ValidatorExecutionResult<TResult>
93 | PromiseLike<ValidatorExecutionResult<TResult>> {
94 const validator = validatorInstance.definition
95 const { signal, cleanup } = createValidatorAbortContext(validatorInstance, {
96 cancelDebouncer: true,
97 })
98β
99 const context = getContext(signal)
100β
101 try {
102 if (isStandardSchema(validator.run)) {
103 return parseStandardSchema(validator.run, context.value, scope)
104 .then((result) => {
105 if (signal.aborted) {
106 return createEmptyMountValidationResult<TResult>()
107 }
108β
109 return normalizeValidatorResult(result as TResult)
110 })
111 .catch((error) => {
112 console.error(error)
113 return createEmptyMountValidationResult<TResult>()
114 })
115 .finally(cleanup)
116 }
117β
118 const result = validator.run(context)
119β
120 if (isPromiseLike(result)) {
121 return Promise.resolve(result)
122 .then((asyncResult): ValidatorExecutionResult<TResult> => {
123 if (signal.aborted) {
124 return createEmptyMountValidationResult<TResult>()
125 }
126β
127 return normalizeValidatorResult(asyncResult as TResult)
128 })
129 .catch((error) => {
130 console.error(error)
131 return createEmptyMountValidationResult<TResult>()
132 })
133 .finally(cleanup)
134 }
135β
136 cleanup()
137 return normalizeValidatorResult(result as TResult)
138 } catch (error) {
139 cleanup()
140 console.error(error)
141 return createEmptyMountValidationResult<TResult>()
142 }
143}
144β
145/**
146 * Continues mount validation sequentially after the first asynchronous result.
147 *
148 * Later validators still honor `runOnMount` and `bailIfInvalid` in configured
149 * order.
150 */
151async function continueMountValidationFromAsyncResult<
152 TResult extends ValidateResult,
153>(
154 pipeline: ReadonlyArray<AnyInternalValidatorInstance>,
155 getContext: MountValidatorPipelineArgs<TResult>['getContext'],
156 scope: 'field' | 'form',
157 startIndex: number,
158 firstResult: PromiseLike<ValidatorExecutionResult<TResult>>,
159 hasFailedBefore: boolean,
160 onResult?: (result: PipelineResult<TResult>) => void,
161): Promise<void> {
162 let hasFailed = hasFailedBefore
163β
164 const firstExecutionResult = await firstResult
165 if (
166 processMountValidationExecutionResult(
167 pipeline[startIndex]!,
168 firstExecutionResult,
169 onResult,
170 )
171 ) {
172 hasFailed = true
173 }
174β
175 for (let i = startIndex + 1; i < pipeline.length; i++) {
176 const validatorInstance = pipeline[i]!
177 const validator = validatorInstance.definition
178 if (validator.runOnMount !== true) continue
179β
180 if (validator.bailIfInvalid && hasFailed) break
181β
182 const result = executeMountValidator<TResult>(
183 getContext,
184 scope,
185 validatorInstance,
186 )
187 const executionResult = isPromiseLike(result) ? await result : result
188β
189 if (
190 processMountValidationExecutionResult(
191 validatorInstance,
192 executionResult,
193 onResult,
194 )
195 ) {
196 hasFailed = true
197 }
198 }
199}
200β
201/**
202 * Starts all eligible synchronous mount work and exposes async continuation.
203 *
204 * The pipeline returns synchronously until it encounters its first promise;
205 * remaining eligible validators then continue through `asyncPromise`.
206 */
207function runMountValidatorPipeline<TResult extends ValidateResult>({
208 pipeline,
209 getContext,
210 scope,
211 onResult,
212}: MountValidatorPipelineArgs<TResult>): FormMountValidatorPipelineResult {
213 if (pipeline.length === 0)
214 return {
215 didRun: false,
216 asyncPromise: null,
217 }
218β
219 if (
220 !pipeline.some(
221 (validatorInstance) => validatorInstance.definition.runOnMount === true,
222 )
223 )
224 return {
225 didRun: false,
226 asyncPromise: null,
227 }
228β
229 let hasFailed = false
230β
231 for (let i = 0; i < pipeline.length; i++) {
232 const validatorInstance = pipeline[i]!
233 const validator = validatorInstance.definition
234 if (validator.runOnMount !== true) continue
235β
236 if (validator.bailIfInvalid && hasFailed) {
237 return {
238 didRun: true,
239 asyncPromise: null,
240 }
241 }
242β
243 const result = executeMountValidator<TResult>(
244 getContext,
245 scope,
246 validatorInstance,
247 )
248β
249 if (isPromiseLike(result)) {
250 return {
251 didRun: true,
252 asyncPromise: continueMountValidationFromAsyncResult(
253 pipeline,
254 getContext,
255 scope,
256 i,
257 result,
258 hasFailed,
259 onResult,
260 ),
261 }
262 }
263β
264 if (
265 processMountValidationExecutionResult(validatorInstance, result, onResult)
266 ) {
267 hasFailed = true
268 }
269 }
270β
271 return {
272 didRun: true,
273 asyncPromise: null,
274 }
275}
276β
277/** Runs mount validation with form-scoped values and routed issue parsing. */
278export function runFormMountValidatorPipeline({
279 pipeline,
280 formApi,
281 onResult,
282}: FormMountValidatorPipelineArgs): FormMountValidatorPipelineResult {
283 return runMountValidatorPipeline<FormValidateResult<any>>({
284 pipeline,
285 getContext: (signal) => ({
286 event: 'mount' as never,
287 signal,
288 formApi,
289 value: formApi.state.values,
290 createErrorMap,
291 createOutput,
292 parseIssues: (issues) =>
293 parseStandardSchemaIssues(issues, formApi.state.values, 'form'),
294 }),
295 scope: 'form',
296 onResult,
297 })
298}
299β
300interface FieldMountValidatorPipelineArgs {
301 pipeline: ReadonlyArray<AnyInternalValidatorInstance>
302 fieldApi: AnyInternalFieldApi
303 onResult?: (result: PipelineResult<FieldValidateResult>) => void
304}
305β
306/** Runs mount validation with the field's current value and issue parser. */
307export function runFieldMountValidatorPipeline({
308 pipeline,
309 fieldApi,
310 onResult,
311}: FieldMountValidatorPipelineArgs): FormMountValidatorPipelineResult {
312 return runMountValidatorPipeline<FieldValidateResult>({
313 pipeline,
314 getContext: (signal) => ({
315 event: 'mount' as never,
316 signal,
317 formApi: fieldApi.form as never,
318 fieldApi: fieldApi as never,
319 value: fieldApi.value,
320 parseIssues: parseFieldIssues,
321 }),
322 scope: 'field',
323 onResult,
324 })
325}
326β
327// ===== GROUP MOUNT VALIDATION =====
328β
329interface GroupMountValidatorPipelineArgs {
330 pipeline: ReadonlyArray<AnyInternalValidatorInstance>
331 groupApi: AnyInternalFormGroupApi
332 onResult?: (result: PipelineResult<FormGroupValidateResult<any>>) => void
333}
334β
335/** Runs mount validation with group-scoped values and routed issue parsing. */
336export function runGroupMountValidatorPipeline({
337 pipeline,
338 groupApi,
339 onResult,
340}: GroupMountValidatorPipelineArgs): FormMountValidatorPipelineResult {
341 return runMountValidatorPipeline<FormGroupValidateResult<any>>({
342 pipeline,
343 getContext: (signal) => ({
344 event: 'mount' as never,
345 signal,
346 formApi: groupApi.form as never,
347 groupApi: groupApi as never,
348 triggerFieldApi: undefined,
349 value: groupApi.value,
350 createErrorMap,
351 createOutput,
352 parseIssues: (issues) =>
353 parseStandardSchemaIssues(issues, groupApi.value, 'form'),
354 }),
355 scope: 'form',
356 onResult,
357 })
358}