refactor(forms): convert Signal Forms errors to use RuntimeError

- Added 13 new error codes to forms/src/errors.ts (1900-1999)
- use RuntimeError

Author: kirjs

packages/forms/signals/compat/src/compat_structure.ts

@@ -6,7 +6,14 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed, Signal, signal, WritableSignal} from '@angular/core';
+import {
+  computed,
+  Signal,
+  signal,
+  WritableSignal,
+  ɵRuntimeError as RuntimeError,
+} from '@angular/core';
+import {SignalFormsErrorCode} from '../../src/errors';
 import {FormFieldManager} from '../../src/field/manager';
 import {FieldNode, ParentFieldNode} from '../../src/field/node';
 import {
@@ -111,7 +118,10 @@ export class CompatStructure extends FieldNodeStructure {
 
   constructor(node: FieldNode, options: CompatFieldNodeOptions) {
     super(options.logic, node, () => {
-      throw new Error(`Compat nodes don't have children.`);
+      throw new RuntimeError(
+        SignalFormsErrorCode.COMPAT_NO_CHILDREN,
+        ngDevMode && `Compat nodes don't have children.`,
+      );
     });
     this.value = getControlValueSignal(options);
     this.parent = getParentFromOptions(options);

packages/forms/signals/src/controls/interop_ng_control.ts

@@ -6,6 +6,9 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {ɵRuntimeError as RuntimeError} from '@angular/core';
+import {SignalFormsErrorCode} from '../errors';
+
 import {
   ControlValueAccessor,
   Validators,
@@ -122,7 +125,10 @@ export class InteropNgControl
     if (this.field().pending()) {
       return 'PENDING';
     }
-    throw Error('AssertionError: unknown form control status');
+    throw new RuntimeError(
+      SignalFormsErrorCode.UNKNOWN_STATUS,
+      ngDevMode && 'Unknown form control status',
+    );
   }
 
   valueAccessor: ControlValueAccessor | null = null;

packages/forms/signals/src/errors.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+/**
+ * The list of error codes used in runtime code of the `forms` package.
+ * Reserved error code range: 1900-1999.
+ */
+export const enum SignalFormsErrorCode {
+  // Signal Forms errors (1900-1999)
+  PATH_NOT_IN_FIELD_TREE = 1900,
+  PATH_RESOLUTION_FAILED = 1901,
+  ORPHAN_FIELD_PROPERTY = 1902,
+  ORPHAN_FIELD_ARRAY = 1903,
+  ORPHAN_FIELD_NOT_FOUND = 1904,
+  ROOT_FIELD_NO_PARENT = 1905,
+  PARENT_NOT_ARRAY = 1906,
+  ABSTRACT_CONTROL_IN_FORM = 1907,
+  PATH_OUTSIDE_SCHEMA = 1908,
+  UNKNOWN_BUILDER_TYPE = 1909,
+  UNKNOWN_STATUS = 1910,
+  COMPAT_NO_CHILDREN = 1911,
+}

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

@@ -6,7 +6,14 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed, Signal, untracked, WritableSignal} from '@angular/core';
+import {
+  computed,
+  Signal,
+  untracked,
+  WritableSignal,
+  ɵRuntimeError as RuntimeError,
+} from '@angular/core';
+import {SignalFormsErrorCode} from '../errors';
 import {AbstractControl} from '@angular/forms';
 import {
   FieldContext,
@@ -65,7 +72,10 @@ export class FieldNodeContext implements FieldContext<unknown> {
           stepsRemaining--;
           field = field.structure.parent;
           if (field === undefined) {
-            throw new Error('Path is not part of this field tree.');
+            throw new RuntimeError(
+              SignalFormsErrorCode.PATH_NOT_IN_FIELD_TREE,
+              ngDevMode && 'Path is not part of this field tree.',
+            );
           }
         }
 
@@ -74,11 +84,13 @@ export class FieldNodeContext implements FieldContext<unknown> {
         for (let key of targetPathNode.keys) {
           field = field.structure.getChild(key);
           if (field === undefined) {
-            throw new Error(
-              `Cannot resolve path .${targetPathNode.keys.join('.')} relative to field ${[
-                '<root>',
-                ...this.node.structure.pathKeys(),
-              ].join('.')}.`,
+            throw new RuntimeError(
+              SignalFormsErrorCode.PATH_RESOLUTION_FAILED,
+              ngDevMode &&
+                `Cannot resolve path .${targetPathNode.keys.join('.')} relative to field ${[
+                  '<root>',
+                  ...this.node.structure.pathKeys(),
+                ].join('.')}.`,
             );
           }
         }
@@ -116,7 +128,10 @@ export class FieldNodeContext implements FieldContext<unknown> {
     const key = this.key();
     // Assert that the parent is actually an array.
     if (!isArray(untracked(this.node.structure.parent!.value))) {
-      throw new Error(`RuntimeError: cannot access index, parent field is not an array`);
+      throw new RuntimeError(
+        SignalFormsErrorCode.PARENT_NOT_ARRAY,
+        ngDevMode && 'Cannot access index, parent field is not an array.',
+      );
     }
     // Return the key as a number if we are indeed inside an array field.
     return Number(key);
@@ -128,8 +143,10 @@ export class FieldNodeContext implements FieldContext<unknown> {
     const result = this.resolve(p)().value();
 
     if (result instanceof AbstractControl) {
-      throw new Error(
-        `Tried to read an 'AbstractControl' value form a 'form()'. Did you mean to use 'compatForm()' instead?`,
+      throw new RuntimeError(
+        SignalFormsErrorCode.ABSTRACT_CONTROL_IN_FORM,
+        ngDevMode &&
+          `Tried to read an 'AbstractControl' value from a 'form()'. Did you mean to use 'compatForm()' instead?`,
       );
     }
     return result;

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

@@ -14,8 +14,11 @@ import {
   Signal,
   untracked,
   WritableSignal,
+  ɵRuntimeError as RuntimeError,
 } from '@angular/core';
 
+import {SignalFormsErrorCode} from '../errors';
+
 import {LogicNode} from '../schema/logic_node';
 import type {FieldPathNode} from '../schema/path_node';
 import {deepSignal} from '../util/deep_signal';
@@ -186,8 +189,10 @@ export abstract class FieldNodeStructure {
       const key = initialKeyInParent!;
       return computed(() => {
         if (this.parent!.structure.getChild(key) !== this.node) {
-          throw new Error(
-            `RuntimeError: orphan field, looking for property '${key}' of ${getDebugName(this.parent!)}`,
+          throw new RuntimeError(
+            SignalFormsErrorCode.ORPHAN_FIELD_PROPERTY,
+            ngDevMode &&
+              `Orphan field, looking for property '${key}' of ${getDebugName(this.parent!)}`,
           );
         }
         return key;
@@ -204,8 +209,9 @@ export abstract class FieldNodeStructure {
           // It should not be possible to encounter this error. It would require the parent to
           // change from an array field to non-array field. However, in the current implementation
           // a field's parent can never change.
-          throw new Error(
-            `RuntimeError: orphan field, expected ${getDebugName(this.parent!)} to be an array`,
+          throw new RuntimeError(
+            SignalFormsErrorCode.ORPHAN_FIELD_ARRAY,
+            ngDevMode && `Orphan field, expected ${getDebugName(this.parent!)} to be an array`,
           );
         }
 
@@ -233,8 +239,9 @@ export abstract class FieldNodeStructure {
           }
         }
 
-        throw new Error(
-          `RuntimeError: orphan field, can't find element in array ${getDebugName(this.parent!)}`,
+        throw new RuntimeError(
+          SignalFormsErrorCode.ORPHAN_FIELD_NOT_FOUND,
+          ngDevMode && `Orphan field, can't find element in array ${getDebugName(this.parent!)}`,
         );
       });
     }
@@ -512,7 +519,10 @@ const ROOT_PATH_KEYS = computed<readonly string[]>(() => []);
  * do not have a parent. This signal will throw if it is read.
  */
 const ROOT_KEY_IN_PARENT = computed(() => {
-  throw new Error(`RuntimeError: the top-level field in the form has no parent`);
+  throw new RuntimeError(
+    SignalFormsErrorCode.ROOT_FIELD_NO_PARENT,
+    ngDevMode && 'The top-level field in the form has no parent.',
+  );
 });
 
 /** Gets a human readable name for a field node for use in error messages. */

packages/forms/signals/src/schema/logic_node.ts

@@ -6,8 +6,10 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import type {MetadataKey} from '../api/rules/metadata';
-import type {ValidationError} from '../api/rules/validation/validation_errors';
+import {ɵRuntimeError as RuntimeError} from '@angular/core';
+import {SignalFormsErrorCode} from '../errors';
+
+import type {ValidationError, MetadataKey} from '../api/rules';
 import type {AsyncValidationResult, DisabledReason, LogicFn, ValidationResult} from '../api/types';
 import {setBoundPathDepthForResolution} from '../field/resolution';
 import {type BoundPredicate, DYNAMIC, LogicContainer, type Predicate} from './logic';
@@ -433,7 +435,10 @@ function getAllChildBuilders(
       ...(builder.children.has(key) ? [{builder: builder.getChild(key), predicates: []}] : []),
     ];
   } else {
-    throw new Error('Unknown LogicNodeBuilder type');
+    throw new RuntimeError(
+      SignalFormsErrorCode.UNKNOWN_BUILDER_TYPE,
+      ngDevMode && 'Unknown LogicNodeBuilder type',
+    );
   }
 }
 
@@ -467,7 +472,10 @@ function createLogic(
   } else if (builder instanceof NonMergeableLogicNodeBuilder) {
     logic.mergeIn(builder.logic);
   } else {
-    throw new Error('Unknown LogicNodeBuilder type');
+    throw new RuntimeError(
+      SignalFormsErrorCode.UNKNOWN_BUILDER_TYPE,
+      ngDevMode && 'Unknown LogicNodeBuilder type',
+    );
   }
   return logic;
 }

packages/forms/signals/src/schema/schema.ts

@@ -6,6 +6,9 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {ɵRuntimeError as RuntimeError} from '@angular/core';
+import {SignalFormsErrorCode} from '../errors';
+
 import {SchemaPath, SchemaFn, SchemaOrSchemaFn} from '../api/types';
 import {FieldPathNode} from './path_node';
 
@@ -105,9 +108,10 @@ export function isSchemaOrSchemaFn(value: unknown): value is SchemaOrSchemaFn<un
 /** Checks that a path node belongs to the schema function currently being compiled. */
 export function assertPathIsCurrent(path: SchemaPath<unknown>): void {
   if (currentCompilingNode !== FieldPathNode.unwrapFieldPath(path).root) {
-    throw new Error(
-      `A FieldPath can only be used directly within the Schema that owns it,` +
-        ` **not** outside of it or within a sub-schema.`,
+    throw new RuntimeError(
+      SignalFormsErrorCode.PATH_OUTSIDE_SCHEMA,
+      ngDevMode &&
+        `A FieldPath can only be used directly within the Schema that owns it, **not** outside of it or within a sub-schema.`,
     );
   }
 }

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

@@ -87,7 +87,7 @@ describe('Field Context', () => {
     );
     f().valid();
     expect(keys).toEqual([
-      'RuntimeError: the top-level field in the form has no parent',
+      jasmine.stringContaining('NG01905'), // SIGNAL_FORMS_ROOT_FIELD_NO_PARENT
       'name',
       'age',
     ]);
@@ -125,10 +125,10 @@ describe('Field Context', () => {
     );
     f().valid();
     expect(indices).toEqual([
-      'RuntimeError: the top-level field in the form has no parent',
+      jasmine.stringContaining('NG01905'), // SIGNAL_FORMS_ROOT_FIELD_NO_PARENT
       0,
       1,
-      'RuntimeError: cannot access index, parent field is not an array',
+      jasmine.stringContaining('NG01906'), // SIGNAL_FORMS_PARENT_NOT_ARRAY
     ]);
   });
 

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

@@ -1319,7 +1319,7 @@ describe('FieldNode', () => {
         {injector: TestBed.inject(Injector)},
       );
 
-      expect(() => f().disabled()).toThrowError('Path is not part of this field tree.');
+      expect(() => f().disabled()).toThrowError(/Path is not part of this field tree\./);
     });
   });