[Complete] Sub-RFC 2: Signal APIs

[pkozlowski-opensource]

Sub-RFC 2: Signal APIs

Changelog

April 10, 2023

• Added asReadonly() to the WritableSignal API
• Changed effect() to schedule cleanup via onCleanup argument instead of returning a cleanup function (see fix(core): allow async functions in effects #49783)

Introduction

This discussion covers the API surface and some of the implementation details for Angular’s signal library.

Signals

Fundamentals

A signal is a value with explicit change semantics. In Angular a signal is represented by a zero argument getter function returning the current signal value:

interface Signal<T> {
  (): T;
  [SIGNAL]: unknown;
}

The getter function is marked with the SIGNAL symbol so the framework can recognize signals and apply internal optimizations.

Signals are fundamentally read-only: we can ask for the current value and observe change notification.

The getter function is used to access the current value and record signal read in a reactive context - this is an essential operation that builds the reactive dependencies graph.

Signal reads outside of the reactive context are permitted. This means that non-reactive code (ex.: existing, 3rd party libraries) can always read the signal's value, without being aware of its reactive nature.

Writable signals

The Angular signals library will provide a default implementation of the writable signal that can be changed through the built-in modification methods (set, update, mutate):

interface WritableSignal<T> extends Signal<T> {
  /**
   * Directly set the signal to a new value, and notify any dependents.
   *
   * Useful for changing primitive values or replacing data structures when
   * the new value is independent of the old one.
   */
  set(value: T): void;

  /**
   * Update the value of the signal based on its current value, and
   * notify any dependents.
   *
   * Useful for setting a new value that depends on the old value, such as
   * updating an immutable data structure.
   */
  update(updateFn: (value: T) => T): void;

  /**
   * Update the current value by mutating it in-place and notifying any
   * dependents.
   *
   * Useful for making internal changes to the signal's value without changing
   * its identity, such as pushing to an array stored in the signal.
   */
  mutate(mutatorFn: (value: T) => void): void;

  /**
   * Return a non-writable `Signal` which accesses this `WritableSignal` but does not allow
   * mutation.
   */
  asReadonly(): Signal<T>;
}

An instance of a settable signal can be created using the signal creation function:

function signal<T>(
  initialValue: T,
  options?: {equal?: (a: T, b: T) => boolean}
): WritableSignal<T>;

Usage example:

// create a writable signal
const counter = signal(0);

// set a new signal value, completely replacing the current one
counter.set(5);

// update signal's value based on the current one
counter.update(currentValue => currentValue + 1);

Signal and WritableSignal interfaces naming

In the current proposal the primary interface is named Signal. This represents a read-only value changing over time. We’ve chosen this name as it is short, discoverable and we are expecting it to be the most commonly imported and used interface. WritableSignal are somewhat specialized and adding “writable” to the name indicates that additional operations are permitted on those types of signals.

An alternative naming that we’ve considered is a pair of the ReadonlySignal (primary interface) and Signal (writable flavor). This aligns nicely with the TypeScript naming schema (ex. ReadonlyArray and Array). We were hesitant to use this naming as ReadonlySignal is far less discoverable and API authors might reach out for the Signal interface when their intention was to use ReadonlySignal, ex.:

import {Signal} from '@angular/core';

// API author requires a writable signal but it needs a read-only version 
// this might force API users to use type casts and / or convert computed to writable signals (!) 
function readFromSignalAndDoSth(signal: Signal) { …}

Discussion point 2a: given the trade-offs outlined here, would you prefer the Signal / WritableSignal naming pair or the ReadonlySignal / Signal one?

Equality

It is possible to, optionally, specify an equality comparator function. If the equality function determines that 2 values are equal, and if not equal, writable signal implementation will:

• block update of signal’s value
• skip change propagation.

The default equality function compares primitive values (numbers, strings, etc) using === semantics but treats objects and arrays as “always unequal”. This allows signals to hold non-primitive values (objects, arrays) and still propagate change notification, example:

const todos = signal<Todo[]>([{todo: 'Open RFC', done: true}]);

// we can update the list and still trigger change notification
// even without using immutable data
todos.update(todosList => {
    todosList.push({todo: 'Respond to RFC comments', done: false});
    return todoList;
});

Other implementations of the signal concept are possible. Both Angular or 3rd party libraries can create customized versions - as long as the underlying contract is maintained.

.set is the fundamental operation, .update is a convenience method

While the API surface has 3 different methods (set, update, mutate) of changing signal’s value, the .set(newValue) is the only fundamental operation that we need in the library. The other 2 methods are just syntactic sugar, convenience methods that could be expressed as .set.

Example of .update expressed with .set:

// create a writable signal
const counter = signal(0);

// update signal's value based on the current one
counter.update(c => c + 1);

// same code written without .update, using .set
counter.set(counter.get() + 1);

While everything could be expressed using .set only, the .update is often more convenient in certain use cases and hence were introduced in the public API surface.

Discussion point 2b: is the convenience of the .update worth introducing, given the larger public API surface?

.mutate is for changing values in-place

The .mutate method can be used to change a signal's value by mutating it. It is only useful for signals that hold non-primitive JavaScript values: arrays or objects. Example:

const todos = signal<Todo[]>([{todo: 'Open RFC', done: true}]);

// we can update the list and still trigger change notification
// even without using immutable data
todos.mutate(todosList => {
    todosList.push({todo: 'Respond to RFC comments', done: false});
});

The .mutate method will always send change notifications, bypassing the custom equality checks on the signal level.

The combination of the .mutate method and the default equality function makes it possible to work with both mutable and immutable data in signals. We specifically didn’t want to “pick sides” in the mutable / immutable data discussion and designed the signal library (and other Angular APIs) so it works with both.

Separation of read/write

In our signal library, we've made a design choice that the main reactive primitive (Signal<T>) is read-only. This means that it's possible to propagate reactive values to consumers without giving those consumers the ability to modify the value themselves.

The separation of read/write capabilities will encourage good architectural patterns for data flow in signal-based applications. This is because mutation of state must be centralized and happen through the owner of that state (the component or service which has the WritableSignal) instead of happening anywhere within the application.

Discussion point 2c: in some systems (e.g. Vue) reactive state is inherently mutable throughout the application. In other frameworks (e.g. SolidJS) this separation is enforced even more strongly. What do you think about our choice to separate readers and writers, and the architectural benefits or drawbacks of this approach?

Getter functions

In the Angular chosen implementation, a signal is represented by a getter function. Here are some of the advantages of using this API: :

• It's a built-in JavaScript construct, which makes signal reads consistent between TypeScript code and template expressions
• It clearly indicates that the primary operation on a signal is read
• It clearly indicates that something more than a plain property access is occurring
• It is syntactically very lightweight, which we feel is important because reading signals is an extremely common operation.

Drawbacks of getter functions

Getter functions do have some downsides, covered below.

Function calls in templates

Angular developers have learned over the years to be wary of calling functions from templates. This advice arose because of the way change detection runs frequently for components, and the potential for functions to easily hide computationally expensive logic.

These concerns don't apply to signal getter functions, which are efficient accessors that do minimal computational work. Calling signal getters repeatedly and frequently is not an issue.

However, using function calls for signal reads might initially confuse developers who are used to avoiding function calls in templates.

Interaction with type narrowing

TypeScript can narrow the type of expressions within conditionals. The following code will type-check even if user.name is nullable, because TypeScript knows that within the if body it can't be null:

if (user.name) {
  console.log(user.name.first);
}

However, TypeScript doesn't narrow function call return types, because it can't know that the function will return the same value every time it's called (like signal functions do). So the above example does not work with signals:

if (user.name()) {
  console.log(user.name().first); // type error
}

For this simple example, it's straightforward to extract user.name() to a constant outside of the if:

const name = user.name();
if (name) {
  console.log(name.first);
}

But this doesn't work in templates, as there is no way to declare an intermediate variable. There are some workarounds (we could create such variables automatically, for example).

Alternative syntaxes

We did consider different approaches and discarded them for the reasons listed below.

.value

const count = signal(0);

console.log('current value', count.value); // read
count.value = count.value + 1;             // write

.value is a potentially viable API but wasn't chosen for the following reasons:

• it looks writable, even though for many signals it may not be;
• it looks like a plain property access;
• it is more verbose when chaining multiple signals together, ex.: user.value.name.value.first vs user().name().first

However, there are some advantages as well. As .value is a plain property access, it does not suffer from the same type narrowing limitations that getter functions do.

Discussion point 2d: do the potential advantages of .value outweigh the disadvantages? Would you prefer that API?

Decorators

class MyComponent {
    @signal count = 0;
    
    increment() {
        console.log('current value', this.count); // read
        this.count = this.count + 1;              // write
    }
}

Decorators are great at providing metadata and / or syntactic sugar and several people suggested usage of decorators. We've explored this options and discarded it for the following reasons:

• we can only decorate classes and their members while we want to have signals usable in all places where JavaScript; expressions are allowed; also, it would limit our ability to further expand the way components can be authored;
• it would be impossible to pass signal instances around (with getters there is a clear distinction between a signal instance and signal's value);
• decorators specification is changing so it wasn't clear if we could build it on the legacy or the new decorators specification
• we would have to generate code for the decorated class members that would make the whole library more "magical" and Angular-specific.

Getter / setter tuple

const [count, setCount] = signal(0);

This approach has a desired property of segregating read and write operations. Unfortunately, we can't use destructuring assignment when defining properties in JavaScript classes:

class MyComponent {
    // this is not legal in JavaScript
    [count, setCount] = signal(0);
}

which made this API a non-starter.

Proxy

The initial steps of our reactivity story are focused on providing basic building blocks, the smallest primitives that we (and the Angular community) can build upon. Signals are such a building block that model reactivity for both primitive JavaScript values and complex objects. We can't proxy access to primitive values so we needed some other mechanism that could work for both primitive JavaScript values and objects / arrays.

Having said this, we do see potential usage of proxies in store-like constructs that encapsulate "bigger" JavaScript objects and / or collections. We might explore Proxy usage there and expect that community-driven, Proxy-based state management solutions will be available in the future.

Compile-time reactivity

Some UI frameworks take a compiler-based approach to reactivity: most notably Marko and Svelte. We did look into those methods and see many benefits, but at the end of the day we've decided to continue with a runtime-based solution.

Svelte-based reactivity results in an excellent developer experience, as the framework comes with built-in reactive language constructs. This greatly reduces "syntactical noise" and makes components code easier to write and read. Unfortunately this approach works only in components - as soon as we want to move reactive code outside of component boundaries (ex. to share it between components) we need to change the reactive paradigm and syntax by moving to Svelte stores. In Angular we wanted to work with the same reactive primitive across the entire application code base. Signals are usable in components, services and anywhere in the application, really.

Marko makes the reactive primitive available across the application but at the cost of "global analysis" in a dedicated compiler. In the past Angular was leaning heavily towards the "full knowledge" / "global analysis" compiler pass but it proved to be relatively slow and made Angular's compilation pipeline hard to integrate with the other tools in the JavaScript ecosystem. We want to shift Angular's to local, faster compilation. Global analysis of a reactive graph would go against this goal.

Computed signals

Computed signals create derived values, based on one or more dependency signal values. The derived value is updated in response to changes in the dependency signal values. Computed values are not updated if there was no update to the dependent signals.

Computed signals may be based on the values of other computed signals, allowing for multiple layers of transitive dynamic computation.

Example:

const counter = signal(0);

// creating a computed signal
const isEven = computed(() => counter() % 2 === 0);

// computed properties are signals themselves
const color = computed(() => isEven() ? 'red' : 'blue');

The signature of the computed is:

function computed<T>(
  computation: () => T,
  options?: {equal?: (a: T, b: T) => boolean}
): Signal<T>;

The computation function is expected to be side-effect free: it should only access values of the dependent signals (and / or other values being part of the computation) and avoid any mutation operations. In particular, the computation function should not write to other signals (the library's implementation will detect attempts of writing to signals from computed and raise an error).

Similarly to the writable signals, computed signals can (optionally) specify the equality function. When provided, the equality function can stop recomputation of the deeper dependency chain if two values are determined to be equal. Example (with the default equality):

const counter = signal(0);

// creating a computed signal
const isEven = computed(() => counter() % 2 === 0);

// computed properties are signals themselves
const color = computed(() => isEven() ? 'red' : 'blue');

// providing a different, even value, to the counter signal means that:
// - isEven must be recomputed (its dependency changed)
// - color don't need to be recomputed (isEven() value stays the same)
counter.set(2);

The algorithm chosen to implement the computed functionality makes strong guarantees about the timing and correctness of computations:

• Computations are lazy: the computation function is not invoked, unless someone is interested in (reads) its value.
• Computations are disposed of automatically: as soon as the computed signal reference is out of scope it is automatically eligible for garbage collection. No explicit cleanup boundaries and / or operations are exposed by the library.
• Computations are glitch-free: it is guaranteed that a given computation is executed a minimal number of times in response to dependencies change. The computation never executes with stale / intermediate dependency values and is immune to the famous “diamond dependency problem”. The glitch-free execution doesn’t require any explicit “transaction” or “batching” operations.

Branching in Computations

Computed signals keep track of which signals were read in their computations, in order to know when recomputation is necessary. This dependency set is dynamic, and self-adjusts with each computation. So in the conditional computation:

const greeting = computed(() => showName() ? `Hello, ${name()}!` : 'Hello!');

The greeting will always be recomputed if the showName signal changes, but if showName is false, the name signal is not a dependency of the greeting and will not cause it to recompute.

Effects

An effect is a side-effectful operation which reads the value of zero or more signals, and is automatically scheduled to be re-run whenever any of those signals changes.

The basic API for an effect has the following signature:

function effect(
  effectFn: (onCleanup: (fn: () => void) => void) => void,
  options?: CreateEffectOptions
): EffectRef;

Usage example:

const firstName = signal('John');
const lastName  = signal('Doe');

// This effect logs the first and last names, and will log them again when either (or both) changes. 
effect(() => console.log(firstName(), lastName()));

Effects have a variety of use cases, including:

• synchronizing data between multiple independent models
• triggering network requests
• performing rendering actions

Effect functions can, optionally, register a cleanup function. If registered, cleanup functions will be executed before the next effect run. The cleanup function makes it possible to "cancel" any work that the previous effect run might have started. Example:

effect((onCleanup) => {
    const countValue = this.count();

    let secsFromChange = 0;
    const id = setInterval(() => {
      console.log(
        `${countValue} had its value unchanged for ${++secsFromChange} seconds`
      );
    }, 1000);

    onCleanup(() => {
      console.log('Clearing and re-scheduling effect');
      clearInterval(id);
    });
});

Scheduling and timing of effects

Effects in Angular Signals must always be executed after the operation of changing a signal has completed.

Given the variety of effect use-cases, there is a wide spectrum of possible execution timings. This is why the actual effect execution timing is not guaranteed and Angular might choose different strategies. Application developers should not depend on any observed execution timing. The only thing that can be guaranteed is that:

• effects will execute at least once;
• effects will execute in response to their dependencies changes at some point in the future;
• effects will execute minimal number of times: if an effect depends on multiple signals and several of them change at once, only one effect execution will be scheduled.

Stopping effects

An effect will be scheduled to run every time one of its dependencies change. In this sense an effect is “always alive” and ready to respond to the changes in a reactive graph. Such “infinite” lifespan is obviously undesired as effects should be shut down when an application stops (or some other life-scope ends).

By default Angular effects lifespan is linked to the underlying DestroyRef in the framework. In other words: effects will try to inject the current DestroyRef instance and add register its stop function in there.

For situations where more control over lifespan scope is required, one can optionally pass the manualCleanup option to the effect creation:

effect(() => {...}, {manualCleanup?: boolean});

If this option is set, the effect won't be automatically destroyed even if the component/directive which created it is destroyed.

Effects can be explicitly stopped / destroyed by using the EffectRef instance returned from the effect creation function:

// create an effect and capture its EffectRef
const effectRef = effect(() => {...});

// later on, explicitly destroy / stop this effect
effectRef.destroy();

Effects writing to signals

We generally consider that writing to signals from effects can lead to unexpected behavior (infinite loops) and hard to follow data flow. As such any attempt of writing to a signal from an effect will be reported as an error and blocked.

This default behavior can be overridden by passing the allowSignalWrites options to the effect creation function, ex.:

const counter = signal(0);
const isBig = signal(false);

effect(() => {
    if (counter() > 5) {
        isBig.set(true);
    } else {
        isBig.set(false);
    }      
}, {allowSignalWrites: true});

Please note that computed is often a more declarative, straightforward and predictable solution to synchronizing data:

const counter = signal(0);
const isBig = computed(() => counter() > 5);

Frequently asked questions

Can I create signals outside of components / stores / services?

Yes! You can create and read signals in components, services, regular functions, top-level JS module code - anywhere you might need a reactive primitive.

We see this as a huge benefit of signals - reactivity is not exclusively contained within components. Signals empower you to model data flow without being constrained by the visual hierarchy of a page

Any guidelines when it comes to granularity of signals?

This is a common question! Given a non-trivial object, it is not obvious how many signals should be created: one signal for the entire object? Or maybe one signal for each individual property?

Currently we can't provide hard-and-fast rules here but would suggest starting with more coarse-grained objects (one signal for the entire object) and split up if necessary. While it is tempting to go with many fine grained signals it is often not practical (creating all those signals can get verbose!) and - counterintuitively - not that performant (creating and maintaining signals in memory has associated cost).

Should I use mutable or immutable data in my signals?

Signals work great with both, we don't want to "pick sides" but rather let developers choose the approach that works best for their teams and use-cases.

Signals library

Why a new library instead of using an existing one?

Most of the existing implementations are tightly integrated with the underlying framework needs. From the Angular perspective we want to pick and choose semantics and an API surface that matches our needs. Some examples where we do have clear preferences:

• lazy evaluation of computed properties fits well into the per-component change detection model
• we need an API where a signal’s getter and setter are co-located on the same object reference so it can be used as a field / property on the existing class-based Angular components
• we want to control the timing of effects execution (probably we will have different types of effects executed at the different points in time related to component lifecycle).
• we can tie effect lifecycles to components, and clean up effects when components are destroyed

Finally, having direct dependency on the 3rd party library comes with non-trivial constraints: one needs to be aligned on concepts, implementation details and release scheduling.

On the other hand, reactive signal libraries tend to be fairly small, both in terms of the conceptual / API surface and implementation (~500 LoC).

How is it different from MobX, SolidJS, Vue reactivity?

Angular signals belongs to the same family of approaches and share core characteristics, same philosophy and architecture:

• declarative, push-based, synchronous reactivity
• there is a dynamic graph of dependencies that gets built and re-wired as the application runs (dependencies are auto-tracked)
• overlapping conceptual surface with the 3 main building blocks (signals, computed, effect)

Core implementation ideas are also the same:

• computations register themselves on a (global) stack and accessed (read) signals inspect this stack to register themselves as dependencies (this is why signals are expressed as some form of a getter function)
• great care is taken to make sure that computations are executed once and only once in response to dependencies change (“glitch-free execution”)

Despite the large number of similarities, there are substantial differences between various implementations: both on the conceptual, API and algorithmic levels:

• timing and order of re-recomputation of derived values - most notably, there is clear distinction between the eager vs. lazy computed values
• scheduling and timing of effects executions varies widely
• cleanup / destroy logic is different
• internal algorithms and data structures are different (especially when it comes to assuring glitch-free execution and cleanup), resulting in different performance characteristics
• API surface is different:
  • main distinction comes from using proxies vs. getter functions
  • many other subtle naming and API signature differences.

Will you publish the library as a separate npm package?

We did discuss the possibility of publishing an independent signal library but didn't do so initially for the following reasons:

• it is still in the early stages and we don't want to publish before going through the RFC feedback and settling on the exact API shape
• there are parts of the library that deeply integrate with the Angular internals (effects scheduling and cleanup is the most notable example)
• there is some practical friction in publishing a new package

We will definitely consider publishing a separate NPM package if there is value in it - please leave feedback in the RFC if you would like to see Angular signals library to be available as a separate NPM package.

[DavidANeil]

Discussion point 2d: do the potential advantages of .value outweigh the disadvantages? Would you prefer that API?

In my ~6 years of using Signals, they have always been with the get value() / .value api.
Personally I find the function call API more readable, though the issues with type narrowing would probably make me wish for .value again.
There are also considerations with the google closure compiler (and probably other minifiers), where a getter is assumed to be side-effect free, allowing for unused values to be removed in dead code elimination passes. I doubt this actually leads to significant bundle-size improvements, though I could definitely imagine up a case where it does.

I wonder if it would be worth it to just expose both on the interface? That way we could use () in most cases, and .value when we need to help TS. Though this just feels like a design cop-out....

If it came down to it, I think I would prefer only having .value, if I had to choose.

[Harpush]

@alxhub can you provide an example? I am not sure I understand how this will work...

[timonkrebs]

Would it be possible to introduce some kind of variables in the template for signals? That would fix all the problems... Maybe something like the let directive: https://ngrx.io/guide/component/let

[lucas-paganini-unvoid]

I deeply care about type narrowing working properly and don't mind declaring an extra variable for it.

The problem (IMHO) is when I need type narrowing in a component template because declaring a variable in the template isn't as clean as it is in a regular TypeScript context.

@alxhub Or template type-checking will need to narrow signals :)

That said, if Angular provides proper type narrowing in the template without the need for an extra template variable, I'd be super happy with the function call API 🙂

[ShawnTalbert]

Can we not just have native JS getters and setters somehow for this? I do not like the idea of calling a function to 'get' the value, and some other named function to 'set' a value.

One reason I enjoy Angular is the simple data binding; including two-way. I would like my template experience to remain mentally simple - I shouldn't have to even consider that the reactivity design has changed under the covers for most cases.

i.e. I would like to bind using plain property names if possible.

<element [something]='foo' ></element>

If angular needs to turn foo into a signal, fine, but don't clutter my end-user experience with that reactivity detail.
The less I need to think about the low level primitives the more I get to focus on solving the application business requirements.

Would it be possible (or rather would I be forced) to do something like this and get 'simple' data binding expressions free of function calls?

class A {

 get foo() {
  return signal(0)
 }

 set foo(v) {
   signal.set(v)
 }
}

[pkozlowski-opensource]

Can we not just have native JS getters and setters somehow for this?

We could wrap object properties into getters / setters but this technique doesn't work for primitive values. What you are proposing with the explicit getter / setter function on a component instance is pretty verbose.

If angular needs to turn foo into a signal, fine, but don't clutter my end-user experience with that reactivity detail.

Actually it was our conscious choice to have reactive values syntax stand out - reactive values are different as compared to regular variables and we believe that it should be syntactically visible.

[robert-king]

awesome work from the Angular team, this is amazing to see :)

1. what happens if a computed or effect throws an error, does it recover?

const isEven = computed(() => {
         if (counter() == 42) {
              throw new Error('oops');
         }
         return   counter() % 2 === 0 
});

2. for the type narrowing, perhaps you could have mySignal.toSignalWithValueSnapshot() but with a better name.

it would be interesting to see something like a deferred signal that gets created once the signal has an initialValue. Perhaps you could still operate on deferred signals, but anything derived from them would also be deferred, but you can avoid nulls. If you try to use a deferred signal within a context that doesn't understand deferred signals, then the get() value is nullable. but in smart contexts, e.g. computed, effect, a suspense list template with loading outlet, etc, the get() value isn't nullable since the context waits for all child deferred signals to be ready. edit: probably just use the awesome new lifecycle methods in the other RFC :)

