solidart 1.0.0-dev1

A simple State Management solution for Dart applications inspired by SolidJS

A simple state-management library inspired by SolidJS.

The objectives of this project are:

1. Being simple and easy to learn
2. Do not go against the framework (e.g. Flutter) with weird workarounds.
3. Do not have a single global state, but put multiple states only in the most appropriate places

Learning

For a comprehensive and updated documentation go to The Official Documentation

There are 3 main concepts you should be aware:

1. Signals
2. Effects
3. Resources

Signals

Signals are the cornerstone of reactivity in solidart. They contain values that change over time; when you change a signal's value, it automatically updates anything that uses it.

To create a signal, you have to use the createSignal method:

final counter = createSignal(0);

The argument passed to the create call is the initial value, and the return value is the signal.

// Retrieve the current counter value
print(counter.value); // prints 0
// equal to
print(counter());

// Change the counter value
counter.value++; // Increments by 1
// or
counter.value = 2; // Sets the value to 2
// or
counter.set(3);
// or
counter.update((value) => value * 2); // Update the value based on the current value

If you're using flutter_solidart you can use the SignalBuilder widget to automatically react to the signal value, for example:

SignalBuilder(
  signal: counter,
  builder: (_, value, __) {
    return Text('$value');
  },
)

Effects

Signals are trackable values, but they are only one half of the equation. To complement those are observers that can be updated by those trackable values. An effect is one such observer; it runs a side effect that depends on signals.

An effect can be created by using createEffect. The effect automatically subscribes to any signal and reruns when any of them change. So let's create an Effect that reruns whenever counter changes:

final disposeFn = createEffect((disposeFn) {
    print("The count is now ${counter.value}");
});

Resources

Resources are special Signals designed specifically to handle Async loading. Their purpose is wrap async values in a way that makes them easy to interact with.

Resources can be driven by a source signal that provides the query to an async data fetcher function that returns a Future.

The contents of the fetcher function can be anything. You can hit typical REST endpoints or GraphQL or anything that generates a future. Resources are not opinionated on the means of loading the data, only that they are driven by futures.

Let's create a Resource:

// The source
final userId = createSignal(1);

// The fetcher
Future<String> fetchUser() async {
    final response = await http.get(
      Uri.parse('https://swapi.dev/api/people/${userId.value}/'),
    );
    return response.body;
}

// The resource
final user = createResource(fetcher: fetchUser, source: userId);

A Resource can also be driven from a [stream] instead of a Future. In this case you just need to pass the stream field to the createResource method. The [source] field is ignored for the [stream] and used only for a [fetcher].