HyperFormula

Class

This is a class for creating HyperFormula instance, all the following public methods are 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 known 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.

Static Properties

buildDate

Static

▪ buildDate: string = '30/10/2026 06:19:31'

Defined in hyperformula/src/HyperFormula.ts:108

Latest build date.

---

languages

Static

▪ languages: Record‹string, RawTranslationPackage›

Defined in hyperformula/src/HyperFormula.ts:124

When using the UMD build, this property contains all available languages to use with the registerLanguage method.

For more information, see the Localizing functions guide.

---

releaseDate

Static

▪ releaseDate: string = '09/10/2026'

Defined in hyperformula/src/HyperFormula.ts:115

A release date.

---

version

Static

▪ version: string = '3.5.0'

Defined in hyperformula/src/HyperFormula.ts:101

Version of the HyperFormula.

Static Accessors

defaultConfig

Static

• get defaultConfig(): ConfigParams

Defined in hyperformula/src/HyperFormula.ts:163

Returns all of HyperFormula’s default configuration options.

example

// returns all default configuration options
const defaultConfig = HyperFormula.defaultConfig;

category Static Accessors

Returns: ConfigParams

Factories

buildEmpty

Static

▸ buildEmpty(configInput: Partial‹ConfigParams›, namedExpressions: SerializedNamedExpression[]): HyperFormula

Defined in hyperformula/src/HyperFormula.ts:360

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.

throws LicenseCapabilityMissingError if namedExpressions is non-empty and the license key is missing or invalid, has expired and blocks evaluation, or does not grant the NamedExpressions feature

example

const namedExpressions = [
 {
   name: 'theUltimateQuestionOfLife',
   expression: '=42',
 },
];

// build with no initial data and with optional config parameter maxColumns
const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3', maxColumns: 1000 }, namedExpressions);

Parameters:

Name	Type	Default	Description
configInput	Partial‹ConfigParams›	{}	engine configuration
namedExpressions	SerializedNamedExpression[]	[]	starting named expressions

Returns: HyperFormula

---

buildFromArray

Static

▸ buildFromArray(sheet: Sheet, configInput: Partial‹ConfigParams›, namedExpressions: SerializedNamedExpression[]): HyperFormula

Defined in hyperformula/src/HyperFormula.ts:283

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.

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

throws LicenseCapabilityMissingError if namedExpressions is non-empty and the license key is missing or invalid, has expired and blocks evaluation, or does not grant the NamedExpressions feature

example

// data represented as an array
const sheetData = [
 ['0', '=SUM(1, 2, 3)', '52'],
 ['=SUM(A1:C1)', '', '=A1'],
 ['2', '=SUM(A1:C1)', '=theUltimateQuestionOfLife'],
];

const namedExpressions = [
 {
   name: 'theUltimateQuestionOfLife',
   expression: '=42',
 },
];

// method with optional config parameter maxColumns
const hfInstance = HyperFormula.buildFromArray(sheetData, { licenseKey: 'gpl-v3', maxColumns: 1000 }, namedExpressions);

Parameters:

Name	Type	Default	Description
sheet	Sheet	-	two-dimensional array representation of sheet
configInput	Partial‹ConfigParams›	{}	engine configuration
namedExpressions	SerializedNamedExpression[]	[]	starting named expressions

Returns: HyperFormula

---

buildFromSheets

Static

▸ buildFromSheets(sheets: Sheets, configInput: Partial‹ConfigParams›, namedExpressions: SerializedNamedExpression[]): HyperFormula

Defined in hyperformula/src/HyperFormula.ts:331

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.

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

throws LicenseCapabilityMissingError if namedExpressions is non-empty and the license key is missing or invalid, has expired and blocks evaluation, or does not grant the NamedExpressions feature

example

// 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', '=theUltimateQuestionOfLife'],
  ],
};

const namedExpressions = [
 {
   name: 'theUltimateQuestionOfLife',
   expression: '=42',
 },
];

// method with optional config parameter useColumnIndex
const hfInstance = HyperFormula.buildFromSheets(sheetData, { licenseKey: 'gpl-v3', useColumnIndex: true }, namedExpressions);

Parameters:

Name	Type	Default	Description
sheets	Sheets	-	object with sheets definition
configInput	Partial‹ConfigParams›	{}	engine configuration
namedExpressions	SerializedNamedExpression[]	[]	starting named expressions

Returns: HyperFormula

---

Instance

destroy

▸ destroy(): void

Defined in hyperformula/src/HyperFormula.ts:4987

Destroys instance of HyperFormula.

example

// destroys the instance
hfInstance.destroy();

Returns: void

---

getConfig

▸ getConfig(): ConfigParams

Defined in hyperformula/src/HyperFormula.ts:1234

Returns current configuration of the engine instance.

For more information, see the Configuration options guide.

example

// should return all config metadata including default and those which were added
const hfConfig = hfInstance.getConfig();

Returns: ConfigParams

---

rebuildAndRecalculate

▸ rebuildAndRecalculate(): void

Defined in hyperformula/src/HyperFormula.ts:1248

Rebuilds the HyperFormula instance preserving the current sheets data.

example

hfInstance.rebuildAndRecalculate();

Returns: void

---

updateConfig

▸ updateConfig(newParams: Partial‹ConfigParams›): void

Defined in hyperformula/src/HyperFormula.ts:1211

Updates the config with given new metadata. It is an expensive operation, as it might trigger rebuilding the engine and recalculation of all formulas.

For more information, see the Configuration options guide.

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

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// add a config param, for example maxColumns,
// you can check the configuration with getConfig method
hfInstance.updateConfig({ maxColumns: 1000 });

Parameters:

Name	Type	Description
newParams	Partial‹ConfigParams›	configuration options to be updated or added

Returns: void

---

Sheets

addSheet

▸ addSheet(sheetName?: undefined | string): string

Defined in hyperformula/src/HyperFormula.ts:2924

Adds a new sheet to the HyperFormula instance. Returns given or autogenerated name of a new sheet.

Note that this method may trigger dependency graph recalculation.

fires sheetAdded after the sheet was added

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws SheetNameAlreadyTakenError when sheet with a given name already exists

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return 'MySheet3'
const nameProvided = hfInstance.addSheet('MySheet3');

// should return autogenerated 'Sheet4'
// because no name was provided and 3 other ones already exist
const generatedName = hfInstance.addSheet();

Parameters:

Name	Type
sheetName?	undefined | string

Returns: string

---

clearSheet

▸ clearSheet(sheetId: number): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:3084

Clears the sheet content. Double-checks if the sheet exists.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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 LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['=SUM(MySheet2!A1:A2)'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return a list of cells which values changed after the operation,
// their absolute addresses and new values, in this example it will return:
// [{
//   address: { sheet: 0, col: 0, row: 0 },
//   newValue: 0,
// }]
const changes = hfInstance.clearSheet(0);

Parameters:

Name	Type	Description
sheetId	number	sheet ID.

Returns: ExportedChange[]

---

countSheets

▸ countSheets(): number

Defined in hyperformula/src/HyperFormula.ts:3780

Returns the number of existing sheets.

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// should return the number of sheets which is '1'
const sheetsCount = hfInstance.countSheets();

Returns: number

---

doesSheetExist

▸ doesSheetExist(sheetName: string): boolean

Defined in hyperformula/src/HyperFormula.ts:3499

Returns true whether sheet with a given name exists. The method accepts sheet name to be checked.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
  MySheet1: [ ['1'] ],
  MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return 'true' since 'MySheet1' exists
const sheetExist = hfInstance.doesSheetExist('MySheet1');

Parameters:

Name	Type	Description
sheetName	string	name of the sheet, case-insensitive.

Returns: boolean

---

getAllSheetsDimensions

▸ getAllSheetsDimensions(): Record‹string, SheetDimensions›

Defined in hyperformula/src/HyperFormula.ts:1087

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

const hfInstance = HyperFormula.buildFromSheets({
  Sheet1: [
   ['1', '2', '=Sheet2!$A1'],
  ],
  Sheet2: [
   ['3'],
   ['4'],
  ],
}, { licenseKey: 'gpl-v3' });

// should return the dimensions of all sheets:
// { Sheet1: { width: 3, height: 1 }, Sheet2: { width: 1, height: 2 } }
const allSheetsDimensions = hfInstance.getAllSheetsDimensions();

Returns: Record‹string, SheetDimensions›

---

getAllSheetsFormulas

▸ getAllSheetsFormulas(): Record‹string, (string | undefined)[][]›

Defined in hyperformula/src/HyperFormula.ts:1158

Returns formulas of all sheets in a form of an object which property keys are strings and values are 2D arrays of strings or possibly undefined when the call does not contain a formula.

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2', '=A1+10'],
], { licenseKey: 'gpl-v3' });

// should return only formulas: { Sheet1: [ [ undefined, undefined, '=A1+10' ] ] }
const allSheetsFormulas = hfInstance.getAllSheetsFormulas();

Returns: Record‹string, (string | undefined)[][]›

---

getAllSheetsSerialized

▸ getAllSheetsSerialized(): Record‹string, RawCellContent[][]›

Defined in hyperformula/src/HyperFormula.ts:1183

Returns formulas or values of all sheets in a form of an object which property keys are strings and values are 2D arrays of RawCellContent.

Each non-formula cell is serialized to the exact value it was set with, preserving its type. For example, a cell set with the string '1' is serialized as the string '1', while a cell set with the number 1 is serialized as the number 1.

throws EvaluationSuspendedError when the evaluation is suspended

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', 2, '=A1+10'],
], { licenseKey: 'gpl-v3' });

// should return all sheets serialized content: { Sheet1: [ [ '1', 2, '=A1+10' ] ] }
// note: the string '1' stays a string and the number 2 stays a number
const allSheetsSerialized = hfInstance.getAllSheetsSerialized();

Returns: Record‹string, RawCellContent[][]›

---

getAllSheetsValues

▸ getAllSheetsValues(): Record‹string, CellValue[][]›

Defined in hyperformula/src/HyperFormula.ts:1139

Returns values of all sheets in a form of an object which property keys are strings and values are 2D arrays of CellValue.

throws EvaluationSuspendedError when the evaluation is suspended

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '=A1+10', '3'],
], { licenseKey: 'gpl-v3' });

// should return all sheets values: { Sheet1: [ [ 1, 11, 3 ] ] }
const allSheetsValues = hfInstance.getAllSheetsValues();

Returns: Record‹string, CellValue[][]›

---

getSheetDimensions

▸ getSheetDimensions(sheetId: number): SheetDimensions

Defined in hyperformula/src/HyperFormula.ts:1114

Returns dimensions of a specified sheet. The sheet dimensions is represented with numbers: width and height.

Note: Due to the memory optimizations, some of the empty bottom rows and rightmost columns are not counted to the dimensions.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NoSheetWithIdError when the given sheet ID does not exist

example

const hfInstance = HyperFormula.buildFromArray([
   ['1', '2', '=Sheet2!$A1'],
], { licenseKey: 'gpl-v3' });

// should return provided sheet's dimensions: { width: 3, height: 1 }
const sheetDimensions = hfInstance.getSheetDimensions(0);

Parameters:

Name	Type	Description
sheetId	number	sheet ID number

Returns: SheetDimensions

---

getSheetFormulas

▸ getSheetFormulas(sheetId: number): (string | undefined)[][]

Defined in hyperformula/src/HyperFormula.ts:1024

Returns an array with normalized formula strings from Sheet or undefined for a cells that have no value.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NoSheetWithIdError when the given sheet ID does not exist

example

const hfInstance = HyperFormula.buildFromArray([
 ['0', '=SUM(1, 2, 3)', '=A1'],
 ['1', '=TEXT(A2, "0.0%")', '=C1'],
 ['2', '=SUM(A1:C1)', '=C1'],
], { licenseKey: 'gpl-v3' });

// 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);

Parameters:

Name	Type	Description
sheetId	number	sheet ID number

Returns: (string | undefined)[][]

---

getSheetId

▸ getSheetId(sheetName: string): number | undefined

Defined in hyperformula/src/HyperFormula.ts:3474

Returns a unique sheet ID assigned to the sheet with a given name or undefined if the sheet does not exist.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
  MySheet1: [ ['1'] ],
  MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return '0' because 'MySheet1' is of ID '0'
const sheetID = hfInstance.getSheetId('MySheet1');

Parameters:

Name	Type	Description
sheetName	string	name of the sheet, for which we want to retrieve ID, case-insensitive.

Returns: number | undefined

---

getSheetName

▸ getSheetName(sheetId: number): string | undefined

