Model

Central interface for managing and manipulating spreadsheet data in memory.

The Model class represents a collection of workbooks and provides a unified API for reading, writing, and calculating cell values across all workbooks. It manages workbook dependency graphs to ensure accurate recalculation when values change, and handles formula evaluation with support for cross-workbook references.

Basic usage

// Wait for formula parser to load before using models
await Model.preconditions;

// Create a model from JSF (recommended)
const parsedJSF = JSON.parse(jsf);
const model = Model.fromJSF(parsedJSF);

// Alternatively, create from CSF (for backward compatibility)
const parsedCSF = JSON.parse(csf);
const model = Model.fromCsf(parsedCSF);

// Write primitive values to cells
model.write('A1', "Hello, World!");
model.write('A2', 42);
model.write('A3', true);

// Read cell values
model.readValue("=A1");
model.readValue("=Sheet1!A1");  // Read from a specific sheet
model.readValue("=[budget.xlsx]Sheet1!A1");  // Read from a specific workbook

// Work with multiple workbooks
model.addWorkbook(anotherWorkbook);
model.write('Sheet1!A1', 100); // Write to specific sheet
model.write('[another_workbook.xlsx]Sheet1!A1', 200); // Write to specific workbook

Performance considerations

Lazy recalculation: only changed cells and their dependents are recalculated
Batch writes: Use writeMultiple() for better performance when writing many cells
Functions may be volatile: functions like NOW() and RAND() recalculate every time

Precondition

Some methods require the Model.preconditions promise to be resolved before use. This ensures the formula parser, a WebAssembly module, has finished loading. Always await this before calling static factory methods or methods marked with this precondition in their docs.

Extends

emitter

Implements

EvaluationContext

Constructors

Constructor

new Model(): Model;

Returns

Model

Overrides

EventEmitter.constructor

Properties

coerceNullToZero

coerceNullToZero: CoercionMode = COERCE_NONE;

Implementation of

EvaluationContext.coerceNullToZero

env

env: Map<"isPrint" | "isMobile" | "username", MaybeBoxedFormulaArgument>;

Information about outside environment relevant to the model and functions. Writable from the outside, but functions get only read access to it.

Implementation of

EvaluationContext.env

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 Model method, just to enable calling it via evaluation context to dodge circular imports.

Parameters

ast

ASTNode

evaluateASTNode

evaluateASTNode: FnEvaluateASTNode;

Evaluate an AST node. This wraps the evaluateASTNodeUnbound function as a Model method, just to enable calling it via evaluation context to dodge circular imports.

Implementation of

EvaluationContext.evaluateASTNode

getEntities()

getEntities: (this) => ModelEntity[];

Returns a list of defined names and tables in the Model.

No guarantees are made about the order of the entities.

Parameters

this

Model

Returns

ModelEntity[]

getGlobal()

getGlobal: (this, name, workbookName?) =>
  | FormulaError
  | DefinedName;

Parameters

this

Model

name

string

workbookName?

string | null

Returns

| FormulaError | DefinedName

the cell object for the given defined-name, or a #NAME? error if not found

getTable()

getTable: (this, name, workbookName) => Table | null;

Parameters

this

Model

name

string

workbookName

string | null | undefined

Returns

Table | null

getWorkbook()

getWorkbook: (this, name?) => Workbook | undefined;

Get the workbook with the given name (case-insensitive), or undefined if no such workbook is in the model.

Parameters

this

Model

name?

string | null

Returns

Workbook | undefined

mode

mode: ModeBit = MODE_GRID_SHEET;

Implementation of

EvaluationContext.mode

resolveName()

