In Dart, what does the covariant keyword on a parameter do, and why do Flutter overrides like CustomPainter.shouldRepaint rely on it?

## The rule that `covariant` bends When a subclass **overrides** a method, Dart requires the override to be usable everywhere the original is. For a parameter, that means the override may accept the **same type or a supertype**, never a narrower subtype: ```dart class Animal { void chase(Animal a) {} } class Mouse extends Animal {} class Cat extends Animal { @override void chase(Mouse a) {} // invalid override: narrows Animal to Mouse } ``` The reason is substitution: code holding `Animal pet = Cat();` may call `pet.chase(Alligator())`, and a `Cat` that only handles mice would receive something it cannot handle. ## What the keyword changes Some designs genuinely want the narrow parameter, most often when an object compares itself with **another instance of the same subclass**. Marking the parameter **`covariant`** says "I know, and I accept the risk": 1. The **static error disappears** — the override compiles. 2. Dart adds a **runtime check** on that parameter. A call through the supertype with an argument that is not the narrowed type throws a **`TypeError`** before the body runs. 3. Calls through the subclass's own static type are checked at compile time as usual. The keyword can be written on the **base** declaration or on the **override**. Written on the base, it makes that parameter covariant in every override, so subclasses narrow it without repeating the word — the Dart documentation recommends the superclass as the usual place. ## Where Flutter uses it Flutter puts `covariant` on base declarations whose subclasses always compare themselves with an older copy of the same class: | Base declaration in Flutter | What your subclass writes | |---|---| | `bool shouldRepaint(covariant CustomPainter oldDelegate)` | `bool shouldRepaint(RingPainter oldDelegate)` | | `bool updateShouldNotify(covariant InheritedWidget oldWidget)` | `bool updateShouldNotify(ThemeScope oldWidget)` | | `void didUpdateWidget(covariant T oldWidget)` on `State<T>` | `void didUpdateWidget(Counter oldWidget)` | The framework only ever passes the previous instance of the same class, so the runtime check never fires in normal use, and your code reads `oldDelegate.progress` directly instead of casting with `as`. ## Where it is allowed The modifier applies to **one parameter at a time** and only to members that can be overridden: - parameters of **instance methods** and **operators**; - the parameter of an **instance setter**; - a **mutable instance field**, which makes its implicit setter's parameter covariant; - since Dart 3.13, a **primary constructor** parameter only when it is a mutable declaring parameter written with `var`. Top-level functions and static methods cannot use it, because nothing overrides them. It is also not a variance annotation on a type parameter: `class Box<covariant T>` is not Dart. ## Relation to covariant generics The same idea already runs inside every generic class. `List<E>.add(E value)` behaves as if its parameter were covariant: seen as a `List<Animal>`, a `List<Cat>` checks each added value at run time. The keyword lets you opt into that behaviour for an ordinary, non-generic parameter. ## When to use it - **Use it** for "compare with another of my own kind" members — equality-like checks, `shouldRepaint`-style hooks, `copyFrom(covariant Shape other)` patterns. - **Avoid it** as a shortcut for a hierarchy that is simply wrong. If callers routinely pass other subtypes, the check will fire in production; a generic base class, such as `abstract class Shape<S extends Shape<S>>`, or a separate method is the better design. - **Document it**: a covariant parameter is a promise that callers going through the base type will pass the right subtype. ## Reading one in code review When a narrowed parameter shows up in a diff, three questions settle it: 1. **Who calls it through the base type?** For `shouldRepaint`, only the framework, and only with the previous painter of the same class, so the check cannot fire. For a method your own code calls on a `List<Shape>`, it can. 2. **Is the narrowing on the base or on one override?** A `covariant` written only on one subclass is easy to miss; on the base declaration it is part of the contract every implementer reads. 3. **Would a failing call be a bug or an expected case?** If mixed arguments are legitimate, the method should accept the base type and branch with a type test or a `switch` on a sealed hierarchy instead of throwing a `TypeError`.