[pkozlowski-opensource]

what happens if a computed or effect throws an error, does it recover?

No, not currently. A computed would memoize an error and keep throwing it until one of the dependencies change and the computation function is invoked again.

There is no special treatment of exceptions in effects, for now - it is a good, open question about desired semantics there.

[e-oz]

Discussion point 2a: given the trade-offs outlined here, would you prefer the Signal / WritableSignal naming pair or the ReadonlySignal / Signal one?

My vote goes for "Signal / WritableSignal".
Developers were taught to use const instead of let by default, for a good reason, so they can be taught to use readonly signals by default.

Discussion point 2b: is the convenience of the .update worth introducing, given the larger public API surface?

Yes.

Discussion point 2c

I'm happy to see that you are helping developers to avoid the chaos that writeable-by-default signals could create. With this approach, signals are not just a global registry of BehaviourSubjects (and it's good to avoid this mess).

Edited: forget about it, I just noticed that signal() returns a WriteableSignal, so it will be a mess indeed.

Discussion point 2d: do the potential advantages of .value outweigh the disadvantages? Would you prefer that API?

Yes. It's also easy to mark as "non-writeable" using TS.

[kbrilla]

Wasn't DeepReadonly dropped in #49644?

[JeanMeche]

Yeah Pavel removed it himself, he probably forgot to update the RFC 😊

