API documentation + bugfix of toJSON + bump version

README.md

@@ -31,6 +31,88 @@ console.log(queue.toJSON());
 // => [45, 67]
 ```
 
+# API
+## Classes
+* LinkedQueue
+* CyclicQueue (bounded)
+* DynamicCyclicQueue (unbounded)
+* ChunkedQueue
+* DynamicArrayQueue
+
+All of these classes support the following methods
+## Methods
+### `enqueue (item)`  
+Add an item to the queue.  
+Bounded implementations might throw an exception if the capacity is exceeded.
+
+### `dequeue ()`
+Return the first inserted (or the "oldest") item in the queue, and removes it from the queue.  
+Zero sized queue would throw an exception.
+
+### `clear ()`
+Clear the queue.
+
+### `size ()`
+Return the current size of the queue.
+
+### `peekFirst ()`
+Return the first inserted (or the "oldest") item in the queue, without removing it from the queue.  
+Zero sized queue would throw an exception.
+
+### `peekLast ()`
+Return the last inserted (or the "newest") item in the queue, without removing it from the queue.  
+Zero sized queue would throw an exception.
+
+### `[Symbol.iterator] ()`
+Iterate over the items in the queue without changing the queue.  
+Iteration order is the insertion order: first inserted item would be returned first.  
+In essence this supports JS iterations of the pattern `for (let x of queue) { ... }`.  
+Example:  
+```javascript
+const queue = new DynamicArrayQueue();
+queue.enqueue(123);
+queue.enqueue(45);
+for (let item of queue) {
+  console.log(item);
+}
+// ==> output would be:
+// 123
+// 45
+// and the queue would remain unchanged
+```
+
+### `drainingIterator ()`
+Iterate over the items in the queue.  
+Every iterated item is removed from the queue.  
+Iteration order is the insertion order: first inserted item would be returned first.  
+Example:
+```javascript
+const queue = new DynamicArrayQueue();
+queue.enqueue(123);
+queue.enqueue(45);
+for (let item of queue.drainingIterator()) {
+  console.log(item);
+}
+console.log(`size = ${queue.size()}`);
+// ==> output would be:
+// 123
+// 45
+// size = 0
+```
+
+### `copyTo (arr, startIndex)`
+`startIndex` is optional, and defaults to 0 if not given.  
+Copy the items of the queue to the given array `arr`, starting from index `startIndex`.  
+First item in the array is first item inserted to the queue, and so forth.  
+No return value.
+
+### `toArray ()`
+Create an array with the same size as the queue, populate it with the items in the queue, keeping the iteration order, and return it.
+
+### `toJSON ()`
+Return a JSON representation (as a string) of the queue.  
+The queue is represented as an array: first item in the array is the first one inserted to the queue and so forth.
+
 ## Common implementations and mistakes
 ### Array + push + shift
 A very common implementation of a queue looks like this:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "lite-fifo",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "main": "src/index.js",
   "homepage": "https://github.com/kleinron/lite-fifo.git#readme",
   "description": "Lightweight, optimized, and efficient implementations for FIFO (queue) data structure",

src/ChunkedQueue.js

@@ -118,11 +118,8 @@ class ChunkedQueue {
     return arr;
   }
 
-  // noinspection JSUnusedGlobalSymbols
   toJSON () {
-    const arr = new Array(this.size());
-    this.copyTo(arr);
-    return arr;
+    return JSON.stringify(this.toArray());
   }
 }
 

src/CyclicQueue.js

@@ -127,9 +127,8 @@ class CyclicQueue {
     return arr;
   }
 
-  // noinspection JSUnusedGlobalSymbols
   toJSON () {
-    return this.toArray();
+    return JSON.stringify(this.toArray());
   }
 }
 

src/DynamicArrayQueue.js

@@ -85,9 +85,8 @@ class DynamicArrayQueue {
     return arr;
   }
 
-  // noinspection JSUnusedGlobalSymbols
   toJSON () {
-    return this.toArray();
+    return JSON.stringify(this.toArray());
   }
 }
 

src/DynamicCyclicQueue.js

@@ -173,9 +173,8 @@ class DynamicCyclicQueue {
     return arr;
   }
 
-  // noinspection JSUnusedGlobalSymbols
   toJSON () {
-    return this.toArray();
+    return JSON.stringify(this.toArray());
   }
 }
 

src/LinkedQueue.js

@@ -104,9 +104,8 @@ class LinkedQueue {
     };
   }
 
-  // noinspection JSUnusedGlobalSymbols
   toJSON () {
-    return this.toArray();
+    return JSON.stringify(this.toArray());
   }
 }
 

test/src/commonTests.js

@@ -206,7 +206,7 @@ describe('Common API for all implementations', () => {
           numbers[i] = randomNumber();
         }
         numbers.forEach(queue.enqueue);
-        const queueAsJson = JSON.stringify(queue);
+        const queueAsJson = queue.toJSON();
         assert.strictEqual(queueAsJson, JSON.stringify(numbers));
       });