feat(signals): add withLinkedState

Generates and adds the properties of a `linkedSignal`
to the store's state.

## Usage Notes:

```typescript
const UserStore = signalStore(
  withState({ options: [1, 2, 3] }),
  withLinkedState(({ options }) => ({ selectOption: () => options()[0] ?? undefined }))
);
```

The resulting state is of type `{ options: number[], selectOption: number | undefined }`.
Whenever the `options` signal changes, the `selectOption` will automatically update.

For advanced use cases, `linkedSignal` can be called within `withLinkedState`:

```typescript
const UserStore = signalStore(
  withState({ id: 1 }),
  withLinkedState(({ id }) => ({
    user: linkedSignal({
      source: id,
      computation: () => ({ firstname: '', lastname: '' })
    })
  }))
)
```

## Implementation Notes

We do not want to encourage wrapping larger parts of the state into a `linkedSignal`.
This decision is primarily driven by performance concerns.

When the entire state is bound to a single signal, any change - regardless of which part -
- is tracked through that one signal.
This means all direct consumers are notified, even if only a small slice of the state actually changed.

Instead, each root property of the state should be a Signal on its own. That's why
the design of `withLinkedState` cannot represent be the whole state.

Author: rainerhahnekamp

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

@@ -293,6 +293,27 @@ describe('StateSource', () => {
         TestBed.flushEffects();
         expect(executionCount).toBe(2);
       });
+
+      it('does not support a dynamic type as state', () => {
+        const Store = signalStore(
+          { providedIn: 'root' },
+          withState<Record<number, number>>({}),
+          withMethods((store) => ({
+            addNumber(num: number): void {
+              patchState(store, {
+                [num]: num,
+              });
+            },
+          }))
+        );
+        const store = TestBed.inject(Store);
+
+        store.addNumber(1);
+        store.addNumber(2);
+        store.addNumber(3);
+
+        expect(getState(store)).toEqual({});
+      });
     });
 
     it('does not support a dynamic type as state', () => {

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

@@ -0,0 +1,158 @@
+import { expecter } from 'ts-snippet';
+import { compilerOptions } from './helpers';
+
+describe('patchState', () => {
+  const expectSnippet = expecter(
+    (code) => `
+        import { computed, inject, linkedSignal, Signal, signal } from '@angular/core';
+        import {
+          patchState,
+          signalStore,
+          withState,
+          withLinkedState,
+          withMethods
+        } from '@ngrx/signals';
+
+        ${code}
+      `,
+    compilerOptions()
+  );
+
+  it('does not have access to methods', () => {
+    const snippet = `
+      signalStore(
+        withMethods(() => ({
+          foo: () => 'bar',
+        })),
+        withLinkedState(({ foo }) => ({ value: foo() }))
+      );
+      `;
+
+    expectSnippet(snippet).toFail(/Property 'foo' does not exist on type '{}'/);
+  });
+
+  it('does not have access to STATE_SOURCE', () => {
+    const snippet = `
+      signalStore(
+        withState({ foo: 'bar' }),
+        withLinkedState((store) => {
+          patchState(store, { foo: 'baz' });
+          return { bar: 'foo' };
+        })
+      )
+      `;
+
+    expectSnippet(snippet).toFail(
+      /is not assignable to parameter of type 'WritableStateSource<object>'./
+    );
+  });
+
+  it('cannot return a primitive value', () => {
+    const snippet = `
+      signalStore(
+        withLinkedState(() => ({ foo: 'bar' }))
+      )
+      `;
+
+    expectSnippet(snippet).toFail(
+      /Type 'string' is not assignable to type 'WritableSignal<unknown> | (() => unknown)'./
+    );
+  });
+
+  it('resolves to a normal state signal with automatic linkedSignal', () => {
+    const snippet = `
+      const UserStore = signalStore(
+        { providedIn: 'root' },
+        withLinkedState(() => ({ firstname: () => 'John', lastname: () => 'Doe' }))
+      );
+
+      const userStore = new UserStore();
+
+      const firstname = userStore.firstname;
+      const lastname = userStore.lastname;
+    `;
+
+    expectSnippet(snippet).toSucceed();
+
+    expectSnippet(snippet).toInfer('firstname', 'Signal<string>');
+    expectSnippet(snippet).toInfer('lastname', 'Signal<string>');
+  });
+
+  it('resolves to a normal state signal with manual linkedSignal', () => {
+    const snippet = `
+      const UserStore = signalStore(
+        { providedIn: 'root' },
+        withLinkedState(() => ({
+          firstname: linkedSignal(() => 'John'),
+          lastname: linkedSignal(() => 'Doe')
+        }))
+      );
+
+      const userStore = new UserStore();
+
+      const firstname = userStore.firstname;
+      const lastname = userStore.lastname;
+    `;
+
+    expectSnippet(snippet).toSucceed();
+
+    expectSnippet(snippet).toInfer('firstname', 'Signal<string>');
+    expectSnippet(snippet).toInfer('lastname', 'Signal<string>');
+  });
+
+  it('should set stateSignals as DeepSignal for automatic linkedSignal', () => {
+    const snippet = `
+      const UserStore = signalStore(
+        { providedIn: 'root' },
+        withLinkedState(() => ({
+          user: () => ({ id: 1, name: 'John Doe' }),
+          location: () => ({ city: 'Berlin', country: 'Germany' }),
+        }))
+      );
+
+      const userStore = new UserStore();
+
+      const location = userStore.location;
+      const user = userStore.user;
+    `;
+
+    expectSnippet(snippet).toSucceed();
+
+    expectSnippet(snippet).toInfer(
+      'location',
+      'DeepSignal<{ city: string; country: string; }>'
+    );
+    expectSnippet(snippet).toInfer(
+      'user',
+      'DeepSignal<{ id: number; name: string; }>'
+    );
+  });
+
+  it('should set stateSignals as DeepSignal for manual linkedSignal', () => {
+    const snippet = `
+      const UserStore = signalStore(
+        { providedIn: 'root' },
+        withLinkedState(() => ({
+          user: linkedSignal(() => ({ id: 1, name: 'John Doe' })),
+          location: linkedSignal(() => ({ city: 'Berlin', country: 'Germany' })),
+        }))
+      );
+
+      const userStore = new UserStore();
+
+      const location = userStore.location;
+      const user = userStore.user;
+    `;
+
+    expectSnippet(snippet).toSucceed();
+
+    expectSnippet(snippet).toInfer(
+      'location',
+      'DeepSignal<{ city: string; country: string; }>'
+    );
+    expectSnippet(snippet).toInfer(
+      'user',
+      'DeepSignal<{ id: number; name: string; }>'
+    );
+  });
+});