Create the `dart:time` API for processing dates with functional programming

[Ing-Brayan-Martinez]

Greetings, the purpose of this proposal is to propose an API to perform mathematical operations on dates, which the DateTime type cannot resolve by itself. Also providing some additional utilities for working with dates, this API takes inspiration from the java.time API which is optimized to work with functional programming

We must clarify that some classes will not be implementable because the DateTime type exists in the dart:core package and the dart:time api classes must avoid cyclic dependency to avoid this it is necessary to implement the map() function To avoid the problem of cyclical dependencies, an example would look like this:

void main() {
  // dart:core
  DateTime date = DateTime.of(2024, 06, 12);

 // dart:time
 Instant result = date.map((value) => Instant.ofEpochSecond(value))
}

An implementable class would be Duration which would look like this

void main() {
  DateTime initialDate = DateTime.of(2024, 06, 12);

  DateTime finalDate = initialDate.plus(Period.ofDays(5));

  int thirty = Duration.between(initialTime, finalTime).getSeconds();
}

An implementable class would be Period which would look like this

void main() {
  DateTime initialDate = DateTime.of(2024, 06, 12);

  DateTime finalDate = initialDate.plus(Period.ofDays(5));

  int five = Period.between(initialDate, finalDate).getDays();
}

Another important implementation is DateFormat to represent a date in String

void main() {
  String date = DateTime.of(2024, 06, 12)
    .map((value) => DateFormat.ofEpochSecond(value))
    .format('YYmmdd');
}

Another important implementation is DateConvert to convert dates into other forms of time e.g.

void main() {
  DayOfWeek sunday = DateTime.parse("2016-06-12")
    .map((value) => DateConvert.ofEpochSecond(value))
    .getDayOfWeek();
}

As you can see the possibilities will be very positive for the developer community, some java.time examples to inspire you

I was investigating if there is a library for this and I only found dart_date but it does not comply with the form of functional programming

[dart-github-bot]

Labels: area-language, type-enhancement Summary: This issue proposes a new dart:time API for functional date manipulation, inspired by Java's java.time API. The API would include classes like Duration, Period, DateFormat, and DateConvert, enabling operations like adding periods, formatting dates, and converting between date representations.

[clragon]

Could you explain how this functionality is not provided by existing mechanisms?

void main() {
  DateTime initialDate = DateTime.of(2024, 06, 12);

  DateTime finalDate = initialDate.plus(Period.ofDays(5));

  int thirty = Duration.between(initialTime, finalTime).getSeconds();
}

can already be written today, in dart, with:

DateTime initialDate = DateTime.of(2024, 06, 12);
DateTime finalDate = initialDate.add(Duration(days: 5));
int thirty = initialDate.difference(finalDate).inSeconds;

The DateFormat class in the first party maintained intl allows you to correctly format your DateTime into various locals and various formats and parse them as well.

Adding a map function to a DateTime object sounds like a viable idea, but generally, dart doesnt have syntax like this. If you require a map function for your DateTime objects, or perhaps all your objects, you can create an Extension that does this in just three lines of code. I dont think it would be necessary for the language team to specifically add something like that.

If you'd like inspiration, you can take a look at a package like kotlin_scope_function that adds many chain functions from kotlin, that are also very trivial to implement and allow you to arbitrarily map objects to other values.

I think its important to recognize that dart has solutions for many problems already, and they are generally solved much better than in Java, where a lot of code is burdened by backwards-compatibility and verbosity as a core principle of the language.

[Ing-Brayan-Martinez]

@clragon You are right, I have no doubt that the Dart language currently cannot solve these problems. My main objective is to support functional programming, take that into account.

If we pose the problem of calculating the difference of days in two dates, we can solve it in 2 ways depending on the programming paradigm we are using.

If we use traditional object-oriented programming the solution would look like this

void main() {
  DateTime initialDate = DateTime(2024, 06, 12);
  DateTime finalDate = initialDate.add(Duration(days: 5));

  int thirty = initialDate.difference(finalDate).inSeconds;
}

If we use functional programming the solution would look like this

void main() {
  DateTime initialDate = DateTime.of(2024, 06, 12);

  DateTime finalDate = initialDate.plus(Period.ofDays(5));

  int thirty = Duration.between(initialTime, finalTime).getSeconds();
}

This form is necessary so that the date calculations can comply with the principle of composition of functions. This in the Dart language is done thanks to the Sream to see it I am going to do the following example

void main() {
  Stream<DateTime> initialDate = Stream.value( DateTime.of(2024, 06, 12) );

  Stream<DateTime> finalDate = Stream.value( DateTime.of(2024, 06, 12).plus(Period.ofDays(5)) );

  Optional<int> opt = Stream.zip([initialDate, finalDate])
     .map((tuple) => Duration.between(tuple.t1, tuple.t2).getSeconds())
    .first

  int thirty = opt.get();
}

As you can see, the dates API is combined with the Streams, which is why I am making this proposal to achieve algorithms that work in this way.

My proposal is not intended to convert Dart into Java only to assume functional programming when you talk about vervosity it is strange because functional programming is a solution for that problem

Then I check the Date Format class to see if it needs any adjustments, I will have to deal with it in a separate problem

[mraleph]

We are not planning to do that.

Developers are free to create whatever packages they see fit though.