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

BREAKING CHANGES:

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

BEFORE:

1. The initial state object reference is preserved:

const initialState = { ngrx: 'rocks' };

// signalState:
const state = signalState(initialState);
state() === initialState; // true

// withState:
const Store = signalStore(withState(initialState));
const store = new Store();
getState(store) === initialState; // true

2. Top-level `WritableSignal`s are wrapped with `Signal`s:

// signalState:
const state = signalState({ ngrx: signal('rocks') });
state.ngrx // type: Signal<WritableSignal<string>>

// withState:
const Store = signalStore(withState({ ngrx: signal('rocks') }));
const store = new Store();
store.ngrx // type: Signal<WritableSignal<string>>

3. Root state properties can be added dynamically:

// signalState:
const state = signalState<Record<string, string>>({});
console.log(state()); // {}

patchState(state, { ngrx: 'rocks' });
console.log(state()); // { ngrx: 'rocks' }

// withState:
const Store = signalStore(
  { protectedState: false },
  withState<Record<string, string>>({})
);
const store = new Store();
console.log(getState(store)); // {}

patchState(store, { ngrx: 'rocks' });
console.log(getState(store)); // { ngrx: 'rocks' }

AFTER:

1. The initial state object reference is not preserved:

const initialState = { ngrx: 'rocks' };

// signalState:
const state = signalState(initialState);
state() === initialState; // false

// withState:
const Store = signalStore(withState(initialState));
const store = new Store();
getState(store) === initialState; // false

2. Top-level `WritableSignal`s are not wrapped with `Signal`s:

// signalState:
const state = signalState({ ngrx: signal('rocks') });
state.ngrx // type: Signal<string>

// withState:
const Store = signalStore(withState({ ngrx: signal('rocks') }));
const store = new Store();
store.ngrx // type: Signal<string>

3. Root state properties can not be added dynamically:

// signalState:
const state = signalState<Record<string, string>>({});
console.log(state()); // {}

patchState(state, { ngrx: 'rocks' });
console.log(state()); // {}

// withState:
const Store = signalStore(
  { protectedState: false },
  withState<Record<string, string>>({})
);
const store = new Store();
console.log(getState(store)); // {}

patchState(store, { ngrx: 'rocks' });
console.log(getState(store)); // {}

Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com>
Co-authored-by: michael-small <33669563+michael-small@users.noreply.github.com>
Co-authored-by: Marko Stanimirović <markostanimirovic95@gmail.com>

Author: 4 people

modules/signals/spec/helpers.ts

@@ -1,5 +1,6 @@
 import { Component, inject, Type } from '@angular/core';
 import { TestBed } from '@angular/core/testing';
+import { SignalsDictionary } from '../src/signal-store-models';
 
 export function createLocalService<Service extends Type<unknown>>(
   serviceToken: Service
@@ -30,3 +31,26 @@ export function createLocalService<Service extends Type<unknown>>(
     destroy: () => fixture.destroy(),
   };
 }
+
+/**
+ * This could be done by using `getState`, but
+ * 1. We don't want to depend on the implementation of `getState` in the test.
+ * 2. We want to be able to provide the state in its actual type (with slice signals).
+ */
+export function assertStateSource(
+  state: SignalsDictionary,
+  expected: SignalsDictionary
+): void {
+  const stateKeys = Reflect.ownKeys(state);
+  const expectedKeys = Reflect.ownKeys(expected);
+
+  const currentState = stateKeys.reduce((acc, key) => {
+    acc[key] = state[key]();
+    return acc;
+  }, {} as Record<string | symbol, unknown>);
+  const expectedState = expectedKeys.reduce((acc, key) => {
+    acc[key] = expected[key]();
+    return acc;
+  }, {} as Record<string | symbol, unknown>);
+  expect(currentState).toEqual(expectedState);
+}

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

@@ -1,7 +1,7 @@
-import { computed } from '@angular/core';
-import { effect, isSignal } from '@angular/core';
+import { computed, effect, isSignal } from '@angular/core';
 import { TestBed } from '@angular/core/testing';
 import { patchState, signalState } from '../src';
+import { SignalsDictionary } from '../src/signal-store-models';
 import { STATE_SOURCE } from '../src/state-source';
 
 vi.mock('@angular/core', { spy: true });
@@ -21,21 +21,30 @@ describe('signalState', () => {
     vi.clearAllMocks();
   });
 