resolveName: (this, 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

this

Model

name

string

sheetName?

string | null

Returns

| FormulaError | DefinedName

Implementation of

EvaluationContext.resolveName

resolveSheet()

resolveSheet: (this, sheetName?, workbookName?) => WorkSheet | null;

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

this

Model

sheetName?

string | null

workbookName?

string | null

Returns

WorkSheet | null

Implementation of

EvaluationContext.resolveSheet

resolveTable()

resolveTable: (this, name, workbookName) => Table | null;

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

this

Model

name

string

workbookName

string | null | undefined

Returns

Table | null

Implementation of

EvaluationContext.resolveTable

resolveWorkbook()

resolveWorkbook: (this, name?) => Workbook | undefined;

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.

Get the workbook with the given name (case-insensitive), or undefined if no such workbook is in the model.

Parameters

this

Model

name?

string | null

Returns

Workbook | undefined

Implementation of

EvaluationContext.resolveWorkbook

writeState()

writeState: (this, includeOverwrittenCells) => ModelStateTree;

Returns an object tree of all current writes to the model. The outermost object’s keys will be workbook names, second level will be sheet names, and third level will be cell IDs or names with the written values as values:

 {
  "myworkbook": {
    "sheet1": {
      "A1": 1234
    }
  }
}

By default, writes that would not produce the same state are omitted from the output. These are writes to formula cells that have been overwritten again by the recalculation process. Re-applying them to a reset model would not reliably produce the same state.

Parameters

this

Model

includeOverwrittenCells

boolean = false

include writes to formula cells that have been overwritten by recalculation.

Returns

ModelStateTree

Implementation of

EvaluationContext.writeState

preconditions

static preconditions: Promise<{
  parse: FnParseFormula;
  replaceRefsOnDelete: ReplaceRefsOnDeleteFn;
  replaceRefsOnMove: ReplaceRefsOnMoveFn;
  replaceSheetReferences: ReplaceSheetReferencesFn;
  replaceWorkbookReferences: ReplaceWorkbookReferencesFn;
}> = formulaParserReady;

Promise that should be awaited before calling certain methods of Model (noted with a precondition in the documentation of those methods).

Accessors

calcMode

Get Signature

get calcMode(): CalcMode;

The effective calculation mode. When a workbook with calcMode: "autoNoTable" is attached, deferDataTables is set to true automatically. The calcMode value is preserved on individual workbooks for round-tripping through JSF.

With multiple workbooks, the first workbook (in insertion order) whose calcMode is not "auto" determines the result. This is adequate for the primary single-workbook use case; multi-workbook conflict resolution is not currently defined beyond this first-wins behavior.

Returns

CalcMode

cellsToDefer

Get Signature

get cellsToDefer(): ReadonlySet<CellItem>;

Cells configured to be skipped during normal recalculation. Use recalculate({ includeDeferred: true }) or recalculate(ALL_FORMULA_CELLS) to include them.

Returns

ReadonlySet<CellItem>

defect

Get Signature

get defect(): string | null | undefined;

Returns

string | null | undefined

deferDataTables

Get Signature

get deferDataTables(): boolean;

When true, data table anchor cells are deferred --- they are not recalculated until recalculate({ includeDeferred: true }) or recalculate(ALL_FORMULA_CELLS) is called.

Setting to true scans all attached workbooks and adds their data-table anchor cells to cellsToDefer. Setting to false removes all data-table anchor cells from cellsToDefer.

Persistence: this flag is one-directional --- attaching a workbook with calcMode: "autoNoTable" sets it to true, but removing that workbook does not reset it. Consumers who want to restore automatic recalculation of data tables must explicitly set deferDataTables = false.

Note: cellsToDefer can also be modified independently of this property, so the boolean may not reflect the exact contents of that set.

Returns

boolean

Set Signature

set deferDataTables(value): void;

Parameters

value

boolean

Returns

void

errors

Get Signature

get errors(): ModelError[];

Returns

ModelError[]

lazyImportPromise

Get Signature

get lazyImportPromise(): Promise<void>;

Returns

Promise<void>

ready

Get Signature

get ready(): boolean;

Returns

boolean

staleDeferredCells

Get Signature

get staleDeferredCells(): ReadonlySet<CellItem>;

Cells that were encountered as dependents during recalculation but were deferred (skipped) because they were configured for deferral. These cells have stale values and need recalculate({ includeDeferred: true }) or recalculate(ALL_FORMULA_CELLS) to be recalculated.

Note: non-deferred cells that transitively depend on deferred cells may also have stale values, since dependency propagation stops at deferred cells.

Returns

ReadonlySet<CellItem>

volatiles

Get Signature

get volatiles(): readonly (CellVertexId | NameVertexId)[];

Returns

readonly (CellVertexId | NameVertexId)[]

Methods

_attachWorkbook()

_attachWorkbook(wb, options): void;

Legacy internal-looking name for the now-public method attachWorkbook

Parameters

wb

Workbook

options

AddWorkbookOptions = {}

Returns

void

addWorkbook()

addWorkbook(data, options): Workbook;

Construct a workbook from the given JSF and then attach it to this model.

This is just a convenience wrapper calling Workbook.fromJsf and attachWorkbook.

If your workbook source is in CSF format, consider using Model.fromCsf instead, or if you have multiple CSF workbooks, use Workbook.fromCsf and attachWorkbook.

Parameters

data

JSF

The workbook data in JSF format

options

AddWorkbookOptions = {}

Configuration options for the new workbook

Returns

Workbook

The newly created Workbook instance that was added to the model

Precondition

The Model.preconditions promise must be resolved before calling this method

Throws

Error if data is invalid in some way

Throws

Error if a non-external workbook with the same name already exists in the model

Throws

Error if precondition is not satisfied (the formula parser has not finished importing)

Example

// Add multiple related workbooks
const model = new Model();
model.addWorkbook(budget2024jsf);  // From e.g. budget2024.xlsx
model.addWorkbook(budget2025jsf);  // From e.g. budget2025.xlsx

addWorkbookFromXlsx()

addWorkbookFromXlsx(
   data,
   filename,
options?): Promise<Workbook>;

Add a workbook from XLSX binary data.

This is a convenience method that wraps @borgar/xlsx-convert to load XLSX data directly into the model. External references in the XLSX are also added to the model.

Parameters

data

Binary XLSX data (works in browsers and Node.js)

ArrayBuffer | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>

filename

string

Filename to associate with the workbook

options?

AddWorkbookOptions & object

Options for workbook loading

Returns

Promise<Workbook>

A Promise resolving to the main Workbook instance

addWorkbookFromXlsxFile()

addWorkbookFromXlsxFile(path, options?): Promise<Workbook>;

Add a workbook from an XLSX file path.

This is a convenience method that wraps @borgar/xlsx-convert to load XLSX files directly into the model. External references in the XLSX are also added to the model.

Parameters

path

string

Path to the XLSX file (Node.js only - uses fs)

options?

AddWorkbookOptions & object

Options for workbook loading

Returns

Promise<Workbook>

A Promise resolving to the main Workbook instance

Example

await Model.preconditions;
const model = new Model();
const budget2024 = await model.addWorkbookFromXlsxFile('budget2024.xlsx');
const budget2025 = await model.addWorkbookFromXlsxFile('budget2025.xlsx');

analyzeAndFixFormula()

analyzeAndFixFormula(formula, options?): AnalyzeFormulaResult;

Parameters

formula

string

options?

sheetName?

string

workbookName?

string | null

Returns

AnalyzeFormulaResult

analyzeFormula()

analyzeFormula(formula, options?): AnalyzeFormulaResult;

Parameters

formula

string

options?

sheetName?

string

workbookName?

string | null

Returns

AnalyzeFormulaResult

attachWorkbook()

attachWorkbook(wb, options): void;

Add an additional workbook to this model.

This method allows you to combine multiple spreadsheet workbooks into a single model, enabling cross-workbook formula references. Each workbook must have a name unique (case-insensitively) within the model, unless an existing workbook with the same name is an external reference stub (marked with isExternal: true), in which case it will be replaced by the new workbook.

Parameters

wb

Workbook

The workbook to add

options

AddWorkbookOptions = {}

Configuration options for which optimization and recalculation work to do

Returns

void

Throws

Error if a non-external workbook with the same name already exists in the model

Example

// Add multiple related workbooks
const model = new Model();
model.attachWorkbook(Workbook.fromJsf(budget2024jsf));
model.attachWorkbook(Workbook.fromJsf(budget2025jsf);

clearCells()

clearCells(ref): void;

Parameters

ref

A reference to the cell, or range of cells, to clear. Defined names are not supported.

string | Reference

Returns

void

emit()

emit(event, ...arguments_): Emitter;

Emit an event, invoking all handlers registered for it.

Parameters

event

string

The name of the event to emit.

arguments_

…any[]

Arguments to pass to the event handlers.

Returns

Emitter

The Emitter instance for method chaining.

Inherited from

EventEmitter.emit

evaluateExpression()

evaluateExpression<Values, Single, Fallback>(expression, __namedParameters): EvaluateExpressionReturnType<Values, Single, Fallback>;

Evaluate expression and return the resulting value, or cell, or 2-D array of values or of cells.

A 2-D array is the type returned by Reference.resolveArea: an Array of Arrays of values or Cell instances, plus the attributes top, left, bottom, right, sheetName.

expr may be a literal value or a formula, or nullish or empty-string or the string '='. In the latter three cases, fallBack is returned.

Also, if values is false and single is true, then fallBack is returned if a cell could not be resolved. This is not done if values is true or single is true. (The intent is to iron out this inconsistency when we get to removing the fallBack parameter altogether, in ENGINE-142.)

Type Parameters

Values

Values extends boolean = boolean

Single

Single extends boolean = boolean

Fallback

Fallback = unknown

Parameters

expression

string

what to evaluate. Treated as a formula if it begins with = and isn’t just that.

__namedParameters

EvaluateExpressionOptions<Values, Single, Fallback>

Returns

EvaluateExpressionReturnType<Values, Single, Fallback>

the evaluated value, directly, or wrapped in a Cell instance or area array. If single is false and values is false, this returns an AreaCellArray. If single is false and values is true, this returns an AreaValueArray. If single is true and values is false, this returns a Cell. If single is true and values is true, this returns a CellValue.

getCell()

getCell(
   cellId,
   sheetName?,
   workbookName?): Cell | null;

Parameters

cellId

string

sheetName?

string | null

workbookName?

string | null

Returns

Cell | null

getWorkbookById()

getWorkbookById(id): Workbook | undefined;

Get the workbook with the given ID, or null if no such workbook is in the model.

Parameters

id

string

Returns

Workbook | undefined

getWorkbooks()

getWorkbooks(): Workbook[];

Returns

Workbook[]

goalSeek()

goalSeek(
   controlCell,
   targetCell,
   targetValue): number | FormulaError;

Parameters

controlCell

string | Reference

targetCell

string | Reference

targetValue

number

Returns

number | FormulaError

hasListeners()

Call Signature

hasListeners(event): boolean;

Check if there are any handlers registered for a specific event.

Parameters

event

string

The name of the event.

Returns

boolean

true if there are one or more handlers, false otherwise.

Inherited from

EventEmitter.hasListeners

Call Signature

hasListeners(): boolean;

Check if there are any handlers registered for any event.

Returns

boolean

true if there are one or more handlers for any event, false otherwise.

Inherited from

EventEmitter.hasListeners

isGlobal()

isGlobal(cellRef, workbookName?): boolean;

Parameters

cellRef

string

workbookName?

string

name of a workbook to look in, if cellRef does not have a workbook prefix

Returns

boolean

iterativeCalculationSettings()

iterativeCalculationSettings(): IterativeCalculationOptions;

Returns

IterativeCalculationOptions

listenerCount()

Call Signature

listenerCount(event): number;

Get the count of listeners for a specific event.

Parameters

event

string

The name of the event.

Returns

number

The number of listeners for the event.

Inherited from

EventEmitter.listenerCount

Call Signature

listenerCount(): number;

Get the count of all event handlers in total.

Returns

number

The total number of event handlers.

Inherited from

EventEmitter.listenerCount

listeners()

listeners(event): (...arguments_) => void[];

Retrieve the event handlers registered for a specific event.

Parameters

event

string

The name of the event.

Returns

(…arguments_) => void[]

An array of functions registered as handlers for the event.

Inherited from

EventEmitter.listeners

off()

Call Signature

off<T>(event, listener): object & Emitter;

Remove a specific event handler for a specified event.

Type Parameters

T

T extends keyof ModelEventArgs

Parameters

event

T

The name of the event.

listener

ModelEventListener<T>

The specific handler function to remove.

Returns

object & Emitter

The Emitter instance for method chaining.

Overrides

EventEmitter.off

Call Signature

off(event): object & Emitter;

Remove all event handlers for a specified event.

Parameters

event

string

The name of the event for which to remove all handlers.

Returns

object & Emitter

The Emitter instance for method chaining.

Overrides

EventEmitter.off

Call Signature

off(): object & Emitter;

Remove all event handlers for all events.

Returns

object & Emitter

The Emitter instance for method chaining.

Overrides

EventEmitter.off

on()

on<T>(event, listener): object & Emitter;

Type Parameters

T

T extends keyof ModelEventArgs

Parameters

event

T

The name of the event to listen to.

listener

ModelEventListener<T>

The function to execute when the event is emitted.

Returns

object & Emitter

The Emitter instance for method chaining.

Overrides

EventEmitter.on

once()

once(event, listener): Emitter;

Parameters

event

string

The name of the event to listen to.

listener

(…arguments_) => void

The function to execute once when the event is emitted.

Returns

Emitter

The Emitter instance for method chaining.

Inherited from

EventEmitter.once

readCell()

readCell(expression, fallBack): Cell;

Evaluate expression and return the resulting Cell.

See evaluateExpression.

Parameters

expression

string

the expression to evaluate. Treated as a formula if it begins with = and isn’t just that.

fallBack

Cell = BLANK_CELL

value to return if expr is empty or null or just =, or failed to resolve to a cell.

Returns

Cell

the resulting Cell instance, or fallBack, or a Cell instance with a FormulaError as its value.

readCellOrDefinedName()

readCellOrDefinedName(expression, fallBack): CellItem;

Evaluate expression, resolving any name reference result and recursing to that formula, until a result that isn’t a name reference is obtained. Return a single Cell which is:

if the result is a reference to a range of sheet cells, the top-left cell cell of that range
else if the result is that of a defined-name formula (not the original expression), return that last defined-name Cell object
else the result itself (or its top-left element if it is a Matrix), wrapped in a Cell with no id.

Parameters

expression

string

the expression to evaluate. Treated as a formula if it begins with = and isn’t just that.

fallBack

CellItem = BLANK_CELL

value to return if expr is empty or null or just =, or failed to resolve to a cell.

Returns

CellItem

the resulting Cell instance, or fallBack, or a Cell instance with a FormulaError as its value.

See

evaluateExpression

readCells()

readCells(expression, options): AreaCellArray;

Evaluate expression and return the resulting 2-D array of cells.

See evaluateExpression.

Parameters

expression

string

the expression to evaluate. Treated as a formula if it begins with = and isn’t just that.

options

cropTo?

"any-cell-information" | "cells-with-non-blank-values"

Returns

AreaCellArray

the resulting 2-D array of cells, or an error or fallback wrapped into the same structure.

readValue()

readValue(expression, fallBack): CellValue;

Evaluate expression and return the resulting value.

See evaluateExpression.

Parameters

expression

string

the expression to evaluate. Treated as a formula if it begins with = and isn’t just that.

fallBack

CellValue = null

value to return if expr is empty or null or just =.

Returns

CellValue

the resulting Cell instance, or fallBack, or a Cell instance with a FormulaError as its value.

recalculate()

recalculate(options?): object;

Recalculates formula cells in the model and updates their values.

This method triggers the recalculation engine to evaluate formulas based on the dependency graph. It emits a ‘beforerecalc’ event before starting, handles any errors during calculation, and triggers an update event when complete.

If any sheets have GSDV cells (which should only happen if this is the initial recalculation), then Cells.clearGsdv is called and if any cells are deleted as a result, a second initial recalculation is performed (with CHANGED_ONLY, so not updating volatiles again) to update formulas depending on them.

Parameters

options?

Controls which cells to recalculate. Can be a WhichCellsToRecalculate symbol or a RecalculateOptions object:

CHANGED_OR_VOLATILE (default): recalculates cells that have changed or are marked volatile
CHANGED_ONLY: recalculates only cells that have changed
ALL_FORMULA_CELLS: forces recalculation of all formula cells
{ which?, includeDeferred? }: options object; includeDeferred: true includes deferred cells in this recalculation while preserving the set of cells to defer for future recalculations. Note: includeDeferred is redundant with ALL_FORMULA_CELLS which already ignores deferral.

WhichCellsToRecalculate | RecalculateOptions

Returns

object

An object with a nativeWorkbooksChanged property containing any GRID-native workbooks that needed recalculation.

nativeWorkbooksChanged

nativeWorkbooksChanged: Set<Workbook>;

removeWorkbook()

removeWorkbook(id): boolean;

Remove a workbook from this model and clean up all related dependencies.

When a workbook is removed, all cells that depend on formulas in that workbook will be recalculated. Any cross-workbook references to the removed workbook will result in #REF! errors in dependent cells.

Parameters

id

string

The unique identifier of the workbook to remove

Returns

boolean

true if the workbook was found and removed, false otherwise

Example

const jsf = ...;  // Load workbook as JSF
jsf.id = '1234';
const model = Model.fromJSF(jsf);
const removed = model.removeWorkbook('1234');

reset()

reset(opts?): void;

Reset all cell values to their initial state (as data was when read). Only values are reset; other cell attributes (function, style) are not affected. This also triggers recalculation, so volatile cells will update.

By default, deferred cells are included in the recalculation so that the model returns to a fully consistent initial state. Pass { includeDeferred: false } to keep deferred cells deferred during reset.

Parameters

opts?

includeDeferred?

boolean

Returns

void

rewriteFormulaAfterMove()

rewriteFormulaAfterMove(
   formula,
   from,
   to): string;

Parameters

formula

string

formula to update.

from

reference containing a workbook and sheet prefix

string | A1Reference

to

reference containing a workbook and sheet prefix

string | A1Reference

Returns

string

the updated formula.

Precondition

Formula parser has finished importing (formulaParserReady has resolved).

runFormula()

runFormula(formula, extraContext): FormulaValue;

Evaluate a spreadsheet formula and return the computed result.

Results are automatically cached based on the formula text and will be reused if the same formula is evaluated multiple times with unchanged dependencies.

Parameters

formula

string

The Excel formula to evaluate, with or without leading ’=’ (e.g., ‘SUM(A1:A10)’ or ‘=SUM(A1:A10)‘)

extraContext

extra options or properties to pass through to the formula runner. These will be available to each spreadsheet function as attributes on this

Partial<EvaluationContext> | null

Returns

FormulaValue

Result of the formula

Precondition

The Model.preconditions promise must be resolved before calling this method

Throws

Error if precondition is not satisfied (the formula parser has not finished importing)

Throws

EvaluationError if AST is invalid or an unanticipated internal error occurs so evaluation can’t complete. This error will have its .ast and .formula properties populated.

Throws

FormulaSyntaxError if formula needs to be parsed and can’t be

Example

import xlsxConvert from "@borgar/xlsx-convert";
import { Model } from '@grid-is/apiary';

await Model.preconditions;

const wb = await xlsxConvert("budget.xlsx");
const model = Model.fromJSF(wb);
const totalSpent = model.runFormula("=SUM(D:D)");

See

Model.readValue to read a value from a cell

write()

Call Signature

write(
   cellRef,
   value,
   recalcNow?,
   skipVolatiles?,
   neutralizeFormulaOnSingleCellWrite?): void;

(Deprecated signature) Write the given value to the given cell (A1 address or global name).

Parameters

cellRef

the address or global name to write to

string | Reference

value

CellValue

the value to write

recalcNow?

boolean

true (the default) to recalculate immediately before returning

skipVolatiles?

boolean

true to skip evaluation of volatile cells when recalculating

neutralizeFormulaOnSingleCellWrite?

boolean

true to neutralize formula in single-cell write

Returns

void

Call Signature

write(
   cellRef,
   value,
   opts?): void;

Write the given value to the given cell (A1 address or global name)

Parameters

cellRef

the address or global name to write to

string | Reference

value

CellValue

the value to write

opts?

WriteOptions

Returns

void

writeMultiple()

writeMultiple(writes, opts): void;

Efficiently write multiple values to different cells in a single operation.

Perform each write in the given list of writes and recalculate once at the end (if the list was non-empty, or if forceRecalc is true).

This method is optimised for bulk data updates. Instead of recalculating after each individual write (which can be slow), it performs all writes first and then recalculates once at the end. This provides significantly better performance when updating many cells at once.

Parameters

writes

readonly [string, CellValue][]

Array of two-element arrays [cell, val] for individual writes

opts

WriteOptions = {}

Options controlling the batch write behaviour

Returns

void

Example

model.writeMultiple([
  ['A1', 100],
  ['A2', 200],
  ['A3', 300],
]);

writes()

writes(includeOverwrittenCells): [string, CellValue][];

Return a list of writes to the model.

By default, writes that would not produce the same state are omitted from the list. These are writes to formula cells that have been overwritten again by the recalculation process. Re-applying them to a reset model would not reliably produce the same state.

Parameters

includeOverwrittenCells

boolean = false

include writes to formula cells that have been overwritten by recalculation.

Returns

[string, CellValue][]

empty()

static empty(filename): Model;

Create an empty Model instance with a single blank workbook and worksheet.

This is a convenience method for creating a new Model from scratch without needing to provide CSF data. The resulting model contains one workbook with one empty worksheet named “Sheet1”.

Parameters

filename

string = 'Book1.xlsx'

The name to assign to the empty workbook

Returns

Model

A new Model instance containing an empty workbook

Precondition

The Model.preconditions promise must be resolved before calling this method

Throws

Error thrown if precondition is not satisfied (the formula parser has not finished importing)

fromCsf()

static fromCsf(csf, options): Model;

Make a Model instance and populate it with a workbook from the given CSF.

CSF (Common Spreadsheet Format) is a JSON representation of a workbook. This method is typically used when loading data that has been previously processed from XLSX to JSON. Packages to do that include xlsx-convert or xlsx.

Parameters

csf

WorkbookCSF

The workbook data in CSF format

options

AddWorkbookOptions = {}

Configuration options for workbook initialisation

Returns

Model

A new Model instance containing the loaded workbook

Precondition

The Model.preconditions promise must be resolved before calling this method

Throws

Error thrown if precondition is not satisfied (the formula parser has not finished importing)

Example

// Ensure parser is ready
await Model.preconditions;

// Create model from JSF data
const model = Model.fromJSF(jsf, {
  // When a workbook is read-only, work required to support writes is skipped in order to load
  // the workbook faster. In particular, formulas will not be parsed and the workbook will not
  // be added to the dependency graph. No initial recalculation occurs, which may lead to
  // inaccuracies in workbooks that depend on it.
  readOnly: true
});

// Access the loaded data
const cellValue = model.readValue('=A1');

fromData()

static fromData(csf, options): Model;

Parameters

csf

WorkbookCSF

options

AddWorkbookOptions = {}

Returns

Model

fromJSF()

static fromJSF(jsf, options): Model;

Make a Model instance and populate it with a workbook from the given JSF.

JSF (JSON Spreadsheet Format) is a JSON representation of a workbook produced by the xlsx-convert library. This method is typically used when loading data that has been previously processed from XLSX to JSON.

Parameters

jsf

JSF

A JSF object representing a workbook

options

AddWorkbookOptions & object = {}

Configuration options for workbook initialization

Returns

Model

A new Model instance containing the loaded workbook

Precondition

The Model.preconditions promise must be resolved before calling this method

Throws

Error thrown if precondition is not satisfied (the formula parser has not finished importing)

Example

// Load Excel file using xlsx-convert
import xlsxConvert from "@borgar/xlsx-convert";

await Model.preconditions;

const wb = await xlsxConvert("budget.xlsx");
const model = Model.fromJSF(wb);
const totalSpent = model.runFormula("=SUM(D:D)");

fromXlsx()

static fromXlsx(
   data,
   filename,
options?): Promise<Model>;

Load a Model from XLSX binary data.

This is a convenience method that wraps @borgar/xlsx-convert to load XLSX data directly into a Model without requiring users to manually import the conversion library.

Parameters

data

Binary XLSX data (works in browsers and Node.js)

ArrayBuffer | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>

filename

string

Filename to associate with the workbook

options?

AddWorkbookOptions & object

Options for workbook loading

Returns

Promise<Model>

A Promise resolving to a new Model instance

Example

const response = await fetch('https://example.com/budget.xlsx');
const data = await response.arrayBuffer();
const model = await Model.fromXlsx(data, 'budget.xlsx');

fromXlsxFile()

static fromXlsxFile(path, options?): Promise<Model>;

Load a Model from an XLSX file path.

This is a convenience method that wraps @borgar/xlsx-convert to load XLSX files directly into a Model without requiring users to manually import the conversion library.

Parameters

path

string

Path to the XLSX file (Node.js only - uses fs)

options?

AddWorkbookOptions & object

Options for workbook loading

Returns

Promise<Model>

A Promise resolving to a new Model instance

Example

const model = await Model.fromXlsxFile('budget.xlsx');
const totalSpent = model.runFormula("=SUM(D:D)");