feat(signals): add deepComputed function

[markostanimirovic]

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:

Closes #4202

Does this PR introduce a breaking change?

[ ] Yes
[x] No

[netlify]

✅ Deploy Preview for ngrx-io canceled.

Name	Link
🔨 Latest commit	c777c77
🔍 Latest deploy log	https://app.netlify.com/sites/ngrx-io/deploys/66f76b2388e73f00089e263d

[timdeschryver]

👍

[brandonroberts]

Q: Why wouldn't signalState use this?

[markostanimirovic]

Q: Why wouldn't signalState use this?

signalState provides a state source to the toDeepSignal function while deepComputed provides a computed signal:

// signalState
const stateSource = signal(initialState);
toDeepSignal(stateSource.asReadonly());

// deepComputed
toDeepSignal(computed(computation));

Instead of stateSource.asReadonly() we can do the following:

// signalState
deepComputed(computed(() => stateSource()));

But I don't see a benefit because the writable signal provides the asReadonly method.

[matheo]

@markostanimirovic what's the reasoning to restrict T to be an object if toDeepSignal supports "any"?
sometimes we have selectors that returns primitives or objects depending on the context 🤔

I mean, I know we should use this only with objects ideally
but our APIs with custom selectors may not have this restriction like:
https://github.com/niklas-wortmann/xstate-angular/blob/main/lib/xstate-ngx/src/lib/useSelector.ts#L25
we need there a deepSignal instead a simple signal for instance

[markostanimirovic]

Yes, that's a requirement. deepComputed uses the initial value to create a proxy for deeply nested signals.

[matheo]

@markostanimirovic it's basically an alias of toDeepSignal which doesn't have that requirement

[markostanimirovic]

If a signal with a primitive value is provided to the toDeepSignal function, it's just returned without further processing. Check the implementation: https://github.com/ngrx/platform/blob/main/modules/signals/src/deep-signal.ts#L26-L29

If a primitive type or union that contains primitive is passed to the DeepSignal type, it will be resolved to Signal:

import { DeepSignal } from '@ngrx/signals';

declare const s1: DeepSignal<string>; // type: Signal<string>
declare const s2: DeepSignal<{ foo: string } | string>; // type: Signal<{ foo: string } | string>

I could remove the extends object restriction from the deepComputed input, but then, users may be confused why the return type is resolved to Signal:

const s1 = deepComputed(() => 1 as number | { foo: string }); // type: Signal<number | { foo: string }>

In other words, there is no difference in this example whether you use computed or deepComputed.

With the extends object restriction it's clear - use deepComputed for objects, otherwise, it has no impact and you can go with computed.

[matheo]

yeah, we can do that with known types
but we cannot do that for generic APIs like the one I provided:
https://github.com/niklas-wortmann/xstate-angular/blob/main/lib/xstate-ngx/src/lib/useSelector.ts#L25

the user can be free to define the selector to get a slice of the state
and the Angular library needs to be able to return a deepSignal (or just a signal if it's a primitive value).

Any user using deepComputed in their components may know the type they are computing
and may realize that if they are passing a primitive value it's equivalent to a signal IMO.