Defined in hyperformula/src/HyperFormula.ts:3428

Returns a unique sheet name assigned to the sheet of a given ID or undefined if the there is no sheet with a given ID.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return 'MySheet2' as this sheet is the second one
const sheetName = hfInstance.getSheetName(1);

Parameters:

Name	Type	Description
sheetId	number	ID of the sheet, for which we want to retrieve name

Returns: string | undefined

---

getSheetNames

▸ getSheetNames(): string[]

Defined in hyperformula/src/HyperFormula.ts:3450

List all sheet names. Returns an array of sheet names as strings.

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return all sheets names: ['MySheet1', 'MySheet2']
const sheetNames = hfInstance.getSheetNames();

Returns: string[]

---

getSheetSerialized

▸ getSheetSerialized(sheetId: number): RawCellContent[][]

Defined in hyperformula/src/HyperFormula.ts:1057

Returns an array of arrays of RawCellContent with serialized content of cells from Sheet, either a cell formula or an explicit value.

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

const hfInstance = HyperFormula.buildFromArray([
 ['0', '=SUM(1, 2, 3)', '=A1'],
 ['1', '=TEXT(A2, "0.0%")', '=C1'],
 ['2', '=SUM(A1:C1)', '=C1'],
], { licenseKey: 'gpl-v3' });

// should return:
// [
//  ['0', '=SUM(1, 2, 3)', '=A1'],
//  ['1', '=TEXT(A2, "0.0%")', '=C1'],
//  ['2', '=SUM(A1:C1)', '=C1'],
// ];
const serializedContent = hfInstance.getSheetSerialized(0);

Parameters:

Name	Type	Description
sheetId	number	sheet ID number

Returns: RawCellContent[][]

---

getSheetValues

▸ getSheetValues(sheetId: number): CellValue[][]

Defined in hyperformula/src/HyperFormula.ts:991

Returns an array of arrays of CellValue with values of all cells from Sheet. Applies rounding and post-processing.

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

const hfInstance = HyperFormula.buildFromArray([
 ['0', '=SUM(1, 2, 3)', '=A1'],
 ['1', '=TEXT(A2, "0.0%")', '=C1'],
 ['2', '=SUM(A1:C1)', '=C1'],
], { licenseKey: 'gpl-v3' });

// should return all values of a sheet: [[0, 6, 0], [1, '1.0%', 0], [2, 6, 0]]
const sheetValues = hfInstance.getSheetValues(0);

Parameters:

Name	Type	Description
sheetId	number	sheet ID number

Returns: CellValue[][]

---

isItPossibleToAddSheet

▸ isItPossibleToAddSheet(sheetName: string): boolean

Defined in hyperformula/src/HyperFormula.ts:2881

Returns information whether it is possible to add a sheet to the engine. Checks against particular rules to ascertain that addSheet can be called. If returns true, doing addSheet operation won’t throw any errors, and it is possible to add sheet with provided name. Returns false if the chosen name is already used. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
  MySheet1: [ ['1'] ],
  MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return 'false' because 'MySheet2' already exists
const isAddable = hfInstance.isItPossibleToAddSheet('MySheet2');

Parameters:

Name	Type	Description
sheetName	string	sheet name, case-insensitive

Returns: boolean

---

isItPossibleToClearSheet

▸ isItPossibleToClearSheet(sheetId: number): boolean

Defined in hyperformula/src/HyperFormula.ts:3038

Returns information whether it is possible to clear a specified sheet. If returns true, doing clearSheet operation won’t throw any errors, provided sheet exists and its content can be cleared. Returns false otherwise Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return 'true' because 'MySheet2' exists and can be cleared
const isClearable = hfInstance.isItPossibleToClearSheet(1);

Parameters:

Name	Type	Description
sheetId	number	sheet ID.

Returns: boolean

---

isItPossibleToRemoveSheet

▸ isItPossibleToRemoveSheet(sheetId: number): boolean

Defined in hyperformula/src/HyperFormula.ts:2958

Returns information whether it is possible to remove sheet for the engine. Returns true if the provided sheet exists, and therefore it can be removed, doing removeSheet operation won’t throw any errors. Returns false otherwise Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return 'true' because sheet with ID 1 exists and is removable
const isRemovable = hfInstance.isItPossibleToRemoveSheet(1);

Parameters:

Name	Type	Description
sheetId	number	sheet ID.

Returns: boolean

---

isItPossibleToRenameSheet

▸ isItPossibleToRenameSheet(sheetId: number, newName: string): boolean

Defined in hyperformula/src/HyperFormula.ts:3808

Returns information whether it is possible to rename sheet. Returns true if the sheet with provided id exists and new name is available Returns false if sheet cannot be renamed Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
  MySheet1: [ ['1'] ],
  MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// returns true
hfInstance.isItPossibleToRenameSheet(0, 'MySheet0');

Parameters:

Name	Type	Description
sheetId	number	a sheet number
newName	string	a name of the sheet to be given

Returns: boolean

---

isItPossibleToReplaceSheetContent

▸ isItPossibleToReplaceSheetContent(sheetId: number, values: RawCellContent[][]): boolean

Defined in hyperformula/src/HyperFormula.ts:3116

Returns information whether it is possible to replace the sheet content. If returns true, doing setSheetContent operation won’t throw any errors, the provided sheet exists and then its content can be replaced. Returns false otherwise Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return 'true' because sheet of ID 0 exists
// and the provided content can be placed in this sheet
const isReplaceable = hfInstance.isItPossibleToReplaceSheetContent(0, [['50'], ['60']]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID.
values	RawCellContent[][]	array of new values

Returns: boolean

---

removeSheet

▸ removeSheet(sheetId: number): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:3005

Removes a sheet

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires sheetRemoved after the sheet was removed

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 LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['=SUM(MySheet2!A1:A2)'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return a list of cells which values changed after the operation,
// their absolute addresses and new values, in this example it will return:
// [{
//   address: { sheet: 0, col: 0, row: 0 },
//   newValue: { error: [CellError], value: '#REF!' },
// }]
const changes = hfInstance.removeSheet(1);

Parameters:

Name	Type	Description
sheetId	number	sheet ID.

Returns: ExportedChange[]

---

renameSheet

▸ renameSheet(sheetId: number, newName: string): void

Defined in hyperformula/src/HyperFormula.ts:3850

Renames a specified sheet.

Note that this method may trigger dependency graph recalculation.

fires sheetRenamed after the sheet was renamed

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NoSheetWithIdError when the given sheet ID does not exist

throws SheetNameAlreadyTakenError when the provided sheet name already exists

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromSheets({
  MySheet1: [ ['1'] ],
  MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// renames the sheet 'MySheet1'
hfInstance.renameSheet(0, 'MySheet0');

Parameters:

Name	Type	Description
sheetId	number	a sheet ID
newName	string	a name of the sheet to be given, if is the same as the old one the method does nothing

Returns: void

---

setSheetContent

▸ setSheetContent(sheetId: number, values: RawCellContent[][]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:3157

Replaces the sheet content with new values.

Returns an array of cells whose values changed as a result of this operation.

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 values argument is not an array of arrays

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// should return a list of cells which values changed after the operation,
// their absolute addresses and new values
const changes = hfInstance.setSheetContent(0, [['50'], ['60']]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID.
values	RawCellContent[][]	array of new values

Returns: ExportedChange[]

---

Ranges

getFillRangeData

▸ getFillRangeData(source: SimpleCellRange, target: SimpleCellRange, offsetsFromTarget: boolean): RawCellContent[][]

Defined in hyperformula/src/HyperFormula.ts:2836

Returns values to fill target range using source range, with properly extending the range using wrap-around heuristic.

throws EvaluationSuspendedError when the evaluation is suspended

throws ExpectedValueOfTypeError if source or target are of wrong type

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

example

const hfInstance = HyperFormula.buildFromArray([[1, '=A1'], ['=$A$1', '2']], { licenseKey: 'gpl-v3' });

// should return [['2', '=$A$1', '2'], ['=A3', 1, '=C3'], ['2', '=$A$1', '2']]
hfInstance.getFillRangeData( {start: {sheet: 0, row: 0, col: 0}, end: {sheet: 0, row: 1, col: 1}},
{start: {sheet: 0, row: 1, col: 1}, end: {sheet: 0, row: 3, col: 3}});

Parameters:

Name	Type	Default	Description
source	SimpleCellRange	-	of data
target	SimpleCellRange	-	range where data is intended to be put
offsetsFromTarget	boolean	false	if true, offsets are computed from target corner, otherwise from source corner

Returns: RawCellContent[][]

---

getRangeFormulas

▸ getRangeFormulas(source: SimpleCellRange): (string | undefined)[][]

Defined in hyperformula/src/HyperFormula.ts:2763

Returns cell formulas in given range.

throws ExpectedValueOfTypeError if source is of wrong type

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

throws NoSheetWithIdError when the given sheet ID does not exist

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(1, 2)', '2', '10'],
 ['5', '6', '7'],
 ['40', '30', '20'],
], { licenseKey: 'gpl-v3' });

// returns cell formulas of a given range only:
// [ [ '=SUM(1, 2)', undefined ], [ undefined, undefined ] ]
const rangeFormulas = hfInstance.getRangeFormulas({ start: { sheet: 0, col: 0, row: 0 }, end: { sheet: 0, col: 1, row: 1 } });

Parameters:

Name	Type	Description
source	SimpleCellRange	rectangular range

Returns: (string | undefined)[][]

---

getRangeSerialized

▸ getRangeSerialized(source: SimpleCellRange): RawCellContent[][]

Defined in hyperformula/src/HyperFormula.ts:2802

Returns serialized cells in given range.

Each non-formula cell is serialized to the exact value it was set with, preserving its type (e.g., a cell set with the string '2' is serialized as the string '2', while a cell set with the number 2 is serialized as the number 2).

throws ExpectedValueOfTypeError if source is of wrong type

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

throws NoSheetWithIdError when the given sheet ID does not exist

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(1, 2)', 2, 10],
 [5, 6, 7],
 [40, 30, 20],
], { licenseKey: 'gpl-v3' });

// should return serialized cell content for the given range:
// [ [ '=SUM(1, 2)', 2 ], [ 5, 6 ] ]
const rangeSerialized = hfInstance.getRangeSerialized({ start: { sheet: 0, col: 0, row: 0 }, end: { sheet: 0, col: 1, row: 1 } });

Parameters:

Name	Type	Description
source	SimpleCellRange	rectangular range

Returns: RawCellContent[][]

---

getRangeValues

▸ getRangeValues(source: SimpleCellRange): CellValue[][]

Defined in hyperformula/src/HyperFormula.ts:2727

Returns the cell content of a given range in a CellValue[][] format.

throws ExpectedValueOfTypeError if source is of wrong type

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

throws NoSheetWithIdError when the given sheet ID does not exist

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(1, 2)', '2', '10'],
 ['5', '6', '7'],
 ['40', '30', '20'],
], { licenseKey: 'gpl-v3' });

// returns calculated cells content: [ [ 3, 2 ], [ 5, 6 ] ]
const rangeValues = hfInstance.getRangeValues({ start: { sheet: 0, col: 0, row: 0 }, end: { sheet: 0, col: 1, row: 1 } });

Parameters:

Name	Type	Description
source	SimpleCellRange	rectangular range

Returns: CellValue[][]

---

Rows

addRows

▸ addRows(sheetId: number, …indexes: ColumnRowIndex[]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1927

Adds multiple rows into a specified position in a given sheet. Does nothing if rows are outside effective sheet size.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['1'],
 ['2'],
], { licenseKey: 'gpl-v3' });

// 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]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID in which rows will be added
...indexes	ColumnRowIndex[]	non-contiguous indexes with format [row, amount], where row is a row number above which the rows will be added

Returns: ExportedChange[]

---

isItPossibleToAddRows

▸ isItPossibleToAddRows(sheetId: number, …indexes: ColumnRowIndex[]): boolean

Defined in hyperformula/src/HyperFormula.ts:1881

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. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2', '3'],
], { licenseKey: 'gpl-v3' });

// 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]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID in which rows will be added
...indexes	ColumnRowIndex[]	non-contiguous indexes with format [row, amount], where row is a row number above which the rows will be added

Returns: boolean

---

isItPossibleToMoveRows

▸ isItPossibleToMoveRows(sheetId: number, startRow: number, numberOfRows: number, targetRow: number): boolean

Defined in hyperformula/src/HyperFormula.ts:2308

