Solidart

What is solidart?

solidart is an open-source state-management library designed for Dart and Flutter applications. It is inspired by the fine-grained reactivity model of SolidJS.

Core Design Principles

When using solidart, you can expect the following architectural characteristics:

• Fine-grained Reactivity: Uses concepts like Signals, Effects, and Computeds (similar to SolidJS).
• Decentralized State: Instead of a single global state tree, solidart encourages managing multiple states only in the most appropriate places.
• No Code Generation: You can manage state without the overhead of build runners or code-gen steps.
• Framework Alignment: Designed to fit well with standard Dart and Flutter best practices.
• Scalability: Built to be performant and efficient for both small and large-scale applications.
• Testability: The architecture is designed to be easily testable.

A Computed signal is a read-only signal that derives its value from other signals. It automatically subscribes to any signals accessed within its constructor function and reruns that function whenever those dependencies change.

Key characteristics:

• Automatic Dependency Tracking: You don't need to manually manage subscriptions; Computed tracks which signals are read during execution.
• Read-Only: Computed implements the ReadSignal interface, meaning it does not have a setter (you cannot call .set() or .updateValue() on it).
• Type Transformation: You can use Computed to transform data types (e.g., from an int to a bool).

final name = Signal('John');
final lastName = Signal('Doe');
final fullName = Computed(() => '${name.value} ${lastName.value}');
print(fullName()); // prints "John Doe"

// Update the name
name.set('Jane');
print(fullName()); // prints "Jane Doe"

An Effect only tracks the current dependencies accessed during its most recent execution. This means if your effect contains conditional logic, the set of signals it tracks can change dynamically.

• If a signal is accessed inside an if block that evaluates to false, that signal is not tracked.
• If the condition changes and the signal is subsequently accessed, the effect will then start tracking that signal.

Warning: Use conditional logic carefully, as it can lead to unexpected behavior where an effect does not react to changes in signals that were not part of its last execution path.

final name = Signal("John");
final lastName = Signal("Doe");
final showFullName = Signal(false);

Effect((_) {
  if (showFullName()) {
    print("${name.value} ${lastName.value}");
  } else {
    print(name.value);
  }
});

// 1. Initially prints "John" and tracks [name, showFullName].
// 2. Changing lastName to "Smith" triggers NOTHING because lastName is not currently tracked.
// 3. Setting showFullName to true triggers the effect. 
// 4. It now prints "John Doe" and tracks [name, lastName, showFullName].

A Computed is a read-only signal that depends on other signals. It automatically subscribes to any signal accessed within its constructor function and reruns that function whenever any of its dependencies change.

Key characteristics:

• Automatic Dependency Tracking: It tracks which signals are accessed during execution.
• Read-Only: A Computed returns a ReadSignal, which means it does not have a value setter. You cannot manually update its value; it only changes when its dependencies change.
• Type Transformation: You can use Computed to transform the type of a signal (e.g., transforming an int signal into a bool signal based on a condition).
• Value Stability: If the result of the computation remains the same after a dependency change (e.g., a boolean condition that stays false), the Computed signal will not emit a new value to its own subscribers.

final counter = Signal(0); // type: int
final isGreaterThan5 = Computed(() => counter() > 5); // type: bool

The Solid widget manages a collection of Provider objects.

Key Concepts:

• Lazy Creation: By default, providers are created lazily via the create function. The signal is only instantiated when it is first accessed. To force immediate creation, set lazy: false.
• Identifiers (id): You can provide multiple providers of the same type by assigning a unique id to each. This allows you to distinguish between them when retrieving them from the context.
• Lifecycle (dispose): You can provide a dispose callback to the Provider. This function is triggered when the Solid widget is removed from the widget tree, allowing for clean-up logic (e.g., closing streams or clearing resources).
• Type Safety: It is mandatory to specify the explicit type of the signal in the Provider (e.g., Provider<Signal<T>>) and when calling observe or get to avoid errors.

In solidart, Resources are specialized Signals designed to manage asynchronous loading states. They wrap async values to provide a standardized way to handle the three common states of a future: data (ready), error, and loading.

Resources can be driven in two ways:

1. By a source signal: A source signal provides a query/parameter to an async fetcher function. When the source changes, the resource automatically re-fetches.
2. By a stream: Instead of a fetcher function, you can provide a stream to the Resource class to drive it from reactive stream data.

Resources are agnostic to the data fetching mechanism (REST, GraphQL, etc.) as long as the mechanism returns a Future or a Stream.

// Example: Resource driven by a source signal
final userId = Signal(1);

Future<String> fetchUser() async {
    // ... fetching logic using userId.value
}

final user = Resource(fetchUser, source: userId);