[pkozlowski-opensource]

Oh, I though that I've removed all the references to DeepReadonly... What did I miss?

Or, maybe it is misunderstanding around #49683 (reply in thread)?

[JeanMeche]

@alxhub removed it for you, cf his edit on the RFC 😉

[e-oz]

Signals are fundamentally read-only

Then why are you returning WriteableSignal from signal()?

[e-oz]

But we all know what 99% of users will do and what libraries will expect.

[pkozlowski-opensource]

Yeh, I can totally see how it is confusing...

So, ironically, most of the signals (computed, fromObservable, input, ...) are read-only - in the sense that the getter function don't have set / update. In this sense the signal creation function is special.

Then, none of the signals is deeply read-only, that is, we don't prevent mutation of objects contained in a signal.

I can totally see how it is very subtle and can be confusing, I will see how to revisit the RFC text. But the bottom line that there are 2 read-only notations that we are discussing here:

• ability to set / update signal's value
• ability to deeply-mutate objects / arrays if those happen to contained in the signal

[e-oz]

At least inputs are readonly. And computed don't allow nested effects. These are good points.

[dvalentine314]

ohh. It's the interface that makes it read only by only providing the getter of the signal object. Not the object itself. Did I get that right?

[alxhub]

@dvalentine314 not exactly. computed() for example returns a signal that does not have .set or any other mutation operation, even if you cast it to any.

