https://github.com/dipendra-sharma/watchable
A lightweight, intuitive state management solution for Flutter. Simplify your app's state with easy-to-use Watchable objects and efficient UI rebuilding
https://github.com/dipendra-sharma/watchable
dart flutter flutter-state-management observability reactive state-management
Last synced: 3 months ago
JSON representation
A lightweight, intuitive state management solution for Flutter. Simplify your app's state with easy-to-use Watchable objects and efficient UI rebuilding
- Host: GitHub
- URL: https://github.com/dipendra-sharma/watchable
- Owner: dipendra-sharma
- License: bsd-3-clause
- Created: 2024-06-26T15:42:30.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-11T13:50:27.000Z (12 months ago)
- Last Synced: 2024-08-22T22:27:38.035Z (10 months ago)
- Topics: dart, flutter, flutter-state-management, observability, reactive, state-management
- Language: Dart
- Homepage: https://pub.dev/packages/watchable
- Size: 298 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Watchable
A lightweight, intuitive state management solution for Flutter applications. Watchable offers a simple API for managing state and efficiently rebuilding UI components when state changes.
## Features
- Simple and intuitive API for state management
- Efficient UI updates with fine-grained control
- Support for both mutable state and event streams
- Easy combination of multiple state objects
- Minimal boilerplate code
- Scalable from simple to complex state management scenarios
## Installation
Add `watchable` to your `pubspec.yaml`:
```yaml
dependencies:
watchable: any
```
Then run `flutter pub get` to install the package.
## Usage
### Basic State Management
Use `StateWatchable` for managing mutable state:
```dart
final counterWatchable = MutableStateWatchable(0);
WatchableBuilder(
watchable: counterWatchable,
builder: (context, value, child) {
return Text('Counter: $value');
},
)
// Update the state
counterWatchable.emit(counterWatchable.value + 1);
```
### Form Handling
Manage form state easily:
```dart
final nameWatchable = MutableStateWatchable('');
final emailWatchable = MutableStateWatchable('');
TextField(
onChanged: (value) => nameWatchable.emit(value),
),
TextField(
onChanged: (value) => emailWatchable.emit(value),
),
WatchableBuilder.from2(
watchable1: nameWatchable,
watchable2: emailWatchable,
combiner: (name, email) => name.isNotEmpty && email.isNotEmpty,
builder: (context, isValid, child) {
return ElevatedButton(
onPressed: isValid ? () => submitForm() : null,
child: Text('Submit'),
);
},
)
```
### Handling Events
Use `Watchable` for event streams:
```dart
final notificationWatchable = MutableWatchable();
WatchableConsumer(
watchable: notificationWatchable,
onEvent: (message) {
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(message)),
);
},
child: YourWidget(),
)
// Trigger an event
notificationWatchable.emit('New notification!');
```
### Combining Multiple States
Easily combine multiple state objects:
```dart
final userWatchable = MutableStateWatchable(null);
final postsWatchable = MutableStateWatchable>([]);
WatchableBuilder.from2, Widget>(
watchable1: userWatchable,
watchable2: postsWatchable,
combiner: (user, posts) {
if (user == null) return LoginScreen();
return PostList(user: user, posts: posts);
},
builder: (context, widget, child) => widget,
)
```
### Optimizing Rebuilds
Use `shouldRebuild` to control when the UI updates:
```dart
WatchableBuilder>(
watchable: itemsWatchable,
shouldRebuild: (previous, current) => previous.length != current.length,
builder: (context, items, child) {
return ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) => ItemTile(item: items[index]),
);
},
)
```
### Managing Complex State & Encapsulated State Access
For more complex state & for controlled access to its state, you can create a custom state class:
```dart
class AppState {
final _user = MutableStateWatchable(null);
StateWatchable get user => _user;
final _todos = MutableStateWatchable([]);
StateWatchable> get todos => _todos;
final _notifications = MutableWatchable();
Watchable get notifications => _notifications;
void login(User user) => _user.emit(user);
void logout() => _user.emit(null);
void addTodo(Todo todo) => _todos.emit([...todos.value, todo]);
void notify(String message) => _notifications.emit(message);
}
final appState = AppState();
// Usage
WatchableBuilder(
watchable: appState.user,
builder: (context, user, child) {
return user != null ? HomeScreen() : LoginScreen();
},
)
```
## Additional Information
For more detailed API information and advanced usage, please refer to the [API documentation](https://pub.dev/documentation/watchable/latest/).
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the BSD-3-Clause License - see the [LICENSE](LICENSE) file for details.