feat(store): enforce exact return types in on() callbacks

The on() function 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 on-function-explicit-return-type ESLint
rule, which is now deprecated.

BREAKING CHANGES:

Reducer callbacks passed to on() 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 initialState: State = { name: '', count: 0 };

const reducer = createReducer(
  initialState,
  on(setName, (state, { name }) => ({
    ...state,
    name,
    extraProp: true, // no error
  })),
);
```

AFTER:

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

Closes #4280

Author: david-shortman

modules/eslint-plugin/src/rules/store/on-function-explicit-return-type.ts

@@ -17,9 +17,11 @@ export default createRule<Options, MessageIds>({
   name: path.parse(__filename).name,
   meta: {
     type: 'suggestion',
+    deprecated: true,
     hasSuggestions: true,
     docs: {
-      description: '`On` function should have an explicit return type.',
+      description:
+        '`On` function should have an explicit return type. Deprecated: The `on` function now enforces exact return types at the type level.',
       ngrxModule: 'store',
     },
     schema: [],

modules/store/spec/types/reducer_creator.spec.ts

@@ -99,9 +99,7 @@ describe('createReducer()', () => {
       `).toInfer(
         'onFn',
         `
-      ReducerTypes<{
-        name: string;
-    }, [ActionCreator<"FOO", (props: {
+      ReducerTypes<State, [ActionCreator<"FOO", (props: {
         foo: string;
     }) => {
         foo: string;
@@ -118,11 +116,217 @@ describe('createReducer()', () => {
       `).toInfer(
         'onFn',
         `
-      ReducerTypes<{
-        name: string;
-    }, [ActionCreator<"FOO", () => Action<"FOO">>]>
+      ReducerTypes<State, [ActionCreator<"FOO", () => Action<"FOO">>]>
     `
       );
     });
+
+    describe('valid patterns', () => {
+      it('should allow spread with property override inside createReducer', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(setName, (state, { name }) => ({ ...state, name })),
+          );
+        `).toSucceed();
+      });
+
+      it('should allow returning initialState inside createReducer', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const reset = createAction('reset');
+
+          const reducer = createReducer(
+            initialState,
+            on(reset, () => initialState),
+          );
+        `).toSucceed();
+      });
+
+      it('should allow returning state directly inside createReducer', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const noop = createAction('noop');
+
+          const reducer = createReducer(
+            initialState,
+            on(noop, (state) => state),
+          );
+        `).toSucceed();
+      });
+
+      it('should allow standalone on() with explicit state type', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const onFn = on(setName, (state: State, { name }) => ({ ...state, name }));
+        `).toSucceed();
+      });
+
+      it('should allow explicit return of all properties inside createReducer', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(setName, (state, { name }) => ({ name, count: state.count })),
+          );
+        `).toSucceed();
+      });
+
+      it('should allow on() with multiple action creators', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const action1 = createAction('action1');
+          const action2 = createAction('action2');
+
+          const reducer = createReducer(
+            initialState,
+            on(action1, action2, (state) => ({ ...state, count: state.count + 1 })),
+          );
+        `).toSucceed();
+      });
+    });
+
+    describe('catches excess properties', () => {
+      it('should catch excess properties in on() callback inside createReducer', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(setName, (state, { name }) => ({ ...state, name, extra: true })),
+          );
+        `).toFail(/Remove excess properties/);
+      });
+
+      it('should catch excess properties in standalone on() with explicit state type', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const onFn = on(setName, (state: State, { name }) => ({ ...state, name, extra: true }));
+        `).toFail(/Remove excess properties/);
+      });
+
+      it('should catch excess properties when returning explicit object', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(setName, (state, { name }) => ({ name, count: state.count, extra: 'bad' })),
+          );
+        `).toFail(/Remove excess properties/);
+      });
+
+      it('should catch excess properties when explicit return type annotation is used', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(setName, (state, { name }): State => ({ ...state, name, extra: true })),
+          );
+        `).toFail(/does not exist in type/);
+      });
+
+      it('should catch excess properties from void on() callback', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const noop = createAction('noop');
+
+          const reducer = createReducer(
+            initialState,
+            on(noop, (state) => ({ ...state, extra: true })),
+          );
+        `).toFail(/Remove excess properties/);
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should work with state containing optional properties', () => {
+        expectSnippet(`
+          interface State { req: string; opt?: number };
+          const initialState: State = { req: 'a' };
+          const update = createAction('update');
+
+          const reducer = createReducer(
+            initialState,
+            on(update, (state) => ({ req: 'b' })),
+          );
+        `).toSucceed();
+      });
+
+      it('should work with state containing index signature', () => {
+        expectSnippet(`
+          const initialState: { [key: string]: number } = {};
+          const add = createAction('add', props<{ key: string; value: number }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(add, (state, { key, value }) => ({ ...state, [key]: value })),
+          );
+        `).toSucceed();
+      });
+
+      it('should catch excess properties with index signature state', () => {
+        expectSnippet(`
+          interface State { name: string };
+          const initialState: State = { name: 'test' };
+          const update = createAction('update');
+
+          const reducer = createReducer(
+            initialState,
+            on(update, (state) => ({ ...state, extra: true })),
+          );
+        `).toFail(/Remove excess properties/);
+      });
+    });
+
+    describe('already enforced type checks', () => {
+      it('should catch missing required properties inside createReducer', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(setName, (state, { name }) => ({ name })),
+          );
+        `).toFail(/is missing in type/);
+      });
+
+      it('should catch wrong property types inside createReducer', () => {
+        expectSnippet(`
+          interface State { name: string; count: number };
+          const initialState: State = { name: 'test', count: 0 };
+          const setName = createAction('setName', props<{ name: string }>());
+
+          const reducer = createReducer(
+            initialState,
+            on(setName, (state, { name }) => ({ ...state, name: 123 })),
+          );
+        `).toFail(/not assignable to type/);
+      });
+    });
   });
 }, 8_000);