[jgbpercy]

The type narrowing in templates issue is the first part of reading the RFCs so far that has given me real pause. Gut feel without having worked with this in detail is that .value (just .val maybe?) is worth it, if it's the best way to avoid that sharp edge.

That said, you allude to "some workarounds" that might avoid the issue while keeping the getter syntax? Perhaps you could go into more detail on that?

Finally, big thanks to you and everyone else on the team for the hard work on this process :)

[alxhub]

Yes - Angular defines the type semantics in its templates, so we could get TypeScript to understand that signal values won't change across the template execution.

[jgbpercy]

Awesome... Well in that case all I'd say is this seems like a necessary step if the getter API is used 👍

[jgbpercy]

Also I do think the RFC could be clearer on this point, in the last sentence under "Interaction with type narrowing"

See the thread on this comment #49683 (comment)

[JeanMeche]

What about a deep-set with a dotted path argument ?

const mySignal = signal({a: {b: {c: {d: {e: 'foo'})
mySignal.set('a.b.c.d.e', 'bar') 

[pkozlowski-opensource]

This could be built on top of the basic primitive introduced here. Having said this I don't think we want to propose / maintain any special way of writing JavaScript getters :-)

[alxhub]

Referring to property names via strings is also a bit sketchy if your code needs to be compatible with advanced optimizations (e.g. Google's Closure Compiler), since property renaming can't detect string references to names like this.

[cexbrayat]

I'd like to point out an edge case with effect and async/await.
With the current design you can use a promise in an effect, but can't use the async/await syntax:

this.query = signal('');
this.fetchEffect = effect(async () => {
  const response = await fetch('/users?query=' + this.query())
  this.users.set(await response.json());
}))

The example above does not compile as effect expects () => void | EffectCleanupFn and not () => Promise<void>:

The workaround is to use then for now, but that feels a bit weird when you're used to async/await

Even if the types are easily fixable, the current design uses the return value of the effect as the cleanup function, which is incompatible with the typical use-case where you want to abort a request:

this.fetchEffect = effect(async () => {
  const controller = new AbortController();
  const response = await fetch('/users?query=' + this.query())
  this.users.set(await response.json());
  return () => controller.abort();
}))

FWIW Vue uses another approach, and the function passed towatchEffect (the effect of Vue) is called with onCleanup as a parameter:

watchEffect(async (onCleanup) => {
  const controller = new AbortController();
  const response = await fetch('/users?query=' + query.value)
  users.value = await response.json();
  onCleanup(() => controller.abort())
})

[dgp1130]

We've discussed providing an AbortSignal to effects which I think would be really ergonomic here.

The bigger problem is that effect() doesn't work well with async anyways, given that signals can only track synchronous usages. For example:

effect(async () => {
  console.log(foo());
  await new Promise((resolve) => { setTimeout(resolve, 1_000); });

  // This is an untracked usage of `bar()` because it happens asynchronously, effect will _not_ rerun when `bar.set()` is called.
  console.log(bar());
});

There are workarounds for sure if you invoke bar() synchronously but then use its result asynchronously for example. But it gets complicated fast and becomes difficult to enforce. This is where the "synchronous reactivity" becomes relevant. In general, an effect() with an async callback won't behave the way you might intuitively expect.

[pkozlowski-opensource]

@cexbrayat #49783

[timonkrebs]

there are workarounds for sure if you invoke bar() synchronously but then use its result asynchronously for example. But it gets complicated fast and becomes difficult to enforce. This is where the "synchronous reactivity" becomes relevant. In general, an effect() with an async callback won't behave the way you might intuitively expect.

@pkozlowski-opensource
Is there any consideration on how to handle this? Now that async function calls in effects seem to be encouraged by angular? Does angular expect all angular devs to be aware of these edge cases?

[yjaaidi]

Instead of mutate(), why not add an option like skipEqualityChecks to set() and update() as primitives and then build up on top later.

items.mutate(value => value.push(item));

// could be replaced by

items().push(item);
items.set(items, {skipEqualityChecks: true});

// or even by
items.update(value => {
  value.push(item)
  return value;
}, {skipEqualityChecks: true});

While this is a bit more verbose, it is more explicit and can be wrapped in a mutate() function or method for those who prefer it.

IMO, an option like skipEqualityChecks is more explicit on what's happening than mutate().

[yjaaidi]

I am really afraid of what people will think mutate() is doing.
Before reading the docs and due to the "magical" nature of signals, one might think that it is tracking mutations using immer or similar.

[alxhub]

I have a different take: APIs should capture intention, not implementation semantics.

.mutate states your intention - "I'm going to mutate the value stored in this signal", and clearly wraps the operation with this intention:

data.mutate(array => {
  array.push(newData);
});

.set with a flag doesn't indicate the intention whatsoever - in fact the actual call to .set doesn't give any indication of why we're setting to the same thing:

// first, make a sketchy mutation on the value inside the signal.
// if we just do this and forget to set the signal afterwards, we've just caused a bug.
data().push(newData);

// why am i setting the signal to the same value? why am i skipping the equality check?
// this code only communicates what it's doing, not _why_.
data.set(data(), {skipEqualityCheck: true});

[Harpush]

@alxhub Connected to a suggestion I made but did you consider making a different default equality between set/update and mutate due to the different intentions?

[pkozlowski-opensource]

did you consider making a different default equality between set/update and mutate due to the different intentions?

No. As explained in the RFC, .mutate bypasses (ignores) equality checks altogether.

One thing we did consider is creating a pair of signal creation methods:

• const counter = signal(0) which would have set + update and would accept an equality function
• const list = mutableSignal([]) which would have mutate and would NOT accept an equality function

We wasn't sure if this is the best approach, though

[Harpush]

@pkozlowski-opensource So I don't understand why the equality check doesn't check object equality. It seems that if .mutate bypasses equality then we can safely assume immutability for set and update. Especially as mentioned by @alxhub the following are bad practices:

const sg = signal({a: 2, b: 'str'});

const val = sg();
val.a = 6;
sg.set(val);

sg.update(v => {
  v.a = 6;
  return v;
})

Instead this is the best practice:

const sg = signal({a: 2, b: 'str'});

sg.mutate(v => v.a = 6);

Anyway you could go the other way around too with immutableSignal.

[yjaaidi]

As mentioned by @JeanMeche in a discussion above, it would be nice to have an asReadonly().
Right now, the workaround is using computed() but it is uselessy memoizing and polluting the graph.

const name = signal('foo');
const readOnlyName = name.asReadonly(); // no `set()`, `update()` or `mutate()` functions

// is better and more efficient than
const name = signal('foo');
const readOnlyName = compute(() => name());

[e-oz]

Because there are no method/function signatures in that quote.
https://developer.mozilla.org/en-US/docs/Glossary/Signature/Function

[timonkrebs]

Because there are no method/function signatures in that quote.
https://developer.mozilla.org/en-US/docs/Glossary/Signature/Function

That is not really an explanation why you would care so much about method signatures (more explicitly about the return type) if you do not want to see it (the return type).

I was also wondering what the .asReadonly() would actually do. Is it only a cast or is it converting it into a computed or is it converting it into some third thing? But then probably not that important...

[mlc-mlapis]

I was also wondering what the .asReadonly() would actually do.

It's not only casting. The result won't have any of the methods of .set, .update, .mutate for sure.

[JeanMeche]

It's not only casting. The result won't have any of the methods of .set, .update, .mutate for sure.

Confirmed by the Sourcecode.

angular/packages/core/src/signals/src/signal.ts

Lines 117 to 122 in c029c67

	asReadonly(): Signal<T> {
	if (this.readonlySignal === undefined) {
	this.readonlySignal = createSignalFromFunction(this, () => this.signal());
	}
	return this.readonlySignal;
	}

[michaelfaith]

You don't need WritableSignal type in declarations, it can be inferred. Methods signatures, return types and generics are the places where you'll need typing, and Signal as readonly signal would be a much better fit because it's exactly what any function should expect in arguments most of the time - readonly signal.

I agree. I feel like this is more ergonomic. I don't think anyone would be confused by asReadonly returning Signal type. If they never even knew ReadonlySignal was a consideration, then it shouldn't cause anyone to stumble

[DavidANeil]

Other implementations of the signal concept are possible. Both Angular or 3rd party libraries can create customized versions - as long as the underlying contract is maintained.

We have an in-house implementation of signals that has widespread usage in our codebase, currently we integrate it with Angular through an @Pipe (basically instead of [data]="signal()" we do [data]="signal | signalValue", and signalValue essentially is an effect that just does a .markForCheck()), it would be very cool if our two systems could "just work" together, without any developer intervention, though we have some invariants that might make this difficult:

1. Our signal implementation cannot strongly depend on Angular.
2. Our signal implementation cannot afford to be slowed down by calling out to Angular in addition to its own stale-tracking.

These invariants would make it unlikely that we would be able to just call Angular's functions, like setActiveConsumer, from our implementation.

I wonder if Angular might consider allowing the Signal implementations to be provided as an option during application bootstrap, similar to how NgZone is today.
This should allow us to have "native" support for our existing signals (which means skipping at least 1 @Pipe per template binding, and 2 Angular Signals per internal Signal).
I am imagining that I would pass in some functions that angular calls when it wants to do certain signal operations, like createWriteableSignal, createComputedSignal.
Or it could be on a lower level, like:
setActiveConsumer, producerAccessed, consumerPollValueStatus, etc.

---

Appendix:
What our integration would probably end up looking like if we didn't have "native" support.

const signalMap = new WeakMap<LucidSignal<any>, AngularSignal<any>>();

@Pipe({name: 'toAngularSignal', pure: true})
export class ToAngularSignal implements PipeTransform {
    public transform<T>(lucidSignal: LucidSignal<T>): AngularSignal<T> {
        if (signalMap.has(lucidSignal)) {
            return signalMap.get(lucidSignal)!;
        }
        const valueChangedSignal = signal(lucidSignal.valueId); // construct an Angular signal
        lucidSignal.effect(() => {
            // Anytime our signal updates, mark the Angular signal as updated.
            // This indirection is important because our `effect` is synchronous upon the signal being marked stale.
            valueChangedSignal.set(lucidSignal.valueId);
        });
        const newSignal = computed(() => {
            // Depend on the valueId, as a dependency only.
            sinkValue(valueChangedSignal());
            // but return the underlying lucidSignal value.
            return lucidSignal();
        });
        signalMap.set(lucidSignal, newSignal);
        return newSignal;
    }
}

Uses would look like this:

<div>
    {{(mySignal | toAngularSignal)()}}
</div>

[alxhub]

This is fascinating, and I'd love to learn more!

I don't think we can make our signal library swappable though, for the same reasons that we didn't use an "off-the-shelf" implementation - the actual internals are tied strongly to Angular, and we rely a lot on those assumptions.

This indirection is important because our effect is synchronous

For example, this kind of thing would completely break, as Angular wants to run effects during change detection.

We do want signals to be interoperable with other reactivity systems though, so I'd be interested in exploring this use case more. One thing we've discussed is how much we want to expose the signal system internals, and I could see some usefulness of that here.

[DavidANeil]

This indirection is important because our effect is synchronous

We don't actually call it effect, (we call it .addEventListener(SignalInvalidated 😂)
If we needed to create a contract-compliant implementation of it for the sake of integrating with Angular, I think we could do that no issue.

the actual internals are tied strongly to Angular

This is why the "internals" would need to passed into the bootstrapper, though honestly that sounds like a pain, what seems much more tenable is just publishing them in a different package, so +1 to the "publishing a separate NPM package" path.
(Re "Our signal implementation cannot strongly depend on Angular": we (in essence) enforce this with a test that bazel query 'somepath(certain:app, @npm//@angular/core)' is the empty set, a standalone package wouldn't trigger this)

I might create an alternate implementation or two of Angular's Signal, though I might have to pull some of the "internal functions" like producerPollStatus back out of the class, like they were in the initial prototype, otherwise it looks really hard to have an alternate implementation.

[timonkrebs]

I wonder if Angular might consider allowing the Signal implementations to be provided as an option during application bootstrap, similar to how NgZone is today.

This would be so great. I really see a lot of potential in this. For several reasons I see why this could be very handy.

• controlling the behaviour of computeds (specialized caching mechanisme for specific usecase
• controlling sheduling of effects
• give more control to devs with pipes/directives
• and serialization etc... thinking about metaframeworks.

[alxhub]

I don't think this is something we could support. Angular Signals are designed with private APIs specifically for the framework's use cases, such as interoperating with the current zone-based change detection system. That kind of usage can't really be made pluggable with third party implementations.

[timonkrebs]

I don't think this is something we could support. Angular Signals are designed with private APIs specifically for the framework's use cases, such as interoperating with the current zone-based change detection system. That kind of usage can't really be made pluggable with third party implementations.

I do see that it is probably not feasible to get this for angular. At least not at the moment.
But maybe it would be possible to get closer to that level of control for some of the points I mentioned.

[Harpush]

The idea of equality can be troublesome and requires passing it every time. How about making assumptions instead:

1. Set and update are always assuming immutability
2. Mutate always assume mutability.

And remain with the custom equal or a flag to override it

[Harpush]

Concerning computed I can create my own immutableComputed but I guess many will do it - so maybe include it inside the core library?

[nivekcode]

Discussion point 2a: given the trade-offs outlined here, would you prefer the Signal / WritableSignal naming pair or the ReadonlySignal / Signal one?

I like Signal / WritableSignal, but since creating a new signal with const a = signal('foo') allows us to update a via set, update or mutate, I would go for Signal / ReadonlySignal.

The naming feels more consistent.

[Bjeaurn]

Still diving into the whole RFC and reading it as a whole. But one of the first ideas I got after seeing some examples in the "wild" (on Twitter), I figured that the Signal fn usage in the HTML could be counterintuitive with the current set of best-practices of trying to prevent the usage of functions in the HTML.

Constructions like this <div *ngIf="example()">{{ example() }}</div> might feel bloated and even counter-intuitive and going against current conventions and best practices as they live within the Angular ecosystem.

A simple solution to this could be of course to have Signals as considered and adding a SignalPipe in whatever form. So the existing set of conventions surrounding the AsyncPipe and constructions like <div *ngIf="example | signal as e">{{ e }}</div> would still be possible and even considered good practice.