LibJS: Add an Iterator constructor and object

The Iterator object cannot be constructed directly but can be subclassed
or created with `Iterator.from` (not implemented here).

Userland/Libraries/LibJS/CMakeLists.txt

@@ -141,6 +141,8 @@ set(SOURCES
     Runtime/Intl/SegmentIteratorPrototype.cpp
     Runtime/Intl/SegmentsPrototype.cpp
     Runtime/Intrinsics.cpp
+    Runtime/Iterator.cpp
+    Runtime/IteratorConstructor.cpp
     Runtime/IteratorOperations.cpp
     Runtime/IteratorPrototype.cpp
     Runtime/JSONObject.cpp

Userland/Libraries/LibJS/Forward.h

@@ -32,6 +32,7 @@
     __JS_ENUMERATE(FinalizationRegistry, finalization_registry, FinalizationRegistryPrototype, FinalizationRegistryConstructor, void)          \
     __JS_ENUMERATE(FunctionObject, function, FunctionPrototype, FunctionConstructor, void)                                                     \
     __JS_ENUMERATE(GeneratorFunction, generator_function, GeneratorFunctionPrototype, GeneratorFunctionConstructor, void)                      \
+    __JS_ENUMERATE(Iterator, iterator, IteratorPrototype, IteratorConstructor, void)                                                           \
     __JS_ENUMERATE(Map, map, MapPrototype, MapConstructor, void)                                                                               \
     __JS_ENUMERATE(NumberObject, number, NumberPrototype, NumberConstructor, void)                                                             \
     __JS_ENUMERATE(Object, object, ObjectPrototype, ObjectConstructor, void)                                                                   \
@@ -106,7 +107,6 @@
     __JS_ENUMERATE(Temporal::Temporal, temporal)
 
 #define JS_ENUMERATE_ITERATOR_PROTOTYPES                         \
-    __JS_ENUMERATE(Iterator, iterator)                           \
     __JS_ENUMERATE(ArrayIterator, array_iterator)                \
     __JS_ENUMERATE(AsyncIterator, async_iterator)                \
     __JS_ENUMERATE(Intl::SegmentIterator, intl_segment_iterator) \

Userland/Libraries/LibJS/Runtime/GlobalObject.cpp

@@ -48,6 +48,7 @@
 #include <LibJS/Runtime/Intl/PluralRulesConstructor.h>
 #include <LibJS/Runtime/Intl/RelativeTimeFormatConstructor.h>
 #include <LibJS/Runtime/Intl/SegmenterConstructor.h>
+#include <LibJS/Runtime/IteratorConstructor.h>
 #include <LibJS/Runtime/JSONObject.h>
 #include <LibJS/Runtime/MapConstructor.h>
 #include <LibJS/Runtime/MathObject.h>
@@ -146,6 +147,7 @@ Object& set_default_global_bindings(Realm& realm)
     global.define_intrinsic_accessor(vm.names.Int8Array, attr, [](auto& realm) -> Value { return realm.intrinsics().int8_array_constructor(); });
     global.define_intrinsic_accessor(vm.names.Int16Array, attr, [](auto& realm) -> Value { return realm.intrinsics().int16_array_constructor(); });
     global.define_intrinsic_accessor(vm.names.Int32Array, attr, [](auto& realm) -> Value { return realm.intrinsics().int32_array_constructor(); });
+    global.define_intrinsic_accessor(vm.names.Iterator, attr, [](auto& realm) -> Value { return realm.intrinsics().iterator_constructor(); });
     global.define_intrinsic_accessor(vm.names.Map, attr, [](auto& realm) -> Value { return realm.intrinsics().map_constructor(); });
     global.define_intrinsic_accessor(vm.names.Number, attr, [](auto& realm) -> Value { return realm.intrinsics().number_constructor(); });
     global.define_intrinsic_accessor(vm.names.Object, attr, [](auto& realm) -> Value { return realm.intrinsics().object_constructor(); });

Userland/Libraries/LibJS/Runtime/Intrinsics.cpp

@@ -63,6 +63,7 @@
 #include <LibJS/Runtime/Intl/SegmenterPrototype.h>
 #include <LibJS/Runtime/Intl/SegmentsPrototype.h>
 #include <LibJS/Runtime/Intrinsics.h>
+#include <LibJS/Runtime/IteratorConstructor.h>
 #include <LibJS/Runtime/IteratorPrototype.h>
 #include <LibJS/Runtime/JSONObject.h>
 #include <LibJS/Runtime/MapConstructor.h>

Userland/Libraries/LibJS/Runtime/Iterator.cpp

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2023, Tim Flynn <trflynn89@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <LibJS/Runtime/Iterator.h>
+
+namespace JS {
+
+ThrowCompletionOr<NonnullGCPtr<Iterator>> Iterator::create(Realm& realm, Object& prototype, IteratorRecord iterated)
+{
+    return MUST_OR_THROW_OOM(realm.heap().allocate<Iterator>(realm, prototype, move(iterated)));
+}
+
+Iterator::Iterator(Object& prototype, IteratorRecord iterated)
+    : Object(ConstructWithPrototypeTag::Tag, prototype)
+    , m_iterated(move(iterated))
+{
+}
+
+Iterator::Iterator(Object& prototype)
+    : Iterator(prototype, {})
+{
+}
+
+}

Userland/Libraries/LibJS/Runtime/Iterator.h

@@ -1,11 +1,13 @@
 /*
  * Copyright (c) 2022, Linus Groh <linusg@serenityos.org>
+ * Copyright (c) 2023, Tim Flynn <trflynn89@serenityos.org>
  *
  * SPDX-License-Identifier: BSD-2-Clause
  */
 
 #pragma once
 
+#include <LibJS/Runtime/Completion.h>
 #include <LibJS/Runtime/Object.h>
 #include <LibJS/Runtime/Value.h>
 
@@ -18,4 +20,19 @@ struct IteratorRecord {
     bool done { false };    // [[Done]]
 };
 
+class Iterator : public Object {
+    JS_OBJECT(Iterator, Object);
+
+public:
+    static ThrowCompletionOr<NonnullGCPtr<Iterator>> create(Realm&, Object& prototype, IteratorRecord iterated);
+
+    IteratorRecord const& iterated() const { return m_iterated; }
+
+private:
+    Iterator(Object& prototype, IteratorRecord iterated);
+    explicit Iterator(Object& prototype);
+
+    IteratorRecord m_iterated; // [[Iterated]]
+};
+
 }

