feat(component-store): enforce exact return types in updater callbacks

The updater() method now enforces exact return types at the type level,
preventing excess properties in callback return values without requiring
explicit return type annotations.

This eliminates the need for the updater-explicit-return-type ESLint rule,
which is now deprecated.

BREAKING CHANGES:

Updater callbacks that return objects with properties not present in the
state type will now produce TypeScript compilation errors.

BEFORE:

```ts
interface State { name: string; count: number }
const store = new ComponentStore<State>({ name: '', count: 0 });

// Previously compiled without error despite the excess property
store.updater((state, name: string) => ({
  ...state,
  name,
  extraProp: true, // no error
}));
```

AFTER:

```ts
// Now produces a TypeScript error:
// Type 'boolean' is not assignable to type
// '"updater callback return type must exactly match the state type.
//  Remove excess properties."'
store.updater((state, name: string) => ({
  ...state,
  name,
  extraProp: true, // TS error
}));
```

Closes #4280

Author: david-shortman

modules/component-store/spec/types/component-store.types.spec.ts

@@ -273,5 +273,61 @@ describe('ComponentStore types', () => {
         );
       });
     });
+
+    describe('catches excess properties', () => {
+      it('when extra property is returned with spread', () => {
+        expectSnippet(
+          `componentStore.updater((state, v: string) => ({...state, extraProp: 'bad'}))('test');`
+        ).toFail(/Remove excess properties/);
+      });
+
+      it('when extra property is returned with explicit object', () => {
+        expectSnippet(
+          `componentStore.updater((state, v: string) => ({ prop: v, prop2: state.prop2, extraProp: 'bad' }))('test');`
+        ).toFail(/Remove excess properties/);
+      });
+
+      it('when extra property is returned from void updater', () => {
+        expectSnippet(
+          `componentStore.updater((state) => ({...state, extraProp: true}))();`
+        ).toFail(/Remove excess properties/);
+      });
+
+      it('when required property is missing', () => {
+        expectSnippet(
+          `componentStore.updater((state, v: string) => ({ prop: v }))('test');`
+        ).toFail(/is missing in type/);
+      });
+
+      it('when property has wrong type', () => {
+        expectSnippet(
+          `componentStore.updater((state, v: string) => ({...state, prop: 123}))('test');`
+        ).toFail(/not assignable to type/);
+      });
+
+      it('allows spread with override', () => {
+        expectSnippet(
+          `const sub = componentStore.updater((state, v: string) => ({...state, prop: v}))('test');`
+        ).toInfer('sub', 'Subscription');
+      });
+
+      it('allows full explicit return matching all state keys', () => {
+        expectSnippet(
+          `const sub = componentStore.updater((state, v: string) => ({ prop: v, prop2: state.prop2 }))('test');`
+        ).toInfer('sub', 'Subscription');
+      });
+
+      it('allows void updater with spread return', () => {
+        expectSnippet(
+          `const v = componentStore.updater((state) => ({...state, prop: 'updated'}))();`
+        ).toInfer('v', 'void');
+      });
+
+      it('allows direct state return', () => {
+        expectSnippet(
+          `const v = componentStore.updater((state) => state)();`
+        ).toInfer('v', 'void');
+      });
+    });
   });
 });

modules/component-store/spec/types/regression.types.spec.ts

