highcharts 9.2.2 → 9.3.0

package/es-modules/Data/Modifiers/ChainModifier.js

@@ -0,0 +1,299 @@
+/* *
+ *
+ *  (c) 2020-2021 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Sophie Bremer
+ *
+ * */
+'use strict';
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import DataModifier from './DataModifier.js';
+import U from '../../Core/Utilities.js';
+var merge = U.merge;
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * Modifies a table with the help of modifiers in an ordered chain.
+ *
+ * @private
+ */
+var ChainModifier = /** @class */ (function (_super) {
+    __extends(ChainModifier, _super);
+    /* *
+     *
+     *  Constructors
+     *
+     * */
+    /**
+     * Constructs an instance of the modifier chain.
+     *
+     * @param {DeepPartial<ChainModifier.Options>} [options]
+     * Options to configure the modifier chain.
+     *
+     * @param {...DataModifier} [modifiers]
+     * Modifiers in order for the modifier chain.
+     */
+    function ChainModifier(options) {
+        var modifiers = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            modifiers[_i - 1] = arguments[_i];
+        }
+        var _this = _super.call(this) || this;
+        _this.modifiers = modifiers;
+        _this.options = merge(ChainModifier.defaultOptions, options);
+        return _this;
+    }
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /**
+     * Adds a configured modifier to the end of the modifier chain. Please note,
+     * that the modifier can be added multiple times.
+     *
+     * @param {DataModifier} modifier
+     * Configured modifier to add.
+     *
+     * @param {DataEventEmitter.EventDetail} [eventDetail]
+     * Custom information for pending events.
+     */
+    ChainModifier.prototype.add = function (modifier, eventDetail) {
+        this.emit({
+            type: 'addModifier',
+            detail: eventDetail,
+            modifier: modifier
+        });
+        this.modifiers.push(modifier);
+        this.emit({
+            type: 'addModifier',
+            detail: eventDetail,
+            modifier: modifier
+        });
+    };
+    /**
+     * Clears all modifiers from the chain.
+     *
+     * @param {DataEventEmitter.EventDetail} [eventDetail]
+     * Custom information for pending events.
+     */
+    ChainModifier.prototype.clear = function (eventDetail) {
+        this.emit({
+            type: 'clearChain',
+            detail: eventDetail
+        });
+        this.modifiers.length = 0;
+        this.emit({
+            type: 'afterClearChain',
+            detail: eventDetail
+        });
+    };
+    /**
+     * Applies partial modifications of a cell change to the property `modified`
+     * of the given modified table.
+     *
+     * *Note:* The `modified` property of the table gets replaced.
+     *
+     * @param {Highcharts.DataTable} table
+     * Modified table.
+     *
+     * @param {string} columnName
+     * Column name of changed cell.
+     *
+     * @param {number|undefined} rowIndex
+     * Row index of changed cell.
+     *
+     * @param {Highcharts.DataTableCellType} cellValue
+     * Changed cell value.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTable}
+     * Table with `modified` property as a reference.
+     */
+    ChainModifier.prototype.modifyCell = function (table, columnName, rowIndex, cellValue, eventDetail) {
+        var modifiers = (this.options.reverse ?
+            this.modifiers.reverse() :
+            this.modifiers);
+        if (modifiers.length) {
+            var clone = table.clone();
+            for (var i = 0, iEnd = modifiers.length; i < iEnd; ++i) {
+                modifiers[i].modifyCell(clone, columnName, rowIndex, cellValue, eventDetail);
+                clone = clone.modified;
+            }
+            table.modified = clone;
+        }
+        return table;
+    };
+    /**
+     * Applies partial modifications of column changes to the property
+     * `modified` of the given table.
+     *
+     * *Note:* The `modified` property of the table gets replaced.
+     *
+     * @param {Highcharts.DataTable} table
+     * Modified table.
+     *
+     * @param {Highcharts.DataTableColumnCollection} columns
+     * Changed columns as a collection, where the keys are the column names.
+     *
+     * @param {number} [rowIndex=0]
+     * Index of the first changed row.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTable}
+     * Table with `modified` property as a reference.
+     */
+    ChainModifier.prototype.modifyColumns = function (table, columns, rowIndex, eventDetail) {
+        var modifiers = (this.options.reverse ?
+            this.modifiers.reverse() :
+            this.modifiers.slice());
+        if (modifiers.length) {
+            var clone = table.clone();
+            for (var i = 0, iEnd = modifiers.length; i < iEnd; ++i) {
+                modifiers[i].modifyColumns(clone, columns, rowIndex, eventDetail);
+                clone = clone.modified;
+            }
+            table.modified = clone;
+        }
+        return table;
+    };
+    /**
+     * Applies partial modifications of row changes to the property `modified`
+     * of the given table.
+     *
+     * *Note:* The `modified` property of the table gets replaced.
+     *
+     * @param {Highcharts.DataTable} table
+     * Modified table.
+     *
+     * @param {Array<(Highcharts.DataTableRow|Highcharts.DataTableRowObject)>} rows
+     * Changed rows.
+     *
+     * @param {number} [rowIndex]
+     * Index of the first changed row.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTable}
+     * Table with `modified` property as a reference.
+     */
+    ChainModifier.prototype.modifyRows = function (table, rows, rowIndex, eventDetail) {
+        var modifiers = (this.options.reverse ?
+            this.modifiers.reverse() :
+            this.modifiers.slice());
+        if (modifiers.length) {
+            var clone = table.clone();
+            for (var i = 0, iEnd = modifiers.length; i < iEnd; ++i) {
+                modifiers[i].modifyRows(clone, rows, rowIndex, eventDetail);
+                clone = clone.modified;
+            }
+            table.modified = clone;
+        }
+        return table;
+    };
+    /**
+     * Applies several modifications to the table.
+     *
+     * *Note:* The `modified` property of the table gets replaced.
+     *
+     * @param {DataTable} table
+     * Table to modify.
+     *
+     * @param {DataEventEmitter.EventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {DataTable}
+     * Table as a reference.
+     *
+     * @emits ChainDataModifier#execute
+     * @emits ChainDataModifier#afterExecute
+     */
+    ChainModifier.prototype.modifyTable = function (table, eventDetail) {
+        var chain = this;
+        chain.emit({ type: 'modify', detail: eventDetail, table: table });
+        var modifiers = (chain.options.reverse ?
+            chain.modifiers.reverse() :
+            chain.modifiers.slice());
+        var modified = table.modified;
+        for (var i = 0, iEnd = modifiers.length, modifier = void 0; i < iEnd; ++i) {
+            modifier = modifiers[i];
+            modified = modifier.modifyTable(modified).modified;
+        }
+        table.modified = modified;
+        chain.emit({ type: 'afterModify', detail: eventDetail, table: table });
+        return table;
+    };
+    /**
+     * Removes a configured modifier from all positions of the modifier chain.
+     *
+     * @param {DataModifier} modifier
+     * Configured modifier to remove.
+     *
+     * @param {DataEventEmitter.EventDetail} [eventDetail]
+     * Custom information for pending events.
+     */
+    ChainModifier.prototype.remove = function (modifier, eventDetail) {
+        var modifiers = this.modifiers;
+        this.emit({
+            type: 'removeModifier',
+            detail: eventDetail,
+            modifier: modifier
+        });
+        modifiers.splice(modifiers.indexOf(modifier), 1);
+        this.emit({
+            type: 'afterRemoveModifier',
+            detail: eventDetail,
+            modifier: modifier
+        });
+    };
+    /* *
+     *
+     *  Static Properties
+     *
+     * */
+    /**
+     * Default option for the ordered modifier chain.
+     */
+    ChainModifier.defaultOptions = {
+        modifier: 'Chain',
+        reverse: false
+    };
+    return ChainModifier;
+}(DataModifier));
+/* *
+ *
+ *  Register
+ *
+ * */
+DataModifier.addModifier(ChainModifier);
+/* *
+ *
+ *  Export
+ *
+ * */
+export default ChainModifier;

