Workbook
Individual workbook within a model. Contains Sheets which contain Cells. Contains its own dependency graph, for now at least, so no dependencies between workbooks.
Extends
Section titled “Extends”emitter
Implements
Section titled “Implements”Properties
Section titled “Properties”_cellContainerForGlobals
Section titled “_cellContainerForGlobals”_cellContainerForGlobals:
CellContainer
_cellsWithErrors
Section titled “_cellsWithErrors”_cellsWithErrors:
VertexIdSet<CellVertexId|NameVertexId>
Vertex ID keys of cells with errors.
_errors
Section titled “_errors”_errors:
ModelError[] =[]
_errorsByMsg
Section titled “_errorsByMsg”_errorsByMsg:
object={}
Index Signature
Section titled “Index Signature”[message: string]: ModelError
_globals
Section titled “_globals”_globals:
Record<string,DefinedName> ={}
_iterativeCalculationSettings
Section titled “_iterativeCalculationSettings”_iterativeCalculationSettings:
null|IterativeCalculationOptions
_model
Section titled “_model”_model:
Model
_rangeWrites
Section titled “_rangeWrites”_rangeWrites:
RangeVertexId[] =[]
VertexIDs of range writes applied in this workbook. Redundant with
this._writes, maintained separately just for quick checking.
_sheets
Section titled “_sheets”_sheets:
WorkSheet[] =[]
_state
Section titled “_state”_state:
undefined|"uploading"|"processing"|"ready"|"invalid"|"replaced"
_tables
Section titled “_tables”_tables:
Map<string,Table>
_writes
Section titled “_writes”_writes:
Map<string,CellValue>
Map keyed by strings, where each string is the key of a Vertex ID
cellEvaluator
Section titled “cellEvaluator”cellEvaluator:
CellEvaluator
cellsWithNeutralizedFormulas
Section titled “cellsWithNeutralizedFormulas”cellsWithNeutralizedFormulas:
Set<Cell|DefinedName>
charts
Section titled “charts”charts:
ChartCSF[]
cloud_connection
Section titled “cloud_connection”cloud_connection:
null|CloudConnection
coerceNullToZero
Section titled “coerceNullToZero”coerceNullToZero:
CoercionMode=COERCE_NONE
Dummy declaration for type checker, overridden with defineProperty in constructor
Implementation of
Section titled “Implementation of”EvaluationContext.coerceNullToZero
defect
Section titled “defect”defect:
null|string
evaluateASTNode()
Section titled “evaluateASTNode()”evaluateASTNode: (
ast) =>MaybeBoxedFormulaArgument
Evaluate an expression, expressed as an AST node, in this context.
NOTE: this must be a function, not arrow function, and be invoked on an
evaluation context, so that it captures the correct this context.
Parameters
Section titled “Parameters”ASTNode
Returns
Section titled “Returns”Implementation of
Section titled “Implementation of”EvaluationContext.evaluateASTNode
externals
Section titled “externals”externals:
External[]
getWorkbookByKey()
Section titled “getWorkbookByKey()”getWorkbookByKey: (
key) =>undefined|Workbook
Get the workbook with the given dependency-graph key (based uniquely on the
workbook name in a case-insensitive way by the wbNameToKey function).
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”undefined | Workbook
Implementation of
Section titled “Implementation of”EvaluationContext.getWorkbookByKey
id:
string
instanceId
Section titled “instanceId”instanceId:
number
isExternal
Section titled “isExternal”isExternal:
boolean
Whether this workbook was loaded as an external reference from another workbook.
keyInDepGraph
Section titled “keyInDepGraph”keyInDepGraph:
number
metadata
Section titled “metadata”metadata:
GridMetadata
mode:
WorkbookMode
Implementation of
Section titled “Implementation of”name:
string
names:
DefinedName[] =[]
ready:
boolean=false
replacedBy
Section titled “replacedBy”replacedBy:
null|string=null
reserved for outside use (client loader)
resolveName()
Section titled “resolveName()”resolveName: (
name,sheetName?) =>FormulaError|DefinedName
Get the cell object for the given defined name (matched case-insensitively)
in the indicated scope or in this context. If sheetName is given, then
only sheet-scoped defined names will be considered, not workbook-scoped
defined names. If this context permits cross-workbook name resolution, then
a match in the current workbook will be preferred but if no match is found
there, then the first match across all workbooks in model order will be
returned. If no match is found, #NAME? is returned.
Parameters
Section titled “Parameters”string
sheetName?
Section titled “sheetName?”null | string
Returns
Section titled “Returns”Implementation of
Section titled “Implementation of”resolveSheet()
Section titled “resolveSheet()”resolveSheet: (
sheetName?,workbookName?) =>null|WorkSheet
Get the sheet with the given name (matched case-insensitively), or the first sheet of the context workbook if no name is given. The context workbook is the default (first) workbook of the model if not evaluating in the context of a specific workbook.
Parameters
Section titled “Parameters”sheetName?
Section titled “sheetName?”null | string
workbookName?
Section titled “workbookName?”null | string
Returns
Section titled “Returns”null | WorkSheet
Implementation of
Section titled “Implementation of”EvaluationContext.resolveSheet
resolveTable()
Section titled “resolveTable()”resolveTable: (
name,workbookName?) =>null|Table
Get the table with the given name (matched case-insensitively) in the context workbook, or if not found there, then in the first workbook in the model that contains a table by this name.
Parameters
Section titled “Parameters”string
workbookName?
Section titled “workbookName?”null | string
Returns
Section titled “Returns”null | Table
Implementation of
Section titled “Implementation of”EvaluationContext.resolveTable
resolveWorkbook()
Section titled “resolveWorkbook()”resolveWorkbook: (
name?) =>undefined|Workbook
Get the workbook with the given case-insensitive name, or if no name is
given, the context workbook, or the default (first) workbook of the model
if not evaluating in the context of a specific workbook.
Parameters
Section titled “Parameters”null | string
Returns
Section titled “Returns”undefined | Workbook
Implementation of
Section titled “Implementation of”EvaluationContext.resolveWorkbook
sheetNameToIndex
Section titled “sheetNameToIndex”sheetNameToIndex:
object={}
Index Signature
Section titled “Index Signature”[name: string]: number
styles
Section titled “styles”
readonlystyles:StyleManager
type:
"unknown"|"airtable"|"notion"|"smartsheet"|"csv"|"excel"|"form-submissions"|"google-sheets"|"native"
The origin of the workbook (Excel, Google Sheets, CSV, etc).
update_time
Section titled “update_time”update_time:
undefined|string
version
Section titled “version”version:
undefined|number
views?
Section titled “views?”
optionalviews:WorkbookView[]
workbookName
Section titled “workbookName”workbookName:
string=''
Dummy declaration for type checker, overridden with defineProperty in constructor
Implementation of
Section titled “Implementation of”EvaluationContext.workbookName
writeState()
Section titled “writeState()”writeState: () =>
any
Returns
Section titled “Returns”any
Implementation of
Section titled “Implementation of”Accessors
Section titled “Accessors”editable
Section titled “editable”Get Signature
Section titled “Get Signature”get editable():
boolean
Returns
Section titled “Returns”boolean
Get Signature
Section titled “Get Signature”get env():
Map<"isPrint"|"isMobile"|"username",MaybeBoxedFormulaArgument>
Returns
Section titled “Returns”Map<"isPrint" | "isMobile" | "username", MaybeBoxedFormulaArgument>
Implementation of
Section titled “Implementation of”errorLevel
Section titled “errorLevel”Get Signature
Section titled “Get Signature”get errorLevel():
number
Returns
Section titled “Returns”number
errors
Section titled “errors”Get Signature
Section titled “Get Signature”get errors():
ModelError[]
Returns
Section titled “Returns”lazyImportPromise
Section titled “lazyImportPromise”Get Signature
Section titled “Get Signature”get lazyImportPromise():
Promise<void>
Returns
Section titled “Returns”Promise<void>
Methods
Section titled “Methods”_addSheet()
Section titled “_addSheet()”_addSheet(
sheetName,index,hidden):WorkSheet
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
number
hidden
Section titled “hidden”0 | 1 | 2
Returns
Section titled “Returns”_applyCalcCellResult()
Section titled “_applyCalcCellResult()”_applyCalcCellResult(
newValue,cell,ref,recordDependencyUse?):object
Parameters
Section titled “Parameters”newValue
Section titled “newValue”result of formula evaluation
the cell whose formula was evaluated
Reference to the cell
recordDependencyUse?
Section titled “recordDependencyUse?”(ref) => void
optional callback for recording dependencies during recalc
Returns
Section titled “Returns”object
change
Section titled “change”change:
number|boolean
changedRefs
Section titled “changedRefs”changedRefs:
Reference[]
_applyWrite()
Section titled “_applyWrite()”_applyWrite(
refStr,value,oldSheetCount,oldSheetIndex):void
Write value value to the given reference, or to the same address in
the sheet with index oldSheetIndex if sheet count matches oldSheetCount
Parameters
Section titled “Parameters”refStr
Section titled “refStr”string
oldSheetCount
Section titled “oldSheetCount”number
oldSheetIndex
Section titled “oldSheetIndex”null | number
Returns
Section titled “Returns”void
_clearExistingModelErrors()
Section titled “_clearExistingModelErrors()”_clearExistingModelErrors(
vertexId):void
Parameters
Section titled “Parameters”vertexId
Section titled “vertexId”CellVertexId | NameVertexId | RangeVertexId
Returns
Section titled “Returns”void
_createFormulaRewriterForColumnDeletion()
Section titled “_createFormulaRewriterForColumnDeletion()”_createFormulaRewriterForColumnDeletion(
sheet,column,count):RewriteFormula
Create a formula rewriting function for column deletion. This does NOT actually delete any cell data - it only creates a function that rewrites formulas to account for deleted columns (e.g., updating references or converting them to #REF! errors).
Parameters
Section titled “Parameters”The worksheet where columns are being deleted
column
Section titled “column”number
0-based column index of the first column to delete
number
The number of columns being deleted
Returns
Section titled “Returns”A function that rewrites formulas to reflect the column deletion
_createFormulaRewriterForRowDeletion()
Section titled “_createFormulaRewriterForRowDeletion()”_createFormulaRewriterForRowDeletion(
sheet,row,count):RewriteFormula
Create a formula rewriting function for row deletion. This does NOT actually delete any cell data - it only creates a function that rewrites formulas to account for deleted rows (e.g., updating references or converting them to #REF! errors).
Parameters
Section titled “Parameters”The worksheet where rows are being deleted
number
0-based row index of the first row to delete
number
The number of rows being deleted
Returns
Section titled “Returns”A function that rewrites formulas to reflect the row deletion
_createRewriteFormulaFunction()
Section titled “_createRewriteFormulaFunction()”_createRewriteFormulaFunction(
from,to):RewriteFormula
Parameters
Section titled “Parameters”Returns
Section titled “Returns”_createRewriteFormulaFunctionForDelete()
Section titled “_createRewriteFormulaFunctionForDelete()”_createRewriteFormulaFunctionForDelete(
deleteRef):RewriteFormula
Parameters
Section titled “Parameters”deleteRef
Section titled “deleteRef”Returns
Section titled “Returns”_getExistingCachedFormulaCell()
Section titled “_getExistingCachedFormulaCell()”_getExistingCachedFormulaCell(
formula,prefix):object
Parameters
Section titled “Parameters”formula
Section titled “formula”string
prefix
Section titled “prefix”string = CACHED_FORMULA_CELL_ID_PREFIX
Returns
Section titled “Returns”object
cell:
null|DefinedName
id:
string
_hasRangeWriteContaining()
Section titled “_hasRangeWriteContaining()”_hasRangeWriteContaining(
vertexId):boolean
Parameters
Section titled “Parameters”vertexId
Section titled “vertexId”Returns
Section titled “Returns”boolean
_insertSheet()
Section titled “_insertSheet()”_insertSheet(
sheet,index):WorkSheet
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”_markCellsReferencingRemovedSheetForRecalculation()
Section titled “_markCellsReferencingRemovedSheetForRecalculation()”_markCellsReferencingRemovedSheetForRecalculation(
sheetBeingRemoved):void
Parameters
Section titled “Parameters”sheetBeingRemoved
Section titled “sheetBeingRemoved”Returns
Section titled “Returns”void
_moveCellsByColumn()
Section titled “_moveCellsByColumn()”_moveCellsByColumn(
sheet,column,moveBy):RewriteFormula
Move all cells to the right or left of a column index.
Parameters
Section titled “Parameters”column
Section titled “column”number
0-based column index
moveBy
Section titled “moveBy”number
the number of positions to move the cells by. If negative, then the cells are moved to the left
Returns
Section titled “Returns”_moveCellsByRow()
Section titled “_moveCellsByRow()”_moveCellsByRow(
sheet,row,moveBy):RewriteFormula
Parameters
Section titled “Parameters”number
0-based row index
moveBy
Section titled “moveBy”number
the number of positions to move the cells by. If negative, then the cells are moved up
Returns
Section titled “Returns”_refPointsToAnotherWorkbook()
Section titled “_refPointsToAnotherWorkbook()”_refPointsToAnotherWorkbook(
reference):boolean
Parameters
Section titled “Parameters”reference
Section titled “reference”Returns
Section titled “Returns”boolean
_removeError()
Section titled “_removeError()”_removeError(
modelError):void
Parameters
Section titled “Parameters”modelError
Section titled “modelError”Returns
Section titled “Returns”void
_rewriteFormulasReferencingRenamedSheet()
Section titled “_rewriteFormulasReferencingRenamedSheet()”_rewriteFormulasReferencingRenamedSheet(
sheet,currentName,newName):void
Precondition: formula parser has finished importing (formulaParserReady has resolved).
Parameters
Section titled “Parameters”currentName
Section titled “currentName”string
newName
Section titled “newName”string
Returns
Section titled “Returns”void
_unneutralizeFormulas()
Section titled “_unneutralizeFormulas()”_unneutralizeFormulas():
void
Reinstate formulas previously neutralized by a write
Returns
Section titled “Returns”void
_updateDependenciesForWrittenFormulaCells()
Section titled “_updateDependenciesForWrittenFormulaCells()”_updateDependenciesForWrittenFormulaCells():
void
Returns
Section titled “Returns”void
_updateParsedFormula()
Section titled “_updateParsedFormula()”_updateParsedFormula(
cell):void
Precondition: formula parser has finished importing (formulaParserReady has resolved).
Parameters
Section titled “Parameters”a cell object representing a global defined name (that
restriction is relevant so that cell.id is its complete cell address,
because that assumption is made here.)
Returns
Section titled “Returns”void
_updateValueAndSpills()
Section titled “_updateValueAndSpills()”_updateValueAndSpills(
cellRef,cell,newValue,isRangeWrite?):Reference[]
Given a formula cell in a sheet, replace its existing value with a newly calculated one, in the case where either the new value or the previous value (or both) is a matrix. Determine and apply any blocking/unblocking of other spilling formula cells that should result from this change.
Parameters
Section titled “Parameters”cellRef
Section titled “cellRef”A reference pointing to cell. Must be an address (not name) reference.
The sheet formula cell whose value will be replaced
newValue
Section titled “newValue”The new value.
MaybeBoxed<CellValue> | Matrix
isRangeWrite?
Section titled “isRangeWrite?”boolean = false
passed to Cells.updateValueAndSpills, see documentation there
Returns
Section titled “Returns”references to all areas whose cells may have
changed, with the area spilled by cell (or a single-cell ref to just
that cell if it did not spill) appearing first, followed by any other
areas which may have changed due to spill blocking/unblocking.
_writesIter()
Section titled “_writesIter()”_writesIter():
IterableIterator<[string,CellValue,KnownVertexId]>
Precondition: Workbook must be initialized
Returns
Section titled “Returns”IterableIterator<[string, CellValue, KnownVertexId]>
addError()
Section titled “addError()”addError(
modelError):null|ModelError
Parameters
Section titled “Parameters”modelError
Section titled “modelError”Returns
Section titled “Returns”null | ModelError
addSheet()
Section titled “addSheet()”addSheet(
sheetName?,index?):WorkSheet
Add a new empty sheet to the workbook
Parameters
Section titled “Parameters”sheetName?
Section titled “sheetName?”if no sheet name is provided a unique sheet name will be generated
null | string
index?
Section titled “index?”number
if no index is provided the sheet will be appended to the list of sheets
Returns
Section titled “Returns”allDefinedNames()
Section titled “allDefinedNames()”allDefinedNames():
IterableIterator<DefinedName>
Returns
Section titled “Returns”IterableIterator<DefinedName>
applyWritesFrom()
Section titled “applyWritesFrom()”applyWritesFrom(
oldWorkbook):void
Parameters
Section titled “Parameters”oldWorkbook
Section titled “oldWorkbook”Workbook
Returns
Section titled “Returns”void
calcCell()
Section titled “calcCell()”calcCell(
cell,checkDirty?,recordDependencyUse?):CellChangeRecord
Calculate a new value for the given cell in this workbook. The cell should
either be a formula cell, or be a value cell which was previously a formula
cell, which gets passed here in order to calculate the spilling effects of
its change to a value cell. The cell’s unconditional static dependencies
are all assumed to be already up-to-date. The up-to-dateness of any other
dependencies is checked and an EvaluationOrderException is thrown if any
are not up-to-date). Assign the new value to the cell, and possibly to
other cells due to spilling. Return information about all cells changed.
Precondition: Workbook is initialized and has data.
Parameters
Section titled “Parameters”checkDirty?
Section titled “checkDirty?”boolean = true
true (the default) to check for dirty states of dependency cells and throw EvaluationOrderException; false to disable this check
recordDependencyUse?
Section titled “recordDependencyUse?”undefined | (ref) => void
Returns
Section titled “Returns”CellChangeRecord
a cell change record in which:
changeis the change in the cell value (numeric if the cell value changed from a number to another number, else true if the cell value changed but not from a number to a number, else false).changedRefsis a list of references to cell ranges which changed.
clearCachedFormula()
Section titled “clearCachedFormula()”clearCachedFormula(
formula):undefined|null
Parameters
Section titled “Parameters”formula
Section titled “formula”undefined | null | string
Returns
Section titled “Returns”undefined | null
clearCachedFormulasExcept()
Section titled “clearCachedFormulasExcept()”clearCachedFormulasExcept(
formulas):void
Parameters
Section titled “Parameters”formulas
Section titled “formulas”string[]
Returns
Section titled “Returns”void
clearCells()
Section titled “clearCells()”clearCells(
ref):boolean
Precondition: Workbook must be initialized
Parameters
Section titled “Parameters”A reference to the cell, or range of cells, to clear. Defined names are not supported.
string | Reference
Returns
Section titled “Returns”boolean
true if any changes were made (so a recalculation is in order).
deleteColumns()
Section titled “deleteColumns()”deleteColumns(
sheetName,columnIndex,count):RewriteFormula
Delete count columns at a specific index in the given sheet.
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
columnIndex
Section titled “columnIndex”number
0-based column index
number
how many columns should be deleted
Returns
Section titled “Returns”deleteRows()
Section titled “deleteRows()”deleteRows(
sheetName,rowIndex,count):RewriteFormula
Delete count rows at a specific index in the given sheet.
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
rowIndex
Section titled “rowIndex”number
0-based row index
number
how many rows should be deleted
Returns
Section titled “Returns”emit()
Section titled “emit()”emit(
event, …arguments_):Emitter
Emit an event, invoking all handlers registered for it.
Parameters
Section titled “Parameters”string
The name of the event to emit.
arguments_
Section titled “arguments_”…any[]
Arguments to pass to the event handlers.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.emit
evaluateAST()
Section titled “evaluateAST()”evaluateAST(
ast,options):MaybeBoxedFormulaValue
Evaluate a formula in the form of an AST, in a given evaluation context.
This wraps the evaluateAST function as a Workbook method, just to
enable calling it via evaluation context to dodge circular imports.
Parameters
Section titled “Parameters”ASTRootNode
options
Section titled “options”Partial<EvaluationContext>
Returns
Section titled “Returns”Implementation of
Section titled “Implementation of”getCachedFormulaCell()
Section titled “getCachedFormulaCell()”getCachedFormulaCell(
formula,calculateIfNew,prefix):null|DefinedName
Get or create a cached-formula defined-name object for the given formula.
Calculate its value unless false is passed for calculateIfNew.
Parameters
Section titled “Parameters”formula
Section titled “formula”undefined | null | string
calculateIfNew
Section titled “calculateIfNew”boolean = true
prefix
Section titled “prefix”string = CACHED_FORMULA_CELL_ID_PREFIX
Returns
Section titled “Returns”null | DefinedName
getCell()
Section titled “getCell()”getCell(
cellId,sheetName?):null|Cell
Parameters
Section titled “Parameters”cellId
Section titled “cellId”string
sheetName?
Section titled “sheetName?”null | string
Returns
Section titled “Returns”null | Cell
getGlobal()
Section titled “getGlobal()”getGlobal(
name):FormulaError|DefinedName
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”getSheet()
Section titled “getSheet()”getSheet(
sheetName?):null|WorkSheet
Parameters
Section titled “Parameters”sheetName?
Section titled “sheetName?”null | string
Returns
Section titled “Returns”null | WorkSheet
the named sheet if sheetName is truthy (null if not found), else the first sheet.
getSheetByIndex()
Section titled “getSheetByIndex()”getSheetByIndex(
index?):null|WorkSheet
Get a sheet of the given index or else, if index is not provided, the first sheet of this workbook.
Parameters
Section titled “Parameters”index?
Section titled “index?”the index of a sheet
null | number
Returns
Section titled “Returns”null | WorkSheet
the sheet found at the given index, or else the first sheet if none was given. If no sheets are present this method returns null.
getSheetIndex()
Section titled “getSheetIndex()”getSheetIndex(
sheetName?):null|number
Get the order index of a sheet with the given name.
Parameters
Section titled “Parameters”sheetName?
Section titled “sheetName?”string
the name of the sheet whose index should be returned. It will be matched case-insensitively.
Returns
Section titled “Returns”null | number
The index of the sheet with the given name, or null if no sheet with that name exists, or 0 if no/empty name was given.
getSheets()
Section titled “getSheets()”getSheets():
WorkSheet[]
Returns
Section titled “Returns”getSheetSize()
Section titled “getSheetSize()”getSheetSize(
sheetName?): [number,number]
Get the size of a sheet with the given name.
Parameters
Section titled “Parameters”sheetName?
Section titled “sheetName?”the name of the sheet whose size should be returned. It will be matched case-insensitively. If not provided, or empty, the size of the first sheet (0, 0) is returned.
null | string
Returns
Section titled “Returns”[number, number]
The size of the sheet with the given name, or null if no sheet with that name exists, or (0, 0) if no/empty name was given.
getTable()
Section titled “getTable()”getTable(
name):null|Table
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”null | Table
getTableContainingCell()
Section titled “getTableContainingCell()”getTableContainingCell(
sheet,cell):null|Table
Parameters
Section titled “Parameters”Returns
Section titled “Returns”null | Table
getTables()
Section titled “getTables()”getTables():
Table[]
Returns
Section titled “Returns”Table[]
hasListeners()
Section titled “hasListeners()”Call Signature
Section titled “Call Signature”hasListeners(
event):boolean
Check if there are any handlers registered for a specific event.
Parameters
Section titled “Parameters”string
The name of the event.
Returns
Section titled “Returns”boolean
true if there are one or more handlers, false otherwise.
Inherited from
Section titled “Inherited from”EventEmitter.hasListeners
Call Signature
Section titled “Call Signature”hasListeners():
boolean
Check if there are any handlers registered for any event.
Returns
Section titled “Returns”boolean
true if there are one or more handlers for any event, false otherwise.
Inherited from
Section titled “Inherited from”EventEmitter.hasListeners
hasWrite()
Section titled “hasWrite()”hasWrite(
vertexId):boolean
Parameters
Section titled “Parameters”vertexId
Section titled “vertexId”Returns
Section titled “Returns”boolean
insertColumns()
Section titled “insertColumns()”insertColumns(
sheetName,columnIndex,count,toTheRight):RewriteFormula
Insert count columns at a specific index in the given sheet.
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
columnIndex
Section titled “columnIndex”number
0-based column index
number
how many columns to insert
toTheRight
Section titled “toTheRight”boolean
determines whether the inserted columns are inserted to the
left or right of the column at columnIndex.
Returns
Section titled “Returns”insertRows()
Section titled “insertRows()”insertRows(
sheetName,rowIndex,count,below):RewriteFormula
Insert count rows at a specific index in the given sheet.
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
rowIndex
Section titled “rowIndex”number
0-based row index
number
how many rows to insert
boolean
determines whether the inserted rows are inserted below or
above of the row at rowIndex.
Returns
Section titled “Returns”isDependencyRoot()
Section titled “isDependencyRoot()”isDependencyRoot(
sheetIndex,row,column,ignoreRangeDependencies):boolean
Determines whether the specified cell has one or more incoming dependencies but no outgoing ones.
Parameters
Section titled “Parameters”sheetIndex
Section titled “sheetIndex”number
0-based sheet index
number
0-based row index
column
Section titled “column”number
0-based column index
ignoreRangeDependencies
Section titled “ignoreRangeDependencies”boolean = false
if set to true, then a cell won’t be considered a root if it only appears in range references
Returns
Section titled “Returns”boolean
isGlobal()
Section titled “isGlobal()”isGlobal(
name):boolean
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”boolean
iterFormulaCells()
Section titled “iterFormulaCells()”iterFormulaCells():
IterableIterator<Cell|DefinedName>
Returns
Section titled “Returns”IterableIterator<Cell | DefinedName>
listenerCount()
Section titled “listenerCount()”Call Signature
Section titled “Call Signature”listenerCount(
event):number
Get the count of listeners for a specific event.
Parameters
Section titled “Parameters”string
The name of the event.
Returns
Section titled “Returns”number
The number of listeners for the event.
Inherited from
Section titled “Inherited from”EventEmitter.listenerCount
Call Signature
Section titled “Call Signature”listenerCount():
number
Get the count of all event handlers in total.
Returns
Section titled “Returns”number
The total number of event handlers.
Inherited from
Section titled “Inherited from”EventEmitter.listenerCount
listeners()
Section titled “listeners()”listeners(
event): (…arguments_) =>void[]
Retrieve the event handlers registered for a specific event.
Parameters
Section titled “Parameters”string
The name of the event.
Returns
Section titled “Returns”(…arguments_) => void[]
An array of functions registered as handlers for the event.
Inherited from
Section titled “Inherited from”EventEmitter.listeners
moveCells()
Section titled “moveCells()”moveCells(
from,to):RewriteFormula
Precondition: formula parser has finished importing (formulaParserReady has resolved).
Parameters
Section titled “Parameters”Must be the same dimensions as to
string | A1Reference
Must be the same dimensions as from
string | A1Reference
Returns
Section titled “Returns”moveColumns()
Section titled “moveColumns()”moveColumns(
sheetName,from,to,count):RewriteFormula
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
number
0-based index of first column to move
number
0-based index of end-position of first column to move
number
the number of columns to move
Returns
Section titled “Returns”moveRows()
Section titled “moveRows()”moveRows(
sheetName,from,to,count):RewriteFormula
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
number
0-based index of first row to move
number
0-based index of end-position of first row to move
number
the number of rows to move
Returns
Section titled “Returns”neutralizeFormulaCell()
Section titled “neutralizeFormulaCell()”neutralizeFormulaCell(
cell):void
Transiently mark the given cell as not a formula cell (because of a value write). This can be reversed by calling unneutralizeFormulaCell, and that happens automatically on reset.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
Call Signature
Section titled “Call Signature”off(
event,listener):Emitter
Remove a specific event handler for a specified event.
Parameters
Section titled “Parameters”string
The name of the event.
listener
Section titled “listener”(…arguments_) => void
The specific handler function to remove.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.off
Call Signature
Section titled “Call Signature”off(
event):Emitter
Remove all event handlers for a specified event.
Parameters
Section titled “Parameters”string
The name of the event for which to remove all handlers.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.off
Call Signature
Section titled “Call Signature”off():
Emitter
Remove all event handlers for all events.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.off
on(
event,listener):Emitter
Register an event handler that listens to a specified event.
Parameters
Section titled “Parameters”string
The name of the event to listen to.
listener
Section titled “listener”(…arguments_) => void
The function to execute when the event is emitted.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.on
once()
Section titled “once()”once(
event,listener):Emitter
Register a one-time event handler for a specified event.
Parameters
Section titled “Parameters”string
The name of the event to listen to.
listener
Section titled “listener”(…arguments_) => void
The function to execute once when the event is emitted.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.once
recordWrite()
Section titled “recordWrite()”recordWrite(
vertexId,value):void
Parameters
Section titled “Parameters”vertexId
Section titled “vertexId”Returns
Section titled “Returns”void
removeDefinedName()
Section titled “removeDefinedName()”removeDefinedName(
name,sheetName?):boolean
Remove a defined name (global or sheet-scoped) from the workbook. This will schedule cells depending on that name for recalculation, but will not perform that recalculation.
Parameters
Section titled “Parameters”string
the name of the defined name to remove. It will be matched case-insensitively.
sheetName?
Section titled “sheetName?”the name of a sheet the defined name is scoped to, null if it is a global defined name. It will be matched case-insensitively.
null | string
Returns
Section titled “Returns”boolean
true if the name was removed, false if it did not exist (or the sheet did not exist)
removeSheet()
Section titled “removeSheet()”removeSheet(
sheetName):boolean
Remove a sheet from the workbook.
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
the name of the sheet to delete. It will be matched case-insensitively.
Returns
Section titled “Returns”boolean
true if the sheet was removed, false if it did not exist
Throws
Section titled “Throws”if there are writes that have not been reset
renameSheet()
Section titled “renameSheet()”renameSheet(
currentName,newName):void
Rename the given sheet to a new name, updating all formulas referencing it
Precondition: formula parser has finished importing (formulaParserReady has resolved).
Parameters
Section titled “Parameters”currentName
Section titled “currentName”string
newName
Section titled “newName”string
must be different from currentName
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if no sheet exists named currentName
reset()
Section titled “reset()”reset():
void
Returns
Section titled “Returns”void
resetDefinedNames()
Section titled “resetDefinedNames()”resetDefinedNames():
void
Assign static-reference values to defined names, or if not static, record them as requiring initial recalculation.
Returns
Section titled “Returns”void
resetModel()
Section titled “resetModel()”resetModel():
void
Returns
Section titled “Returns”void
rewriteFormulas()
Section titled “rewriteFormulas()”rewriteFormulas(
rewriteFormula):number
Parameters
Section titled “Parameters”rewriteFormula
Section titled “rewriteFormula”(formula) => string
Returns
Section titled “Returns”number
number of formulas changed
rowHeight()
Section titled “rowHeight()”rowHeight(
rowIndex,sheetName):number
Height of the given column in the given sheet, in pixels.
Parameters
Section titled “Parameters”rowIndex
Section titled “rowIndex”number
1-based row index
sheetName
Section titled “sheetName”string
name of the sheet in which to look up a row height
Returns
Section titled “Returns”number
setColumnWidth()
Section titled “setColumnWidth()”setColumnWidth(
sheetName,column,width):void
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
column
Section titled “column”number
0-based column index
number
non-negative
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if there is no sheet with sheetName in this workbook, or if col and/or width are invalid
setDefinedName()
Section titled “setDefinedName()”setDefinedName<
AbortOnError>(name,formula,sheet?,abortOnError?,validateNow?):DefinedName|AbortOnErrorextendstrue?null:never
Add a defined name in this workbook with the given formula.
If any error is detected in the formula (syntax error, or use of something
we do not support), abort and return null if abortOnError is true, else
go ahead and make the defined name but record the error with this.addError.
Type Parameters
Section titled “Type Parameters”AbortOnError
Section titled “AbortOnError”AbortOnError extends boolean = false
Parameters
Section titled “Parameters”string
formula
Section titled “formula”string
sheet?
Section titled “sheet?”sheet to scope the name to, or null for workbook scope
null | WorkSheet
abortOnError?
Section titled “abortOnError?”AbortOnError
true to return null and make no change if formula has any errors
validateNow?
Section titled “validateNow?”boolean = true
set to false to skip formula validation here (caller is responsible for it then)
Returns
Section titled “Returns”DefinedName | AbortOnError extends true ? null : never
setRowHeight()
Section titled “setRowHeight()”setRowHeight(
sheetName,rowNum,height):void
Sets the height of a row.
One function, SUBTOTAL, may yield different results depending on whether some cells in the range belong to hidden rows or not. Therefore, if the row becomes hidden, or was hidden before this change, a recalculation of formulas referencing cells in the affected row will be required. This call will register state about that, so that the next recalculation will update formula cells as needed. It is up to the caller to make sure a recalculation is eventually triggered.
Precondition: Workbook is initialized.
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
rowNum
Section titled “rowNum”number
0-based row index
height
Section titled “height”number
non-negative
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if there is no sheet with sheetName in this workbook, or if rowNum and/or height are invalid
sheetHasBeenPruned()
Section titled “sheetHasBeenPruned()”sheetHasBeenPruned(
sheetName):boolean
Parameters
Section titled “Parameters”sheetName
Section titled “sheetName”string
Returns
Section titled “Returns”boolean
state()
Section titled “state()”state(
newState?,defect?):object
Parameters
Section titled “Parameters”newState?
Section titled “newState?”"uploading" | "processing" | "ready" | "invalid"
defect?
Section titled “defect?”null | string
Returns
Section titled “Returns”object
defect
Section titled “defect”defect:
null|string
id:
string
state:
undefined|"uploading"|"processing"|"ready"|"invalid"|"replaced"
update_time
Section titled “update_time”update_time:
undefined|string
toCSF()
Section titled “toCSF()”toCSF():
CSFOutput
Returns
Section titled “Returns”CSFOutput
toJsf()
Section titled “toJsf()”toJsf():
JSF
Serialize this workbook to JSF (JSON Spreadsheet Format).
This is the inverse of Workbook.fromJsf, producing a JSF object that can be used to reconstruct the workbook state.
Returns
Section titled “Returns”JSF
A JSF object representing this workbook
toXlsx()
Section titled “toXlsx()”toXlsx():
Promise<Buffer<ArrayBufferLike>>
Convert this workbook to XLSX format and return the result as a Buffer.
This method converts the workbook to JSF format first, then generates an XLSX file from that representation.
Returns
Section titled “Returns”Promise<Buffer<ArrayBufferLike>>
A Promise resolving to a Buffer containing the XLSX file data
toXlsxFile()
Section titled “toXlsxFile()”toXlsxFile(
path):Promise<void>
Convert this workbook to XLSX format and write it to a file.
This method converts the workbook to JSF format first, then generates an XLSX file from that representation and writes it to the specified path.
Parameters
Section titled “Parameters”string
The file path to write the XLSX file to
Returns
Section titled “Returns”Promise<void>
unneutralizeFormulaCell()
Section titled “unneutralizeFormulaCell()”unneutralizeFormulaCell(
cell):void
Revert the action of neutralizeFormulaCell, reinstating the formula.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
updateCellResetState()
Section titled “updateCellResetState()”updateCellResetState(
ref):void
Update the reset state of the cell referenced by ref. The reference
can be to a cell in a sheet, or a defined name in the Workbook.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
updateDependencies()
Section titled “updateDependencies()”updateDependencies(
vertexIDs?):void
Parameters
Section titled “Parameters”vertexIDs?
Section titled “vertexIDs?”(CellVertexId | NameVertexId)[]
Returns
Section titled “Returns”void
write()
Section titled “write()”write(
ref,val,neutralizeFormulaOnSingleCellWrite?):boolean
Write the given value to the given cell (A1 address or global name)
Precondition: Workbook must be initialized
Parameters
Section titled “Parameters”the address or global name to write to
string | Reference
the value to write
neutralizeFormulaOnSingleCellWrite?
Section titled “neutralizeFormulaOnSingleCellWrite?”boolean = false
set to true if writes to single formula cells should neutralize them
Returns
Section titled “Returns”boolean
true if a write occurred
writeCellData()
Section titled “writeCellData()”writeCellData(
cellRef,cellData):Cell|DefinedName
Write the given cell data attributes (.v, .f, etc.) to an existing or
new cell.
If cell value is an error value, normalize it to the corresponding
singleton error value in errorTable.
If cellData has a formula, it is parsed and (if parsing succeeds) the AST
is stored in the cell object.
If cellData has an .f attribute (whether null or not), the whole
workbook’s dependency graph is rebuilt (unless you pass false for
rebuildDependencyGraph).
Preconditions:
- Formula parser has finished importing (
formulaParserReadyhas resolved). - Workbook must be initialized.
Parameters
Section titled “Parameters”cellRef
Section titled “cellRef”the cell to write, as a Reference or
a string representing one. If this indicates a range, the top-left cell
of that range is written. This must not be a name reference as this
method does not support those yet.
string | Reference
cellData
Section titled “cellData”Omit<Cell, "s" | "f" | "v"> & object & object & object
object with attributes to write to the cell
Returns
Section titled “Returns”the existing or new Cell instance.
Throws
Section titled “Throws”if precondition is not satisfied (the formula parser has
not finished importing), or if a string is passed and it fails to parse
as a Reference.
writes()
Section titled “writes()”writes(): [
string,CellValue][]
Precondition: Workbook must be initialized
Returns
Section titled “Returns”[string, CellValue][]
fromCsf()
Section titled “fromCsf()”
staticfromCsf(csf,model,options):Workbook
Create a Workbook from CSF format directly, bypassing JSF conversion. This provides significantly better performance than converting CSF→JSF→Workbook.
Parameters
Section titled “Parameters”Workbook data in CSF format
The Model instance to attach this workbook to
options
Section titled “options”WorkbookOptions = {}
Workbook initialization options
Returns
Section titled “Returns”Workbook
A new Workbook instance populated from CSF
fromJsf()
Section titled “fromJsf()”
staticfromJsf(jsf,model,options):Workbook
Create a Workbook from JSF format.
Parameters
Section titled “Parameters”JSF
Workbook data in JSF format
The Model instance to attach this workbook to
options
Section titled “options”WorkbookOptions = {}
Workbook initialization options
Returns
Section titled “Returns”Workbook
A new Workbook instance populated from JSF
fromXlsx()
Section titled “fromXlsx()”
staticfromXlsx(data,model,filename,options?):Promise<Workbook>
Create a Workbook from XLSX binary data.
This is a convenience method that wraps @borgar/xlsx-convert to load XLSX data
directly into a Workbook without requiring users to manually import the conversion library.
Note: This creates only the main workbook. External references in the XLSX file are not automatically added to the model. Use Model.addWorkbookFromXlsx to also add externals.
Parameters
Section titled “Parameters”Binary XLSX data (works in browsers and Node.js)
ArrayBuffer | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>
The Model instance to attach this workbook to
filename
Section titled “filename”string
Filename to associate with the workbook
options?
Section titled “options?”WorkbookOptions
Workbook initialization options
Returns
Section titled “Returns”Promise<Workbook>
A Promise resolving to a new Workbook instance
fromXlsxFile()
Section titled “fromXlsxFile()”
staticfromXlsxFile(path,model,options?):Promise<Workbook>
Create a Workbook from an XLSX file path.
This is a convenience method that wraps @borgar/xlsx-convert to load XLSX files
directly into a Workbook without requiring users to manually import the conversion library.
Note: This creates only the main workbook. External references in the XLSX file are not automatically added to the model. Use Model.addWorkbookFromXlsxFile to also add externals.
Parameters
Section titled “Parameters”string
Path to the XLSX file (Node.js only - uses fs)
The Model instance to attach this workbook to
options?
Section titled “options?”WorkbookOptions
Workbook initialization options
Returns
Section titled “Returns”Promise<Workbook>
A Promise resolving to a new Workbook instance