model: Add Reactions data structure, for efficient access in UI

One important optimization for efficiency is, when a message has no
reactions, to initialize its `.reactions` to `null` instead of an
empty [Reactions] instance:
  #286 (comment)

Author: chrisbobbe

lib/api/model/model.dart

@@ -262,7 +262,9 @@ sealed class Message {
   bool isMeMessage;
   int? lastEditTimestamp;
 
-  final List<Reaction> reactions;
+  @JsonKey(fromJson: _reactionsFromJson, toJson: _reactionsToJson)
+  Reactions? reactions; // null is equivalent to an empty [Reactions]
+
   final int recipientId;
   final String senderEmail;
   final String senderFullName;
@@ -280,6 +282,15 @@ sealed class Message {
   final String? matchContent;
   final String? matchSubject;
 
+  static Reactions? _reactionsFromJson(dynamic json) {
+    final list = (json as List<dynamic>);
+    return list.isNotEmpty ? Reactions.fromJson(list) : null;
+  }
+
+  static Object _reactionsToJson(Reactions? value) {
+    return value ?? [];
+  }
+
   static List<MessageFlag> _flagsFromJson(dynamic json) {
     final list = json as List<dynamic>;
     return list.map((raw) => MessageFlag.fromRawString(raw as String)).toList();

lib/api/model/model.g.dart

@@ -1,8 +1,148 @@
+import 'dart:collection';
+
+import 'package:collection/collection.dart';
 import 'package:json_annotation/json_annotation.dart';
 
 part 'reaction.g.dart';
 
-/// As in [Message.reactions].
+/// A message's reactions, in a convenient data structure.
+class Reactions {
+  int get total => _total;
+  int _total;
+
+  /// A list of [ReactionWithVotes] objects.
+  ///
+  /// There won't be two items with the same
+  /// [ReactionWithVotes.reactionType] and [ReactionWithVotes.emojiCode].
+  /// (We don't also key on [ReactionWithVotes.emojiName];
+  /// see [ReactionWithVotes].)
+  ///
+  /// Sorted descending by the size of [ReactionWithVotes.userIds],
+  /// i.e., the number of votes.
+  late final List<ReactionWithVotes> aggregated;
+
+  Reactions._(this.aggregated, this._total);
+
+  factory Reactions(List<Reaction> unaggregated) {
+    final byReaction = LinkedHashMap<Reaction, ReactionWithVotes>(
+      equals: (a, b) => a.reactionType == b.reactionType && a.emojiCode == b.emojiCode,
+      hashCode: (r) => Object.hash(r.reactionType, r.emojiCode),
+    );
+    for (final reaction in unaggregated) {
+      final current = byReaction[reaction] ??= ReactionWithVotes.empty(reaction);
+      current.userIds.add(reaction.userId);
+    }
+
+    return Reactions._(
+      byReaction.values.sorted(
+        // Descending by number of votes
+        (a, b) => -a.userIds.length.compareTo(b.userIds.length),
+      ),
+      unaggregated.length,
+    );
+  }
+
+  factory Reactions.fromJson(List<dynamic> json) {
+    return Reactions(
+      json.map((r) => Reaction.fromJson(r as Map<String, dynamic>)).toList(),
+    );
+  }
+
+  List<dynamic> toJson() {
+    final result = <Reaction>[];
+    for (final reactionWithVotes in aggregated) {
+      result.addAll(reactionWithVotes.userIds.map((userId) => Reaction(
+        reactionType: reactionWithVotes.reactionType,
+        emojiCode: reactionWithVotes.emojiCode,
+        emojiName: reactionWithVotes.emojiName,
+        userId: userId,
+      )));
+    }
+    return result;
+  }
+
+  void add(Reaction reaction) {
+    final currentIndex = aggregated.indexWhere((r) {
+      return r.reactionType == reaction.reactionType && r.emojiCode == reaction.emojiCode;
+    });
+    if (currentIndex == -1) {
+      final newItem = ReactionWithVotes.empty(reaction);
+      newItem.userIds.add(reaction.userId);
+      aggregated.add(newItem);
+    } else {
+      final current = aggregated[currentIndex];
+      current.userIds.add(reaction.userId);
+
+      // Reposition `current` in list to keep it sorted by number of votes
+      final newIndex = 1 + aggregated.lastIndexWhere(
+        (item) => item.userIds.length >= current.userIds.length,
+        currentIndex - 1,
+      );
+      if (newIndex < currentIndex) {
+        aggregated
+          ..setRange(newIndex + 1, currentIndex + 1, aggregated, newIndex)
+          ..[newIndex] = current;
+      }
+    }
+    _total++;
+  }
+
+  void remove({
+    required ReactionType reactionType,
+    required String emojiCode,
+    required int userId,
+  }) {
+    final currentIndex = aggregated.indexWhere((r) {
+      return r.reactionType == reactionType && r.emojiCode == emojiCode;
+    });
+    if (currentIndex == -1) { // TODO(log)
+      return;
+    }
+    final current = aggregated[currentIndex];
+    current.userIds.remove(userId);
+    if (current.userIds.isEmpty) {
+      aggregated.removeAt(currentIndex);
+    } else {
+      final lteIndex = aggregated.indexWhere(
+        (item) => item.userIds.length <= current.userIds.length,
+        currentIndex + 1,
+      );
+      final newIndex = lteIndex == -1 ? aggregated.length - 1 : lteIndex - 1;
+      if (newIndex > currentIndex) {
+        aggregated
+          ..setRange(currentIndex, newIndex, aggregated, currentIndex + 1)
+          ..[newIndex] = current;
+      }
+    }
+    _total--;
+  }
+}
+
+/// A data structure identifying a reaction and who has voted for it.
+///
+/// [emojiName] is not part of the key identifying the reaction.
+/// Servers don't key on it (only user, message, reaction type, and emoji code),
+/// and we mimic that behavior:
+///   https://github.com/zulip/zulip-flutter/pull/256#discussion_r1284865099
+/// It's included here so we can display it in UI.
+class ReactionWithVotes {
+  final ReactionType reactionType;
+  final String emojiCode;
+  final String emojiName;
+  final Set<int> userIds = {};
+
+  ReactionWithVotes.empty(Reaction reaction)
+    : reactionType = reaction.reactionType,
+      emojiCode    = reaction.emojiCode,
+      emojiName    = reaction.emojiName;
+
+  @override
+  String toString() => 'ReactionWithVotes(reactionType: $reactionType, emojiCode: $emojiCode, emojiName: $emojiName, userIds: $userIds)';
+}
+
+/// A reaction object found inside message objects in the Zulip API.
+///
+/// E.g., under "reactions:" in <https://zulip.com/api/get-message>.
 @JsonSerializable(fieldRename: FieldRename.snake)
 class Reaction {
   final String emojiName;

lib/api/model/reaction.dart

@@ -350,18 +350,21 @@ class MessageListView with ChangeNotifier, _MessageSequence {
     final message = messages[index];
     switch (event.op) {
       case ReactionOp.add:
-        message.reactions.add(Reaction(
+        (message.reactions ??= Reactions([])).add(Reaction(
           emojiName: event.emojiName,
           emojiCode: event.emojiCode,
           reactionType: event.reactionType,
           userId: event.userId,
         ));
       case ReactionOp.remove:
-        message.reactions.removeWhere((r) {
-          return r.emojiCode == event.emojiCode
-            && r.reactionType == event.reactionType
-            && r.userId == event.userId;
-        });
+        if (message.reactions == null) { // TODO(log)
+          return;
+        }
+        message.reactions!.remove(
+          reactionType: event.reactionType,
+          emojiCode: event.emojiCode,
+          userId: event.userId,
+        );
     }
 
     notifyListeners();

lib/model/message_list.dart

@@ -15,7 +15,7 @@ void main() {
     MessageEvent mkEvent(List<MessageFlag> flags) => Event.fromJson({
       'type': 'message',
       'id': 1,
-      'message': message.toJson()..remove('flags'),
+      'message': (deepToJson(message) as Map<String, dynamic>)..remove('flags'),
       'flags': flags.map((f) => f.toJson()).toList(),
     }) as MessageEvent;
     check(mkEvent(message.flags)).message.jsonEquals(message);

test/api/model/events_test.dart

@@ -5,15 +5,41 @@ extension MessageChecks on Subject<Message> {
   Subject<String> get content => has((e) => e.content, 'content');
   Subject<bool> get isMeMessage => has((e) => e.isMeMessage, 'isMeMessage');
   Subject<int?> get lastEditTimestamp => has((e) => e.lastEditTimestamp, 'lastEditTimestamp');
-  Subject<List<Reaction>> get reactions => has((e) => e.reactions, 'reactions');
+  Subject<Reactions?> get reactions => has((e) => e.reactions, 'reactions');
   Subject<List<MessageFlag>> get flags => has((e) => e.flags, 'flags');
 
   // TODO accessors for other fields
 }
 
-extension ReactionsChecks on Subject<List<Reaction>> {
-  void deepEquals(_) {
-    throw UnimplementedError('Tried to call [Subject<List<Reaction>>.deepEquals]. Use jsonEquals instead.');
+extension ReactionsChecks on Subject<Reactions> {
+  Subject<int> get total => has((e) => e.total, 'total');
+  Subject<List<ReactionWithVotes>> get aggregated => has((e) => e.aggregated, 'aggregated');
+}
+
+extension ReactionWithVotesChecks on Subject<ReactionWithVotes> {
+  Subject<ReactionType> get reactionType => has((r) => r.reactionType, 'reactionType');
+  Subject<String> get emojiCode => has((r) => r.emojiCode, 'emojiCode');
+  Subject<String> get emojiName => has((r) => r.emojiName, 'emojiName');
+  Subject<Set<int>> get userIds => has((r) => r.userIds, 'userIds');
+
+  /// Whether this [ReactionWithVotes] corresponds to the given same-emoji [reactions].
+  void matchesReactions(List<Reaction> reactions) {
+    assert(reactions.isNotEmpty);
+    final first = reactions.first;
+
+    // Same emoji for all reactions
+    assert(reactions.every((r) => r.reactionType == first.reactionType && r.emojiCode == first.emojiCode));
+
+    final userIds = Set.from(reactions.map((r) => r.userId));
+
+    // No double-votes from one person (we don't expect this from servers)
+    assert(userIds.length == reactions.length);
+
+    return which(it()
+      ..reactionType.equals(first.reactionType)
+      ..emojiCode.equals(first.emojiCode)
+      ..userIds.deepEquals(userIds)
+    );
   }
 }
 

test/api/model/model_checks.dart

@@ -66,8 +66,9 @@ void main() {
   });
 
   group('DmMessage', () {
-    final Map<String, dynamic> baseJson = Map.unmodifiable(
-      eg.dmMessage(from: eg.otherUser, to: [eg.selfUser]).toJson());
+    final Map<String, dynamic> baseJson = Map.unmodifiable(deepToJson(
+      eg.dmMessage(from: eg.otherUser, to: [eg.selfUser]),
+    ) as Map<String, dynamic>);
 
     DmMessage parse(Map<String, dynamic> specialJson) {
       return DmMessage.fromJson({ ...baseJson, ...specialJson });