Returns information whether it is possible to move a particular number of rows to a specified position in a given sheet. Checks against particular rules to ascertain that moveRows can be called. If returns true, doing moveRows operation won’t throw any errors. Returns false if the operation might be disrupted and causes side effects by the fact that there is an array inside the selected rows, the target location includes an array or the provided address is invalid. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1'],
 ['2'],
], { licenseKey: 'gpl-v3' });

// should return 'true' for this example
// it is possible to move one row from row 0 into row 2
const isMovable = hfInstance.isItPossibleToMoveRows(0, 0, 1, 2);

Parameters:

Name	Type	Description
sheetId	number	a sheet number in which the operation will be performed
startRow	number	number of the first row to move
numberOfRows	number	number of rows to move
targetRow	number	row number before which rows will be moved

Returns: boolean

---

isItPossibleToRemoveRows

▸ isItPossibleToRemoveRows(sheetId: number, …indexes: ColumnRowIndex[]): boolean

Defined in hyperformula/src/HyperFormula.ts:1960

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. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1'],
 ['2'],
], { licenseKey: 'gpl-v3' });

// 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]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID from which rows will be removed
...indexes	ColumnRowIndex[]	non-contiguous indexes with format: [row, amount]

Returns: boolean

---

isItPossibleToSetRowOrder

▸ isItPossibleToSetRowOrder(sheetId: number, newRowOrder: number[]): boolean

Defined in hyperformula/src/HyperFormula.ts:1660

Checks if it is possible to reorder rows of a sheet according to a permutation. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

Parameter newRowOrder should have the form [ newPositionForRow0, newPositionForRow1, newPositionForRow2, ... ], i.e. the value at index i is the new position for the row that is currently at index i. See setRowOrder for details.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['A'],
 ['B'],
 ['C']
], { licenseKey: 'gpl-v3' });

// returns true
hfInstance.isItPossibleToSetRowOrder(0, [1, 2, 0]);

// returns false (array length must match the number of rows)
hfInstance.isItPossibleToSetRowOrder(0, [2]);

Parameters:

Name	Type	Description
sheetId	number	ID of a sheet to operate on
newRowOrder	number[]	permutation of rows

Returns: boolean

---

isItPossibleToSwapRowIndexes

▸ isItPossibleToSwapRowIndexes(sheetId: number, rowMapping: [number, number][]): boolean

Defined in hyperformula/src/HyperFormula.ts:1567

Checks if it is possible to reorder rows of a sheet according to a source-target mapping. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 [1],
 [2],
 [4, 5],
], { licenseKey: 'gpl-v3' });

// returns true
const isSwappable = hfInstance.isItPossibleToSwapRowIndexes(0, [[0, 2], [2, 0]]);

// returns false
const isSwappable = hfInstance.isItPossibleToSwapRowIndexes(0, [[0, 1]]);

Parameters:

Name	Type	Description
sheetId	number	ID of a sheet to operate on
rowMapping	[number, number][]	array mapping original positions to final positions of rows

Returns: boolean

---

moveRows

▸ moveRows(sheetId: number, startRow: number, numberOfRows: number, targetRow: number): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:2359

Moves a particular number of rows to a specified position in a given sheet.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires valuesUpdated if recalculation was triggered by this change

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws InvalidArgumentsError when the given arguments are invalid

throws SourceLocationHasArrayError when the source location has array inside - array cannot be moved

throws TargetLocationHasArrayError when the target location has array inside - cells cannot be replaced by the array

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['1'],
 ['2'],
], { licenseKey: 'gpl-v3' });

// should return a list of cells which values changed after the operation,
// their absolute addresses and new values
const changes = hfInstance.moveRows(0, 0, 1, 2);

Parameters:

Name	Type	Description
sheetId	number	a sheet number in which the operation will be performed
startRow	number	number of the first row to move
numberOfRows	number	number of rows to move
targetRow	number	row number before which rows will be moved

Returns: ExportedChange[]

---

removeRows

▸ removeRows(sheetId: number, …indexes: ColumnRowIndex[]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:2005

Removes multiple rows from a specified position in a given sheet. Does nothing if rows are outside the effective sheet size.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['1'],
 ['2'],
], { licenseKey: 'gpl-v3' });

// should return: [{ sheet: 0, col: 1, row: 2, value: null }] for this example
const changes = hfInstance.removeRows(0, [1, 1]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID from which rows will be removed
...indexes	ColumnRowIndex[]	non-contiguous indexes with format: [row, amount]

Returns: ExportedChange[]

---

setRowOrder

▸ setRowOrder(sheetId: number, newRowOrder: number[]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1623

Reorders rows of a sheet according to a permutation of 0-based indexes.

Parameter newRowOrder should have the form [ newPositionForRow0, newPositionForRow1, newPositionForRow2, ... ]. In other words, the value at index i is the new position for the row that is currently at index i. Note that this is the opposite of [ previousPositionForRow0, previousPositionForRow1, ... ].

This method might be used to sort the rows of a sheet.

Returns an array of cells whose values changed as a result of this operation.

Note: This method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['A'],
 ['B'],
 ['C']
], { licenseKey: 'gpl-v3' });

// Move 'A' to index 1, 'B' to index 2, and 'C' to index 0.
const newRowOrder = [1, 2, 0]; // [ newPosForA, newPosForB, newPosForC ]

const changes = hfInstance.setRowOrder(0, newRowOrder);

// Sheet after this operation: [['C'], ['A'], ['B']]

Parameters:

Name	Type	Description
sheetId	number	ID of a sheet to operate on
newRowOrder	number[]	permutation of rows; array length must match the number of rows returned by getSheetDimensions()

Returns: ExportedChange[]

---

swapRowIndexes

▸ swapRowIndexes(sheetId: number, rowMapping: [number, number][]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1534

Reorders rows of a sheet according to a source-target mapping.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 [1],
 [2],
 [4, 5],
], { licenseKey: 'gpl-v3' });

// 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]]);

Parameters:

Name	Type	Description
sheetId	number	ID of a sheet to operate on
rowMapping	[number, number][]	array mapping original positions to final positions of rows

Returns: ExportedChange[]

---

Columns

addColumns

▸ addColumns(sheetId: number, …indexes: ColumnRowIndex[]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:2087

Adds multiple columns into a specified position in a given sheet. Does nothing if the columns are outside the effective sheet size.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['=RAND()', '42'],
], { licenseKey: 'gpl-v3' });

// should return a list of cells which values changed after the operation,
// their absolute addresses and new values, for this example:
// [{
//   address: { sheet: 0, col: 1, row: 0 },
//   newValue: 0.92754862796338,
// }]
const changes = hfInstance.addColumns(0, [0, 1]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID in which columns will be added
...indexes	ColumnRowIndex[]	non-contiguous indexes with format: [column, amount], where column is a column number from which new columns will be added

Returns: ExportedChange[]

---

isItPossibleToAddColumns

▸ isItPossibleToAddColumns(sheetId: number, …indexes: ColumnRowIndex[]): boolean

Defined in hyperformula/src/HyperFormula.ts:2037

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. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// 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]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID in which columns will be added
...indexes	ColumnRowIndex[]	non-contiguous indexes with format: [column, amount], where column is a column number from which new columns will be added

Returns: boolean

---

isItPossibleToMoveColumns

▸ isItPossibleToMoveColumns(sheetId: number, startColumn: number, numberOfColumns: number, targetColumn: number): boolean

Defined in hyperformula/src/HyperFormula.ts:2396

Returns information whether it is possible to move a particular number of columns to a specified position in a given sheet. Checks against particular rules to ascertain that moveColumns can be called. If returns true, doing moveColumns operation won’t throw any errors. Returns false if the operation might be disrupted and causes side effects by the fact that there is an array inside the selected columns, the target location includes an array or the provided address is invalid. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// should return 'true' for this example
// it is possible to move one column from column 1 into column 2 of sheet 0
const isMovable = hfInstance.isItPossibleToMoveColumns(0, 1, 1, 2);

Parameters:

Name	Type	Description
sheetId	number	a sheet number in which the operation will be performed
startColumn	number	number of the first column to move
numberOfColumns	number	number of columns to move
targetColumn	number	column number before which columns will be moved

Returns: boolean

---

isItPossibleToRemoveColumns

▸ isItPossibleToRemoveColumns(sheetId: number, …indexes: ColumnRowIndex[]): boolean

Defined in hyperformula/src/HyperFormula.ts:2119

Returns information whether it is possible to remove columns from a specified position in a given sheet. Checks against particular rules to ascertain that removeColumns can be called. If returns true, doing removeColumns operation won’t throw any errors. Returns false if given arguments are invalid. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// should return 'true' for this example
// it is possible to remove one column, in place of the second column of sheet 0
const isRemovable = hfInstance.isItPossibleToRemoveColumns(0, [1, 1]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID from which columns will be removed
...indexes	ColumnRowIndex[]	non-contiguous indexes with format [column, amount]

Returns: boolean

---

isItPossibleToSetColumnOrder

▸ isItPossibleToSetColumnOrder(sheetId: number, newColumnOrder: number[]): boolean

Defined in hyperformula/src/HyperFormula.ts:1841

Checks if it is possible to reorder columns of a sheet according to a permutation. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

Parameter newColumnOrder should have the form [ newPositionForColumn0, newPositionForColumn1, newPositionForColumn2, ... ], i.e. the value at index i is the new position for the column that is currently at index i. See setColumnOrder for details.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['A', 'B', 'C']
], { licenseKey: 'gpl-v3' });

// returns true
hfInstance.isItPossibleToSetColumnOrder(0, [1, 2, 0]);

// returns false (array length must match the number of columns)
hfInstance.isItPossibleToSetColumnOrder(0, [1]);

Parameters:

Name	Type	Description
sheetId	number	ID of a sheet to operate on
newColumnOrder	number[]	permutation of columns

Returns: boolean

---

isItPossibleToSwapColumnIndexes

▸ isItPossibleToSwapColumnIndexes(sheetId: number, columnMapping: [number, number][]): boolean

Defined in hyperformula/src/HyperFormula.ts:1752

Checks if it is possible to reorder columns of a sheet according to a source-target mapping. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

fires valuesUpdated if recalculation was triggered by this change

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 [1, 2, 4],
 [5]
], { licenseKey: 'gpl-v3' });

// returns true
hfInstance.isItPossibleToSwapColumnIndexes(0, [[0, 2], [2, 0]]);

// returns false
hfInstance.isItPossibleToSwapColumnIndexes(0, [[0, 1]]);

Parameters:

Name	Type
sheetId	number
columnMapping	[number, number][]

Returns: boolean

---

moveColumns

▸ moveColumns(sheetId: number, startColumn: number, numberOfColumns: number, targetColumn: number): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:2454

Moves a particular number of columns to a specified position in a given sheet.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires valuesUpdated if recalculation was triggered by this change

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws InvalidArgumentsError when the given arguments are invalid

throws SourceLocationHasArrayError when the source location has array inside - array cannot be moved

throws TargetLocationHasArrayError when the target location has array inside - cells cannot be replaced by the array

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2', '3', '=RAND()', '=SUM(A1:C1)'],
], { licenseKey: 'gpl-v3' });

// move column B before column D; the SUM range follows its cells and becomes A1:B1
// should return a list of cells which values changed after the operation,
// their absolute addresses and new values, for this example:
// [{
//   address: { sheet: 0, col: 4, row: 0 },
//   newValue: 4,
//  }, {
//   address: { sheet: 0, col: 3, row: 0 },
//   newValue: 0.16210054671639,
// }]
const changes = hfInstance.moveColumns(0, 1, 1, 3);

Parameters:

Name	Type	Description
sheetId	number	a sheet number in which the operation will be performed
startColumn	number	number of the first column to move
numberOfColumns	number	number of columns to move
targetColumn	number	column number before which columns will be moved

Returns: ExportedChange[]

---

removeColumns

▸ removeColumns(sheetId: number, …indexes: ColumnRowIndex[]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:2168

Removes multiple columns from a specified position in a given sheet. Does nothing if columns are outside the effective sheet size.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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 LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['0', '=SUM(1, 2, 3)', '=A1'],
], { licenseKey: 'gpl-v3' });

// should return a list of cells which values changed after the operation,
// their absolute addresses and new values, in this example it will return:
// [{
//   address: { sheet: 0, col: 1, row: 0 },
//   newValue: { error: [CellError], value: '#REF!' },
// }]
const changes = hfInstance.removeColumns(0, [0, 1]);

Parameters:

Name	Type	Description
sheetId	number	sheet ID from which columns will be removed
...indexes	ColumnRowIndex[]	non-contiguous indexes with format: [column, amount]

Returns: ExportedChange[]

---

setColumnOrder

