fix: .iterator() method follows Java's PriorityQueue implementation

Author: ignlg

README.md

@@ -40,6 +40,14 @@ heap vs array: push + top(50) of 100
 
 ## Changelog
 
+### 2.2
+
+- Fixes `.iterator()` method to follow [Java's PriorityQueue implementation:
+  ](https://docs.oracle.com/javase/8/docs/api/java/util/PriorityQueue.html)
+  > The Iterator provided in method [iterator()](<https://docs.oracle.com/javase/8/docs/api/java/util/PriorityQueue.html#iterator()>) is not guaranteed to traverse the elements of the priority queue in any particular order.
+
+Notice that _using the heap directly as an iteraror will consume the heap,_ as Python's `heapq` implementation does.
+
 ### 2.1
 
 - Adds `Heap.nlargest` as heapq.
@@ -77,7 +85,7 @@ console.log(minHeap.peek()); //> 1
 console.log(minHeap.pop()); //> 1
 console.log(minHeap.peek()); //> 2
 
-// Iterator
+// Iterator, that will consume the heap
 maxHeap.init([3, 4, 1, 12, 8]);
 for (const value of maxHeap) {
   console.log('Next top value is', value);
@@ -94,7 +102,13 @@ const customPriorityComparator = (a, b) => a.priority - b.priority;
 const priorityQueue = new Heap(customPriorityComparator);
 priorityQueue.init(tasks);
 
-// priorityQueue === priorityQueue.iterator()
+// Iterator, the Java way, that will not consume the heap but does not guarantee
+// to traverse the elements of the heap in any particular order. Barely useful.
+for (const taks of priorityQueue.iterator()) {
+  // Do something
+}
+
+// Iterator, the JavaScript and Python way, that will consume the heap
 for (const task of priorityQueue) {
   // Do something
 }
@@ -133,6 +147,7 @@ Basic comparators already included:
 
 ## Implements JavaScript style methods
 
+- `for (const value of heap)` directly usable as an Iterator, consumes the heap
 - `length` of the heap
 - `limit` amount of elements in the heap
 - `pop()` the top element
@@ -152,7 +167,7 @@ Basic comparators already included:
 - `contains(element, fn?)`
 - _`element()` alias of `peek()`_
 - `isEmpty()`
-- `iterator()` returns `this` because it is iterable
+- `iterator()` returns the same as `toArray()` because it is iterable and follows Java's implementation
 - _`offer(element)` alias of `add(element)`_
 - `peek()`
 - _`poll()` alias of `pop()`_

dist/heap-js.es5.js

@@ -693,7 +693,7 @@ var Heap = /** @class */ (function () {
      * Returns an iterator. To comply with Java interface.
      */
     Heap.prototype.iterator = function () {
-        return this;
+        return this.toArray();
     };
     /**
      * Limit heap size if needed

dist/heap-js.umd.js

@@ -699,7 +699,7 @@
          * Returns an iterator. To comply with Java interface.
          */
         Heap.prototype.iterator = function () {
-            return this;
+            return this.toArray();
         };
         /**
          * Limit heap size if needed

docs/assets/main.js

@@ -766,12 +766,13 @@ footer .tsd-legend {
 
 .tsd-flag {
     display: inline-block;
-    padding: 1px 5px;
+    padding: 0.25em 0.4em;
     border-radius: 4px;
     color: var(--color-comment-tag-text);
     background-color: var(--color-comment-tag);
     text-indent: 0;
-    font-size: 14px;
+    font-size: 75%;
+    line-height: 1;
     font-weight: normal;
 }
 

docs/assets/style.css

@@ -646,7 +646,7 @@ export class Heap<T> implements Iterable<T> {
    * Returns an iterator. To comply with Java interface.
    */
   iterator(): Iterable<T> {
-    return this;
+    return this.toArray();
   }
 
   /**

docs/classes/Heap.html

@@ -425,27 +425,36 @@ describe('Heap instances', function () {
       });
 
       describe('is Iterable', function () {
-        it('should be iterable via for...of', function () {
+        it('should be iterable via for...of, consuming the heap', function () {
           heap.init(values.concat(values));
           const top = heap.toArray().slice(0);
           top.sort(heap.comparator());
-          const result = [];
+          const resultFirstRound = [];
           for (const value of heap) {
-            result.push(value);
+            resultFirstRound.push(value);
           }
-          expect(result).toEqual(top);
+          const resultSecondRound = [];
+          for (const value of heap) {
+            resultSecondRound.push(value);
+          }
+          expect(resultFirstRound).toEqual(top);
+          expect(resultSecondRound).toEqual([]);
         });
       });
       describe('#iterator()', function () {
-        it('returns an iterable', function () {
+        it('returns an iterable that does not consume the heap', function () {
           heap.init(values.concat(values));
           const top = heap.toArray().slice(0);
-          top.sort(heap.comparator());
-          const result = [];
+          const resultFirstRound = [];
+          for (const value of heap.iterator()) {
+            resultFirstRound.push(value);
+          }
+          const resultSecondRound = [];
           for (const value of heap.iterator()) {
-            result.push(value);
+            resultSecondRound.push(value);
           }
-          expect(result).toEqual(top);
+          expect(resultFirstRound).toEqual(top);
+          expect(resultSecondRound).toEqual(top);
         });
       });
     });