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

@@ -153,6 +153,16 @@ 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? getDashEventByLabel(String label) {
+    for (final event in DashEvent.values) {
+      if (event.label == label) return event;
+    }
+
+    return null;
+  }
 }
 
 /// Officially-supported clients of this package as logical

pkgs/unified_analytics/lib/src/event.dart

@@ -5,7 +5,6 @@
 import 'dart:convert';
 
 import 'enums.dart';
-import 'utils.dart';
 
 final class Event {
   final DashEvent eventName;
@@ -708,6 +707,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 +719,93 @@ final class Event {
       other is Event &&
       other.runtimeType == runtimeType &&
       other.eventName == eventName &&
-      compareEventData(other.eventData, eventData);
-
-  @override
-  String toString() => jsonEncode({
+      _compareEventData(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();
+
+  /// Utility function to take in two maps [a] and [b] and compares them
+  /// to ensure that they have the same keys and values.
+  ///
+  /// Used for the equality operator.
+  bool _compareEventData(Map<String, Object?> a, Map<String, Object?> b) {
+    final keySetA = a.keys.toSet();
+    final keySetB = b.keys.toSet();
+    final intersection = keySetA.intersection(keySetB);
+
+    // Ensure that the keys are the same for each object
+    if (intersection.length != keySetA.length ||
+        intersection.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;
+  }
+
+  /// 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 the required keys are present
+      if (!jsonMap.containsKey('eventName') ||
+          !jsonMap.containsKey('eventData')) {
+        return null;
+      }
+
+      // Ensure the values for each key is the correct type
+      final eventName = jsonMap['eventName'];
+      final eventData = jsonMap['eventData'];
+      if (eventName is! String || eventData is! Map<String, Object?>) {
+        return null;
+      }
+
+      // Retrieve the correct DashEvent enum from the provided label
+      final dashEvent = DashEvent.getDashEventByLabel(eventName);
+      if (dashEvent == null) {
+        return null;
+      }
+
+      return Event._(eventName: dashEvent, eventData: eventData);
+    } on FormatException {
+      return null;
+    }
+  }
 }

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/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);
+  });
 }