---
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.

### When NOT to use (Abstention Guardrails)

Do NOT apply modern features or refactor code when:

- **SDK Constraint < 3.0.0**: The package's `pubspec.yaml` specifies an SDK
  constraint that supports Dart 2.x (e.g., `sdk: '>=2.19.0 <4.0.0'`).
  Refactoring to Dart 3 features will introduce syntax errors for Dart 2 users.
- **Single-Variable Type Promotion**: Checking a single variable or parameter
  where standard `if (x is Foo)` is clearer, more concise, and avoids creating
  unnecessary alias variables compared to `if (x case final Foo f)`.
- **Non-Algebraic Boolean Branching**: Branching on independent boolean flags,
  side-effecting conditions, or early-exit guard clauses
  (`if (!condition) return;`). Do not force these into switch expressions.
- **Deep Expression Nesting**: Complex multi-step operations where converting a
  switch statement into a deeply nested switch expression obscures intent, harms
  debugger step-through capability, or hurts stack trace readability.

## 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/JSON property extraction, type checking, or list/segment
indexing:

- **Regex**: `containsKey\(['"][^'"]+['"]\)`
- **Regex**: `json\[['"][^'"]+['"]\]\s+is\s+`
- **Regex**: `\.length\s*(>=|==|>|<)\s*\d+` (Combined with manual list index
  access like `\[0\]`, `\[1\]`, `.first`, or `\[\w+\.length\s*-\s*\d+\]`).
- **Regex**: `\.skip\(1\)|\.sublist\(1\)` (Tail slicing replaceable by
  `[head, ...final rest]`).
- **Regex**: `\.split\([^)]+\)` (Followed by `.length` or index checks; note
  that matching `[final first, final second, ...final rest]` guarantees at least
  one delimiter was present).

### 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(...),
}
```

#### 3. Use `switch` Expressions or Inline `if-case` for Boolean Returns

In Dart 3 grammar, `<expr> case <pattern> [when <guard>]` is a `caseClause`
valid only inside `if (...)`, `for (...; ...; ...)`, or `while (...)` headers.
It is **not** a standalone boolean expression like `is`. To return a `bool` from
a pattern check, either inline `if (segments case [...])` at the branch site or
use a `switch` expression.

**Avoid:**

```dart
// ❌ Compile error: 'case' cannot be used as a standalone expression
bool isCommentsRoute(List<String> segments) =>
    segments case ['api', 'comments', ...];
```

**Prefer:**

```dart
// ✅ Switch expression evaluates to a boolean value
bool isCommentsRoute(List<String> segments) => switch (segments) {
  ['api', 'comments', ...] => true,
  _ => false,
};
```

#### 4. Use `Set.contains` in `when` Guards over Long `||` Pattern Chains

Each `||` logical-or pattern operator adds `+1` to cognitive complexity metrics
(e.g., `analytica.dart`). When checking single-element membership against an
existing `Set` or a large list of constant strings, bind the element in the list
pattern and check `allowedSet.contains(first)` in the `when` guard (or keep a
direct `Set.contains` check when no tail destructuring is needed).

**Avoid:**

```dart
// ❌ High cognitive complexity (+6 for 7 literals chained with ||)
if (segments case [
  'status' || 'chat' || 'assets' || 'static' || 'api' || 'documents' || 'r',
  ...final rest,
]) {
  handleRoute(rest);
}
```

**Prefer:**

```dart
// ✅ Binds head and tail cleanly with O(1) Set lookup in `when`
const allowedTopLevel = {
  'status', 'chat', 'assets', 'static', 'api', 'documents', 'r',
};
if (segments case [final first, ...final rest]
    when allowedTopLevel.contains(first)) {
  handleRoute(rest);
}
```

## Related Skills

- **[dart-best-practices]**: General code style and foundational Dart idioms
  that predate or complement the modern syntax features.
- **[dart-use-pattern-matching]**: Comprehensive pattern matching, list/path
  segment destructuring, and `String.split()` idioms.

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