▸ setColumnOrder(sheetId: number, newColumnOrder: number[]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1806

Reorders columns of a sheet according to a permutation of 0-based indexes.

Parameter newColumnOrder should have the form [ newPositionForColumn0, newPositionForColumn1, newPositionForColumn2, ... ]. In other words, the value at index i is the new position for the column that is currently at index i. Note that this is the opposite of [ previousPositionForColumn0, previousPositionForColumn1, ... ].

This method might be used to sort the columns of a sheet.

Returns an array of cells whose values changed as a result of this operation.

Note: This method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
  ['A', 'B', 'C']
], { licenseKey: 'gpl-v3' });

// Move 'A' to index 1, 'B' to index 2, and 'C' to index 0.
const newColumnOrder = [1, 2, 0]; // [ newPosForA, newPosForB, newPosForC ]

const changes = hfInstance.setColumnOrder(0, newColumnOrder);

// Sheet after this operation: [['C', 'A', 'B']]

Parameters:

Name	Type	Description
sheetId	number	ID of a sheet to operate on
newColumnOrder	number[]	permutation of columns; array length must match the number of columns returned by getSheetDimensions()

Returns: ExportedChange[]

---

swapColumnIndexes

▸ swapColumnIndexes(sheetId: number, columnMapping: [number, number][]): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1722

Reorders columns of a sheet according to a source-target mapping.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 [1, 2, 4],
 [5]
], { licenseKey: 'gpl-v3' });

// 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]]);

Parameters:

Name	Type	Description
sheetId	number	ID of a sheet to operate on
columnMapping	[number, number][]	array mapping original positions to final positions of columns

Returns: ExportedChange[]

---

Cells

doesCellHaveFormula

▸ doesCellHaveFormula(cellAddress: SimpleCellAddress): boolean

Defined in hyperformula/src/HyperFormula.ts:3591

Returns true if the specified cell contains a formula. The method accepts cell coordinates as object with column, row and sheet numbers.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(A2:A3)', '2'],
], { licenseKey: 'gpl-v3' });

// should return 'true' since the A1 cell contains a formula
const A1Formula = hfInstance.doesCellHaveFormula({ sheet: 0, col: 0, row: 0 });

// should return 'false' since the B1 cell does not contain a formula
const B1NoFormula = hfInstance.doesCellHaveFormula({ sheet: 0, col: 1, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: boolean

---

doesCellHaveSimpleValue

▸ doesCellHaveSimpleValue(cellAddress: SimpleCellAddress): boolean

Defined in hyperformula/src/HyperFormula.ts:3560

Returns true if the specified cell contains a simple value. The method accepts cell coordinates as object with column, row and sheet numbers.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(A2:A3)', '2'],
], { licenseKey: 'gpl-v3' });

// should return 'true' since the selected cell contains a simple value
const isA1Simple = hfInstance.doesCellHaveSimpleValue({ sheet: 0, col: 0, row: 0 });

// should return 'false' since the selected cell does not contain a simple value
const isB1Simple = hfInstance.doesCellHaveSimpleValue({ sheet: 0, col: 1, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: boolean

---

getCellFormula

▸ getCellFormula(cellAddress: SimpleCellAddress): string | undefined

Defined in hyperformula/src/HyperFormula.ts:897

Returns a normalized formula string from the cell of a given address or undefined for an address that does not exist and empty values.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError when cellAddress is of incorrect type

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(1, 2, 3)', '0'],
], { licenseKey: 'gpl-v3' });

// 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 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: string | undefined

---

getCellHyperlink

▸ getCellHyperlink(cellAddress: SimpleCellAddress): string | undefined

Defined in hyperformula/src/HyperFormula.ts:927

Returns the HYPERLINK url for a cell of a given address or undefined for an address that does not exist or a cell that is not HYPERLINK

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError when cellAddress is of incorrect type

example

const hfInstance = HyperFormula.buildFromArray([
 ['=HYPERLINK("https://hyperformula.handsontable.com/", "HyperFormula")', '0'],
], { licenseKey: 'gpl-v3' });

// should return url of 'HYPERLINK': https://hyperformula.handsontable.com/
const A1Hyperlink = hfInstance.getCellHyperlink({ sheet: 0, col: 0, row: 0 });

// should return 'undefined' for a cell that is not 'HYPERLINK'
const B1Hyperlink = hfInstance.getCellHyperlink({ sheet: 0, col: 1, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: string | undefined

---

getCellSerialized

▸ getCellSerialized(cellAddress: SimpleCellAddress): RawCellContent

Defined in hyperformula/src/HyperFormula.ts:959

Returns RawCellContent with a serialized content of the cell of a given address: either a cell formula, an explicit value, or an error.

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

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(1, 2, 3)', '0'],
], { licenseKey: 'gpl-v3' });

// 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 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: RawCellContent

---

getCellType

▸ getCellType(cellAddress: SimpleCellAddress): CellType

Defined in hyperformula/src/HyperFormula.ts:3528

Returns the type of a cell at a given address. The method accepts cell coordinates as object with column, row and sheet numbers.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(A2:A3)', '2'],
], { licenseKey: 'gpl-v3' });

// should return 'FORMULA', the cell of given coordinates is of this type
const cellA1Type = hfInstance.getCellType({ sheet: 0, col: 0, row: 0 });

// should return 'VALUE', the cell of given coordinates is of this type
const cellB1Type = hfInstance.getCellType({ sheet: 0, col: 1, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: CellType

---

getCellValue

▸ getCellValue(cellAddress: SimpleCellAddress): CellValue

Defined in hyperformula/src/HyperFormula.ts:866

Returns the cell value of a given address. Applies rounding and post-processing.

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

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(1, 2, 3)', '2'],
], { licenseKey: 'gpl-v3' });

// 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 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: CellValue

---

getCellValueDetailedType

▸ getCellValueDetailedType(cellAddress: SimpleCellAddress): CellValueDetailedType

Defined in hyperformula/src/HyperFormula.ts:3722

Returns detailed type of the cell value of a given address. The method accepts cell coordinates as object with column, row and sheet numbers.

For more information, see the Types of values guide.

throws NoSheetWithIdError when the given sheet ID does not exist

throws EvaluationSuspendedError when the evaluation is suspended

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1%', '1$'],
], { licenseKey: 'gpl-v3' });

// should return 'NUMBER_PERCENT', cell value type of provided coordinates is a number with a format inference percent.
const cellType = hfInstance.getCellValueDetailedType({ sheet: 0, col: 0, row: 0 });

// should return 'NUMBER_CURRENCY', cell value type of provided coordinates is a number with a format inference currency.
const cellType = hfInstance.getCellValueDetailedType({ sheet: 0, col: 1, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: CellValueDetailedType

---

getCellValueFormat

▸ getCellValueFormat(cellAddress: SimpleCellAddress): FormatInfo

Defined in hyperformula/src/HyperFormula.ts:3756

Returns auxiliary format information of the cell value of a given address. The method accepts cell coordinates as object with column, row and sheet numbers.

throws NoSheetWithIdError when the given sheet ID does not exist

throws EvaluationSuspendedError when the evaluation is suspended

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['1$', '1'],
], { licenseKey: 'gpl-v3' });

// should return '$', cell value type of provided coordinates is a number with a format inference currency, parsed as using '$' as currency.
const cellFormat = hfInstance.getCellValueFormat({ sheet: 0, col: 0, row: 0 });

// should return undefined, cell value type of provided coordinates is a number with no format information.
const cellFormat = hfInstance.getCellValueFormat({ sheet: 0, col: 1, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: FormatInfo

---

getCellValueType

▸ getCellValueType(cellAddress: SimpleCellAddress): CellValueType

Defined in hyperformula/src/HyperFormula.ts:3686

Returns type of the cell value of a given address. The method accepts cell coordinates as object with column, row and sheet numbers.

For more information, see the Types of values guide.

throws NoSheetWithIdError when the given sheet ID does not exist

throws EvaluationSuspendedError when the evaluation is suspended

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['=SUM(1, 2, 3)', '2'],
], { licenseKey: 'gpl-v3' });

// should return 'NUMBER', cell value type of provided coordinates is a number
const cellValue = hfInstance.getCellValueType({ sheet: 0, col: 1, row: 0 });

// should return 'NUMBER', cell value type of provided coordinates is a number
const cellValue = hfInstance.getCellValueType({ sheet: 0, col: 0, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: CellValueType

---

isCellEmpty

▸ isCellEmpty(cellAddress: SimpleCellAddress): boolean

Defined in hyperformula/src/HyperFormula.ts:3623

Returnstrue if the specified cell is empty. The method accepts cell coordinates as object with column, row and sheet numbers.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
  [null, '1'],
], { licenseKey: 'gpl-v3' });

// should return 'true', cell of provided coordinates is empty
const isEmpty = hfInstance.isCellEmpty({ sheet: 0, col: 0, row: 0 });

// should return 'false', cell of provided coordinates is not empty
const isNotEmpty = hfInstance.isCellEmpty({ sheet: 0, col: 1, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: boolean

---

isCellPartOfArray

▸ isCellPartOfArray(cellAddress: SimpleCellAddress): boolean

Defined in hyperformula/src/HyperFormula.ts:3651

Returns true if a given cell is a part of an array. The method accepts cell coordinates as object with column, row and sheet numbers.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if cellAddress is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
   ['{=TRANSPOSE(B1:B1)}'],
], { licenseKey: 'gpl-v3' });

// should return 'true', cell of provided coordinates is a part of an array
const isPartOfArray = hfInstance.isCellPartOfArray({ sheet: 0, col: 0, row: 0 });

Parameters:

Name	Type	Description
cellAddress	SimpleCellAddress	cell coordinates

Returns: boolean

---

isItPossibleToMoveCells

▸ isItPossibleToMoveCells(source: SimpleCellRange, destinationLeftCorner: SimpleCellAddress): boolean

Defined in hyperformula/src/HyperFormula.ts:2206

Returns information whether it is possible to move cells to a specified position in a given sheet. Checks against particular rules to ascertain that moveCells can be called. If returns true, doing moveCells operation won’t throw any errors. Returns false if the operation might be disrupted and causes side effects by the fact that there is an array inside the selected columns, the target location includes an array or the provided address is invalid. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if destinationLeftCorner, source, or any of basic type arguments are of wrong type

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// choose the coordinates and assign them to variables
const source = { sheet: 0, col: 1, row: 0 };
const destination = { sheet: 0, col: 3, row: 0 };

// should return 'true' for this example
// it is possible to move a block of width 1 and height 1
// from the corner: column 1 and row 0 of sheet 0
// into destination corner: column 3, row 0 of sheet 0
const isMovable = hfInstance.isItPossibleToMoveCells({ start: source, end: source }, destination);

Parameters:

Name	Type	Description
source	SimpleCellRange	range for a moved block
destinationLeftCorner	SimpleCellAddress	upper left address of the target cell block

Returns: boolean

---

isItPossibleToSetCellContents

▸ isItPossibleToSetCellContents(address: SimpleCellAddress | SimpleCellRange): boolean

Defined in hyperformula/src/HyperFormula.ts:1423

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. Returns false also when the license key does not allow the Crud feature (see LicenseCapabilityMissingError).

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

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// 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 });

Parameters:

Name	Type	Description
address	SimpleCellAddress | SimpleCellRange	single cell or block of cells to check

Returns: boolean

---

moveCells

▸ moveCells(source: SimpleCellRange, destinationLeftCorner: SimpleCellAddress): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:2267

Moves the content of a cell block from source to the target location.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires valuesUpdated if recalculation was triggered by this change

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if destinationLeftCorner or source are of wrong type

throws InvalidArgumentsError when the given arguments are invalid

throws SheetSizeLimitExceededError when performing this operation would result in sheet size limits exceeding

throws SourceLocationHasArrayError when the source location has array inside - array cannot be moved

throws TargetLocationHasArrayError when the target location has array inside - cells cannot be replaced by the array

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['=RAND()', '42'],
], { licenseKey: 'gpl-v3' });

// choose the coordinates and assign them to variables
const source = { sheet: 0, col: 1, row: 0 };
const destination = { sheet: 0, col: 3, row: 0 };

// should return a list of cells which values changed after the operation,
// their absolute addresses and new values, for this example:
// [{
//   address: { sheet: 0, col: 0, row: 0 },
//   newValue: 0.93524248002062,
// }]
const changes = hfInstance.moveCells({ start: source, end: source }, destination);

Parameters:

Name	Type	Description
source	SimpleCellRange	range for a moved block
destinationLeftCorner	SimpleCellAddress	upper left address of the target cell block

