LibJS: Implement Temporal.Instant.prototype.round

Author: https://github.com/trflynn89
Commit: https://github.com/LadybirdBrowser/ladybird/commit/f1c3e3d71a0
Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/2557
Reviewed-by: https://github.com/shannonbooth ✅

Libraries/LibJS/Runtime/Temporal/InstantPrototype.cpp

@@ -5,6 +5,7 @@
  * SPDX-License-Identifier: BSD-2-Clause
  */
 
+#include <LibJS/Runtime/Date.h>
 #include <LibJS/Runtime/Temporal/AbstractOperations.h>
 #include <LibJS/Runtime/Temporal/Duration.h>
 #include <LibJS/Runtime/Temporal/InstantPrototype.h>
@@ -37,6 +38,7 @@ void InstantPrototype::initialize(Realm& realm)
     define_native_function(realm, vm.names.subtract, subtract, 1, attr);
     define_native_function(realm, vm.names.until, until, 1, attr);
     define_native_function(realm, vm.names.since, since, 1, attr);
+    define_native_function(realm, vm.names.round, round, 1, attr);
     define_native_function(realm, vm.names.equals, equals, 1, attr);
     define_native_function(realm, vm.names.toString, to_string, 0, attr);
     define_native_function(realm, vm.names.toLocaleString, to_locale_string, 0, attr);
@@ -126,6 +128,99 @@ JS_DEFINE_NATIVE_FUNCTION(InstantPrototype::since)
     return TRY(difference_temporal_instant(vm, DurationOperation::Since, instant, other, options));
 }
 
