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.

markostanimirovic · 2025-05-29T19:24:53Z

modules/signals/src/signal-state.ts

 import { DeepSignal, toDeepSignal } from './deep-signal';
+import { SignalsDictionary } from './signal-store-models';
+import { STATE_SOURCE, WritableStateSource } from './state-source';

 export type SignalState<State extends object> = DeepSignal<State> &
  WritableStateSource<State>;

 export function signalState<State extends object>(
  initialState: State
 ): SignalState<State> {


Should we enable the same functionality for the signalState?

Suggested change

): SignalState<State> {

): SignalState<{ [K in keyof State]: State[K] extends WritableSignal<infer V> ? V : State[K] }> {

@timdeschryver, @markostanimirovic. Your call. I'm happy with extending signalState or keeping it as it is.

Just for clarity. It should be possible to do something like this.

const userSignal = signal({ id: 1, name: 'John' }); const userState = signalState({ user: userSignal });

sounds good to me 👍

For me as well, I will go over this PR tomorrow/wednesday.

Alright, then let me add user-defined Signals to signalState as well.

Done.

Implementation Detail: I moved the type StateResult into the SignalState instead of using it as return type of signalState. That has the advantage that the type SignalState<State> can be kept.

markostanimirovic · 2025-05-29T19:26:15Z

modules/signals/src/signal-state.ts

-  const stateSource = signal(initialState as State);
-  const signalState = toDeepSignal(stateSource.asReadonly());
+  const stateKeys = Reflect.ownKeys(initialState);
+  const stateAsRecord = initialState as Record<string | symbol, unknown>;


If this variable is required only because of the changed type, let's use casting directly on line 19, since it's used only there.

Done for stateAsRecord. stateKeys is used three times.

markostanimirovic · 2025-05-29T19:28:12Z

modules/signals/src/signal-state.ts

+  const stateKeys = Reflect.ownKeys(initialState);
+  const stateAsRecord = initialState as Record<string | symbol, unknown>;
+
+  // define STATE_SOURCE property


I suggest removing this and other comments below that describe what the code is doing. The implementation looks straightforward, so I don't think there is a need for that.

markostanimirovic · 2025-05-29T19:29:02Z

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

+  ...args:
+    | [Partial<SignalStoreFeatureResult>, ...SignalStoreFeature[]]
+    | SignalStoreFeature[]
+): SignalStoreFeature<EmptyFeatureResult, EmptyFeatureResult> {
+  const features = (
+    typeof args[0] === 'function' ? args : args.slice(1)
+  ) as SignalStoreFeature[];


why is this change necessary?

With the change for the types, the typings stopped working for signalStoreFeature (not for signalStore). I had to apply this change to make it work again.

I'll take a closer look

The closest I can come up with is the following signature, but this uses the any type , which isn't ideal.

export function signalStoreFeature( featureOrInput: SignalStoreFeature | Partial<SignalStoreFeatureResult>, ...restFeatures: SignalStoreFeature<any, SignalStoreFeatureResult>[] ): SignalStoreFeature<EmptyFeatureResult, EmptyFeatureResult> {

markostanimirovic · 2025-05-29T19:29:57Z

modules/signals/src/state-source.ts

+    | Partial<Prettify<NoInfer<State>>>
+    | PartialStateUpdater<Prettify<NoInfer<State>>>


why do we need NoInfer together with Prettify here?

Without NoInfer, a sequence of updaters would not work anymore.

You can try it out by removing the NoInfer and then navigating to the test in state-source.spec.ts in line 122.

Not sure if we can drop Prettify. I didn't because it was already there before.

Thanks for the explanation. I'll take a look

I think using NoInfer is fine here, otherwise the State type will be updated based on the updaters types. AFAIK this makes sure the State type remains intact.

markostanimirovic · 2025-05-29T19:30:21Z

modules/signals/src/state-source.ts

+  const stateKeys = Reflect.ownKeys(stateSource[STATE_SOURCE]);
+  for (const key of Reflect.ownKeys(newState)) {
+    if (!stateKeys.includes(key)) {
+      // TODO: Optional properties which don't exist in the initial state will not be added


we can display a warning in dev mode for this case

We have here another breaking change. If we have a state with an optional root property and the initial state skips that one, patchState will always skip that one.

We could do a check for undefined in withState and/or come with an ESLint rule.

I've added some additional tests.

Currently, it's also not 'allowed' to have optional state slices. If a state slice is not provided to the initial state, the state signal is never created.

markostanimirovic · 2025-05-29T19:43:15Z

modules/signals/src/with-state.ts

+type StripWritableSignals<State extends object> = {
+  [Property in keyof State]: State[Property] extends WritableSignal<infer Type>
+    ? Type
+    : State[Property];
+};


(1) I'd rename the State generic to StateInput and StripWritableSignals to StateResult.
(2) Value is probably a more precise name than Type here. Anyway, since general/generic names are used here, the readability will be the same IMO if we go with letters only.
(3) An empty line is missing before the function definition

Suggested change

type StripWritableSignals<State extends object> = {

[Property in keyof State]: State[Property] extends WritableSignal<infer Type>

? Type

: State[Property];

};

type StateResult<StateInput extends object> = {

[K in keyof StateInput]: StateInput[K] extends WritableSignal<infer V>

? V

: StateInput[K];

};

Done renaming

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.

markostanimirovic · 2025-05-29T20:04:27Z

modules/signals/src/with-state.ts

+      const signalValue = stateAsRecord[key];
+      stateSource[key] = isWritableSignal(signalValue)
+        ? signalValue
+        : signal(signalValue);
+      stateSignals[key] = toDeepSignal(stateSource[key]);


instead of reassigning stateSignals[key] 2 times:

Suggested change

const signalValue = stateAsRecord[key];

stateSource[key] = isWritableSignal(signalValue)

? signalValue

: signal(signalValue);

stateSignals[key] = toDeepSignal(stateSource[key]);

const signalOrValue = (state as Record<string | symbol, unknown>)[key];

const sig = isWritableSignal(signalOrValue) ? signalOrValue : signal(signalOrValue);

stateSource[key] = toDeepSignal(sig);

Marko, don't we have to assign them twice? Once for STATE_SOURCE and once for the state signals? That would be variables stateSource and stateSignals.

Oh sorry, my bad. The second assignment is for stateSignals, not stateSource. All good here 👍

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

@rainerhahnekamp It's also necessary to write BREAKING CHANGES: ... in a plain text format 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 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` 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>

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

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

Draft

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>

	): SignalState<State> {
	): SignalState<{ [K in keyof State]: State[K] extends WritableSignal<infer V> ? V : State[K] }> {

		\| Partial<Prettify<NoInfer<State>>>
		\| PartialStateUpdater<Prettify<NoInfer<State>>>

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

rainerhahnekamp commented May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

netlify bot commented May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ngrx-io canceled.

Uh oh!

netlify bot commented May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ngrx-site-v19 ready!

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!

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!

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

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

rainerhahnekamp commented May 25, 2025 •

edited

Loading

Change to `STATE_SOURCE`

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

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

netlify bot commented May 25, 2025 •

edited

Loading

netlify bot commented May 25, 2025 •

edited

Loading