Model

Represents a spreadsheet model containing one or more workbooks.

Constructors

Constructor

new Model(): Model;

Returns

Model

Properties

Property	Modifier	Type
workbooks	public	Workbook[]
preconditions	static	Promise<boolean>

Accessors

hasData

Get Signature

get hasData(): boolean;

Returns

boolean

Methods

addWorkbook()

addWorkbook(jsf: Workbook): Workbook;

Adds a workbook into the model.

The model will accept any amount of workbooks, but most operations only support the first one added.

Parameters

Parameter	Type	Description
jsf	Workbook	The JSF workbook structure to add.

Returns

Workbook

The Workbook that was created and added.

---

addWorkbookFromXLSX()

addWorkbookFromXLSX(
   data:
  | ArrayBuffer
  | Buffer<ArrayBufferLike>
  | Uint8Array<ArrayBufferLike>,
   filename: string,
options?: AddWorkbookOptions): 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, so callers do not need to install or invoke the conversion library themselves. External references in the XLSX are also added to the model.

Parameters

Parameter	Type	Description
data	| ArrayBuffer | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>	Binary XLSX data (works in browsers and Node.js).
filename	string	Filename to associate with the workbook.
options	AddWorkbookOptions	Configuration options for workbook initialization.

Returns

Promise<Workbook>

A Promise resolving to the loaded Workbook.

---

addWorkbookFromXLSXFile()

addWorkbookFromXLSXFile(path: string, options?: AddWorkbookOptions): 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. Node.js only — uses fs. External references in the XLSX are also added to the model.

Parameters

Parameter	Type	Description
path	string	Path to the XLSX file.
options	AddWorkbookOptions	Configuration options for workbook initialization.

Returns

Promise<Workbook>

A Promise resolving to the loaded Workbook.

---

getWorkbook()

getWorkbook(workbookName?: string | null): Workbook | null;

Get a workbook instance from the model.

This is an incomplete method in that it will only return the first workbook added.

Parameters

Parameter	Type	Description
workbookName?	string | null	The name of the workbook to get.

Returns

Workbook | null

---

readCell()

readCell(formula: string): Cell | null;

Read a cell from the model.

Parameters

Parameter	Type	Description
formula	string	A reference or an expression to evaluate.

Returns

Cell | null

---

readCells()

readCells(formula: string): CellArray;

Read a 2D array of cells from the model.

Parameters

Parameter	Type	Description
formula	string	A reference or an expression to evaluate.

Returns

CellArray

---

recalculate()

recalculate(): void;

Pretend to recalculate the model.

WARNING: This just bumps the lastWrite counter allowing it to be used for cache invalidation.

Returns

void

---

reset()

reset(): void;

Pretend to reset the model to its initial state.

WARNING: This is a no-op. The model will remain unchanged.

Returns

void

---

runFormula()

runFormula(formula: string): ReturnValue;

Run a formula in the model.

This is a low-level method that simply evaluates the formula and returns the raw result.

WARNING: The evaluator is VERY limited and does not support most spreadsheet functions!

Parameters

Parameter	Type	Description
formula	string	The formula to run.

Returns

ReturnValue

---

toJSF()

toJSF(workbookName?: string): Workbook | null;

Convert a workbook in the model into a JSF object.

Parameters

Parameter	Type	Description
workbookName?	string	The name of the workbook to convert. If null, the first workbook is used.

Returns

Workbook | null

---

write()

write(
   formula: string,
   value: CellValue,
   doRecalc?: boolean): void;

Write a value to a cell.

WARNING: While the value does get written to the cell, dependent cells will not be updated.

Parameters

Parameter	Type	Default value	Description
formula	string	undefined	A reference to a cell.
value	CellValue	undefined	The new value.
doRecalc?	boolean	true	Should the model pretend to do recalculation after the write?

Returns

void

---

writeMultiple()

writeMultiple(pairs: [string, CellValue][], opts?: {
  forceRecalc?: boolean;
  skipRecalc?: boolean;
}): void;

Perform multiple writes of value to cell.

WARNING: While the values do get written to the cells, dependent cells will not be updated.

Parameters

Parameter	Type	Description
pairs	[string, CellValue][]	A list of [reference, value] pairs.
opts	{ forceRecalc?: boolean; skipRecalc?: boolean; }	Options for the write operation.
opts.forceRecalc?	boolean	-
opts.skipRecalc?	boolean	-

Returns

void

---

writes()

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

Get a list of all writes that have been performed on the model.

Returns

[string, CellValue][]

A list of [cellId, value] pairs.

---

empty()

static empty(): Model;

Create an “empty” Model.

A convenience method for creating a new Model from scratch without needing to provide JSF data. The returned model contains one workbook, with one worksheet named “Sheet1”, with a single empty cell.

Returns

Model

---

fromCsf()

static fromCsf(): void;

Returns

void

---

fromJSF()

static fromJSF(jsf: Workbook, options?: AddWorkbookOptions): Model;

Create a model from a JSF structure.

Parameters

Parameter	Type	Description
jsf	Workbook	A JSF workbook structure.
options	AddWorkbookOptions	Configuration options for workbook initialization.

Returns

Model

---

fromXLSX()

static fromXLSX(
   data:
  | ArrayBuffer
  | Buffer<ArrayBufferLike>
  | Uint8Array<ArrayBufferLike>,
   filename: string,
options?: AddWorkbookOptions): Promise<Model>;

Create a model from XLSX binary data.

This is a convenience method that wraps @borgar/xlsx-convert so callers can load an Excel file without installing or invoking the conversion library themselves.

Parameters

Parameter	Type	Description
data	| ArrayBuffer | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>	Binary XLSX data (works in browsers and Node.js).
filename	string	Filename to associate with the workbook.
options	AddWorkbookOptions	Configuration options for workbook initialization.

Returns

Promise<Model>

A Promise resolving to a new Model instance containing the loaded workbook.

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: string, options?: AddWorkbookOptions): Promise<Model>;

Create a model from an XLSX file path.

This is a convenience method that wraps @borgar/xlsx-convert so callers can load an Excel file without installing or invoking the conversion library themselves. Node.js only — uses fs.

Parameters

Parameter	Type	Description
path	string	Path to the XLSX file.
options	AddWorkbookOptions	Configuration options for workbook initialization.

Returns

Promise<Model>

A Promise resolving to a new Model instance containing the loaded workbook.

Example

const model = await Model.fromXLSXFile('budget.xlsx');
const total = model.readCell('=SUM(D:D)');