Proposal for Contribution

[LennartCode]

After thorough evaluation, I decided to use tempo for a project of mine. As this project also requires types for exact time intervals between specific Instants, weeks and months in a specific year and unsigned (always positive) variants of Period and Timespan I thought about contributing them here. Would you be interested in such a contribution?

I am open for feedback and suggestions!

[pcekm]

Thanks for reaching out.

I had written a detailed response, but I strongly suspect that what you're asking for is not what you actually need. So before we get into the specifics of what you're proposing, please tell me what you're trying to accomplish.

[LennartCode]

I am currently implementing a package providing the types from JSCalendar (RFC 8984), the successor of iCalendar. As I want the types to be expressive and stay close to the spec, things like an unsigned duration are helpful to catch programming errors with the type system. For example, subtracting durations leads to a signed duration (which may or may not be negative), so assigning it to a property that requires an unsigned duration can throw an exception. Timespan and Period support both positive and negative durations and thus cannot catch these types of errors at compile time.

The library is used in a calendar application, which supports multiple views. To display a certain week, month or year it is useful to have a type that models this time frame (like the 12th week of 2025; July 2025). These types can then have auxiliary methods that test if a date is contained in the time frame, return the first and last date, indicate if the year is a leap year and so on.

So far, I did not use intervals between two Instants and will probably pivot to modelling such intervals using a start Instant and Timespan. An interval type could be interesting though, should the need for interval arithmetic with open intervals arise.

In case, you thought that I wanted to model a month using such an interval, no worries, I get why this is a terrible idea (time zones, daylight savings time...) :D

Currently, I implement the features above using extension types and classes that wrap tempo types. This works, but in case you are interested, I would like to contribute them for others to use as well. Other packages like date_time have support for weeks for example but are lacking in other regards.

If you were interested, I would also suggest to introduce new constructors that use the IsoWeek8601Week or Year types instead of int where appropriate.

[LennartCode]

Hi :)
is there an update on this? I am happy to provide further information, if needed.

[pcekm]

Sorry, I've been spending some time away from the keyboard.

I think I understand now. In the context of that RFC, it seems like you're trying to do reasonable things. The question is how many of those things fit within Tempo's scope. Which is "the date time library I wish Dart had shipped with." (I should probably put that at the top of the README.) So it's meant to be broadly applicable—a basis for building more complicated things. Much of what you're proposing is probably outside of that scope. But that doesn't mean we can't add some features.

I see your proposal as two main areas: unsigned time periods, and interval types.

Since RFC 8984 specifies an unsigned duration, it makes sense to have one in your package. But it's fairly application specific and unusual, so probably doesn't belong in Tempo. And it seems like a fairly straightforward wrapper around Timespan (although I don't know how you could get it to catch negative values at compile time).

Interval types are more broadly useful, but they're pretty rare as components of a standard date time library. Mostly I think because doing it in a broadly applicable way would be complex enough to warrant a separate package. It could also easily end up being too generic to be actually helpful.

Even the seemingly straightforward cases that you're talking about can get complicated. Particularly weeks. A week can start on Saturday, Sunday, or Monday depending on where you are, and in which year do you include the week of January 1st? ISO week numbering specifies one way, but there are other common ways as well. It's a mess I'm not sure I want to wade into.

So, to sum up: I don't think I'm open to the addition of any new types right now, but I'm definitely open to adding features that would be broadly useful, provided they're within Tempo's scope. I'm especially interested in removing rough edges and friction points—making things as easy, consistent, and obvious as possible. For example, if you're constantly having to convert to and from a type because it supports an operation you need and the original doesn't, please file a feature request.

I hope I haven't deterred you from asking for features or contributing to Tempo. And I definitely don't want to deter you from trying to change my mind. :-) I'm happy you're using Tempo, and I want you to continue to do so. Good luck with your project!