Temporal.Duration High-Precision Timing in JavaScript

This article provides an overview of how the modern JavaScript Temporal API, specifically Temporal.Duration, overcomes the limitations of the legacy Date object to deliver nanosecond-precision time difference calculations. You will learn how Temporal.Duration models time spans, how it integrates with points in time via methods like since() and until(), and how built-in rounding, balancing, and unit conversion prevent precision loss and floating-point errors.

The Shift to Nanosecond Precision

The legacy JavaScript Date object relies internally on millisecond timestamps represented as standard floating-point numbers. In contrast, the Temporal specification introduces native nanosecond precision using integer-based arithmetic under the hood.

A Temporal.Duration represents a distinct length of time. It holds separate integer fields for years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds:

const duration = Temporal.Duration.from({
  hours: 1,
  minutes: 30,
  seconds: 15,
  milliseconds: 500,
  microseconds: 250,
  nanoseconds: 100
});

Because individual units are tracked independently, Temporal.Duration avoids the floating-point inaccuracies that frequently occur when converting fractional milliseconds into smaller sub-millisecond units.

Calculating Differences Between Time Points

To calculate the exact difference between two high-precision points in time, modern JavaScript uses Temporal.Instant or Temporal.PlainDateTime combined with the .since() or .until() methods. These methods compute the difference and return a Temporal.Duration.

const start = Temporal.Instant.from("2026-03-30T10:00:00.000000100Z");
const end = Temporal.Instant.from("2026-03-30T10:00:05.000000950Z");

// Calculate duration to the exact nanosecond
const diff = end.since(start);

console.log(diff.seconds);     // 5
console.log(diff.nanoseconds); // 850

By default, differences computed between Temporal.Instant instances default to seconds and sub-second components, preventing unintended conversion errors across daylight saving boundaries.

Controlling Precision with largestUnit and smallestUnit

Temporal.Duration calculations allow precise control over unit granularity without manual division or modulo operations. By configuring options in .since(), .until(), or .round(), you can designate the upper and lower precision limits:

const diffWithConfig = end.since(start, {
  largestUnit: 'millisecond',
  smallestUnit: 'nanosecond'
});

console.log(diffWithConfig.milliseconds); // 5000
console.log(diffWithConfig.nanoseconds);  // 850

• largestUnit determines how high the values will balance before rolling over (e.g., aggregating seconds into total milliseconds or hours).
• smallestUnit defines the truncation or rounding boundary.

Exact Rounding and Fractional Totals

High-precision calculation often requires rounding durations to human-readable units or converting entire durations into a fractional single unit. Temporal.Duration includes native .round() and .total() methods that execute these operations safely.

Rounding Durations

Rounding a duration allows you to specify target increments and rounding modes (such as halfExpand, trunc, ceil, or floor):

const preciseDuration = Temporal.Duration.from({ seconds: 10, microseconds: 650 });

const rounded = preciseDuration.round({
  smallestUnit: 'millisecond',
  roundingMode: 'halfExpand'
});

console.log(rounded.seconds);      // 10
console.log(rounded.milliseconds); // 1

Computing Fractional Totals

When calculating performance metrics or benchmarks, durations often need to be converted to a single floating-point number representing a specific unit. The .total() method performs this calculation relative to an exact target unit:

const totalMicroseconds = preciseDuration.total({ unit: 'microsecond' });
console.log(totalMicroseconds); // 10000650

Summary

Temporal.Duration transforms JavaScript timing operations by providing first-class support for sub-millisecond precision down to single nanoseconds. By decoupling duration values from system clock timestamps, utilizing integer-safe arithmetic, and offering native methods for rounding and unit balancing, Temporal.Duration eliminates the need for third-party date libraries for high-precision time calculations.