A todo list as an aggregate: events and undo
The whole list is one handler. The app writes events, and a reducer folds them into the list the same way on every peer. A todo keeps the id of the event that added it, so two peers that move or remove it at the same time never duplicate it. This is model C of Which handler do you need?: compare it with the containers recipe.
A todo list as an aggregate: events and undoSource ↗
A Flutter todo list held by one aggregate: the app writes events (added, edited, checked, moved, removed), and a reducer folds them the same way on every peer. Each action can be undone.
- todos.dart
- main.dart
- todo_page.dart
- Install
import 'dart:convert';
import 'dart:typed_data';
import 'package:crdt_lf/crdt_lf.dart';
/// One todo, addressed by the id of the event that added it.
final class Todo {
/// Creates the todo [id].
const Todo(this.id, this.text, {this.done = false});
/// The id of the event that added the todo: the same on every peer.
final EventId id;
/// What to do.
final String text;
/// Whether it is done.
final bool done;
/// A copy with the given fields replaced.
Todo copyWith({String? text, bool? done}) =>
Todo(id, text ?? this.text, done: done ?? this.done);
}
/// The state of the aggregate: the todos, in order.
final class TodoList {
/// Creates a list of [todos].
const TodoList([this.todos = const []]);
/// The todos, in order.
final List<Todo> todos;
/// Where the todo [id] is, or `-1`.
int indexOf(EventId id) => todos.indexWhere((todo) => todo.id == id);
}
/// What happens to a [TodoList].
sealed class TodoEvent {
const TodoEvent();
}
/// Adds a todo at the end.
final class TodoAdded extends TodoEvent {
/// Creates the event.
const TodoAdded(this.text);
/// What to do.
final String text;
}
/// Replaces the text of [todo].
final class TodoEdited extends TodoEvent {
/// Creates the event.
const TodoEdited(this.todo, this.text);
/// The todo to edit.
final EventId todo;
/// The new text.
final String text;
}
/// Marks [todo] as done, or not.
final class TodoChecked extends TodoEvent {
/// Creates the event.
const TodoChecked(this.todo, {required this.done});
/// The todo to mark.
final EventId todo;
/// Whether it is done.
final bool done;
}
/// Moves [todo] after [after], or first when [after] is `null`.
final class TodoMoved extends TodoEvent {
/// Creates the event.
const TodoMoved(this.todo, {this.after});
/// The todo to move.
final EventId todo;
/// The todo it goes after.
final EventId? after;
}
/// Removes [todo].
final class TodoRemoved extends TodoEvent {
/// Creates the event.
const TodoRemoved(this.todo);
/// The todo to remove.
final EventId todo;
}
/// Puts back [todo], with its own id, after [after]. An undo writes it.
final class TodoRestored extends TodoEvent {
/// Creates the event.
const TodoRestored(this.todo, {this.after});
/// The todo to put back.
final Todo todo;
/// The todo it goes after.
final EventId? after;
}
/// How a [TodoEvent] moves a [TodoList], and how an undo takes it back.
final class TodoListAggregate
extends InvertibleAggregateDefinition<TodoList, TodoEvent> {
/// Creates the definition.
const TodoListAggregate();
String get handlerType => 'todo-aggregate';
TodoList initial(String id) => const TodoList();
// Pure: every peer replays the same events, in the same order, through it.
// An event on a todo that is gone does nothing.
TodoList reduce(TodoList state, TodoEvent event, EventContext context) {
switch (event) {
case TodoAdded(:final text):
return TodoList([...state.todos, Todo(context.id, text)]);
case TodoEdited(:final todo, :final text):
return _update(state, todo, (found) => found.copyWith(text: text));
case TodoChecked(:final todo, :final done):
return _update(state, todo, (found) => found.copyWith(done: done));
case TodoMoved(:final todo, :final after):
final index = state.indexOf(todo);
if (index == -1) {
return state;
}
final todos = [...state.todos];
return TodoList(_insertAfter(todos, todos.removeAt(index), after));
case TodoRemoved(:final todo):
return TodoList([...state.todos.where((found) => found.id != todo)]);
case TodoRestored(:final todo, :final after):
if (state.indexOf(todo.id) != -1) {
return state;
}
return TodoList(_insertAfter([...state.todos], todo, after));
}
}
// Read against the state before the event. Ids, never positions: the undo
// is applied after what the other peers wrote in between.
List<TodoEvent> invert(
TodoList before,
TodoEvent event,
EventContext context,
) {
switch (event) {
case TodoAdded():
return [TodoRemoved(context.id)];
case TodoRestored(:final todo):
return before.indexOf(todo.id) == -1 ? [TodoRemoved(todo.id)] : [];
case TodoEdited(:final todo) ||
TodoChecked(:final todo) ||
TodoMoved(:final todo) ||
TodoRemoved(:final todo):
final index = before.indexOf(todo);
if (index == -1) {
return [];
}
final old = before.todos[index];
final previous = index == 0 ? null : before.todos[index - 1].id;
return [
switch (event) {
TodoEdited() => TodoEdited(todo, old.text),
TodoChecked() => TodoChecked(todo, done: old.done),
TodoMoved() => TodoMoved(todo, after: previous),
_ => TodoRestored(old, after: previous),
},
];
}
}
ValueCodec<TodoEvent> get eventCodec => const TodoEventCodec();
ValueCodec<TodoList> get stateCodec => const TodoListCodec();
static TodoList _update(
TodoList state,
EventId id,
Todo Function(Todo todo) change,
) {
final index = state.indexOf(id);
if (index == -1) {
return state;
}
return TodoList([...state.todos]..[index] = change(state.todos[index]));
}
// An anchor that is gone puts the todo first.
static List<Todo> _insertAfter(List<Todo> todos, Todo todo, EventId? after) {
final anchor = after == null ? -1 : todos.indexWhere((t) => t.id == after);
return todos..insert(anchor + 1, todo);
}
}
/// The kind of the todo list: one spec for the whole app.
final todoListKind = CRDTAggregateHandler.spec(const TodoListAggregate());
/// The todo list of [document].
CRDTAggregateHandler<TodoList, TodoEvent> todosOf(CRDTDocument document) {
return document.handler(todoListKind, 'todos');
}
const _json = JsonValueCodec<Map<String, dynamic>>();
String _idToJson(EventId id) => base64Encode(id.toBytes());
EventId _idFromJson(String id) => EventId.fromBytes(base64Decode(id));
Map<String, dynamic> _todoToJson(Todo todo) => {
'id': _idToJson(todo.id),
'text': todo.text,
'done': todo.done,
};
Todo _todoFromJson(Map<String, dynamic> json) => Todo(
_idFromJson(json['id'] as String),
json['text'] as String,
done: json['done'] as bool,
);
/// Writes the events as JSON. The bytes travel and are stored: changing them
/// means a new `version` of the aggregate.
final class TodoEventCodec implements ValueCodec<TodoEvent> {
/// Creates the codec.
const TodoEventCodec();
Uint8List encode(TodoEvent value) => _json.encode(switch (value) {
TodoAdded(:final text) => {'type': 'added', 'text': text},
TodoEdited(:final todo, :final text) => {
'type': 'edited',
'todo': _idToJson(todo),
'text': text,
},
TodoChecked(:final todo, :final done) => {
'type': 'checked',
'todo': _idToJson(todo),
'done': done,
},
TodoMoved(:final todo, :final after) => {
'type': 'moved',
'todo': _idToJson(todo),
'after': after == null ? null : _idToJson(after),
},
TodoRemoved(:final todo) => {'type': 'removed', 'todo': _idToJson(todo)},
TodoRestored(:final todo, :final after) => {
'type': 'restored',
'todo': _todoToJson(todo),
'after': after == null ? null : _idToJson(after),
},
});
TodoEvent decode(Uint8List bytes) {
final json = _json.decode(bytes);
final after = json['after'] as String?;
return switch (json['type']) {
'added' => TodoAdded(json['text'] as String),
'edited' => TodoEdited(
_idFromJson(json['todo'] as String),
json['text'] as String,
),
'checked' => TodoChecked(
_idFromJson(json['todo'] as String),
done: json['done'] as bool,
),
'moved' => TodoMoved(
_idFromJson(json['todo'] as String),
after: after == null ? null : _idFromJson(after),
),
'removed' => TodoRemoved(_idFromJson(json['todo'] as String)),
'restored' => TodoRestored(
_todoFromJson(json['todo'] as Map<String, dynamic>),
after: after == null ? null : _idFromJson(after),
),
final type => throw FormatException('Unknown todo event: $type'),
};
}
}
/// Writes the state as JSON, for snapshots. It keeps the ids: the events
/// written after a snapshot address the todos by them.
final class TodoListCodec implements ValueCodec<TodoList> {
/// Creates the codec.
const TodoListCodec();
Uint8List encode(TodoList value) =>
_json.encode({'todos': value.todos.map(_todoToJson).toList()});
TodoList decode(Uint8List bytes) => TodoList([
for (final todo in _json.decode(bytes)['todos'] as List<dynamic>)
_todoFromJson(todo as Map<String, dynamic>),
]);
}
import 'package:crdt_lf/crdt_lf.dart';
import 'package:crdt_lf_flutter/crdt_lf_flutter.dart';
import 'package:flutter/material.dart';
import 'todo_page.dart';
import 'todos.dart';
void main() {
runApp(
MaterialApp(
title: 'Todos',
home: CrdtProvider(
// In memory: the provider creates the document and disposes it.
create: (_) {
final document = CRDTDocument();
todosOf(document); // the page reads the aggregate under 'todos'
return document;
},
child: const TodoPage(),
),
),
);
}
import 'package:crdt_lf/crdt_lf.dart';
import 'package:crdt_lf_flutter/crdt_lf_flutter.dart';
import 'package:flutter/material.dart';
import 'todos.dart';
/// A page that shows the todos of the document above it, with undo.
class TodoPage extends StatefulWidget {
/// Creates the page of the todos.
const TodoPage({super.key});
State<TodoPage> createState() => _TodoPageState();
}
class _TodoPageState extends State<TodoPage> {
late final CRDTUndoManager _undo;
void initState() {
super.initState();
final document = context.crdtDocument;
// One undo step per action: no time window merges two of them.
_undo = CRDTUndoManager(document, captureTimeout: Duration.zero)
..track(todosOf(document));
}
void dispose() {
_undo.dispose();
super.dispose();
}
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Todos'),
actions: [
StreamBuilder<void>(
stream: _undo.changes,
builder:
(context, _) => Row(
children: [
IconButton(
tooltip: 'Undo',
icon: const Icon(Icons.undo),
onPressed: _undo.canUndo ? _undo.undo : null,
),
IconButton(
tooltip: 'Redo',
icon: const Icon(Icons.redo),
onPressed: _undo.canRedo ? _undo.redo : null,
),
],
),
),
],
),
floatingActionButton: FloatingActionButton(
tooltip: 'New todo',
onPressed:
() => todosOf(context.crdtDocument).dispatch(const TodoAdded('')),
child: const Icon(Icons.add),
),
body: CrdtHandlerBuilder<CRDTAggregateHandler<TodoList, TodoEvent>>(
id: 'todos',
builder: (context, handler) {
final todos = handler.value.todos;
return ReorderableListView(
// The list gives positions; the event names ids.
onReorderItem: (from, to) {
final others = [...todos]..removeAt(from);
handler.dispatch(
TodoMoved(
todos[from].id,
after: to == 0 ? null : others[to - 1].id,
),
);
},
children: [
for (final todo in todos)
TodoTile(
key: ValueKey(todo.id),
todo: todo,
dispatch: handler.dispatch,
),
],
);
},
),
);
}
}
/// One todo: a check box, its text and a delete button.
class TodoTile extends StatelessWidget {
/// Creates the tile of [todo].
const TodoTile({required this.todo, required this.dispatch, super.key});
/// The todo to show.
final Todo todo;
/// Writes an event to the todo list.
final ValueChanged<TodoEvent> dispatch;
Widget build(BuildContext context) {
return ListTile(
leading: Checkbox(
value: todo.done,
onChanged:
(done) => dispatch(TodoChecked(todo.id, done: done ?? false)),
),
// The text is one field of the aggregate: an edit replaces it whole, on
// submit. A new text from another peer builds a new field.
title: TextFormField(
key: ValueKey(todo.text),
initialValue: todo.text,
decoration: const InputDecoration(hintText: 'What to do'),
onFieldSubmitted: (text) => dispatch(TodoEdited(todo.id, text)),
),
trailing: IconButton(
tooltip: 'Delete',
icon: const Icon(Icons.delete_outline),
onPressed: () => dispatch(TodoRemoved(todo.id)),
),
);
}
}
flutter pub add crdt_lf crdt_lf_flutter
Key points
- A todo is addressed by the id of the event that added it (
EventContext.id, returned bydispatch), never by its position: a concurrent insert shifts a position, never an id. reduceis pure, and an event on a todo that is gone does nothing: that is the merged result of a concurrent remove.- The text is one field of the aggregate: two peers that edit it at the same time keep one of the two texts. For text typed together, use the containers recipe.
InvertibleAggregateDefinition.invertmakes each event undoable. An undo of a remove puts the todo back under its own id, so later events still find it.- The codecs write what travels and what is stored: change their bytes, or the meaning of an event, and raise
versionwith a migration. - The document lives in memory. To keep it on the device, open it from a storage backend: the snapshots it takes keep the replay of a late event short.