Returns: ExportedChange[]

---

setCellContents

▸ setCellContents(topLeftCornerAddress: SimpleCellAddress, cellContents: RawCellContent[][] | RawCellContent): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1480

Sets the content for a block of cells of a given coordinates.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Crud feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2', '=A1'],
], { licenseKey: 'gpl-v3' });

// 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']]);

Parameters:

Name	Type	Description
topLeftCornerAddress	SimpleCellAddress	top left corner of block of cells
cellContents	RawCellContent[][] | RawCellContent	array with content

Returns: ExportedChange[]

---

Named Expressions

addNamedExpression

▸ addNamedExpression(expressionName: string, expression: RawCellContent, scope?: undefined | number, options?: NamedExpressionOptions): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:4102

Adds a specified named expression.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires namedExpressionAdded always, unless batch mode is used

fires valuesUpdated if recalculation was triggered by this change

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NamedExpressionNameIsAlreadyTakenError when the named-expression name is not available.

throws NamedExpressionNameIsInvalidError when the named-expression name is not valid

throws NoRelativeAddressesAllowedError when the named-expression formula contains relative references

throws NoSheetWithIdError if no sheet with given sheetId exists

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the NamedExpressions feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add own expression, scope limited to 'Sheet1' (sheetId=0), the method should return a list of cells which values
// changed after the operation, their absolute addresses and new values
// for this example:
// [{
//   name: 'prettyName',
//   newValue: 142,
// }]
const changes = hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100', 0);

Parameters:

Name	Type	Description
expressionName	string	a name of the expression to be added
expression	RawCellContent	the expression
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope
options?	NamedExpressionOptions	additional metadata related to named expression

Returns: ExportedChange[]

---

changeNamedExpression

▸ changeNamedExpression(expressionName: string, newExpression: RawCellContent, scope?: undefined | number, options?: NamedExpressionOptions): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:4330

Changes a given named expression to a specified formula.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires valuesUpdated if recalculation was triggered by this change

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NamedExpressionDoesNotExistError when the given expression does not exist.

throws NoSheetWithIdError if no sheet with given sheetId exists

throws [[ArrayFormulasNotSupportedError]] when the named expression formula is an array formula

throws NoRelativeAddressesAllowedError when the named expression formula contains relative references

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the NamedExpressions feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add a named expression, scope limited to 'Sheet1' (sheetId=0)
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100', 0);

// change the named expression in the same scope
const changes = hfInstance.changeNamedExpression('prettyName', '=Sheet1!$A$1+200', 0);

Parameters:

Name	Type	Description
expressionName	string	an expression name, case-insensitive.
newExpression	RawCellContent	a new expression
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope
options?	NamedExpressionOptions	additional metadata related to named expression

Returns: ExportedChange[]

---

getAllNamedExpressionsSerialized

▸ getAllNamedExpressionsSerialized(): SerializedNamedExpression[]

Defined in hyperformula/src/HyperFormula.ts:4505

Returns all named expressions serialized.

For more information, see the Named expressions guide.

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
 ['50'],
 ['60'],
], { licenseKey: 'gpl-v3' });

// add two named expressions and one scoped
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100');
hfInstance.addNamedExpression('anotherPrettyName', '=Sheet1!$A$2+100');
hfInstance.addNamedExpression('alsoPrettyName', '=Sheet1!$A$3+100', 0);

// get all expressions serialized
// should return:
// [
// {name: 'prettyName', expression: '=Sheet1!$A$1+100', options: undefined, scope: undefined},
// {name: 'anotherPrettyName', expression: '=Sheet1!$A$2+100', options: undefined, scope: undefined},
// {name: 'alsoPrettyName', expression: '=Sheet1!$A$3+100', options: undefined, scope: 0}
// ]
const allExpressions = hfInstance.getAllNamedExpressionsSerialized();

Returns: SerializedNamedExpression[]

---

getNamedExpression

▸ getNamedExpression(expressionName: string, scope?: undefined | number): NamedExpression | undefined

Defined in hyperformula/src/HyperFormula.ts:4228

Returns a named expression, or undefined for a named expression that does not exist or does not hold a formula.

For more information, see the Named expressions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NoSheetWithIdError if no sheet with given sheetId exists

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add a named expression in 'Sheet1' (sheetId=0)
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100', 0);

// returns a named expression that corresponds to the passed name from 'Sheet1' (sheetId=0)
// for this example, returns:
// {name: 'prettyName', expression: '=Sheet1!$A$1+100', options: undefined, scope: 0}
const myFormula = hfInstance.getNamedExpression('prettyName', 0);

// for a named expression that doesn't exist, returns 'undefined':
const myFormulaTwo = hfInstance.getNamedExpression('uglyName', 0);

Parameters:

Name	Type	Description
expressionName	string	expression name, case-insensitive.
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope

Returns: NamedExpression | undefined

---

getNamedExpressionFormula

▸ getNamedExpressionFormula(expressionName: string, scope?: undefined | number): string | undefined

Defined in hyperformula/src/HyperFormula.ts:4183

Returns a normalized formula string for given named expression, or undefined for a named expression that does not exist or does not hold a formula.

For more information, see the Named expressions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NoSheetWithIdError if no sheet with given sheetId exists

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add a named expression in 'Sheet1' (sheetId=0)
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100', 0);

// returns a normalized formula string corresponding to the passed name from 'Sheet1' (sheetId=0),
// '=Sheet1!A1+100' for this example
const myFormula = hfInstance.getNamedExpressionFormula('prettyName', 0);

Parameters:

Name	Type	Description
expressionName	string	expression name, case-insensitive.
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope

Returns: string | undefined

---

getNamedExpressionValue

▸ getNamedExpressionValue(expressionName: string, scope?: undefined | number): CellValue | undefined

Defined in hyperformula/src/HyperFormula.ts:4141

Gets specified named expression value. Returns a CellValue or undefined if the given named expression does not exist.

For more information, see the Named expressions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NoSheetWithIdError if no sheet with given sheetId exists

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add a named expression, only 'Sheet1' (sheetId=0) considered as it is the scope
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100', 0);

// returns the calculated value of a passed named expression, 142 for this example
const myFormula = hfInstance.getNamedExpressionValue('prettyName', 0);

Parameters:

Name	Type	Description
expressionName	string	expression name, case-insensitive.
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope

Returns: CellValue | undefined

---

isItPossibleToAddNamedExpression

▸ isItPossibleToAddNamedExpression(expressionName: string, expression: RawCellContent, scope?: undefined | number): boolean

Defined in hyperformula/src/HyperFormula.ts:4046

Returns information whether it is possible to add named expression into a specific scope. Checks against particular rules to ascertain that addNamedExpression can be called. If returns true, doing addNamedExpression operation won’t throw any errors. Returns false if the operation might be disrupted. Returns false also when the license key does not allow the NamedExpressions feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// should return 'true' for this example,
// it is possible to add named expression to global scope
const isAddable = hfInstance.isItPossibleToAddNamedExpression('prettyName', '=Sheet1!$A$1+100');

Parameters:

Name	Type	Description
expressionName	string	a name of the expression to be added
expression	RawCellContent	the expression
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope

Returns: boolean

---

isItPossibleToChangeNamedExpression

▸ isItPossibleToChangeNamedExpression(expressionName: string, newExpression: RawCellContent, scope?: undefined | number): boolean

Defined in hyperformula/src/HyperFormula.ts:4278

Returns information whether it is possible to change named expression in a specific scope. Checks against particular rules to ascertain that changeNamedExpression can be called. If returns true, doing changeNamedExpression operation won’t throw any errors. Returns false if the operation might be disrupted. Returns false also when the license key does not allow the NamedExpressions feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add a named expression
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100');

// should return 'true' for this example,
// it is possible to change named expression
const isAddable = hfInstance.isItPossibleToChangeNamedExpression('prettyName', '=Sheet1!$A$1+100');

Parameters:

Name	Type	Description
expressionName	string	an expression name, case-insensitive.
newExpression	RawCellContent	a new expression
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope

Returns: boolean

---

isItPossibleToRemoveNamedExpression

▸ isItPossibleToRemoveNamedExpression(expressionName: string, scope?: undefined | number): boolean

Defined in hyperformula/src/HyperFormula.ts:4368

Returns information whether it is possible to remove named expression from a specific scope. Checks against particular rules to ascertain that removeNamedExpression can be called. If returns true, doing removeNamedExpression operation won’t throw any errors. Returns false if the operation might be disrupted. Returns false also when the license key does not allow the NamedExpressions feature (see LicenseCapabilityMissingError).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add a named expression
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100');

// should return 'true' for this example,
// it is possible to change named expression
const isAddable = hfInstance.isItPossibleToRemoveNamedExpression('prettyName');

Parameters:

Name	Type	Description
expressionName	string	an expression name, case-insensitive.
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope

Returns: boolean

---

listNamedExpressions

▸ listNamedExpressions(scope?: undefined | number): string[]

Defined in hyperformula/src/HyperFormula.ts:4467

Lists named expressions.

• If scope parameter is provided, returns an array of expression names defined for this scope.
• If scope parameter is undefined, returns an array of global expression names.

For more information, see the Named expressions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NoSheetWithIdError if no sheet with given sheetId exists

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
 ['50'],
 ['60'],
], { licenseKey: 'gpl-v3' });

// add two named expressions and one scoped
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100');
hfInstance.addNamedExpression('anotherPrettyName', '=Sheet1!$A$2+100');
hfInstance.addNamedExpression('alsoPrettyName', '=Sheet1!$A$3+100', 0);

// list the expressions, should return: ['prettyName', 'anotherPrettyName'] for this example
const listOfExpressions = hfInstance.listNamedExpressions();

 // list the expressions, should return: ['alsoPrettyName'] for this example
const listOfExpressions = hfInstance.listNamedExpressions(0);

Parameters:

Name	Type	Description
scope?	undefined | number	scope of the named expressions, sheetId for local scope or undefined for global scope

Returns: string[]

---

removeNamedExpression

▸ removeNamedExpression(expressionName: string, scope?: undefined | number): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:4417

Removes a named expression.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires namedExpressionRemoved after the expression was removed

fires valuesUpdated if recalculation was triggered by this change

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NamedExpressionDoesNotExistError when the given expression does not exist.

throws NoSheetWithIdError if no sheet with given sheetId exists

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the NamedExpressions feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
], { licenseKey: 'gpl-v3' });

// add a named expression
hfInstance.addNamedExpression('prettyName', '=Sheet1!$A$1+100', 0);

// remove the named expression
const changes = hfInstance.removeNamedExpression('prettyName', 0);

Parameters:

Name	Type	Description
expressionName	string	expression name, case-insensitive.
scope?	undefined | number	scope definition, sheetId for local scope or undefined for global scope

Returns: ExportedChange[]

---

Helpers

calculateFormula

▸ calculateFormula(formulaString: string, sheetId: number): CellValue | CellValue[][]

Defined in hyperformula/src/HyperFormula.ts:4570

Calculates fire-and-forget formula, returns the calculated value.

throws ExpectedValueOfTypeError if any of its basic type arguments is of wrong type.

throws NotAFormulaError when the provided string is not a valid formula (i.e., doesn’t start with =).

throws NoSheetWithIdError when the provided sheetID doesn’t exist.

example

const hfInstance = HyperFormula.buildFromSheets({
 Sheet1: [['58']],
 Sheet2: [['1', '2', '3'], ['4', '5', '6']]
}, { licenseKey: 'gpl-v3' });

// returns the calculated formula's value
// for this example, returns `68`
const calculatedFormula = hfInstance.calculateFormula('=A1+10', 0);

// for this example, returns [['11', '12', '13'], ['14', '15', '16']]
const calculatedFormula = hfInstance.calculateFormula('=A1:B3+10', 1);

Parameters:

Name	Type	Description
formulaString	string	A formula in a proper format, starting with =.
sheetId	number	The ID of a sheet in context of which the formula gets evaluated.

Returns: CellValue | CellValue[][]

---

getAvailableFunctions

▸ getAvailableFunctions(): FunctionListEntry[]

Defined in hyperformula/src/HyperFormula.ts:4761

Returns metadata of all functions available in this instance for a function picker, with names translated according to the language set in this instance’s configuration. Each entry contains the translated name, the language-independent canonical name, the category, and a short description. Entries are sorted alphabetically by their localized name, using the collation rules of the host environment, so the exact order of names that differ only by case or diacritics may vary between hosts.