@@ -41,4 +41,27 @@ describe('regression component-store', () => {
       `;
     expectSnippet(effectTest).toSucceed();
   });
+
+  describe('updater exact return type', () => {
+    it('should work with state containing optional properties', () => {
+      expectSnippet(`
+        const store = new ComponentStore<{ req: string; opt?: number }>({ req: 'a' });
+        store.updater((state) => ({ req: 'b' }))();
+      `).toSucceed();
+    });
+
+    it('should work with state containing index signature', () => {
+      expectSnippet(`
+        const store = new ComponentStore<{ [key: string]: number }>({});
+        store.updater((state, v: number) => ({...state, newKey: v}))(5);
+      `).toSucceed();
+    });
+
+    it('should catch excess properties with concrete state type', () => {
+      expectSnippet(`
+        const store = new ComponentStore<{ name: string }>({ name: 'test' });
+        store.updater((state, v: string) => ({...state, name: v, extra: true}))('test');
+      `).toFail(/Remove excess properties/);
+    });
+  });
 });

modules/component-store/src/component-store.ts

@@ -40,6 +40,10 @@ import {
 import { isOnStateInitDefined, isOnStoreInitDefined } from './lifecycle_hooks';
 import { toSignal } from '@angular/core/rxjs-interop';
 
+const excessPropertiesAreNotAllowedMsg =
+  'updater callback return type must exactly match the state type. Remove excess properties.';
+type ExcessPropertiesAreNotAllowed = typeof excessPropertiesAreNotAllowedMsg;
+
 export interface SelectConfig<T = unknown> {
   debounce?: boolean;
   equal?: ValueEqualityFn<T>;
@@ -132,7 +136,17 @@ export class ComponentStore<T extends object> implements OnDestroy {
     ReturnType = OriginType extends void
       ? () => void
       : (observableOrValue: ValueType | Observable<ValueType>) => Subscription,
-  >(updaterFn: (state: T, value: OriginType) => T): ReturnType {
+    // Captures the actual return type to enforce exact state shape
+    R extends T = T,
+  >(
+    updaterFn: (
+      state: T,
+      value: OriginType
+    ) => R &
+      (Exclude<keyof R, keyof T> extends never
+        ? unknown
+        : ExcessPropertiesAreNotAllowed)
+  ): ReturnType {
     return ((
       observableOrValue?: OriginType | Observable<OriginType>
     ): Subscription => {
@@ -379,9 +393,8 @@ export class ComponentStore<T extends object> implements OnDestroy {
     // This type quickly became part of effect 'API'
     ProvidedType = void,
     // The actual origin$ type, which could be unknown, when not specified
-    OriginType extends
-      | Observable<ProvidedType>
-      | unknown = Observable<ProvidedType>,
+    OriginType extends Observable<ProvidedType> | unknown =
+      Observable<ProvidedType>,
     // Unwrapped actual type of the origin$ Observable, after default was applied
     ObservableType = OriginType extends Observable<infer A> ? A : never,
     // Return either an optional callback or a function requiring specific types as inputs

modules/eslint-plugin/src/rules/component-store/updater-explicit-return-type.ts

@@ -12,8 +12,10 @@ export default createRule<Options, MessageIds>({
   name: path.parse(__filename).name,
   meta: {
     type: 'problem',
+    deprecated: true,
     docs: {
-      description: '`Updater` should have an explicit return type.',
+      description:
+        '`Updater` should have an explicit return type. Deprecated: `ComponentStore.updater` now enforces exact return types at the type level.',
       ngrxModule: 'component-store',
     },
     schema: [],

projects/www/src/app/pages/guide/eslint-plugin/rules/updater-explicit-return-type.md

@@ -3,6 +3,7 @@
 `Updater` should have an explicit return type.
 
 - **Type**: problem
+- **Deprecated**: Yes
 - **Fixable**: No
 - **Suggestion**: No
 - **Requires type checking**: No
@@ -11,6 +12,12 @@
 <!-- Everything above this generated, do not edit -->
 <!-- MANUAL-DOC:START -->
 
+## Deprecation Notice
+
+This rule is deprecated. The `ComponentStore.updater` method now enforces exact return types at the type level, so excess properties in updater callbacks will produce TypeScript compilation errors without needing an explicit return type annotation.
+
+Note: This type-level enforcement does not apply when the store's state type is an unresolved generic parameter (e.g., `class MyStore<T> extends ComponentStore<T>`). In those cases, explicit return type annotations are still recommended.
+
 ## Rule Details
 
 To enforce that the `updater` method from `@ngrx/component-store` returns the expected state interface, we must explicitly add the return type.