Clarity on maximum Duration nanoseconds value

[nekevss]

Mentioned briefly during the champions call.

I was hoping to get some clarity on the max time duration for nanoseconds, specifically when creating a Duration.

Background

Currently, the maximum valid Duration for a normalized nanosecond is 9,007,199,254,740,991,999,999,999 (2^53 * 10^9 - 1). This number is both VERY large, and also not valid when provided to IsValidDuration, which, due to floating arithmetic appears to have a maximum duration value of 9,007,199,254,740,991,463,129,087 (beyond this point floating point rounds up to 2^53, below it appears to round to 2^53 - 1).

Examples

The test262 test that the below tests are based off is: Duration/prototype/round/out-of-range-when-converting-from-normalized-duration.js.

But the below example better highlights the boundary mentioned in the above background.

import { Temporal } from "@js-temporal/polyfill"

const d = new Temporal.Duration(0, 0, 0, 0, 0, 0, /* s = */ Number.MAX_SAFE_INTEGER, 0, 0, /* ns = */ 463_129_087);
let result = d.round({ largestUnit: "nanoseconds", roundingIncrement: 1})
console.log(result.toString()) // PT9007199254740990.926258176S

try {
    const e = new Temporal.Duration(0, 0, 0, 0, 0, 0, /* s = */ Number.MAX_SAFE_INTEGER, 0, 0, /* ns = */ 463_129_088);
    e.round({ largestUnit: "nanoseconds", roundingIncrement: 1})
} catch (e) {
    console.log(e) // Throws range error
}

Looking for general thoughts on the maximum size of the Duration, whether this behavior is intended or could/should be updated.

FWIW, also, the day range of Duration a duration with only day + time fields is very large as defined by IsValidDuration. (2^53 - 1) / 86,400 = 104,249,991,374 days, where the maximum epoch day range is 100,000,000 day.

[ptomato]

The behaviour is intended. Because of the float64 storage requirement, largestUnit: "nanoseconds" is just always going to be subject to precision loss if you have a long duration.

By my reading it's correct according to IsValidDuration: ℝ(𝔽(nanoseconds)) × 10⁻⁹ ≥ 2⁵³.

Whether we would want to adjust that limit — I'd prefer not, as it's already been discussed to death once 😄 But I will say that my understanding from the previous discussion was that the only actually helpful potential adjustment would be to make total nanoseconds fit in an int64, which would not be large enough to subtract the min Instant from the max Instant and therefore impossible without giving Temporal a smaller range than legacy Date. So assuming that anything between 65 and 128 bits is equally inconvenient, we picked float64 safe-integer seconds plus 10⁹−1 nanoseconds, for implementations that might want to use floats (i.e., anything in self-hosted or userspace JS.)

[nekevss]

If it's preferred to keep everything as is, then should the test262 test be updated? I'm not entirely convinced that the current test properly represents the point that it's testing vs. the above example. Because it may be possible for a nanosecond (and maybe microsecond) beyond the MAX_SAFE_INTEGER value to be a valid duration based on the above example (unless the C++ library does correctly handle the unsafe integer floating point arithmetic) and that should probably be represented in the test suite.

Also, the example above only tests the nanosecond case, not the microseconds. So we'd probably have to find the boundary for microseconds as well for testing.

[nekevss]

Just to build out the above, this came up when trying to optimize Duration away from floating points to integers in temporal_rs's implementation. While this isn't necessarily a blocker to that, it does really highlight some slightly weird behavior here caused primarily due to floating point operations due to how large the values are at the upper range.

(Also, just to note, I'm not sure I would advocate for nanoseconds to fit in the range of signed or unsigned 64 bit integer. But currently, both nanoseconds AND microseconds are above the range that could be represented by even an unsigned 64 bit integer).

Due to how large the values are on the upper range, the maximum possible duration will change depending on the unit for millisecond, microsecond, and nanosecond.

For instance, extending the above example (note I didn't actually test the extended with the polyfill, but I did test it on FireFox nightly):

import { Temporal } from "@js-temporal/polyfill"

const d = new Temporal.Duration(0, 0, 0, 0, 0, 0, /* s = */ Number.MAX_SAFE_INTEGER, 0, 0, /* ns = */ 463_129_087);
let result = d.round({ largestUnit: "nanoseconds", roundingIncrement: 1})
console.log(result.toString())

try {
    const e = new Temporal.Duration(0, 0, 0, 0, 0, 0, /* s = */ Number.MAX_SAFE_INTEGER, 0, 0, /* ns = */ 463_129_088);
    e.round({ largestUnit: "nanoseconds", roundingIncrement: 1})
} catch (e) {
    console.log(e) // Throws range error
}

// Range Error with largestUnit of microseconds.
// Resulting duration should be 9_007_199_254_740_991_463_129 in the microseconds field
const e = new Temporal.Duration(0, 0, 0, 0, 0, 0, /* s = */ Number.MAX_SAFE_INTEGER, 0, 0, /* ns = */ 463_129_088);
let result = e.round({ largestUnit: "microseconds", roundingIncrement: 1}) // Use microseconds instead of nanoseconds
console.log(result.toString())

// Let's test the maximum range, first failure for microseconds.
try {
    const e = new Temporal.Duration(0, 0, 0, 0, 0, 0, /* s = */ Number.MAX_SAFE_INTEGER, 0, /* mis = */ 475_712, 0);
    e.round({ largestUnit: "microseconds", roundingIncrement: 1})
} catch (e) {
    console.log(e) // Throws range error
}

/// But the first RangeError for microseconds is a valid duration for milliseconds
const e = new Temporal.Duration(0, 0, 0, 0, 0, 0, /* s = */ Number.MAX_SAFE_INTEGER, 0, /* mis = */ 475_712, 0);
let result = e.round({ largestUnit: "milliseconds", roundingIncrement: 1})

A duration that is out of range with a largest unit of nanoseconds is now a valid duration with microseconds as the largest unit, because the microseconds largest unit changes the maximum possible valid duration due to balancing and floating point arithmetic. Same with microseconds -> milliseconds.

Going to list out the maximum valid Durations based off of unit below for reference:

Unit	Largest Valid Duration
nanosecond	9_007_199_254_740_991_463_129_087
microsecond	9_007_199_254_740_991_475_711
millisecond	9_007_199_254_740_991_487

EDIT: I removed comments listing the printed duration as I didn't explicitly check whether those are accurate.

[ptomato]

Possibly relevant:

• Duration normalization, part 2 of 3 #2727 (review)
• Duration normalization, part 2 of 3 #2727 (comment)

I believe there are test262 tests for the difficult cases that Anba's script revealed, but I'm not 100% sure.

[ptomato]

We discussed this in the Temporal meeting of 2025-05-15 and noted a few things:

• The current limits were written with several possibilities in mind for representation of time durations (what used to be called normalized time durations): 2x float64 or JS Number (whether seconds + subsecond-nanoseconds, or value + error), int128, int64+int32, or some other representation. We did not anticipate that any implementation would want to have the representation of the user-facing Temporal.Duration object as anything but float64 for each component, since those components directly back user-facing JS Numbers.
• The maximum ms, µs, and ns values are intentional. E.g., 9_007_199_254_740_991_475_711 µs is the largest µs value for which ℝ(𝔽(value)) × 10⁻⁶ < 2⁵³.
• We do need to update tests such as https://github.com/tc39/test262/blob/main/test/built-ins/Temporal/Duration/prototype/round/out-of-range-when-converting-from-normalized-duration.js to cover the largest possible ms, µs, and ns values, as well as the smallest impossible ones.