hyperformula-dc
Version:
HyperFormula is a JavaScript engine for efficient processing of spreadsheet-like data and formulas
1,332 lines (1,331 loc) • 129 kB
TypeScript
/**
* @license
* Copyright (c) 2021 Handsoncode. All rights reserved.
*/
import { SimpleCellRange } from './AbsoluteCellRange';
import { CellType, CellValueDetailedType, CellValueType, SimpleCellAddress } from './Cell';
import { CellContentParser, RawCellContent } from './CellContentParser';
import { CellValue } from './CellValue';
import { Config, ConfigParams } from './Config';
import { ColumnRowIndex, CrudOperations } from './CrudOperations';
import { DateTime } from './DateTimeHelper';
import { AddressMapping, ArrayMapping, DependencyGraph, Graph, RangeMapping, SheetMapping, Vertex } from './DependencyGraph';
import { Listeners, TypedEmitter } from './Emitter';
import { Evaluator } from './Evaluator';
import { ExportedChange, Exporter } from './Exporter';
import { LicenseKeyValidityState } from './helpers/licenseKeyValidator';
import { RawTranslationPackage, TranslationPackage } from './i18n';
import { FunctionPluginDefinition } from './interpreter';
import { FunctionRegistry, FunctionTranslationsPackage } from './interpreter/FunctionRegistry';
import { FormatInfo } from './interpreter/InterpreterValue';
import { LazilyTransformingAstService } from './LazilyTransformingAstService';
import { ColumnSearchStrategy } from './Lookup/SearchStrategy';
import { NamedExpression, NamedExpressionOptions, NamedExpressions } from './NamedExpressions';
import { ParserWithCaching, Unparser } from './parser';
import { Serialization, SerializedNamedExpression } from './Serialization';
import { Sheet, SheetDimensions, Sheets } from './Sheet';
import { Statistics, StatType } from './statistics';
/**
* This is a class for creating HyperFormula instance, all the following public methods
* ale related to this class.
*
* The instance can be created only by calling one of the static methods
* `buildFromArray`, `buildFromSheets` or `buildEmpty` and should be disposed of with the
* `destroy` method when it's no longer needed to free the resources.
*
* The instance can be seen as a workbook where worksheets can be created and
* manipulated. They are organized within a widely know structure of columns and rows
* which can be manipulated as well. The smallest possible data unit are the cells, which
* may contain simple values or formulas to be calculated.
*
* All CRUD methods are called directly on HyperFormula instance and will trigger
* corresponding lifecycle events. The events are marked accordingly, as well as thrown
* errors so they can be correctly handled.
*/
export declare class HyperFormula implements TypedEmitter {
private _config;
private _stats;
private _dependencyGraph;
private _columnSearch;
private _parser;
private _unparser;
private _cellContentParser;
private _evaluator;
private _lazilyTransformingAstService;
private _crudOperations;
private _exporter;
private _namedExpressions;
private _serialization;
private _functionRegistry;
/**
* Version of the HyperFormula.
*
* @category Static Properties
*/
static version: string;
/**
* Latest build date.
*
* @category Static Properties
*/
static buildDate: string;
/**
* A release date.
*
* @category Static Properties
*/
static releaseDate: string;
/**
* Contains all available languages to use in registerLanguage.
*
* @category Static Properties
*/
static languages: Record<string, RawTranslationPackage>;
/**
* Calls the `graph` method on the dependency graph.
* Allows to execute `graph` directly without a need to refer to `dependencyGraph`.
*
* @internal
*/
get graph(): Graph<Vertex>;
/**
* Calls the `rangeMapping` method on the dependency graph.
* Allows to execute `rangeMapping` directly without a need to refer to `dependencyGraph`.
*
* @internal
*/
get rangeMapping(): RangeMapping;
/**
* Calls the `arrayMapping` method on the dependency graph.
* Allows to execute `arrayMapping` directly without a need to refer to `dependencyGraph`.
*
* @internal
*/
get arrayMapping(): ArrayMapping;
/**
* Calls the `sheetMapping` method on the dependency graph.
* Allows to execute `sheetMapping` directly without a need to refer to `dependencyGraph`.
*
* @internal
*/
get sheetMapping(): SheetMapping;
/**
* Calls the `addressMapping` method on the dependency graph.
* Allows to execute `addressMapping` directly without a need to refer to `dependencyGraph`.
*
* @internal
*/
get addressMapping(): AddressMapping;
/** @internal */
get dependencyGraph(): DependencyGraph;
/** @internal */
get evaluator(): Evaluator;
/** @internal */
get columnSearch(): ColumnSearchStrategy;
/** @internal */
get lazilyTransformingAstService(): LazilyTransformingAstService;
/**
* Returns state of the validity of the license key.
*
* @internal
*/
get licenseKeyValidityState(): LicenseKeyValidityState;
private static buildFromEngineState;
/**
* Builds the engine for a sheet from a two-dimensional array representation.
* The engine is created with a single sheet.
* Can be configured with the optional second parameter that represents a [[ConfigParams]].
* If not specified, the engine will be built with the default configuration.
*
* @param {Sheet} sheet - two-dimensional array representation of sheet
* @param {Partial<ConfigParams>} configInput - engine configuration
* @param {SerializedNamedExpression[]} namedExpressions - starting named expressions
*
* @throws [[SheetSizeLimitExceededError]] when sheet size exceeds the limits
* @throws [[InvalidArgumentsError]] when sheet is not an array of arrays
* @throws [[FunctionPluginValidationError]] when plugin class definition is not consistent with metadata
*
* @example
* ```js
* // data represented as an array
* const sheetData = [
* ['0', '=SUM(1,2,3)', '52'],
* ['=SUM(A1:C1)', '', '=A1'],
* ['2', '=SUM(A1:C1)', '91'],
* ];
*
* // method with optional config parameter maxColumns
* const hfInstance = HyperFormula.buildFromArray(sheetData, { maxColumns: 1000 });
* ```
*
* @category Factories
*/
static buildFromArray(sheet: Sheet, configInput?: Partial<ConfigParams>, namedExpressions?: SerializedNamedExpression[]): HyperFormula;
/**
* Builds the engine from an object containing multiple sheets with names.
* The engine is created with one or more sheets.
* Can be configured with the optional second parameter that represents a [[ConfigParams]].
* If not specified the engine will be built with the default configuration.
*
* @param {Sheet} sheets - object with sheets definition
* @param {Partial<ConfigParams>} configInput - engine configuration
* @param {SerializedNamedExpression[]} namedExpressions - starting named expressions
*
* @throws [[SheetSizeLimitExceededError]] when sheet size exceeds the limits
* @throws [[InvalidArgumentsError]] when any sheet is not an array of arrays
* @throws [[FunctionPluginValidationError]] when plugin class definition is not consistent with metadata
*
* @example
* ```js
* // data represented as an object with sheets: Sheet1 and Sheet2
* const sheetData = {
* 'Sheet1': [
* ['1', '', '=Sheet2!$A1'],
* ['', '2', '=SUM(1,2,3)'],
* ['=Sheet2!$A2', '2', ''],
* ],
* 'Sheet2': [
* ['', '4', '=Sheet1!$B1'],
* ['', '8', '=SUM(9,3,3)'],
* ['=Sheet1!$B1', '2', ''],
* ],
* };
*
* // method with optional config parameter useColumnIndex
* const hfInstance = HyperFormula.buildFromSheets(sheetData, { useColumnIndex: true });
* ```
*
* @category Factories
*/
static buildFromSheets(sheets: Sheets, configInput?: Partial<ConfigParams>, namedExpressions?: SerializedNamedExpression[]): HyperFormula;
/**
* Builds an empty engine instance.
* Can be configured with the optional parameter that represents a [[ConfigParams]].
* If not specified the engine will be built with the default configuration.
*
* @param {Partial<ConfigParams>} configInput - engine configuration
* @param {SerializedNamedExpression[]} namedExpressions - starting named expressions
*
* @example
* ```js
* // build with no initial data and with optional config parameter maxColumns
* const hfInstance = HyperFormula.buildEmpty({ maxColumns: 1000 });
* ```
*
* @category Factories
*/
static buildEmpty(configInput?: Partial<ConfigParams>, namedExpressions?: SerializedNamedExpression[]): HyperFormula;
private static registeredLanguages;
/**
* Returns registered language from its code string.
*
* @param {string} languageCode - code string of the translation package
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[LanguageNotRegisteredError]] when trying to retrieve not registered language
*
* @example
* ```js
* // return registered language
* const language = HyperFormula.getLanguage('enGB');
* ```
*
* @category Static Methods
*/
static getLanguage(languageCode: string): TranslationPackage;
/**
* Registers language from under given code string.
*
* @param {string} languageCode - code string of the translation package
* @param {RawTranslationPackage} languagePackage - translation package to be registered
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[ProtectedFunctionTranslationError]] when trying to register translation for protected function
* @throws [[LanguageAlreadyRegisteredError]] when given language is already registered
*
* @example
* ```js
* // return registered language
* HyperFormula.registerLanguage('plPL', plPL);
* ```
*
* @category Static Methods
*/
static registerLanguage(languageCode: string, languagePackage: RawTranslationPackage): void;
/**
* Unregisters language that is registered under given code string.
*
* @param {string} languageCode - code string of the translation package
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[LanguageNotRegisteredError]] when given language is not registered
*
* @example
* ```js
* // register the language for the instance
* HyperFormula.registerLanguage('plPL', plPL);
*
* // unregister plPL
* HyperFormula.unregisterLanguage('plPL');
* ```
*
* @category Static Methods
*/
static unregisterLanguage(languageCode: string): void;
/**
* Returns all registered languages codes.
*
* @example
* ```js
* // should return all registered language codes: ['enGB', 'plPL']
* const registeredLangugaes = HyperFormula.getRegisteredLanguagesCodes();
* ```
*
* @category Static Methods
*/
static getRegisteredLanguagesCodes(): string[];
/**
* Registers all functions in a given plugin with optional translations
*
* @param {FunctionPluginDefinition} plugin - plugin class
* @param {FunctionTranslationsPackage} translations - optional package of function names translations
*
* @throws [[FunctionPluginValidationError]] when plugin class definition is not consistent with metadata
* @throws [[ProtectedFunctionTranslationError]] when trying to register translation for protected function
*
* @example
* ```js
* // import your own plugin
* import { MyExamplePlugin } from './file_with_your_plugin';
*
* // register the plugin
* HyperFormula.registerFunctionPlugin(MyExamplePlugin);
* ```
*
* @category Static Methods
*/
static registerFunctionPlugin(plugin: FunctionPluginDefinition, translations?: FunctionTranslationsPackage): void;
/**
* Unregisters all functions defined in given plugin
*
* @param {FunctionPluginDefinition} plugin - plugin class
*
* @example
* ```js
* // get the class of a plugin
* const registeredPluginClass = HyperFormula.getFunctionPlugin('EXAMPLE');
*
* // unregister all functions defined in a plugin of ID 'EXAMPLE'
* HyperFormula.unregisterFunctionPlugin(registeredPluginClass);
* ```
*
* @category Static Methods
*/
static unregisterFunctionPlugin(plugin: FunctionPluginDefinition): void;
/**
* Registers a function with a given id if such exists in a plugin.
*
* @param {string} functionId - function id, e.g. 'SUMIF'
* @param {FunctionPluginDefinition} plugin - plugin class
* @param translations
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[FunctionPluginValidationError]] when function with a given id does not exists in plugin or plugin class definition is not consistent with metadata
* @throws [[ProtectedFunctionTranslationError]] when trying to register translation for protected function
*
* @example
* ```js
* // import your own plugin
* import { MyExamplePlugin } from './file_with_your_plugin';
*
* // register a function
* HyperFormula.registerFunction('EXAMPLE', MyExamplePlugin);
* ```
*
* @category Static Methods
*/
static registerFunction(functionId: string, plugin: FunctionPluginDefinition, translations?: FunctionTranslationsPackage): void;
/**
* Unregisters a function with a given id
*
* @param {string} functionId - function id, e.g. 'SUMIF'
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* // import your own plugin
* import { MyExamplePlugin } from './file_with_your_plugin';
*
* // register a function
* HyperFormula.registerFunction('EXAMPLE', MyExamplePlugin);
*
* // unregister a function
* HyperFormula.unregisterFunction('EXAMPLE');
* ```
*
* @category Static Methods
*/
static unregisterFunction(functionId: string): void;
/**
* Clears function registry
*
* @example
* ```js
* HyperFormula.unregisterAllFunctions();
* ```
*
* @category Static Methods
*/
static unregisterAllFunctions(): void;
/**
* Returns translated names of all registered functions for a given language
*
* @param {string} code - language code
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* // return a list of function names registered for enGB
* const allNames = HyperFormula.getRegisteredFunctionNames('enGB');
* ```
*
* @category Static Methods
*/
static getRegisteredFunctionNames(code: string): string[];
/**
* Returns class of a plugin used by function with given id
*
* @param {string} functionId - id of a function, e.g. 'SUMIF'
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* // import your own plugin
* import { MyExamplePlugin } from './file_with_your_plugin';
*
* // register a plugin
* HyperFormula.registerFunctionPlugin(MyExamplePlugin);
*
* // return the class of a given plugin
* const myFunctionClass = HyperFormula.getFunctionPlugin('EXAMPLE');
* ```
*
* @category Static Methods
*/
static getFunctionPlugin(functionId: string): FunctionPluginDefinition | undefined;
/**
* Returns classes of all plugins registered in this instance of HyperFormula
*
* @example
* ```js
* // return classes of all plugins
* const allClasses = HyperFormula.getAllFunctionPlugins();
* ```
*
* @category Static Methods
*/
static getAllFunctionPlugins(): FunctionPluginDefinition[];
private readonly _emitter;
private _evaluationSuspended;
protected constructor(_config: Config, _stats: Statistics, _dependencyGraph: DependencyGraph, _columnSearch: ColumnSearchStrategy, _parser: ParserWithCaching, _unparser: Unparser, _cellContentParser: CellContentParser, _evaluator: Evaluator, _lazilyTransformingAstService: LazilyTransformingAstService, _crudOperations: CrudOperations, _exporter: Exporter, _namedExpressions: NamedExpressions, _serialization: Serialization, _functionRegistry: FunctionRegistry);
/**
* Returns the cell value of a given address.
* Applies rounding and post-processing.
*
* @param {SimpleCellAddress} cellAddress - cell coordinates
*
* @throws [[ExpectedValueOfTypeError]] when cellAddress is of incorrect type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[EvaluationSuspendedError]] when the evaluation is suspended
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['=SUM(1,2,3)', '2'],
* ]);
*
* // get value of A1 cell, should be '6'
* const A1Value = hfInstance.getCellValue({ sheet: 0, col: 0, row: 0 });
*
* // get value of B1 cell, should be '2'
* const B1Value = hfInstance.getCellValue({ sheet: 0, col: 1, row: 0 });
* ```
*
* @category Cells
*/
getCellValue(cellAddress: SimpleCellAddress): CellValue;
private ensureEvaluationIsNotSuspended;
/**
* Returns a normalized formula string from the cell of a given address or `undefined` for an address that does not exist and empty values.
*
* @param {SimpleCellAddress} cellAddress - cell coordinates
*
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[ExpectedValueOfTypeError]] when cellAddress is of incorrect type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['=SUM(1,2,3)', '0'],
* ]);
*
* // should return a normalized A1 cell formula: '=SUM(1,2,3)'
* const A1Formula = hfInstance.getCellFormula({ sheet: 0, col: 0, row: 0 });
*
* // should return a normalized B1 cell formula: 'undefined'
* const B1Formula = hfInstance.getCellFormula({ sheet: 0, col: 1, row: 0 });
* ```
*
* @category Cells
*/
getCellFormula(cellAddress: SimpleCellAddress): string | undefined;
/**
* Returns [[RawCellContent]] with a serialized content of the cell of a given address: either a cell formula, an explicit value, or an error.
*
* @param {SimpleCellAddress} cellAddress - cell coordinates
*
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[EvaluationSuspendedError]] when the evaluation is suspended
* @throws [[ExpectedValueOfTypeError]] when cellAddress is of incorrect type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['=SUM(1,2,3)', '0'],
* ]);
*
* // should return serialized content of A1 cell: '=SUM(1,2,3)'
* const cellA1Serialized = hfInstance.getCellSerialized({ sheet: 0, col: 0, row: 0 });
*
* // should return serialized content of B1 cell: '0'
* const cellB1Serialized = hfInstance.getCellSerialized({ sheet: 0, col: 1, row: 0 });
* ```
*
* @category Cells
*/
getCellSerialized(cellAddress: SimpleCellAddress): RawCellContent;
/**
* Returns an array of arrays of [[CellValue]] with values of all cells from [[Sheet]].
* Applies rounding and post-processing.
*
* @param {number} sheetId - sheet ID number
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[EvaluationSuspendedError]] when the evaluation is suspended
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['0', '=SUM(1,2,3)', '=A1'],
* ['1', '=TEXT(A2, "0.0%")', '=C1'],
* ['2', '=SUM(A1:C1)', '=C1'],
* ]);
*
* // should return all values of a sheet: [[0, 6, 0], [1, '1.0%', 0], [2, 6, 0]]
* const sheetValues = hfInstance.getSheetValues(0);
* ```
*
* @category Sheets
*/
getSheetValues(sheetId: number): CellValue[][];
/**
* Returns an array with normalized formula strings from [[Sheet]] or `undefined` for a cells that have no value.
*
* @param {SimpleCellAddress} sheetId - sheet ID number
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['0', '=SUM(1,2,3)', '=A1'],
* ['1', '=TEXT(A2, "0.0%")', '=C1'],
* ['2', '=SUM(A1:C1)', '=C1'],
* ]);
*
* // should return all formulas of a sheet:
* // [
* // [undefined, '=SUM(1,2,3)', '=A1'],
* // [undefined, '=TEXT(A2, "0.0%")', '=C1'],
* // [undefined, '=SUM(A1:C1)', '=C1'],
* // ];
* const sheetFormulas = hfInstance.getSheetFormulas(0);
* ```
*
* @category Sheets
*/
getSheetFormulas(sheetId: number): (string | undefined)[][];
/**
* Returns an array of arrays of [[RawCellContent]] with serialized content of cells from [[Sheet]], either a cell formula or an explicit value.
*
* @param {SimpleCellAddress} sheetId - sheet ID number
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[EvaluationSuspendedError]] when the evaluation is suspended
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['0', '=SUM(1,2,3)', '=A1'],
* ['1', '=TEXT(A2, "0.0%")', '=C1'],
* ['2', '=SUM(A1:C1)', '=C1'],
* ]);
*
* // should return:
* // [
* // ['0', '=SUM(1,2,3)', '=A1'],
* // ['1', '=TEXT(A2, "0.0%")', '=C1'],
* // ['2', '=SUM(A1:C1)', '=C1'],
* // ];
* const serializedContent = hfInstance.getSheetSerialized(0);
* ```
*
* @category Sheets
*/
getSheetSerialized(sheetId: number): RawCellContent[][];
/**
* Returns a map containing dimensions of all sheets for the engine instance represented as a key-value pairs where keys are sheet IDs and dimensions are returned as numbers, width and height respectively.
*
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromSheets({
* Sheet1: [
* ['1', '2', '=Sheet2!$A1'],
* ],
* Sheet2: [
* ['3'],
* ['4'],
* ],
* });
*
* // should return the dimensions of all sheets:
* // { Sheet1: { width: 3, height: 1 }, Sheet2: { width: 1, height: 2 } }
* const allSheetsDimensions = hfInstance.getAllSheetsDimensions();
* ```
*
* @category Sheets
*/
getAllSheetsDimensions(): Record<string, SheetDimensions>;
/**
* Returns dimensions of a specified sheet.
* The sheet dimensions is represented with numbers: width and height.
*
* @param {number} sheetId - sheet ID number
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2', '=Sheet2!$A1'],
* ]);
*
* // should return provided sheet's dimensions: { width: 3, height: 1 }
* const sheetDimensions = hfInstance.getSheetDimensions(0);
* ```
*
* @category Sheets
*/
getSheetDimensions(sheetId: number): SheetDimensions;
/**
* Returns values of all sheets in a form of an object which property keys are strings and values are arrays of arrays of [[CellValue]].
*
* @throws [[EvaluationSuspendedError]] when the evaluation is suspended
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '=A1+10', '3'],
* ]);
*
* // should return all sheets values: { Sheet1: [ [ 1, 11, 3 ] ] }
* const allSheetsValues = hfInstance.getAllSheetsValues();
* ```
*
* @category Sheets
*/
getAllSheetsValues(): Record<string, CellValue[][]>;
/**
* Returns formulas of all sheets in a form of an object which property keys are strings and values are arrays of arrays of strings or possibly `undefined` when the call does not contain a formula.
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2', '=A1+10'],
* ]);
*
* // should return only formulas: { Sheet1: [ [ undefined, undefined, '=A1+10' ] ] }
* const allSheetsFormulas = hfInstance.getAllSheetsFormulas();
* ```
* @category Sheets
*/
getAllSheetsFormulas(): Record<string, (string | undefined)[][]>;
/**
* Returns formulas or values of all sheets in a form of an object which property keys are strings and values are arrays of arrays of [[RawCellContent]].
*
* @throws [[EvaluationSuspendedError]] when the evaluation is suspended
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2', '=A1+10'],
* ]);
*
* // should return all sheets serialized content: { Sheet1: [ [ 1, 2, '=A1+10' ] ] }
* const allSheetsSerialized = hfInstance.getAllSheetsSerialized();
* ```
*
* @category Sheets
*/
getAllSheetsSerialized(): Record<string, RawCellContent[][]>;
/**
* Updates the config with given new metadata.
*
* @param {Partial<ConfigParams>} newParams configuration options to be updated or added
*
* @throws [[ExpectedValueOfTypeError]] when some parameters of config are of wrong type (e.g. currencySymbol)
* @throws [[ConfigValueEmpty]] when some parameters of config are of invalid value (e.g. currencySymbol)
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2'],
* ]);
*
* // add a config param, for example maxColumns,
* // you can check the configuration with getConfig method
* hfInstance.updateConfig({ maxColumns: 1000 });
* ```
*
* @category Instance
*/
updateConfig(newParams: Partial<ConfigParams>): void;
/**
* Returns current configuration of the engine instance.
*
* @example
* ```js
* // should return all config metadata including default and those which were added
* const hfConfig = hfInstance.getConfig();
* ```
*
* @category Instance
*/
getConfig(): ConfigParams;
/**
* Serializes and deserializes whole engine, effectively reloading it.
*
* @example
* ```js
* hfInstance.rebuildAndRecalculate();
* ```
*
* @category Instance
*/
rebuildAndRecalculate(): void;
/**
* Returns a snapshot of computation time statistics.
* It returns a map with key-value pairs where keys are enums for stat type and time (number).
*
* @internal
*
* @category Instance
*/
getStats(): Map<StatType, number>;
/**
* Undo the previous operation.
*
* Note that this method may trigger dependency graph recalculation.
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[NoOperationToUndoError]] when there is no operation running that can be undone
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2'],
* ['3', ''],
* ]);
*
* // perform CRUD operation, for example remove the second row
* hfInstance.removeRows(0, [1, 1]);
*
* // do an undo, it should return the changes
* const changes = hfInstance.undo();
* ```
*
* @category Undo and Redo
*/
undo(): ExportedChange[];
/**
* Re-do recently undone operation.
*
* Note that this method may trigger dependency graph recalculation.
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[NoOperationToRedoError]] when there is no operation running that can be re-done
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1'],
* ['2'],
* ['3'],
* ]);
*
* // perform CRUD operation, for example remove the second row
* hfInstance.removeRows(0, [1, 1]);
*
* // do an undo, it should return prvious values: [['1'], ['2'], ['3']]
* hfInstance.undo();
*
* // do a redo, it should return the values after removing the second row: [['1'], ['3']]
* const changes = hfInstance.redo();
* ```
*
* @category Undo and Redo
*/
redo(): ExportedChange[];
/**
* Checks if there is at least one operation that can be undone.
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1'],
* ['2'],
* ['3'],
* ]);
*
* // perform CRUD operation, for example remove the second row
* hfInstance.removeRows(0, [1, 1]);
*
* // should return 'true', it is possible to undo last operation
* // which is removing rows in this example
* const isSomethingToUndo = hfInstance.isThereSomethingToUndo();
* ```
*
* @category Undo and Redo
*/
isThereSomethingToUndo(): boolean;
/**
* Checks if there is at least one operation that can be re-done.
*
* @example
* ```js
* hfInstance.undo();
*
* // when there is an action to redo, this returns 'true'
* const isSomethingToRedo = hfInstance.isThereSomethingToRedo();
* ```
*
* @category Undo and Redo
*/
isThereSomethingToRedo(): boolean;
/**
* Returns information whether it is possible to change the content in a rectangular area bounded by the box.
* If returns `true`, doing [[setCellContents]] operation won't throw any errors.
* Returns `false` if the address is invalid or the sheet does not exist.
*
* @param {SimpleCellAddress | SimpleCellRange} address - single cell or block of cells to check
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[SheetsNotEqual]] if range provided has distinct sheet numbers for start and end
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2'],
* ]);
*
* // top left corner
* const address1 = { col: 0, row: 0, sheet: 0 };
* // bottom right corner
* const address2 = { col: 1, row: 0, sheet: 0 };
*
* // should return 'true' for this example, it is possible to set content of
* // width 2, height 1 in the first row and column of sheet 0
* const isSettable = hfInstance.isItPossibleToSetCellContents({ start: address1, end: address2 });
* ```
*
* @category Cells
*/
isItPossibleToSetCellContents(address: SimpleCellAddress | SimpleCellRange): boolean;
/**
* Sets the content for a block of cells of a given coordinates.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {SimpleCellAddress} topLeftCornerAddress - top left corner of block of cells
* @param {(RawCellContent[][]|RawCellContent)} cellContents - array with content
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[InvalidArgumentsError]] when the value is not an array of arrays or a raw cell value
* @throws [[SheetSizeLimitExceededError]] when performing this operation would result in sheet size limits exceeding
* @throws [[ExpectedValueOfTypeError]] if topLeftCornerAddress argument is of wrong type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2', '=A1'],
* ]);
*
* // should set the content, returns:
* // [{
* // address: { sheet: 0, col: 3, row: 0 },
* // newValue: 2,
* // }]
* const changes = hfInstance.setCellContents({ col: 3, row: 0, sheet: 0 }, [['=B1']]);
* ```
*
* @category Cells
*/
setCellContents(topLeftCornerAddress: SimpleCellAddress, cellContents: RawCellContent[][] | RawCellContent): ExportedChange[];
/**
* Reorders rows of a sheet according to a source-target mapping.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {number} sheetId - ID of a sheet to operate on
* @param {[number, number][]} rowMapping - array mapping original positions to final positions of rows
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[InvalidArgumentsError]] when rowMapping does not define correct row permutation for some subset of rows of the given sheet
* @throws [[SourceLocationHasArrayError]] when the selected position has array inside
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1],
* [2],
* [4, 5],
* ]);
*
* // should set swap rows 0 and 2 in place, returns:
* // [{
* // address: { sheet: 0, col: 0, row: 2 },
* // newValue: 1,
* // },
* // {
* // address: { sheet: 0, col: 1, row: 2 },
* // newValue: null,
* // },
* // {
* // address: { sheet: 0, col: 0, row: 0 },
* // newValue: 4,
* // },
* // {
* // address: { sheet: 0, col: 1, row: 0 },
* // newValue: 5,
* // }]
* const changes = hfInstance.swapRowIndexes(0, [[0,2],[2,0]]);
* ```
*
* @category Rows
*/
swapRowIndexes(sheetId: number, rowMapping: [number, number][]): ExportedChange[];
/**
* Checks if it is possible to reorder rows of a sheet according to a source-target mapping.
*
* @param {number} sheetId - ID of a sheet to operate on
* @param {[number, number][]} rowMapping - array mapping original positions to final positions of rows
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1],
* [2],
* [4, 5],
* ]);
*
* // returns true
* const isSwappable = hfInstance.isItPossibleToSwapRowIndexes(0, [[0,2],[2,0]]);
*
* // returns false
* const isSwappable = hfInstance.isItPossibleToSwapRowIndexes(0, [[0,1]]);
* ```
*
* @category Rows
*/
isItPossibleToSwapRowIndexes(sheetId: number, rowMapping: [number, number][]): boolean;
/**
* Reorders rows of a sheet according to a permutation.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {number} sheetId - ID of a sheet to operate on
* @param {number[]} newRowOrder - permutation of rows
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[InvalidArgumentsError]] when rowMapping does not define correct row permutation for some subset of rows of the given sheet
* @throws [[SourceLocationHasArrayError]] when the selected position has array inside
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1],
* [2],
* [4, 5],
* ]);
* // rows 0 and 2 swap places
*
* // returns:
* // [{
* // address: { sheet: 0, col: 0, row: 2 },
* // newValue: 1,
* // },
* // {
* // address: { sheet: 0, col: 1, row: 2 },
* // newValue: null,
* // },
* // {
* // address: { sheet: 0, col: 0, row: 0 },
* // newValue: 4,
* // },
* // {
* // address: { sheet: 0, col: 1, row: 0 },
* // newValue: 5,
* // }]
* const changes = hfInstance.setRowOrder(0, [2, 1, 0]);
* ```
*
* @category Rows
*/
setRowOrder(sheetId: number, newRowOrder: number[]): ExportedChange[];
/**
* Checks if it is possible to reorder rows of a sheet according to a permutation.
*
* @param {number} sheetId - ID of a sheet to operate on
* @param {number[]} newRowOrder - permutation of rows
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1],
* [2],
* [4, 5],
* ]);
*
* // returns true
* hfInstance.isItPossibleToSetRowOrder(0, [2, 1, 0]);
*
* // returns false
* hfInstance.isItPossibleToSetRowOrder(0, [2]);
* ```
*
* @category Rows
*/
isItPossibleToSetRowOrder(sheetId: number, newRowOrder: number[]): boolean;
/**
* Reorders columns of a sheet according to a source-target mapping.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {number} sheetId - ID of a sheet to operate on
* @param {[number, number][]} columnMapping - array mapping original positions to final positions of columns
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[InvalidArgumentsError]] when columnMapping does not define correct column permutation for some subset of columns of the given sheet
* @throws [[SourceLocationHasArrayError]] when the selected position has array inside
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1, 2, 4],
* [5]
* ]);
*
* // should set swap columns 0 and 2 in place, returns:
* // [{
* // address: { sheet: 0, col: 2, row: 0 },
* // newValue: 1,
* // },
* // {
* // address: { sheet: 0, col: 2, row: 1 },
* // newValue: 5,
* // },
* // {
* // address: { sheet: 0, col: 0, row: 0 },
* // newValue: 4,
* // },
* // {
* // address: { sheet: 0, col: 0, row: 1 },
* // newValue: null,
* // }]
* const changes = hfInstance.swapColumnIndexes(0, [[0,2],[2,0]]);
* ```
*
* @category Columns
*/
swapColumnIndexes(sheetId: number, columnMapping: [number, number][]): ExportedChange[];
/**
* Checks if it is possible to reorder columns of a sheet according to a source-target mapping.
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1, 2, 4],
* [5]
* ]);
*
* // returns true
* hfInstance.isItPossibleToSwapColumnIndexes(0, [[0,2],[2,0]]);
*
* // returns false
* hfInstance.isItPossibleToSwapColumnIndexes(0, [[0,1]]);
* ```
*
* @category Columns
*/
isItPossibleToSwapColumnIndexes(sheetId: number, columnMapping: [number, number][]): boolean;
/**
* Reorders columns of a sheet according to a permutation.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {number} sheetId - ID of a sheet to operate on
* @param {number[]} newColumnOrder - permutation of columns
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[InvalidArgumentsError]] when columnMapping does not define correct column permutation for some subset of columns of the given sheet
* @throws [[SourceLocationHasArrayError]] when the selected position has array inside
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1, 2, 4],
* [5]
* ]);
* // columns 0 and 2 swap places
*
* // returns:
* // [{
* // address: { sheet: 0, col: 2, row: 0 },
* // newValue: 1,
* // },
* // {
* // address: { sheet: 0, col: 2, row: 1 },
* // newValue: 5,
* // },
* // {
* // address: { sheet: 0, col: 0, row: 0 },
* // newValue: 4,
* // },
* // {
* // address: { sheet: 0, col: 0, row: 1 },
* // newValue: null,
* // }]
* const changes = hfInstance.setColumnOrder(0, [2, 1, 0]]);
* ```
*
* @category Columns
*/
setColumnOrder(sheetId: number, newColumnOrder: number[]): ExportedChange[];
/**
* Checks if it possible to reorder columns of a sheet according to a permutation.
*
* @param {number} sheetId - ID of a sheet to operate on
* @param {number[]} newColumnOrder - permutation of columns
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* [1, 2, 4],
* [5]
* ]);
*
* // returns true
* hfInstance.isItPossibleToSetColumnOrder(0, [2, 1, 0]]);
*
* // returns false
* hfInstance.isItPossibleToSetColumnOrder(0, [1]]);
* ```
*
* @category Columns
*/
isItPossibleToSetColumnOrder(sheetId: number, newColumnOrder: number[]): boolean;
/**
* Returns information whether it is possible to add rows into a specified position in a given sheet.
* Checks against particular rules to ascertain that addRows can be called.
* If returns `true`, doing [[addRows]] operation won't throw any errors.
* Returns `false` if adding rows would exceed the sheet size limit or given arguments are invalid.
*
* @param {number} sheetId - sheet ID in which rows will be added
* @param {ColumnRowIndex[]} indexes - non-contiguous indexes with format [row, amount], where row is a row number above which the rows will be added
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2', '3'],
* ]);
*
* // should return 'true' for this example,
* // it is possible to add one row in the second row of sheet 0
* const isAddable = hfInstance.isItPossibleToAddRows(0, [1, 1]);
* ```
*
* @category Rows
*/
isItPossibleToAddRows(sheetId: number, ...indexes: ColumnRowIndex[]): boolean;
/**
* Adds multiple rows into a specified position in a given sheet.
* Does nothing if rows are outside of effective sheet size.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {number} sheetId - sheet ID in which rows will be added
* @param {ColumnRowIndex[]} indexes - non-contiguous indexes with format [row, amount], where row is a row number above which the rows will be added
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[SheetSizeLimitExceededError]] when performing this operation would result in sheet size limits exceeding
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1'],
* ['2'],
* ]);
*
* // should return a list of cells which values changed after the operation,
* // their absolute addresses and new values
* const changes = hfInstance.addRows(0, [0, 1]);
* ```
*
* @category Rows
*/
addRows(sheetId: number, ...indexes: ColumnRowIndex[]): ExportedChange[];
/**
* Returns information whether it is possible to remove rows from a specified position in a given sheet.
* Checks against particular rules to ascertain that removeRows can be called.
* If returns `true`, doing [[removeRows]] operation won't throw any errors.
* Returns `false` if given arguments are invalid.
*
* @param {number} sheetId - sheet ID from which rows will be removed
* @param {ColumnRowIndex[]} indexes - non-contiguous indexes with format: [row, amount]
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1'],
* ['2'],
* ]);
*
* // should return 'true' for this example
* // it is possible to remove one row from row 1 of sheet 0
* const isRemovable = hfInstance.isItPossibleToRemoveRows(0, [1, 1]);
* ```
*
* @category Rows
*/
isItPossibleToRemoveRows(sheetId: number, ...indexes: ColumnRowIndex[]): boolean;
/**
* Removes multiple rows from a specified position in a given sheet.
* Does nothing if rows are outside of the effective sheet size.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {number} sheetId - sheet ID from which rows will be removed
* @param {ColumnRowIndex[]} indexes - non-contiguous indexes with format: [row, amount]
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[InvalidArgumentsError]] when the given arguments are invalid
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1'],
* ['2'],
* ]);
*
* // should return: [{ sheet: 0, col: 1, row: 2, value: null }] for this example
* const changes = hfInstance.removeRows(0, [1, 1]);
* ```
*
* @category Rows
*/
removeRows(sheetId: number, ...indexes: ColumnRowIndex[]): ExportedChange[];
/**
* Returns information whether it is possible to add columns into a specified position in a given sheet.
* Checks against particular rules to ascertain that addColumns can be called.
* If returns `true`, doing [[addColumns]] operation won't throw any errors.
* Returns `false` if adding columns would exceed the sheet size limit or given arguments are invalid.
*
* @param {number} sheetId - sheet ID in which columns will be added
* @param {ColumnRowIndex[]} indexes - non-contiguous indexes with format: [column, amount], where column is a column number from which new columns will be added
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
*
* @example
* ```js
* const hfInstance = HyperFormula.buildFromArray([
* ['1', '2'],
* ]);
*
* // should return 'true' for this example,
* // it is possible to add 1 column in sheet 0, at column 1
* const isAddable = hfInstance.isItPossibleToAddColumns(0, [1, 1]);
* ```
*
* @category Columns
*/
isItPossibleToAddColumns(sheetId: number, ...indexes: ColumnRowIndex[]): boolean;
/**
* Adds multiple columns into a specified position in a given sheet.
* Does nothing if the columns are outside of the effective sheet size.
*
* Note that this method may trigger dependency graph recalculation.
*
* @param {number} sheetId - sheet ID in which columns will be added
* @param {ColumnRowIndex[]} indexes - non-contiguous indexes with format: [column, amount], where column is a column number from which new columns will be added
*
* @fires [[valuesUpdated]] if recalculation was triggered by this change
*
* @throws [[ExpectedValueOfTypeError]] if any of its basic type argument is of wrong type
* @throws [[NoSheetWithIdError]] when the given sheet ID does not exist
* @throws [[InvalidArgumentsError]] when the given arguments are invalid
* @throws [[SheetSizeLimitExceededError]] when performing this operation would result in sheet size limits exceeding
*