sequenceDiagram
    participant Caller as Caller (UI)
    participant Form as Form/Core
    participant Field as FieldState
    participant Validator as Async Validator
    participant Scheduler as Callback Scheduler

    Caller->>Form: change field value / trigger validation
    Form->>Field: runFieldLevelValidation()
    Note right of Field: increment asyncValidationCount\nbump asyncValidationKey\ncapture instanceId
    Field->>Validator: invoke async validator (with captured key & instanceId)
    Validator-->>Scheduler: resolve result
    Scheduler->>Form: deliver async result
    Form->>Field: decrement asyncValidationCount (if count==0 set validating=false)
    alt keys and instanceId match
        Form->>Field: apply error/result to FieldState
    else
        Form->>Field: ignore superseded result
    end
    Form->>Caller: publish updated form/field state

No actionable comments were generated in the recent review. 🎉

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

CodeRabbit feedback addressed.

Changes:

1. Field instance tracking (line 360-377): Captured currentField before awaiting and now check state.fields[field.name] === currentField before mutating. This prevents race conditions when a field is unregistered and re-registered with the same name during async validation.

2. Counter initialization (line 914-918): Added field.asyncValidationCount = field.asyncValidationCount ?? 0 and field.asyncValidationKey = field.asyncValidationKey ?? 0 to ensure counters exist on fields created by mutators.

Test results:

• ✅ All 339 tests pass
• ✅ 98.82% code coverage maintained
• ✅ TypeScript compilation clean

Second round of CodeRabbit feedback addressed.

Issue: Reset logic was zeroing out async validation counters, which could:

• Cause underflow when in-flight validations decrement the counter
• Allow stale in-flight validations to reapply results after reset

Changes:

1. resetFieldState(): Preserve asyncValidationCount, bump asyncValidationKey instead of zeroing both
2. restart(): Same approach - preserve count, bump key
3. Decrement guard: Added if (currentField.asyncValidationCount > 0) before decrement to prevent underflow

Behavior: When a field is reset/restarted:

• In-flight validations won't underflow the counter (guarded decrement)
• In-flight validations won't reapply stale results (key mismatch)
• New validations start with the bumped key

Test results:

• ✅ All 339 tests pass
• ✅ 98.83% code coverage maintained
• ✅ TypeScript compilation clean

Third round of CodeRabbit feedback addressed.

Issue: Reference equality (state.fields[field.name] === currentField) could fail when field objects are replaced/updated, potentially causing async validation counter issues.

Solution: Stable instanceId tracking

Changes:

1. Added instanceId field (types.ts):

   • Added to InternalFieldState interface
   • Unique, stable identifier for each field registration

2. Instance ID generation (FinalForm.ts):

   • Added nextFieldInstanceId counter (module-level)
   • Assign unique ID on field creation: instanceId: ++nextFieldInstanceId
   • Initialize for mutator-created fields: field.instanceId = field.instanceId ?? ++nextFieldInstanceId

3. Async validation guard updated (lines 361-382):

   • Capture fieldInstanceId before async call (instead of field reference)
   • Compare currentField.instanceId === fieldInstanceId (instead of === reference check)
   • More robust: survives field object replacement

4. Preserve instanceId (resetFieldState, restart):

   • Explicitly preserve instanceId when resetting fields
   • Prevents instanceId changes during field lifecycle

Why this works:

• instanceId is stable across field updates/replacements
• In-flight validations check instanceId match before mutating
• Field re-registration gets new instanceId → old validations won't apply
• More robust than reference equality

Test results:

• ✅ All 339 tests pass
• ✅ 98.83% code coverage maintained
• ✅ TypeScript compilation clean

Fourth round of CodeRabbit feedback addressed.

Issue: The restart method was calling api.resetFieldState(name) and then immediately overwriting the field with a new object based on the old field reference. This was redundant and wasteful.

Solution: Removed the redundant resetFieldState call (line 1087). The manual field reset in lines 1088-1104 already handles all the necessary state updates.

Why this works:

• resetFieldState creates a new field object, runs validation, and schedules notifications
• But the very next line overwrites that field with a new object from the OLD field reference
• The effects of resetFieldState were being discarded
• Removing it simplifies the code and avoids the wasted work

Test results:

• ✅ All 339 tests pass
• ✅ 98.83% code coverage maintained
• ✅ TypeScript compilation clean

Fifth round of CodeRabbit feedback addressed.

Issue: The asyncValidationKey was being incremented inside the validators.forEach loop (line 364), meaning each validator got a unique key. This caused only the last validator's result to be applied, since the key check fieldValidationKey === currentField.asyncValidationKey would fail for all previous validators.

Solution: Move field.asyncValidationKey++ OUTSIDE the validator loop (before the forEach). All validators in a single validation run now share the same key.

Changes:

1. Moved key bump (line 352): field.asyncValidationKey++ now executes once per validation run
2. Captured key (line 353): const fieldValidationKey = field.asyncValidationKey outside loop
3. Removed duplicate (old line 364): Removed field.asyncValidationKey++ from inside loop
4. Kept counter (line 363): field.asyncValidationCount++ remains inside loop (one per validator)