+// 8.3.9 Temporal.Instant.prototype.round ( roundTo ), https://tc39.es/proposal-temporal/#sec-temporal.instant.prototype.round
+JS_DEFINE_NATIVE_FUNCTION(InstantPrototype::round)
+{
+    auto& realm = *vm.current_realm();
+
+    auto round_to_value = vm.argument(0);
+
+    // 1. Let instant be the this value.
+    // 2. Perform ? RequireInternalSlot(instant, [[InitializedTemporalInstant]]).
+    auto instant = TRY(typed_this_object(vm));
+
+    // 3. If roundTo is undefined, then
+    if (round_to_value.is_undefined()) {
+        // a. Throw a TypeError exception.
+        return vm.throw_completion<TypeError>(ErrorType::TemporalMissingOptionsObject);
+    }
+
+    GC::Ptr<Object> round_to;
+
+    // 4. If roundTo is a String, then
+    if (round_to_value.is_string()) {
+        // a. Let paramString be roundTo.
+        auto param_string = round_to_value;
+
+        // b. Set roundTo to OrdinaryObjectCreate(null).
+        round_to = Object::create(realm, nullptr);
+
+        // c. Perform ! CreateDataPropertyOrThrow(roundTo, "smallestUnit", paramString).
+        MUST(round_to->create_data_property_or_throw(vm.names.smallestUnit, param_string));
+    }
+    // 5. Else,
+    else {
+        // a. Set roundTo to ? GetOptionsObject(roundTo).
+        round_to = TRY(get_options_object(vm, round_to_value));
+    }
+
+    // 6. NOTE: The following steps read options and perform independent validation in alphabetical order
+    //    (GetRoundingIncrementOption reads "roundingIncrement" and GetRoundingModeOption reads "roundingMode").
+
+    // 7. Let roundingIncrement be ? GetRoundingIncrementOption(roundTo).
+    auto rounding_increment = TRY(get_rounding_increment_option(vm, *round_to));
+
+    // 8. Let roundingMode be ? GetRoundingModeOption(roundTo, HALF-EXPAND).
+    auto rounding_mode = TRY(get_rounding_mode_option(vm, *round_to, RoundingMode::HalfExpand));
+
+    // 9. Let smallestUnit be ? GetTemporalUnitValuedOption(roundTo, "smallestUnit", TIME, REQUIRED).
+    auto smallest_unit = TRY(get_temporal_unit_valued_option(vm, *round_to, vm.names.smallestUnit, UnitGroup::Time, Required {}));
+    auto smallest_unit_value = smallest_unit.get<Unit>();
+
+    auto maximum = [&]() {
+        switch (smallest_unit_value) {
+        // 10. If smallestUnit is hour, then
+        case Unit::Hour:
+            // a. Let maximum be HoursPerDay.
+            return hours_per_day;
+        // 11. Else if smallestUnit is minute, then
+        case Unit::Minute:
+            // a. Let maximum be MinutesPerHour × HoursPerDay.
+            return minutes_per_hour * hours_per_day;
+        // 12. Else if smallestUnit is second, then
+        case Unit::Second:
+            // a. Let maximum be SecondsPerMinute × MinutesPerHour × HoursPerDay.
+            return seconds_per_minute * minutes_per_hour * hours_per_day;
+        // 13. Else if smallestUnit is millisecond, then
+        case Unit::Millisecond:
+            // a. Let maximum be ℝ(msPerDay).
+            return ms_per_day;
+        // 14. Else if smallestUnit is microsecond, then
+        case Unit::Microsecond:
+            // a. Let maximum be 10**3 × ℝ(msPerDay).
+            return 1000 * ms_per_day;
+        // 15. Else,
+        case Unit::Nanosecond:
+            // a. Assert: smallestUnit is nanosecond.
+            // b. Let maximum be nsPerDay.
+            return ns_per_day;
+        default:
+            break;
+        }
+
+        VERIFY_NOT_REACHED();
+    }();
+
+    // 16. Perform ? ValidateTemporalRoundingIncrement(roundingIncrement, maximum, true).
+    TRY(validate_temporal_rounding_increment(vm, rounding_increment, maximum, true));
+
+    // 17. Let roundedNs be RoundTemporalInstant(instant.[[EpochNanoseconds]], roundingIncrement, smallestUnit, roundingMode).
+    auto rounded_nanoseconds = round_temporal_instant(instant->epoch_nanoseconds()->big_integer(), rounding_increment, smallest_unit_value, rounding_mode);
+
+    // 18. Return ! CreateTemporalInstant(roundedNs).
+    return MUST(create_temporal_instant(vm, BigInt::create(vm, move(rounded_nanoseconds))));
+}
+
 // 8.3.10 Temporal.Instant.prototype.equals ( other ), https://tc39.es/proposal-temporal/#sec-temporal.instant.prototype.equals
 JS_DEFINE_NATIVE_FUNCTION(InstantPrototype::equals)
 {

Libraries/LibJS/Runtime/Temporal/InstantPrototype.h

@@ -29,6 +29,7 @@ private:
     JS_DECLARE_NATIVE_FUNCTION(subtract);
     JS_DECLARE_NATIVE_FUNCTION(until);
     JS_DECLARE_NATIVE_FUNCTION(since);
+    JS_DECLARE_NATIVE_FUNCTION(round);
     JS_DECLARE_NATIVE_FUNCTION(equals);
     JS_DECLARE_NATIVE_FUNCTION(to_string);
     JS_DECLARE_NATIVE_FUNCTION(to_locale_string);

Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.round.js

@@ -0,0 +1,109 @@
+describe("correct behavior", () => {
+    test("length is 1", () => {
+        expect(Temporal.Instant.prototype.round).toHaveLength(1);
+    });
+
+    test("basic functionality", () => {
+        const instant = new Temporal.Instant(1111111111111n);
+        expect(instant.round({ smallestUnit: "second" }).epochNanoseconds).toBe(1111000000000n);
+        expect(
+            instant.round({ smallestUnit: "second", roundingMode: "ceil" }).epochNanoseconds
+        ).toBe(1112000000000n);
+        expect(
+            instant.round({ smallestUnit: "minute", roundingIncrement: 30, roundingMode: "floor" })
+                .epochNanoseconds
+        ).toBe(0n);
+        expect(
+            instant.round({
+                smallestUnit: "minute",
+                roundingIncrement: 30,
+                roundingMode: "halfExpand",
+            }).epochNanoseconds
+        ).toBe(1800000000000n);
+    });
+
+    test("smallest unit", () => {
+        const instant = new Temporal.Instant(1732488841234567891n);
+
+        const tests = [
+            { smallestUnit: "hour", floor: 1732485600000000000n, ceil: 1732489200000000000n },
+            { smallestUnit: "minute", floor: 1732488840000000000n, ceil: 1732488900000000000n },
+            { smallestUnit: "second", floor: 1732488841000000000n, ceil: 1732488842000000000n },
+            {
+                smallestUnit: "millisecond",
+                floor: 1732488841234000000n,
+                ceil: 1732488841235000000n,
+            },
+            {
+                smallestUnit: "microsecond",
+                floor: 1732488841234567000n,
+                ceil: 1732488841234568000n,
+            },
+            { smallestUnit: "nanosecond", floor: 1732488841234567891n, ceil: 1732488841234567891n },
+        ];
+
+        for (const { smallestUnit, floor, ceil } of tests) {
+            let result = instant.round({ smallestUnit, roundingMode: "floor" });
+            expect(result.epochNanoseconds).toBe(floor);
+
+            result = instant.round({ smallestUnit, roundingMode: "ceil" });
+            expect(result.epochNanoseconds).toBe(ceil);
+        }
+    });
+
+    test("string argument is implicitly converted to options object", () => {
+        const instant = new Temporal.Instant(1111111111111n);
+        expect(
+            instant.round("second").equals(instant.round({ smallestUnit: "second" }))
+        ).toBeTrue();
+    });
+});
+
+describe("errors", () => {
+    test("this value must be a Temporal.Instant object", () => {
+        expect(() => {
+            Temporal.Instant.prototype.round.call("foo", {});
+        }).toThrowWithMessage(TypeError, "Not an object of type Temporal.Instant");
+    });
+
+    test("missing options object", () => {
+        expect(() => {
+            const instant = new Temporal.Instant(1n);
+            instant.round();
+        }).toThrowWithMessage(TypeError, "Required options object is missing or undefined");
+    });
+
+    test("invalid rounding mode", () => {
+        expect(() => {
+            const instant = new Temporal.Instant(1n);
+            instant.round({ smallestUnit: "second", roundingMode: "serenityOS" });
+        }).toThrowWithMessage(RangeError, "is not a valid value for option roundingMode");
+    });
+
+    test("invalid smallest unit", () => {
+        expect(() => {
+            const instant = new Temporal.Instant(1n);
+            instant.round({ smallestUnit: "serenityOS" });
+        }).toThrowWithMessage(RangeError, "is not a valid value for option smallestUnit");
+    });
+
+    test("increment may not be NaN", () => {
+        expect(() => {
+            const instant = new Temporal.Instant(1n);
+            instant.round({ smallestUnit: "second", roundingIncrement: NaN });
+        }).toThrowWithMessage(RangeError, "is not a valid value for option roundingIncrement");
+    });
+
+    test("increment may smaller than 1 or larger than maximum", () => {
+        const instant = new Temporal.Instant(1n);
+        expect(() => {
+            instant.round({ smallestUnit: "second", roundingIncrement: -1 });
+        }).toThrowWithMessage(RangeError, "is not a valid value for option roundingIncrement");
+        expect(() => {
+            instant.round({ smallestUnit: "second", roundingIncrement: 0 });
+        }).toThrowWithMessage(RangeError, "is not a valid value for option roundingIncrement");
+        expect(() => {
+            instant.round({ smallestUnit: "second", roundingIncrement: Infinity });
+        }).toThrowWithMessage(RangeError, "is not a valid value for option roundingIncrement");
+    });
+});