feat(forms): add reloadValidation to Signal Forms to manually trigger async validation

alxhub · leonsenft · commit 74f76d8075d0 · 2026-03-19T15:22:13.000-07:00
This commit introduces a formal mechanism to manually re-trigger asynchronous validations in Signal Forms, addressing #66994. It exposes a `reloadValidation` method on the `FieldState` interface that recursively cascades down the form tree and invokes the underlying `ResourceRef`'s `reload()` method for any metadata keys tagged with the internal `IS_ASYNC_VALIDATION_RESOURCE` symbol. Fixes #66994
diff --git a/adev/src/content/examples/aria/tree/src/single-select/basic/app/app.html b/adev/src/content/examples/aria/tree/src/single-select/basic/app/app.html
@@ -23,10 +23,7 @@
         node.children ? 'folder' : 'docs'
       }}</span>
       {{ node.name }}
-      <span
-        aria-hidden="true"
-        class="material-symbols-outlined selected-icon"
-        translate="no"
+      <span aria-hidden="true" class="material-symbols-outlined selected-icon" translate="no"
         >check</span
       >
     </li>
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -132,6 +132,7 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
     readonly fieldTree: FieldTree<unknown, TKey>;
     markAsDirty(): void;
     markAsTouched(options?: MarkAsTouchedOptions): void;
+    reloadValidation(): void;
     reset(value?: TValue): void;
     readonly value: WritableSignal<TValue>;
 }
@@ -269,6 +270,9 @@ export type IgnoreUnknownProperties<T> = T extends Record<PropertyKey, unknown>
     [K in keyof T as RemoveStringIndexUnknownKey<K, T[K]>]: IgnoreUnknownProperties<T[K]>;
 } : T;
 
+// @public
+export const IS_ASYNC_VALIDATION_RESOURCE: unique symbol;
+
 // @public
 export interface ItemFieldContext<TValue> extends ChildFieldContext<TValue> {
     readonly index: Signal<number>;
diff --git a/packages/forms/signals/src/api/rules/metadata.ts b/packages/forms/signals/src/api/rules/metadata.ts
@@ -121,6 +121,14 @@ function override<T>(getInitial?: () => T): MetadataReducer<T | undefined, T> {
   };
 }
 
