v2.0.0 breaking changes for package:collection

Starts using Dart 3.0 class modifiers.
This is a breaking change, making some classes be `final` or `interface`
which prevents behavior that was previously possible.

Removes existing deprecated API, except for `whereNotNull`.

Deprecates API that is available in platform libraries (`IterableZip` class).

Changes behavior of `UnorderedIterableEquality`, `SetEquality` and `MapEquality`
to assume the compared collections' notions of equality agree with the
`Equality` object for elements/keys in the `UnorderedIterableEquality`/
`SetEquality`/`MapEquality` object.
This should improve performance of the equality comparisons, which currently
try to assume nothing, and therefore cannot use `.contains`/`.containsKey`/`[]`
on one collection with keys/values from the other collection

Exceptions:
- `CanonicalizedMap` marked `@sealed` instead of `final`.
  Was extended in at least one place. Fix to that package sent.

Author: lrhn

pkgs/collection/analysis_options.yaml

@@ -12,5 +12,4 @@ linter:
     - missing_whitespace_between_adjacent_strings
     - no_adjacent_strings_in_list
     - no_runtimeType_toString
-    - package_api_docs
     - unnecessary_await_in_return

pkgs/collection/lib/src/canonicalized_map.dart

@@ -4,13 +4,16 @@
 
 import 'dart:collection';
 
+import 'package:meta/meta.dart';
+
 /// A map whose keys are converted to canonical values of type `C`.
 ///
 /// This is useful for using case-insensitive String keys, for example. It's
 /// more efficient than a [LinkedHashMap] with a custom equality operator
 /// because it only canonicalizes each key once, rather than doing so for each
 /// comparison.
