fix: add new drain method that iterates and dequeues

index.d.ts

@@ -33,8 +33,22 @@ export default class Queue<ValueType> implements Iterable<ValueType> {
 	*/
 	constructor();
 
+	/**
+	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 that, use `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.
+	*/
 	[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 items as you consume it, use the `Queue` object as an iterator.
+	*/
+	drain(): IterableIterator<ValueType>;
+
 	/**
 	Add a value to the queue.
 	*/

index.js

@@ -75,4 +75,11 @@ export default class Queue {
 			current = current.next;
 		}
 	}
+
+	* drain() {
+		let current;
+		while ((current = this.dequeue()) !== undefined) {
+			yield current;
+		}
+	}
 }

readme.md

@@ -39,7 +39,9 @@ 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 that, 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 +59,14 @@ 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.
+
+If you want to not remove items as you consume it, use the `Queue` object as an iterator.
+
 #### `.clear()`
 
 Clear the queue.

test.js

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