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 < and > Do Not Work

Temporal objects are objects, not primitive numbers.

When you write (a < b), JavaScript tries to convert both objects to primitives.

For Temporal objects, this does not produce a numeric timestamp like Dates.

Example

// Create two Temporal objects

const a = Temporal.PlainDate.from("2026-02-17");

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

// Compare the dates

console.log(a < b);  // ❌ Error

Temporal.Duration.compare()

Note: 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);

Note: that the two examples above both return 0 for equal. 90 minutes is the same duration as 1 hour and 30 minutes.

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);

Note: Date Comparison Always use the compare() or equals() methods rather than standard equality operators.

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)