feat(signals): allow user-defined signals in `withState` and `signalState` by splitting `STATE_SOURCE` #4795

rainerhahnekamp · 2025-05-25T23:51:10Z

BREAKING CHANGE: withState and signalState now support user-defined signals like linkedSignal, resource.value, or any other WritableSignal.

For example:

const user = signal({ id: 1, name: 'John Doe' });
const userClone = linkedSignal(user);
const userValue = resource({
  loader: () => Promise.resolve('user'),
  defaultValue: ''
});

const Store = signalStore(
  withState({ user, userClone, userValue: userValue.value })
);

The state slices don't change:

store.user;       // DeepSignal<{ id: number, name: string }>
store.userClone;  // DeepSignal<{ id: number, name: string }>
store.userValue;  // Signal<string>

The behavior of linkedSignal and resource is preserved. Since the SignalStore no longer creates the signals internally in these cases, signals passed into withState can also be changed externally.

This is a foundational change to enable features like withLinkedState (#4639) and potential support for withResource.

The internal STATE_SOURCE is no longer represented as a single WritableSignal holding the entire state object. Instead, each top-level property becomes its own WritableSignal, or remains as-is if the user already provides a WritableSignal.

Motivation

Internal creation of signals limited flexibility; users couldn’t bring their own signals into the store
Reusing existing signals enables future features like withLinkedState or withResource.
Splitting state into per-key signals improves the performance, because the root is not the complete state anymore.

Change to `STATE_SOURCE`

Given:

type User = {
  firstname: string;
  lastname: string;
};

Before

STATE_SOURCE: WritableSignal<User>;

Now

STATE_SOURCE: {
  firstname: WritableSignal<string>;
  lastname: WritableSignal<string>;
};

Breaking Changes

1. Different object reference

The returned object from signalState() or getState() no longer keeps the same object identity:

const obj = { ngrx: 'rocks' };
const state = signalState(obj);

Before:

state() === obj; // ✅ true

Now:

state() === obj; // ❌ false

2. No signal change on empty patch

Empty patches no longer emit updates, since no signal is mutated:

const state = signalState({ ngrx: 'rocks' });

let count = 0;
effect(() => count++);

TestBed.flushEffects();
expect(count).toBe(1);

patchState(state, {});

Before:

expect(count).toBe(2); // triggered

Now:

expect(count).toBe(1); // no update

3. No wrapping of top-level `WritableSignal`s

const Store = signalStore(
  withState({ foo: signal('bar') })
);
const store = new Store();

Before:

store.foo; // Signal<Signal<string>>

Now:

store.foo; // Signal<string>

4.: `patchState` no longer supports `Record` as root state

Using a Recordas the root state is no longer supported by patchState.

Before:

const Store = signalStore(
  { providedIn: 'root' },
  withState<Record<number, number>>({}),
  withMethods((store) => ({
    addNumber(num: number): void {
      patchState(store, {
        [num]: num,
      });
    },
  }))
);

store.addNumber(1);
store.addNumber(2);

expect(getState(store)).toEqual({ 1: 1, 2: 2 });

After:

const Store = signalStore(
  { providedIn: 'root' },
  withState<Record<number, number>>({}),
  withMethods((store) => ({
    addNumber(num: number): void {
      patchState(store, {
        [num]: num,
      });
    },
  }))
);

store.addNumber(1);
store.addNumber(2);

expect(getState(store)).toEqual({}); // ❌ Nothing updated

If dynamic keys are needed, consider managing them inside a nested signal instead.

Further Changes

signalStoreFeature updated due to changes in WritableStateSource
patchState now uses NoInfer on updaters to prevent incorrect type inference when chaining

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?

Closes #

What is the new behavior?

Does this PR introduce a breaking change?

[x] Yes
[ ] No

Other information

netlify · 2025-05-25T23:51:14Z

✅ Deploy Preview for ngrx-io canceled.

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`8ee9d11`
🔍 Latest deploy log	https://app.netlify.com/projects/ngrx-io/deploys/684c77822d044d0008a1c21b

netlify · 2025-05-25T23:51:44Z

✅ Deploy Preview for ngrx-site-v19 ready!

Name	Link
🔨 Latest commit	`8ee9d11`
🔍 Latest deploy log	https://app.netlify.com/projects/ngrx-site-v19/deploys/684c77827bdf870008f8172b
😎 Deploy Preview	https://deploy-preview-4795--ngrx-site-v19.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.

modules/signals/src/signal-state.ts

modules/signals/src/signal-store-feature.ts

modules/signals/src/state-source.ts

modules/signals/src/with-state.ts

markostanimirovic · 2025-05-29T19:47:27Z

modules/signals/src/with-state.ts

-      );
-      return { ...acc, [key]: toDeepSignal(sliceSignal) };
-    }, {} as SignalsDictionary);
+    const stateAsRecord = state as Record<string | symbol, unknown>;


