Confusing legacy tag for "Union types and Sealed classes"

[romatallinn]

Context

The documentation marks the whole chapter of Union types and Sealed classes as Legacy. It gives an impression that this whole thing should be avoided and be better done in native dart. It gives a note explaining the details, and the case for map/when vs switch is clear and contains accurate reasoning.

Problem

Nevertheless, if I am not mistaken, Union types and Sealed classes themselves are not outdated and are still relevant? It's just map/when should be replaced with switch and alike?

Relevant use-case for union types: parsing json and convert it to a specific model by unionKey.

Solution

Re-structure chapter in the way that block about map/when specifically is noted as legacy, but not union types as a whole.

Additional context

As of Dart 3, Dart now has built-in pattern-matching using sealed classes.
As such, you no-longer need to rely on Freezed's generated methods for pattern matching. Instead of using when/map, use the official Dart syntax.

[romatallinn]

I can imagine it's me missing a common way to replace this functionality with dart-native, but I doubt it. My unionKey example--and especially unionValueCase extra (which is super useful)--is quite an extra utility that is not supported by dart from the box.