dart-modern-features

--- name: dart-modern-features description: |- Guidelines for using modern Dart features (v3.0 - v3.10) such as Records, Pattern Matching, Switch Expressions, Extension Types, Class Modifiers, Wildcards, Null-Aware Elements, and Dot Shorthands. key_features: - Records & Pattern Matching - Switch Expressions & Extension Types - Class Modifiers & Null-aware elements ---

# Dart Modern Features

## 1. When to use this skill

Use this skill when: - Writing or reviewing Dart code targeting Dart 3.0 or later. - Refactoring legacy Dart code to use modern, concise, and safe features. - Looking for idiomatic ways to handle multiple return values, deep data extraction, or exhaustive checking.

## Discovery

To find candidates for modernization:

### Switch Expressions Search for switch statements where every case assigns to the same variable or returns: - **Regex**: `switch\s*\([^)]+\)\s*\{\s*case`

### Pattern Matching Candidates Search for manual map or JSON property extraction and type checking: - **Regex**: `containsKey\(['"][^'"]+['"]\)` - **Regex**: `json\[['"][^'"]+['"]\]\s+is\s+`

### Null-Aware Elements Search for collection `if` statements checking for null: - **Regex**: `if\s*\(\w+\s*!=\s*null\)\s*\w+`

### Digit Separators Search for long numbers without separators: - **Regex**: `\b\d{6,}\b` (Matches numbers with 6 or more digits).

## 2. Features

### Records Use records as anonymous, immutable, aggregate structures to bundle multiple objects without defining a custom class. Prefer them for returning multiple values from a function or grouping related data temporarily.

**Avoid:** Creating a dedicated class for simple multiple-value returns. ```dart class UserResult { final String name; final int age; UserResult(this.name, this.age); }

UserResult fetchUser() { return UserResult('Alice', 42); } ```

**Prefer:** Using records to bundle types seamlessly on the fly. ```dart (String, int) fetchUser() { return ('Alice', 42); }

void main() { var user = fetchUser(); print(user.$1); // Alice } ```

### Patterns and Pattern Matching Use patterns to destructure complex data into local variables and match against specific shapes or values. Use them in `switch`, `if-case`, or variable declarations to unpack data directly.

**Avoid:** Manually checking types, nulls, and keys for data extraction. ```dart void processJson(Map<String, dynamic> json) { if (json.containsKey('name') && json['name'] is String && json.containsKey('age') && json['age'] is int) { String name = json['name']; int age = json['age']; print('$name is $age years old.'); } } ```

**Prefer:** Combining type-checking, validation, and assignment into a single statement. ```dart void processJson(Map<String, dynamic> json) { if (json case {'name': String name, 'age': int age}) { print('$name is $age years old.'); } } ```

### Switch Expressions Use switch expressions to return a value directly, eliminating bulky `case` and `break` statements.

**Avoid:** Using switch statements where every branch simply returns or assigns a value. ```dart String describeStatus(int code) { switch (code) { case 200: return 'Success'; case 404: return 'Not Found'; default: return 'Unknown'; } } ```

**Prefer:** Returning the evaluated expression directly using the `=>` syntax. ```dart String describeStatus(int code) => switch (code) { 200 => 'Success', 404 => 'Not Found', _ => 'Unknown', }; ```

### Class Modifiers Use class modifiers (`sealed`, `final`, `base`, `interface`) to restrict how classes can be used outside their defines library. Prefer `sealed` for defining closed families of subtypes to enable exhaustive checking.

**Avoid:** Using open `abstract` classes when the set of subclasses is known and fixed. ```dart abstract class Result {}

class Success extends Result {} class Failure extends Result {}

String handle(Result r) { if (r is Success) return 'OK'; if (r is Failure) return 'Error'; return 'Unknown'; } ```

**Prefer:** Using `sealed` to guarantee to the compiler that all cases are covered. ```dart sealed class Result {}

class Success extends Result {} class Failure extends Result {}

String handle(Result r) => switch(r) { Success() => 'OK', Failure() => 'Error', }; ```

### Extension Types Use extension types for a zero-cost wrapper around an existing type. Use them to restrict operations or add custom behavior without runtime overhead.

**Avoid:** Allocating new wrapper objects just for domain-specific logic or type safety. ```dart class Id { final int value; Id(this.value); bool get isValid => value > 0; } ```

**Prefer:** Using extension types which compile down to the underlying type at runtime. ```dart extension type Id(int value) { bool get isValid => value > 0; } ```

### Digit Separators Use underscores (`_`) in number literals strictly to improve visual readability of large numeric values.

**Avoid:** Long number literals that are difficult to read at a glance. ```dart const int oneMillion = 1000000; ```

**Prefer:** Using underscores to separate thousands or other groupings. ```dart const int oneMillion = 1_000_000; ```

### Wildcard Variables Use wildcards (`_`) as non-binding variables or parameters to explicitly signal that a value is intentionally unused.

**Avoid:** Inventing clunky, distinct variable names to avoid "unused variable" warnings. ```dart void handleEvent(String ignoredName, int status) { print('Status: $status'); } ```

**Prefer:** Explicitly dropping the binding with an underscore. ```dart void handleEvent(String _, int status) { print('Status: $status'); } ```

### Null-Aware Elements Use null-aware elements (`?`) inside collection literals to conditionally include items only if they evaluate to a non-null value.

**Avoid:** Using collection `if` statements for simple null checks. ```dart var names = [ 'Alice', if (optionalName != null) optionalName, 'Charlie' ]; ```

**Prefer:** Using the `?` prefix inline. ```dart var names = ['Alice', ?optionalName, 'Charlie']; ```

### Dot Shorthands Use dot shorthands to omit the explicit type name when it can be confidently inferred from context, such as with enums or static fields.

**Avoid:** Fully qualifying type names when the type is obvious from the context. ```dart LogLevel currentLevel = LogLevel.info; ```

**Prefer:** Reducing visual noise with inferred shorthand. ```dart LogLevel currentLevel = .info; ```

### Pragmatic Balance: When NOT to Over-Patternize Pattern matching and switch expressions should simplify code, not add syntactic overhead.

#### 1. Prefer `is` Type Promotion over `if-case` for Single Variables If you only need to check a type or promote a variable, use standard `is` checks instead of `if-case` or `case` patterns that introduce shadow aliases.

**Avoid:** ```dart // ❌ Anti-pattern: Introduces unnecessary alias variable `k` for (final MapEntry(:key, :value) in map.entries) { if (key case final String k when value != null) { process(k, value); } } ```

**Prefer:** ```dart // ✅ Promotes `key` directly in-place without extra variables for (final MapEntry(:key, :value) in map.entries) { if (key is String && value != null) { process(key, value); } } ```

#### 2. Consolidate Nullable Types in Switch Arms When mapping or returning values in a switch expression where both `null` and a type `T` are valid and passed through, match the nullable type `T?` directly rather than creating redundant `null` arms.

**Avoid:** ```dart // ❌ Redundant separate null arm switch (value) { final String s => s, null => null, _ => throw FormatException(...), } ```

**Prefer:** ```dart // ✅ Clean nullable pattern match switch (value) { final String? s => s, _ => throw FormatException(...), } ```

## Related Skills

- **[dart-best-practices]**: General code style and foundational Dart idioms that predate or complement the modern syntax features.

[dart-best-practices]: https://github.com/kevmoo/dash_skills/blob/main/skills/dart-best-practices/SKILL.md