In Dart, when should a payment-method hierarchy be `sealed` rather than `final`, and what does each cost when you later add a method?

## Two ways to close a hierarchy Suppose a payments package exports a `PaymentMethod` type with three variants: `Card`, `Wallet` and `BankTransfer`. The package does not want other packages inventing new payment methods, because the charging code only knows these three. Both `sealed` and `final` stop other libraries from extending or implementing `PaymentMethod`. They differ in what they promise to *users* and what they cost the *maintainer*. ## What `sealed` promises ```dart sealed class PaymentMethod {} final class Card extends PaymentMethod { Card(this.last4); final String last4; } final class Wallet extends PaymentMethod { Wallet(this.provider); final String provider; } final class BankTransfer extends PaymentMethod { BankTransfer(this.iban); final String iban; } ``` - `PaymentMethod` is **implicitly abstract**: nobody can create a bare `PaymentMethod()`. - Every **direct subtype must be in the same library** (the same file or one of its `part` files). - Because the set of direct subtypes is known, the compiler accepts a switch with one case per subtype as **exhaustive**, with no default branch. How that checking works belongs to the pattern-matching topic. dart.dev compares this to an enum: the subtypes behave like a fixed list of values that user code can rely on covering completely. ## What `final` promises ```dart final class PaymentMethod { PaymentMethod(this.label); final String label; } ``` - Other libraries can **construct** it but cannot extend, implement, mix it in or use it in an `on` clause. - There is **no exhaustiveness**: even if user code tests for every known subtype, the compiler requires a default case. - Subclasses in your own library must be `base`, `final` or `sealed` (the restriction is transitive). ## The cost of adding a variant later | Change in v2 | `sealed` hierarchy | `final` hierarchy | |---|---|---| | Add `Voucher` subtype | **breaking**: every exhaustive user switch stops compiling | non-breaking: user default cases handle it | | Add a method to the supertype | non-breaking for users (they cannot subtype it) | non-breaking for users | | Users create instances of the supertype itself | impossible | allowed | | Users get compile errors pointing at unhandled variants | yes | no | The dart.dev maintainer guide frames the breaking change positively: those errors are useful, because they point users at every place that must now handle `Voucher`. But it is still a breaking change, and a package that expects to add variants often should prefer `final`. ## A decision checklist 1. **Must users create instances of the supertype itself?** Then it cannot be `sealed`, since sealed types are implicitly abstract. 2. **Does the type have subtypes in your library?** If not, `sealed` gives no benefit. 3. **Do users need to handle each variant separately and be told when a new one appears?** Choose `sealed`, and treat new variants as major releases. 4. **Do you want to add variants freely in minor releases?** Choose `final` for the supertype, and accept that users write default cases. ## Details interviewers probe - `abstract sealed class` is a compile-time error: sealed is already abstract. - A sealed class **can declare constructors** for its subclasses to call and **factory constructors** that return a subtype, e.g. `factory PaymentMethod.card(String last4) = Card;`. - `sealed` is **not transitive**: if `Card` has no modifier, another library may extend `Card`. That does not break exhaustiveness over `PaymentMethod`, because such a subclass is still a `Card`. Mark the variants `final` if you want them closed too. - The SDK uses the same trade-off: `num` is `sealed` in `dart:core`, with `int` and `double` as its direct subtypes, and `dart:io`'s `FileSystemEvent` became `sealed` in Dart 3.1 — itself listed as a breaking change.