The list reflects this instance’s own registry: the built-in functions and any custom (user-registered) functions, plus their aliases. An alias is listed under its own id, borrowing its target’s category and description, with the target id exposed as aliasOf. Custom functions ship no catalogue entry, so their category is 'Custom' and they carry no shortDescription — with one exception: the catalogue is keyed by function id, so a custom plugin registered over a built-in id inherits that id’s entry and is listed with the built-in’s category and description.

That registry is a snapshot taken when the instance was built, not a live view of the global one: a function registered with registerFunctionPlugin or registerFunction afterwards reaches only the engines built later, so an engine kept across a late registration keeps reporting the set it was built with.

A function with no translation entry for the configured language is omitted: the interpreter refuses to evaluate an untranslated id, so listing it would advertise a function that cannot be called — in practice, a custom plugin registered without translations for that language. A translation set to an empty string is not a missing entry: it falls back to the canonical id, so the function stays listed under its canonical name.

A function the instance’s license key does not include is omitted for the same reason: it would evaluate to a #LIC! error. The list therefore answers “what can this engine compute”, not “what does this package contain”. Two consequences worth knowing:

• A key that blocks evaluation (a missing or invalid key, an expired classic key, or a trial past its grace period) does not shorten the list. Such a key restricts nothing by entitlement — it is reported on the console, and every license-gated function call evaluates to #LIC! — so the full catalog is still described. VERSION() and OFFSET() are protected built-ins outside the license system, so they keep evaluating. Use it to build a function picker before a key is configured. An expired key that keeps evaluating (a subscription past its grace period, or a perpetual key whose maintenance doesn’t cover this build) keeps its own grants, so the list stays exactly what it was while the key was current.
• A custom (user-registered) function is omitted only if it took a built-in id the key excludes. The rule is “not covered by the capability table”, not “not user-registered”, so a plugin registered under an id the built-in catalog already uses is treated as that built-in. Registered under an id of its own, a custom function is never omitted. See getFunctionDetails, which states the same exception.

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// get the list of available functions, translated for the configured language
const functions = hfInstance.getAvailableFunctions();

Returns: FunctionListEntry[]

---

getCellDependents

▸ getCellDependents(address: SimpleCellAddress | SimpleCellRange): (SimpleCellRange | SimpleCellAddress)[]

Defined in hyperformula/src/HyperFormula.ts:3355

Returns all the out-neighbors in the dependency graph for a given cell address or range. Including:

• All cells with formulas that contain the given cell address or range
• Some of the ranges that contain the given cell address or range

The exact result depends on the optimizations applied by the HyperFormula to the dependency graph, some of which are described in the section “Optimizations for large ranges”.

The returned array includes also named expression dependents. They are represented as cell references with sheet ID -1.

throws ExpectedValueOfTypeError if address is not SimpleCellAddress or SimpleCellRange

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

throws NoSheetWithIdError when the given sheet ID does not exist

example

const hfInstance = HyperFormula.buildFromArray( [ ['1', '=A1', '=A1+B1'] ] , { licenseKey: 'gpl-v3' });

hfInstance.getCellDependents({ sheet: 0, col: 0, row: 0});
// returns [{ sheet: 0, col: 1, row: 0}, { sheet: 0, col: 2, row: 0}]

Parameters:

Name	Type	Description
address	SimpleCellAddress | SimpleCellRange	object representation of an absolute address or range of addresses

Returns: (SimpleCellRange | SimpleCellAddress)[]

---

getCellPrecedents

▸ getCellPrecedents(address: SimpleCellAddress | SimpleCellRange): (SimpleCellRange | SimpleCellAddress)[]

Defined in hyperformula/src/HyperFormula.ts:3393

Returns all the in-neighbors in the dependency graph for a given cell address or range. In particular:

• If the argument is a single cell, getCellPrecedents() returns all cells and ranges contained in that cell’s formula.
• If the argument is a range of cells, getCellPrecedents() returns some of the cell addresses and smaller ranges contained in that range (but not all of them). The exact result depends on the optimizations applied by the HyperFormula to the dependency graph, some of which are described in the section “Optimizations for large ranges”.

The returned array includes also named expression precedents. They are represented as cell references with sheet ID -1.

throws ExpectedValueOfTypeError if address is of wrong type

throws NoSheetWithIdError when the given sheet ID does not exist

example

const hfInstance = HyperFormula.buildFromArray( [ ['1', '=A1', '=A1+B1'] ] , { licenseKey: 'gpl-v3' });

hfInstance.getCellPrecedents({ sheet: 0, col: 2, row: 0});
// returns [{ sheet: 0, col: 0, row: 0}, { sheet: 0, col: 1, row: 0}]

Parameters:

Name	Type	Description
address	SimpleCellAddress | SimpleCellRange	object representation of an absolute address or range of addresses

Returns: (SimpleCellRange | SimpleCellAddress)[]

---

getFunctionDetails

▸ getFunctionDetails(canonicalName: string): FunctionDetails | undefined

Defined in hyperformula/src/HyperFormula.ts:4807

Returns the full metadata of a single function registered in this instance, with names translated according to the language set in this instance’s configuration: the parameter list (with per-parameter optionality), the number of trailing parameters that repeat (repeatLastArgs), the category, a short description, and the documentation link (documentationUrl) and usage examples (examples) — every built-in authors both. Resolves both built-in and custom (user-registered) functions, as well as aliases. An alias reports its target’s metadata (including examples, which spell the target’s name) under the alias id, with the target id exposed as aliasOf. Returns undefined when the function id is unknown, not registered in this instance, has no translation entry for the configured language, or is not included in this instance’s license key (neither an untranslated nor an unlicensed id can be evaluated, so neither is described — which keeps this method consistent with getAvailableFunctions, including its behavior for a key that blocks evaluation). For a custom function, category is 'Custom', there is no shortDescription, documentationUrl or examples, and parameters are reported positionally (Arg1, Arg2, …). A custom plugin registered over a built-in id is the exception: the catalogue is keyed by function id, so it reports that built-in’s authored metadata alongside the parameter list of the implementation actually registered.

canonicalName is matched exactly, in two ways worth knowing:

• It is case-sensitive, unlike formula syntax. 'SUMIF' resolves; 'sumif' and 'SumIf' return undefined, even though =sumif(...) evaluates.
• It must be the canonical (English) id, never a localized name. localizedName is output only: under plPL this method reports localizedName: 'SUMA.JEŻELI' for 'SUMIF', but passing 'SUMA.JEŻELI' back in returns undefined. To look up an entry from getAvailableFunctions, pass its canonicalName.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// get the details of the SUMIF function, translated for the configured language
const details = hfInstance.getFunctionDetails('SUMIF');

Parameters:

Name	Type	Description
canonicalName	string	the language-independent function id, e.g. 'SUMIF'

Returns: FunctionDetails | undefined

---

getNamedExpressionsFromFormula

▸ getNamedExpressionsFromFormula(formulaString: string): string[]

Defined in hyperformula/src/HyperFormula.ts:4601

Return a list of named expressions used by a formula.

throws ExpectedValueOfTypeError if any of its basic type arguments is of wrong type.

throws NotAFormulaError when the provided string is not a valid formula (i.e., doesn’t start with =).

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// returns a list of named expressions used by a formula
// for this example, returns ['foo', 'bar']
const namedExpressions = hfInstance.getNamedExpressionsFromFormula('=foo+bar*2');

Parameters:

Name	Type	Description
formulaString	string	A formula in a proper format, starting with =.

Returns: string[]

---

normalizeFormula

▸ normalizeFormula(formulaString: string): string

Defined in hyperformula/src/HyperFormula.ts:4534

Parses and then unparses a formula. Returns a normalized formula (e.g., restores the original capitalization of sheet names, function names, cell addresses, and named expressions).

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws NotAFormulaError when the provided string is not a valid formula, i.e., does not start with “=”

example

const hfInstance = HyperFormula.buildFromArray([
 ['42'],
 ['50'],
], { licenseKey: 'gpl-v3' });

// returns '=Sheet1!$A$1+10'
const normalizedFormula = hfInstance.normalizeFormula('=SHEET1!$A$1+10');

// returns '=3*$A$1'
const normalizedFormula = hfInstance.normalizeFormula('=3*$a$1');

Parameters:

Name	Type	Description
formulaString	string	a formula in a proper format - it must start with “=”

Returns: string

---

numberToDate

▸ numberToDate(inputNumber: number): DateTime

Defined in hyperformula/src/HyperFormula.ts:4861

Interprets number as a date.

For more information, see the Date and time handling guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// pass the number of days since nullDate
// the method should return formatted date, for this example:
// {year: 2020, month: 1, day: 15}
const dateFromNumber = hfInstance.numberToDate(43845);

Parameters:

Name	Type	Description
inputNumber	number	number of days since nullDate, should be non-negative, fractions are ignored.

Returns: DateTime

---

numberToDateTime

▸ numberToDateTime(inputNumber: number): DateTime

Defined in hyperformula/src/HyperFormula.ts:4835

Interprets number as a date + time.

For more information, see the Date and time handling guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// pass the number of days since nullDate
// the method should return formatted date and time, for this example:
// {year: 2020, month: 1, day: 15, hours: 2, minutes: 24, seconds: 0}
const dateTimeFromNumber = hfInstance.numberToDateTime(43845.1);

Parameters:

Name	Type	Description
inputNumber	number	number of days since nullDate, should be non-negative, fractions are interpreted as hours/minutes/seconds.

Returns: DateTime

---

numberToTime

▸ numberToTime(inputNumber: number): DateTime

Defined in hyperformula/src/HyperFormula.ts:4886

Interprets number as a time (hours/minutes/seconds).

For more information, see the Date and time handling guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// pass a number to be interpreted as a time
// should return {hours: 26, minutes: 24} for this example
const timeFromNumber = hfInstance.numberToTime(1.1);

Parameters:

Name	Type	Description
inputNumber	number	time in 24h units.

Returns: DateTime

---

simpleCellAddressFromString

▸ simpleCellAddressFromString(cellAddress: string, contextSheetId: number): SimpleCellAddress | undefined

Defined in hyperformula/src/HyperFormula.ts:3196

Computes the simple (absolute) address of a cell address, based on its string representation.

• If a sheet name is present in the string representation but is not present in the engine, returns undefined.
• If no sheet name is present in the string representation, uses contextSheetId as a sheet id in the returned address.

For more information, see the Cell references guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
hfInstance.addSheet('Sheet0'); //sheetId = 0

// returns { sheet: 42, col: 0, row: 0 }
const simpleCellAddress = hfInstance.simpleCellAddressFromString('A1', 42);

// returns { sheet: 0, col: 0, row: 5 }
const simpleCellAddress = hfInstance.simpleCellAddressFromString('Sheet0!A6', 42);

// returns { sheet: 0, col: 0, row: 5 }
const simpleCellAddress = hfInstance.simpleCellAddressFromString('Sheet0!$A$6', 42);

// returns 'undefined', as there's no 'Sheet 2' in the HyperFormula instance
const simpleCellAddress = hfInstance.simpleCellAddressFromString('Sheet2!A6', 42);

Parameters:

Name	Type	Description
cellAddress	string	string representation of cell address in A1 notation
contextSheetId	number	sheet id used to construct the simple address in case of missing sheet name in cellAddress argument

Returns: SimpleCellAddress | undefined

---

simpleCellAddressToString

▸ simpleCellAddressToString(cellAddress: SimpleCellAddress, optionsOrContextSheetId: object | number): undefined | string

Defined in hyperformula/src/HyperFormula.ts:3265

Computes string representation of an absolute address in A1 notation. If cellAddress.sheet is not present in the engine, returns undefined.

For more information, see the Cell references guide.

throws ExpectedValueOfTypeError if its arguments are of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
hfInstance.addSheet('Sheet0'); //sheetId = 0
const addr = { sheet: 0, col: 1, row: 1 };

// should return 'B2'
const A1Notation = hfInstance.simpleCellAddressToString(addr);

// should return 'B2'
const A1Notation = hfInstance.simpleCellAddressToString(addr, { includeSheetName: false });

// should return 'Sheet0!B2'
const A1Notation = hfInstance.simpleCellAddressToString(addr, { includeSheetName: true });

// should return 'B2' as context sheet id is the same as addr.sheet
const A1Notation = hfInstance.simpleCellAddressToString(addr, 0);

// should return 'Sheet0!B2' as context sheet id is different from addr.sheet
const A1Notation = hfInstance.simpleCellAddressToString(addr, 42);

Parameters:

Name	Type	Default	Description
cellAddress	SimpleCellAddress	-	object representation of an absolute address
optionsOrContextSheetId	object | number	{}	options object or number used as context sheet id to construct the string address (see examples)

