Improved docs and errors for boost and turboThreshold. Close highchar…

…ts#11608.

errors/12/readme.md

@@ -1,9 +1,12 @@
 # Highcharts expects point configuration to be numbers or arrays in turbo mode
 
-This error occurs if the series.data option contains object configurations and
+This error occurs if the `series.data` option contains object configurations and
 the number of points exceeds the turboThreshold. It can be fixed by either
 setting `turboThreshold` to a higher value, or changing the point
 configurations to numbers or arrays.
 
+In boost mode, turbo mode is always on, which means only array of numbers or
+two dimensional arrays are allowed.
+
 See
 [plotOptions.series.turboThreshold](https://api.highcharts.com/highcharts#plotOptions.series.turboThreshold)

errors/errors.json

@@ -10,7 +10,7 @@
 	},
 	"12": {
 		"title": "Highcharts expects point configuration to be numbers or arrays in turbo mode",
-		"text": "<h1>Highcharts expects point configuration to be numbers or arrays in turbo mode</h1><p>This error occurs if the series.data option contains object configurations and the number of points exceeds the turboThreshold. It can be fixed by either setting <code>turboThreshold</code> to a higher value, or changing the point configurations to numbers or arrays.</p><p>See <a href=\"https://api.highcharts.com/highcharts#plotOptions.series.turboThreshold\">plotOptions.series.turboThreshold</a></p>"
+		"text": "<h1>Highcharts expects point configuration to be numbers or arrays in turbo mode</h1><p>This error occurs if the <code>series.data</code> option contains object configurations and the number of points exceeds the turboThreshold. It can be fixed by either setting <code>turboThreshold</code> to a higher value, or changing the point configurations to numbers or arrays.</p><p>In boost mode, turbo mode is always on, which means only array of numbers or two dimensional arrays are allowed.</p><p>See <a href=\"https://api.highcharts.com/highcharts#plotOptions.series.turboThreshold\">plotOptions.series.turboThreshold</a></p>"
 	},
 	"13": {
 		"title": "Rendering div not found",

js/error-messages.js

@@ -25,7 +25,7 @@ H.errorMessages = {
     },
     "12": {
         "title": "Highcharts expects point configuration to be numbers or arrays in turbo mode",
-        "text": "<h1>Highcharts expects point configuration to be numbers or arrays in turbo mode</h1><p>This error occurs if the series.data option contains object configurations and the number of points exceeds the turboThreshold. It can be fixed by either setting <code>turboThreshold</code> to a higher value, or changing the point configurations to numbers or arrays.</p><p>See <a href=\"https://api.highcharts.com/highcharts#plotOptions.series.turboThreshold\">plotOptions.series.turboThreshold</a></p>"
+        "text": "<h1>Highcharts expects point configuration to be numbers or arrays in turbo mode</h1><p>This error occurs if the <code>series.data</code> option contains object configurations and the number of points exceeds the turboThreshold. It can be fixed by either setting <code>turboThreshold</code> to a higher value, or changing the point configurations to numbers or arrays.</p><p>In boost mode, turbo mode is always on, which means only array of numbers or two dimensional arrays are allowed.</p><p>See <a href=\"https://api.highcharts.com/highcharts#plotOptions.series.turboThreshold\">plotOptions.series.turboThreshold</a></p>"
     },
     "13": {
         "title": "Rendering div not found",

js/modules/boost/boost-overrides.js

@@ -285,7 +285,8 @@ wrap(Series.prototype, 'getExtremes', function (proceed) {
 wrap(Series.prototype, 'processData', function (proceed) {
 
     var series = this,
-        dataToMeasure = this.options.data;
+        dataToMeasure = this.options.data,
+        firstPoint;
 
     // Used twice in this function, first on this.options.data, the second
     // time it runs the check again after processedXData is built.
@@ -320,6 +321,11 @@ wrap(Series.prototype, 'processData', function (proceed) {
 
         // Enter or exit boost mode
         if (this.isSeriesBoosting) {
+            // Force turbo-mode:
+            firstPoint = this.getFirstNotNullPoint(this.options.data);
+            if (!isNumber(firstPoint) && !H.isArray(firstPoint)) {
+                H.error(12, false, this.chart);
+            }
             this.enterBoost();
         } else if (this.exitBoost) {
             this.exitBoost();

js/parts/Series.js

@@ -1912,6 +1912,10 @@ null,
      * and the rest are assumed to be the same format. This saves expensive
      * data checking and indexing in long series. Set it to `0` disable.
      *
+     * Note:
+     * In boost mode turbo threshold is forced. Only array of numbers or
+     * two dimensional arrays are allowed.
+     *
      * @since   2.2
      * @product highcharts highstock gantt
      *
@@ -2737,12 +2741,7 @@ null,
             // loops are similar, they are repeated inside each if-else
             // conditional for max performance.
             if (turboThreshold && dataLength > turboThreshold) {
-                // find the first non-null point
-                i = 0;
-                while (firstPoint === null && i < dataLength) {
-                    firstPoint = data[i];
-                    i++;
-                }
+                firstPoint = series.getFirstNotNullPoint(data);
                 if (isNumber(firstPoint)) { // assume all points are numbers
                     for (i = 0; i < dataLength; i++) {
                         xData[i] = this.autoIncrement();
@@ -3132,6 +3131,24 @@ null,
         this.dataMax = arrayMax(activeYData);
         fireEvent(this, 'afterGetExtremes');
     },
+    /**
+     * Find and return the first non null point in the data
+     *
+     * @private
+     * @function Highcharts.Series.getFirstNotNullPoint
+     * @param {Array<Highcharts.PointOptionsType>} data
+     *        Array of options for points
+     *
+     * @return {Highcharts.PointOptionsType}
+     */
+    getFirstNotNullPoint: function (data) {
+        var firstPoint = null, dataLength = data.length, i = 0;
+        while (firstPoint === null && i < dataLength) {
+            firstPoint = data[i];
+            i++;
+        }
+        return firstPoint;
+    },
     /**
      * Translate data points from raw data values to chart specific
      * positioning data needed later in the `drawPoints` and `drawGraph`

samples/unit-tests/series/setdata/demo.js

@@ -353,18 +353,11 @@ QUnit.test('Boosted series with updatePoints', function (assert) {
         series: [{
             boostThreshold: 1,
             type: 'scatter',
-            data: [{
-                x: 0,
-                y: 0
-            },
-            {
-                x: 1,
-                y: 1
-            },
-            {
-                x: 2,
-                y: 2
-            }]
+            data: [
+                [0, 0],
+                [1, 1],
+                [2, 2]
+            ]
         }]
     });
 
@@ -376,18 +369,11 @@ QUnit.test('Boosted series with updatePoints', function (assert) {
         'Initial data'
     );
 
-    chart.series[0].setData([{
-        x: 3,
-        y: 3
-    },
-    {
-        x: 4,
-        y: 4
-    },
-    {
-        x: 5,
-        y: 5
-    }]);
+    chart.series[0].setData([
+        [3, 3],
+        [4, 4],
+        [5, 5]
+    ]);
 
     assert.strictEqual(
         chart.series[0].points.map(function (p) {

ts/parts/Series.ts

@@ -152,6 +152,10 @@ declare global {
                 allowNull?: boolean
             ): Array<Point>;
             public getXExtremes(xData: Array<number>): RangeObject;
+            public getFirstNotNullPoint (
+                this: Highcharts.Series,
+                data: Array<PointOptionsType>
+            ): PointOptionsType;
             public getZonesGraphs(
                 props: Array<Array<string>>
             ): Array<Array<string>>;
@@ -2507,6 +2511,10 @@ H.Series = H.seriesType<Highcharts.LineSeries>(
          * and the rest are assumed to be the same format. This saves expensive
          * data checking and indexing in long series. Set it to `0` disable.
          *
+         * Note:
+         * In boost mode turbo threshold is forced. Only array of numbers or
+         * two dimensional arrays are allowed.
+         *
          * @since   2.2
          * @product highcharts highstock gantt
          *
@@ -3629,13 +3637,7 @@ H.Series = H.seriesType<Highcharts.LineSeries>(
                 // conditional for max performance.
                 if (turboThreshold && dataLength > turboThreshold) {
 
-                    // find the first non-null point
-                    i = 0;
-                    while (firstPoint === null && i < dataLength) {
-                        firstPoint = data[i];
-                        i++;
-                    }
-
+                    firstPoint = series.getFirstNotNullPoint(data);
 
                     if (isNumber(firstPoint)) { // assume all points are numbers
                         for (i = 0; i < dataLength; i++) {
@@ -4180,6 +4182,32 @@ H.Series = H.seriesType<Highcharts.LineSeries>(
             fireEvent(this, 'afterGetExtremes');
         },
 
+        /**
+         * Find and return the first non null point in the data
+         *
+         * @private
+         * @function Highcharts.Series.getFirstNotNullPoint
+         * @param {Array<Highcharts.PointOptionsType>} data
+         *        Array of options for points
+         *
+         * @return {Highcharts.PointOptionsType}
+         */
+        getFirstNotNullPoint: function (
+            this: Highcharts.Series,
+            data: Array<Highcharts.PointOptionsType>
+        ): Highcharts.PointOptionsType {
+            var firstPoint = null,
+                dataLength = data.length,
+                i = 0;
+
+            while (firstPoint === null && i < dataLength) {
+                firstPoint = data[i];
+                i++;
+            }
+
+            return firstPoint;
+        },
+
         /**
          * Translate data points from raw data values to chart specific
          * positioning data needed later in the `drawPoints` and `drawGraph`