package/es-modules/Data/Modifiers/DataModifier.js

@@ -0,0 +1,303 @@
+/* *
+ *
+ *  (c) 2020-2021 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Sophie Bremer
+ *  - Gøran Slettemark
+ *
+ * */
+'use strict';
+import DataPromise from '../DataPromise.js';
+import U from '../../Core/Utilities.js';
+var addEvent = U.addEvent, fireEvent = U.fireEvent, merge = U.merge;
+/** eslint-disable valid-jsdoc */
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * Abstract class to provide an interface for modifying a table.
+ *
+ * @private
+ */
+var DataModifier = /** @class */ (function () {
+    function DataModifier() {
+    }
+    /* *
+     *
+     *  Static Functions
+     *
+     * */
+    /**
+     * Adds a modifier class to the registry. The modifier has to provide the
+     * `DataModifier.options` property and the `DataModifier.execute` method to
+     * modify the table.
+     *
+     * @param {DataModifier} modifier
+     * Modifier class (aka class constructor) to register.
+     *
+     * @return {boolean}
+     * Returns true, if the registration was successful. False is returned, if
+     * their is already a modifier registered with this name.
+     */
+    DataModifier.addModifier = function (modifier) {
+        var name = DataModifier.getName(modifier), registry = DataModifier.registry;
+        if (typeof name === 'undefined' ||
+            registry[name]) {
+            return false;
+        }
+        registry[name] = modifier;
+        return true;
+    };
+    /**
+     * Returns all registered modifier names.
+     *
+     * @return {Array<string>}
+     * All registered modifier names.
+     */
+    DataModifier.getAllModifierNames = function () {
+        return Object.keys(DataModifier.registry);
+    };
+    /**
+     * Returns a copy of the modifier registry as record object with
+     * modifier names and their modifier class.
+     *
+     * @return {Record<string,DataModifierRegistryType>}
+     * Copy of the modifier registry.
+     */
+    DataModifier.getAllModifiers = function () {
+        return merge(DataModifier.registry);
+    };
+    /**
+     * Returns a modifier class (aka class constructor) of the given modifier
+     * name.
+     *
+     * @param {string} name
+     * Registered class name of the class type.
+     *
+     * @return {DataModifier|undefined}
+     * Class type, if the class name was found, otherwise `undefined`.
+     */
+    DataModifier.getModifier = function (name) {
+        return DataModifier.registry[name];
+    };
+    /**
+     * Extracts the name from a given modifier class.
+     *
+     * @param {DataModifier} modifier
+     * Modifier class to extract the name from.
+     *
+     * @return {string}
+     * Modifier name, if the extraction was successful, otherwise an empty
+     * string.
+     */
+    DataModifier.getName = function (modifier) {
+        return (modifier.toString().match(DataModifier.nameRegExp) ||
+            ['', ''])[1];
+    };
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /**
+     * Runs a timed execution of the modifier on the given datatable.
+     * Can be configured to run multiple times.
+     *
+     * @param {DataTable} dataTable
+     * The datatable to execute
+     *
+     * @param {DataModifier.BenchmarkOptions} options
+     * Options. Currently supports `iterations` for number of iterations.
+     *
+     * @return {Array<number>}
+     * An array of times in milliseconds
+     *
+     */
+    DataModifier.prototype.benchmark = function (dataTable, options) {
+        var results = [];
+        var modifier = this;
+        var execute = function () {
+            modifier.modifyTable(dataTable);
+            modifier.emit({ type: 'afterBenchmarkIteration' });
+        };
+        var defaultOptions = {
+            iterations: 1
+        };
+        var iterations = merge(defaultOptions, options).iterations;
+        modifier.on('afterBenchmarkIteration', function () {
+            if (results.length === iterations) {
+                modifier.emit({ type: 'afterBenchmark', results: results });
+                return;
+            }
+            // Run again
+            execute();
+        });
+        var times = {
+            startTime: 0,
+            endTime: 0
+        };
+        // Add timers
+        modifier.on('modify', function () {
+            times.startTime = window.performance.now();
+        });
+        modifier.on('afterModify', function () {
+            times.endTime = window.performance.now();
+            results.push(times.endTime - times.startTime);
+        });
+        // Initial run
+        execute();
+        return results;
+    };
+    /**
+     * Emits an event on the modifier to all registered callbacks of this event.
+     *
+     * @param {DataEventEmitter.Event} [e]
+     * Event object containing additonal event information.
+     */
+    DataModifier.prototype.emit = function (e) {
+        fireEvent(this, e.type, e);
+    };
+    /**
+     * Returns a modified copy of the given table.
+     *
+     * @param {Highcharts.DataTable} table
+     * Table to modify.
+     *
+     * @param {DataEventEmitter.EventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Promise<Highcharts.DataTable>}
+     * Table with `modified` property as a reference.
+     */
+    DataModifier.prototype.modify = function (table, eventDetail) {
+        var modifier = this;
+        return new DataPromise(function (resolve, reject) {
+            if (table.modified === table) {
+                table.modified = table.clone(false, eventDetail);
+            }
+            try {
+                resolve(modifier.modifyTable(table, eventDetail));
+            }
+            catch (e) {
+                modifier.emit({
+                    type: 'error',
+                    detail: eventDetail,
+                    table: table
+                });
+                reject(e);
+            }
+        });
+    };
+    /**
+     * Applies partial modifications of a cell change to the property `modified`
+     * of the given modified table.
+     *
+     * @param {Highcharts.DataTable} table
+     * Modified table.
+     *
+     * @param {string} columnName
+     * Column name of changed cell.
+     *
+     * @param {number|undefined} rowIndex
+     * Row index of changed cell.
+     *
+     * @param {Highcharts.DataTableCellType} cellValue
+     * Changed cell value.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTable}
+     * Table with `modified` property as a reference.
+     */
+    DataModifier.prototype.modifyCell = function (table, columnName, rowIndex, cellValue, eventDetail) {
+        return this.modifyTable(table);
+    };
+    /**
+     * Applies partial modifications of column changes to the property
+     * `modified` of the given table.
+     *
+     * @param {Highcharts.DataTable} table
+     * Modified table.
+     *
+     * @param {Highcharts.DataTableColumnCollection} columns
+     * Changed columns as a collection, where the keys are the column names.
+     *
+     * @param {number} [rowIndex=0]
+     * Index of the first changed row.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTable}
+     * Table with `modified` property as a reference.
+     */
+    DataModifier.prototype.modifyColumns = function (table, columns, rowIndex, eventDetail) {
+        return this.modifyTable(table);
+    };
+    /**
+     * Applies partial modifications of row changes to the property `modified`
+     * of the given table.
+     *
+     * @param {Highcharts.DataTable} table
+     * Modified table.
+     *
+     * @param {Array<(Highcharts.DataTableRow|Highcharts.DataTableRowObject)>} rows
+     * Changed rows.
+     *
+     * @param {number} [rowIndex]
+     * Index of the first changed row.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTable}
+     * Table with `modified` property as a reference.
+     */
+    DataModifier.prototype.modifyRows = function (table, rows, rowIndex, eventDetail) {
+        return this.modifyTable(table);
+    };
+    /**
+     * Registers a callback for a specific modifier event.
+     *
+     * @param {string} type
+     * Event type as a string.
+     *
+     * @param {DataEventEmitter.EventCallback} callback
+     * Function to register for an modifier callback.
+     *
+     * @return {Function}
+     * Function to unregister callback from the modifier event.
+     */
+    DataModifier.prototype.on = function (type, callback) {
+        return addEvent(this, type, callback);
+    };
+    /* *
+     *
+     *  Static Properties
+     *
+     * */
+    /**
+     * Regular expression to extract the modifier name (group 1) from the
+     * stringified class type.
+     */
+    DataModifier.nameRegExp = /^function\s+(\w*?)(?:Data)?(?:Modifier)?\s*\(/;
+    /**
+     * Registry as a record object with modifier names and their class.
+     */
+    DataModifier.registry = {};
+    return DataModifier;
+}());
+/* *
+ *
+ *  Export
+ *
+ * */
+export default DataModifier;