Add support for encoding TypedArrays as primitive objects for serialization

package.json

@@ -59,6 +59,7 @@
     "@plotly/d3-sankey": "^0.5.0",
     "alpha-shape": "^1.0.0",
     "array-range": "^1.0.1",
+    "base64-arraybuffer": "^0.1.5",
     "canvas-fit": "^1.5.0",
     "color-normalize": "^1.0.3",
     "color-rgba": "^2.0.0",

src/lib/coerce.js

@@ -19,7 +19,10 @@ var nestedProperty = require('./nested_property');
 var counterRegex = require('./regex').counter;
 var DESELECTDIM = require('../constants/interactions').DESELECTDIM;
 var wrap180 = require('./angles').wrap180;
-var isArrayOrTypedArray = require('./is_array').isArrayOrTypedArray;
+var isArray = require('./is_array');
+var isArrayOrTypedArray = isArray.isArrayOrTypedArray;
+var isPrimitiveTypedArrayRepr = isArray.isPrimitiveTypedArrayRepr;
+var b64 = require('base64-arraybuffer');
 
 exports.valObjectMeta = {
     data_array: {
@@ -33,8 +36,18 @@ exports.valObjectMeta = {
         otherOpts: ['dflt'],
         coerceFunction: function(v, propOut, dflt) {
             // TODO maybe `v: {type: 'float32', vals: [/* ... */]}` also
-            if(isArrayOrTypedArray(v)) propOut.set(v);
-            else if(dflt !== undefined) propOut.set(dflt);
+            if(isArrayOrTypedArray(v)) {
+                propOut.set(v);
+            } else if(isPrimitiveTypedArrayRepr(v)) {
+                var coercedV = primitiveTypedArrayReprToTypedArray(v);
+                if(coercedV === undefined && dflt !== undefined) {
+                    propOut.set(dflt);
+                } else {
+                    propOut.set(coercedV);
+                }
+            } else if(dflt !== undefined) {
+                propOut.set(dflt);
+            }
         }
     },
     enumerated: {
@@ -392,6 +405,10 @@ exports.coerce = function(containerIn, containerOut, attributes, attribute, dflt
     if(opts.arrayOk && isArrayOrTypedArray(v)) {
         propOut.set(v);
         return v;
+    } else if(opts.arrayOk && isPrimitiveTypedArrayRepr(v)) {
+        var coercedV = primitiveTypedArrayReprToTypedArray(v);
+        propOut.set(coercedV);
+        return coercedV;
     }
 
     var coerceFunction = exports.valObjectMeta[opts.valType].coerceFunction;
@@ -521,3 +538,49 @@ function validate(value, opts) {
     return out !== failed;
 }
 exports.validate = validate;
+
+var dtypeStringToTypedarrayType = {
+    int8: Int8Array,
+    int16: Int16Array,
+    int32: Int32Array,
+    uint8: Uint8Array,
+    uint8_clamped: Uint8ClampedArray,
+    uint16: Uint16Array,
+    uint32: Uint32Array,
+    float32: Float32Array,
+    float64: Float64Array
+};
+
+/**
+ * Convert a primitive TypedArray representation object into a TypedArray
+ * @param {object} v: Object with `dtype` and `data` properties that
+ * represens a TypedArray.
+ *
+ * @returns {TypedArray}
+ */
+function primitiveTypedArrayReprToTypedArray(v) {
+    // v has dtype and data properties
+
+    // Get TypedArray constructor type
+    var TypeArrayType = dtypeStringToTypedarrayType[v.dtype];
+
+    // Process data
+    var coercedV;
+    var value = v.value;
+    if(value instanceof ArrayBuffer) {
+        // value is an ArrayBuffer
+        coercedV = new TypeArrayType(value);
+    } else if(value.constructor === DataView) {
+        // value has a buffer property, where the buffer is an ArrayBuffer
+        coercedV = new TypeArrayType(value.buffer);
+    } else if(Array.isArray(value)) {
+        // value is a primitive array
+        coercedV = new TypeArrayType(value);
+    } else if(typeof value === 'string' ||
+        value instanceof String) {
+        // value is a base64 encoded string
+        var buffer = b64.decode(value);
+        coercedV = new TypeArrayType(buffer);
+    }
+    return coercedV;
+}

src/lib/is_array.js

@@ -5,6 +5,7 @@
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
+var Lib = require('../lib');
 
 'use strict';
 
@@ -38,8 +39,14 @@ function isArray1D(a) {
     return !isArrayOrTypedArray(a[0]);
 }
 
+function isPrimitiveTypedArrayRepr(a) {
+    return (Lib.isPlainObject(a) &&
+        a.hasOwnProperty('dtype') && a.hasOwnProperty('value'));
+}
+
 module.exports = {
     isTypedArray: isTypedArray,
     isArrayOrTypedArray: isArrayOrTypedArray,
-    isArray1D: isArray1D
+    isArray1D: isArray1D,
+    isPrimitiveTypedArrayRepr: isPrimitiveTypedArrayRepr
 };

test/image/mocks/typed_array_repr_scatter.json

@@ -0,0 +1,13 @@
+{
+  "data": [{
+    "type": "scatter",
+    "x":  {"dtype": "float64", "value": [3, 2, 1]},
+    "y":  {"dtype": "float32", "value": "AABAQAAAAEAAAIA/"},
+    "marker": {
+      "color": {
+        "dtype": "uint16",
+        "value": "AwACAAEA",
+      },
+    }
+  }]
+}

test/jasmine/tests/primitive_typed_array_repr_test.js

@@ -0,0 +1,148 @@
+var Lib = require('@src/lib');
+var supplyDefaults = require('../assets/supply_defaults');
+var b64 = require('base64-arraybuffer');
+var mock1 = require('@mocks/typed_array_repr_scatter.json');
+
+var typedArraySpecs = [
+    ['int8', new Int8Array([-128, -34, 1, 127])],
+    ['uint8', new Uint8Array([0, 1, 127, 255])],
+    ['uint8_clamped', new Uint8ClampedArray([0, 1, 127, 255])],
+    ['int16', new Int16Array([-32768, -123, 345, 32767])],
+    ['uint16', new Uint16Array([0, 345, 32767, 65535])],
+    ['int32', new Int32Array([-2147483648, -123, 345, 32767, 2147483647])],
+    ['uint32', new Uint32Array([0, 345, 32767, 4294967295])],
+    ['float32', new Float32Array([1.2E-38, -2345.25, 2.7182818, 3.1415926, 2, 3.4E38])],
+    ['float64', new Float64Array([5.0E-324, 2.718281828459045, 3.141592653589793, 1.8E308])]
+];
+
+describe('Test TypedArray representations', function() {
+    'use strict';
+
+    describe('ArrayBuffer', function() {
+        it('should accept representation as ArrayBuffer', function() {
+            typedArraySpecs.forEach(function(arraySpec) {
+                // Build value and confirm its type
+                var value = arraySpec[1].buffer;
+                expect(value.constructor).toEqual(ArrayBuffer);
+
+                var repr = {
+                    dtype: arraySpec[0],
+                    value: value
+                };
+                var gd = {
+                    data: [{
+                        y: repr
+                    }],
+                };
+
+                supplyDefaults(gd);
+
+                expect(gd.data[0].y).toEqual(repr);
+                expect(gd._fullData[0].y).toEqual(arraySpec[1]);
+            });
+        });
+    });
+
+    describe('Array', function() {
+        it('should accept representation as Array', function() {
+            typedArraySpecs.forEach(function(arraySpec) {
+                // Build value and confirm its type
+                var value = Array.prototype.slice.call(arraySpec[1]);
+                expect(Array.isArray(value)).toEqual(true);
+
+                var repr = {
+                    dtype: arraySpec[0],
+                    value: value
+                };
+                var gd = {
+                    data: [{
+                        y: repr
+                    }],
+                };
+
+                supplyDefaults(gd);
+
+                expect(gd.data[0].y).toEqual(repr);
+                expect(gd._fullData[0].y).toEqual(arraySpec[1]);
+            });
+        });
+    });
+
+    describe('DataView', function() {
+        it('should accept representation as DataView', function() {
+            typedArraySpecs.forEach(function(arraySpec) {
+                // Build value and confirm its type
+                var value = new DataView(arraySpec[1].buffer);
+                expect(value.constructor).toEqual(DataView);
+
+                var repr = {
+                    dtype: arraySpec[0],
+                    value: value
+                };
+                var gd = {
+                    data: [{
+                        y: repr
+                    }],
+                };
+
+                supplyDefaults(gd);
+
+                expect(gd.data[0].y).toEqual(repr);
+                expect(gd._fullData[0].y).toEqual(arraySpec[1]);
+            });
+        });
+    });
+
+    describe('base64', function() {
+        it('should accept representation as base 64 string', function() {
+            typedArraySpecs.forEach(function(arraySpec) {
+                // Build value and confirm its type
+                var value = b64.encode(arraySpec[1].buffer);
+                expect(typeof value).toEqual('string');
+
+                var repr = {
+                    dtype: arraySpec[0],
+                    value: value
+                };
+                var gd = {
+                    data: [{
+                        y: repr
+                    }],
+                };
+
+                supplyDefaults(gd);
+                expect(gd.data[0].y).toEqual(repr);
+                expect(gd._fullData[0].y).toEqual(arraySpec[1]);
+            });
+        });
+    });
+
+    describe('mock', function() {
+        it('should accept representation as base 64 and Array in Mock', function() {
+
+            var gd = Lib.extendDeep({}, mock1);
+            supplyDefaults(gd);
+
+            // Check x
+            // data_array property
+            expect(gd.data[0].x).toEqual({
+                'dtype': 'float64',
+                'value': [3, 2, 1]});
+            expect(gd._fullData[0].x).toEqual(new Float64Array([3, 2, 1]));
+
+            // Check y
+            // data_array property
+            expect(gd.data[0].y).toEqual({
+                'dtype': 'float32',
+                'value': 'AABAQAAAAEAAAIA/'});
+            expect(gd._fullData[0].y).toEqual(new Float32Array([3, 2, 1]));
+
+            // Check marker.color
+            // This is an arrayOk property not a data_array property
+            expect(gd.data[0].marker.color).toEqual({
+                'dtype': 'uint16',
+                'value': 'AwACAAEA'});
+            expect(gd._fullData[0].marker.color).toEqual(new Uint16Array([3, 2, 1]));
+        });
+    });
+});