We can do explicit casting on line 50 and remove this variable.

modules/signals/src/with-state.ts

markostanimirovic · 2025-05-29T20:09:26Z

@rainerhahnekamp It's also necessary to write BREAKING CHANGES: ... in a plain text form 8000 at before the Other Information section. It will be copied to the commit body on squash merge. See the example here: #4584

rainerhahnekamp · 2025-05-29T20:28:32Z

It's also necessary to write BREAKING CHANGES: ...

Got it: Plural and then a line break.

It looks like my IDE messed up the subject a little bit. Will check that one as well.

rainerhahnekamp · 2025-06-01T16:48:42Z

@markostanimirovic, I've updated the code or - where applicable - answered your comments. Please check, once you have time.

I've also fixed a bug in af974f9.

I see commits from main have been merged. Can I rebase them instead or does GitHub do that automatically meanwhile?

markostanimirovic · 2025-06-01T17:38:23Z

@markostanimirovic, I've updated the code or - where applicable - answered your comments. Please check, once you have time.

I've also fixed a bug in af974f9.

I see commits from main have been merged. Can I rebase them instead or does GitHub do that automatically meanwhile?

You can sync changes from main manually and push the changes, or use the "Update branch" button which is available on the PR page.

Btw, lint is also failing.

rainerhahnekamp · 2025-06-04T09:12:17Z

@markostanimirovic, @timdeschryver

signalState now also support user-defined writable Signals
I've updated the docs, by adding an example in signalState for both old and new website.

I will push the PR for withLinkedState later today.

projects/www/src/app/pages/guide/signals/signal-state.md

projects/ngrx.io/content/guide/signals/signal-state.md

modules/signals/src/state-source.ts

…State` BREAKING CHANGES: `withState` and `signalState` now support user-defined signals like `linkedSignal`, `resource.value`, or any other `WritableSignal`. For example: ```ts const user = signal({ id: 1, name: 'John Doe' }); const userClone = linkedSignal(user); const userValue = resource({ loader: () => Promise.resolve('user'), defaultValue: '' }); const Store = signalStore( withState({ user, userClone, userValue: userValue.value }) ); ``` The state slices don't change: ```ts st 6DAF ore.user; // DeepSignal<{ id: number, name: string }> store.userClone; // DeepSignal<{ id: number, name: string }> store.userValue; // Signal<string> ``` The behavior of `linkedSignal` and `resource` is preserved. Since the SignalStore no longer creates the signals internally in these cases, signals passed into `withState` can also be changed externally. This is a foundational change to enable features like `withLinkedState` and potential support for `withResource`. The internal `STATE_SOURCE` is no longer represented as a single `WritableSignal` holding the entire state object. Instead, each top-level property becomes its own `WritableSignal`, or remains as-is if the user already provides a `WritableSignal`. ## Motivation - Internal creation of signals limited flexibility; users couldn’t bring their own signals into the store - Reusing existing signals enables future features like `withLinkedState` or `withResource`. - Splitting state into per-key signals improves the performance, because the root is not the complete state anymore. ## Change to `STATE_SOURCE` Given: ```ts type User = { firstname: string; lastname: string; }; ``` ### Before ```ts STATE_SOURCE: WritableSignal<User>; ``` ### Now ```ts STATE_SOURCE: { firstname: WritableSignal<string>; lastname: WritableSignal<string>; }; ``` ## Breaking Changes ### 1. Different object reference The returned object from `signalState()` or `getState()` no longer keeps the same object identity: ```ts const obj = { ngrx: 'rocks' }; const state = signalState(obj); ``` **Before:** ```ts state() === obj; // ✅ true ``` **Now:** ```ts state() === obj; // ❌ false ``` --- ### 2. No signal change on empty patch Empty patches no longer emit updates, since no signal is mutated: ```ts const state = signalState({ ngrx: 'rocks' }); let count = 0; effect(() => count++); TestBed.flushEffects(); expect(count).toBe(1); patchState(state, {}); ``` **Before:** ```ts expect(count).toBe(2); // triggered ``` **Now:** ```ts expect(count).toBe(1); // no update ``` --- ### 3. No wrapping of top-level `WritableSignal`s ```ts const Store = signalStore( withState({ foo: signal('bar') }) ); const store = new Store(); ``` **Before:** ```ts store.foo; // Signal<Signal<string>> ``` **Now:** ```ts store.foo; // Signal<string> ``` --- ### 4.: `patchState` no longer supports `Record` as root state Using a `Record`as the root state is no longer supported by `patchState`. **Before:** ```ts const Store = signalStore( { providedIn: 'root' }, withState<Record<number, number>>({}), withMethods((store) => ({ addNumber(num: number): void { patchState(store, { [num]: num, }); }, })) ); store.addNumber(1); store.addNumber(2); expect(getState(store)).toEqual({ 1: 1, 2: 2 }); ``` **After:** ```ts const Store = signalStore( { providedIn: 'root' }, withState<Record<number, number>>({}), withMethods((store) => ({ addNumber(num: number): void { patchState(store, { [num]: num, }); }, })) ); store.addNumber(1); store.addNumber(2); expect(getState(store)).toEqual({}); // ❌ Nothing updated ``` If dynamic keys are needed, consider managing them inside a nested signal instead. ## Further Changes - `signalStoreFeature` updated due to changes in `WritableStateSource` - `patchState` now uses `NoInfer` on `updaters` to prevent incorrect type inference when chaining

Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com>

