make Lib.getTargetArray API more robust

- add 📚
- do not make copy of set target arrays
- return false if attribute string get does return array

Author: etpinard

src/lib/index.js

@@ -344,13 +344,25 @@ lib.mergeArray = function(traceAttr, cd, cdAttr) {
     }
 };
 
-lib.getTargetArray = function(trace, target) {
+/** Returns target as set by 'target' transform attribute
+ *
+ * @param {object} trace : full trace object
+ * @param {object} transformOpts : transform option object
+ *  - target (string} :
+ *      either an attribute string referencing an array in the trace object, or
+ *      a set array.
+ *
+ * @return {array or false} : the target array (NOT a copy!!) or false if invalid
+ */
+lib.getTargetArray = function(trace, transformOpts) {
+    var target = transformOpts.target;
+
     if(typeof target === 'string' && target) {
         var array = lib.nestedProperty(trace, target).get();
-
-        return Array.isArray(array) ? array : [];
+        return Array.isArray(array) ? array : false;
+    } else if(Array.isArray(target)) {
+        return target;
     }
-    else if(Array.isArray(target)) return target.slice();
 
     return false;
 };

src/transforms/filter.js

@@ -142,12 +142,11 @@ exports.supplyDefaults = function(transformIn) {
 exports.calcTransform = function(gd, trace, opts) {
     if(!opts.enabled) return;
 
+    var targetArray = Lib.getTargetArray(trace, opts);
+    if(!targetArray) return;
+
     var target = opts.target;
-    var targetArray = Lib.getTargetArray(trace, target);
     var len = targetArray.length;
-
-    if(!len) return;
-
     var targetCalendar = opts.targetcalendar;
 
     // even if you provide targetcalendar, if target is a string and there

src/transforms/sort.js

@@ -73,12 +73,12 @@ exports.supplyDefaults = function(transformIn) {
 exports.calcTransform = function(gd, trace, opts) {
     if(!opts.enabled) return;
 
+    var targetArray = Lib.getTargetArray(trace, opts);
+    if(!targetArray) return;
+
     var target = opts.target;
-    var targetArray = Lib.getTargetArray(trace, target);
     var len = targetArray.length;
 
-    if(!len) return;
-
     var arrayAttrs = PlotSchema.findArrayAttributes(trace);
     var d2c = Axes.getDataToCoordFunc(gd, trace, target, targetArray);
     var indices = getIndices(opts, targetArray, d2c);