-final class CanonicalizedMap<C, K, V> implements Map<K, V> {
+@sealed // TODO: Make `final` when no longer extended.
+class CanonicalizedMap<C, K, V> implements Map<K, V> {
   final C Function(K) _canonicalize;
 
   final bool Function(K)? _isValidKeyFn;
@@ -25,10 +28,11 @@ final class CanonicalizedMap<C, K, V> implements Map<K, V> {
   /// The [isValidKey] function is called before calling [canonicalize] for
   /// methods that take arbitrary objects. It can be used to filter out keys
   /// that can't be canonicalized.
-  CanonicalizedMap(C Function(K key) canonicalize,
-      {bool Function(K key)? isValidKey})
-      : _canonicalize = canonicalize,
-        _isValidKeyFn = isValidKey;
+  CanonicalizedMap(
+    C Function(K key) canonicalize, {
+    bool Function(K key)? isValidKey,
+  }) : _canonicalize = canonicalize,
+       _isValidKeyFn = isValidKey;
 
   /// Creates a canonicalized map that is initialized with the key/value pairs
   /// of [other].
@@ -39,10 +43,12 @@ final class CanonicalizedMap<C, K, V> implements Map<K, V> {
   /// The [isValidKey] function is called before calling [canonicalize] for
   /// methods that take arbitrary objects. It can be used to filter out keys
   /// that can't be canonicalized.
-  CanonicalizedMap.from(Map<K, V> other, C Function(K key) canonicalize,
-      {bool Function(K key)? isValidKey})
-      : _canonicalize = canonicalize,
-        _isValidKeyFn = isValidKey {
+  CanonicalizedMap.from(
+    Map<K, V> other,
+    C Function(K key) canonicalize, {
+    bool Function(K key)? isValidKey,
+  }) : _canonicalize = canonicalize,
+       _isValidKeyFn = isValidKey {
     addAll(other);
   }
 
@@ -56,15 +62,19 @@ final class CanonicalizedMap<C, K, V> implements Map<K, V> {
   /// methods that take arbitrary objects. It can be used to filter out keys
   /// that can't be canonicalized.
   CanonicalizedMap.fromEntries(
-      Iterable<MapEntry<K, V>> entries, C Function(K key) canonicalize,
-      {bool Function(K key)? isValidKey})
-      : _canonicalize = canonicalize,
-        _isValidKeyFn = isValidKey {
+    Iterable<MapEntry<K, V>> entries,
+    C Function(K key) canonicalize, {
+    bool Function(K key)? isValidKey,
+  }) : _canonicalize = canonicalize,
+       _isValidKeyFn = isValidKey {
     addEntries(entries);
   }
 
   CanonicalizedMap._(
-      this._canonicalize, this._isValidKeyFn, Map<C, MapEntry<K, V>> base) {
+    this._canonicalize,
+    this._isValidKeyFn,
+    Map<C, MapEntry<K, V>> base,
+  ) {
     _base.addAll(base);
   }
 
@@ -92,8 +102,11 @@ final class CanonicalizedMap<C, K, V> implements Map<K, V> {
   }
 
   @override
-  void addEntries(Iterable<MapEntry<K, V>> entries) => _base.addEntries(entries
-      .map((e) => MapEntry(_canonicalize(e.key), MapEntry(e.key, e.value))));
+  void addEntries(Iterable<MapEntry<K, V>> entries) => _base.addEntries(
+    entries.map(
+      (e) => MapEntry(_canonicalize(e.key), MapEntry(e.key, e.value)),
+    ),
+  );
 
   @override
   Map<K2, V2> cast<K2, V2>() => _base.cast<K2, V2>();
@@ -158,14 +171,16 @@ final class CanonicalizedMap<C, K, V> implements Map<K, V> {
 
   @override
   V update(K key, V Function(V) update, {V Function()? ifAbsent}) =>
-      _base.update(_canonicalize(key), (pair) {
-        var value = pair.value;
-        var newValue = update(value);
-        if (identical(newValue, value)) return pair;
-        return MapEntry(key, newValue);
-      },
-          ifAbsent:
-              ifAbsent == null ? null : () => MapEntry(key, ifAbsent())).value;
+      _base.update(
+        _canonicalize(key),
+        (pair) {
+          var value = pair.value;
+          var newValue = update(value);
+          if (identical(newValue, value)) return pair;
+          return MapEntry(key, newValue);
+        },
+        ifAbsent: ifAbsent == null ? null : () => MapEntry(key, ifAbsent()),
+      ).value;
 
   @override
   void updateAll(V Function(K key, V value) update) =>
@@ -193,5 +208,6 @@ final class CanonicalizedMap<C, K, V> implements Map<K, V> {
   /// Creates a `Map<C,V>` (with the canonicalized keys).
   /// See [toMap].
   Map<C, V> toMapOfCanonicalKeys() => Map<C, V>.fromEntries(
-      _base.entries.map((e) => MapEntry<C, V>(e.key, e.value.value)));
+    _base.entries.map((e) => MapEntry<C, V>(e.key, e.value.value)),
+  );
 }

pkgs/collection/lib/src/unmodifiable_wrappers.dart

@@ -193,12 +193,4 @@ abstract mixin class UnmodifiableMapMixin<K, V> implements Map<K, V> {
   /// operations that change the map are disallowed.
   @override
   void clear() => _throw();
-
-  /// Throws an [UnsupportedError];
-  /// operations that change the map are disallowed.
-  set first(_) => _throw();
-
-  /// Throws an [UnsupportedError];
-  /// operations that change the map are disallowed.
-  set last(_) => _throw();
 }

pkgs/collection/pubspec.yaml

@@ -1,16 +1,20 @@
 name: collection
-version: 1.19.1
+version: 1.20.0-2.0.0.wip
 description: >-
   Collections and utilities functions and classes related to collections.
 repository: https://github.com/dart-lang/core/tree/main/pkgs/collection
 
 topics:
  - collections
  - data-structures
+ - equality
 
 environment:
-  sdk: ^3.4.0
+  sdk: ^3.7.0
+
+dependencies:
+  meta: ^1.16.0
 
 dev_dependencies:
-  dart_flutter_team_lints: ^3.0.0
+  dart_flutter_team_lints: ^3.3.0
   test: ^1.16.0

pkgs/collection/test/analysis_options.yaml

@@ -1,6 +1,6 @@
 include: ../analysis_options.yaml
 
-# Turn off the avoid_dynamic_calls lint for the test/ directory.
+# Turn off common lint violations for the test/ directory.
 analyzer:
   errors:
     avoid_dynamic_calls: ignore

pkgs/collection/test/extensions_test.dart

@@ -2051,7 +2051,7 @@ Iterable<T> iterable<T>(Iterable<T> values) sync* {
   yield* values;
 }
 
-Never unreachable([_, __, ___]) => fail('Unreachable');
+Never unreachable([Object? _, Object? _, Object? _]) => fail('Unreachable');
 
 String toString(Object? o) => '$o';
 

pkgs/collection/test/iterable_zip_test.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.
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 import 'package:collection/collection.dart';
 import 'package:test/test.dart';