RFC: Use signals for state management

[Legioth]

The architectural concept of using "signals" for state management is establishing itself as a general approach throughout the frontend development ecosystem. There are some variations in syntax between signal.value and [getterFunction, setterFunction] but the overall approach is the same with fine-grained reactivity and automatic tracking of dependencies. Specifically for Hilla, both React and Lit (as of version 3.0) are compatible with @preact/signals which uses the signal.value syntax.

Signals 101

As a simple example, a counter button using signals can be implemented like this in React

function Counter() {
  const counter = useSignal(0);
  return <button onClick={() => counter.value++}>Click count: {counter}</button>
}

The power of signals is that a signal can just as well be shared between multiple independent components so that counter would not have to be scoped to a single component instance but instead be shared between multiple component instances. In that case, all visible components would be updated whenever any component changes the signal value.

// In global.ts
export const counter = signal(0);

// In Counter.tsx
import { counter } from '../global.js';

Compared to the default useState approach in React, the use of signals offers several benefits:

• computed() and effect() are automatically updated whenever any dependency changes. This stands in contrast to useMemo and useEffect that need explicitly defined dependency arrays.
• You can easily share state between different parts of the application without "props drilling" and without an explicitly defined useContext. As a related performance benefit, redundant invocations of the render function can also be avoided without any additional effort from the developer.
• Hilla APIs designed around signals can more easily be ported to different rendering frameworks. We spent a significant effort adopting Hilla's Lit-based form binding library to integrate nicely with the default state management mechanisms in React. Even with this effort, there are some performance tradeoffs since the whole form needs to be rendered again whenever any field value changes. A form binding library based on signals would have been much easier to adopt to React. The same also applies for the new <AutoGrid>, <AutoForm> and <AutoCrud> functionality that is now designed specifically for useState and cannot easily be ported to Lit.

Adopting signals as the primary approach for UI state management would mean that we use signals in tutorials and documentation examples in place of useState and that we design new functionality based on signals.

Full stack shared signals

As a full-stack framework, Hilla can provide some unique additional benefits by making it easy to synchronize signal values between the browser and the server.

Multi-user signals

One way of reasoning about collaborative UIs is that some part of the UI state is shared between multiple users. A fundamental concept behind signals is that the value is updated from "somewhere else". There's nothing saying that this other place could be on the server or in some other user's browser. A shared signal could thus be returned from the server in a simliar way to how returning a Flux is used for setting up a subscription.

@BrowserCallable
public class CounterService {
  private static final ValueSignal<Integer> counter = new ValueSignal<>(0);

  public ValueSignal<Integer> counter() {
    return counter;
  }
}

Whereas the counter signal from global.js is shared within a browser tab, it could be changed to be shared between multiple tabs, browsers and users by acquiring it from the service instead.

import { CounterService } from "Frontend/generated/endpoints";

const counter = CounterService.counter();

The one thing that changes with concurrently updated state is that you need to define changes in a granular way that are resistant to concurrent changes. In the counter example, concurrent button clicks will lead to two different users reading the same current value, e.g. 5, and concurrently write their incremented value to the signal. The end result would thus be two separate updates setting the value to 6 even though the actual number of clicks is then 7.

To deal with this, we need to submit a transactional update to the signal. This update will be retried if there's a conflict to make sure that the correct number of increments will eventually be applied (or use a customized signal type based on counting the number of increments instead of a general purpose value holder).

return <button onClick={() => counter.transaction((value) => value + 1)}>Click count: {counter}</button>

Correspondingly, adding an item to a shared array shouldn't be done using signal.value = [...signal.value, newItem] but instead with an atomic operation such as signal.insertLast(newItem). An atomic operation like insertLast is also less code to write and more familiar for Java developers.

CRUD signals

Sharing state between the server and the browser can also be beneficial for CRUD-like cases that persist data in a backend. Adding a value to a signal list corresponds to adding a new row to a database. This has the benefit that data operations on the client are expressed in the same way regardless whether they only update a local representation or also persist that change to a backend.

This requires a slightly more complex signal representation that supports pagination and filtering rather than always loading all the data. The power comes from combining client-updated signals for filtering and paging with a server-updated signal. The client only needs to do employees.filterSignal.value = "asdf" and this will trigger a request that will asynchronously update the value of a employees signal. employees would also have a changesPending signal that can be used to let the user know that data is being fetched.

On the Java side, this CRUD signal could be represented in a similar way as the CrudRepositoryService class used with <AutoCrud>.

[joelpop]

Although client-side transactions would be a desirable feature

return <button onClick={() => counter.transaction((value) => value + 1)}>Click count: {counter}</button>

it seems that anywhere an atomic operation can be used in lieu of a client-side transaction, that would be preferable, similar to your recommendation for updating an array, such as

return <button onClick={() => counter.increment()}>Click count: {counter}</button>

(not sure of the syntax).

[Legioth]

The challenge is that an operation such as increment() only makes sense when the type of the signal value is numerical but not for e.g. string-valued signals. This means that we would might end up with lots of different signal subtypes such as NumberSignal. That in turn leads to a balance between the complexity of choosing the right signal type and having atomic operations for all possible cases.

[joelpop]

So (pardon my ignorance), both transaction and increment would have to be implemented as part of the framework as opposed to user-defined?

[Legioth]

Any custom operation needs to have identical implementations in the browser and the server that operate against a complex internal data structure. Enabling a dedicated API through a NumberSignal type would furthermore also require some additional customizability for the TypeScript generator.

Making all those parts extensible would lead to a large API surface that we would have to document and harden against potential breaking changes as we evolve the internals. It's certainly possible, but I'm not sure if it's worth the trade-off.

[Legioth]

I'm leaning towards having NumberSignal as a dedicated type specifically for the increment(delta) operation but I'm not sure if there are any other cases that would benefit from custom operations if we also provide a slightly more sophisticated transaction API that allows combining multiple operations with various test operations.

The thing to keep in mind is that most actual business logic should be applied against a real database through a regular service method whereas full-stack signals are mainly for managing the state that is shown in the UI. This state is either based on non-authoritative data (e.g. a collaboratively edited draft) or then it's updated based on the results of running some regular business logic.

A silly example of a more sophisticated transaction API could look like this. Note that this type of transaction isn't rerun. Also note that this is a silly example since this kind of logic should really be performed against a real database through a service method.

NumberSignal fromBalance = balances.getByKey(from);
NumberSignal toBalance = balances.getByKey(to);
transaction(() => {
  fromBalance.test('>=', depositAmount);
  fromBalance.increment(-depositAmount);
  toBalance.increment(depositAmount);
});