Dart Seal Type Hierarchies

Seal Type Hierarchies

1. When to use this skill

Use this skill when:

• A package declares an abstract base type whose subtypes are all defined in the same library, but the base type is not marked sealed.
• Code branches over the members of such a hierarchy with is checks or a non-exhaustive switch, so adding a subtype later fails silently at runtime instead of loudly at compile time.
• Reviewing a new type hierarchy and deciding whether it should be open to external subtyping.

When NOT to use (Abstention Guardrails)

Do NOT seal a type when:

• Subtypes span multiple libraries: sealed requires every direct subtype to be declared in the same library as the base type. If subtypes live in other files (and are not part of the same library), the code will not compile. Either move them or leave the hierarchy open.
• The type is public API and external extension is intended: Sealing a type exported from a published package is a breaking change for any downstream package that extends or implements it. Plugin interfaces, visitor bases, and extension points are meant to be open. Do not seal them to win exhaustiveness.
• The base type is concrete and instantiated: sealed implies abstract. If callers construct the base type directly, sealing it breaks them, and the fix is a larger refactor than this skill covers.
• Fewer than two subtypes: A single subtype is specialization, not an algebraic hierarchy. Exhaustiveness checking buys nothing.
• SDK constraint below 3.0.0: Class modifiers do not exist before Dart 3. Check environment.sdk in pubspec.yaml first.

2. Why sealing is the correctness move

The value is not switch syntax. It is that the compiler starts rejecting incomplete branching:

Copy code
seal the hierarchy -> exhaustiveness checking -> adding a subtype becomes
a compile error at every switch, instead of a silent fallthrough

An unsealed hierarchy with is cascades is not wrong today. It becomes wrong the moment someone adds a subtype, and nothing tells them which call sites they missed. Sealing is prophylactic: it converts a future runtime bug into a present-day compile error.

This is a different concern from preferring pattern matching for readability. Pattern matching over an unsealed hierarchy is a style choice. Sealing the hierarchy is a correctness guarantee, and the ergonomic payoff is a consequence, not the goal.

3. Detection

A type is a candidate when all of the following hold:

1. It is declared abstract and is not already sealed.
2. It has two or more direct subtypes.
3. Every direct subtype is declared in the same library as the base type.
4. Sealing it is not a breaking change: it lives under lib/src/, or is already marked final, or the package is an application rather than a published library.

Conditions 1 through 3 are decidable from the syntax tree. Condition 4 requires knowing the author's intent about the public API and is the part a human or an LLM must confirm.

This detection is not expressible as a single-file regular expression. It is a question about the package-wide type graph: you must collect every type declaration and every extends/implements/with edge before you can tell whether a hierarchy is closed.

4. Applying the change

Before

dartCopy code
abstract class Shape {}

class Circle extends Shape {
  final double radius;
  Circle(this.radius);
}

class Square extends Shape {
  final double side;
  Square(this.side);
}

double area(Shape shape) {
  if (shape is Circle) {
    return 3.14159 * shape.radius * shape.radius;
  } else if (shape is Square) {
    return shape.side * shape.side;
  }
  // Silently reached when a new subtype is added.
  throw ArgumentError('Unknown shape: $shape');
}

After

dartCopy code
sealed class Shape {}

final class Circle extends Shape {
  final double radius;
  Circle(this.radius);
}

final class Square extends Shape {
  final double side;
  Square(this.side);
}

double area(Shape shape) => switch (shape) {
  Circle(:final radius) => 3.14159 * radius * radius,
  Square(:final side) => side * side,
};

Adding class Triangle extends Shape now produces a compile error at area, naming the missing case. The throw and its unreachable-by-construction error message are gone.

Migration steps

1. Add sealed to the base type declaration.
2. Run dart analyze. Every non-exhaustive switch over the hierarchy now reports an error; every subtype declared outside the library reports one too.
3. Convert is cascades to switch expressions, removing the trailing throw/default that existed only to satisfy the return type.
4. Consider marking leaf subtypes final to prevent further extension.

5. Interaction with other skills

• dart-use-pattern-matching / dart-modern-features: apply after sealing. Rewriting an is cascade as a switch over an unsealed type is a readability change only; the same rewrite over a sealed type is checked by the compiler.
• Do not treat this skill as a reason to seal a hierarchy you do not own the evolution of.