feat(core): make SimpleChanges generic (#64535)

crisbeto · thePunderWoman · commit c2d376b85aa6 · 2025-10-20T17:49:39.000Z
Currently it's easy to make a mistake when accessing properties on `SimpleChanges`, because the keys aren't typed. These changes add an optional generic to the interface so that users can get a compilation error if they make a typo. A few things to note: 1. The generic argument is optional and we revert to the old behavior if one isn't passed for backwards compatibility. 2. All of the keys are optional, because they aren't guaranteed to be present for any `ngOnChanges` invocation. 3. We unwrap the values of input signals to match the behavior at runtime. Fixes #17560. PR Close #64535
diff --git a/goldens/public-api/core/index.api.md b/goldens/public-api/core/index.api.md
@@ -1726,22 +1726,25 @@ export type Signal<T> = (() => T) & {
 export function signal<T>(initialValue: T, options?: CreateSignalOptions<T>): WritableSignal<T>;
 
 // @public
-export class SimpleChange {
-    constructor(previousValue: any, currentValue: any, firstChange: boolean);
+export class SimpleChange<T = any> {
+    constructor(previousValue: T, currentValue: T, firstChange: boolean);
     // (undocumented)
-    currentValue: any;
+    currentValue: T;
     // (undocumented)
     firstChange: boolean;
     isFirstChange(): boolean;
     // (undocumented)
-    previousValue: any;
+    previousValue: T;
 }
 
 // @public
-export interface SimpleChanges {
-    // (undocumented)
+export type SimpleChanges<T = unknown> = T extends object ? {
+    [Key in keyof T]?: SimpleChange<T[Key] extends {
+        [ɵINPUT_SIGNAL_BRAND_READ_TYPE]: infer V;
+    } ? V : T[Key]>;
+} : {
     [propName: string]: SimpleChange;
-}
+};
 
 // @public
 export interface SkipSelf {
diff --git a/packages/core/src/change_detection/simple_change.ts b/packages/core/src/change_detection/simple_change.ts
@@ -6,6 +6,8 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import type {ɵINPUT_SIGNAL_BRAND_READ_TYPE} from '../authoring/input/input_signal';
+
 /**
  * Represents a basic change from a previous to a new value for a single
  * property on a directive instance. Passed as a value in a
@@ -15,10 +17,10 @@
  *
  * @publicApi
  */
-export class SimpleChange {
+export class SimpleChange<T = any> {
   constructor(
-    public previousValue: any,
-    public currentValue: any,
+    public previousValue: T,
+    public currentValue: T,
     public firstChange: boolean,
   ) {}
   /**
@@ -32,12 +34,19 @@ export class SimpleChange {
 /**
  * A hashtable of changes represented by {@link SimpleChange} objects stored
  * at the declared property name they belong to on a Directive or Component. This is
- * the type passed to the `ngOnChanges` hook.
+ * the type passed to the `ngOnChanges` hook. Pass the current class or `this` as the
+ * first generic argument for stronger type checking (e.g. `SimpleChanges<YourComponent>`).
  *
  * @see {@link OnChanges}
  *
  * @publicApi
  */
-export interface SimpleChanges {
-  [propName: string]: SimpleChange;
-}
+export type SimpleChanges<T = unknown> = T extends object
+  ? {
+      [Key in keyof T]?: SimpleChange<
+        T[Key] extends {[ɵINPUT_SIGNAL_BRAND_READ_TYPE]: infer V} ? V : T[Key]
+      >;
+    }
+  : {
+      [propName: string]: SimpleChange; // Backwards-compatible signature.
+    };
diff --git a/packages/core/test/authoring/BUILD.bazel b/packages/core/test/authoring/BUILD.bazel
@@ -8,6 +8,7 @@ ts_project(
         "signal_input_signature_test.ts",
         "signal_model_signature_test.ts",
         "signal_queries_signature_test.ts",
+        "simple_changes_signature_test.ts",
         "unwrap_writable_signal_signature_test.ts",
     ],
     deps = [
diff --git a/packages/core/test/authoring/simple_changes_signature_test.ts b/packages/core/test/authoring/simple_changes_signature_test.ts
@@ -0,0 +1,78 @@
+/*!
+ * @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
+ */
+
+import {Directive, input, signal, Input, model, SimpleChanges} from '@angular/core';
+
+// import preserved to simplify `.d.ts` emit and simplify the `type_tester` logic.
+// tslint:disable-next-line no-duplicate-imports
+import {WritableSignal} from '@angular/core';
+
+export class SimpleChangesSignatureTest {
+  /** #ignore */
+  private generic = TestDir.getGenericTypes();
+
+  /** #ignore */
+  private nonGeneric = TestDir.getNonGenericTypes();
+
+  /** string | undefined */
+  decoratorInput = this.generic.decoratorInput;
+
+  /** number | undefined */
+  signalInput = this.generic.signalInput;
+
+  /** string | undefined */
+  signalInputWithTransform = this.generic.signalInputWithTransform;
+
+  /** number | undefined */
+  model = this.generic.model;
+
+  /** WritableSignal<string> */
+  nonInputSignal = this.generic.nonInputSignal;
+
+  /** any */
+  decoratorInputNonGeneric = this.nonGeneric.decoratorInput;
+
+  /** any */
+  signalInputNonGeneric = this.nonGeneric.signalInput;
+}
+
+@Directive()
+export class TestDir {
+  @Input() decoratorInput = 'hello';
+
+  signalInput = input(1);
+
+  signalInputWithTransform = input('hello', {
+    transform: (value: number) => value.toString(),
+  });
+
+  model = model(1);
+
+  nonInputSignal = signal('hello');
+
+  static getGenericTypes() {
+    const changes: SimpleChanges<TestDir> = null!;
+
+    return {
+      decoratorInput: changes.decoratorInput?.currentValue,
+      signalInput: changes.signalInput?.currentValue,
+      signalInputWithTransform: changes.signalInputWithTransform?.currentValue,
+      model: changes.model?.currentValue,
+      nonInputSignal: changes.nonInputSignal!.currentValue,
+    };
+  }
+
+  static getNonGenericTypes() {
+    const changes: SimpleChanges = null!;
+
+    return {
+      decoratorInput: changes['decoratorInput'].currentValue,
+      signalInput: changes['signalInput'].currentValue,
+    };
+  }
+}
diff --git a/packages/core/test/authoring/type_tester.ts b/packages/core/test/authoring/type_tester.ts
@@ -21,6 +21,7 @@ const TESTS = new Map<string, (value: string) => string>([
   ['signal_queries_signature_test', (v) => `Signal<${v}>`],
   ['signal_model_signature_test', (v) => `ModelSignal<${v}>`],
   ['unwrap_writable_signal_signature_test', (v) => v],
+  ['simple_changes_signature_test', (v) => v],
 ]);
 
 const containingDir = path.dirname(url.fileURLToPath(import.meta.url));
@@ -61,6 +62,11 @@ function testFile(testFileName: string, getType: (v: string) => string): boolean
 
     // strip comment start, and beginning (plus whitespace).
     const expectedTypeComment = leadingComments[0].replace(/(^\/\*\*?\s*|\s*\*+\/$)/g, '');
+
+    if (expectedTypeComment === '#ignore') {
+      continue;
+    }
+
     const expectedType = getType(expectedTypeComment);
     // strip excess whitespace or newlines.
     const got = member.type?.getText().replace(/(\n+|\s\s+)/g, '');
diff --git a/packages/forms/test/directives_spec.ts b/packages/forms/test/directives_spec.ts
@@ -706,15 +706,15 @@ describe('Form Directives', () => {
       tick();
       expect(ngModel.control.disabled).toEqual(false);
 
-      ngModel.ngOnChanges({isDisabled: new SimpleChange('', false, false)});
+      ngModel.ngOnChanges({isDisabled: new SimpleChange('' as any, false, false)});
       tick();
       expect(ngModel.control.disabled).toEqual(false);
 
       ngModel.ngOnChanges({isDisabled: new SimpleChange('', 'false', false)});
       tick();
       expect(ngModel.control.disabled).toEqual(false);
 
-      ngModel.ngOnChanges({isDisabled: new SimpleChange('', 0, false)});
+      ngModel.ngOnChanges({isDisabled: new SimpleChange('' as any, 0, false)});
       tick();
       expect(ngModel.control.disabled).toEqual(false);
 
