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.

When ComponentStore is extended with a generic state type parameter
(e.g. class MyStore<T> extends ComponentStore<T>), callbacks that
spread state and override known properties may produce a false type
error. Return state directly or use a type assertion (as T) in those
cases.

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/component-store/write.md

@@ -46,6 +46,34 @@ export class MoviesStore extends ComponentStore<MoviesState> {
 
 </ngrx-code-example>
 
+The `updater` method enforces that callbacks return an object matching the state type exactly. Returning an object with extra properties that don't exist on the state type will produce a TypeScript compilation error:
+
+<ngrx-code-example header="movies.store.ts">
+
+```ts
+@Injectable()
+export class MoviesStore extends ComponentStore<MoviesState> {
+  constructor() {
+    super({ movies: [] });
+  }
+
+  readonly addMovie = this.updater((state, movie: Movie) => ({
+    movies: [...state.movies, movie],
+    // TS error: 'updater()' callback return type must exactly match
+    // the state type. Remove excess properties.
+    extra: true,
+  }));
+}
+```
+
+</ngrx-code-example>
+
+<ngrx-docs-alert type="inform">
+
+**Note:** When `ComponentStore` is extended with a generic state type parameter (e.g., `class MyStore<T extends object> extends ComponentStore<T>`), TypeScript cannot fully resolve the excess property check because `keyof T` is deferred. In those cases, callbacks that spread state and override known properties may produce a false type error. Return `state` directly or use a type assertion (`as T`) as a workaround.
+
+</ngrx-docs-alert>
+
 Updater then can be called with the values imperatively or could take an Observable.
 
 <ngrx-code-example header="movies-page.component.ts">

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,10 @@
 <!-- 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. It is safe to remove this rule from your ESLint configuration. See the [Updating state guide](guide/component-store/write) for details and known limitations.
+
 ## Rule Details
 
 To enforce that the `updater` method from `@ngrx/component-store` returns the expected state interface, we must explicitly add the return type.