Spreader

A fast spreadsheet logic library implemented in WebAssembly.

Spreader is a zero dependency module that implements spreadsheet logic - reading and writing data and formulas into cells, automatic recalculation, copying and moving cells, adding and deleting rows and columns and so on. It does not implement any spreadsheet UI. It is currently in alpha stage.

Install

npm install @centipede/spreader  --save

Quick start

const Spreader  = require('@centipede/spreader')
...
//Spreader is implemented in Webassembly so it needs to be loaded asynchronously
const spreaderLib = await Spreader();
try {
    //Create a new sheet
    const sheet = new spreaderLib.Sheet();
    //Set a cell to contain plain value. Instead of "A2" 
    //you can also say {x:0, y:1} or just [0, 1]. 
    //Columns are x and rows y, zero-based
    sheet.setValueCell("A2", "Hello ");
    sheet.setValueCell("B3", "World!");
    //Set a cell to contain formula
    sheet.setFormulaCell("A1", "A2 & B3");
    //Read calculated formula result
    let val = s.getValue("A1");
    // val is "Hello Wolrd!" here
} finally {
    //release Webassembly resources
    s.delete();
}

Limits

Maximum possible size of a sheet is currently 65536 x 2147483648 (e.g. 2¹⁶ x 2³¹) cells. You can query this value via Sheet.maxSize property. Note that currently, sheets are held entirely in memory (there is no 'offloading' of unused data to some kind of storage). Thus, depending on how much memory you have available the actual limit on how big a sheet you will be able to create might be lower than maximum.

There is no hard limit on things like:

• Maximum length of cell's string value
• Maximum number of function arguments (for functions that support variable number of arguments like SUM)
• Maximum level of nesting in formulas or anything else in the library. Instead, those are limited by available memory. In practice such limit is quite a bit larger than traditional 255 of Excel.

Cell and Area coordinates

Cell coordinates in the API can be given in the usual "A1", "B2" format. Alternatively, and slightly faster, you can use {x:..., y:...} objects or [x, y] arrays. In the later case x and y are zero based so {x:0, y:0} and [0, 0] correspond to "A1".

Similarly area coordinates can be given either as "A1:B2" or as {origin:{x:..., y:...}, size:{width:..., height:...}} or as [x, y, width, height], whichever suits your needs more. As with individual cells, using "A1:B2" format is slightly slower.

Cell values

Spreader supports the following cell value types: null (e.g. blank cell), boolean, number, string and instances of its own ErrorValue (e.g. ErrorValue.InvalidReference) that represent the usual spreadsheet #-errors (e.g. #REF!).

Numbers contained in a cell are never NaNs and never infinite. Setting a NaN or infinite value cell will result in an ErrorValue instead.

Strings you set into a cell via sheet.setValueCell() call do not need to be escaped - they are always taken to be literal. For example sheet.setValueCell("A1", "=3") will result in a cell holding literal "=3" value as if you typed '=3 in Excel or other spreadsheets.

Supported formulas

Spreader supports all the operators (e.g. =, +, >, * etc.) supported by Excel.

Dynamic array formulas are fully supported. Therefor there is no need for ARRAYFORMULA and it isn't recognized.

The following functions are currently implemented:

Expand

• A
  ADDRESS, AVERAGE, AVERAGEA, AVERAGEIF
• C
  CEIL, CHOOSE, COLUMN, CONCAT, CONCATENATE, COUNT, COUNTA
• D
  DATE, DATEDIF, DAY, DAYS
• E
  EDATE, EOMONTH, ERROR.TYPE
• F
  FIND, FLOOR
• H
  HLOOKUP, HOUR
• I
  IF, INDEX, INDIRECT, INT, ISBLANK, ISERR, ISERROR, ISEVEN, ISLOGICAL, ISNA, ISNONTEXT, ISNUMBER, ISODD, ISOWEEKNUM, ISTEXT
• L
  LEFT, LEN, LOWER
• M
  MATCH, MAX, MAXA, MID, MIN, MINA, MINUTE, MOD, MONTH, MROUND
• N
  NOT, NOW
• O
  OR
• R
  REPLACE, RIGHT, ROUND, ROUNDDOWN, ROUNDUP, ROW
• S
  SECOND, SIGN, STDEV, STDEV.P, STDEV.S, STDEVA, STDEVP, STDEVPA, SUBSTITUTE, SUM, SUMIF, SWITCH
• T
  TIME, TODAY, TRANSPOSE, TRIM
• U
  UPPER
• V
  VLOOKUP
• W
  WEEKDAY, WEEKNUM
• X
  XOR
• Y
  YEAR

Recalculation

By default sheet recalculation is automatic. You can suspend it using sheet.suspendRecalc() and resume it again using sheet.resumeRecalc(). Suspend calls can nest and each is "undone" by a corresponding resume. While suspended you can manually recalculate a sheet using sheet.recalculate().

Manipulating sheet size

Similar to how visual spreadsheets behave sheet size (as returned by sheet.size()) is dynamic and you don't manipulate it directly. When you set any cell to a non-null value sheet automatically expands to encompass it if it is outside the current size. It doesn't automatically contract, however. To reduce size you can use sheet.deleteColumns() and sheet.deleteRows() calls. Those, as well as sheet.insertColumns() and sheet.insertRows() can be used to delete/insert rows and columns anywhere in the sheet. Just like in visual spreadsheets all the references in formulas will be automatically adjusted to account for insertion or deletion.

Copying and moving cells

Normal copying and moving semantics of spreadsheets are also fully supported. You can use:

• sheet.copyCell() to copy a single cell to a single cell or area.
• sheet.copyCells() (note the plural) to copy an area to another location given by its top left corner
• sheet.moveCell() to move a single cell to a new location (also a single cell)
• sheet.moveCells() to move a cell area to a new location given by its top left corner

For all these calls the formula references are adjusted in normal spreadsheet fashion.

Roadmap and missing features

Spreader is currently in alpha - implemented features work and work well but many desirable things are missing. In particular, it is currently impossible to implement a full, performant spreadsheet UI on top of it. This is mostly due to lack of things such as change notifications, undo and support of keeping track of cell formatting. With this in mind the following features are on the roadmap

• Change notifications to enable clients to react to cells changed during recalculation
• Ability to associate abstract formatting information with cells rows and columns. Spreader itself doesn't care about formatting - it just needs to keep track of it for clients to act upon.
  • Support conditional formatting formulas. Similar to above associate opaque format with boolean formulas and tell the client which one to use.
• Support optional undo. It needs to be optional because it will slow things down and not all clients need it.
• Support more functions in formulas
• Support localized formula input. Currently formula syntax must use US English syntax: . as decimal separator, , to separate arguments. Excel allows using , and ; for languages that use comma as decimal separator.
• Serialization/deserialization. Likely in xlsx and json.
• Maybe: support doing spreadsheet math using decimals rather than doubles.