Generics and the type system

A generic is a class or function that takes a type as a parameter. The goal: reuse the same logic across different types without losing type safety.

• Generic class: class Cache<T> { T? get(String key); void put(String key, T value); }
• Generic function: T firstOr<T>(List<T> items, T fallback) => items.isEmpty ? fallback : items.first;
• Several parameters: class Pair<A, B> { ... }

The alternative — making everything dynamic — shortens the code but pushes every mistake to runtime. A generic instead knows the concrete type at the call site: for a Cache<User>, get returns User? and the compiler checks it.

A bounded generic constrains the type parameter: T extends Comparable<T> allows only comparable types. That is what lets you call the type's methods inside the generic body. Without a bound, T behaves as Object? and there is almost nothing you can do with it.

Covariance and its price. Generics in Dart are covariant: List<int> is considered a subtype of List<num>. That makes everyday code convenient (you can pass a List<int> to a function expecting List<num>), but it is not safe for writes.

The scenario: List<int> ints = [1, 2]; List<num> nums = ints; nums.add(3.5); — statically everything is legal, because 3.5 is a num. At runtime the object is still a List<int> and add throws a TypeError.

To stay sound, Dart inserts a runtime downcast check — which is exactly why the failure happens at the add call rather than at compile time. Covariance is a deliberate trade for convenience, and its price is that small runtime check.

The practical consequence: when an API accepts a shared collection at a wider type (List<num>), either take it read-only (Iterable<num>) or make your own copy (List<num>.from(...)).

`is`, `as` and promotion. is is a runtime type test; when it succeeds, flow analysis promotes the variable and no as is needed. as is a cast that throws a TypeError when wrong. is! is the negated form.

The rule: before writing `as`, ask whether an `is` check would do. if (x is User) { x.name } is both safer and more readable than a cast. Dart 3 patterns take it one step further: if (x case User(:final name)).

Legitimate uses of as: dynamic boundaries such as the result of jsonDecode, generics where the type is known at the call site, and platform interop. For every as, ask: if this cast is wrong, where does the error surface — here, or three screens later?

Note: a cast on a dynamic value gives no static checking at all — dynamic d = 'text'; final n = d as int; only throws at runtime while the analyzer stays silent.