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

[david-shortman]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/ngrx/platform/blob/main/CONTRIBUTING.md#commit
• Tests for the changes have been added (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Documentation content changes
[ ] Other... Please describe:

What is the current behavior?

TypeScript does not perform excess property checking on callback return values. This means that on() and ComponentStore.updater() callbacks can return objects with extra properties that don't exist on the state type, and TypeScript won't report an error:

// No compilation error — `extra` is silently accepted
on(setName, (state, { name }) => ({ ...state, name, extra: true }))

// No compilation error — `extra` is silently accepted
this.updater((state, value: string) => ({ ...state, name: value, extra: true }))

The on-function-explicit-return-type and updater-explicit-return-type ESLint rules exist as workarounds, requiring developers to add explicit return type annotations to trigger TypeScript's excess property checking.

Closes #4280

What is the new behavior?

Both on() and ComponentStore.updater() now enforce exact return types at the type level. The callback return type is captured as a generic R, and a conditional check determines whether R contains keys not present in the state type. If excess keys are found, the return type is intersected with a descriptive string literal type, producing a clear compile-time error with an actionable message:

// TS error: Type '{ extra: boolean; ... }' is not assignable to type
// '"callback return type must exactly match the state type. Remove excess properties."'
on(setName, (state, { name }) => ({ ...state, name, extra: true }))

// TS error: Type '{ extra: boolean; ... }' is not assignable to type
// '"updater callback return type must exactly match the state type. Remove excess properties."'
this.updater((state, value: string) => ({ ...state, name: value, extra: true }))

The custom type error messages follow the same pattern used in ngrx action creators (e.g., 'action creator cannot return an array'), providing actionable guidance instead of cryptic never type errors.

No explicit return type annotations are needed. The following patterns continue to work without changes:

• Spread with overrides: (state) => ({ ...state, name: 'updated' })
• Returning initialState or state directly
• States with optional properties or index signatures
• Multiple action creators in on()
• Generic reducer factories that return state directly

The updater-explicit-return-type and on-function-explicit-return-type ESLint rules are deprecated since the type system now handles this directly.

Limitation with generic state types

When the state type is an unresolved generic parameter — e.g., class MyStore<T> extends ComponentStore<T> or function createGenericReducer<TState>() — TypeScript cannot fully resolve the excess property check because keyof T is deferred. This means callbacks that spread state and override known properties (e.g., {...state, id: value}) will produce a false type error in those contexts. The workaround is to return state directly or use a type assertion (as T). This is a TypeScript limitation with deferred conditional types on generic parameters, not something that can be solved at the library level. The deprecated ESLint rules do not help in this case either.

Does this PR introduce a breaking change?

[x] Yes
[ ] No

BREAKING CHANGES:

The updater() and on() callback return types are now strictly checked
for excess properties. Code that previously compiled with extra
properties in these callbacks will now produce TypeScript compilation
errors with a descriptive message.

When the state type is an unresolved generic parameter (e.g.
class MyStore<T> extends ComponentStore<T>, or a generic reducer
factory function), 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:

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

this.updater((state, value: string) => ({
  ...state,
  name: value,
  extra: true, // no error
}))

AFTER:

// Type '{ extra: 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,
    extra: true, // TS error with descriptive message
  })),
);

// Type '{ extra: boolean; ... }' is not assignable to type
// '"updater callback return type must exactly match the state type.
//  Remove excess properties."'
this.updater((state, value: string) => ({
  ...state,
  name: value,
  extra: true, // TS error with descriptive message
}))

Other information

Validated with ts-snippet type tests covering: spread patterns, explicit returns, void callbacks, direct state returns, initialState returns, optional properties, index signatures, multiple action creators, generic reducer factories, missing properties, wrong property types, and excess property detection in both createReducer-wrapped and standalone on() usage.

[netlify]

✅ Deploy Preview for ngrx-io ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	696698f
🔍 Latest deploy log	https://app.netlify.com/projects/ngrx-io/deploys/6999560d5f46b90008c4a2b6
😎 Deploy Preview	https://deploy-preview-5078--ngrx-io.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[david-shortman]

CI failures seem unrelated to this PR:

effects:test
Single test (should enforce an Action return value) timed out at 8s. This is a flaky ts-snippet test. Passes locally.

example-app-e2e
Cypress times out looking for bc-book-preview. This reproduces locally with the same failure, but I think it's a pre-existing issue with the example app.

[timdeschryver]

Because this is a breaking change, the earliest that this can be released is v22.
It will also require a discussion first.

[timdeschryver]

Is there a reason/advantage to deprecate the rules instead of removing them?

[david-shortman]

I suppose they actually don't have value when the return types are no longer needed. So might as well just remove.

[timdeschryver]

Suggested change

	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:
	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 produces a TypeScript compilation error:

[timdeschryver]

Suggested change

	The `on` function 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:
	The `on` function 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 produces a TypeScript compilation error:

[timdeschryver]

I think mentioning "because keyof T is deferred" is not very useful here for our users. Additionally, adding a test case for this scenario can be useful.

Suggested change

**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.

**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. 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.

[netlify]

✅ Deploy Preview for ngrx-site-v21 ready!

Name	Link
🔨 Latest commit	696698f
🔍 Latest deploy log	https://app.netlify.com/projects/ngrx-site-v21/deploys/6999560de3c9f70008fea40b
😎 Deploy Preview	https://deploy-preview-5078--ngrx-site-v21.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.