feat(store): enforce exact return types in on() and updater() callbacks by david-shortman · Pull Request #5078 · ngrx/platform

david-shortman · 2026-01-30T00:56:52Z

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?

on() and ComponentStore.updater() report excess properties at compile time, and the error names the property:

// TS error: callback return type must exactly match the state type.
// Remove excess properties. Excess property: extra
on(setName, (state, { name }) => ({ ...state, name, extra: true }))

// TS error: updater callback return type must exactly match the state type.
// Remove excess properties. Excess property: extra
this.updater((state, value: string) => ({ ...state, name: value, extra: true }))

How it works: the callback's return type is captured as R, and its keys are inferred into K extends AllowedStateKeys<State>. A conditional type can't see a generic's constraint (e.g. T extends { loading: boolean }), but the constraint check on an inferred type argument can, because it uses assignability. Keys that fail the constraint are left over and reported as excess.

The custom error messages follow the same pattern as NgRx action creators (e.g., 'action creator cannot return an array'), giving actionable guidance instead of a cryptic never error.

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

Spread with overrides: (state) => ({ ...state, name: 'updated' })
Returning initialState or state directly
Multiple action creators in on()
Optional properties and index signatures (Record<string, T> with computed keys)
Discriminated union state, including returning a member with its own keys
Nullable state (User | null)
Generic state in stores and reducer factories: keys guaranteed by the constraint can be returned ({ ...state, loading: true } with T extends { loading: boolean }), other keys are reported as excess

The on-function-explicit-return-type and updater-explicit-return-type ESLint rules are removed, since the type check makes them unnecessary.

Does this PR introduce a breaking change?

[x] Yes
[ ] No

BREAKING CHANGES:

on() and ComponentStore.updater() callbacks must return the exact state type. Returning properties that don't exist on the state type is now a compilation error that names the property.

BEFORE:

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

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

AFTER:

const reducer = createReducer(
  initialState,
  // TS error: callback return type must exactly match the state type.
  // Remove excess properties. Excess property: extra
  on(setName, (state, { name }) => ({ ...state, name, extra: true }))
);

readonly setName = this.updater((state, name: string) => ({
  ...state,
  name,
  // TS error: updater callback return type must exactly match the state type.
  // Remove excess properties. Excess property: extra
  extra: true,
}));

Remove the excess property, or add it to the state type. Union, nullable, and index-signature state types are supported, as are generic state types: properties guaranteed by the generic constraint can be returned, other properties are reported as excess.

The @ngrx/on-function-explicit-return-type and @ngrx/updater-explicit-return-type ESLint rules are removed because the type check makes them unnecessary.

BEFORE:

{
  "rules": {
    "@ngrx/on-function-explicit-return-type": "error",
    "@ngrx/updater-explicit-return-type": "error"
  }
}

AFTER:

{
  "rules": {}
}

Other information

Type tests (ts-snippet for on(), Vitest expectTypeOf / @ts-expect-error for updater()) cover:

Valid: spread with overrides, explicit returns, void callbacks, returning state / initialState, optional properties, index signatures and Record state, discriminated unions, nullable state, and multiple action creators. Generic cases: constrained overrides, unconstrained return state, ListState<T>, Base & T, and as T assertions.
Rejected: excess properties in createReducer-wrapped and standalone on(), excess properties in one branch of a ternary, keys on no union member, excess keys on nullable state, keys not guaranteed by a generic constraint, missing properties, and wrong property types.

netlify · 2026-01-30T00:56:59Z

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

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 ngrx#4280

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. When on() is used inside a generic reducer factory where the state type is an unresolved generic parameter (e.g. createGenericReducer<TState>), callbacks that spread state and override known properties may produce a false type error. Return state directly or use a type assertion (as TState) in those cases. 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 ngrx#4280

