Merge 5e655d4 into b5d77b1

README.md

@@ -318,17 +318,22 @@ queue.on(OperationEvent.PAUSED, (operationQueue) => {
 A helper class that accepts a function which will be exexuted as the operation's task.
 
 ```javascript
-const operation = new BlockOperation(async () => {
-    return new Promise((resolve, reject) => {
-            setTimeout(() => {
-                resolve('my operation result');
-            }, 1000);
-        })
+const operation = new BlockOperation(async (op) => {
+	const data = await api.get();
+	...
+	return data;
 });
 
 const result = await operation.start()
 console.log(result) // 'my operation result'
 ```
+You have acces to the operation in the function:
+
+```javascript
+const operation = new BlockOperation(async (op) => {
+	console.log(op === operation);
+});
+```
 
 ## GroupOperation
 

src/BlockOperation.js

@@ -35,7 +35,7 @@ class BlockOperation extends Operation {
     run() {
         const promises = [];
         this.blocks.forEach(block => {
-            promises.push(block());
+            promises.push(block(this));
         });
         return Promise.all(promises);
     }

src/CircularOperationValidator.js

@@ -8,8 +8,11 @@ class CircularOperationValidatorError extends Error {
 
 class CircularOperationValidator {
 
+    /**
+     * @param {Array.<Operation>} operations
+     */
     constructor(operations) {
-        this.operations = operations
+        this.operations = operations;
         this._checkCircular();
     }
 
@@ -32,6 +35,11 @@ class CircularOperationValidator {
         })
     }
 
+    /**
+     * @param {Operation} op
+     * @param map
+     * @private
+     */
     _verifyOpMap(op, map) {
         if (map[op.id] !== undefined) {
             this._throwError(op, map)

src/GroupOperation.js

@@ -43,7 +43,7 @@ class GroupOperation extends Operation {
     }
 
     /**
-     * @param {Array.<Operation>} operation 
+     * @param {Array.<Operation>} operations
      */
     addOperations(operations) {
         this.operations = this.operations.concat(operations);

src/Operation.js

@@ -13,7 +13,7 @@ const { copyArray, isObjectEmpty } = require('./utils');
 class Operation extends EventEmitter {
 
     /**
-     * @param {number} id 
+     * @param {number} [id]
      */
     constructor(id) {
         super();
@@ -44,22 +44,23 @@ class Operation extends EventEmitter {
 
     /**
      * @description Getter returning if Operation finished its task
-     * @type {boolean}
+     * @returns {boolean}
      */
     get isFinished() {
         return this._done;
     }
 
     /**
      * @description Knowing if operation was cancelled
-     * @type {boolean}
+     * @returns {boolean}
      */
     get isCancelled() {
         return this._cancelled;
     }
 
     /**
      * Setter for isInQueue value
+     * @param {boolean} value
      */
     set isInQueue(value) {
         this._isInQueue = value;
@@ -75,6 +76,7 @@ class Operation extends EventEmitter {
     /**
      * Setter for queuePriority value.
      * It is only settable when operation has not yet executed, cancelled or finished
+     * @param {QueuePriority|number} value
      */
     set queuePriority(value) {
         if (this.isExecuting || this.isCancelled || this.isFinished) {
@@ -88,6 +90,7 @@ class Operation extends EventEmitter {
 
     /**
      * Getter for queuePriority value
+     * @returns {QueuePriority|number}
      */
     get queuePriority() {
         return this._queuePriority;
@@ -96,18 +99,20 @@ class Operation extends EventEmitter {
     /**
      * Setter for dependencies value.
      * It is only settable when operation has not yet executed, cancelled or finished
+     * @param {Array.<Operation>} operations
      */
-    set dependencies(value) {
+    set dependencies(operations) {
         if (this.isExecuting || this.isCancelled || this.isFinished) {
             return;
         }
 
-        this._dependencies = value;
+        this._dependencies = operations;
     }
 
     /**
      * Getter for dependencies value.
-     * When operation is executing, cancelled, or finihsed, this returns a copy
+     * When operation is executing, cancelled, or finished, this returns a copy
+     * @returns {Array.<Operation>}
      */
     get dependencies() {
         if (this.isExecuting || this.isCancelled || this.isFinished) {
@@ -198,6 +203,9 @@ class Operation extends EventEmitter {
         return this.promise;
     }
 
+    /**
+     * @protected
+     */
     main() {
         this.isExecuting = true;
         this.emit(OperationEvent.START, this);
@@ -261,7 +269,6 @@ class Operation extends EventEmitter {
             }
         }
     }
-
 }
 
 module.exports = {

src/OperationEvent.js

@@ -6,34 +6,39 @@ class OperationEvent {
 
     /**
      * Event when operation starts
+     * @returns {string}
      */
     get START() {
         return 'start';
     }
 
     /**
      * Event when operation is ready to be executed
+     * @returns {string}
      */
     get READY() {
         return 'ready';
     }
 
     /**
      * Event when operation is done
+     * @returns {string}
      */
     get DONE() {
         return 'done';
     }
 
     /**
      * Event when operation is cancelled
+     * @returns {string}
      */
     get CANCEL() {
         return 'cancel';
     }
 
     /**
      * Event when something went wrong
+     * @returns {string}
      */
     get ERROR() {
         return 'e';

src/OperationQueue.js

@@ -91,7 +91,7 @@ class OperationQueue extends EventEmitter {
 
     /**
      * Getter
-     * @returns {boolean|*}
+     * @returns {boolean}
      */
     get isPaused() {
         return this._paused;
@@ -183,7 +183,7 @@ class OperationQueue extends EventEmitter {
         }
 
         if (this.runningQueue.length < this.maximumConcurentOperations && this.hasOperations()) {
-            const operation = this._getNextOperation();
+            const operation = this.getNextOperation();
             if (operation
                  && !operation.isExecuting
                  || !operation.isCancelled
@@ -196,6 +196,9 @@ class OperationQueue extends EventEmitter {
         }
     }
 
+    /**
+     * @returns {boolean}
+     */
     hasOperations() {
         return !!(this.queues[QueuePriority.veryHigh].length
         + this.queues[QueuePriority.high].length
@@ -204,7 +207,12 @@ class OperationQueue extends EventEmitter {
         + this.queues[QueuePriority.veryLow].length);
     }
 
-    _getNextOperation() {
+    /**
+     * Returns the next operation to be executed
+     *
+     * @returns {?Operation}
+     */
+    getNextOperation() {
         let operation = null;
         if (this.queues[QueuePriority.veryHigh].length) {
             operation = this.queues[QueuePriority.veryHigh].pop();

src/QueueEvent.js

@@ -6,20 +6,23 @@ class QueueEvent {
 
     /**
      * DONE Event
+     * @returns {string}
      */
     get DONE() {
         return 'done';
     }
 
     /**
      * PAUSED Event
+     * @returns {string}
      */
     get PAUSED() {
         return 'paused';
     }
 
     /**
      * RESUMED Event
+     * @returns {string}
      */
     get RESUMED() {
         return 'resumed';
@@ -28,4 +31,4 @@ class QueueEvent {
 
 module.exports = {
     QueueEvent: new QueueEvent()
-}
+};

src/QueuePriority.js

@@ -6,42 +6,47 @@ class QueuePriority {
 
     /**
      * Lowest priority
+     * @type {number}
      */
     get veryLow() {
         return 0;
     }
 
     /**
      * Low priority
+     * @type {number}
      */
     get low() {
         return 1;
     }
 
     /**
      * Normal priority
+     * @type {number}
      */
     get normal() {
         return 2;
     }
 
     /**
      * High priority
+     * @type {number}
      */
     get high() {
         return 3;
     }
 
     /**
      * Highest priority
+     * @type {number}
      */
     get veryHigh() {
         return 4;
     }
 
     /**
      * Validates QueuePriority assignment value
-     * @param {number} value 
+     * @param {QueuePriority|number} value
      */
     isValid(value) {
         return value >= this.veryLow && value <= this.veryHigh;

tests/BlockOperation.spec.js

@@ -83,7 +83,7 @@ describe('BlockOperation', () => {
 
             expect(runFunction).toHaveBeenCalled();
         });
-    })
+    });
 
     describe('function addBlock', () => {
         test('should add new function block', () => {
@@ -118,5 +118,15 @@ describe('BlockOperation', () => {
 
             expect(operation.blocks.length).toEqual(1);
         });
-    })
+    });
+
+    describe('function run', () => {
+        test('pass operation object to function block', async () => {
+            const operation = new BlockOperation((op) => {
+                expect(op).toEqual(operation);
+            });
+
+            await operation.start();
+        });
+    });
 });