[js] Enable haxe for-in iteration of js.lib Map and Set (#8754)

* [js] Enable haxe for-in iteration of js.lib Map and Set

* [js] Add to IteratorStructure<T>

* Correct comment

* [js] Disable direct iteration of js.lib.Iterator because of semantic mismatch

* [js] Enable `js.lib.Iterator` iteration via `using HaxeIterator`

* [js] Add details to comment

* [js] Remove MapKVIterator because it is not needed

* [js] Use haxe-style casing for SetKvIterator

* Add documentation to js.lib.Iterator

* Rename to SetKeyValueIterator

std/js/lib/HaxeIterator.hx

@@ -0,0 +1,53 @@
+/*
+ * Copyright (C)2005-2019 Haxe Foundation
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+package js.lib;
+
+/**
+	`HaxeIterator` wraps a JavaScript native iterator object to enable for-in iteration in haxe.
+	It can be used directly: `new HaxeIterator(jsIterator)` or via using: `using HaxeIterator`.
+**/
+class HaxeIterator<T> {
+
+	final jsIterator: js.lib.Iterator<T>;
+	var lastStep: js.lib.Iterator.IteratorStep<T>;
+
+	public inline function new(jsIterator: js.lib.Iterator<T>) {
+		this.jsIterator = jsIterator;
+		lastStep = jsIterator.next();
+	}
+
+	public inline function hasNext(): Bool {
+		return !lastStep.done;
+	}
+
+	public inline function next(): T {
+		var v = lastStep.value;
+		lastStep = jsIterator.next();
+		return v;
+	}
+
+	public static inline function iterator<T>(jsIterator: js.lib.Iterator<T>) {
+		return new HaxeIterator(jsIterator);
+	}
+
+}

std/js/lib/Iterator.hx

@@ -22,11 +22,16 @@
 
 package js.lib;
 
+/**
+	Native JavaScript iterator structure. To enable haxe for-in iteration, use `js.lib.HaxeIterator`, for example `for (v in new js.lib.HaxeIterator(jsIterator))` or add `using js.lib.HaxeIterator;` to your module
+
+	See [Iteration Protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)
+**/
 typedef Iterator<T> = {
 	function next():IteratorStep<T>;
 }
 
 typedef IteratorStep<T> = {
 	done:Bool,
 	?value:T
-}
+}

std/js/lib/Map.hx

@@ -22,8 +22,6 @@
 
 package js.lib;
 
-import js.lib.Iterator;
-
 /**
 	The (native) JavaScript Map object holds key-value pairs.
 	Any value (both objects and primitive values) may be used as either a key
@@ -88,19 +86,28 @@ extern class Map<K, V> {
 		Returns a new `Iterator` object that contains the keys for each element
 		in the `js.Map` object in insertion order.
 	**/
-	function keys():Iterator<K>;
+	function keys():js.lib.Iterator<K>;
 
 	/**
 		Returns a new `Iterator` object that contains the values for each
 		element in the `js.Map` object in insertion order.
 	**/
-	function values():Iterator<V>;
+	function values():js.lib.Iterator<V>;
 
 	/**
 		Returns a new `Iterator` object that contains an array of `MapEntry`
 		for each element in the `js.Map` object in insertion order.
 	**/
-	function entries():Iterator<MapEntry<K, V>>;
+	function entries():js.lib.Iterator<MapEntry<K, V>>;
+
+	inline function iterator(): js.lib.HaxeIterator<V> {
+		return new HaxeIterator(this.values());
+	}
+
+	inline function keyValueIterator(): HaxeIterator<MapEntry<K,V>> {
+		return new HaxeIterator(this.entries());
+	}
+
 }
 
 /**
@@ -115,4 +122,4 @@ abstract MapEntry<K, V>(Array<Any>) {
 
 	inline function get_value():V
 		return this[1];
-}
+}

std/js/lib/Set.hx

@@ -23,7 +23,6 @@
 package js.lib;
 
 import js.lib.Map.MapEntry;
-import js.lib.Iterator;
 
 /**
 	The `js.Set` object lets you store unique values of any type, whether
@@ -81,13 +80,13 @@ extern class Set<T> {
 		Returns a new `js.lib.Iterator` object that contains the keys for each element
 		in the `js.Set` object in insertion order.
 	**/
-	function keys():Iterator<T>;
+	function keys():js.lib.Iterator<T>;
 
 	/**
 		Returns a new `js.lib.Iterator` object that contains the values for each
 		element in the `js.Set` object in insertion order.
 	**/
-	function values():Iterator<T>;
+	function values():js.lib.Iterator<T>;
 
 	/**
 		Returns a new `js.lib.Iterator` object that contains an array of
@@ -96,5 +95,41 @@ extern class Set<T> {
 		This is kept similar to the `js.Map` object, so that each entry has the
 		same value for its key and value here.
 	**/
-	function entries():Iterator<MapEntry<T, T>>;
+	function entries():js.lib.Iterator<MapEntry<T, T>>;
+
+	inline function iterator(): HaxeIterator<T> {
+		return new HaxeIterator(this.values());
+	}
+
+	inline function keyValueIterator(): SetKeyValueIterator<T> {
+		return new SetKeyValueIterator(this);
+	}
+
 }
+
+/**
+	key => value iterator for js.lib.Set, tracking the entry index for the key to match the behavior of haxe.ds.List
+**/
+class SetKeyValueIterator<T> {
+
+	final set: js.lib.Set<T>;
+	final values: HaxeIterator<T>;
+	var index = 0;
+
+	public inline function new(set: js.lib.Set<T>) {
+		this.set = set;
+		this.values = new HaxeIterator(set.values());
+	}
+
+	public inline function hasNext() : Bool {
+		return values.hasNext();
+	}
+
+	public inline function next() : {key: Int, value: T} {
+		return {
+			key: index++,
+			value: values.next(),
+		};
+	}
+
+}