david-shortman · 2026-01-30T01:26:07Z

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 · 2026-02-03T19:22:18Z

  name: path.parse(__filename).name,
  meta: {
    type: 'problem',
+    deprecated: true,


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

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

timdeschryver · 2026-02-03T19:25:27Z


 </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:


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 · 2026-02-03T19:25:43Z


+### Exact return type enforcement
+
+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:


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 · 2026-02-03T19:29:37Z

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


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 · 2026-02-21T06:48:34Z

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

Remove updater-explicit-return-type and on-function-explicit-return-type ESLint rules since TypeScript now enforces exact return types at the type level, making these lint rules unnecessary. Address review feedback by using present tense in docs and simplifying generic type notes. Add v22 migration guide with breaking change callout for rule removal. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

@ts-expect-error

The updater exact-return-type tests added in this branch used ts-snippet's expectSnippet API, which was removed when ngrx#5145 migrated the component-store type specs to Vitest. Rewrite them with expectTypeOf / @ts-expect-error to match the migrated specs and fix the test-affected CI failure. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@ts-expect-error

Under TypeScript 6.0 the branded exact-return-type error is reported on the updater callback argument (and the trailing invocation surfaces a second "Expected 0 arguments" error), so the inline @ts-expect-error placements did not match. Move the directive before the callback argument and drop the trailing invocation so exactly one expected error is suppressed per case. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

timdeschryver · 2026-06-22T20:47:20Z

@david-shortman can you please take a look at the conflicts/build please?

Resolve modify/delete conflicts on the legacy eslintrc config files (all.json, all-type-checked.json, component-store.json, store.json) by accepting their removal from upstream (ngrx#5175 dropped eslint v8 / legacy eslintrc config). The deprecated rule removals are already reflected in the corresponding .ts config files. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ric state Add a type test covering the known limitation where an unresolved generic state type (class MyStore<T> extends ComponentStore<T>) defers the excess-property check, causing spread-with-override callbacks to report a false positive. Verifies both documented workarounds (an `as T` assertion and returning state/T directly) compile. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

markostanimirovic · 2026-06-29T21:52:38Z

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


If this fix solves the updater return type but introduces the issue with user-defined stores that use generics for state (as it is mentioned here), I don't think we can proceed with it.

markostanimirovic · 2026-06-29T21:53:10Z

+
+<ngrx-docs-alert type="inform">
+
+**Note:** When `on` is used inside a generic reducer factory where the state type is an unresolved generic parameter (e.g., `function createGenericReducer<TState>()`), 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 TState`) as a workaround.


Same here: https://github.com/ngrx/platform/pull/5078/changes#r3494912154

timdeschryver · 2026-07-16T15:50:22Z

We've decided to not include this in the v22 release.

david-shortman · 2026-07-16T22:38:02Z

Sounds good, seems like I need more thought on this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…e in exact return type check

netlify · 2026-09-29T12:30:23Z

✅ Deploy Preview for ngrx-io ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`e82e44f`
🔍 Latest deploy log	https://app.netlify.com/projects/ngrx-io/deploys/6abbaf580d8a6b0008c98cfc
😎 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.
🤖 Make changes	Run an agent on this branch

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

david-shortman · 2026-09-29T12:44:25Z

I've added a fix for false positives and don't need a generic workaround anymore.

The primary fix was to infer returned keys into K extends AllowedStateKeys<State>. That constraint check uses assignability, which respects generic constraints. If K fails the constraint, the remaining keys are reported as excess, and the error names the property.

The generic-limitation docs notes are removed, and the @ts-expect-error limitation test is now a passing test, with added cases for generic, union, nullable and Record state.

david-shortman added 2 commits January 29, 2026 20:08

david-shortman force-pushed the fix/exact-return-type-enforcement branch from f5a3b4b to 23aa053 Compare January 30, 2026 01:08

david-shortman marked this pull request as ready for review January 30, 2026 01:26

david-shortman mentioned this pull request Jan 30, 2026

updater-explicit-return-type No longer needed with NoInfer #4280

Closed

1 of 2 tasks

timdeschryver reviewed Feb 3, 2026

View reviewed changes

timdeschryver added Breaking Change 22.x labels Feb 3, 2026

david-shortman force-pushed the fix/exact-return-type-enforcement branch from ba777e1 to 696698f Compare February 21, 2026 06:51

timdeschryver and others added 4 commits June 11, 2026 20:28

Merge branch 'main' into fix/exact-return-type-enforcement

60ee716

Merge branch 'main' into fix/exact-return-type-enforcement

2859760

david-shortman and others added 2 commits June 26, 2026 16:38

markostanimirovic reviewed Jun 29, 2026

View reviewed changes

timdeschryver added 23.x and removed 22.x labels Jul 16, 2026

david-shortman and others added 3 commits September 29, 2026 08:09

Merge branch 'main' into fix/exact-return-type-enforcement

687bef3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

fix(store): support generic, union, nullable and index-signature stat…

da5fe72

…e in exact return type check

docs(store): remove generic state limitation from exact return type docs

e82e44f

david-shortman requested review from markostanimirovic and timdeschryver September 29, 2026 21:50


		</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:


		### Exact return type enforcement

		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:


		<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 type="inform">

		Note: When `on` is used inside a generic reducer factory where the state type is an unresolved generic parameter (e.g., `function createGenericReducer<TState>()`), 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 TState`) as a workaround.

Conversation

david-shortman commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Other information

Uh oh!

netlify Bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ngrx-io ready!

Uh oh!

david-shortman commented Jan 30, 2026

Uh oh!

timdeschryver left a comment

Choose a reason for hiding this comment

Uh oh!

timdeschryver Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

david-shortman Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

timdeschryver Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

timdeschryver Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

timdeschryver Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

netlify Bot commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ngrx-site-v21 ready!

Uh oh!

timdeschryver commented Jun 22, 2026

Uh oh!

markostanimirovic Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

markostanimirovic Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

timdeschryver commented Jul 16, 2026

Uh oh!

david-shortman commented Jul 16, 2026

Uh oh!

netlify Bot commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ngrx-io ready!

Uh oh!

david-shortman commented Sep 29, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

david-shortman commented Jan 30, 2026 •

edited

Loading

netlify Bot commented Jan 30, 2026 •

edited

Loading

netlify Bot commented Feb 21, 2026 •

edited

Loading

netlify Bot commented Sep 29, 2026 •

edited

Loading