projects/www/src/app/pages/guide/signals/signal-state.md

Co-authored-by: michael-small <33669563+michael-small@users.noreply.github.com>

Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com>

markostanimirovic

Great work Rainer!

Please check this comment: #4795 (comment)

It's necessary to add "BREAKING CHANGES: ..." at the end of the issue description in a plain text format. This will be copied in a commit message body.

markostanimirovic · 2025-06-16T20:28:20Z

modules/signals/spec/with-state.spec.ts

+import {
+  computed,
+  isSignal,
+  linkedSignal,
+  resource,
+  signal,
+} from '@angular/core';
+import { TestBed } from '@angular/core/testing';
 import { withComputed, withMethods, withState } from '../src';
-import { STATE_SOURCE } from '../src/state-source';
-import { getInitialInnerStore } from '../src/signal-store';
+import { getInitialInnerStore, signalStore } from '../src/signal-store';
+import { getState, patchState } from '../src/state-source';


Check unused imports. Most of them them seem unused. Also, public APIs, like getState, patchState, etc. should be imported from the ../src path.

Let's also add one or multiple unit tests (without signalStore usage) for withState to validate the changed behavior.

markostanimirovic · 2025-06-16T20:30:34Z

modules/signals/spec/state-source.spec.ts

+      });
+    });
+
+    it('should only patch affected root properties', () => {


nit: for consistency

Suggested change

it('should only patch affected root properties', () => {

it('patches only affected root properties', () => {

markostanimirovic · 2025-06-16T20:31:04Z

modules/signals/spec/state-source.spec.ts

@@ -192,6 +294,27 @@ describe('StateSource', () => {
        expect(executionCount).toBe(2);
      });
    });
+
+    it('does not support a dynamic type as state', () => {


Suggested change

it('does not support a dynamic type as state', () => {

it('does not support a dynamic dictionary as state', () => {

markostanimirovic · 2025-06-16T20:33:42Z

modules/signals/spec/state-source.spec.ts

@@ -344,4 +467,125 @@ describe('StateSource', () => {
      });
    });
  });
+
+  describe('integration of Signals natively', () => {


Maybe this description would be more precise:

Suggested change

describe('integration of Signals natively', () => {

describe('user-defined signals as state slices', () => {

markostanimirovic · 2025-06-16T20:35:00Z

modules/signals/spec/state-source.spec.ts

+          expect(store.user()).toEqual({ id: 2, name: 'John Doe' });
+        });
+
+        it('allows mixed writable Signal Types', () => {


Suggested change

it('allows mixed writable Signal Types', () => {

it('allows mixing signals and plain values', () => {

markostanimirovic · 2025-06-16T20:52:33Z

modules/signals/src/state-source.ts

+          '@ngrx/signals: Skipping update for unknown property in state source.',
+          `Property: ${String(key)}`


"state source" may be confusing for users who are not familiar with SignalStore/State internal implementation. Message:

Suggested change

'@ngrx/signals: Skipping update for unknown property in state source.',

`Property: ${String(key)}`

`@ngrx/signals: patchState was called with an unknown state slice '${String(key)}'.`,

'Ensure that all state properties are explicitly defined in the initial state.',

'Updates to properties not present in the initial state will be ignored.',

markostanimirovic · 2025-06-16T21:05:38Z

modules/signals/src/state-source.ts

+    if (currentState[signalKey] === newState[signalKey]) {
+      continue;
+    }
+


this check can be removed. It already exists in set fn implementation: https://github.com/angular/angular/blob/main/packages/core/primitives/signals/src/signal.ts#L91

markostanimirovic · 2025-06-16T21:48:31Z

modules/signals/src/state-source.ts

+  signal: unknown
+): signal is WritableSignal<unknown> {


input can be any value, not just a signal, so we can rename it to value or something similar:

Suggested change

signal: unknown

): signal is WritableSignal<unknown> {

value: unknown

): value is WritableSignal<unknown> {

markostanimirovic · 2025-06-16T22:22:42Z

projects/ngrx.io/content/guide/signals/signal-state.md

+When a state property holds an object as its value, the `signalState` function generates a `DeepSignal`.
+It can be used as a regular read-only signal, but it also contains signals for each property of the object it refers to.
+
+```ts
+const firstName = user.firstName; // type: Signal<string>
+const lastName = user.lastName; // type: Signal<string>
+
+console.log(firstName()); // logs: 'Eric'
+console.log(lastName()); // logs: 'Clapton'
+```
+
+If the root properties of a state are already a `WritableSignal`, then they are reused instead of creating new signals.
+This allows the integration of external `WritableSignal`s, such as `linkedSignal` or `resource.value`.
+


The previous paragraph and example are duplicated here accidentally. The example for the new signalState behavior is missing.

Let's leave 'Creating a SignalState' section as it is, and after 'Custom State Updaters' (before 'Usage') add a new section. Note: the new section should be added after 'Updating State' section because the example uses patchState. I also suggest not mentioning implementation details, like - "they are reused instead of creating new signals".

## Using User-Defined Signals The `signalState` function supports integrating user-defined `WritableSignal` instances as part of the state. If a root state property is a `WritableSignal`, its value becomes an integral part of the state. The SignalState instance and the original signal remain synchronized - updating one will immediately reflect in the other. \```ts const name = signal('Jimi Hendrix'); const userState = signalState({ // 👇 Providing an external signal as part of the initial state. name, isAdmin: false, }); console.log(userState.name()); // logs: Jimi Hendrix // Updating the external signal name.set('Brian May'); // reflects the value in the SignalState instance. console.log(userState.name()); // logs: Brian May // Updating the SignalState instance patchState(userState, { name: 'Eric Clapton' }); // reflects the value in the external signal. console.log(name()); // logs: Eric Clapton \```

We should also add an alert/paragraph with similar content for withState.

rainerhahnekamp force-pushed the signals/feat/user-defined-signals-in-state branch 2 times, most recently from 3ee3f3b to 4f6c28b Compare May 26, 2025 00:07

rainerhahnekamp marked this pull request as ready for review May 26, 2025 00:08

rainerhahnekamp requested a review from markostanimirovic May 26, 2025 00:09

rainerhahnekamp changed the title ~~feat!: allow user-defined signals in withState by splitting STATE_SOURCE~~ feat(signals)!: allow user-defined signals in withState by splitting STATE_SOURCE May 26, 2025

rainerhahnekamp force-pushed the signals/feat/user-defined-signals-in-state branch from 4f6c28b to 5d23f0c Compare May 26, 2025 00:10

markostanimirovic requested changes May 29, 2025

View reviewed changes

markostanimirovic added the Breaking Change label May 29, 2025

rainerhahnekamp force-pushed the signals/feat/user-defined-signals-in-state branch from 1057bd7 to be6190f Compare June 1, 2025 16:43

rainerhahnekamp requested review from markostanimirovic and timdeschryver June 1, 2025 16:48

rainerhahnekamp force-pushed the signals/feat/user-defined-signals-in-state branch 2 times, most recently from 574c406 to 8fd5c51 Compare June 4, 2025 08:54

rainerhahnekamp changed the title ~~feat(signals)!: allow user-defined signals in withState by splitting STATE_SOURCE~~ feat(signals)!: allow user-defined signals in withState and signalState by splitting STATE_SOURCE Jun 4, 2025

rainerhahnekamp force-pushed the signals/feat/user-defined-signals-in-state branch from 26c18a2 to 5f159a1 Compare June 4, 2025 09:09

timdeschryver reviewed Jun 4, 2025

View reviewed changes

projects/www/src/app/pages/guide/signals/signal-state.md Outdated Show resolved Hide resolved

8000

projects/ngrx.io/content/guide/signals/signal-state.md Outdated Show resolved Hide resolved

timdeschryver reviewed Jun 4, 2025

View reviewed changes

modules/signals/src/state-source.ts Show resolved Hide resolved

rainerhahnekamp mentioned this pull request Jun 4, 2025

feat(signals): add withLinkedState() #4818

Open

3 tasks

rainerhahnekamp force-pushed the signals/feat/user-defined-signals-in-state branch from ec120da to 3b86461 Compare June 7, 2025 22:08

rainerhahnekamp added 4 commits June 8, 2025 01:42

feat(signals): warn on optional properties

c9060d9

refactor(signals): rename StripWritableSignals to StateResult

68367cc

fix(signals): ensure patchState only patches affected signals

1388b86

rainerhahnekamp and others added 8 commits June 8, 2025 01:43

refactor(signals): remove unnecessary code comments

b047ff0

refactor(signals): inline stateAsRecord

423a0ea

fix(signals): ESLint issue with using number as variable name

49fc004

fix(signals): check for ngDevMode properly

cf0093e

feat(signals): add user-defined signals for signalState

5d271b5

docs(signals): add user-defined signals for signalState

5784c89

Update projects/ngrx.io/content/guide/signals/signal-state.md

f0ff302

Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com>

tests: add test verifying further breaking change

ee3d751

rainerhahnekamp force-pushed the signals/feat/user-defined-signals-in-state branch from 3b86461 to ee3d751 Compare June 7, 2025 23:43

michael-small reviewed Jun 9, 2025

View reviewed changes

projects/www/src/app/pages/guide/signals/signal-state.md Outdated Show resolved Hide resolved

Update projects/www/src/app/pages/guide/signals/signal-state.md

9d6b09b

Co-authored-by: michael-small <33669563+michael-small@users.noreply.github.com>

timdeschryver approved these changes Jun 13, 2025

View reviewed changes

Update projects/www/src/app/pages/guide/signals/signal-state.md

8ee9d11

Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com>

rainerhahnekamp mentioned this pull request Jun 16, 2025

add withResource #4834

Draft

3 tasks

markostanimirovic requested changes Jun 16, 2025

View reviewed changes

markostanimirovic changed the title ~~feat(signals)!: allow user-defined signals in withState and signalState by splitting STATE_SOURCE~~ feat(signals): allow user-defined signals in withState and signalState by splitting STATE_SOURCE Jun 16, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(signals): allow user-defined signals in `withState` and `signalState` by splitting `STATE_SOURCE` #4795

feat(signals): allow user-defined signals in `withState` and `signalState` by splitting `STATE_SOURCE` #4795

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

	it('should only patch affected root properties', () => {
	it('patches only affected root properties', () => {

	it('does not support a dynamic type as state', () => {
	it('does not support a dynamic dictionary as state', () => {

	describe('integration of Signals natively', () => {
	describe('user-defined signals as state slices', () => {

	it('allows mixed writable Signal Types', () => {
	it('allows mixing signals and plain values', () => {

		'@ngrx/signals: Skipping update for unknown property in state source.',
		`Property: ${String(key)}`

-          '@ngrx/signals: Skipping update for unknown property in state source.',
-          `Property: ${String(key)}`
+          `@ngrx/signals: patchState was called with an unknown state slice '${String(key)}'.`,
+          'Ensure that all state properties are explicitly defined in the initial state.',
+          'Updates to properties not present in the initial state will be ignored.',

Uh oh!

feat(signals): allow user-defined signals in withState and signalState by splitting STATE_SOURCE #4795

Are you sure you want to change the base?

feat(signals): allow user-defined signals in withState and signalState by splitting STATE_SOURCE #4795

Uh oh!

Conversation

Uh oh!

Motivation

Change to STATE_SOURCE

Before

Now

Breaking Changes

1. Different object reference

2. No signal change on empty patch

3. No wrapping of top-level WritableSignals

4.: patchState no longer supports Record as root state

Further Changes

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!

Uh oh!

✅ Deploy Preview for ngrx-io canceled.

Uh oh!

Uh oh!

✅ Deploy Preview for ngrx-site-v19 ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

feat(signals): allow user-defined signals in `withState` and `signalState` by splitting `STATE_SOURCE` #4795

feat(signals): allow user-defined signals in `withState` and `signalState` by splitting `STATE_SOURCE` #4795

Change to `STATE_SOURCE`

3. No wrapping of top-level `WritableSignal`s

4.: `patchState` no longer supports `Record` as root state