Userland/Libraries/LibJS/Runtime/IteratorConstructor.cpp

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2023, Tim Flynn <trflynn89@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <LibJS/Runtime/AbstractOperations.h>
+#include <LibJS/Runtime/Intrinsics.h>
+#include <LibJS/Runtime/Iterator.h>
+#include <LibJS/Runtime/IteratorConstructor.h>
+#include <LibJS/Runtime/IteratorPrototype.h>
+#include <LibJS/Runtime/Realm.h>
+#include <LibJS/Runtime/VM.h>
+
+namespace JS {
+
+// 3.1.1.1 The Iterator Constructor, https://tc39.es/proposal-iterator-helpers/#sec-iterator-constructor
+IteratorConstructor::IteratorConstructor(Realm& realm)
+    : Base(realm.vm().names.Iterator.as_string(), realm.intrinsics().function_prototype())
+{
+}
+
+ThrowCompletionOr<void> IteratorConstructor::initialize(Realm& realm)
+{
+    MUST_OR_THROW_OOM(Base::initialize(realm));
+
+    auto& vm = this->vm();
+
+    // 3.1.1.2.1 Iterator.prototype, https://tc39.es/proposal-iterator-helpers/#sec-iterator.prototype
+    define_direct_property(vm.names.prototype, realm.intrinsics().iterator_prototype(), 0);
+
+    define_direct_property(vm.names.length, Value(0), Attribute::Configurable);
+
+    return {};
+}
+
+// 3.1.1.1.1 Iterator ( ), https://tc39.es/proposal-iterator-helpers/#sec-iterator
+ThrowCompletionOr<Value> IteratorConstructor::call()
+{
+    auto& vm = this->vm();
+
+    // 1. If NewTarget is undefined or the active function object, throw a TypeError exception.
+    return vm.throw_completion<TypeError>(ErrorType::ConstructorWithoutNew, "Iterator");
+}
+
+// 3.1.1.1.1 Iterator ( ), https://tc39.es/proposal-iterator-helpers/#sec-iterator
+ThrowCompletionOr<NonnullGCPtr<Object>> IteratorConstructor::construct(FunctionObject& new_target)
+{
+    auto& vm = this->vm();
+
+    // 1. If NewTarget is undefined or the active function object, throw a TypeError exception.
+    if (&new_target == this)
+        return vm.throw_completion<TypeError>(ErrorType::ClassIsAbstract, "Iterator");
+
+    // 2. Return ? OrdinaryCreateFromConstructor(NewTarget, "%Iterator.prototype%").
+    return TRY(ordinary_create_from_constructor<Iterator>(vm, new_target, &Intrinsics::iterator_prototype));
+}
+
+}

Userland/Libraries/LibJS/Runtime/IteratorConstructor.h

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023, Tim Flynn <trflynn89@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <LibJS/Forward.h>
+#include <LibJS/Runtime/NativeFunction.h>
+
+namespace JS {
+
+class IteratorConstructor : public NativeFunction {
+    JS_OBJECT(IteratorConstructor, NativeFunction);
+
+public:
+    virtual ThrowCompletionOr<void> initialize(Realm&) override;
+
+    virtual ThrowCompletionOr<Value> call() override;
+    virtual ThrowCompletionOr<NonnullGCPtr<Object>> construct(FunctionObject& new_target) override;
+
+private:
+    explicit IteratorConstructor(Realm&);
+
+    virtual bool has_constructor() const override { return true; }
+};
+
+}

Userland/Libraries/LibJS/Tests/builtins/Iterator/Iterator.js

@@ -0,0 +1,27 @@
+describe("errors", () => {
+    test("called without new", () => {
+        expect(() => {
+            Iterator();
+        }).toThrowWithMessage(TypeError, "Iterator constructor must be called with 'new'");
+    });
+
+    test("cannot be directly constructed", () => {
+        expect(() => {
+            new Iterator();
+        }).toThrowWithMessage(TypeError, "Abstract class Iterator cannot be constructed directly");
+    });
+});
+
+describe("normal behavior", () => {
+    test("length is 0", () => {
+        expect(Iterator).toHaveLength(0);
+    });
+
+    test("can be constructed from with subclass", () => {
+        class TestIterator extends Iterator {}
+
+        const iterator = new TestIterator();
+        expect(iterator).toBeInstanceOf(TestIterator);
+        expect(iterator).toBeInstanceOf(Iterator);
+    });
+});