Returns: undefined | string

---

simpleCellRangeFromString

▸ simpleCellRangeFromString(cellRange: string, contextSheetId: number): SimpleCellRange | undefined

Defined in hyperformula/src/HyperFormula.ts:3225

Computes simple (absolute) address of a cell range based on its string representation. If sheet name is present in string representation but not present in the engine, returns undefined.

For more information, see the Cell references guide.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
hfInstance.addSheet('Sheet0'); //sheetId = 0

// should return { start: { sheet: 0, col: 0, row: 0 }, end: { sheet: 0, col: 1, row: 0 } }
const simpleCellAddress = hfInstance.simpleCellRangeFromString('A1:A2', 0);

Parameters:

Name	Type	Description
cellRange	string	string representation of cell range in A1 notation
contextSheetId	number	sheet id used to construct the simple address in case of missing sheet name in cellRange argument

Returns: SimpleCellRange | undefined

---

simpleCellRangeToString

▸ simpleCellRangeToString(cellRange: SimpleCellRange, optionsOrContextSheetId: object | number): string | undefined

Defined in hyperformula/src/HyperFormula.ts:3318

Computes string representation of an absolute range in A1 notation. Returns undefined if:

• cellRange is not a valid range,
• cellRange.start.sheet and cellRange.start.end are different,
• cellRange.start.sheet is not present in the engine,
• cellRange.start.end is not present in the engine.

Note: This method is useful only for cell ranges; does not work with column ranges and row ranges.

For more information, see the Cell references guide.

throws ExpectedValueOfTypeError if its arguments are of wrong type

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
hfInstance.addSheet('Sheet0'); //sheetId = 0
const range = { start: { sheet: 0, col: 1, row: 1 }, end: { sheet: 0, col: 2, row: 1 } };

// should return 'B2:C2'
const A1Notation = hfInstance.simpleCellRangeToString(range);

// should return 'B2:C2'
const A1Notation = hfInstance.simpleCellRangeToString(range, { includeSheetName: false });

// should return 'Sheet0!B2:C2'
const A1Notation = hfInstance.simpleCellRangeToString(range, { includeSheetName: true });

// should return 'B2:C2' as context sheet id is the same as range.start.sheet and range.end.sheet
const A1Notation = hfInstance.simpleCellRangeToString(range, 0);

// should return 'Sheet0!B2:C2' as context sheet id is different from range.start.sheet and range.end.sheet
const A1Notation = hfInstance.simpleCellRangeToString(range, 42);

Parameters:

Name	Type	Default	Description
cellRange	SimpleCellRange	-	object representation of an absolute range
optionsOrContextSheetId	object | number	{}	options object or number used as context sheet id to construct the string address (see examples)

Returns: string | undefined

---

validateFormula

▸ validateFormula(formulaString: string): boolean

Defined in hyperformula/src/HyperFormula.ts:4635

Validates the formula. If the provided string starts with “=” and is a parsable formula, the method returns true. The validation is purely grammatical: the method doesn’t verify if the formula can be calculated or not.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

// checks if the given string is a valid formula, should return 'true' for this example
const isFormula = hfInstance.validateFormula('=SUM(1, 2)');

Parameters:

Name	Type	Description
formulaString	string	a formula in a proper format - it must start with “=”

Returns: boolean

---

Clipboard

clearClipboard

▸ clearClipboard(): void

Defined in hyperformula/src/HyperFormula.ts:2642

Clears the clipboard content.

example

// clears the clipboard, isClipboardEmpty() should return true if called afterwards
hfInstance.clearClipboard();

The usage of the internal clipboard is described thoroughly in the Clipboard Operations guide.

Returns: void

---

copy

▸ copy(source: SimpleCellRange): CellValue[][]

Defined in hyperformula/src/HyperFormula.ts:2494

Stores a copy of the cell block in internal clipboard for the further paste. Returns the copied values for use in external clipboard.

For more information, see the Clipboard Operations guide.

throws NoSheetWithIdError when the given sheet ID does not exist

throws ExpectedValueOfTypeError if source is of wrong type

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Clipboard feature

example

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2'],
], { licenseKey: 'gpl-v3' });

// it copies [ [ 2 ] ]
const clipboardContent = hfInstance.copy({
  start: { sheet: 0, col: 1, row: 0 },
  end: { sheet: 0, col: 1, row: 0 },
});

The usage of the internal clipboard is described thoroughly in the Clipboard Operations guide.

Parameters:

Name	Type	Description
source	SimpleCellRange	rectangle range to copy

Returns: CellValue[][]

---

cut

▸ cut(source: SimpleCellRange): CellValue[][]

Defined in hyperformula/src/HyperFormula.ts:2536

Stores information of the cell block in internal clipboard for further paste. Calling paste right after this method is equivalent to call moveCells. Almost any CRUD operation called after this method will abort the cut operation. Returns the cut values for use in external clipboard.

For more information, see the Clipboard Operations guide.

throws ExpectedValueOfTypeError if source is of wrong type

throws SheetsNotEqual if range provided has distinct sheet numbers for start and end

throws NoSheetWithIdError when the given sheet ID does not exist

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Clipboard feature

example

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2'],
], { licenseKey: 'gpl-v3' });

// returns the values that were cut: [ [ 1 ] ]
const clipboardContent = hfInstance.cut({
  start: { sheet: 0, col: 0, row: 0 },
  end: { sheet: 0, col: 0, row: 0 },
});

The usage of the internal clipboard is described thoroughly in the Clipboard Operations guide.

Parameters:

Name	Type	Description
source	SimpleCellRange	rectangle range to cut

Returns: CellValue[][]

---

isClipboardEmpty

▸ isClipboardEmpty(): boolean

Defined in hyperformula/src/HyperFormula.ts:2625

Returns information whether there is something in the clipboard.

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
], { licenseKey: 'gpl-v3' });

// copy desired content
const clipboardContent = hfInstance.copy({
  start: { sheet: 0, col: 1, row: 0 },
  end: { sheet: 0, col: 1, row: 0 },
});

// returns 'false', there is content in the clipboard
const isClipboardEmpty = hfInstance.isClipboardEmpty();

The usage of the internal clipboard is described thoroughly in the Clipboard Operations guide.

Returns: boolean

---

paste

▸ paste(targetLeftCorner: SimpleCellAddress): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:2589

When called after copy it pastes copied values and formulas into a cell block. When called after cut it performs moveCells operation into the cell block. Does nothing if the clipboard is empty.

For more information, see the Clipboard Operations guide.

Returns an array of cells whose values changed as a result of this operation.

Note that this method may trigger dependency graph recalculation.

fires valuesUpdated if recalculation was triggered by this change

throws NoSheetWithIdError when the given sheet ID does not exist

throws EvaluationSuspendedError when the evaluation is suspended

throws SheetSizeLimitExceededError when performing this operation would result in sheet size limits exceeding

throws NothingToPasteError when clipboard is empty

throws TargetLocationHasArrayError when the selected target area has array inside

throws ExpectedValueOfTypeError if targetLeftCorner is of wrong type

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Clipboard feature

example

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2'],
], { licenseKey: 'gpl-v3' });

// [ [ 2 ] ] was copied
const clipboardContent = hfInstance.copy({
  start: { sheet: 0, col: 1, row: 0 },
  end: { sheet: 0, col: 1, row: 0 },
});

// returns a list of modified cells: their absolute addresses and new values
const changes = hfInstance.paste({ sheet: 0, col: 1, row: 0 });

The usage of the internal clipboard is described thoroughly in the Clipboard Operations guide.

Parameters:

Name	Type	Description
targetLeftCorner	SimpleCellAddress	upper left address of the target cell block

Returns: ExportedChange[]

---

Undo and Redo

clearRedoStack

▸ clearRedoStack(): void

Defined in hyperformula/src/HyperFormula.ts:2672

Clears the redo stack in undoRedo history.

For more information, see the Undo-Redo guide.

example

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2', '3'],
], { licenseKey: 'gpl-v3' });

// do an operation, for example remove columns
hfInstance.removeColumns(0, [0, 1]);

// undo the operation
hfInstance.undo();

// redo the operation
hfInstance.redo();

// clear the redo stack
hfInstance.clearRedoStack();

Returns: void

---

clearUndoStack

▸ clearUndoStack(): void

Defined in hyperformula/src/HyperFormula.ts:2699

Clears the undo stack in undoRedo history.

For more information, see the Undo-Redo guide.

example

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2', '3'],
], { licenseKey: 'gpl-v3' });

// do an operation, for example remove columns
hfInstance.removeColumns(0, [0, 1]);

// undo the operation
hfInstance.undo();

// clear the undo stack
hfInstance.clearUndoStack();

Returns: void

---

isThereSomethingToRedo

▸ isThereSomethingToRedo(): boolean

Defined in hyperformula/src/HyperFormula.ts:1387

Checks if there is at least one operation that can be re-done. Returns false also when the license key does not allow the UndoRedo feature (see LicenseCapabilityMissingError).

For more information, see the Undo-Redo guide.

example

hfInstance.undo();

// when there is an action to redo, this returns 'true'
const isSomethingToRedo = hfInstance.isThereSomethingToRedo();

Returns: boolean

---

isThereSomethingToUndo

▸ isThereSomethingToUndo(): boolean

Defined in hyperformula/src/HyperFormula.ts:1364

Checks if there is at least one operation that can be undone. Returns false also when the license key does not allow the UndoRedo feature (see LicenseCapabilityMissingError).

For more information, see the Undo-Redo guide.

example

const hfInstance = HyperFormula.buildFromArray([
 ['1'],
 ['2'],
 ['3'],
], { licenseKey: 'gpl-v3' });

// 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();

Returns: boolean

---

redo

▸ redo(): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1334

Re-do recently undone operation.

For more information, see the Undo-Redo guide.

Returns an array of cells whose values changed as a result of this 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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the UndoRedo feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['1'],
 ['2'],
 ['3'],
], { licenseKey: 'gpl-v3' });

// perform CRUD operation, for example remove the second row
hfInstance.removeRows(0, [1, 1]);

// undo the operation, it should return previous 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();

Returns: ExportedChange[]

---

undo

▸ undo(): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:1294

Undo the previous operation.

For more information, see the Undo-Redo guide.

Returns an array of cells whose values changed as a result of this 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

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the UndoRedo feature

example

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
 ['3', ''],
], { licenseKey: 'gpl-v3' });

// perform CRUD operation, for example remove the second row
hfInstance.removeRows(0, [1, 1]);

// undo the operation, it should return the changes
const changes = hfInstance.undo();

Returns: ExportedChange[]

---

Batch

batch

▸ batch(batchOperations: function): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:3894

Runs the provided callback as a single batch operation and returns the changed cells.

Returns an array of cells whose values changed as a result of all batched operations.

Note that this method may trigger dependency graph recalculation.

fires valuesUpdated if recalculation was triggered by this change

fires evaluationSuspended always

fires evaluationResumed after the recomputation of necessary values

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Batching feature

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// multiple operations in a single callback will trigger evaluation only once
// and only one set of changes is returned as a combined result of all
// the operations that were triggered within the callback
const changes = hfInstance.batch(() => {
 hfInstance.setCellContents({ col: 3, row: 0, sheet: 0 }, [['=B1']]);
 hfInstance.setCellContents({ col: 4, row: 0, sheet: 0 }, [['=A1']]);
});

Parameters:

▪ batchOperations: function

a function with operations to be performed

▸ (): void

Returns: ExportedChange[]

---

isEvaluationSuspended

▸ isEvaluationSuspended(): boolean

Defined in hyperformula/src/HyperFormula.ts:4016

Checks if the dependency graph recalculation process is suspended or not.

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// suspend the evaluation
hfInstance.suspendEvaluation();

// between suspendEvaluation() and resumeEvaluation()
// or inside batch() callback it will return 'true', otherwise 'false'
const isEvaluationSuspended = hfInstance.isEvaluationSuspended();

const changes = hfInstance.resumeEvaluation();

Returns: boolean

---

resumeEvaluation

▸ resumeEvaluation(): ExportedChange[]

Defined in hyperformula/src/HyperFormula.ts:3981

Resumes the dependency graph recalculation that was suspended with suspendEvaluation. It also triggers the recalculation and returns an array of cells whose values changed as a result of all batched operations.

fires valuesUpdated if recalculation was triggered by this change

fires evaluationResumed after the recomputation of necessary values

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// similar to batch() but operations are not within a callback,
// one method suspends the recalculation
// the second will resume calculations and return the changes

// first, suspend the evaluation
hfInstance.suspendEvaluation();

