feat: Add support for canonical JSON serialization. (#241)

This adds a canonical JSON serializer which can be used for implementing
per-context summary events.

Testing starts with all the cases from the JavaScript implementation,
and then it was extended with dart/flutter concerns.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Primarily additive functionality and tests; main risk is subtle
cross-platform numeric/string canonicalization differences, mitigated by
extensive coverage and a Chrome CI run.
> 
> **Overview**
> Introduces `canonicalizeJson` (RFC 8785 canonical JSON) to
`packages/common`, producing deterministic, compact JSON by sorting
object keys, normalizing number formatting (including scientific
notation and trimming trailing zeros), and rejecting cycles; strict mode
errors on NaN/Infinity with an optional lenient mode that replaces them
with `null`.
> 
> Adds comprehensive unit tests (including golden test vectors) plus a
dedicated platform-parity test suite, and updates CI to run the
canonicalization tests on Chrome to catch Dart VM vs JavaScript
serialization differences early. The new API is exported from
`launchdarkly_dart_common.dart` for downstream use.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
5de41dc. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

.github/actions/ci/action.yml

@@ -54,6 +54,15 @@ runs:
       shell: bash
       run: melos run test
 
+    - name: Platform Canonicalization Tests (Chrome)
+      shell: bash
+      # Run RFC 8785 canonicalization tests on Chrome to verify platform-independent behavior.
+      # These tests ensure that the canonicalization produces identical output on both
+      # Dart VM (tested above via melos run test) and Dart2JS/JavaScript (tested here).
+      run: |
+        cd packages/common
+        dart test test/serialization/canonicalize_json_platform_test.dart -p chrome --test-randomize-ordering-seed=random
+
     - name: Contract Tests
       shell: bash
       run: |

packages/common/lib/launchdarkly_dart_common.dart

@@ -28,6 +28,7 @@ export 'src/serialization/ld_evaluation_results_serialization.dart'
     show LDEvaluationResultsSerialization;
 export 'src/serialization/ld_context_serialization.dart'
     show LDContextSerialization;
+export 'src/serialization/canonicalize_json.dart' show canonicalizeJson;
 export 'src/serialization/event_serialization.dart'
     show
         IdentifyEventSerialization,

packages/common/lib/src/serialization/canonicalize_json.dart

@@ -0,0 +1,131 @@
+import 'dart:convert';
+
+/// Serialize a number according to RFC 8785 rules.
+///
+/// Per RFC 8785, NaN and Infinity are forbidden and implementations
+/// must terminate with an error if encountered. However, when [lenient]
+/// is true, these values are replaced with null instead.
+String _serializeNumber(num value, {required bool lenient}) {
+  // RFC 8785 requires termination with error for NaN and Infinity
+  // In lenient mode, replace with null instead
+  if (value.isNaN) {
+    if (lenient) {
+      return 'null';
+    }
+    throw ArgumentError('NaN is not allowed in RFC 8785 canonical JSON');
+  }
+  if (value.isInfinite) {
+    if (lenient) {
+      return 'null';
+    }
+    throw ArgumentError('Infinity is not allowed in RFC 8785 canonical JSON');
+  }
+
+  // Check if it's an integer value (even if stored as double)
+  // Per RFC 8785/ECMA-262: integers with magnitude >= 10^21 must use
+  // scientific notation, not plain decimal. Only convert to int if the
+  // value is small enough for plain decimal representation.
+  const maxPlainDecimal = 1e21;
+  if (value == value.toInt() && value.abs() < maxPlainDecimal) {
+    return value.toInt().toString();
+  }
+
+  // For non-integer values or large integers, use Dart's toString()
+  // Dart's num.toString() returns the shortest string that uniquely identifies
+  // the number, using exponential notation outside the range 10^-6 to 10^21.
+  // On web platforms, Dart defers to JavaScript's number serialization.
+  // See: https://api.dart.dev/dart-core/num/toString.html
+  String str = value.toString();
+
+  // RFC 8785 requires lowercase 'e' in scientific notation
+  // Dart may produce uppercase 'E', so normalize it
+  if (str.contains('E')) {
+    str = str.replaceAll('E', 'e');
+  }
+
+  // Remove unnecessary trailing zeros after decimal point
+  // (but only if not in scientific notation)
+  if (str.contains('.') && !str.contains('e')) {
+    str = str.replaceAll(RegExp(r'\.?0+$'), '');
+  }
+
+  return str;
+}
+
+/// Internal implementation of canonicalize that tracks visited objects.
+String _canonicalizeJson(dynamic object,
+    {required bool lenient, List<dynamic> visited = const []}) {
+  // Handle null
+  if (object == null) {
+    return 'null';
+  }
+
+  // Handle primitives
+  if (object is num) {
+    return _serializeNumber(object, lenient: lenient);
+  }
+
+  if (object is bool) {
+    return object.toString();
+  }
+
+  if (object is String) {
+    return jsonEncode(object);
+  }
+
+  // Check for cycles
+  if (visited.contains(object)) {
+    throw ArgumentError('Cycle detected');
+  }
+
+  // Handle arrays
+  if (object is List) {
+    final newVisited = [...visited, object];
+    final values = object.map((item) =>
+        _canonicalizeJson(item, lenient: lenient, visited: newVisited));
+    return '[${values.join(',')}]';
+  }
+
+  // Handle objects/maps
+  if (object is Map) {
+    final newVisited = [...visited, object];
+
+    // Create a list of key-value pairs with string keys for sorting
+    final entries = object.entries.map((entry) {
+      final keyStr = entry.key.toString();
+      return MapEntry(keyStr, entry);
+    }).toList()
+      ..sort((a, b) => a.key.compareTo(b.key));
+
+    final serializedValues = entries.map((entry) {
+      final keyStr = entry.key;
+      final originalValue = entry.value.value;
+      final value = _canonicalizeJson(originalValue,
+          lenient: lenient, visited: newVisited);
+      // Include the key-value pair only if the value is not undefined
+      // (In Dart, we don't have undefined, so we include all values)
+      return '${jsonEncode(keyStr)}:$value';
+    });
+
+    return '{${serializedValues.join(',')}}';
+  }
+
+  // For any other object type, we can't serialize it
+  throw ArgumentError(
+      'Cannot canonicalize object of type ${object.runtimeType}');
+}
+
+/// Given some object to serialize, produce a canonicalized JSON string
+/// according to RFC 8785 (https://www.rfc-editor.org/rfc/rfc8785.html).
+///
+/// We do not support custom toJson methods on objects. Objects should be
+/// limited to basic types.
+///
+/// When [lenient] is false (default), throws an [ArgumentError] if NaN or
+/// Infinity is encountered, per RFC 8785 requirements. When [lenient] is
+/// true, NaN and Infinity are replaced with null for safety.
+///
+/// Throws an [ArgumentError] if a cycle is detected in the object graph.
+String canonicalizeJson(dynamic object, {bool lenient = false}) {
+  return _canonicalizeJson(object, lenient: lenient);
+}

packages/common/test/serialization/canonicalize_json_platform_test.dart

@@ -0,0 +1,151 @@
+// Platform-independent canonicalization tests for RFC 8785.
+//
+// These tests verify that JSON canonicalization produces identical results
+// on both Dart VM (native) and Dart2JS (web) platforms.
+//
+// In CI, these tests run on both platforms:
+// - VM platform: via `melos run test`
+// - Chrome platform: via dedicated CI step (see .github/actions/ci/action.yml)
+//
+// To run locally on both platforms:
+//   dart test test/serialization/canonicalize_json_platform_test.dart -p vm,chrome
+
+import 'dart:convert';
+import 'package:launchdarkly_dart_common/src/serialization/canonicalize_json.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('Platform-independent canonicalization', () {
+    // These tests verify that canonicalization produces identical results
+    // on both Dart VM (native) and Dart2JS (web) platforms
+
+    final testCases = <String, dynamic>{
+      // Large numbers that could expose platform differences
+      '1e30': 1e30,
+      '1e21': 1e21,
+      '1e-27': 1e-27,
+
+      // Integer-valued doubles
+      '56': 56.0,
+      '42': 42,
+      '0': 0.0,
+      '-100': -100.0,
+
+      // Fractional numbers
+      '3.14': 3.14,
+      '4.5': 4.50, // Should remove trailing zero
+      '0.002': 2e-3,
+
+      // Objects with mixed numeric types
+      'object with numbers': {
+        'int': 42,
+        'double': 3.14,
+        'large': 1e30,
+        'small': 1e-27,
+        'zero': 0.0,
+      },
+
+      // Arrays with various number types
+      'array of numbers': [1, 2.5, 1e10, 1e-5, 0],
+
+      // Edge cases
+      'negative zero': -0.0,
+      'negative large': -1e30,
+
+      // Complex nested structure
+      'complex': {
+        'z': 99,
+        'a': {
+          'nested': 1e20,
+          'values': [1, 2.5, 3.0],
+        },
+        'm': true,
+      }
+    };
+
+    // Expected outputs (platform-independent)
+    final expectedOutputs = <String, String>{
+      '1e30': '1e+30',
+      '1e21': '1e+21',
+      '1e-27': '1e-27',
+      '56': '56',
+      '42': '42',
+      '0': '0',
+      '-100': '-100',
+      '3.14': '3.14',
+      '4.5': '4.5',
+      '0.002': '0.002',
+      'object with numbers':
+          '{"double":3.14,"int":42,"large":1e+30,"small":1e-27,"zero":0}',
+      'array of numbers': '[1,2.5,10000000000,0.00001,0]',
+      'negative zero': '0',
+      'negative large': '-1e+30',
+      'complex':
+          '{"a":{"nested":100000000000000000000,"values":[1,2.5,3]},"m":true,"z":99}',
+    };
+
+    for (var entry in testCases.entries) {
+      test('${entry.key} produces platform-independent output', () {
+        final result = canonicalizeJson(entry.value);
+        final expected = expectedOutputs[entry.key];
+
+        expect(result, equals(expected),
+            reason:
+                'Value ${entry.key} should produce the same output on all platforms');
+
+        // Verify it's valid JSON by round-tripping
+        expect(() => jsonDecode(result), returnsNormally,
+            reason: 'Output should be valid JSON');
+      });
+    }
+
+    test('large integer double (1.0) representation', () {
+      // This test specifically checks behavior that could differ between platforms
+      // On native: 1.0.toString() -> "1.0"
+      // On web: 1.0.toString() -> "1"
+      // Our canonicalization should always produce "1"
+
+      final result = canonicalizeJson(1.0);
+      expect(result, equals('1'),
+          reason: 'Integer-valued doubles should not include decimal point');
+    });
+
+    test('scientific notation normalization', () {
+      // Dart might produce "1E+30" on some platforms
+      // We normalize to lowercase "1e+30"
+
+      final result = canonicalizeJson(1e30);
+      expect(result, equals('1e+30'));
+      expect(result, isNot(contains('E')),
+          reason: 'Should use lowercase e, not uppercase E');
+    });
+
+    test('complex structure produces deterministic output', () {
+      final obj = {
+        'numbers': [1e30, 56.0, 3.14],
+        'nested': {
+          'z': 'last',
+          'a': 'first',
+        },
+      };
+
+      // Should be the same on all platforms
+      final result = canonicalizeJson(obj);
+      expect(
+          result,
+          equals(
+              '{"nested":{"a":"first","z":"last"},"numbers":[1e+30,56,3.14]}'));
+    });
+
+    test('lenient mode works consistently across platforms', () {
+      final result1 = canonicalizeJson(double.nan, lenient: true);
+      expect(result1, equals('null'));
+
+      final result2 = canonicalizeJson(double.infinity, lenient: true);
+      expect(result2, equals('null'));
+
+      final result3 = canonicalizeJson(double.negativeInfinity, lenient: true);
+      expect(result3, equals('null'));
+    });
+  });
+}