/dart-language

name: dart-language
description: "Dart 3.x language feature standards: null safety, records, sealed classes, switch pattern matching, extensions, and async/await. Use when using !, ?., ??, late, sealed classes, record types, switch expressions, or async patterns — and before introducing any new Dart 3.x construct to confirm the modern idiomatic approach."
metadata:
  triggers:
    files:
      - "**/*.dart"
    keywords:
      - sealed
      - record
      - switch
      - pattern
      - "!"
      - late
      - async
      - extension

Dart Language Patterns

**Priority: P0 (CRITICAL)**

Implementation Guidelines

• **Null Safety**: Avoid `!`. Use `?.`, `??`, or short-circuiting. Use `late` only if necessary.
• **Immutability**: Use `final` for all variables. Use `@freezed` for data classes.
• **Pattern Matching (3.x)**: Use `switch (value)` with patterns and destructuring.
• **Records**: Use a Record (e.g., `(String, int)`) for multiple values; use named fields when meaning matters. Destructure at call sites: `final (error, data) = fetchUser();`.
• **Sealed Classes**: Use `sealed class` for exhaustive state handling in domain logic.
• **Extensions**: Use `extension` to add utility methods to third-party types.
• **Wildcards (3.7+)**: Use `_` for unused variables in declarations and patterns.
• **Tear-offs**: Prefer using tear-offs (e.g., `list.forEach(print)`) over anonymous lambdas (e.g., `list.forEach((e) => print(e))`).
• **Asynchrony**: Prefer `async/await` over raw `Future.then`. Use `unawaited` for fire-and-forget logic if necessary.
• **Encapsulation**: Use `_` prefix for library-private members. Prefer `final` properties.
• **Collections**: Use `collection-if`, `collection-for`, and spread operators `...`.
• **Safe List Access**: Prefer `.firstOrNull`, `.lastOrNull`, or `.elementAtOrNull(i)`.
• **No dynamic**: Use `Object` or generics instead of `dynamic`.
• **Type Aliases**: Use `typedef` for complex IDs or callbacks.

Anti-Patterns

• **No ! Operator**: not use bang operator `!` unless you can prove value non-null via `if` or `assert`.
• **No var for members**: not use `var` for class members; use `final` or explicit types.
• **No logic in constructors**: not perform complex calculations or async work inside constructors.
• **No zero-arg methods for pure computations**: Use a getter. `int get invoiceType =>` not `int toInvoiceType()`.
• **No generic conversion names**: Name value-object converters for their target context: `get apiFilterType` not `get invoiceType`.

Code

// Sealed class and Switch expression
sealed class Result {}
class Success extends Result { final String data; Success(this.data); }
class Failure extends Result {}

String message(Result r) => switch (r) {
  Success(data: var d) => "Got $d",
  Failure() => "Error",
};

References

• feature-based-clean-architecture | tooling

Null-safety checklist

• Replace `!` with `?`-aware access, explicit narrowing, or a guard clause; do not silence nullability with a force unwrap.

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• Replace ! with ?
• destructure,destructuring,final (error,result.error