Why I made jalali_date
The history of jalali_date, a Persian calendar package for Dart: the first version in 2018, a conversion bug I had to own, and the rewrite in 2026.
In 2018 I was writing Dart and needed Jalali dates. That is most of the story.
The Jalali calendar, also called Persian, Shamsi or Solar Hijri, is the official calendar of Iran and Afghanistan. If you build anything for people in Iran, every date on the screen is in it. The week starts on Saturday and Friday is the day off. The year begins at Nowruz, around 21 March. I was working in Tehran at the time, and showing a Gregorian date and hoping nobody minded was not an option.
So I wrote a small package. The repository, Dart-Persian-Date, went up on 10 July 2018. Version 0.0.1 did one thing: it took a Gregorian date and gave back a Jalali one. The next day I added the time to toString. I did not plan beyond that.
In April 2019 I fixed a few things dart pub complained about, and in May I added a homepage URL. By then it was on pub.dev as jalali_date. In July 2020 I added options to show or hide the hour, minute and second, and fixed the length of minutes and seconds in the output.
Then nothing for about six years. I moved to Germany at some point in that time, and the package sat untouched.
Coming back
This month I opened it again. The first job was housekeeping: move to Dart 3 and null safety, and drop the Flutter dependency so it is pure Dart and runs anywhere Dart runs.
Then I found the real problem. The Gregorian-to-Jalali conversion I wrote in 2018 was wrong for some years. Century years, and years that fall across a Jalali leap cycle. That is my mistake, and it had been in the package the whole time. If you used it and a date near one of those boundaries looked off, that was the package, not you.
I did not try to patch it. I replaced the algorithm with a port of jalaali-js and stopped trying to be clever about calendar arithmetic.
That became 1.0.0. With the conversion fixed it made sense to add the other direction, Jalali to Gregorian, plus validation that throws an ArgumentError on a bad date, leap years and month lengths, Persian month and weekday names, a format(pattern) method and a padded toString. 1.0.0 has breaking changes. They are listed on the migration page.
1.1.0 came after that: date arithmetic, comparisons, weeks that start on Saturday, parsing with either Persian or Arabic-Indic digits, output in Persian digits, DateTime.toPersianDate(), JSON, Dari month names for Afghanistan, and ranges and bounds so you can build a date picker on top of it.
I also merged a pull request from AliRn76 that zero-pads the time parts and respects the show flags. Thank you for that.
Where it stands
The docs are at nodets.com/jalali. The source is on GitHub under Apache-2.0, and the package is on pub.dev.
If you use it and a date comes out wrong, open an issue. I have been wrong about this once already.