test(forms): cancel pending async validators on submission

Prevent a validation that is pending at the time of submission from
overriding submission errors when it resolves.

Author: leonsenft

packages/forms/signals/src/api/rules/validation/validate_async.ts

@@ -6,9 +6,9 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {ResourceRef, Signal} from '@angular/core';
+import {ResourceRef, Signal, WritableSignal, linkedSignal} from '@angular/core';
 import {FieldNode} from '../../../field/node';
-import {addDefaultField} from '../../../field/validation';
+import {PENDING_VALIDATION_PARAMS, addDefaultField} from '../../../field/validation';
 import {FieldPathNode} from '../../../schema/path_node';
 import {assertPathIsCurrent} from '../../../schema/schema';
 import {
@@ -117,6 +117,15 @@ export function validateAsync<TValue, TParams, TResult, TPathKind extends PathKi
   assertPathIsCurrent(path);
   const pathNode = FieldPathNode.unwrapFieldPath(path);
 
+  // Wrap the parameters in a linked signal so they can be overridden with `undefined` to cancel the
+  // validation on submission.
+  const PARAMS = createManagedMetadataKey<WritableSignal<TParams | undefined>, TParams>(
+    linkedSignal,
+  );
+  metadata(path, PARAMS, (ctx) => opts.params(ctx));
+  // Add the linked signal to the list of all pending validations.
+  metadata(path, PENDING_VALIDATION_PARAMS, (ctx) => ctx.state.metadata(PARAMS));
+
   const RESOURCE = createManagedMetadataKey<ReturnType<typeof opts.factory>, TParams | undefined>(
     opts.factory,
   );
@@ -126,7 +135,7 @@ export function validateAsync<TValue, TParams, TResult, TPathKind extends PathKi
     if (validationState.shouldSkipValidation() || !validationState.syncValid()) {
       return undefined;
     }
-    return opts.params(ctx);
+    return ctx.state.metadata(PARAMS)!();
   });
 
   pathNode.builder.addAsyncErrorRule((ctx) => {

packages/forms/signals/src/api/structure.ts

@@ -379,6 +379,7 @@ export async function submit<TModel>(
   node.submitState.selfSubmitting.set(true);
   try {
     const errors = await action(form);
+    node.cancelPendingValidation();
     errors && setSubmissionErrors(node, errors);
   } finally {
     node.submitState.selfSubmitting.set(false);

packages/forms/signals/src/field/node.ts

@@ -36,7 +36,7 @@ import {
   type TrackingKey,
 } from './structure';
 import {FieldSubmitState} from './submit';
-import {ValidationState} from './validation';
+import {PENDING_VALIDATION_PARAMS, ValidationState} from './validation';
 
 /**
  * Internal node in the form tree for a given field.
@@ -229,6 +229,24 @@ export class FieldNode implements FieldState<unknown> {
     return this.metadata(REQUIRED) ?? FALSE;
   }
 
+  /**
+   * Cancels any pending async validations for this field and its descendants.
+   */
+  cancelPendingValidation(): void {
+    if (!this.pending()) {
+      return;
+    }
+
+    if (this.hasMetadata(PENDING_VALIDATION_PARAMS)) {
+      // Setting the resource params to `undefined` cancels the pending validation.
+      this.metadata(PENDING_VALIDATION_PARAMS)!().forEach((params) => params.set(undefined));
+    }
+
+    for (const child of this.structure.children()) {
+      child.cancelPendingValidation();
+    }
+  }
+
   metadata<M>(key: MetadataKey<M, any, any>): M | undefined {
     return this.metadataState.get(key);
   }
@@ -257,8 +275,6 @@ export class FieldNode implements FieldState<unknown> {
   /**
    * Resets the {@link touched} and {@link dirty} state of the field and its descendants.
    *
-   * Note this does not change the data model, which can be reset directly if desired.
-   *
    * @param value Optional value to set to the form. If not passed, the value will not be changed.
    */
   reset(value?: unknown): void {

packages/forms/signals/src/field/validation.ts

@@ -6,13 +6,25 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed, Signal, ɵWritable} from '@angular/core';
+import {computed, Signal, WritableSignal, ɵWritable} from '@angular/core';
+import {createMetadataKey, MetadataKey, MetadataReducer} from '../api/rules/metadata';
 import type {ValidationError} from '../api/rules/validation/validation_errors';
 import type {FieldTree, TreeValidationResult, ValidationResult} from '../api/types';
 import {isArray} from '../util/type_guards';
 import type {FieldNode} from './node';
 import {shortCircuitFalse} from './util';
 
+/**
+ * A private {@link MetadataKey} used to accumulate `validateAsync()` parameters.
+ *
+ * This is used to cancel all pending validations when the field is submitted.
+ */
+export const PENDING_VALIDATION_PARAMS: MetadataKey<
+  Signal<WritableSignal<unknown | undefined>[]>,
+  WritableSignal<unknown | undefined> | undefined,
+  WritableSignal<unknown | undefined>[]
+> = createMetadataKey(MetadataReducer.list());
+
 /**
  * Helper function taking validation state, and returning own state of the node.
  * @param state

packages/forms/signals/test/node/submit.spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {Injector, resource, signal} from '@angular/core';
+import {ApplicationRef, Injector, resource, signal} from '@angular/core';
 import {TestBed} from '@angular/core/testing';
 import {
   form,
@@ -18,6 +18,12 @@ import {
 } from '../../public_api';
 
 describe('submit', () => {
+  let appRef: ApplicationRef;
+
+  beforeEach(() => {
+    appRef = TestBed.inject(ApplicationRef);
+  });
+
   it('fails fast on invalid form', async () => {
     const data = signal({first: '', last: ''});
     const f = form(
@@ -60,10 +66,79 @@ describe('submit', () => {
     const submitSpy = jasmine.createSpy();
     await submit(f, submitSpy);
 
-    expect(f().pending()).toBe(true);
     expect(submitSpy).toHaveBeenCalled();
   });
 
+  it('should cancel pending async validations on success', async () => {
+    const data = signal('');
+    const {promise, resolve} = promiseWithResolvers();
+    const f = form(
+      data,
+      (p) => {
+        validateAsync(p, {
+          params: ({value}) => value(),
+          factory: (params) =>
+            resource({
+              params,
+              loader: async ({params}) => {
+                await promise;
+                return params;
+              },
+            }),
+          onSuccess: () => ({kind: 'async'}),
+          onError: () => ({kind: 'async-error'}),
+        });
+      },
+      {injector: TestBed.inject(Injector)},
+    );
+
+    expect(f().pending()).withContext('Async validator should be pending').toBe(true);
+
+    await submit(f, async () => {});
+    expect(f().pending()).withContext('Submission should cancel pending validators').toBe(false);
+    expect(f().valid()).toBe(true);
+
+    resolve(undefined);
+    await appRef.whenStable();
+    expect(f().valid()).toBe(true);
+  });
+
+  it('should cancel pending async validations on error', async () => {
+    const data = signal('');
+    const {promise, resolve} = promiseWithResolvers();
+    const f = form(
+      data,
+      (p) => {
+        validateAsync(p, {
+          params: ({value}) => value(),
+          factory: (params) =>
+            resource({
+              params,
+              loader: async ({params}) => {
+                await promise;
+                return params;
+              },
+            }),
+          onSuccess: () => ({kind: 'async'}),
+          onError: () => ({kind: 'async-error'}),
+        });
+      },
+      {injector: TestBed.inject(Injector)},
+    );
+
+    expect(f().pending()).withContext('Async validator should be pending').toBe(true);
+
+    await submit(f, async () => ({kind: 'submit'}));
+    expect(f().pending()).withContext('Submission should cancel pending validators').toBe(false);
+    expect(f().errors()).toEqual([jasmine.objectContaining({kind: 'submit'})]);
+
+    resolve(undefined);
+    await appRef.whenStable();
+    expect(f().errors())
+      .withContext('Resolving the pending validator should not clear submission errors')
+      .toEqual([jasmine.objectContaining({kind: 'submit'})]);
+  });
+
   it('maps error to a field', async () => {
     const data = signal({first: '', last: ''});
     const f = form(