// perform operations
hfInstance.setCellContents({ col: 3, row: 0, sheet: 0 }, [['=B1']]);
hfInstance.setSheetContent(1, [['50'], ['60']]);

// resume the evaluation
const changes = hfInstance.resumeEvaluation();

Returns: ExportedChange[]

---

suspendEvaluation

▸ suspendEvaluation(): void

Defined in hyperformula/src/HyperFormula.ts:3944

Suspends the dependency graph recalculation to start a batch operation. It allows optimizing the performance. With this method, multiple CRUD operations can be done without triggering recalculation after every operation. Suspending evaluation should result in an overall faster calculation compared to recalculating after each operation separately. To resume the evaluation use resumeEvaluation.

fires evaluationSuspended always

throws LicenseCapabilityMissingError if the license key is missing or invalid, has expired and blocks evaluation, or does not grant the Batching feature

example

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['1'] ],
 MySheet2: [ ['10'] ],
}, { licenseKey: 'gpl-v3' });

// similar to batch() but operations are not within a callback,
// one method suspends the recalculation
// the second will resume calculations and return the changes

// suspend the evaluation with this method
hfInstance.suspendEvaluation();

// perform operations
hfInstance.setCellContents({ col: 3, row: 0, sheet: 0 }, [['=B1']]);
hfInstance.setSheetContent(1, [['50'], ['60']]);

// use resumeEvaluation to resume
const changes = hfInstance.resumeEvaluation();

Returns: void

---

Events

off

▸ off‹Event›(event: Event, listener: Listeners[Event]): void

Defined in hyperformula/src/HyperFormula.ts:4972

Unsubscribes from an event or from all events. For the list of all available events, see Listeners.

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// define a simple function to be called upon emitting an event
const handler = ( ) => { console.log('baz') }

// subscribe to a 'sheetAdded', pass the handler
hfInstance.on('sheetAdded', handler);

// add a sheet to trigger an event,
// console should print 'baz' each time a sheet is added
hfInstance.addSheet('FooBar');

// unsubscribe from a 'sheetAdded'
hfInstance.off('sheetAdded', handler);

// add a sheet, the console should not print anything
hfInstance.addSheet('FooBaz');

Type parameters:

▪ Event: keyof Listeners

Parameters:

Name	Type	Description
event	Event	the name of the event to subscribe to
listener	Listeners[Event]	to be called when event is emitted

Returns: void

---

on

▸ on‹Event›(event: Event, listener: Listeners[Event]): void

Defined in hyperformula/src/HyperFormula.ts:4912

Subscribes to an event. For the list of all available events, see Listeners.

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// subscribe to a 'sheetAdded', pass a simple handler
hfInstance.on('sheetAdded', ( ) => { console.log('foo') });

// add a sheet to trigger an event,
// console should print 'foo' after each time sheet is added in this example
hfInstance.addSheet('FooBar');

Type parameters:

▪ Event: keyof Listeners

Parameters:

Name	Type	Description
event	Event	the name of the event to subscribe to
listener	Listeners[Event]	to be called when event is emitted

Returns: void

---

once

▸ once‹Event›(event: Event, listener: Listeners[Event]): void

Defined in hyperformula/src/HyperFormula.ts:4938

Subscribes to an event once. For the list of all available events, see Listeners.

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// subscribe to a 'sheetAdded', pass a simple handler
hfInstance.once('sheetAdded', ( ) => { console.log('foo') });

// call addSheet twice,
// console should print 'foo' only once when the sheet is added in this example
hfInstance.addSheet('FooBar');
hfInstance.addSheet('FooBaz');

Type parameters:

▪ Event: keyof Listeners

Parameters:

Name	Type	Description
event	Event	the name of the event to subscribe to
listener	Listeners[Event]	to be called when event is emitted

Returns: void

---

Custom Functions

getAllFunctionPlugins

▸ getAllFunctionPlugins(): FunctionPluginDefinition[]

Defined in hyperformula/src/HyperFormula.ts:4709

Returns classes of all plugins registered in this instance of HyperFormula

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// return classes of all plugins registered, assign to a variable
const allNames = hfInstance.getAllFunctionPlugins();

Returns: FunctionPluginDefinition[]

---

getFunctionPlugin

▸ getFunctionPlugin(functionId: string): FunctionPluginDefinition | undefined

Defined in hyperformula/src/HyperFormula.ts:4691

Returns class of a plugin used by function with given id

For more information, see the Custom functions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

// import your own plugin
import { MyExamplePlugin } from './file_with_your_plugin';

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// register a plugin
HyperFormula.registerFunctionPlugin(MyExamplePlugin);

// get the plugin
const myPlugin = hfInstance.getFunctionPlugin('EXAMPLE');

Parameters:

Name	Type	Description
functionId	string	id of a function, e.g., ‘SUMIF’

Returns: FunctionPluginDefinition | undefined

---

getRegisteredFunctionNames

▸ getRegisteredFunctionNames(): string[]

Defined in hyperformula/src/HyperFormula.ts:4661

Returns translated names of all functions registered in this instance of HyperFormula according to the language set in the configuration

Answers for the instance’s function REGISTRY — what is registered, not what the license key lets it evaluate — so it lists every registered function whatever the key grants. To build a function picker that never offers a function evaluating to #LIC!, use getAvailableFunctions, which answers about availability.

example

const hfInstance = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

// return translated names of all functions, assign to a variable
const allNames = hfInstance.getRegisteredFunctionNames();

Returns: string[]

---

Static Methods

getAllFunctionPlugins

Static

▸ getAllFunctionPlugins(): FunctionPluginDefinition[]

Defined in hyperformula/src/HyperFormula.ts:669

Returns classes of all plugins registered in HyperFormula.

example

// return classes of all plugins
const allClasses = HyperFormula.getAllFunctionPlugins();

Returns: FunctionPluginDefinition[]

---

getFunctionPlugin

Static

▸ getFunctionPlugin(functionId: string): FunctionPluginDefinition | undefined

Defined in hyperformula/src/HyperFormula.ts:653

Returns class of a plugin used by function with given id

For more information, see the Custom functions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

// 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');

Parameters:

Name	Type	Description
functionId	string	id of a function, e.g., ‘SUMIF’

Returns: FunctionPluginDefinition | undefined

---

getLanguage

Static

▸ getLanguage(languageCode: string): TranslationPackage

Defined in hyperformula/src/HyperFormula.ts:382

Returns registered language from its code string.

For more information, see the Localizing functions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws LanguageNotRegisteredError when trying to retrieve not registered language

example

// return registered language
const language = HyperFormula.getLanguage('enGB');

Parameters:

Name	Type	Description
languageCode	string	code string of the translation package

Returns: TranslationPackage

---

getRegisteredFunctionNames

Static

▸ getRegisteredFunctionNames(code: string): string[]

Defined in hyperformula/src/HyperFormula.ts:623

Returns translated names of all registered functions for a given language.

Answers for the GLOBAL function registry, because a static method has no engine, and therefore no configuration, in scope. An engine configured with its own functionPlugins registers only those, so this method can list functions that engine cannot evaluate at all.

The two forms answer different questions and neither replaces the other: this one translates into any registered language without building an engine, while the instance method of the same name answers for the engine you actually hold, in that instance’s own language. Neither form looks at the license key: to list only the functions an instance can evaluate, use getAvailableFunctions.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

// return a list of function names registered for enGB
const allNames = HyperFormula.getRegisteredFunctionNames('enGB');

Parameters:

Name	Type	Description
code	string	language code

Returns: string[]

---

getRegisteredLanguagesCodes

Static

▸ getRegisteredLanguagesCodes(): string[]

Defined in hyperformula/src/HyperFormula.ts:463

Returns all registered languages codes.

example

// should return all registered language codes: ['enGB', 'plPL']
const registeredLanguages = HyperFormula.getRegisteredLanguagesCodes();

Returns: string[]

---

registerFunction

Static

▸ registerFunction(functionId: string, plugin: FunctionPluginDefinition, translations?: FunctionTranslationsPackage): void

Defined in hyperformula/src/HyperFormula.ts:547

Registers a function with a given id if such exists in a plugin.

For more information, see the Custom functions guide.

Note: This method does not affect the existing HyperFormula instances.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws FunctionPluginValidationError when function with a given id does not exist in plugin or plugin class definition is not consistent with metadata

throws ProtectedFunctionTranslationError when trying to register translation for protected function

example

// import your own plugin
import { MyExamplePlugin } from './file_with_your_plugin';

// register a function
HyperFormula.registerFunction('EXAMPLE', MyExamplePlugin);

Parameters:

Name	Type	Description
functionId	string	function id, e.g., ‘SUMIF’
plugin	FunctionPluginDefinition	plugin class
translations?	FunctionTranslationsPackage	translations for the function name

Returns: void

---

registerFunctionPlugin

Static

▸ registerFunctionPlugin(plugin: FunctionPluginDefinition, translations?: FunctionTranslationsPackage): void

Defined in hyperformula/src/HyperFormula.ts:493

Registers all functions in a given plugin with optional translations.

For more information, see the Custom functions guide.

Note: FunctionPlugins must be registered prior to the creation of HyperFormula instances in which they are used. HyperFormula instances created prior to the registration of a FunctionPlugin are unable to access the FunctionPlugin. Registering a FunctionPlugin with [[custom-functions]] requires the translations parameter.

throws FunctionPluginValidationError when plugin class definition is not consistent with metadata

throws ProtectedFunctionTranslationError when trying to register translation for protected function

example

// import your own plugin
import { MyExamplePlugin } from './file_with_your_plugin';

// register the plugin
HyperFormula.registerFunctionPlugin(MyExamplePlugin);

Parameters:

Name	Type	Description
plugin	FunctionPluginDefinition	plugin class
translations?	FunctionTranslationsPackage	optional package of function names translations

Returns: void

---

registerLanguage

Static

▸ registerLanguage(languageCode: string, languagePackage: RawTranslationPackage): void

Defined in hyperformula/src/HyperFormula.ts:413

Registers language under given code string.

For more information, see the Localizing functions guide.

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

// return registered language
HyperFormula.registerLanguage('enUS', enUS);
const engine = HyperFormula.buildEmpty({licenseKey: 'gpl-v3', language: 'enUS'});

Parameters:

Name	Type	Description
languageCode	string	code string of the translation package
languagePackage	RawTranslationPackage	translation package to be registered

Returns: void

---

unregisterAllFunctions

Static

▸ unregisterAllFunctions(): void

Defined in hyperformula/src/HyperFormula.ts:594

Clears function registry.

Note: This method does not affect the existing HyperFormula instances.

example

HyperFormula.unregisterAllFunctions();

Returns: void

---

unregisterFunction

Static

▸ unregisterFunction(functionId: string): void

Defined in hyperformula/src/HyperFormula.ts:577

Unregisters a function with a given id.

For more information, see the Custom functions guide.

Note: This method does not affect the existing HyperFormula instances.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

example

// import your own plugin
import { MyExamplePlugin } from './file_with_your_plugin';

// register a function
HyperFormula.registerFunction('EXAMPLE', MyExamplePlugin);

// unregister a function
HyperFormula.unregisterFunction('EXAMPLE');

Parameters:

Name	Type	Description
functionId	string	function id, e.g., ‘SUMIF’

Returns: void

---

unregisterFunctionPlugin

Static

▸ unregisterFunctionPlugin(plugin: FunctionPluginDefinition): void

Defined in hyperformula/src/HyperFormula.ts:517

Unregisters all functions defined in given plugin.

For more information, see the Custom functions guide.

Note: This method does not affect the existing HyperFormula instances.

example

// get the class of a plugin
const registeredPluginClass = HyperFormula.getFunctionPlugin('EXAMPLE');

// unregister all functions defined in a plugin of ID 'EXAMPLE'
HyperFormula.unregisterFunctionPlugin(registeredPluginClass);

Parameters:

Name	Type	Description
plugin	FunctionPluginDefinition	plugin class

Returns: void

---

unregisterLanguage

Static

▸ unregisterLanguage(languageCode: string): void

Defined in hyperformula/src/HyperFormula.ts:443

Unregisters language that is registered under given code string.

For more information, see the Localizing functions guide.

throws ExpectedValueOfTypeError if any of its basic type argument is of wrong type

throws LanguageNotRegisteredError when given language is not registered

example

// register the language for the instance
HyperFormula.registerLanguage('plPL', plPL);

// unregister plPL
HyperFormula.unregisterLanguage('plPL');

Parameters:

Name	Type	Description
languageCode	string	code string of the translation package

Returns: void