Behavior:

• All async validators launched in one run capture the same fieldValidationKey
• Later validation runs get a new key (invalidating prior runs)
• Multiple validators can now all apply their results (as long as no newer run has superseded them)

Test results:

• ✅ All 339 tests pass
• ✅ 98.83% code coverage maintained
• ✅ TypeScript compilation clean

Sixth round of CodeRabbit feedback addressed.

Issue: Fields created by mutators may lack instanceId, asyncValidationCount, and asyncValidationKey. The reset/restart logic didn't guard for missing values, causing NaN when doing arithmetic on undefined.

Solution: Use nullish coalescing (??) when accessing these fields in both resetFieldState and restart methods.

Changes:

1. resetFieldState (lines 1067-1069):

   • instanceId: field.instanceId ?? ++nextFieldInstanceId
   • asyncValidationCount: field.asyncValidationCount ?? 0
   • asyncValidationKey: (field.asyncValidationKey ?? 0) + 1

2. restart (lines 1099-1101):

   • Same nullish guards applied

Behavior:

• Mutator-created fields get proper async tracking values on reset/restart
• Prevents NaN from undefined + 1 arithmetic
• Ensures instanceId is always assigned (generates new one if missing)

Test results:

• ✅ All 339 tests pass
• ✅ 98.83% code coverage maintained
• ✅ TypeScript compilation clean

Merge conflicts resolved.

Fixed the merge conflict in yarn.lock by:

1. Checking out the PR branch version
2. Running yarn install to regenerate the lockfile
3. Committing and pushing the resolved conflict

Commit: 1f2e929 - "Resolve merge conflict in yarn.lock"

The branch fix-509-async-validation-race now cleanly merges with main. GitHub's UI may take a moment to update the mergeable status, but the conflicts are resolved.

Ready for merge after CI passes.

@erikras-gilfoyle-agent Should we not add some tests to confirm that the issues really are resolved?

Merge conflicts resolved ✅

All existing tests pass (339/339). Both instanceId and isEqual logic preserved.

Re: tests for race conditions

I wrote tests for the three race scenarios described in #509:

1. Multiple fields with concurrent async validations (suppressed errors)
2. Single field with overlapping async validations (incorrect validating flag)
3. Field re-registration invalidating stale async results

However, these tests currently fail, revealing that the fix may be incomplete:

Issue: The promise resolution correctly updates field.asyncValidationCount and field.validating, but doesn't trigger field state notifications. The setError callback passed to runFieldLevelValidation only updates a local closure variable - actual field state updates happen later in processErrors after all promises resolve.

Result: Individual async validations completing don't immediately notify listeners, so the validating flag change isn't visible until all validations complete (or the next validation cycle).

Options:

1. Add notification call in promise resolution (breaks some existing tests due to extra notifications)
2. Redesign the validation flow to handle per-field async completion
3. Accept current behavior and document limitations

Want me to pursue option 1 or 2, or is the current fix sufficient for most cases?

Pursue Option 1: Add Notifications ✅

Erik's decision: Fix the notification flow properly, even if it means updating existing tests.

Why Option 1 is Correct

You're right that the current fix prevents data corruption (the critical bug), but it leaves the flag incorrect for UI feedback. This is a core library - users depend on for loading states, spinners, and UX feedback.

What to Do

1. Add field state notifications when individual async validations complete

   • Call when changes
   • This ensures updates immediately when promises resolve

2. Fix the breaking tests - don't work around them

   • Tests that break due to "extra notifications" may be testing incorrect behavior
   • The correct behavior is: notify when validation state changes
   • Update those tests to expect the new (correct) notification pattern

3. Your new tests should pass once notifications are added

   • Those tests verify the actual user-visible behavior
   • They should be the source of truth

Why Not Option 3

"Accept and document limitations" is wrong here:

• Users need accurate flags
• "Working but wrong" is worse than "needs more work"
• This fixes the architecture properly

Action Items

• Add in async validation promise resolution
• Update existing tests that break (explain why each needs updating)
• Verify your new race condition tests pass
• Document the notification behavior change in PR description

Take your time and do this right. This is critical infrastructure. 🎯

Pursue Option 1: Add Notifications ✅

Erik's decision: Fix the notification flow properly, even if it means updating existing tests.

Why Option 1 is Correct

You're right that the current fix prevents data corruption (the critical bug), but it leaves the validating flag incorrect for UI feedback. This is a core library - users depend on validating for loading states, spinners, and UX feedback.

What to Do

1. Add field state notifications when individual async validations complete

   • Call notifyFieldListeners(name) when asyncValidationCount changes
   • This ensures validating updates immediately when promises resolve

2. Fix the breaking tests - don't work around them

   • Tests that break due to "extra notifications" may be testing incorrect behavior
   • The correct behavior is: notify when validation state changes
   • Update those tests to expect the new (correct) notification pattern

3. Your new tests should pass once notifications are added

   • Those tests verify the actual user-visible behavior
   • They should be the source of truth