+/**
+ * A symbol used to tag a `MetadataKey` as representing an asynchronous validation resource.
+ *
+ * @category validation
+ * @experimental 21.0.0
+ */
+export const IS_ASYNC_VALIDATION_RESOURCE: unique symbol = Symbol('IS_ASYNC_VALIDATION_RESOURCE');
+
 /**
  * Represents metadata that is aggregated from multiple parts according to the key's reducer
  * function. A value can be contributed to the aggregated value for a field using an
@@ -136,6 +144,9 @@ function override<T>(getInitial?: () => T): MetadataReducer<T | undefined, T> {
 export class MetadataKey<TRead, TWrite, TAcc> {
   private brand!: [TRead, TWrite, TAcc];
 
+  /** @internal */
+  [IS_ASYNC_VALIDATION_RESOURCE]?: true;
+
   /** Use {@link reducedMetadataKey}. */
   protected constructor(
     readonly reducer: MetadataReducer<TAcc, TWrite>,
diff --git a/packages/forms/signals/src/api/rules/validation/validate_async.ts b/packages/forms/signals/src/api/rules/validation/validate_async.ts
@@ -18,7 +18,7 @@ import {
   SchemaPathRules,
   TreeValidationResult,
 } from '../../types';
-import {createManagedMetadataKey, metadata} from '../metadata';
+import {IS_ASYNC_VALIDATION_RESOURCE, createManagedMetadataKey, metadata} from '../metadata';
 
 /**
  * A function that takes the result of an async operation and the current field context, and maps it
@@ -120,6 +120,8 @@ export function validateAsync<TValue, TParams, TResult, TPathKind extends PathKi
   const RESOURCE = createManagedMetadataKey<ReturnType<typeof opts.factory>, TParams | undefined>(
     opts.factory,
   );
+  RESOURCE[IS_ASYNC_VALIDATION_RESOURCE] = true;
+
   metadata(path, RESOURCE, (ctx) => {
     const node = ctx.stateOf(path) as FieldNode;
     const validationState = node.validationState;
diff --git a/packages/forms/signals/src/api/types.ts b/packages/forms/signals/src/api/types.ts
@@ -544,6 +544,10 @@ export interface FieldState<
    * @param value Optional value to set to the form. If not passed, the value will not be changed.
    */
   reset(value?: TValue): void;
+  /**
+   * Reloads all asynchronous validators for this field and its descendants.
+   */
+  reloadValidation(): void;
 }
 
 /**
diff --git a/packages/forms/signals/src/field/node.ts b/packages/forms/signals/src/field/node.ts
@@ -6,7 +6,15 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed, linkedSignal, type Signal, untracked, type WritableSignal} from '@angular/core';
+import {
+  computed,
+  linkedSignal,
+  type Signal,
+  untracked,
+  type WritableSignal,
+  type Resource,
+  type WritableResource,
+} from '@angular/core';
 import {
   MAX,
   MAX_LENGTH,
@@ -15,6 +23,7 @@ import {
   MIN_LENGTH,
   PATTERN,
   REQUIRED,
+  IS_ASYNC_VALIDATION_RESOURCE,
 } from '../api/rules/metadata';
 import type {ValidationError} from '../api/rules/validation/validation_errors';
 import type {
@@ -309,6 +318,28 @@ export class FieldNode implements FieldState<unknown> {
     }
   }
 
+  /**
+   * Reloads all asynchronous validators for this field and its descendants.
+   */
+  reloadValidation(): void {
+    untracked(() => this._reloadValidation());
+  }
+
+  private _reloadValidation(): void {
+    const keys = this.logicNode.logic.getMetadataKeys();
+    for (const key of keys) {
+      if (key[IS_ASYNC_VALIDATION_RESOURCE]) {
+        const resource = this.metadata(key)! as Resource<unknown> &
+          Partial<Pick<WritableResource<unknown>, 'reload'>>;
+        resource.reload?.();
+      }
+    }
+
+    for (const child of this.structure.children()) {
+      child._reloadValidation();
+    }
+  }
+
   /**
    * Creates a linked signal that initiates a {@link debounceSync} when set.
    */
diff --git a/packages/forms/signals/test/node/resource.spec.ts b/packages/forms/signals/test/node/resource.spec.ts
@@ -396,4 +396,47 @@ describe('resources', () => {
 
     expect(f().metadata(RES)).toBe(undefined);
   });
+
+  describe('reloadValidation', () => {
+    it('should trigger a reload of async http validation', async () => {
+      const usernameForm = form(
+        signal('unique-user'),
+        (p) => {
+          validateHttp(p, {
+            request: ({value}) => `/api/check?username=${value()}`,
+            onSuccess: (available: boolean) => (available ? undefined : {kind: 'username-taken'}),
+            onError: () => null,
+          });
+        },
+        {injector},
+      );
+
+      TestBed.tick();
+      const req1 = backend.expectOne('/api/check?username=unique-user');
+
+      expect(usernameForm().pending()).toBe(true);
+
+      req1.flush(true);
+      await appRef.whenStable();
+
+      expect(usernameForm().valid()).toBe(true);
+      expect(usernameForm().pending()).toBe(false);
+
+      // Trigger reload
+      usernameForm().reloadValidation();
+
+      // Expect a new request to be made even though the value hasn't changed
+      TestBed.tick();
+      const req2 = backend.expectOne('/api/check?username=unique-user');
+
+      expect(usernameForm().pending()).toBe(true);
+      expect(usernameForm().valid()).toBe(false);
+
+      req2.flush(false);
+      await appRef.whenStable();
+
+      expect(usernameForm().invalid()).toBe(true);
+      expect(usernameForm().pending()).toBe(false);
+    });
+  });
 });
