dart-use-primary-constructors

Files (1)

• SKILL.md

SKILL.md (first lines)

# Dart Primary Constructors & New Constructor Syntax Skill

Use this skill when helping users write, refactor, or debug code using Dart's **Primary Constructors** feature.

### Dart Version Requirements
*   **Dart 3.13 and above**: Primary constructors are enabled by default.
*   **Dart 3.12**: The feature is available but experimental. Users must explicitly enable the experiment flag `primary-constructors` via `--enable-experiment=primary-constructors` or in `analysis_options.yaml`:
```yaml
analyzer:
  enable-experiment:
    - primary-constructors
```
*   **Dart 3.11 and earlier**: Primary constructors are not supported.

---

## 1. Overview
Primary Constructors allow developers to declare a non-redirecting generative constructor as well as a set of instance variables directly in the class header. This significantly reduces boilerplate and improves code readability.

### Key Benefits
- Combines field declaration, parameter declaration, and initialization into a single declaration known as a declaring parameter declaration.
- Enables safe reference to constructor parameters in non-late field initializers (Primary Initializer Scope).
- Allows empty declaration bodies to be represented concisely with a semicolon (`;`).
- Introduces abbreviated concise syntax for in-body constructors.

---

## 2. Syntax Reference

### 2.1 Basic Class Header Syntax
To declare a primary constructor, place a parameter list immediately after the type name (and optional type parameters):

```dart
// Declares fields x and y, and a generative constructor Point(this.x, this.y)
class Point(var int x, var int y);

// Declares final fields
class PointFinal(final int x, final int y);
```

### 2.2 Declaring, Initializing, and Plain Parameters
A primary constructor parameter list distinguishes between three types of parameters:
1. **Declaring Parameters**: Indicated by the `var` or `final` modifier (e.g., `final int x`). They implicitly create a corresponding instance field in the class.
2. **Initializing Parameters**: Indicated by the `this.` or `super.` prefix (e.g., `this.x` or `super.x`). They initialize an existing field or a super constructor parameter, respectively.
3. **Regular Parameters**: Declared without modifiers (e.g., `int y`). They do not become fields and are only available during initialization (e.g., in field initializers or the `this :` initializer list in the class body).

```dart
// `x` is a field and a parameter because it has the keyword `final`. In particular, we can use the name `x` in the initializer list in the in-body part of the primary constructor. 'y' is a only parameter because it has neither of the keywords `final` or `var`, but `y` is passed to the super constructor via the `this :` initializer list.
class C(final int x, int y) extends Base {
  this : super(y);
}
```

Declaring parameters and initializing parameters are two ways of achieving the same goal: declaring a class with instance fields which are set in the constructor. Regular parameters are different in that their values are not automatically routed to an instance field.

### 2.3 Constant Primary Constructors
To make a primary constructor `const`, place the `const` keyword before the class/type name in the declaration header:

```dart
class const Point(final int x, final int y);
extension type const Ext(int x);
enum const MyEnum(final int x) {
  entry(1);
}
```

### 2.4 Extension Types
Extension types **must** use primary constructors.
- The single parameter in the header is the representation field.
- The representation variable cannot use the `var` modifier (using `var` triggers the `representation_field_modifier` error).
- The representation variable can optionally use the `final` modifier. If `final` is not present then it is inferred; that is, the parameter is declaring whether or not it's explicitly `final`.

### 2.5 Empty Body Semicolon Shorthand (`;`)
When a class, mixin class, mixin, extension or extension type has an empty body, the `{}` braces can be replaced by a semicolon (`;`):

```dart
class C(int x);
mixin class MC;
extension type ET(int x);
mixin M;
extension Ext on C;
```

### 2.6 The In-Body Part of a Primary Constructor (`this ...`)
If a primary constructor requires assertions or custom field initializations, they can be declared in the body using the `this :` syntax:

```dart
class Point(var int x, var int y) {
  // Initializer list in class body
  this : assert(x >= 0), y = y * 2;
}
```

You can also write a constructor body with this syntax (`this {...}`).

### 2.7 Abbreviated Concise Constructor Syntax
For constructors declared within the class body, the class name can be omitted and replaced with the `new` or `factory` keywords:

| Traditional Syntax | Abbreviated Concise Syntax |
| :--- | :--- |
| `MyClass() {}` | `new() {}` |
| `MyClass.name() {}` | `new name() {}` |
| `const MyClass();` | `const new();` |
| `const MyClass.name();` | `const new name();` |
| `factory MyClass() => ...` | `factory() => ...` |
| `factory MyClass.name() => ...` | `factory name() => ...` |

---

## 3. Semantics & Scoping Rules

### 3.1 Primary Initializer Scope
When a primary constructor is declared, its formal parameters are introduced into the **Primary Initializer Scope**. This scope is the current scope for non-late field initializers in the class body and the primary constructor's initializer list (after `this :`).
This allows non-late fields to reference constructor parameters directly during declaration:
  ```dart
  class DeltaPoint(final int x, int delta) {
    // 'x' and 'delta' are in scope here
    final int y = x + delta;
  }

From maranix/skills, MIT.

More from maranix/skills