JS Temporal Compare

Date Comparison

In JavaScript, objects cannot be compared using operators like , ==, or ===.

Always use the equals() or compare() methods rather than standard equality operators.

All temporal objects have their own compare() method:

• Temporal.Instant.compare(instant1, instant2)
• Temporal.PlainDate.compare(plaindate1, plaindate2)
• Temporal.PlainTime.compare(plaintime1, plaintime2)
• Temporal.PlainYearMonth.compare(plainyearmonth1, plainyearmonth2)
• Temporal.PlainMonthDay.compare(plainmonthday1 plainmonthday2)
• Temporal.PlainDateTime.compare(plaindatetime1,plaindatetime2)
• Temporal.ZonedDateTime.compare(zoneddtatime1, zoneddtatime2)
• Temporal.Duration.compare(duration1, duration2)

The compare() Method

The compare() method returns:

• -1 if the first date is earlier
• 1 if the first day is later
• 0 if they are equal:

Example

// Create two Temporal objects

const date1 = Temporal.PlainDate.from("2026-05-17");

const date2 = Temporal.PlainDate.from("2024-12-25");

// Compare the dates

result = Temporal.PlainDate.compare(date1, date2);

Why Do Not Work

Temporal objects are objects, not primitive numbers.

When you write (a The Temporal.Duration object does not have an equals() method due to the > complexity of handling different representations of the same duration. > Instead, equality is checked using the static Temporal.Duration.compare() method.

Examples

// Create two Durations

const d1 = Temporal.Duration.from({ hours:1, minutes:30 });

const d2 = Temporal.Duration.from({ minutes:90 });

// Compare the Durations

let result = Temporal.Duration.compare(d1, d2);

Range Errors

Example

// Create two Durations

const d1 = Temporal.Duration.from({ days:30 });

const d2 = Temporal.Duration.from({ months: 1 });

// Compare the Durations

let result = Temporal.Duration.compare(d1, d2);

The code above fails and throws a RangeError because d2 contains a calendar unit (months), which has an uneven and variable length.

Without a specific starting point on the calendar, the JavaScript runtime cannot determine exactly how many days are in "1 month" to perform the comparison.

For example, 1 month starting in February could be 28 or 29 days, while 1 month starting in January is 31 days.

To fix this, you must pass a relativeTo option as the third argument to Temporal.Duration.compare(). This provides a concrete date context to calculate the exact lengths.

Example

const d1 = Temporal.Duration.from({ days: 30 });

const d2 = Temporal.Duration.from({ months: 1 });

// Provide a start date (e.g., January 1st, 2026)

const startPoint = Temporal.PlainDate.from("2026-01-01");

// Compare the Durations using the reference date

let result = Temporal.Duration.compare(d1, d2, { relativeTo: startPoint });

// Returns -1 (January has 31 days. 30 days is SHORTER than 1 month.)

By altering the relativeTo reference point, the execution context dictates different evaluation results:

February 1st Start: d1 (30 days) is longer than d2 (1 month / 28 days), returning 1.

April 1st Start: d1 (30 days) is exactly equal to d2 (1 month / 30 days), returning 0.

January 1st Start: d1 (30 days) is shorter than d2 (1 month / 31 days), returning -1.

Temporal.Instant.compare()

Example

// Create Temporal.Instant objects

const i1 = Temporal.Instant.from("2026-05-17T12:00:00Z");

const i2 = Temporal.Instant.from("2026-05-17T12:00:00Z");

const i3 = Temporal.Instant.from("2026-05-17T13:00:00Z");

// compare()

let x1 = Temporal.Instant.compare(i1, i2));

let x2 = Temporal.Instant.compare(i1, i3));

let x3 = Temporal.Instant.compare(i3, i1));

Temporal.PlainDate.compare()

Example

// Create two Temporal objects

const date1 = Temporal.PlainDate.from("2026-05-17");

const date2 = Temporal.PlainDate.from("2024-12-25");

// Compare the dates

result = Temporal.PlainDate.compare(date1, date2);

Temporal Sort

The compare() method is designed to be passed directly into the JavaScript Array.sort() method:

Example

// Create an Array of dates

const dates = [

  Temporal.PlainDate.from("2026-05-17"),

  Temporal.PlainDate.from("2022-01-01"),

  Temporal.PlainDate.from("2024-12-25")

];

// Sort chronologically

dates.sort(Temporal.PlainDate.compare);

The Temporal equals() Method

Most (*) temporal objects have their own equals() method:

• instant.equals(instant)
• plaindate.equals(plaindate)
• plaintime.equals(plaintime)
• plainyearmonth.equals(plainyearmonth)
• plainmonthday.equals(plainmonthday)
• plaindateTime.equals(plaindatetime)
• zoneddateTime.equals(zoneddtatime)

(*) Duration has not.

The equals() method returns true if both dates are equal.

Temporal.Instant equals()

Example

// Create Temporal.Instant objects

const i1 = Temporal.Instant.from("2026-05-17T12:00:00Z");

const i2 = Temporal.Instant.from("2026-05-17T12:00:00Z");

const i3 = Temporal.Instant.from("2026-05-17T13:00:00Z");

// equals()

let x1 = i1.equals(i2); // true

let x2 = i1.equals(i3); // false

Temporal.PlainDate equals()

Example

// Create two Temporal objects

const date1 = Temporal.PlainDate.from('2026-05-17');

const date2 = Temporal.PlainDate.from('2026-05-17');

let result = date1.equals(date2);

Temporal.PlainDateTime equals()

You can compare PlaneDateTime values using the equals() method.

Example

const d1 = Temporal.PlainDateTime.from("2026-05-17T14:30:00");

const d2 = Temporal.PlainDateTime.from("2026-05-17T14:30:00");

let result = d1.equals(d2)