New annotations for enforcing types

[FMorschel]

I recently had a discussion on Discord about ThemeData.cardTheme that was accepting an Object parameter in the current stable (because it originally accepted CardTheme), and with this issue and PR, CardThemeData was created. In the current master, the old CardTheme can only be used as a Widget (here is the migration guide as a reference).

I'm not sure we have some annotation that could help users in this process. Something like "In a future version, we will stop supporting this type here" to be added to a parameter.

So we could do:

void foo(
  @WillStopSupporting(double, '1.2.3')
  num value
) {
  //Some code
}

I could not find any similar issue, so I opened this one to gather more thoughts.

Something like this could also help (if the logic is reversed) if we want to do something like the above, but only accepting CardTheme and CardThemeData (without union types), so we could say "We only accept these types here" in a way that the user can handle without running the code and failing or going through the docs to find all possibilities.

For visibility @lrhn @srawlins @bwilkerson

[lrhn]

SGTM, obviously. See: #60504, in particular Deprecated.type<T>.

Rather than saying which type you would stop supporting, which may not be directly usable, if fx an Object parameter says it will stop accepting String, say what they type changes to. (Here it would be int, when num stops supporting double.)

[FMorschel]

Great idea.

What about a "union type"-like parameter? There could be a named constructor that accepts a list of types, I think.

[Reprevise]

While this is useful for deprecations, I think it could expanded into a union type annotation. I could see it being useful for Uri.queryParameters because it's a Map<String, dynamic> which is really just Map<String, String?>|Map<String, Iterable<String>>. If we could have an annotation to specify the types it could prevent some runtime errors.

To avoid having to specify it everywhere we can create a typedef and just apply the annotation to that. (I don't know if this would actually work, but it's a neat idea I think.)

@UnionType([Map<String, String?>, Map<String, Iterable<String>])
typedef QueryParameters = Map<String, dynamic>;

EDIT: Okay I just looked at the queryParameters type again and realized it's actually typed like Map<String, String?|Iterable<String>> which means that if you're mixing strings and iterables in the same map that you actually just end up with Map<String, Object> and this "UnionType" annotation wouldn't really work. We'd have to have an annotation that either targets the map's value type or somehow apply an annotation to the value type itself like Map<String, @UnionType([String?, Iterable<String>]) dynamic>.