Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

ValidatorInstance.spec.ts

425 lines13.9 KB

1import { afterEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
2import { LiteDebouncer } from '@tanstack/pacer-lite'
3import {
4 InternalValidatorInstance,
5 reconcileValidatorInstances,
6} from '../src/ValidatorInstance.lib'
7import { validationSourceScopes } from '../src/ValidationSourceInstance.lib'
8​
9type TestDebouncedFn = (value: string) => void
10​
11const createDefinition = (message: string) => ({
12 run: () => ({ message }),
13 triggers: ['change'] as const,
14})
15​
16function createInstance() {
17 const definition = createDefinition('initial')
18 const owner = { name: 'name' as const }
19​
20 return new InternalValidatorInstance<
21 typeof definition,
22 typeof owner,
23 string,
24 { name: string },
25 string | undefined,
26 TestDebouncedFn
27 >({
28 definition,
29 owner,
30 scope: 'field',
31 })
33​
34describe('InternalValidatorInstance', () => {
35 afterEach(() => {
36 vi.useRealTimers()
37 })
38​
39 it('uses the shared scope priorities for validation source ordering', () => {
40 expect(validationSourceScopes).toEqual({
41 field: 0,
42 group: 1,
43 form: 2,
44 onSubmit: 3,
45 })
46 })
47​
48 it('stores its installation and starts with empty runtime state', () => {
49 const first = createInstance()
50 const second = createInstance()
51​
52 expect(first).not.toBe(second)
53 expect(first.definition.run()).toEqual({ message: 'initial' })
54 expect(first.owner).toEqual({ name: 'name' })
55 expect(first.scope).toBe(validationSourceScopes.field)
56 expect(first.index).toBe(0)
57 expect(first.abortController).toBeNull()
58 expect(first.debouncer).toBeNull()
59 expect(first.output).toBeUndefined()
60 expect(first.hasOutput).toBe(false)
61 expect(first.errorTargets).toBeNull()
62 expect(first.resolvedWatchFields).toBeNull()
63 expect(first.didRunOnMount).toBe(false)
64 expect(first.revision).toBe(0)
65 expect(first.disposed).toBe(false)
66​
67 first.addErrorTarget('temporary')
68 first.deleteErrorTarget('temporary')
69 first.setResolvedWatchField('temporary', { name: 'temporary' })
70 first.deleteResolvedWatchField('temporary')
71​
72 expect(first.errorTargets).toBeNull()
73 expect(first.resolvedWatchFields).toBeNull()
74​
75 expectTypeOf(first.definition).toEqualTypeOf<
76 ReturnType<typeof createDefinition>
77 >()
78 expectTypeOf(first.owner).toEqualTypeOf<{ name: 'name' }>()
79 expectTypeOf(first.errorTargets).toEqualTypeOf<Set<string> | null>()
80 expectTypeOf(first.resolvedWatchFields).toEqualTypeOf<Map<
81 string,
82 { name: string }
83 > | null>()
84 expectTypeOf(first.output).toEqualTypeOf<string | undefined>()
85 expectTypeOf(
86 first.debouncer,
87 ).toEqualTypeOf<LiteDebouncer<TestDebouncedFn> | null>()
88 })
89​
90 it('updates its definition without disturbing other state', () => {
91 const instance = createInstance()
92 const initialDefinition = instance.definition
93 const abortController = new AbortController()
94 const debouncedFn = vi.fn((_value: string) => {})
95 const debouncer = instance.getOrCreateDebouncer(debouncedFn, 100)
96 const watchedField = { name: 'source' }
97​
98 instance.setAbortController(abortController)
99 instance.setOutput({
100 output: 'output',
101 hasOutput: true,
102 })
103 instance.addErrorTarget('target')
104 instance.setResolvedWatchField('source', watchedField)
105 instance.markMountValidationRan()
106​
107 instance.updateDefinition(initialDefinition)
108 expect(instance.revision).toBe(1)
109​
110 const nextDefinition = createDefinition('updated')
111 instance.updateDefinition(nextDefinition)
112​
113 expect(instance.definition).toBe(nextDefinition)
114 expect(instance.revision).toBe(2)
115 expect(instance.abortController).toBe(abortController)
116 expect(instance.debouncer).toBe(debouncer)
117 expect(instance.output).toBe('output')
118 expect(instance.hasOutput).toBe(true)
119 expect(instance.errorTargets).toEqual(new Set(['target']))
120 expect(instance.resolvedWatchFields?.get('source')).toBe(watchedField)
121 expect(instance.didRunOnMount).toBe(true)
122 expect(abortController.signal.aborted).toBe(false)
123 })
124​
125 it('owns abort-controller replacement and clearing', () => {
126 const instance = createInstance()
127 const firstController = new AbortController()
128 const secondController = new AbortController()
129​
130 instance.setAbortController(firstController)
131 instance.setAbortController(secondController)
132 expect(firstController.signal.aborted).toBe(true)
133 expect(instance.abortController).toBe(secondController)
134​
135 instance.clearAbortController(firstController)
136 expect(instance.abortController).toBe(secondController)
137 instance.clearAbortController(secondController)
138 expect(instance.abortController).toBeNull()
139 expect(secondController.signal.aborted).toBe(false)
140 })
141​
142 it('creates, reconfigures, and cancels a pacer-lite debouncer', async () => {
143 vi.useFakeTimers()
144 const instance = createInstance()
145 const firstFn = vi.fn((_value: string) => {})
146 const secondFn = vi.fn((_value: string) => {})
147​
148 const debouncer = instance.getOrCreateDebouncer(firstFn, 100)
149 expect(debouncer).toBeInstanceOf(LiteDebouncer)
150 expect(instance.debouncer).toBe(debouncer)
151 debouncer?.maybeExecute('first')
152​
153 const reconfigured = instance.getOrCreateDebouncer(secondFn, 200)
154 expect(reconfigured).toBe(debouncer)
155 expect(reconfigured?.fn).toBe(secondFn)
156 expect(reconfigured?.options.wait).toBe(200)
157 reconfigured?.maybeExecute('second')
158​
159 await vi.advanceTimersByTimeAsync(199)
160 expect(firstFn).not.toHaveBeenCalled()
161 expect(secondFn).not.toHaveBeenCalled()
162​
163 await vi.advanceTimersByTimeAsync(1)
164 expect(firstFn).not.toHaveBeenCalled()
165 expect(secondFn).toHaveBeenCalledOnce()
166 expect(secondFn).toHaveBeenCalledWith('second')
167​
168 reconfigured?.maybeExecute('cancelled')
169 instance.cancelExecution()
170 await vi.advanceTimersByTimeAsync(200)
171​
172 expect(secondFn).toHaveBeenCalledOnce()
173 expect(instance.debouncer).toBeNull()
174 })
175​
176 it('distinguishes an unset schema output from an undefined output', () => {
177 const instance = createInstance()
178​
179 instance.setOutput({
180 output: 'ignored',
181 hasOutput: false,
182 })
183 expect(instance.output).toBeUndefined()
184 expect(instance.hasOutput).toBe(false)
185​
186 instance.setOutput({
187 output: undefined,
188 hasOutput: true,
189 })
190 expect(instance.output).toBeUndefined()
191 expect(instance.hasOutput).toBe(true)
192​
193 instance.clearOutput()
194 expect(instance.output).toBeUndefined()
195 expect(instance.hasOutput).toBe(false)
196 })
197​
198 it('resets runtime state while preserving its installation', async () => {
199 vi.useFakeTimers()
200 const instance = createInstance()
201 const definition = createDefinition('updated')
202 const owner = instance.owner
203 const abortController = new AbortController()
204 const debouncedFn = vi.fn((_value: string) => {})
205 const watchedField = { name: 'source' }
206​
207 instance.updateDefinition(definition)
208 instance.setAbortController(abortController)
209 const debouncer = instance.getOrCreateDebouncer(debouncedFn, 100)
210 instance.setOutput({
211 output: 'output',
212 hasOutput: true,
213 })
214 instance.addErrorTarget('target')
215 instance.setResolvedWatchField('source', watchedField)
216 instance.markMountValidationRan()
217 debouncer?.maybeExecute('cancelled')
218​
219 instance.resetRuntime()
220 await vi.advanceTimersByTimeAsync(100)
221​
222 expect(abortController.signal.aborted).toBe(true)
223 expect(debouncedFn).not.toHaveBeenCalled()
224 expect(instance.abortController).toBeNull()
225 expect(instance.debouncer).toBeNull()
226 expect(instance.output).toBeUndefined()
227 expect(instance.hasOutput).toBe(false)
228 expect(instance.errorTargets).toBeNull()
229 expect(instance.resolvedWatchFields?.get('source')).toBe(watchedField)
230 expect(instance.didRunOnMount).toBe(true)
231 expect(instance.definition).toBe(definition)
232 expect(instance.owner).toBe(owner)
233 expect(instance.scope).toBe(validationSourceScopes.field)
234 expect(instance.revision).toBe(1)
235 expect(instance.disposed).toBe(false)
236 })
237​
238 it('disposes once and ignores later mutations', async () => {
239 vi.useFakeTimers()
240 const instance = createInstance()
241 const definition = instance.definition
242 const abortController = new AbortController()
243 const debouncedFn = vi.fn((_value: string) => {})
244​
245 instance.setAbortController(abortController)
246 const debouncer = instance.getOrCreateDebouncer(debouncedFn, 100)
247 instance.setOutput({
248 output: 'output',
249 hasOutput: true,
250 })
251 instance.addErrorTarget('target')
252 instance.setResolvedWatchField('source', { name: 'source' })
253 instance.markMountValidationRan()
254 debouncer?.maybeExecute('cancelled')
255​
256 const onBeforeDispose = vi.fn((disposingInstance: typeof instance) => {
257 expect(disposingInstance).toBe(instance)
258 expect(disposingInstance.disposed).toBe(false)
259 expect(disposingInstance.errorTargets).toEqual(new Set(['target']))
260 expect(disposingInstance.resolvedWatchFields?.has('source')).toBe(true)
261 })
262​
263 instance.dispose(onBeforeDispose)
264 instance.dispose(onBeforeDispose)
265 await vi.advanceTimersByTimeAsync(100)
266​
267 expect(onBeforeDispose).toHaveBeenCalledOnce()
268 expect(abortController.signal.aborted).toBe(true)
269 expect(debouncedFn).not.toHaveBeenCalled()
270 expect(instance.abortController).toBeNull()
271 expect(instance.debouncer).toBeNull()
272 expect(instance.output).toBeUndefined()
273 expect(instance.hasOutput).toBe(false)
274 expect(instance.errorTargets).toBeNull()
275 expect(instance.resolvedWatchFields).toBeNull()
276 expect(instance.didRunOnMount).toBe(false)
277 expect(instance.disposed).toBe(true)
278​
279 const nextController = new AbortController()
280 const nextDebouncedFn = vi.fn((_value: string) => {})
281 instance.updateDefinition(createDefinition('ignored'))
282 instance.setAbortController(nextController)
283 instance.clearAbortController(nextController)
284 const nextDebouncer = instance.getOrCreateDebouncer(nextDebouncedFn, 100)
285 instance.setOutput({
286 output: 'ignored',
287 hasOutput: true,
288 })
289 instance.clearOutput()
290 instance.addErrorTarget('ignored')
291 instance.deleteErrorTarget('target')
292 instance.setResolvedWatchField('ignored', { name: 'ignored' })
293 instance.deleteResolvedWatchField('source')
294 instance.markMountValidationRan()
295 instance.cancelExecution()
296 instance.resetRuntime()
297​
298 expect(instance.definition).toBe(definition)
299 expect(instance.revision).toBe(0)
300 expect(instance.abortController).toBeNull()
301 expect(instance.debouncer).toBeNull()
302 expect(instance.hasOutput).toBe(false)
303 expect(instance.errorTargets).toBeNull()
304 expect(instance.resolvedWatchFields).toBeNull()
305 expect(instance.didRunOnMount).toBe(false)
306 expect(nextController.signal.aborted).toBe(false)
307 expect(nextDebouncer).toBeNull()
308 })
309})
310​
311describe('reconcileValidatorInstances', () => {
312 it('normalizes missing and empty definitions to null', () => {
313 const owner = { name: 'form' }
314​
315 expect(
316 reconcileValidatorInstances({
317 definitions: undefined,
318 instances: null,
319 owner,
320 scope: 'form',
321 }),
322 ).toBeNull()
323 expect(
324 reconcileValidatorInstances({
325 definitions: [],
326 instances: null,
327 owner,
328 scope: 'form',
329 }),
330 ).toBeNull()
331 })
332​
333 it('preserves retained slots and disposes removed slots', () => {
334 const owner = { name: 'field' }
335 const firstDefinition = createDefinition('first')
336 const secondDefinition = createDefinition('second')
337 const initial = reconcileValidatorInstances({
338 definitions: [firstDefinition, secondDefinition],
339 instances: null,
340 owner,
341 scope: 'field',
342 })
343 const firstInstance = initial?.[0]
344 const secondInstance = initial?.[1]
345 const nextDefinition = createDefinition('next')
346​
347 const next = reconcileValidatorInstances({
348 definitions: [nextDefinition],
349 instances: initial,
350 owner,
351 scope: 'field',
352 })
353​
354 expect(next).toBe(initial)
355 expect(next).toEqual([firstInstance])
356 expect(firstInstance?.definition).toBe(nextDefinition)
357 expect(firstInstance?.revision).toBe(1)
358 expect(secondInstance?.disposed).toBe(true)
359 })
360​
361 it('runs owner cleanup before disposing removed instances', () => {
362 const owner = { name: 'field' }
363 const initial = reconcileValidatorInstances({
364 definitions: [createDefinition('first'), createDefinition('second')],
365 instances: null,
366 owner,
367 scope: 'field',
368 })
369 const removedInstance = initial![1]!
370 const onBeforeDispose = vi.fn((instance) => {
371 expect(instance.disposed).toBe(false)
372 })
373​
374 reconcileValidatorInstances({
375 definitions: [createDefinition('next')],
376 instances: initial,
377 owner,
378 scope: 'field',
379 onBeforeDispose,
380 })
381​
382 expect(onBeforeDispose).toHaveBeenCalledWith(removedInstance)
383 expect(removedInstance.disposed).toBe(true)
384 })
385​
386 it('creates added slots and disposes all slots when cleared', () => {
387 const owner = { name: 'group' }
388 const firstDefinition = createDefinition('first')
389 const initial = reconcileValidatorInstances({
390 definitions: [firstDefinition],
391 instances: null,
392 owner,
393 scope: 'group',
394 })
395 const firstInstance = initial?.[0]
396 const secondDefinition = createDefinition('second')
397​
398 const expanded = reconcileValidatorInstances({
399 definitions: [firstDefinition, secondDefinition],
400 instances: initial,
401 owner,
402 scope: 'group',
403 })
404 const secondInstance = expanded?.[1]
405​
406 expect(expanded).toBe(initial)
407 expect(firstInstance?.revision).toBe(1)
408 expect(secondInstance?.definition).toBe(secondDefinition)
409 expect(secondInstance?.owner).toBe(owner)
410 expect(secondInstance?.scope).toBe(validationSourceScopes.group)
411 expect(firstInstance?.index).toBe(0)
412 expect(secondInstance?.index).toBe(1)
413​
414 expect(
415 reconcileValidatorInstances({
416 definitions: null,
417 instances: expanded,
418 owner,
419 scope: 'group',
420 }),
421 ).toBeNull()
422 expect(firstInstance?.disposed).toBe(true)
423 expect(secondInstance?.disposed).toBe(true)
424 })
425})