Serializing/deserializing methods for Event instances

pkgs/unified_analytics/CHANGELOG.md

@@ -4,6 +4,7 @@
 - Get rid of `late` variables throughout implementation class, `AnalyticsImpl`
 - Any error events (`Event.analyticsException`) encountered within package will be sent when invoking `Analytics.close`; replacing `ErrorHandler` functionality
 - Exposing new method for `FakeAnalytics.sendPendingErrorEvents` to send error events on command
+- Added `Event.fromJson` static method to generate instance of `Event` from JSON
 
 ## 5.8.8
 

pkgs/unified_analytics/lib/src/enums.dart

@@ -2,6 +2,8 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'package:collection/collection.dart';
+
 /// The valid dash tool labels stored in the [DashTool] enum.
 List<String> get validDashTools =>
     DashTool.values.map((e) => e.label).toList()..sort();
@@ -153,6 +155,11 @@ enum DashEvent {
     required this.description,
     this.toolOwner,
   });
+
+  /// This takes in the string label for a given [DashEvent] and returns the
+  /// enum for that string label.
+  static DashEvent? fromLabel(String label) =>
+      DashEvent.values.firstWhereOrNull((e) => e.label == label);
 }
 
 /// Officially-supported clients of this package as logical
@@ -199,7 +206,7 @@ enum DashTool {
 
   /// This takes in the string label for a given [DashTool] and returns the
   /// enum for that string label.
-  static DashTool getDashToolByLabel(String label) {
+  static DashTool? fromLabel(String label) {
     for (final tool in DashTool.values) {
       if (tool.label == label) return tool;
     }

pkgs/unified_analytics/lib/src/event.dart

@@ -4,12 +4,15 @@
 
 import 'dart:convert';
 
+import 'package:collection/collection.dart';
+
 import 'enums.dart';
-import 'utils.dart';
 
 final class Event {
   final DashEvent eventName;
   final Map<String, Object?> eventData;
+  final DeepCollectionEquality _deepCollectionEquality =
+      const DeepCollectionEquality();
 
   /// Event that is emitted whenever a user has opted in
   /// or out of the analytics collection.
@@ -708,6 +711,10 @@ final class Event {
           if (label != null) 'label': label,
         };
 
+  /// Private constructor to be used when deserializing JSON into an instance
+  /// of [Event].
+  Event._({required this.eventName, required this.eventData});
+
   @override
   int get hashCode => Object.hash(eventName, jsonEncode(eventData));
 
@@ -716,11 +723,67 @@ final class Event {
       other is Event &&
       other.runtimeType == runtimeType &&
       other.eventName == eventName &&
-      compareEventData(other.eventData, eventData);
-
-  @override
-  String toString() => jsonEncode({
+      _deepCollectionEquality.equals(other.eventData, eventData);
+
+  /// Converts an instance of [Event] to JSON.
+  ///
+  /// Example for [Event.timing] converted to JSON below.
+  /// ```json
+  /// {
+  ///   "eventName": "timing",
+  ///   "eventData": {
+  ///     "workflow": "my-work-flow",
+  ///     "variableName": "my-variable",
+  ///     "elapsedMilliseconds": 123,
+  ///     "label": "my-label"
+  ///   }
+  /// }
+  /// ```
+  String toJson() => jsonEncode({
         'eventName': eventName.label,
         'eventData': eventData,
       });
+
+  @override
+  String toString() => toJson();
+
+  /// Returns a valid instance of [Event] if [json] follows the correct schema.
+  ///
+  /// Schema is below with the following notes:
+  /// - The `eventName` key must have a string value that exists in [DashEvent].
+  /// - The `eventData` key must have a nested object as its value.
+  /// ```json
+  /// {
+  ///   "eventName": "string-label",
+  ///   "eventData": {
+  ///     "myVar1": "value1",
+  ///     "myVar2": 123
+  ///   }
+  /// }
+  /// ```
+  static Event? fromJson(String json) {
+    try {
+      final jsonMap = jsonDecode(json) as Map<String, Object?>;
+
+      // Ensure that eventName is a string and a valid label and
+      // eventData is a nested object
+      if (jsonMap
+          case {
+            'eventName': final String eventName,
+            'eventData': final Map<String, Object?> eventData,
+          }) {
+        final dashEvent = DashEvent.fromLabel(eventName);
+        if (dashEvent == null) return null;
+
+        return Event._(
+          eventName: dashEvent,
+          eventData: eventData,
+        );
+      }
+
+      return null;
+    } on FormatException {
+      return null;
+    }
+  }
 }

pkgs/unified_analytics/lib/src/survey_handler.dart

@@ -134,10 +134,12 @@ class Survey {
         samplingRate = json['samplingRate'] is String
             ? double.parse(json['samplingRate'] as String)
             : json['samplingRate'] as double,
-        excludeDashToolList =
-            (json['excludeDashTools'] as List<dynamic>).map((e) {
-          return DashTool.getDashToolByLabel(e as String);
-        }).toList(),
+        excludeDashToolList = (json['excludeDashTools'] as List<dynamic>)
+            .map((e) {
+              return DashTool.fromLabel(e as String);
+            })
+            .whereType<DashTool>()
+            .toList(),
         conditionList = (json['conditions'] as List<dynamic>).map((e) {
           return Condition.fromJson(e as Map<String, dynamic>);
         }).toList(),

pkgs/unified_analytics/lib/src/utils.dart

@@ -36,26 +36,6 @@ bool checkDirectoryForWritePermissions(Directory directory) {
   return fileStat.modeString()[1] == 'w';
 }
 
-/// Utility function to take in two maps [a] and [b] and compares them
-/// to ensure that they have the same keys and values
-bool compareEventData(Map<String, Object?> a, Map<String, Object?> b) {
-  final keySetA = a.keys.toSet();
-  final keySetB = b.keys.toSet();
-
-  // Ensure that the keys are the same for each object
-  if (keySetA.intersection(keySetB).length != keySetA.length ||
-      keySetA.intersection(keySetB).length != keySetB.length) {
-    return false;
-  }
-
-  // Ensure that each of the key's values are the same
-  for (final key in a.keys) {
-    if (a[key] != b[key]) return false;
-  }
-
-  return true;
-}
-
 /// Format time as 'yyyy-MM-dd HH:mm:ss Z' where Z is the difference between the
 /// timezone of t and UTC formatted according to RFC 822.
 String formatDateTime(DateTime t) {

pkgs/unified_analytics/pubspec.yaml

@@ -12,6 +12,7 @@ environment:
 
 dependencies:
   clock: ^1.1.1
+  collection: '>=1.18.0 <2.0.0'
   file: '>=6.1.4 <8.0.0'
   http: '>=0.13.5 <2.0.0'
   intl: '>=0.18.0 <0.20.0'

pkgs/unified_analytics/test/event_test.dart

@@ -556,7 +556,9 @@ void main() {
   test('Confirm all constructors were checked', () {
     var constructorCount = 0;
     for (var declaration in reflectClass(Event).declarations.keys) {
-      if (declaration.toString().contains('Event.')) constructorCount++;
+      // Count public constructors but omit private constructors
+      if (declaration.toString().contains('Event.') &&
+          !declaration.toString().contains('Event._')) constructorCount++;
     }
 
     // Change this integer below if your PR either adds or removes
@@ -568,4 +570,55 @@ void main() {
             '`pkgs/unified_analytics/test/event_test.dart` '
             'to reflect the changes made');
   });
+
+  test('Serializing event to json successful', () {
+    final event = Event.analyticsException(
+      workflow: 'workflow',
+      error: 'error',
+      description: 'description',
+    );
+
+    final expectedResult = '{"eventName":"analytics_exception",'
+        '"eventData":{"workflow":"workflow",'
+        '"error":"error",'
+        '"description":"description"}}';
+
+    expect(event.toJson(), expectedResult);
+  });
+
+  test('Deserializing string to event successful', () {
+    final eventJson = '{"eventName":"analytics_exception",'
+        '"eventData":{"workflow":"workflow",'
+        '"error":"error",'
+        '"description":"description"}}';
+
+    final eventConstructed = Event.fromJson(eventJson);
+    expect(eventConstructed, isNotNull);
+    eventConstructed!;
+
+    expect(eventConstructed.eventName, DashEvent.analyticsException);
+    expect(eventConstructed.eventData, {
+      'workflow': 'workflow',
+      'error': 'error',
+      'description': 'description',
+    });
+  });
+
+  test('Deserializing string to event unsuccessful for invalid eventName', () {
+    final eventJson = '{"eventName":"NOT_VALID_NAME",'
+        '"eventData":{"workflow":"workflow",'
+        '"error":"error",'
+        '"description":"description"}}';
+
+    final eventConstructed = Event.fromJson(eventJson);
+    expect(eventConstructed, isNull);
+  });
+
+  test('Deserializing string to event unsuccessful for invalid eventData', () {
+    final eventJson = '{"eventName":"analytics_exception",'
+        '"eventData": "not_valid_event_data"}';
+
+    final eventConstructed = Event.fromJson(eventJson);
+    expect(eventConstructed, isNull);
+  });
 }