From d46869e7b66acb6ed9ad5c845e233d32ac35faa0 Mon Sep 17 00:00:00 2001 From: snapsl <32878439+snapsl@users.noreply.github.com> Date: Sat, 1 Mar 2025 15:37:09 +0100 Subject: [PATCH 1/5] add migration guide --- packages/freezed/README.md | 5 ++ packages/freezed/migration_guide.md | 96 +++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 packages/freezed/migration_guide.md diff --git a/packages/freezed/README.md b/packages/freezed/README.md index 88a4cd2a..d912eaeb 100644 --- a/packages/freezed/README.md +++ b/packages/freezed/README.md @@ -59,6 +59,7 @@ to focus on the definition of your model. - [Configurations](#configurations) - [Changing the behavior for a specific model](#changing-the-behavior-for-a-specific-model) - [Changing the behavior for the entire project](#changing-the-behavior-for-the-entire-project) +- [Migration](#migration) - [Utilities](#utilities) - [IDE Extensions](#ide-extensions) - [Freezed extension for VSCode](#freezed-extension-for-vscode) @@ -1247,6 +1248,10 @@ targets: when_or_null: false ``` +# Migration + +Use the [changelog](CHANGELOG.md) and our [migration guide](migration_guide.md). + # Utilities ## IDE Extensions diff --git a/packages/freezed/migration_guide.md b/packages/freezed/migration_guide.md new file mode 100644 index 00000000..a6cfaf61 --- /dev/null +++ b/packages/freezed/migration_guide.md @@ -0,0 +1,96 @@ +# Migration Guide + +## Migrate from v2 to v3 + +### Require keyword (`sealed` / `abstract`) + +Classes using the factory constructor now require a keyword `sealed` / `abstract`. + +```diff +@freezed +-class Person with _$Person { ++abstract class Person with _$Person { + const factory Person({ + required String firstName, + required String lastName, + required int age, + }) = _Person; + + factory Person.fromJson(Map json) + => _$PersonFromJson(json); +} +``` + +```diff +@freezed +-class Model with _$Model { ++sealed class Model with _$Model { + factory Model.first(String a) = First; + factory Model.second(int b, bool c) = Second; +} +``` + +### Pattern matching + +Freezed no longer generates `.map `/`.when` extensions and their derivatives for freezed classes used for pattern matching. Instead, use Dart's built-in pattern matching syntax. + +```diff +final model = Model.first('42'); + +-final res = model.map( +- first: (String a) => 'first $a', +- second: (int b, bool c) => 'second $b $c', +-); ++final res = switch (model) { ++ First(:final a) => 'first $a', ++ Second(:final b, :final c) => 'second $b $c', ++}; + +``` + + +### Classic classes (new) + +Instead of primary constructors, you can write normal Dart classes. + +In this scenario, write a typical constructor + fields combo as you normally would: + +```dart +import 'package:freezed_annotation/freezed_annotation.dart'; + +// required: associates our `main.dart` with the code generated by Freezed +part 'main.freezed.dart'; +// optional: Since our Person class is serializable, we must add this line. +// But if Person was not serializable, we could skip it. +part 'main.g.dart'; + +@freezed +@JsonSerializable() // needed for class serialization +class Person with _$Person { + const Person({ + required this.firstName, + required this.lastName, + required this.age, + }); + + final String firstName; + final String lastName; + final int age; + + factory Person.fromJson(Map json) + => _$PersonFromJson(json); + + Map toJson() => _$PersonToJson(this); +} +``` + +In this scenario, Freezed will generate `copyWith`/`toString`/`==`/`hashCode`, +but won't do anything related to JSON encoding (hence why you need to manually add `@JsonSerializable`). + +This syntax has the benefit of enabling advanced constructor logic, such as +inheritance or non-constant default values. + + +### Advanced Topics + + \ No newline at end of file From ae0d7df531ef1df0e7e1557c06ba905c7a235a43 Mon Sep 17 00:00:00 2001 From: snapsl <32878439+snapsl@users.noreply.github.com> Date: Sat, 1 Mar 2025 15:52:53 +0100 Subject: [PATCH 2/5] add link --- packages/freezed/migration_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/freezed/migration_guide.md b/packages/freezed/migration_guide.md index a6cfaf61..154822f6 100644 --- a/packages/freezed/migration_guide.md +++ b/packages/freezed/migration_guide.md @@ -32,7 +32,7 @@ Classes using the factory constructor now require a keyword `sealed` / `abstract ### Pattern matching -Freezed no longer generates `.map `/`.when` extensions and their derivatives for freezed classes used for pattern matching. Instead, use Dart's built-in pattern matching syntax. +Freezed no longer generates `.map `/`.when` extensions and their derivatives for freezed classes used for pattern matching. Instead, use Dart's built-in [pattern matching](https://dart.dev/language/patterns#matching) syntax. ```diff final model = Model.first('42'); From f3da0f5c5b05e35b635453887effe8d305540698 Mon Sep 17 00:00:00 2001 From: snapsl <32878439+snapsl@users.noreply.github.com> Date: Sun, 2 Mar 2025 10:20:49 +0100 Subject: [PATCH 3/5] remove todo --- packages/freezed/migration_guide.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/packages/freezed/migration_guide.md b/packages/freezed/migration_guide.md index 154822f6..491b1c67 100644 --- a/packages/freezed/migration_guide.md +++ b/packages/freezed/migration_guide.md @@ -32,7 +32,7 @@ Classes using the factory constructor now require a keyword `sealed` / `abstract ### Pattern matching -Freezed no longer generates `.map `/`.when` extensions and their derivatives for freezed classes used for pattern matching. Instead, use Dart's built-in [pattern matching](https://dart.dev/language/patterns#matching) syntax. +Freezed no longer generates `.map`/`.when` extensions and their derivatives for freezed classes used for pattern matching. Instead, use Dart's built-in [pattern matching](https://dart.dev/language/patterns#matching) syntax. ```diff final model = Model.first('42'); @@ -89,8 +89,3 @@ but won't do anything related to JSON encoding (hence why you need to manually a This syntax has the benefit of enabling advanced constructor logic, such as inheritance or non-constant default values. - - -### Advanced Topics - - \ No newline at end of file From c260f6828764cf7bc9677a1207a4af2b60412a6c Mon Sep 17 00:00:00 2001 From: Remi Rousselet Date: Sun, 2 Mar 2025 13:34:24 +0100 Subject: [PATCH 4/5] Move migration --- packages/freezed/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/freezed/README.md b/packages/freezed/README.md index d912eaeb..3597bb2d 100644 --- a/packages/freezed/README.md +++ b/packages/freezed/README.md @@ -8,6 +8,10 @@ Welcome to [Freezed], yet another code generator for data classes, tagged unions, nested classes and cloning. +# Migration to 3.0.0 + +To migrate from 2.0.0 to 3.0.0, see [changelog](CHANGELOG.md#300---2025-02-25) and our [migration guide](migration_guide.md). + # Motivation Dart is awesome, but defining a "model" can be tedious. You have to: @@ -23,12 +27,13 @@ and affect the readability of your model significantly. Freezed tries to fix that by implementing most of this for you, allowing you to focus on the definition of your model. -| Before | After | -| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| Before | After | +| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | ![before](https://raw.githubusercontent.com/rrousselGit/freezed/refs/heads/master/resources/before.png) | ![before](https://raw.githubusercontent.com/rrousselGit/freezed/master/resources/after.png) | # Index +- [Migration to 3.0.0](#migration-to-300) - [Motivation](#motivation) - [Index](#index) - [How to use](#how-to-use) @@ -59,7 +64,6 @@ to focus on the definition of your model. - [Configurations](#configurations) - [Changing the behavior for a specific model](#changing-the-behavior-for-a-specific-model) - [Changing the behavior for the entire project](#changing-the-behavior-for-the-entire-project) -- [Migration](#migration) - [Utilities](#utilities) - [IDE Extensions](#ide-extensions) - [Freezed extension for VSCode](#freezed-extension-for-vscode) @@ -1248,10 +1252,6 @@ targets: when_or_null: false ``` -# Migration - -Use the [changelog](CHANGELOG.md) and our [migration guide](migration_guide.md). - # Utilities ## IDE Extensions From 82b26caf62130be8cead1956545120a9acfd1058 Mon Sep 17 00:00:00 2001 From: Remi Rousselet Date: Sun, 2 Mar 2025 13:35:11 +0100 Subject: [PATCH 5/5] Cleanup --- packages/freezed/migration_guide.md | 46 +---------------------------- 1 file changed, 1 insertion(+), 45 deletions(-) diff --git a/packages/freezed/migration_guide.md b/packages/freezed/migration_guide.md index 491b1c67..c3bb2213 100644 --- a/packages/freezed/migration_guide.md +++ b/packages/freezed/migration_guide.md @@ -1,8 +1,6 @@ -# Migration Guide - ## Migrate from v2 to v3 -### Require keyword (`sealed` / `abstract`) +### Require keyword (`sealed` / `abstract`) Classes using the factory constructor now require a keyword `sealed` / `abstract`. @@ -47,45 +45,3 @@ final model = Model.first('42'); +}; ``` - - -### Classic classes (new) - -Instead of primary constructors, you can write normal Dart classes. - -In this scenario, write a typical constructor + fields combo as you normally would: - -```dart -import 'package:freezed_annotation/freezed_annotation.dart'; - -// required: associates our `main.dart` with the code generated by Freezed -part 'main.freezed.dart'; -// optional: Since our Person class is serializable, we must add this line. -// But if Person was not serializable, we could skip it. -part 'main.g.dart'; - -@freezed -@JsonSerializable() // needed for class serialization -class Person with _$Person { - const Person({ - required this.firstName, - required this.lastName, - required this.age, - }); - - final String firstName; - final String lastName; - final int age; - - factory Person.fromJson(Map json) - => _$PersonFromJson(json); - - Map toJson() => _$PersonToJson(this); -} -``` - -In this scenario, Freezed will generate `copyWith`/`toString`/`==`/`hashCode`, -but won't do anything related to JSON encoding (hence why you need to manually add `@JsonSerializable`). - -This syntax has the benefit of enabling advanced constructor logic, such as -inheritance or non-constant default values.