Add `DateTime.fromSecondsSinceEpoch` and `int get secondsSinceEpoch`

[KKimj]

Proposal to Add Features to the DateTime Class

• DateTime.fromSecondsSinceEpoch:
  A constructor that creates a DateTime instance from seconds since the epoch.

• int get secondsSinceEpoch:
  A getter that retrieves the number of seconds since the epoch from a DateTime instance.

Using dateTime.millisecondsSinceEpoch ~/ 1000 for conversions is often verbose.

Adding these features would simplify the code and enhance the dev-experience.

It would be useful when only seconds are needed from DateTime, ultimately reducing overhead from unnecessary operations with milliseconds.

AS-IS

final DateTime now = DateTime.now(); 
// Verbose, often takes up 2 lines due to 80-column formatting.
final int seconds = now.millisecondsSinceEpoch ~/ 1000; 

TO-BE

final DateTime now = DateTime.now();
final int seconds = now.secondsSinceEpoch;

Thanks!
I’d love to hear your thoughts—feel free to drop a comment!

[dart-github-bot]

Summary: User proposes adding DateTime.fromSecondsSinceEpoch constructor and secondsSinceEpoch getter to simplify working with seconds since the epoch, avoiding verbose millisecond calculations.

[lrhn]

Adding constructors should be non-breaking, but adding a getter to an interface is breaking.

I don't think the benefit would be worth that.
(Which is why we need interface default methods.)

[julemand101]

but adding a getter to an interface is breaking.

I guess it could be argued that this field could be added using extension like done with:
https://api.dart.dev/dart-core/DateTimeCopyWith.html

[KKimj]

I created this PR to propose a concept for the secondsSinceEpoch using an extension.

I welcome your thoughts and feedback!

[lrhn]

Not seeing the big need for this. It is just
* Duration.millisecondsPerSecond and ~/ Duration.millisecondsPerSecond, and you can make that shorter by just using 1000.

If we do decide to add something, why just seconds?
We can have minutesSinceEpoch, hoursSinceEpoch and daysSinceEpoch too (although the last one runs into daylight saving issues). Adding just one feels arbitrary.

Not sure I want all of them.

[KKimj]

Thank you for your comments. I agree with your opinions and concerns. Here’s my perspective:

1. Seconds Since Epoch is a De Facto Standard

Unix time (= epoch time) is defined as The number of Seconds that have elapsed since the epoch and is widely used across various systems and APIs. Here are some examples:

• APIs/Protocols:

  • Google Timestamp: Explicitly uses seconds. Documentation
  • JWT exp: Mandates expiration time in seconds RFC 7519).
  • Redis TIME: Returns time in seconds and microseconds. Documentation

• Languages (Standard Libraries):

  • Go: time.Time.Unix() method returns seconds. Documentation
  • Python: datetime.timestamp() returns seconds as a float. Documentation
  • Java: Instant.getEpochSecond() retrieves seconds directly. Documentation

• Systems:

  • POSIX time: Uses time_t to represent time in seconds since the epoch. Documentation
  • Unix CLI: Commands like date +%s output time as seconds. Documentation

---

2. Why Focus on Seconds (and Not Minutes/Hours)?

• Common Practice: No major systems, APIs, or protocols use minutes/hours as epoch-based units.
• Lack of Demand: Real-world use cases for minutesSinceEpoch or hoursSinceEpoch are nonexistent. Adding them would complicate the API without practical value.

---

3. Conclusion

The absence of get secondsSinceEpoch forces developers to use verbose, inconsistent conversions:

// Inconsistent, repetitive patterns
final int seconds1 = now.millisecondsSinceEpoch ~/ 1000;
final int seconds2 = now.millisecondsSinceEpoch ~/ Duration.millisecondsPerSecond;
final int seconds3 = (now.millisecondsSinceEpoch / 1000).floor();
final int seconds4 = (now.millisecondsSinceEpoch ~/ 1000).toInt();
// Seconds to Milliseconds is vise versa

This enhancement will:

• Reducing Cognitive Overhead for developers: Eliminate manual conversions.
• Enhancing Code Safety: Fewer manual conversions.
• Improving Interoperability: Align with ecosystems, as well as other languages and libraries.

Thank you for considering this proposal! I look forward to your thoughts. 🚀