-  it('has writable state source', () => {
-    const state = signalState({});
-    const stateSource = state[STATE_SOURCE];
+  it('creates its properties as Signals', () => {
+    const state = signalState({ foo: 'bar' });
+    const stateSource: SignalsDictionary = state[STATE_SOURCE];
 
-    expect(isSignal(stateSource)).toBe(true);
-    expect(typeof stateSource.update === 'function').toBe(true);
+    expect(isSignal(state)).toBe(true);
+    for (const key of Reflect.ownKeys(stateSource)) {
+      expect(isSignal(stateSource[key])).toBe(true);
+      expect(typeof stateSource[key].update === 'function').toBe(true);
+    }
+  });
+
+  it('does not keep the object reference of the initial state', () => {
+    const state = signalState(initialState);
+    expect(state()).not.toBe(initialState);
+    expect(state()).toEqual(initialState);
   });
 
   it('creates signals for nested state slices', () => {
     const state = signalState(initialState);
 
-    expect(state()).toBe(initialState);
+    expect(state()).toEqual(initialState);
     expect(isSignal(state)).toBe(true);
 
-    expect(state.user()).toBe(initialState.user);
+    expect(state.user()).toEqual(initialState.user);
     expect(isSignal(state.user)).toBe(true);
 
     expect(state.user.firstName()).toBe(initialState.user.firstName);
@@ -80,20 +89,11 @@ describe('signalState', () => {
     expect((state.user.firstName as any).y).toBe(undefined);
   });
 
-  it('does not modify STATE_SOURCE', () => {
-    const state = signalState(initialState);
-
-    expect((state[STATE_SOURCE] as any).user).toBe(undefined);
-    expect((state[STATE_SOURCE] as any).foo).toBe(undefined);
-    expect((state[STATE_SOURCE] as any).numbers).toBe(undefined);
-    expect((state[STATE_SOURCE] as any).ngrx).toBe(undefined);
-  });
-
   it('overrides Function properties if state keys have the same name', () => {
     const initialState = { name: { length: { length: 'ngrx' }, name: 20 } };
     const state = signalState(initialState);
 
-    expect(state()).toBe(initialState);
+    expect(state()).toEqual(initialState);
 
     expect(state.name()).toBe(initialState.name);
     expect(isSignal(state.name)).toBe(true);
@@ -190,12 +190,12 @@ describe('signalState', () => {
 
       patchState(state, {});
       TestBed.tick();
-      expect(stateCounter).toBe(2);
+      expect(stateCounter).toBe(1);
       expect(userCounter).toBe(1);
 
       patchState(state, (state) => state);
       TestBed.tick();
-      expect(stateCounter).toBe(3);
+      expect(stateCounter).toBe(1);
       expect(userCounter).toBe(1);
     }));
 });

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

@@ -8,6 +8,7 @@ import {
   withState,
 } from '../src';
 import { STATE_SOURCE } from '../src/state-source';
+import { assertStateSource } from './helpers';
 
 describe('signalStoreFeature', () => {
   function withCustomFeature1() {
@@ -50,7 +51,7 @@ describe('signalStoreFeature', () => {
 
     const store = new Store();
 
-    expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo' });
+    assertStateSource(store[STATE_SOURCE], { foo: signal('foo') });
     expect(store.foo()).toBe('foo');
     expect(store.bar()).toBe('foo1');
     expect(store.baz()).toBe('foofoo12');
@@ -65,7 +66,7 @@ describe('signalStoreFeature', () => {
 
     const store = new Store();
 
-    expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo' });
+    assertStateSource(store[STATE_SOURCE], { foo: signal('foo') });
     expect(store.foo()).toBe('foo');
     expect(store.bar()).toBe('foo1');
     expect(store.m()).toBe('foofoofoo123');
@@ -81,7 +82,11 @@ describe('signalStoreFeature', () => {
 
     const store = new Store();
 
-    expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo', foo1: 1, foo2: 2 });
+    assertStateSource(store[STATE_SOURCE], {
+      foo: signal('foo'),
+      foo1: signal(1),
+      foo2: signal(2),
+    });
     expect(store.foo()).toBe('foo');
     expect(store.bar()).toBe('foo1');
     expect(store.baz()).toBe('foofoo12');

modules/signals/spec/signal-store.spec.ts

@@ -16,7 +16,7 @@ import {
   withState,
 } from '../src';
 import { STATE_SOURCE } from '../src/state-source';
-import { createLocalService } from './helpers';
+import { assertStateSource, createLocalService } from './helpers';
 
 describe('signalStore', () => {
   describe('creation', () => {
@@ -47,42 +47,56 @@ describe('signalStore', () => {
       expect(store1.foo()).toBe('bar');
     });
 
-    it('creates a store with readonly state source by default', () => {
+    it('creates a store with state source as Record holding slices as signals by default', () => {
       const Store = signalStore(withState({ foo: 'bar' }));
       const store = new Store();
       const stateSource = store[STATE_SOURCE];
 
-      expect(isSignal(stateSource)).toBe(true);
-      expect(stateSource()).toEqual({ foo: 'bar' });
+      expect(isSignal(stateSource)).toBe(false);
+      expect(Object.keys(stateSource)).toEqual(['foo']);
+      expect(isSignal(stateSource.foo)).toBe(true);
+      assertStateSource(stateSource, {
+        foo: signal('bar'),
+      });
     });
 
-    it('creates a store with readonly state source when protectedState option is true', () => {
+    it('creates a store with state source as Record holding slices as signals when protectedState option is true', () => {
       const Store = signalStore(
         { protectedState: true },
         withState({ foo: 'bar' })
       );
       const store = new Store();
       const stateSource = store[STATE_SOURCE];
 
-      expect(isSignal(stateSource)).toBe(true);
-      expect(stateSource()).toEqual({ foo: 'bar' });
+      expect(isSignal(stateSource)).toBe(false);
+      expect(Object.keys(stateSource)).toEqual(['foo']);
+      expect(isSignal(stateSource.foo)).toBe(true);
+      assertStateSource(stateSource, {
+        foo: signal('bar'),
+      });
     });
 
-    it('creates a store with writable state source when protectedState option is false', () => {
+    it('creates a store with state source as Record holding slices as writeable signals when protectedState option is false', () => {
       const Store = signalStore(
         { protectedState: false },
         withState({ foo: 'bar' })
       );
       const store = new Store();
       const stateSource = store[STATE_SOURCE];
 
-      expect(isSignal(stateSource)).toBe(true);
-      expect(stateSource()).toEqual({ foo: 'bar' });
-      expect(typeof stateSource.update === 'function').toBe(true);
+      expect(isSignal(stateSource)).toBe(false);
+      expect(Object.keys(stateSource)).toEqual(['foo']);
+      expect(isSignal(stateSource.foo)).toBe(true);
+      assertStateSource(stateSource, {
+        foo: signal('bar'),
+      });
+      expect(typeof stateSource.foo.update === 'function').toBe(true);
 
       patchState(store, { foo: 'baz' });
 
-      expect(stateSource()).toEqual({ foo: 'baz' });
+      assertStateSource(stateSource, {
+        foo: signal('baz'),
+      });
     });
   });
 
@@ -97,10 +111,11 @@ describe('signalStore', () => {
 
       const store = new Store();
 
-      expect(store[STATE_SOURCE]()).toEqual({
-        foo: 'foo',
-        x: { y: { z: 10 } },
+      assertStateSource(store[STATE_SOURCE], {
+        foo: signal('foo'),
+        x: signal({ y: { z: 10 } }),
       });
+
       expect(store.foo()).toBe('foo');
       expect(store.x()).toEqual({ y: { z: 10 } });
       expect(store.x.y()).toEqual({ z: 10 });
@@ -178,7 +193,9 @@ describe('signalStore', () => {
 
       const store = new Store();
 
-      expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo' });
+      assertStateSource(store[STATE_SOURCE], {
+        foo: signal('foo'),
+      });
       expect(store.foo()).toBe('foo');
       expect(store.bar()).toBe('bar');
       expect(store.num).toBe(10);
@@ -236,7 +253,9 @@ describe('signalStore', () => {
 
       const store = new Store();
 
-      expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo' });
+      assertStateSource(store[STATE_SOURCE], {
+        foo: signal('foo'),
+      });
       expect(store.foo()).toBe('foo');
       expect(store.bar()).toBe('bar');
       expect(store.num).toBe(10);
@@ -279,7 +298,9 @@ describe('signalStore', () => {
         withMethods(() => ({ baz: () => 'baz' })),
         withProps(() => ({ num: 100 })),
         withMethods((store) => {
-          expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo' });
+          assertStateSource(store[STATE_SOURCE], {
+            foo: signal('foo'),
+          });
           expect(store.foo()).toBe('foo');
           expect(store.bar()).toBe('bar');
           expect(store.baz()).toBe('baz');
@@ -291,7 +312,9 @@ describe('signalStore', () => {
 
       const store = new Store();
 
-      expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo' });
+      assertStateSource(store[STATE_SOURCE], {
+        foo: signal('foo'),
+      });
       expect(store.foo()).toBe('foo');
       expect(store.bar()).toBe('bar');
       expect(store.baz()).toBe('baz');
@@ -372,7 +395,9 @@ describe('signalStore', () => {
         withProps(() => ({ num: 10 })),
         withHooks({
           onInit(store) {
-            expect(store[STATE_SOURCE]()).toEqual({ foo: 'foo' });
+            assertStateSource(store[STATE_SOURCE], {
+              foo: signal('foo'),
+            });
             expect(store.foo()).toBe('foo');
             expect(store.bar()).toBe('bar');
             expect(store.baz()).toBe('baz');