meyerweb
commented
3 years ago I’ve been working on porting the Temporal documentation to MDN, which means I’ve been through the documentation several times now, and I didn’t once find the plural field values in Temporal.Duration bothersome. In fact, had they been singular, I’m pretty sure I’d have asked why that choice was made, because it would have seemed odd.
In part, the difference of singular in Temporal.PlainDateTime and plural in durations made sense to me because when using PlainDateTime, you’re working with a single exact moment in time. With Duration, you’re supplying or receiving some number of units of time, which will usually be in multiples—2 years, 5 days; 13 months; 17 minutes; or what have you. Even in the case where the number is singular, like one year, it would follow the human pattern “How many years is this?” “It’s one year.”
More to the point, whenever I’ve worked with APIs where a single value is supplied or returned, and that value can be multiple in the sense of more (or less) than one, the field names are usually plural. But, fearing a selective memory, I went and looked at some existing time APIs, and they all seem to use plural labels for durations. In moment.js:
moment.duration({
seconds: 2,
minutes: 2,
hours: 2,
days: 2,
weeks: 2,
months: '2',
years: '2'
});constexpr absl::Duration ten_ns = absl::Nanoseconds(10);
constexpr absl::Duration min = absl::Minutes(1);
constexpr absl::Duration hour = absl::Hours(1);
absl::Duration dur = 60 * min; // dur == hour
absl::Duration half_sec = absl::Milliseconds(500);
absl::Duration quarter_sec = 0.25 * absl::Seconds(1);| Name | Type |
|---|---|
obj.years |
number |
obj.quarters |
number |
obj.months |
number |
obj.weeks |
number |
obj.days |
number |
obj.hours |
number |
obj.minutes |
number |
obj.seconds |
number |
obj.milliseconds |
number |
For that matter in C++:
| Type | Definition |
|---|---|
std::chrono::nanoseconds |
duration</*signed integer type of at least 64 bits*/, std::nano> |
std::chrono::microseconds |
duration</*signed integer type of at least 55 bits*/, std::micro> |
std::chrono::milliseconds |
duration</*signed integer type of at least 45 bits*/, std::milli> |
std::chrono::seconds |
duration</*signed integer type of at least 35 bits*/> |
std::chrono::minutes |
duration</*signed integer type of at least 29 bits*/, std::ratio<60>> |
std::chrono::hours |
duration</*signed integer type of at least 23 bits*/, std::ratio<3600>> |
std::chrono::days |
duration</*signed integer type of at least 25 bits*/, std::ratio<86400>> |
std::chrono::weeks |
duration</*signed integer type of at least 22 bits*/, std::ratio<604800>> |
std::chrono::months) |
duration</*signed integer type of at least 20 bits*/, std::ratio<2629746>> |
std::chrono::years |
duration</*signed integer type of at least 17 bits*/, std::ratio<31556952> |
…and in Rust:
#![feature(duration_constants)]
use std::time::Duration;
assert_eq!(Duration::SECOND, Duration::from_secs(1));This all suggests that if Temporal uses singular labels in durations, developers will be more likely to typo the labels when trying to learn and use Temporal, which feels like unnecessary friction. It could also make more difficult the lives of developers who have to go back and forth between Temporal and other time-centric APIs as they work in legacy code versus new code.
FrankYFTang
littledan
justingrant
In Intl.DateTimeFormat, Intl.NumberFormat, Intl.DisplayNames, and even Temporal.DateTime, the date/time fields are singular: "second", "minute", "hour", "day", etc.
However, in Temporal.Duration, they are plural: "seconds", "minutes", etc.
I understand the reasoning, that it sounds more natural in English to say "seconds: 30" instead of "second: 30", but there are some downsides to the inconsistent naming:
Thoughts on making the Temporal.Duration field names singular?