Using Dart Const Constructors for Immutable Compile‑Time Data Classes

Desired Outcome

By the end of this guide you will have a Dart data class that:

• Is fully immutable and thread‑safe.
• Can be instantiated with const for compile‑time constant propagation.
• Is canonicalized—identical const instances share the same memory reference.
• Shows measurable memory and allocation savings compared to a mutable counterpart.

Prerequisites

• Flutter SDK 3.0+ or Dart SDK 3.0+ installed.
• Basic understanding of Dart classes, final fields, and the const keyword.
• Access to a terminal with dart command available.

Procedure

1. Define a const‑friendly class

   All fields must be final or const. No late or mutable types are allowed.

   class Point {
     final double x;
     final double y;
   
     const Point(this.x, this.y);
   }
   

2. Instantiate with const

   Use the const keyword at the call site to create a compile‑time constant.

   const origin = Point(0.0, 0.0);
   const pointA = Point(1.0, 2.0);
   

3. Canonicalization test

   Declare the same values twice and verify that they reference the same object.

   const pointB = Point(1.0, 2.0);
   print(identical(pointA, pointB)); // true
   

4. Enforce compile‑time safety

   Attempt to add a non‑final field; the analyzer will reject the code.

   // ❌ Error: Field 'z' must be final or const.
   class BadPoint {
     int z; // non‑final
     const BadPoint(this.z);
   }
   

5. Benchmark allocation cost

   Write a simple loop that creates many instances of the const class and a mutable version. Measure allocation time with dart run --enable-asserts and dart run --release flags.

   void main() {
     const point = Point(1.0, 2.0);
     for (var i = 0; i < 1_000_000; i++) {
       // const instances are reused; no allocation happens.
       final _ = point;
     }
   }
   

6. Compile‑time constant usage

   Use a const instance as a static final field or as a default parameter.

   class Circle {
     final Point center;
     final double radius;
     const Circle(this.center, this.radius);
   }
   
   class ShapeDefaults {
     static const Circle unitCircle = Circle(Point(0.0, 0.0), 1.0);
   }
   

Expected Checks

• Analyzer: Run dart analyze in the project root. No errors should appear for the const class.
• Canonicalization: identical(a, b) returns true for two separately declared const instances with identical values.
• Binary size: Compile with dart compile exe bin/main.dart and compare main.exe size to a non‑const version. Expect a measurable reduction.
• Runtime safety: Attempting to modify a const field (e.g., point.x = 5;) results in a runtime error.

Recovery Options

• If the analyzer reports a non‑final field, convert it to final or remove it from the const constructor.
• For fields that depend on runtime data, replace the const constructor with a regular one and provide a factory that returns a const instance when possible.
• When canonicalization is not desired (e.g., you need distinct objects), omit the const keyword at instantiation time.

Performance Comparison

Below is a simplified table showing the expected differences between const and mutable versions when creating 1,000,000 instances:

Version	Allocation Time	Binary Size
Mutable Point	~150 ms	~1.2 MB
Const Point	~5 ms (no allocations)	~1.0 MB

These numbers are illustrative; actual results depend on the environment and compiler optimizations.

Common Pitfalls

• Using late or dynamic fields in a const class – compile‑time error.
• Calling a non‑const method from within a const constructor – compile‑time error.
• Referencing this before all fields are initialized in the initializer list – compile‑time error.
• Mutating a const instance at runtime – runtime exception.

Always run dart analyze after modifications to catch these issues early.