LibJS: Implement the Temporal.Instant constructor

And the simple Temporal.Instant.prototype getters, so that the constructed Temporal.Instant may actually be validated.
Author: https://github.com/trflynn89 Commit: 90820873a2 Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/2557 Reviewed-by: https://github.com/shannonbooth ✅
2025-09-02 07:37:03 +00:00 · 2024-11-24 14:12:27 -05:00 · 2024-11-24 14:12:27 -05:00 · 90820873a2 · 2024-11-25 12:34:28 +00:00
commit 90820873a2
parent 1675f40e29
22 changed files with 710 additions and 14 deletions
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.compare.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.compare.js
@ -0,0 +1,13 @@
+describe("correct behavior", () => {
+    test("length is 2", () => {
+        expect(Temporal.Instant.compare).toHaveLength(2);
+    });
+
+    test("basic functionality", () => {
+        const instant1 = new Temporal.Instant(111n);
+        expect(Temporal.Instant.compare(instant1, instant1)).toBe(0);
+        const instant2 = new Temporal.Instant(999n);
+        expect(Temporal.Instant.compare(instant1, instant2)).toBe(-1);
+        expect(Temporal.Instant.compare(instant2, instant1)).toBe(1);
+    });
+});
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.from.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.from.js
@ -0,0 +1,64 @@
+describe("correct behavior", () => {
+    test("length is 1", () => {
+        expect(Temporal.Instant.from).toHaveLength(1);
+    });
+
+    test("Instant instance argument", () => {
+        const instant = new Temporal.Instant(123n);
+        expect(Temporal.Instant.from(instant).epochNanoseconds).toBe(123n);
+    });
+
+    test("Instant string argument", () => {
+        expect(Temporal.Instant.from("1975-02-02T14:25:36.123456789Z").epochNanoseconds).toBe(
+            160583136123456789n
+        );
+        // Time zone is not validated
+        expect(
+            Temporal.Instant.from("1975-02-02T14:25:36.123456789Z[Custom/TimeZone]")
+                .epochNanoseconds
+        ).toBe(160583136123456789n);
+
+        // Accepts but ignores the calendar.
+        let result = null;
+        expect(() => {
+            result = Temporal.Instant.from("1970-01-01T00:00Z[u-ca=UTC]");
+        }).not.toThrow();
+        expect(result).toBeInstanceOf(Temporal.Instant);
+        expect(result.epochNanoseconds).toBe(0n);
+
+        // Does not validate calendar name, it only checks that the calendar name matches the grammar.
+        result = null;
+        expect(() => {
+            result = Temporal.Instant.from("1970-01-01T00:00Z[u-ca=aAaAaAaA-bBbBbBb]");
+        }).not.toThrow();
+        expect(result).toBeInstanceOf(Temporal.Instant);
+        expect(result.epochNanoseconds).toBe(0n);
+    });
+});
+
+describe("errors", () => {
+    test("invalid instant string", () => {
+        expect(() => {
+            Temporal.Instant.from("foo");
+        }).toThrowWithMessage(RangeError, "Invalid ISO date time");
+    });
+
+    test("invalid epoch nanoseconds", () => {
+        // Test cases from https://github.com/tc39/proposal-temporal/commit/baead4d85bc3e9ecab1e9824c3d3fe4fdd77fc3a
+        expect(() => {
+            Temporal.Instant.from("-271821-04-20T00:00:00+00:01");
+        }).toThrowWithMessage(RangeError, "Invalid ISO date");
+        expect(() => {
+            Temporal.Instant.from("+275760-09-13T00:00:00-00:01");
+        }).toThrowWithMessage(
+            RangeError,
+            "Invalid epoch nanoseconds value, must be in range -86400 * 10^17 to 86400 * 10^17"
+        );
+    });
+
+    test("annotations must match annotation grammar even though they're ignored", () => {
+        expect(() => {
+            Temporal.Instant.from("1970-01-01T00:00Z[SerenityOS=cool]");
+        }).toThrowWithMessage(RangeError, "Invalid ISO date time");
+    });
+});
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.fromEpochMilliseconds.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.fromEpochMilliseconds.js
@ -0,0 +1,52 @@
+describe("correct behavior", () => {
+    test("length is 1", () => {
+        expect(Temporal.Instant.fromEpochMilliseconds).toHaveLength(1);
+    });
+
+    test("basic functionality", () => {
+        expect(Temporal.Instant.fromEpochMilliseconds(0).epochMilliseconds).toBe(0);
+        expect(Temporal.Instant.fromEpochMilliseconds(1).epochMilliseconds).toBe(1);
+        expect(Temporal.Instant.fromEpochMilliseconds(999_999_999).epochMilliseconds).toBe(
+            999_999_999
+        );
+        expect(
+            Temporal.Instant.fromEpochMilliseconds(8_640_000_000_000_000).epochMilliseconds
+        ).toBe(8_640_000_000_000_000);
+
+        expect(Temporal.Instant.fromEpochMilliseconds(-0).epochMilliseconds).toBe(0);
+        expect(Temporal.Instant.fromEpochMilliseconds(-1).epochMilliseconds).toBe(-1);
+        expect(Temporal.Instant.fromEpochMilliseconds(-999_999_999).epochMilliseconds).toBe(
+            -999_999_999
+        );
+        expect(
+            Temporal.Instant.fromEpochMilliseconds(-8_640_000_000_000_000).epochMilliseconds
+        ).toBe(-8_640_000_000_000_000);
+    });
+});
+
+describe("errors", () => {
+    test("argument must be coercible to BigInt", () => {
+        expect(() => {
+            Temporal.Instant.fromEpochMilliseconds(1.23);
+        }).toThrowWithMessage(RangeError, "Cannot convert non-integral number to BigInt");
+        // NOTE: ToNumber is called on the argument first, so this is effectively NaN.
+        expect(() => {
+            Temporal.Instant.fromEpochMilliseconds("foo");
+        }).toThrowWithMessage(RangeError, "Cannot convert non-integral number to BigInt");
+    });
+
+    test("out-of-range epoch milliseconds value", () => {
+        expect(() => {
+            Temporal.Instant.fromEpochMilliseconds(8_640_000_000_000_001);
+        }).toThrowWithMessage(
+            RangeError,
+            "Invalid epoch nanoseconds value, must be in range -86400 * 10^17 to 86400 * 10^17"
+        );
+        expect(() => {
+            Temporal.Instant.fromEpochMilliseconds(-8_640_000_000_000_001);
+        }).toThrowWithMessage(
+            RangeError,
+            "Invalid epoch nanoseconds value, must be in range -86400 * 10^17 to 86400 * 10^17"
+        );
+    });
+});
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.fromEpochNanoseconds.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.fromEpochNanoseconds.js
@ -0,0 +1,51 @@
+describe("correct behavior", () => {
+    test("length is 1", () => {
+        expect(Temporal.Instant.fromEpochNanoseconds).toHaveLength(1);
+    });
+
+    test("basic functionality", () => {
+        expect(Temporal.Instant.fromEpochNanoseconds(0n).epochNanoseconds).toBe(0n);
+        expect(Temporal.Instant.fromEpochNanoseconds(1n).epochNanoseconds).toBe(1n);
+        expect(Temporal.Instant.fromEpochNanoseconds(999_999_999n).epochNanoseconds).toBe(
+            999_999_999n
+        );
+        expect(
+            Temporal.Instant.fromEpochNanoseconds(8_640_000_000_000_000_000_000n).epochNanoseconds
+        ).toBe(8_640_000_000_000_000_000_000n);
+
+        expect(Temporal.Instant.fromEpochNanoseconds(-0n).epochNanoseconds).toBe(0n);
+        expect(Temporal.Instant.fromEpochNanoseconds(-1n).epochNanoseconds).toBe(-1n);
+        expect(Temporal.Instant.fromEpochNanoseconds(-999_999_999n).epochNanoseconds).toBe(
+            -999_999_999n
+        );
+        expect(
+            Temporal.Instant.fromEpochNanoseconds(-8_640_000_000_000_000_000_000n).epochNanoseconds
+        ).toBe(-8_640_000_000_000_000_000_000n);
+    });
+});
+
+describe("errors", () => {
+    test("argument must be coercible to BigInt", () => {
+        expect(() => {
+            Temporal.Instant.fromEpochNanoseconds(123);
+        }).toThrowWithMessage(TypeError, "Cannot convert number to BigInt");
+        expect(() => {
+            Temporal.Instant.fromEpochNanoseconds("foo");
+        }).toThrowWithMessage(SyntaxError, "Invalid value for BigInt: foo");
+    });
+
+    test("out-of-range epoch nanoseconds value", () => {
+        expect(() => {
+            Temporal.Instant.fromEpochNanoseconds(8_640_000_000_000_000_000_001n);
+        }).toThrowWithMessage(
+            RangeError,
+            "Invalid epoch nanoseconds value, must be in range -86400 * 10^17 to 86400 * 10^17"
+        );
+        expect(() => {
+            Temporal.Instant.fromEpochNanoseconds(-8_640_000_000_000_000_000_001n);
+        }).toThrowWithMessage(
+            RangeError,
+            "Invalid epoch nanoseconds value, must be in range -86400 * 10^17 to 86400 * 10^17"
+        );
+    });
+});
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.js
@ -0,0 +1,30 @@
+describe("errors", () => {
+    test("called without new", () => {
+        expect(() => {
+            Temporal.Instant();
+        }).toThrowWithMessage(TypeError, "Temporal.Instant constructor must be called with 'new'");
+    });
+
+    test("argument must be coercible to bigint", () => {
+        expect(() => {
+            new Temporal.Instant(123);
+        }).toThrowWithMessage(TypeError, "Cannot convert number to BigInt");
+        expect(() => {
+            new Temporal.Instant("foo");
+        }).toThrowWithMessage(SyntaxError, "Invalid value for BigInt: foo");
+    });
+});
+
+describe("normal behavior", () => {
+    test("length is 1", () => {
+        expect(Temporal.Instant).toHaveLength(1);
+    });
+
+    test("basic functionality", () => {
+        const instant = new Temporal.Instant(123n);
+        expect(instant.epochNanoseconds).toBe(123n);
+        expect(typeof instant).toBe("object");
+        expect(instant).toBeInstanceOf(Temporal.Instant);
+        expect(Object.getPrototypeOf(instant)).toBe(Temporal.Instant.prototype);
+    });
+});
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.epochMilliseconds.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.epochMilliseconds.js
@ -0,0 +1,33 @@
+describe("correct behavior", () => {
+    test("basic functionality", () => {
+        expect(new Temporal.Instant(0n).epochMilliseconds).toBe(0);
+        expect(new Temporal.Instant(1n).epochMilliseconds).toBe(0);
+        expect(new Temporal.Instant(999_999n).epochMilliseconds).toBe(0);
+        expect(new Temporal.Instant(1_000_000n).epochMilliseconds).toBe(1);
+        expect(new Temporal.Instant(1_500_000n).epochMilliseconds).toBe(1);
+        expect(new Temporal.Instant(1_999_999n).epochMilliseconds).toBe(1);
+        expect(new Temporal.Instant(2_000_000n).epochMilliseconds).toBe(2);
+        expect(new Temporal.Instant(8_640_000_000_000_000_000_000n).epochMilliseconds).toBe(
+            8_640_000_000_000_000
+        );
+
+        expect(new Temporal.Instant(-0n).epochMilliseconds).toBe(0);
+        expect(new Temporal.Instant(-1n).epochMilliseconds).toBe(-1);
+        expect(new Temporal.Instant(-999_999n).epochMilliseconds).toBe(-1);
+        expect(new Temporal.Instant(-1_000_000n).epochMilliseconds).toBe(-1);
+        expect(new Temporal.Instant(-1_500_000n).epochMilliseconds).toBe(-2);
+        expect(new Temporal.Instant(-1_999_999n).epochMilliseconds).toBe(-2);
+        expect(new Temporal.Instant(-2_000_000n).epochMilliseconds).toBe(-2);
+        expect(new Temporal.Instant(-8_640_000_000_000_000_000_000n).epochMilliseconds).toBe(
+            -8_640_000_000_000_000
+        );
+    });
+});
+
+describe("errors", () => {
+    test("this value must be a Temporal.Instant object", () => {
+        expect(() => {
+            Reflect.get(Temporal.Instant.prototype, "epochMilliseconds", "foo");
+        }).toThrowWithMessage(TypeError, "Not an object of type Temporal.Instant");
+    });
+});
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.epochNanoseconds.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.epochNanoseconds.js
@ -0,0 +1,25 @@
+describe("correct behavior", () => {
+    test("basic functionality", () => {
+        expect(new Temporal.Instant(0n).epochNanoseconds).toBe(0n);
+        expect(new Temporal.Instant(1n).epochNanoseconds).toBe(1n);
+        expect(new Temporal.Instant(999n).epochNanoseconds).toBe(999n);
+        expect(new Temporal.Instant(8_640_000_000_000_000_000_000n).epochNanoseconds).toBe(
+            8_640_000_000_000_000_000_000n
+        );
+
+        expect(new Temporal.Instant(-0n).epochNanoseconds).toBe(-0n);
+        expect(new Temporal.Instant(-1n).epochNanoseconds).toBe(-1n);
+        expect(new Temporal.Instant(-999n).epochNanoseconds).toBe(-999n);
+        expect(new Temporal.Instant(-8_640_000_000_000_000_000_000n).epochNanoseconds).toBe(
+            -8_640_000_000_000_000_000_000n
+        );
+    });
+});
+
+describe("errors", () => {
+    test("this value must be a Temporal.Instant object", () => {
+        expect(() => {
+            Reflect.get(Temporal.Instant.prototype, "epochNanoseconds", "foo");
+        }).toThrowWithMessage(TypeError, "Not an object of type Temporal.Instant");
+    });
+});
--- a/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.valueOf.js
+++ b/Libraries/LibJS/Tests/builtins/Temporal/Instant/Instant.prototype.valueOf.js
@ -0,0 +1,7 @@
+describe("errors", () => {
+    test("throws TypeError", () => {
+        expect(() => {
+            new Temporal.Instant(0n).valueOf();
+        }).toThrowWithMessage(TypeError, "Cannot convert Temporal.Instant to a primitive value");
+    });
+});