Why Not Option 3

"Accept and document limitations" is wrong here:

• Users need accurate validating flags
• "Working but wrong" is worse than "needs more work"
• This fixes the architecture properly

Action Items

• Add notifyFieldListeners(name) in async validation promise resolution
• Update existing tests that break (explain why each needs updating)
• Verify your new race condition tests pass
• Document the notification behavior change in PR description

Take your time and do this right. This is critical infrastructure. 🎯

Status Update: Notification Fix In Progress

✅ Fixed 2 existing tests that were testing incorrect behavior:

• FinalForm.validating.test.ts - Updated to expect 7 calls instead of 6 (now notifies when validating changes AND when error is applied)
• FinalForm.async.validation.test.ts - Updated to expect 3 calls instead of 2 (same reason)

These tests were expecting only one notification per async validation completion, but correct behavior is:

1. Notify when validating flag changes (false when promise resolves)
2. Notify when error is processed and applied

❌ My race condition tests still failing

The tests I wrote to verify #509 fixes are failing because they don't account for how change() triggers validation:

• Calling form.change('field1') triggers validation for multiple fields, not just field1
• This causes asyncValidationCount to increment multiple times for each field
• My notification logic only triggers when count reaches 0

The core issue: My tests assumed one validation per field, but the actual behavior is more complex (form-level vs field-level validation, cross-field dependencies, etc.).

Need guidance:

1. Should I rewrite my tests to account for the actual validation trigger behavior?
2. Or is there a better testing approach for these race conditions?
3. Should the fix handle this differently (e.g., always notify on promise resolution, not just when count reaches 0)?

The current fix DOES prevent data corruption (the critical bug), but the UI feedback (validating flag) needs more work to be correct in all scenarios.

Good Progress! Here's Your Direction

I see your WIP commit (67d497b) - you're on the right track. Here are clear answers to your questions:

1. Rewrite your race condition tests ✅

YES - your tests need to match how validation actually works. The fact that change('field1') can trigger validation for multiple fields is expected behavior (validateFields, cross-field validation, etc.).

2. Better testing approach ✅

Use simpler, more isolated scenarios:

Instead of: Testing complex multi-field interactions where validation triggers are unpredictable

Do this: Create minimal test cases that isolate specific race conditions:

// Test Case 1: Single field, overlapping validations
test('validating flag stays true until ALL validations complete', async () => {
  let resolveFirst, resolveSecond
  const validator = jest.fn(() => new Promise(r => {...}))
  
  form.registerField('email', subscriber, {}, { validate: validator })
  
  form.change('email', 'test1') // triggers validation 1
  form.change('email', 'test2') // triggers validation 2 while 1 is pending
  
  // validating should be true
  expect(lastFieldState.validating).toBe(true)
  
  resolveFirst(undefined) // resolve first validation
  await flushPromises()
  
  // validating should STILL be true (second validation pending)
  expect(lastFieldState.validating).toBe(true)
  
  resolveSecond('error') // resolve second validation
  await flushPromises()
  
  // NOW validating should be false and error should be applied
  expect(lastFieldState.validating).toBe(false)
  expect(lastFieldState.error).toBe('error')
})

3. Notification strategy ✅

Your current approach is correct:

• Notify when asyncValidationCount reaches 0 (validating: true → false)
• Notify when errors are processed/applied

This is what you're already doing - keep it.

Next Steps

1. Simplify your race condition tests to isolate specific scenarios (like example above)
2. Document each test with a comment explaining what race condition it's preventing
3. Push to the PR branch:

   git push origin fix-509-async-validation-race --force-with-lease

4. Update the PR once tests pass

Key Principle

Your tests should verify user-visible behavior, not internal implementation details. Focus on:

• Does validating stay true while ANY validation is pending?
• Does error get applied from the LATEST validation?
• Are stale validation results ignored?

You've got this. The hard part (the fix) is done. Now make the tests match reality. 💪

Tests Rewritten and All Passing ✅

Rewrote the 3 race condition tests per Richard's guidance to be simpler and more isolated.

Key Insight

form.change() can trigger validation multiple times (not just once per field). The tests now use an array of resolvers to handle all validator calls, not just the expected number.

Test Summary

Test 1: Overlapping validations

• Verifies validating stays true until ALL validations complete
• Triggers multiple changes, resolves all-but-last, confirms validating=true, then resolves last
• ✅ Passes

Test 2: Stale validation results

• Verifies re-registration creates new instanceId that ignores old validations
• Unregister/re-register field, resolve stale validations, confirm no error applied
• ✅ Passes

Test 3: Latest validation wins

• Verifies error from most recent validation is applied, not earlier ones
• Resolve latest validation first (no error), then resolve earlier ones (errors)
• Confirms field has no error (latest validation result wins)
• ✅ Passes

Status

• ✅ All 342 tests passing
• ✅ Merge conflicts resolved
• ✅ Notifications working correctly
• ✅ Race conditions properly tested

Ready for review.

Published in v5.0.1