refactor: move the destructive iterator to a new method

Author: Victor Fernandez

index.d.ts

@@ -33,8 +33,20 @@ export default class Queue<ValueType> implements Iterable<ValueType> {
 	*/
 	constructor();
 
+	/**
+	Implements the iterable protocol, allowing the queue to be used in a for...of loop.
+	Iterates through the queue without removing elements.
+	If you want to remove the items as you consume it, use `drain()` instead.
+	*/
 	[Symbol.iterator](): IterableIterator<ValueType>;
 
+	/**
+	Returns an iterator that dequeues items as you consume it.
+	This allows you to empty the queue while processing its items.
+	If you want to *not* remove the items as you consume it, use the queue object as iterator.
+	*/
+	drain(): IterableIterator<ValueType>;
+
 	/**
 	Add a value to the queue.
 	*/

index.js

@@ -68,6 +68,15 @@ export default class Queue {
 	}
 
 	* [Symbol.iterator]() {
+		let current = this.#head;
+
+		while (current) {
+			yield current.value;
+			current = current.next;
+		}
+	}
+
+	* drain() {
 		let current;
 		while ((current = this.dequeue()) !== undefined) {
 			yield current;

readme.md

@@ -39,7 +39,10 @@ console.log(queue.dequeue());
 
 ### `queue = new Queue()`
 
-The instance is an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols), which means you can iterate over the queue front to back with a “for…of” loop, or use spreading to convert the queue to an array. Don't do this unless you really need to though, since it's slow.
+The instance is an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols), which means you can iterate over the queue front to back with a “for…of” loop. Using the iterator will _not_ remove the items from the queue. If you want to remove the items as you consume it,
+use [`drain()`](#drain) instead.
+
+You can also use spreading to convert the queue to an array. Don't do this unless you really need to though, since it's slow.
 
 #### `.enqueue(value)`
 
@@ -57,6 +60,12 @@ Get the next value in the queue without removing it.
 
 Returns the value or `undefined` if the queue is empty.
 
+#### `.drain()`
+
+Returns an iterator that dequeues items as you consume it.
+
+This allows you to empty the queue while processing its items.
+
 #### `.clear()`
 
 Clear the queue.

test.js

@@ -70,11 +70,11 @@ test('iterable', t => {
 	t.deepEqual([...queue], ['🦄', '🌈']);
 });
 
-test('iterable dequeues (issue 11)', t => {
+test('drain iterable dequeues (issue 11)', t => {
 	const queue = new Queue();
 	queue.enqueue('🦄');
 	queue.enqueue('🌈');
-	for (const _ of queue) {}
+	for (const _ of queue.drain()) {}
 	t.deepEqual([...queue], []);
 	t.is(queue.size, 0);
 })