diff --git a/resources/type-system/strict-raw-types.md b/resources/type-system/strict-raw-types.md new file mode 100644 index 0000000000..19f74aa137 --- /dev/null +++ b/resources/type-system/strict-raw-types.md @@ -0,0 +1,125 @@ +# Strict raw types static analysis option + +This document specifies the "Strict raw types" mode enabled with a static +analysis option. As a static analysis option, we only intend to implement this +feature in the Dart Analyzer. Under this feature, a type with omitted type +argument(s) is defined as a "raw type." Dart fills in such type arguments with +their bounds, or `dynamic` if there are no bounds. + +## Enabling strict raw types + + To enable strict raw types, set the `strict-raw-types` option to `true`, under + the Analyzer's `language` section: + + ```yaml +analyzer: + language: + strict-raw-types: true +``` + +## Motivation + +It is possible to write Dart code that passes all static type analysis and +compile-time checks that is guaranteed to result in runtime errors. Common +examples include runtime type errors, and no-such-method errors. Developers are +often surprised to see such errors at runtime, which look like they should be +caught at compile time. + +The strict raw types mode aims to highlight such code during static analysis. +We can look at some common examples: + +```dart +void main() { + List a = [1, 2, 3]; +} +``` + +Developers often think that inference fills in the type of `a` from the right +side of the assignment. It may look like `a` has the type `List`. But Dart +fills in omitted type arguments, like `E` on `List`, with `dynamic` (or the +corresponding type parameter's bound); `List a;` is purely a shorthand for +`List a;`. Inference then flows from `a` onto the expression on the +right side of the assignment. This is more obvious in another example: + +```dart +void main() { + List a = [1, 2, 3]..forEach((e) => print(e.length)); + var b = [4, 5, 6]..forEach((e) => print(e.length)); +} +``` + +The first statement does not result in any static analysis errors, since the +type of the list is inferred to be `List`. Instead, the code results +in a runtime no-such-method error, when the `length` getter is called on an +`int`. + +The second statement, however, allows the type of the list to be inferred from +its elements, as `List`, which results in a static analysis type error, +which notes that the getter `length` is not defined on `int`. + +Raw types can also lead to unintended dynamic dispatch: + +```dart +void main() { + List a = [1, 2, 3]; + a.forEach((e) => print(e.isEven)); +} +``` + +The developer likely does not realize that the parameter `e` of the callback is +`dynamic`, and that the call to `isEven` is a dynamic dispatch. + +Reporting strict raw types encourages developers to fill in omitted type +arguments, hopefully with something other than `dynamic`. In cases where the +only good type is `dynamic`, then including it as an explicit type argument +avoids the raw type, and makes the dynamic behavior more explicit in the code. + +## Conditions for a raw type Hint + +Any raw type results in a raw type Hint, except under the following conditions: + +* the raw type is on the right side of an `as` or an `is` expression +* the raw type is defined by a class, mixin, or typedef annotated with the + `optionalTypeArgs` annotation from the meta package. + +## Examples + +This section is non-normative. It does not represent an exhaustive selection of +conditions for a raw type Hint. + +```dart +import 'package:meta/meta.dart'; + +List l1 = [1, 2, 3]; // Hint +List l2 = [1, 2, 3]; // Hint +final f1 = Future.value(7); // OK + +fn1(Map map) => print(map); // Hint +Map fn2() => {}; // Hint + +class C1 { + List l3 = [1, 2, 3]; // Hint + print([] is Set); // OK + + m(Map map) => print(map); // Hint +} + +class C2 {} + +class C3 extends C2 {} // Hint +class C4 implements C2 {} // Hint +class C5 with C2 {} // Hint + +typedef Callback = void Function(T); + +Callback = (int n) => print(n); // Hint + +@optionalTypeArgs +class C6 {} + +C6 a; // OK +List b; // OK +C6 c; // Hint + +class C7 extends C6 {} // OK +```