LibJS: Implement Temporal.Instant.prototype.subtract()

Author: https://github.com/linusg
Commit: https://github.com/SerenityOS/serenity/commit/6852ba4d343
Pull-request: https://github.com/SerenityOS/serenity/pull/9250
Reviewed-by: https://github.com/IdanHo ✅

Userland/Libraries/LibJS/Runtime/CommonPropertyNames.h

@@ -369,6 +369,7 @@ namespace JS {
     P(subarray)                              \
     P(substr)                                \
     P(substring)                             \
+    P(subtract)                              \
     P(sup)                                   \
     P(tan)                                   \
     P(tanh)                                  \

Userland/Libraries/LibJS/Runtime/Temporal/InstantPrototype.cpp

@@ -36,6 +36,7 @@ void InstantPrototype::initialize(GlobalObject& global_object)
 
     u8 attr = Attribute::Writable | Attribute::Configurable;
     define_native_function(vm.names.add, add, 1, attr);
+    define_native_function(vm.names.subtract, subtract, 1, attr);
     define_native_function(vm.names.round, round, 1, attr);
     define_native_function(vm.names.equals, equals, 1, attr);
     define_native_function(vm.names.valueOf, value_of, 0, attr);
@@ -152,6 +153,31 @@ JS_DEFINE_NATIVE_FUNCTION(InstantPrototype::add)
     return create_temporal_instant(global_object, *ns);
 }
 
+// 8.3.8 Temporal.Instant.prototype.subtract ( temporalDurationLike ), https://tc39.es/proposal-temporal/#sec-temporal.instant.prototype.subtract
+JS_DEFINE_NATIVE_FUNCTION(InstantPrototype::subtract)
+{
+    auto temporal_duration_like = vm.argument(0);
+
+    // 1. Let instant be the this value.
+    // 2. Perform ? RequireInternalSlot(instant, [[InitializedTemporalInstant]]).
+    auto* instant = typed_this(global_object);
+    if (vm.exception())
+        return {};
+
+    // 3. Let duration be ? ToLimitedTemporalDuration(temporalDurationLike, « "years", "months", "weeks", "days" »).
+    auto duration = to_limited_temporal_duration(global_object, temporal_duration_like, { "years"sv, "months"sv, "weeks"sv, "days"sv });
+    if (vm.exception())
+        return {};
+
+    // 4. Let ns be ? AddInstant(instant.[[Nanoseconds]], −duration.[[Hours]], −duration.[[Minutes]], −duration.[[Seconds]], −duration.[[Milliseconds]], −duration.[[Microseconds]], −duration.[[Nanoseconds]]).
+    auto* ns = add_instant(global_object, instant->nanoseconds(), -duration->hours, -duration->minutes, -duration->seconds, -duration->milliseconds, -duration->microseconds, -duration->nanoseconds);
+    if (vm.exception())
+        return {};
+
+    // 5. Return ! CreateTemporalInstant(ns).
+    return create_temporal_instant(global_object, *ns);
+}
+
 // 8.3.11 Temporal.Instant.prototype.round ( options ), https://tc39.es/proposal-temporal/#sec-temporal.instant.prototype.round
 JS_DEFINE_NATIVE_FUNCTION(InstantPrototype::round)
 {

Userland/Libraries/LibJS/Runtime/Temporal/InstantPrototype.h

@@ -24,6 +24,7 @@ private:
     JS_DECLARE_NATIVE_FUNCTION(epoch_microseconds_getter);
     JS_DECLARE_NATIVE_FUNCTION(epoch_nanoseconds_getter);
     JS_DECLARE_NATIVE_FUNCTION(add);
+    JS_DECLARE_NATIVE_FUNCTION(subtract);
     JS_DECLARE_NATIVE_FUNCTION(round);
     JS_DECLARE_NATIVE_FUNCTION(equals);
     JS_DECLARE_NATIVE_FUNCTION(value_of);

Userland/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.subtract.js

@@ -0,0 +1,59 @@
+describe("correct behavior", () => {
+    test("length is 1", () => {
+        expect(Temporal.Instant.prototype.subtract).toHaveLength(1);
+    });
+
+    test("basic functionality", () => {
+        const instant = new Temporal.Instant(1625614921000000000n);
+        const duration = new Temporal.Duration(0, 0, 0, 0, 1, 2, 3, 4, 5, 6);
+        expect(instant.subtract(duration).epochNanoseconds).toBe(1625611197995994994n);
+    });
+});
+
+describe("errors", () => {
+    test("this value must be a Temporal.Instant object", () => {
+        expect(() => {
+            Temporal.Instant.prototype.subtract.call("foo");
+        }).toThrowWithMessage(TypeError, "Not a Temporal.Instant");
+    });
+
+    test("invalid nanoseconds value, positive", () => {
+        const instant = new Temporal.Instant(8_640_000_000_000_000_000_000n);
+        const duration = new Temporal.Duration(0, 0, 0, 0, 0, 0, 0, 0, 0, -1);
+        expect(() => {
+            instant.subtract(duration);
+        }).toThrowWithMessage(
+            RangeError,
+            "Invalid epoch nanoseconds value, must be in range -86400 * 10^17 to 86400 * 10^17"
+        );
+    });
+
+    test("invalid nanoseconds value, negative", () => {
+        const instant = new Temporal.Instant(-8_640_000_000_000_000_000_000n);
+        const duration = new Temporal.Duration(0, 0, 0, 0, 0, 0, 0, 0, 0, 1);
+        expect(() => {
+            instant.subtract(duration);
+        }).toThrowWithMessage(
+            RangeError,
+            "Invalid epoch nanoseconds value, must be in range -86400 * 10^17 to 86400 * 10^17"
+        );
+    });
+
+    test("disallowed fields", () => {
+        const instant = new Temporal.Instant(1625614921000000000n);
+        for (const [args, property] of [
+            [[123, 0, 0, 0], "years"],
+            [[0, 123, 0, 0], "months"],
+            [[0, 0, 123, 0], "weeks"],
+            [[0, 0, 0, 123], "days"],
+        ]) {
+            const duration = new Temporal.Duration(...args);
+            expect(() => {
+                instant.subtract(duration);
+            }).toThrowWithMessage(
+                RangeError,
+                `Invalid value for duration property '${property}': must be zero, got 123`
+            );
+        }
+    });
+});