modules/store/src/models.ts

@@ -175,4 +175,9 @@ export interface SelectSignalOptions<T> {
   equal?: ValueEqualityFn<T>;
 }
 
+export const excessPropertiesAreNotAllowedMsg =
+  'callback return type must exactly match the state type. Remove excess properties.';
+export type ExcessPropertiesAreNotAllowed =
+  typeof excessPropertiesAreNotAllowedMsg;
+
 export type Prettify<T> = { [K in keyof T]: T[K] } & {};

modules/store/src/reducer_creator.ts

@@ -1,4 +1,10 @@
-import { ActionCreator, ActionReducer, ActionType, Action } from './models';
+import {
+  ActionCreator,
+  ActionReducer,
+  ActionType,
+  Action,
+  ExcessPropertiesAreNotAllowed,
+} from './models';
 
 // Goes over the array of ActionCreators, pulls the action type out of each one
 // and returns the array of these action types.
@@ -62,14 +68,20 @@ export function on<
   // is created outside of `createReducer` and state type is either explicitly set OR inferred by return type.
   // For example: `const onFn = on(action, (state: State, {prop}) => ({ ...state, name: prop }));`
   InferredState = State,
+  // Compute the effective state type: either State (when known from createReducer) or InferredState (when standalone)
+  EffectiveState = unknown extends State ? InferredState : State,
+  // Captures the actual return type to enforce exact state shape — excess properties produce a descriptive type error
+  R extends EffectiveState = EffectiveState,
 >(
   ...args: [
     ...creators: Creators,
-    reducer: OnReducer<
-      State extends infer S ? S : never,
-      Creators,
-      InferredState
-    >,
+    reducer: (
+      state: unknown extends State ? InferredState : State,
+      action: ActionType<Creators[number]>
+    ) => R &
+      (Exclude<keyof R, keyof EffectiveState> extends never
+        ? unknown
+        : ExcessPropertiesAreNotAllowed),
   ]
 ): ReducerTypes<unknown extends State ? InferredState : State, Creators> {
   const reducer = args.pop() as unknown as OnReducer<

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

@@ -3,6 +3,7 @@
 `On` function should have an explicit return type.
 
 - **Type**: suggestion
+- **Deprecated**: Yes
 - **Fixable**: No
 - **Suggestion**: Yes
 - **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 `on` function now enforces exact return types at the type level, so excess properties in `on` callbacks will produce TypeScript compilation errors without needing an explicit return type annotation.
+
 ## Rule Details
 
 When we use the `on` function to create reducers, we usually copy the state into a new object, and then add the properties that are being modified after that certain action. This may result in unexpected typing problems, we can add new properties into the state that did not exist previously. TypeScript doesn't see this as a problem and might change the state's interface. The solution is to provide an explicit return type to the `on` function callback.