feat(signals): add delegatedSignal (#5151)

Closes #5121

Author: markostanimirovic

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

@@ -0,0 +1,99 @@
+import { computed, isSignal, signal } from '@angular/core';
+import { delegatedSignal } from '../src';
+
+describe('delegatedSignal', () => {
+  it('updates from source to delegated signal', () => {
+    const query = signal('');
+    const limit = signal(10);
+
+    const delegated = delegatedSignal({
+      source: () => ({ query: query(), limit: limit() }),
+      update: ({ query: q, limit: l }) => {
+        query.set(q);
+        limit.set(l);
+      },
+    });
+
+    expect(delegated()).toEqual({ query: '', limit: 10 });
+
+    query.set('ngrx');
+    expect(delegated()).toEqual({ query: 'ngrx', limit: 10 });
+
+    limit.set(25);
+    expect(delegated()).toEqual({ query: 'ngrx', limit: 25 });
+  });
+
+  it('updates from delegated signal to source', () => {
+    const query = signal('');
+    const limit = signal(10);
+
+    const delegated = delegatedSignal({
+      source: () => ({ query: query(), limit: limit() }),
+      update: ({ query: q, limit: l }) => {
+        query.set(q);
+        limit.set(l);
+      },
+    });
+
+    delegated.set({ query: 'ngrx', limit: 25 });
+    expect(query()).toBe('ngrx');
+    expect(limit()).toBe(25);
+
+    delegated.update((current) => ({ ...current, query: 'signals' }));
+    expect(query()).toBe('signals');
+    expect(limit()).toBe(25);
+  });
+
+  it('asReadonly returns a readonly signal backed by the source computation', () => {
+    const query = signal('');
+    const limit = signal(10);
+
+    const delegated = delegatedSignal({
+      source: () => ({ query: query(), limit: limit() }),
+      update: ({ query: q, limit: l }) => {
+        query.set(q);
+        limit.set(l);
+      },
+    });
+
+    const readonly = delegated.asReadonly();
+    expect(isSignal(readonly)).toBe(true);
+    expect('set' in readonly).toBe(false);
+    expect('update' in readonly).toBe(false);
+    expect(readonly()).toEqual({ query: '', limit: 10 });
+
+    query.set('ngrx');
+    expect(readonly()).toEqual({ query: 'ngrx', limit: 10 });
+  });
+
+  it('uses the provided equality function', () => {
+    const query = signal('');
+    const limit = signal(10);
+    let recomputeCount = 0;
+
+    const delegated = delegatedSignal({
+      source: () => ({ query: query(), limit: limit() }),
+      update: ({ query: q, limit: l }) => {
+        query.set(q);
+        limit.set(l);
+      },
+      equal: (a, b) => a.query === b.query,
+    });
+
+    const downstream = computed(() => {
+      recomputeCount++;
+      return delegated();
+    });
+
+    downstream();
+    expect(recomputeCount).toBe(1);
+
+    limit.set(25);
+    downstream();
+    expect(recomputeCount).toBe(1);
+
+    query.set('ngrx');
+    downstream();
+    expect(recomputeCount).toBe(2);
+  });
+});

modules/signals/src/delegated-signal.ts

@@ -0,0 +1,67 @@
+import {
+  computed,
+  untracked,
+  ValueEqualityFn,
+  WritableSignal,
+} from '@angular/core';
+
+export type DelegatedSignalConfig<T> = {
+  source: () => T;
+  update: (value: NoInfer<T>) => void;
+  equal?: ValueEqualityFn<NoInfer<T>>;
+};
+
+/**
+ * @description
+ *
+ * Creates a `WritableSignal` whose reads are delegated to a source computation
+ * and whose writes are delegated to an `update` callback.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Component, inject } from '@angular/core';
+ * import {
+ *   delegatedSignal,
+ *   patchState,
+ *   signalStore,
+ *   withMethods,
+ *   withState,
+ * } from '@ngrx/signals';
+ *
+ * const CounterStore = signalStore(
+ *   withState({ count: 0 }),
+ *   withMethods((store) => ({
+ *     updateCount(count: number): void {
+ *       patchState(store, { count });
+ *     },
+ *   })),
+ * );
+ *
+ * \@Component({
+ *   selector: 'app-counter',
+ *   template: '...',
+ *   providers: [CounterStore],
+ * })
+ * class Counter {
+ *   readonly #store = inject(CounterStore);
+ *
+ *   readonly count = delegatedSignal({
+ *     source: this.#store.count,
+ *     update: this.#store.updateCount,
+ *   });
+ * }
+ * ```
+ */
+export function delegatedSignal<T>(
+  config: DelegatedSignalConfig<T>
+): WritableSignal<T> {
+  const source = computed(config.source, { equal: config.equal });
+  const delegated = computed(source) as WritableSignal<T>;
+
+  delegated.set = (value) => config.update(value);
+  delegated.update = (updater) => config.update(updater(untracked(source)));
+  delegated.asReadonly = () => source;
+
+  return delegated;
+}

modules/signals/src/index.ts

@@ -1,5 +1,6 @@
 export { deepComputed } from './deep-computed';
 export { DeepSignal } from './deep-signal';
+export { delegatedSignal, DelegatedSignalConfig } from './delegated-signal';
 export { signalMethod, SignalMethod } from './signal-method';
 export { signalState, SignalState } from './signal-state';
 export { signalStore } from './signal-store';

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

@@ -0,0 +1,71 @@
+# DelegatedSignal
+
+The `delegatedSignal` function creates a `WritableSignal` whose reads are delegated to a `source` computation and whose writes are delegated to an `update` callback.
+It is useful for bridging two state containers, such as synchronizing SignalStore with Signal Forms as shown in the example below.
+
+<ngrx-code-example>
+
+```ts
+import { Component, inject } from '@angular/core';
+import {
+  form,
+  FormField,
+  minLength,
+  required,
+} from '@angular/forms/signals';
+import {
+  delegatedSignal,
+  patchState,
+  signalStore,
+  withMethods,
+  withState,
+} from '@ngrx/signals';
+
+type User = { id: number; name: string };
+
+const UsersStore = signalStore(
+  { providedIn: 'root' },
+  withState({ query: '', limit: 10, users: [] as User[] }),
+  withMethods((store) => ({
+    updateFilter(query: string, limit: number): void {
+      patchState(store, { query, limit });
+    },
+  }))
+);
+
+@Component({
+  selector: 'app-user-list',
+  imports: [FormField],
+  template: `
+    <input type="text" [formField]="filterForm.query" />
+    <input type="number" [formField]="filterForm.limit" />
+
+    <ul>
+      @for (user of users(); track user.id) {
+        <li>{{ user.name }}</li>
+      }
+    </ul>
+  `,
+})
+class UserList {
+  readonly #store = inject(UsersStore);
+
+  readonly users = this.#store.users;
+  readonly filter = delegatedSignal({
+    source: () => ({
+      query: this.#store.query(),
+      limit: this.#store.limit(),
+    }),
+    update: ({ query, limit }) => {
+      this.#store.updateFilter(query, limit);
+    },
+  });
+
+  readonly filterForm = form(this.filter, (schemaPath) => {
+    required(schemaPath.query);
+    minLength(schemaPath.query, 2);
+  });
+}
+```
+
+</ngrx-code-example>

projects/www/src/app/services/guide-menu.service.ts

@@ -98,6 +98,7 @@ export class GuideMenuService {
       ]),
       link('SignalState', '/guide/signals/signal-state'),
       link('DeepComputed', '/guide/signals/deep-computed'),
+      link('DelegatedSignal', '/guide/signals/delegated-signal'),
       link('SignalMethod', '/guide/signals/signal-method'),
       link('RxJS Integration', '/guide/signals/rxjs-integration'),
       link('FAQ', '/guide/signals/faq'),