Status: approved (2026-11-16). This is the design that implementation follows. §12 records the decisions taken in review. Any change to the design is made by editing this document in a PR.
Conventions in this document:
[to verify]marks an OOXML or platform fact that must be checked against ECMA-376 or a real file before the code relies on it. Most were resolved by the manual check in conformance.md, which names the corpus file that checks each one and records the result. That check was done in Excel for Mac on 2026-11-17; Excel for Windows and Apple Numbers were not checked by hand. Facts it confirmed say (confirmed in Excel for Mac, 2026-11-17).[placeholder, set in JSE-n]marks a number that has not been measured. The task named sets it.JSE-nnames the implementation task of this rewrite that owns a decision (JSE-2 zip and model, JSE-3 writer, JSE-4 sheet features, JSE-5 CSV, JSE-6 reader, JSE-7 DOM, JSE-8 performance and worker, JSE-9 conformance).- ECMA-376 references are to Part 1 (Fundamentals and Markup Language Reference), 5th edition, transitional schema, unless stated otherwise.
- Goals, non-goals, out of scope
- Entry points
- Data model
- Builders and helpers
- Write, read, CSV, DOM, worker, import, format and render APIs
- Zip codec
- Errors and warnings
- Security model
- Versioning, compatibility, runtime support
- Worked examples
- Appendix: OOXML reference tables
- Design decisions
- Roadmap beyond 2.0
- Read and write
.xlsx(Office Open XML SpreadsheetML, transitional) and.csv(RFC 4180) from one typed model. - 100% TypeScript, strict mode, with the public types as the primary documentation.
- Zero runtime dependencies. Zip container and CRC-32 in-house; deflate/inflate through the platform's
CompressionStream/DecompressionStream. - Runs everywhere modern JS runs: browsers, Web Workers, Node. No framework dependency, and no access to
window,documentor any other global at import time (SSR-safe). - Tree-shakable: a writer-only user never ships the reader, the CSV code or the DOM code (§2).
- Safe on untrusted input: the reader enforces zip-bomb, XML and memory limits by default (§8).
- Serve the consumers: dataset export (
{ columns, data }), HTML table export, file import back to{ columns, data }, and a future read-only viewer that needs styles, merges, sizes, freeze panes, number formats and formula text with cached values. - Faithful output: files open in Excel (Windows and Mac), LibreOffice, Numbers and Google Sheets without a repair prompt.
The first two are later phases (§13), not permanent exclusions.
- Lossless round-trip of arbitrary files.
write(read(file))keeps everything in the model below. Parts the model does not cover (charts, drawings, pivots, comments, and so on) are dropped, with a warning on read. There is no "pass unknown parts through" mode in 2.0; preserving unknown parts is planned for 2.x. - Formula evaluation. Formulas are stored as text with their cached values. Evaluation is a separate, later module (3.x).
- A synchronous API. All file I/O is
async(§6). - Pixel-exact layout. Column widths, auto-width and row heights use the spec's character-width formulas, not font metrics.
- Compatibility with the 1.x API. 2.0 is a rewrite. The 1.x constructor that took injected
jszip/saveAsinstances is gone.
The project's end goal is to read, write and view every kind of Excel and CSV file. Everything below is therefore a phase boundary, not a permanent non-goal: §13 places each item in a later phase, and 2.0's design must not close the door on any of them.
| Feature | Notes |
|---|---|
.xls (BIFF8, Excel 97–2003) |
The reader detects it and throws UNSUPPORTED_FORMAT. |
.xlsb (binary workbook) |
Detected, UNSUPPORTED_FORMAT. |
.ods (OpenDocument) |
Detected, UNSUPPORTED_FORMAT. |
| Charts, images, drawings, shapes | Dropped on read with a warning. |
| Pivot tables, slicers, timelines | Dropped on read with a warning. |
Macros (.xlsm VBA projects) |
An .xlsm file is read as a workbook without its VBA part; the writer never produces .xlsm. |
| Encrypted or password-protected files | Detected (they are CFB containers, not zip), UNSUPPORTED_FORMAT. |
| Formula evaluation | Stored formulas and cached values only. |
| Also not in 2.0 (planned later) | Data validation, conditional formatting, comments/notes, Excel tables (ListObjects), sheet/workbook protection, sparklines, external links, streaming row-by-row reader and writer. |
One npm package, javascript-excel, with subpath exports. package.json declares "sideEffects": false. Every module is free of top-level side effects, so bundlers can drop anything not imported.
| Entry | Exports | Pulls in | Tree-shaking intent |
|---|---|---|---|
javascript-excel |
Model types; address, date, colour and style helpers; fromDataset, fromDatasets, toDataset; xlsx writer: toUint8Array, toBlob; error classes and isExcelError |
Zip writer, XML writer | The default "build a file" path. No reader, no CSV, no DOM. |
javascript-excel/read |
read, readSheetNames, detectFormat, ReadOptions, ReadLimits, DEFAULT_READ_LIMITS |
Zip reader, XML pull tokenizer | Only apps that open files pay for the reader. |
javascript-excel/csv |
parseCsv, readCsv, toCsv, toCsvBlob, option types |
Nothing from the xlsx code | CSV-only apps ship a few kB of CSV code and the model types. |
javascript-excel/dom |
fromTable, download |
DOM APIs, called only inside functions | The only module that touches document. Safe to import during SSR; calling it without a DOM throws ENVIRONMENT_UNSUPPORTED. |
javascript-excel/worker |
exposeWorker (worker side), createWorkerClient (main-thread side) |
Writer and reader, inside the worker only | Moves big jobs off the main thread. Main-thread code that imports only createWorkerClient does not ship the engine. |
javascript-excel/import |
importDataset, detectHeader, inferColumnTypes, coerceColumns, parseNumber, parseDate, mapColumns, applyMapping, option and result types |
Reader and CSV reader | Importing user files into { columns, data } (§5.6). Apps that only write never load it. |
javascript-excel/format |
formatValue, formatCell, FormatOptions, FormattedValue |
Format-code parser and renderer; locale data from Intl |
Only apps that show formatted values (viewers, previews) pay for it. |
javascript-excel/render |
createRenderSheet and its geometry, cell, navigation and copy functions (§5.8) |
Nothing from the reader or writer; number formatting only through the format option |
Only viewers pay for it. |
Rules:
- Deep imports (
javascript-excel/dist/...) are not part of the API, and theexportsmap blocks them. - Both ESM and CJS builds ship. Because of the dual-package hazard,
instanceof ExcelErrorcan fail when ESM and CJS copies are mixed in one app, so the documented check isisExcelError(err)orerr.code(§7). - Types are exported from the entry that uses them. Shared model types are re-exported from every entry, so
import type { Workbook } from 'javascript-excel/read'works.
- Plain data, no classes. A
Workbookis a tree of plain objects, arrays, strings, numbers, booleans andDates. It is thereforestructuredClone-able and can be sent to a worker withpostMessage. Behaviour lives in free functions. - One model for read and write. The writer accepts loose input (
CellInput). The reader returns the normalised form (Cell), which is also valid writer input. - Zero-based indices, A1 strings for references.
rows[0][0]is cellA1. Ranges and references in the model are A1 strings ('A1:C3'). Helpers convert between them (§4.1). - Sparse by design.
rowsand each row's cells are arrays that may have holes. A hole is "no cell". - Unknown fields are ignored by the writer, so the model can grow in minor releases (§9).
- Optional means
undefinedis allowed: every optional property is declaredprop?: T | undefined, so consumers withexactOptionalPropertyTypescan pass an explicitundefined, which the writer treats as absent. Declarations below omit the| undefinedfor brevity.
/** C is the cell type: CellInput for writer input, Cell for reader output. */
export interface Workbook<C = CellInput> {
sheets: Sheet<C>[]; // at least one sheet (NO_SHEETS otherwise)
/** Index into `sheets` of the sheet shown when the file opens. Default 0. Must not be hidden. */
activeSheet?: number;
/** Use the 1904 date system (workbookPr/@date1904). Default false (1900 system). */
date1904?: boolean;
properties?: DocProperties;
definedNames?: DefinedName[];
/** Workbook default font, used for fonts[0] in styles.xml and for width maths. Default Calibri 11. */
defaultFont?: Font;
/** Reader output only: theme colours and fonts, for resolving theme colours (§3.5.6). Ignored on write in 2.0. */
theme?: Theme;
/** Reader output only: a custom indexed palette from styles.xml/colors, if the file has one. */
indexedColors?: string[]; // ARGB, index 0..63
/** Calculation flags (calcPr). */
calc?: { fullCalcOnLoad?: boolean | 'auto' }; // write default 'auto', see §5.1
}
export interface DocProperties {
// docProps/core.xml (Dublin Core and OPC core properties)
title?: string;
subject?: string;
creator?: string;
keywords?: string;
description?: string;
lastModifiedBy?: string;
category?: string;
created?: Date; // write default: now
modified?: Date; // write default: now
// docProps/app.xml (extended properties)
company?: string;
manager?: string;
application?: string; // write default 'javascript-excel'
// docProps/custom.xml. An array (not an object keyed by name) so file-supplied names are never object keys.
custom?: Array<{ name: string; value: string | number | boolean | Date }>;
}
export interface DefinedName {
name: string; // e.g. 'TaxRate', '_xlnm.Print_Area'
/** Formula text without '=': "'Sheet 1'!$A$1:$B$4" */
ref: string;
/** Sheet index when the name is local to a sheet (localSheetId). */
sheet?: number;
hidden?: boolean;
comment?: string;
}Defined names follow Excel's rules (INVALID_DEFINED_NAME otherwise): the name starts with a letter, _ or \, continues with letters, digits, ., _, \ or ?, is at most 255 characters, and is not a cell reference (A1, XFD1048576), an R1C1 reference or R/C on its own. Names are unique per scope (workbook, or sheet), case-insensitively, and ref is formula text, not validated further. Names starting with _xlnm. are reserved for the writer.
Print areas, print titles and the autofilter database are defined names in OOXML (_xlnm.Print_Area, _xlnm.Print_Titles, _xlnm._FilterDatabase). The model exposes them as sheet properties (§3.6, §3.7). The writer generates those defined names, and the reader maps them back and does not repeat them in definedNames.
export interface Sheet<C = CellInput> {
/** Validated on write, see "Sheet names" below. */
name: string;
/** rows[r][c]; both levels may be sparse. Max 1,048,576 rows x 16,384 columns. */
rows: Array<Array<C | undefined> | undefined>;
/** Per-row properties, indexed like `rows`. */
rowProps?: Array<RowProps | undefined>;
/** Per-column properties, index 0 = column A. */
colProps?: Array<ColumnProps | undefined>;
/** Merged ranges, A1 strings: ['A1:C1']. Must not overlap. */
merges?: string[];
autoFilter?: string; // range, e.g. 'A1:F1'
view?: SheetView;
print?: PrintSetup;
state?: 'visible' | 'hidden' | 'veryHidden'; // default 'visible'
tabColor?: Color;
/** Default column width in characters (sheetFormatPr/@defaultColWidth). */
defaultColWidth?: number;
/** Default row height in points (sheetFormatPr/@defaultRowHeight). */
defaultRowHeight?: number;
/** Style applied under column, row and cell styles on write (§3.5.7). Not produced by the reader. */
defaultStyle?: Style;
/** Reader output only: the used range computed from the cells read, e.g. 'A1:F120'. */
dimension?: string;
}
export interface RowProps {
height?: number; // points, 0..409
hidden?: boolean;
style?: Style;
outlineLevel?: number; // 0..7
collapsed?: boolean;
}
export interface ColumnProps {
width?: ColumnWidth;
hidden?: boolean;
style?: Style;
outlineLevel?: number; // 0..7
collapsed?: boolean;
}
/**
* number or { wch } = width in characters, as Excel's UI shows it (8.43 is the Calibri 11 default).
* { wpx } = width in pixels at 96 dpi.
* 'auto' = estimated by the writer from the column's text.
* Reader output is always a number in characters.
*/
export type ColumnWidth = number | { wch: number } | { wpx: number } | 'auto';Column width conversion (ECMA-376 §18.3.1.13, col/@width). The file stores the width including padding. With the maximum digit width MDW of the default font:
- characters to file width:
width = Truncate((wch * MDW + 5) / MDW * 256) / 256 - pixels to file width:
width = Truncate(((wpx - 5) / MDW) * 100 + 0.5) / 100, then the formula above - file width to pixels (reader):
wpx = Truncate(((256 * width + Truncate(128 / MDW)) / 256) * MDW)
MDW = 7 px for Calibri 11, the default font. With it, the formula turns Excel's default 8.43 characters into width="9.140625", the value Excel files carry for default-width columns (unit-tested). Excel shows the widths the model asks for, in characters (confirmed in Excel for Mac, 2026-11-17; conformance.md, 13-columns-rows). Pixel widths depend on the platform and were not checked. The writer uses MDW = 7 whatever the default font is [to verify for other default fonts]. The model's character unit is the one Excel's UI shows. The maximum width is 255 characters.
'auto'measurescellText()of every cell in the column (the widest line; East Asian wide characters and emoji count two), adds 2 characters of padding and clamps the result to 8.43..60 characters. 60 is a readability choice made in JSE-4, not a measurement. It writesbestFit="1". Number formats and fonts are not taken into account.- Width 0 also writes
hidden="1", as Excel does for a zero-width column. A rowheightof 0 likewise hides the row. - Columns without
colPropsget no<col>element, unless the sheet has adefaultStyle, which is written as a<col>covering those columns throughXFD. Consecutive columns with identical properties share one<col min max>. Column and row styles are written on<col style>and<row s customFormat>as well as being merged into the cells (§3.5.7). - Every
colPropsandrowPropsfield is validated (INVALID_SHEET_PROPERTY): widths 0..255 characters, heights 0..409 points,outlineLevel0..7, booleans.sheetFormatPrcarries the default sizes and the highest outline levels.
Sheet names. The writer throws INVALID_SHEET_NAME unless the name:
- is 1 to 31 characters long. Excel counts code points: it accepts 30 x's and 😀, which is 31 code points and 32 UTF-16 units (confirmed in Excel for Mac, 2026-11-17; conformance.md, 17-workbook).
validateSheetName, the writer andsanitizeSheetNamecount code points too (from 2.0.0-beta.1; before, they counted UTF-16 units and rejected such names); - contains none of
\ / ? * [ ] :; - does not start or end with an apostrophe
'; - is not
History, which Excel reserves: renaming a tab to it gives "History is a reserve word" (confirmed in Excel for Mac, 2026-11-17; conformance.md, 17-workbook). The check ignores case (history,HISTORY); onlyHistoryitself was tried in Excel.
Names must be unique, compared case-insensitively (DUPLICATE_SHEET_NAME). sanitizeSheetName() (§4.6) makes any string valid.
/** What the writer accepts in a cell slot. */
export type CellInput = CellValue | Cell | null | undefined;
/** Bare values. A string is always text, even when it starts with '='. Only `Cell.formula` makes a formula. */
export type CellValue = string | number | boolean | Date | CellErrorValue | RichText;
export interface CellErrorValue { error: ErrorCode }
export interface RichText { richText: RichTextRun[] }
export interface RichTextRun { text: string; font?: Font }
export type ErrorCode =
| '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A';
export type CellType = 'string' | 'number' | 'boolean' | 'date' | 'error' | 'richText' | 'empty';
export interface Cell {
/** Literal value, or the cached result when `formula` is set. null/undefined = empty (styled if `style` is set). */
value?: CellValue | null;
/** Formula text without the leading '='. A leading '=' is accepted on write and stripped. */
formula?: string;
/** Array formula (CSE) range, e.g. 'D1:D3'; set on the anchor cell only. */
arrayRef?: string;
/**
* Reader: always set; describes `value` (for formulas, the cached value).
* Writer: optional. If set, it must match `value` (INVALID_CELL otherwise). It is a check, not a coercion.
*/
type?: CellType;
style?: Style;
hyperlink?: Hyperlink;
}
export type Hyperlink =
| string // external URL, shorthand for { target }
| { target: string; tooltip?: string } // external: http(s), mailto, ...
| { location: string; tooltip?: string }; // internal: "'Sheet 2'!A1" or a defined nameHow each value is written:
| Input | SpreadsheetML | Notes |
|---|---|---|
string |
t="s" (shared string) or t="inlineStr" |
Text, never parsed. Max 32,767 characters (STRING_TOO_LONG). |
number |
t="n" |
Must be finite (INVALID_NUMBER for NaN, ±Infinity). |
boolean |
t="b" |
|
Date |
t="n" + date numFmt |
Converted to a serial (§3.4.1). If the cell has no numFmt, built-in id 14 is used. |
{ error } |
t="e" |
Only the seven codes above. Other #... strings are not accepted in 2.0 [to verify: how newer Excel errors such as #SPILL! are stored in files; no file saved by Excel 365 has been checked yet]. |
{ richText } |
shared string with <r> runs |
|
Cell with formula |
<f> + cached <v> when value is set |
§3.4.2 |
null / undefined / hole |
no <c>, or a styled empty <c> if the Cell has a style |
Text encoding follows ECMA-376 ST_Xstring: characters not allowed in XML 1.0, and \r, which XML parsers turn into \n, are written as _xHHHH_. Text that already contains _xHHHH_ literally is escaped as _x005F_xHHHH_. The reader reverses both. Leading and trailing whitespace is kept with xml:space="preserve".
The reader returns each cell as a Cell with type set. Bare values are never returned. cellText(cell) (§4.5) gives the plain text of any cell.
Excel stores dates as serial numbers. The writer converts Date to a serial and the reader converts back, both in the time zone set by dateZone (default 'local', see §12 Q2).
- 1900 system (default): serial 1 = 1900-01-01. Excel treats 1900 as a leap year, so serial 60 is the non-existent 1900-02-29 and every serial from 61 onwards is offset by one. The writer writes dates from 1900-03-01 onwards with the epoch 1899-12-30, and earlier dates with epoch 1899-12-31, which matches Excel. The reader returns serial 60 as a number with warning
INVALID_DATE_SERIAL. Serials from 0 to below 1 are Excel's day 0 ("1900-01-00"), which is how time-only values such as 0.5 (12:00) are stored.serialToDatereturns them on 1899-12-31, andserialToDate(60)returns 1900-03-01; flagging serial 60 is the reader's job. - 1904 system (
date1904: true): serial 0 = 1904-01-01. - Range: 1899-12-31 (1904 system: 1904-01-01) to 9999-12-31. Outside it, or for an invalid
Date, the writer throwsINVALID_DATE. 1899-12-31 is Excel's day 0 ("1900-01-00"), where time-only values live as serials 0 to below 1.serialToDatereturns them on that day, sodateToSerialaccepts it too and time-only cells round-trip. - Fractions are times of day; the writer keeps millisecond precision.
Date detection on read. A numeric cell is returned as type: 'date' with a Date value when its number format is a date or time format:
- built-in ids 14–22, 45 and 47 (46 is
[h]:mm:ss, an elapsed time); - built-in ids 27–36 and 50–58 (locale-dependent East Asian date formats). Excel for Mac in de-DE displays them as dates (confirmed in Excel for Mac, 2026-11-17); in an East Asian locale
[to verify: not tried; conformance.md, 11-number-formats-locale]; - custom codes that, after removing quoted literals, backslash escapes and bracketed sections other than the elapsed-time tokens
[h],[m],[s], contain a date/time token (y,m,d,h,s,AM/PM,A/P,e,g,b)[to verify against more real-world files; the reader tests cover the common codes].
Elapsed-time formats ([h]:mm:ss) are durations, not dates. The reader returns them as type: 'number' and leaves formatting to the caller. With ReadOptions.dates: 'serial', no conversion happens and date cells come back as type: 'number'.
formulais stored verbatim in<f>, after the leading=is stripped and the text is XML-escaped. The library does not parse or validate it.valueon a formula cell is the cached result, written to<v>. Excel recalculates on open. LibreOffice, by default, and file previewers, mail previews and the future viewer show the cached value, so callers should supply one when they know it.fromDatasettotals compute it (§4.3).- When any formula cell has no cached value and
calc.fullCalcOnLoadis'auto'(the default), the writer setscalcPr/@fullCalcOnLoad="1". - Functions added after Excel 2007 must carry the
_xlfn.prefix in the file (for example_xlfn.XLOOKUP), or Excel shows#NAME?. In 2.0 the writer stores text verbatim and the reader returns it verbatim, prefix included (§12 Q11). A later 2.x minor adds opt-in auto-prefixing for post-2007 functions, plus a reader option that strips the prefixes for display. - Shared formulas (
<f t="shared">): the reader expands them into per-cell formula text by shifting relative A1 references (§12 Q6). Array formulas come back asformulaplusarrayRefon the anchor cell; the other cells of the range carry only cached values. Dynamic-array metadata (metadata.xml) is not modelled. - Maximum formula length is 8,192 characters (Excel limit). The writer does not enforce it.
One canonical style model, used for cells, rows, columns, rich-text runs and the defaults. Every field is optional. The writer deduplicates complete styles into cellXfs (one xf per distinct style).
export interface Style {
font?: Font;
fill?: Fill;
border?: Border;
alignment?: Alignment;
numFmt?: NumFmt;
protection?: { locked?: boolean; hidden?: boolean }; // only takes effect once sheet protection exists (later)
}export interface Font {
name?: string; // 'Calibri'
size?: number; // points
color?: Color;
bold?: boolean;
italic?: boolean;
underline?: boolean | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting'; // true = 'single'
strike?: boolean;
vertAlign?: 'superscript' | 'subscript' | 'baseline';
/** Font family class: 0 n/a, 1 Roman, 2 Swiss, 3 Modern, 4 Script, 5 Decorative. */
family?: number;
charset?: number;
scheme?: 'major' | 'minor' | 'none';
outline?: boolean; // Mac-only rendering
shadow?: boolean; // Mac-only rendering
condense?: boolean;
extend?: boolean;
}In rich-text runs the writer emits rFont instead of name, as CT_RPrElt requires.
/** A string is shorthand for a solid fill in that colour: fill: 'FFFF00'. */
export type Fill = string | PatternFill | GradientFill;
export interface PatternFill {
type?: 'pattern';
pattern: PatternType;
/** Pattern colour. For 'solid' this is the cell colour (OOXML puts a solid fill in fgColor). */
fgColor?: Color;
bgColor?: Color;
}
export type PatternType =
| 'none' | 'solid' | 'mediumGray' | 'darkGray' | 'lightGray'
| 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis'
| 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis'
| 'gray125' | 'gray0625'; // ST_PatternType, all 19 values
export interface GradientFill {
type: 'gradient';
gradient: 'linear' | 'path';
degree?: number; // linear only
left?: number; right?: number; top?: number; bottom?: number; // path only, 0..1
stops: Array<{ position: number; color: Color }>; // position 0..1
}The writer always reserves fills[0] = none and fills[1] = gray125, which Excel requires. User fills start at index 2.
export interface Border {
left?: BorderSide;
right?: BorderSide;
top?: BorderSide;
bottom?: BorderSide;
diagonal?: BorderSide;
diagonalUp?: boolean;
diagonalDown?: boolean;
}
export interface BorderSide {
style: BorderStyle;
color?: Color; // default: automatic (black)
}
/** ST_BorderStyle, all 14 values. */
export type BorderStyle =
| 'none' | 'thin' | 'medium' | 'thick' | 'double' | 'hair'
| 'dotted' | 'dashed' | 'dashDot' | 'dashDotDot'
| 'mediumDashed' | 'mediumDashDot' | 'mediumDashDotDot' | 'slantDashDot';Each side is independent, with its own style and colour. The writer emits the sides in schema order (left, right, top, bottom, diagonal), because Excel rejects out-of-order elements. borderAll(side) (§4.4) builds the common "all four sides" border (issue #34).
export interface Alignment {
horizontal?: 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
vertical?: 'top' | 'center' | 'bottom' | 'justify' | 'distributed';
wrapText?: boolean;
shrinkToFit?: boolean;
/** Indent level, in steps of about three character widths. Excel shows it for left, right and distributed. */
indent?: number; // Excel UI caps at 250 (confirmed in Excel for Mac, 2026-11-17)
/** Degrees, -90..90, positive = counter-clockwise; or 'vertical' for stacked text. */
rotation?: number | 'vertical';
readingOrder?: 'context' | 'ltr' | 'rtl';
justifyLastLine?: boolean;
}Mapping to CT_CellAlignment:
| Model | OOXML |
|---|---|
rotation: 0..90 |
textRotation="0".."90" |
rotation: -1..-90 |
textRotation="91".."180" (that is, 90 - rotation) |
rotation: 'vertical' |
textRotation="255" |
readingOrder: 'context' / 'ltr' / 'rtl' |
readingOrder="0" / "1" / "2" |
/** number = built-in format id (0..163); string = format code. */
export type NumFmt = number | string;- Numbers are built-in ids. The writer emits
numFmtIdwith no<numFmt>element. Ids that the spec does not define, or defines only per locale, are accepted but render differently by locale (§11.2). - Strings are custom codes, written as
<numFmt>with ids allocated from 164 upward, one per distinct code. The one exception is'General', which maps to id 0. The writer does not map other strings to built-in ids, because a built-in id such as 14 renders in the user's locale while the string'mm-dd-yy'should render literally (§12 Q5). - The reader returns built-in ids as numbers and custom codes as strings, so
readthenwritekeeps formats unchanged. BUILTIN_NUM_FMTSexports the spec table (§11.2),isDateFormat(fmt)the detection rule from §3.4.1.javascript-excel/format(§5.7) renders number formats:1234.5with#,##0.00shows as1,234.50(§12 Q14).
/**
* string: 'RRGGBB', 'AARRGGBB', '#RRGGBB' or '#AARRGGBB' (case-insensitive) = { rgb }.
* The writer normalises to upper-case ARGB, with alpha FF when omitted.
*/
export type Color =
| string
| { rgb: string } // ARGB 'FF336699'
| { theme: number; tint?: number } // theme colour index 0..11, tint -1..1
| { indexed: number } // legacy palette 0..63, 64 = system foreground, 65 = system background (confirmed in Excel for Mac, 2026-11-17)
| { auto: true }; // automatic colourAll four forms map one to one to CT_Color attributes (rgb, theme + tint, indexed, auto), and the reader returns the same form the file used. The reader returns object forms only, never the string shorthand. Notes:
- Alpha. Excel ignores the alpha byte of
rgb; the writer still writes it. - Theme index order. The index refers to the theme's
clrSchemewith the first two pairs swapped: 0 =lt1(Background 1), 1 =dk1(Text 1), 2 =lt2, 3 =dk2, 4–9 =accent1–accent6, 10 =hlink, 11 =folHlink(confirmed in Excel for Mac, 2026-11-17; conformance.md,12-colours). - Tint is applied to the HSL luminance as in ECMA-376 §18.8.19 (
CT_Color/@tint). - Resolving.
resolveColor(color, { theme, indexedColors })(§4.4) returns a concrete ARGB string. It uses the file's theme and palette, or the defaults (the Office theme and the standard 64-colour palette) when the file has none. The viewer andfromTableneed it. - On write, theme colours refer to the default Office theme that the writer embeds as
xl/theme/theme1.xml. Custom themes are not written in 2.0.
export interface Theme {
/** ARGB in clrScheme order: dk1, lt1, dk2, lt2, accent1..6, hlink, folHlink. */
colors: string[];
majorFont?: string; // latin typeface
minorFont?: string;
}A cell's written style is a deep merge, with later layers winning field by field:
sheet.defaultStyle → colProps[c].style → rowProps[r].style → cell.style
font, alignment, protection and each border side merge by field. fill and numFmt replace as a whole. Excel itself does not inherit like this: each cell's xf is complete, and row and column styles only apply to cells created later. The writer therefore resolves each cell's full style. It also writes the row and column styles themselves (row/@s, col/@style), so new cells typed in Excel pick them up (§12 Q4).
The reader does the reverse: cell.style is the cell's own complete xf, and rowProps/colProps carry the row and column styles. It does not try to factor shared parts back out. Cells that use the same xf share one frozen (Object.freeze) Style object (§12 Q8). To change a style, copy it first: { ...cell, style: mergeStyles(cell.style, change) }. A cell whose xf is the default (index 0) has no style.
export interface SheetView {
/** Frozen panes: rows above and columns left of the split stay visible. */
freeze?: { rows?: number; cols?: number };
rightToLeft?: boolean; // sheetView/@rightToLeft: column A on the right
showGridLines?: boolean; // default true
showRowColHeaders?: boolean; // default true
zoom?: number; // percent, 10..400
activeCell?: string; // 'B2'
selection?: string; // 'B2:D5'
}freeze: { rows: 1 }writes<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>, withxSplit,topLeftCellandactivePaneadjusted whencolsis set. The reader reads onlystate="frozen"or"frozenSplit"panes intofreeze; plain split panes are ignored with a warning.rightToLeftflips the sheet. It is separate fromalignment.readingOrder, which sets text direction per cell.autoFilter: 'A1:F1'writes<autoFilter ref>and the hidden defined name_xlnm._FilterDatabase, local to the sheet. Filter criteria are not modelled.merges: the writer throwsOVERLAPPING_MERGEwhen ranges overlap, which Excel would otherwise repair. Values in covered cells (every cell but the top-left) are written as given. Excel keeps them hidden.view.activeCellandview.selectionwrite a<selection>element, in the active pane when panes are frozen (the active cell defaults to the pane's top-left cell).zoomwriteszoomScaleandzoomScaleNormal.tabColortakes anyColorand is written insheetPr.- Hyperlinks are set per cell (
Cell.hyperlink). The writer collects them into<hyperlinks>. External targets go to the sheet's relationships (xl/worksheets/_rels/sheetN.xml.rels, one relationship per distinct URL) withTargetMode="External". Internal locations use@location. The cell's value is the display text, and the cell keeps its own style (no automatic blue underline). External targets must have a scheme inWriteOptions.hyperlinkSchemes, matched case-insensitively (defaulthttp,https,mailto). URLs without a scheme (relative paths), and URLs with control characters, throwINVALID_HYPERLINK. A hyperlink in a file whoserefspans a range is attached to its top-left cell, with warningHYPERLINK_RANGE_REDUCED.
export interface PrintSetup {
orientation?: 'portrait' | 'landscape';
/** ST paper size code, e.g. 1 = Letter, 9 = A4. */
paperSize?: number;
/** Fit to N pages wide / tall; 0 = automatic. Sets sheetPr/pageSetUpPr/@fitToPage. */
fitTo?: { width?: number; height?: number };
scale?: number; // percent, 10..400; ignored when fitTo is set
margins?: { left?: number; right?: number; top?: number; bottom?: number; header?: number; footer?: number }; // inches
center?: { horizontal?: boolean; vertical?: boolean };
gridLines?: boolean;
headings?: boolean;
/** Written as the _xlnm.Print_Area defined name. */
printArea?: string; // 'A1:F40'
/** Written as _xlnm.Print_Titles. Rows '1:2', columns 'A:B'. */
printTitles?: { rows?: string; cols?: string };
/** Raw header/footer strings with Excel's &-codes, e.g. '&CPage &P of &N'. */
header?: { odd?: string; even?: string; first?: string };
footer?: { odd?: string; even?: string; first?: string };
}"Fit to width" is fitTo: { width: 1 }. A fitTo side that is omitted is written as 0 (automatic). Excel's own default for a missing attribute is 1, so the writer always writes both. <pageMargins> is always written, with Excel's "Normal" margins (0.7, 0.7, 0.75, 0.75, 0.3, 0.3 inches) for any side not given. <pageSetup>, <printOptions> and <headerFooter> are written only when set. An even header or footer sets differentOddEven, and a first-page one sets differentFirst.
All helpers are pure functions exported from javascript-excel.
export interface CellAddress { row: number; col: number } // zero-based
export interface RangeAddress { start: CellAddress; end: CellAddress }
export function encodeCol(col: number): string; // 0 -> 'A', 16383 -> 'XFD'
export function decodeCol(letters: string): number;
export function encodeCell(a: CellAddress): string; // { row: 0, col: 1 } -> 'B1'
export function decodeCell(ref: string): CellAddress; // accepts '$B$1'
export function encodeRange(r: RangeAddress): string;
export function decodeRange(ref: string): RangeAddress; // 'A1:C3'; 'A1' = single cellOut-of-bounds or malformed refs throw INVALID_REF.
export function getCell<C>(sheet: Sheet<C>, ref: string | CellAddress): C | undefined;
export function setCell<C>(sheet: Sheet<C>, ref: string | CellAddress, cell: C): void; // mutates sheet.rows
export function cellText(cell: CellInput, options?: { dateZone?: 'local' | 'utc' }): string; // rich text joined, errors as '#N/A', dates ISO 8601, formulas as their cached valueThis is the main builder. It serves react-data-export's dataset export and any vanilla or Vue user.
export function fromDataset<T>(dataset: Dataset<T>, options?: DatasetOptions<T>): Sheet;
/** Several blocks stacked on one sheet (replaces the old xSteps/ySteps). */
export function fromDatasets(
blocks: Array<DatasetBlock<any>>, // Dataset & { placement?: 'below' | 'right'; offset?: { rows?: number; cols?: number } }
options?: DatasetOptions<any> & { gap?: number }, // empty rows (or columns, for 'right') between blocks, default 1
): Sheet;
export interface Dataset<T> {
/** Falsy entries are skipped (conditional columns). Omitted: inferred from the keys of the first object row. */
columns?: Array<ColumnDef<T> | null | false | undefined>;
/** Objects (picked by key/path/value) or arrays (picked by index). */
data: readonly T[];
}
export type ColumnDef<T> = LeafColumn<T> | GroupColumn<T>;
export interface GroupColumn<T> {
/** Header group: its title spans its leaf columns (a merged header cell). */
title: string | RichText | Cell;
headerStyle?: Style;
children: Array<ColumnDef<T> | null | false | undefined>;
}
export interface LeafColumn<T> {
title?: string | RichText | Cell; // header cell; default: key/path, or '' for value/index accessors
// Accessor: use exactly one. With none: array rows use the leaf position, object rows throw INVALID_COLUMN.
/** Own property name, taken literally ('a.b' is a key containing a dot). */
key?: string;
/** Path into nested data: 'a.b', 'items[0].name', "a['x.y']". */
path?: string;
/** Computed value. */
value?: (row: T, ctx: { rowIndex: number }) => CellInput;
/** Array rows: index into the row. */
index?: number;
/** Coerce data cells (see the table below). Default 'auto': take values as they are. */
type?: 'auto' | 'string' | 'number' | 'boolean' | 'date' | 'datetime';
numFmt?: NumFmt;
style?: Style; // data cells of this column
headerStyle?: Style; // overrides options.headerStyle
width?: ColumnWidth | 'auto';
hidden?: boolean;
/** Totals row entry for this column. */
total?: ColumnTotal; // 'sum' | 'average' | 'count' | 'min' | 'max' | CellInput | ((ctx: { range: string; values: CellValue[] }) => CellInput)
}
export interface DatasetOptions<T> {
name?: string; // sheet name, default 'Sheet1'; an invalid name throws (§12 Q19)
origin?: string; // top-left cell of the block, default 'A1'
header?: boolean; // write header rows, default true
headerStyle?: Style; // default { font: { bold: true } }
freezeHeader?: boolean; // freeze all header rows, default false
autoFilter?: boolean; // last header row through last data row (totals excluded), default false
autoWidth?: boolean | AutoWidthOptions; // default false
rightToLeft?: boolean;
totals?: { label?: string; style?: Style }; // label goes in the first leaf column if it has no total
rowStyle?: (row: T, rowIndex: number) => Style | undefined;
onWarning?: (w: ExcelWarning) => void;
}
export interface AutoWidthOptions {
min?: number; // characters, default 8.43 (Excel default)
max?: number; // characters, default 60 (a readability choice made in JSE-4, not a measurement); cap 255
sampleRows?: number; // rows measured, default all (JSE-8: measuring every row of 1M cells cost no more than run-to-run noise)
}Behaviour:
-
Header groups. The header depth is the deepest
childrennesting. A group's title is merged across its leaf columns. A leaf that sits higher than the deepest level is merged down to the last header row (rowspan). Example:[{ title: 'Name', key: 'name' }, { title: 'Q1', children: [{ title: 'Jan', key: 'jan' }, { title: 'Feb', key: 'feb' }] }]givesA1:A2merged ("Name"),B1:C1merged ("Q1"), and "Jan" and "Feb" in row 2. -
Cells. An accessor may return a bare value or a full
Cell({ value, style, formula, hyperlink }). Styles merge as data layer, thencolumn.style, thenrowStyle(row), then the cell's own style.numFmtgoes into the column style. -
Path accessor safety. Paths read own properties only. The segments
__proto__,prototypeandconstructorthrowINVALID_COLUMN. -
Coercion by
type:typeAccepts Unconvertible values 'string'anything; String(v), dates as ISO 8601— 'number'numbers; strings that fully match a plain decimal or exponent number (no thousands separators, no locale) written as text, warning COERCION_FAILED'boolean'booleans; 'true'/'false'in any casewritten as text, warning 'date'Date; ISO 8601 strings; numbers taken as epoch millisecondswritten as text, warning; default numFmt14'datetime'as 'date'default numFmt22Non-finite numbers (
NaN,±Infinity) become empty cells with warningNON_FINITE_NUMBER, whatever thetype. -
Auto width measures
cellText()of the header and data cells per column. East Asian wide characters count as two, and a 2-character padding is added; the result is clamped to[min, max]. It is an estimate without font metrics. Header-group titles do not widen their leaf columns. -
Totals. If any column has
total, one row follows the data. The built-ins writeSUBTOTAL(109|101|103|105|104, range)formulas: sum, average, count (COUNTA), min, max. UnlikeSUM,SUBTOTALignores rows hidden by the autofilter. Each formula gets a cached value that the builder computes from the data, so viewers and LibreOffice show the right number without recalculating. The function form receives the column's data range ('C2:C101') and values. -
Freeze and filter refer to the actual header rows, so they work with
originand header groups. -
Shared style objects. Cells of a column share one style object, and banded rows share one merged object per column and
rowStyleobject. The writer's identity cache therefore resolves each distinct style once, however many rows there are. Only a cell's own style makes a new object. As with reader output (§12 Q8), copy a style before editing it. -
Inferred columns. Without
columns, object rows give one column per key of the first object (title = key). Array rows give one column per index and no header row. -
Header styles layer
options.headerStyle, then the column's or group'sheaderStyle, then the style of aCelltitle. A leaf's default title is itskeyorpath, else''. -
Totals details.
- Dates count as their serials.
averagewith no numbers caches#DIV/0!;min/maxwith no numbers cache 0.countisCOUNTA(every non-empty cell, including''), and its cell drops the column's number format.- A totals cell is styled with the column style, then
totals.style, then its own style. - With no data rows there is no range, so built-ins write their value without a formula.
- Any other string, such as
'n/a', is a literal cell.
-
fromDatasets. The first block starts atorigin(plusoffset.rows). Each later block is placed by itsplacement. A row of blocks is a'below'block (or the first block) and the'right'blocks that follow it.'below'(the default): the block startsgapempty rows below the lowest row used by the previous row of blocks (totals included), oroffset.rowsrows when given.offset.colsshifts it right of the origin. Without'right'blocks, this is the previous block's last row, as before.'right': the block starts on the previous block's top row,gapempty columns after the previous block's last used column (its widest row, header groups and totals included).offset.colsadds to that, andoffset.rowsmoves the block down from that top row. A first block with'right'starts at the origin.- So a
'below'block after'right'blocks starts below the lowest block of that row, and blocks never overlap. Negative offsets can still make them overlap, as before. - Freeze and filter use the first block that has header rows. A column's width is the first explicit width, or the widest auto measurement across blocks. Gap rows are holes in
rows.
/** Inverse direction, for import: a sheet back to { columns, data }. */
export function toDataset(sheet: Sheet<Cell> | Sheet, options?: ToDatasetOptions): DatasetResult;
export interface ToDatasetOptions {
headerRow?: number | false; // zero-based row index, default 0; false = keys are column letters
range?: string; // default: sheet.dimension, else the used range
values?: 'value' | 'cell'; // 'value' (default): CellValue (a formula gives its cached value); 'cell': the full Cell
skipTotals?: 'auto' | boolean; // drop a trailing totals row; default 'auto' (see below)
headerRows?: number; // header rows from headerRow on, flattened into one title; default 1
join?: string; // joins the parts of a multi-row title; default ' / '
}
export interface DatasetResult { columns: Array<{ title: string; key: string }>; data: Array<Record<string, unknown>> }toDataset builds keys from header text (trimmed), deduplicated with _2, _3 suffixes; an empty header gives the column letter. Empty cells are null, rows with no values are skipped, and with values: 'cell' a bare value is returned as { value }. It also accepts a builder-made Sheet, so toDataset(fromDataset(ds)) gives the flat data back.
Totals rows. With skipTotals: 'auto' (the default), the last data row is dropped when it contains at least one formula and every formula in it is SUBTOTAL(…). That is the totals row fromDataset writes, and a label such as "Total" may sit next to the formulas. So toDataset(read(write(fromDataset(ds)))) returns the data rows only. true always drops the last row, and false keeps every row. A sheet whose genuine last data row is all SUBTOTAL formulas needs skipTotals: false. Rows are null-prototype objects (Object.create(null)), so a header named __proto__ from an untrusted file is just a key.
Multi-row headers. With headerRows: n, the title of each column joins the text of rows headerRow to headerRow + n - 1 with join, skipping empty parts. Merged cells are expanded first, so a group title merged over three columns prefixes all three ("Q1 / Jan", "Q1 / Feb", "Q1 / Mar"), and a title merged down through the header rows appears once ("Name"). That reads back the header groups fromDataset writes. Without merges (always the case in CSV), a group title is written once, over the first of its columns (Name,Q1, over ,Jan,Feb). So an empty, unmerged cell in an upper header row takes the nearest non-empty cell to its left in the same row, when the column has text in a lower header row: that gives "Q1 / Jan", "Q1 / Feb", and toCsv of header groups reads back with the original titles. The fill never starts left of the table's first column (a leading empty cell over "Name" stays empty), never crosses a merged cell (a real merge already gives the extent), and skips columns with no text in the lower rows. Data starts after the last header row. Header detection, type inference and column mapping are in javascript-excel/import (§5.6).
export function mergeStyles(...styles: Array<Style | undefined>): Style; // the §3.5.7 merge
export function borderAll(side: BorderSide): Border; // same side on left/right/top/bottom
export function resolveColor(color: Color, ctx?: { theme?: Theme; indexedColors?: string[] }): string; // ARGB
export const BUILTIN_NUM_FMTS: Readonly<Record<number, string>>;
export function isDateFormat(fmt: NumFmt): boolean;export function dateToSerial(d: Date, opts?: { date1904?: boolean; dateZone?: 'local' | 'utc' }): number;
export function serialToDate(serial: number, opts?: { date1904?: boolean; dateZone?: 'local' | 'utc' }): Date;/** Replaces forbidden characters with '_', trims apostrophes, truncates to 31 code points (never splitting a surrogate pair), falls back to 'Sheet' (also for 'History'). */
export function sanitizeSheetName(name: string): string;
/** Returns null when valid, or the reason. */
export function validateSheetName(name: string): null | 'empty' | 'too-long' | 'forbidden-char' | 'apostrophe' | 'reserved';export function toUint8Array(wb: Workbook, options?: WriteOptions): Promise<Uint8Array>;
export function toBlob(wb: Workbook, options?: WriteOptions): Promise<BlobType>; // type: XLSX_MIME
// BlobType, BinaryInput and AbortSignalLike are shared by every entry point; see "Shared types" at the end of §5.3.
export const XLSX_MIME = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
export interface WriteOptions {
/** 'deflate' (default) or 'store' (no compression; faster, bigger). */
compression?: 'deflate' | 'store';
/** Shared strings table (default true) or inline strings (false: less memory, larger files). */
sharedStrings?: boolean;
/** Time zone used to turn Date into serials. Default 'local'. */
dateZone?: 'local' | 'utc';
/** Allowed URL schemes for external hyperlinks. Default ['http', 'https', 'mailto']. */
hyperlinkSchemes?: string[];
signal?: AbortSignalLike;
onProgress?: (p: Progress) => void;
}
export interface Progress {
phase: 'prepare' | 'styles' | 'sheets' | 'zip' | 'unzip' | 'parse';
sheet?: string;
/** Overall progress estimate 0..1, non-decreasing. */
ratio: number;
}- Invalid input throws
ValidationError(§7), and no bytes are returned. Workbook-level checks (sheet names, active sheet, document properties) run first. Cells and styles are checked as their sheet is written, which is still before the archive is complete. The writer emits no warnings: any input it cannot write faithfully is an error. - Parts written:
[Content_Types].xml,_rels/.rels,docProps/core.xml,docProps/app.xml,docProps/custom.xml(if any),xl/workbook.xml,xl/_rels/workbook.xml.rels,xl/styles.xml,xl/theme/theme1.xml,xl/sharedStrings.xml(if used),xl/worksheets/sheetN.xmlandxl/worksheets/_rels/sheetN.xml.rels(for hyperlinks). - XML is produced as chunk arrays and fed to the compressor in pieces; the whole sheet is never built as one string. The output is assembled in memory, so peak memory is roughly the model plus the compressed file.
- Deterministic output: the same model and options give identical bytes when
properties.createdandproperties.modifiedare set. Zip entry timestamps come frommodified. - Abort: rejects with
signal.reason(aDOMExceptionnamedAbortErrorby default), the same asfetch. The writer checks the signal between sheet XML chunks (about 64 K characters each). Yielding (JSE-23). AwaitingCompressionStreamwrites only runs microtasks in Chromium, so before JSE-23 a write on the main thread was one long task. For 100k and 300k rows of 7 columns in Chromium 150 that was 544 and 1,662 ms, and no frame rendered and no timer, input or abort ran until it finished. The async writers (toUint8Array,toBlob, andclient.writeinside a worker) now return to the event loop between sheet and shared-strings chunks once about 16 ms have passed. They usesetImmediatewhere it exists (Node, Bun), else aMessageChannelmessage, elsesetTimeout(0). In the same benchmark (bench/browser/write-yield.bench.test.ts) no task is over 50 ms, the longest gap between frames is 18 ms, total time is unchanged within noise (+2 % and −0.5 %), and the bytes are identical.scheduler.yield()is not used: its continuations run ahead of rendering, which left frames 133 ms apart.setTimeout(0)cost 10–20 % more because of its 4 ms clamp. The time budget is internal, not an option. In Node, JSE-8 measured the longest event-loop block of a 1M-cell write at 11–18 ms on an Apple-silicon laptop and 22–28 ms on a GitHub Actions runner (unique strings and per-cell style objects included), and of a read at 3–10 ms and 7–18 ms; the README has the full table. The shared strings table is written in chunks too. Before JSE-8 it was built as one string, which blocked for 161 ms at 1M unique strings. For heavy jobs that must not touch the UI thread at all, use/worker(§5.5). onProgressis throttled to one event per 50 ms. The first event, every change ofphaseorsheet, and the finalratio: 1are always delivered, andrationever decreases. Unthrottled, the reader emitted an event every 0.3 ms and the writer every 7 ms (2,011 and 105 events for 1M cells), which a UI cannot use and which a worker would turn into as many messages. The reader uses the same throttle.
export type BinaryInput = Uint8Array | ArrayBuffer | BlobType; // Node Buffer is a Uint8Array; BlobType: §5.3
export function read(input: BinaryInput, options?: ReadOptions): Promise<ReadResult>;
export function readSheetNames(input: BinaryInput, options?: Pick<ReadOptions, 'limits' | 'signal'>): Promise<SheetInfo[]>;
export function detectFormat(input: BinaryInput): Promise<DetectedFormat>; // never throws for unreadable input
export interface SheetInfo { name: string; index: number; state: 'visible' | 'hidden' | 'veryHidden' }
export type DetectedFormat = 'xlsx' | 'xlsm' | 'xltx' | 'xltm' | 'xlsb' | 'ods' | 'cfb' | 'zip' | 'unknown'; // 'cfb' = .xls or an encrypted OOXML file
export interface ReadResult {
workbook: Workbook<Cell>;
warnings: ExcelWarning[];
}
export interface ReadOptions {
/** Only parse these sheets (by name or index); the others are listed with empty rows. Default: all. */
sheets?: Array<string | number>;
/** Parse styles (default true). false is faster: no cell.style, but date detection still uses numFmt. */
styles?: boolean;
/** Return formula text (default true). false: cached values only. */
formulas?: boolean;
/** 'date' (default): date-formatted numbers become Date. 'serial': leave as numbers. */
dates?: 'date' | 'serial';
dateZone?: 'local' | 'utc'; // default 'local'
/** Rich text as runs (default) or flattened to a plain string. */
richText?: 'runs' | 'plain';
/** Read only rows 0..maxRows-1 of each parsed sheet; later rows are skipped (ROWS_TRUNCATED). Default: all. */
maxRows?: number;
limits?: Partial<ReadLimits>;
signal?: AbortSignalLike; // a DOM or Node AbortSignal (§5.3)
onProgress?: (p: Progress) => void;
onWarning?: (w: ExcelWarning) => void; // called as warnings occur, in addition to ReadResult.warnings
}
export interface ReadLimits {
maxInputBytes: number;
maxEntries: number;
maxEntryBytes: number; // decompressed bytes of one part
maxTotalBytes: number; // decompressed bytes of all parts read
maxRatio: number; // decompressed / compressed, per entry
maxXmlDepth: number;
maxCells: number; // all sheets together
maxSharedStrings: number;
maxWarnings: number; // then a single WARNINGS_TRUNCATED
}
export const DEFAULT_READ_LIMITS: Readonly<ReadLimits>;Defaults, measured in JSE-6 (method below):
| Limit | Default | Evidence |
|---|---|---|
maxInputBytes |
256 MiB | 2,000,000 dense random numbers are a 26 MB file, so 256 MiB is roughly 20M dense cells, beyond maxCells |
maxEntries |
10,000 | 250 sheets are 258 parts; ordinary files have 9–15 |
maxEntryBytes |
512 MiB | 2M dense cells are a 96 MB sheet part (about 48 bytes per cell), so a sheet at maxCells fits |
maxTotalBytes |
1 GiB | Twice maxEntryBytes; the largest corpus file inflates to 96 MB |
maxRatio |
1,000, per entry, checked once the entry has produced more than 1 MiB | Real files: 4–27 when cells carry r references (openpyxl); 412 for <row><c><v>1</v></c></row> repeated (JSE-2) and 686 for <row/> repeated, from writers that omit r. Raw DEFLATE peaks at about 1,028 (20 MB of zeros). So 1,000 accepts every legitimate shape and stops near-maximal bombs. The ratio is inflated bytes over the entry's whole compressed size, so no entry inflates to more than 1,000 times its stored size, whatever maxEntryBytes allows |
maxXmlDepth |
64 | Deepest part in the corpus: 7 |
maxCells |
10,000,000 | The reader's model costs 94–275 bytes of heap per cell (108 for dense numbers, 275 with unique strings), so 10M cells is about 1–2.7 GB, the most a browser tab or a default Node heap holds |
maxSharedStrings |
5,000,000 | About 260 bytes of heap per short unique string with its cell (unique-strings file); stops a part of tiny <si> items (up to 44M in 512 MiB) before it exhausts memory |
maxWarnings |
1,000 | Then a single WARNINGS_TRUNCATED |
Method: test/fixtures/read/generate_corpus.py (openpyxl 3.1.5) writes dense, repetitive-number, repetitive-string, styled-empty, many-sheet, long-text and unique-string workbooks of 0.5–2M cells; test/fixtures/read/measure_limits.mjs reports entries, sizes, ratios, XML depth and read time for each, and heap per cell was measured with --expose-gc around read(). Reading 2M dense cells took 1.8 s on an Apple-silicon laptop (Node 24); performance proper is JSE-8.
Spreadsheet format limits are always enforced and cannot be configured: 1,048,576 rows, 16,384 columns (XFD). A cell reference beyond them is skipped with warning CELL_OUT_OF_BOUNDS.
How the reader works, as far as the API is concerned:
- The whole archive is held in memory, because the zip central directory sits at the end of the file. Parts are inflated one at a time and streamed through the XML pull tokenizer, so a sheet's XML is never held whole. The shared strings table is held whole.
- Parts are found through relationships (
_rels/.rels→ workbook → sheets), never by fixed path, so files from Google Sheets, Numbers and LibreOffice, which use different part names, work. Part names are compared case-insensitively, as OPC requires. Absolute and relative relationship targets are both resolved. - Cells and rows without an
rattribute (allowed by the schema) are placed by position. A missing or wrong<dimension>is ignored;sheet.dimensionis computed from the cells. - ISO/IEC 29500 Strict files are read like transitional ones (§12 Q9): the tokenizer reports names without namespace prefixes, relationship types are matched by their last path segment (
/worksheet,/sharedStrings, …), which Strict and transitional share, andt="d"(ISO 8601 date) cells are read. The writer writes transitional only. - Formats. Detection is a table: the container signature (CFB, zip), then the content type of the workbook part, each entry naming the decoder that reads it.
.xlsx,.xltx,.xlsmand.xltmshare the SpreadsheetML decoder; for the macro-enabled two, oneUNSUPPORTED_PARTwarning says the VBA macros are not read or run. Formats without a decoder in 2.0 throwUNSUPPORTED_FORMATwithdetails.format:'cfb'(.xls, or an encrypted/password-protected.xlsx, which is a CFB container),'xlsb','ods','unknown'(no zip signature). They are a phase boundary, not a design limit: supporting.xlsbor.xlslater is a new decoder plus its table row. A zip without a workbook part isNOT_XLSX. A workbook part with a missing or unknown content type is read as SpreadsheetML (.binas.xlsb). - Unread parts are not lost at the zip level. The reader parses only the parts the model represents, but the archive stays addressable by part name until the read ends, and an internal (not yet public) option returns every unparsed part byte for byte. A later release can use it to carry drawings, comments, VBA or custom XML through a read-modify-write.
- Unsupported content (drawings, charts, comments, pivot tables, tables, OLE objects, form controls, VBA, external links, chart sheets, …) gives one
UNSUPPORTED_PARTwarning per kind. Chart, dialog and macro sheets are not worksheets: they are left out ofsheetsandreadSheetNames, and defined names local to them are dropped. - Styles: each
cellXfsentry is one frozenStyle(§12 Q8). Pattern fills come back withtype: 'pattern', sofill.typetells pattern and gradient fills apart. A style records only what differs from the defaults: font 0 (the workbook default font), fills 0 and 1 (the requirednoneandgray125placeholders) and border 0 are left out, andnumFmtId0 (General) gives nonumFmt.applyFontand the other apply flags are ignored, as Excel does for cell formats. - Values:
t="s","inlineStr"and"str"are strings (or rich text), with_xHHHH_escapes decoded;"b"booleans;"e"errors, including codes newer than the seven of ECMA-376 (#SPILL!,#CALC!, …), returned as written;"d"ISO dates; numbers otherwise, converted toDatewhen their number format is a date format (§3.4.1). A formula's cached value setsvalueandtype; without one the cell istype: 'empty'with itsformula. Shared formulas are expanded (§12 Q6); data-table formulas (t="dataTable") give their cached values only. maxRows(for previews and import limits, §5.6):-
Rows: on the first row at or beyond
maxRows, the sheet parser jumps to the end of<sheetData>with a plain text search, without tokenizing the skipped rows. The elements after it (merges, hyperlinks, views, autofilter, print setup) are still read, and oneROWS_TRUNCATEDwarning is reported per sheet. Rows are stored in ascending order (ECMA-376 §18.3.1.73[to verify]), so nothing below the limit is lost. -
Shared strings: the table is decoded after the sheets, and only up to the highest index the rows read use; the rest of the part is skipped the same way. So
maxSharedStringsonly applies to the entries decoded. A string index past the table givesINVALID_SHARED_STRING, as on the full path; the sheet'sdimensionwas already computed by then and may still include that dropped cell. -
Still read in full: the sheet and shared-string parts are still inflated to the end.
-
Without
maxRows, shared strings are parsed before the sheets, as always. -
Measured on a 100,000 × 10 sheet (
styles: false, median of 7 reads, Node 26 on an Apple M2 under light load):sheet full read maxRows: 25numbers only 517 ms 77 ms 1M unique strings 941 ms 166 ms (412 ms before the shared strings were decoded lazily)
-
- Column widths: the file stores characters plus padding (ECMA-376 §18.3.1.13); the reader converts back to the characters Excel's UI shows, the unit
ColumnWidthuses, so a width of 20 written by the writer reads back as 20. Files from tools that store the UI value directly (openpyxl writes30for 30) read as Excel shows them (29.29). - Print setup: the
_xlnm.Print_Areaand_xlnm.Print_Titlesdefined names becomesheet.print.printAreaandprintTitlesand are not repeated indefinedNames;_xlnm._FilterDatabaseis implied bysheet.autoFilterand dropped. - Yielding (JSE-24). As with the writer (§5.1), a read on the main thread used to be one long task in Chromium: for 100k and 300k rows of 7 columns in Chromium 150 that was about 535 and 1,580 ms with no frame rendered, and no timer, input or abort ran until the read finished. There were two causes. Awaiting the decompressor and the part parsers only runs microtasks. And each zip entry was written to
DecompressionStreamin one piece, which Chromium inflates in batches of up to about 50 ms. Nowread(andclient.readinside a worker) returns to the event loop between XML chunks of every streamed part (sheets, shared strings, styles, theme) once about 16 ms have passed, using the writer's mechanism (setImmediate, elseMessageChannel, elsesetTimeout(0)). It also feeds compressed data to the decompressor in 256 KB slices. Inbench/browser/read-yield.bench.test.ts, no task is over 50 ms, the longest gap between frames is 18 ms, and total time is within noise (+0.4 % to +2.3 %). The model is deep-equal to before on the conformance corpus and the read fixtures under five option sets, and on a 300k-row file. A read inside a worker takes the same time as before. The budget is internal, not an option.readCsvalready yields between 1M-character chunks and is unchanged (17 ms frame gaps at 300k rows).
export function parseCsv(text: string, options?: CsvParseOptions): CsvParseResult;
export function readCsv(input: string | BinaryInput, options?: CsvReadOptions): Promise<CsvParseResult>;
export function toCsv(source: Sheet | CellInput[][], options?: CsvWriteOptions): string;
export function toCsvBlob(source: Sheet | CellInput[][], options?: CsvWriteOptions): BlobType; // type: CSV_MIME
export const CSV_MIME = 'text/csv;charset=utf-8';
export interface CsvParseOptions {
/** A single character, or 'auto' (default): picks from , ; TAB | by field-count consistency over the first records. */
delimiter?: string | 'auto';
quote?: string; // default '"'; a quote inside a quoted field is doubled (RFC 4180)
/**
* Default false: every field is a string. true: unquoted fields that are numbers, TRUE/FALSE
* (or true/false) or ISO 8601 dates become numbers, booleans and Dates. No locale guessing.
* Quoted fields always stay strings.
*/
inferTypes?: boolean;
dateZone?: 'local' | 'utc'; // ISO dates without an offset (inferTypes); default 'local' (§12 Q2)
skipEmptyLines?: boolean; // default false: a blank line gives an empty row []
/** 'lenient' (default): malformed input gives warnings. 'strict': throws CsvError. */
mode?: 'lenient' | 'strict';
maxRows?: number; // default unlimited; stops reading with warning CSV_ROWS_TRUNCATED
maxFieldBytes?: number; // default 1,048,576 (1 MiB of UTF-8); a bigger field throws LimitError
}
export interface CsvReadOptions extends CsvParseOptions {
encoding?: string; // used without a BOM; any TextDecoder label; default 'utf-8'
signal?: AbortSignalLike; // a DOM or Node AbortSignal
}
export interface CsvParseResult {
rows: CellValue[][]; // string[][] unless inferTypes
delimiter: string; // the one used (detected or given)
newline: '\r\n' | '\n' | '\r'; // the first one seen; '\r\n' when the input has none
bom: boolean; // input started with a BOM (removed from the data)
warnings: ExcelWarning[]; // CSV_UNTERMINATED_QUOTE, CSV_STRAY_QUOTE, CSV_FIELD_COUNT, CSV_INVALID_ENCODING, CSV_ROWS_TRUNCATED
}
export interface CsvWriteOptions {
delimiter?: string; // default ','
newline?: '\r\n' | '\n'; // default '\r\n' (RFC 4180), also after the last record
quote?: 'auto' | 'all'; // 'auto' (default): quote fields containing delimiter, quote, CR or LF
/** Prepend a UTF-8 BOM so Excel detects UTF-8. toCsvBlob default true, toCsv default false. */
bom?: boolean;
/** Formula-injection guard, default true. See below. */
escapeFormulas?: boolean;
/** Dates: 'iso' (default; YYYY-MM-DD, or YYYY-MM-DDTHH:mm:ss, plus .sss when there are milliseconds) or a function. */
dates?: 'iso' | ((d: Date) => string);
dateZone?: 'local' | 'utc';
/** Formula cells: write the cached value (default) or the formula text ('formula', which still passes the guard). */
formulas?: 'value' | 'formula';
}Shared types. BinaryInput, BlobType, BlobLike, AbortSignalLike and ExcelWarning are one set of declarations (src/binary.ts, src/signal.ts, src/warnings.ts), exported from the core entry and from /csv, and later from /read. BinaryInput is Uint8Array | ArrayBuffer | BlobType. The package compiles without DOM types, so BlobType resolves to the platform Blob when the consumer's TypeScript setup declares one (lib dom or @types/node) and to a structural BlobLike (size, type, arrayBuffer()) otherwise. AbortSignalLike is the structural { aborted, reason } part of AbortSignal.
- Parsing: one pass, hand-written scanner, no recursion, linear time. RFC 4180 fields and quoting; CRLF, LF and CR are all record separators, and quoted fields may contain any of them. A trailing newline does not add a record. A blank line is an empty row (
[]), which is never aCSV_FIELD_COUNTmismatch. - Malformed input (lenient): an unclosed quote runs to the end of the input (
CSV_UNTERMINATED_QUOTE); a quote inside an unquoted field is kept, and text after a closing quote is appended to the field, as Python'scsvmodule does (CSV_STRAY_QUOTE); a record whose field count differs from the first record's is kept (CSV_FIELD_COUNT). Warnings carryref, the A1 cell of the record and field, and a message with the line number. At most 1,000 warnings are kept, then oneWARNINGS_TRUNCATED.mode: 'strict'throwsCsvErrorCSV_MALFORMEDinstead, withdetails: { warning, ref, line }.CSV_ROWS_TRUNCATEDis not malformed input and is reported in both modes. - Delimiter detection: over the first 20 records (at most 64 KiB), quote-aware. The candidate whose most common field count (above 1) covers the most records wins; ties go to the earlier of
, ; TAB |. A single-column file gives,. - Type inference (
inferTypes): numbers in plain decimal or exponent form (-1.5,.5,1e3), but not007,1.,0x10,Infinityor integers beyond 2^53, which stay text;TRUE/FALSE/true/false; ISO 8601YYYY-MM-DDandYYYY-MM-DDTHH:mm[:ss[.sss]](Tor space) with optionalZor±HH:mm, validated (no 2023-02-29). Quoted and empty fields stay strings. - Decoding (
readCsv): a UTF-8, UTF-16LE or UTF-16BE BOM wins. Otherwiseencodingapplies (any labelTextDecoderaccepts; an unknown label is aTypeError), default'utf-8'. Invalid bytes become U+FFFD with warningCSV_INVALID_ENCODING(strict mode:CSV_MALFORMED). - Async:
readCsvparses in chunks of about 1M characters, yields to the event loop between them and checkssignal; an abort rejects withsignal.reason, asfetchdoes.parseCsvis synchronous. - Options that are not valid (a delimiter that is not one character, or is CR, LF or the quote; an unknown enum value) throw
TypeError. - Serialising values: numbers as
String(n)(shortest round-trip, never locale-formatted;NaN/±InfinitythrowINVALID_NUMBER), booleans asTRUE/FALSE, errors as their code, rich text as plain text, empty cells as empty fields, invalidDates throwINVALID_DATE. ASheetis serialised fromA1to its last used cell as a rectangle (a cell is used when it has a value or a formula; style alone does not count); merges, styles and hyperlinks are dropped. ACellInput[][]is written as given, so ragged rows stay ragged. - Formula-injection guard (on by default). A string field that starts with
=,+,-,@, TAB (\t) or CR (\r) is written with a leading', so a spreadsheet app opening the CSV treats it as text. This covers plain strings, rich text, string cached values of formula cells, and formula text withformulas: 'formula'. Numbers, booleans and dates from the model are not strings and are never prefixed, so-5stays-5; the output of a customdatesfunction is not prefixed either.escapeFormulas: falseturns the guard off. The guard is one-way: reading the file back gives the prefixed text. It applies totoCsvandtoCsvBlobonly; the xlsx writer does not need it, because xlsx cells have explicit types (§3.4).
export function fromTable(table: TableElement, options?: FromTableOptions): Sheet;
export function download(data: Uint8Array | BlobType | string, filename: string, options?: DownloadOptions): void;
export const DOWNLOAD_REVOKE_DELAY_MS: number; // 40 000
/** HTMLTableElement / HTMLTableCellElement when the consumer has DOM types, else `object`. */
export type TableElement = typeof globalThis extends { HTMLTableElement: { prototype: infer T } } ? T : object;
export type TableCellElement = typeof globalThis extends { HTMLTableCellElement: { prototype: infer T } } ? T : object;
export interface FromTableOptions {
name?: string; // sheet name, default 'Sheet1'; an invalid name throws (§12 Q19)
/** Which rows are header rows: 'thead' (default) or a fixed row count, or false. Header rows get headerStyle. */
header?: 'thead' | number | false;
headerStyle?: Style; // default { font: { bold: true } }
includeFooter?: boolean; // <tfoot>, default true
/** Skip rows and cells with the `hidden` attribute or inline display:none. With styles: 'computed', also the computed style. Default true. */
skipHidden?: boolean;
/** Rows/cells matching this selector are skipped. Default '[data-export-ignore]'. */
ignore?: string;
/** 'none' (default) or 'computed': map getComputedStyle to Style (see below). */
styles?: 'none' | 'computed';
/** Infer numbers/booleans from text (default false: text stays text unless a data-type hint says otherwise). */
inferTypes?: boolean;
/** The first <a href> in a cell becomes Cell.hyperlink (default true). */
links?: boolean;
/** Link schemes kept (default ['http', 'https', 'mailto']); others are dropped with HYPERLINK_DROPPED. */
hyperlinkSchemes?: string[];
freezeHeader?: boolean;
autoFilter?: boolean;
autoWidth?: boolean | AutoWidthOptions;
/** Per-cell hook: return a CellInput to override, or undefined to keep the default mapping. */
cell?: (el: TableCellElement, ctx: { row: number; col: number; header: boolean }) => CellInput | undefined;
/** Data problems that do not stop the conversion: COERCION_FAILED, HYPERLINK_DROPPED (§7.3). */
onWarning?: (w: ExcelWarning) => void;
}
export interface DownloadOptions {
/** Default: a Blob keeps its type; otherwise from the extension (.xlsx, .csv), else text/plain;charset=utf-8 for strings and application/octet-stream for bytes. */
mimeType?: string;
}-
No globals at import. The module is safe to import during SSR.
fromTablereads styles through the table's own window (ownerDocument.defaultView), so tables in iframes work. Calling either function without a DOM throwsENVIRONMENT_UNSUPPORTED. A non-<table>element throwsTypeError. -
Structure. Rows come from
<thead>, then each<tbody>(and bare<tr>), then<tfoot>, whatever their order in the markup.colspan/rowspanare laid out on an occupancy grid and becomemerges(issue #28).rowspan="0"spans to the end of its row group. Spans are clamped to HTML's limits (1000 / 65534) and to the table. Nested tables are read as text of their cell, not as rows. Skipped cells (hidden, ignored) are left out, so the cells after them move left. -
Hints on
<td>/<th>:data-value="..."gives the raw value instead of the text.data-type="string|number|boolean|date"coerces it.numbertakes plain decimals and1,234.5-style grouping.booleantakes true/false, yes/no and 1/0.datetakes ISO 8601: date-only and zone-less values are local wall-clock time, andZor±hh:mmare honoured. A value that doesn't fit stays text with warningCOERCION_FAILED.data-numfmt="0.00"sets the number format; all digits means a built-in id (data-numfmt="14").data-export-ignoreon a row or cell skips it.
-
Text: child text, ignoring
<script>,<style>,<template>and<noscript>. Whitespace, including , is collapsed per line.<br>becomes a newline and turns onwrapText. -
Links: the first
<a href>becomes the cell's hyperlink, resolved to an absolute URL (a.href). In-page#anchorsare ignored. Schemes outsidehyperlinkSchemesare dropped withHYPERLINK_DROPPED, so the sheet always passes the writer's allowlist (§3.6). -
Header rows get
headerStyle. Computed styles are merged over it, field by field.freezeHeaderfreezes the header rows, andautoFiltercovers the last header row through the last row; both need at least one header row.autoWidthsets numeric widths fromcellText(§4.3 bounds). -
styles: 'computed'maps:font-weight≥ 600 (orbold/bolder) to bold;font-styleitalic/oblique;text-decorationunderline and line-through;color, except black, which is Excel's automatic colour;- the first non-transparent
background-colorof the cell, its row, its section or the table (what the reader sees), as a solid fill; - explicit
text-alignleft/right/center/justify (including the vendorcenterthat<th>computes to); vertical-aligntop/bottom;white-spacepre-wrap/pre-line/break-spacestowrapText.
These are not mapped:
text-align: start/end, the computed default (Excel's general alignment follows the sheet direction);vertical-align: middle, the HTML table default; and borders, fonts and sizes, in 2.0. Colours are parsed from hex, the basic named colours,rgb()/rgba()(comma or space syntax),hsl(),hwb()and the CSS Color 4 forms browsers report for modern CSS (Tailwind v4, for example):lab(),lch(),oklab(),oklch()andcolor()insrgb,srgb-linear,display-p3,a98-rgb,prophoto-rgb,rec2020,xyz,xyz-d50andxyz-d65. They are converted to sRGB (CIE Lab/LCH from D50 with Bradford adaptation); colours outside sRGB are clipped per channel, andnonecomponents count as 0. As withrgba(), a colour with alpha 0 is transparent and any other alpha is dropped (Excel fills are opaque). -
RTL:
dir="rtl"on the table or an ancestor, or computeddirection: rtlwithstyles: 'computed', setsview.rightToLeft. -
downloadcreates an object URL, clicks a temporary hidden<a download rel="noopener">and removes it. It revokes the URL afterDOWNLOAD_REVOKE_DELAY_MS(40 s, the delay FileSaver.js uses, because Safari needs the URL after the click; not measured here), and also when the click throws. A stringdatais encoded as UTF-8. A Blob is passed through, re-typed only whenmimeTypediffers.
// excel.worker.ts (two lines the app writes)
import { exposeWorker } from 'javascript-excel/worker';
exposeWorker(); // serves on `self`; pass an endpoint to serve elsewhere
// main thread
export function createWorkerClient(worker: WorkerLike): WorkerClient; // a DOM `Worker` fits WorkerLike
export interface WorkerClient {
write(wb: Workbook, options?: WriteOptions & TransferOption): Promise<Uint8Array>;
read(input: BinaryInput, options?: ReadOptions & TransferOption): Promise<ReadResult>;
toCsv(source: Sheet | CellInput[][], options?: CsvWriteOptions): Promise<string>;
parseCsv(input: string | BinaryInput, options?: CsvParseOptions & { encoding?: string; signal?: AbortSignalLike } & TransferOption): Promise<CsvParseResult>;
importDataset(input: string | BinaryInput, options?: ImportDatasetOptions & TransferOption): Promise<ImportDatasetResult>; // §5.6
terminate(): void;
}
export interface TransferOption { transfer?: boolean }
export interface MessageEndpoint { // a Worker, the worker's self, or a MessagePort
postMessage(message: unknown, transfer?: unknown[]): void;
addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void;
}
export interface WorkerLike extends MessageEndpoint { terminate(): void }- The app owns the worker file and creates it with
new Worker(new URL('./excel.worker.ts', import.meta.url), { type: 'module' }). This is the pattern Vite, webpack 5 and Next.js all bundle correctly, and avoids shipping a prebuilt worker URL (§12 Q15). onProgress,onWarningandsignalwork across the boundary. Aborting rejects the call at once withsignal.reason(asfetchdoes) and sends a cancel message; the worker stops at its next check, and its queue moves on.terminate()rejects the calls in flight with anAbortError.- Errors keep their class and
code: anExcelErrorthrown in the worker is rebuilt on the main thread, soisExcelError(err)anderr.codework.TypeErrorandRangeErrorstay what they are. - Transfer: results (
Uint8Array) are transferred back, not copied. Inputs are copied by default. Withtransfer: true, an inputArrayBufferorUint8Arrayis transferred and becomes detached in the caller.Blobs are always cheap to send. - The model crosses the boundary through structured clone, which is why it is plain data (§3.1). Functions cannot cross: an option holding a function (other than
onProgress/onWarning), for exampletoCsv'sdatesformatter, is rejected with aTypeErrorbefore anything is sent.fromDatasetandfromTablerun on the main thread and the resultingSheetis sent to the worker. - Sending cost (JSE-15).
postMessageserializes the model on the calling thread, and the worker deserializes it on its own thread. For 600k cells in Chromium 150 (Apple-silicon laptop,bench/browser/worker-send.bench.test.ts), the calling thread is busy for 6 ms with numbers only, 13 ms with unique strings, 64–78 ms with{ value, style }cells sharing style objects, and 193–254 ms with a new style literal per cell. Node worker threads measure the same (bench/worker.mjs). A compact transfer encoding was tried: typed arrays transferred, plus a string list and a deduplicated style table. It cut the end-to-end time for styled sheets (1,340 → 749 ms), but it raised the calling thread's cost where it matters most: 193 → 320 ms for a new style per cell, and 54 → 105 ms for a mix of numbers, strings and styled cells. Encoding in JavaScript is slower than the browser's native serializer. It only won with shared style objects (64 → 20 ms). Since the point of the worker is a free main thread, it was not shipped. The code and measurements are on thejse-15-compact-experimentbranch. To keep the send cheap, share style objects between cells (const bold = { font: { bold: true } }) rather than writing a new literal per cell. - Several calls may be in flight on one client; they run one after another in the worker. The library's messages carry a tag, so the app can use the same worker for its own messages.
- Code that imports only
createWorkerClientdoes not ship the engine: the smoke test bundles it alone and finds no writer, reader, CSV or import code (5.3 KiB unminified). - Node
worker_threadsis not supported by/workerin 2.0 out of the box (itsWorkeris anEventEmitter, not anEventTarget). A three-line adapter works, and the tests use one. Node users usually callread/toUint8Arraydirectly.
Turns a user's .xlsx or .csv file into a dataset, { columns, data }, the shape fromDataset writes. This is the framework-free part of react-data-import (its docs/api.md, decided 2026-11-16), so a Vue or vanilla app gets the same import. Everything here is built on read, readCsv and toDataset.
export function importDataset(input: string | BinaryInput, options?: ImportDatasetOptions): Promise<ImportDatasetResult>;
// building blocks, usable on their own
export function detectHeader(sheet: Sheet<CellInput>, options?: DetectHeaderOptions): HeaderDetection;
export function inferColumnTypes(dataset: DatasetLike, options?: TypeOptions): InferredColumn[];
export function coerceColumns(dataset: DatasetLike, types: Record<string, ColumnType | InferredColumn>, options?: TypeOptions): CoerceResult;
export function parseNumber(text: string, options?: { decimal?: '.' | ','; group?: NumberGroup }): number | undefined;
export function parseDate(text: string, options?: { order?: 'YMD' | 'DMY' | 'MDY'; zone?: 'local' | 'utc' }): Date | undefined;
export function mapColumns(columns: ReadonlyArray<{ key: string; title: string }>, schema: ImportSchema, mapping?: ColumnMapping): MappingResult;
export function applyMapping(dataset: DatasetLike, mapping: ColumnMapping, schema: ImportSchema): MappedDataset;
export interface ImportDatasetOptions {
format?: 'auto' | 'xlsx' | 'csv'; // default 'auto' (below)
fileName?: string; // for bytes without a name: CSV detection and meta.fileName
mimeType?: string;
sheet?: number | string | 'first-visible'; // default 'first-visible'
header?: 'auto' | number | { row?: number; rows: number; join?: string } | false; // default 'auto'
range?: string; // e.g. 'B3:H200'; default: the used range
types?: 'infer' | 'none' | Record<string, ColumnType>; // by key or title; default 'infer'
locale?: ImportLocale;
delimiter?: string | 'auto'; // CSV; default 'auto'
encoding?: string; // CSV without a BOM; default 'utf-8'
skipTotals?: 'auto' | boolean; // default 'auto' (toDataset)
errorCells?: 'null' | 'keep'; // default 'null'
dates?: 'date' | 'serial'; // xlsx; default 'date'
dateZone?: 'local' | 'utc'; // default 'local'
schema?: ImportSchema;
mapping?: ColumnMapping; // overrides the automatic mapping, field by field
maxRows?: number; // data rows; more is LIMIT_EXCEEDED
preview?: number; // read only the first N data rows; no mapping
limits?: Partial<ReadLimits>;
signal?: AbortSignalLike;
onProgress?: (p: ImportProgress) => void;
onWarning?: (w: ExcelWarning) => void;
}
export interface ImportDatasetResult {
columns: ImportedColumn[]; // with a schema: one per schema field, in schema order (unmapped: letter '', type 'empty')
data: Array<Record<string, unknown>>; // null-prototype objects
rowNumbers: number[]; // spreadsheet row (1-based) of each data entry
issues: ImportIssue[];
warnings: ExcelWarning[]; // from the reader or CSV parser
meta: ImportMeta;
}
export type ColumnType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'mixed' | 'empty';
export interface ImportedColumn { key: string; title: string; letter: string; type: ColumnType; field?: string }
export interface ImportMeta {
format: 'xlsx' | 'xlsm' | 'xltx' | 'xltm' | 'csv';
fileName?: string;
sheet?: { name: string; index: number };
sheets?: SheetInfo[]; // every worksheet, for a sheet picker (xlsx)
header: { rows: number[]; detected: boolean; confidence?: 'high' | 'low' }; // zero-based sheet rows
range: string; // what became the dataset, e.g. 'A3:H120'
delimiter?: string; // CSV
encoding?: string; // CSV: from the BOM, else the encoding option
bom?: boolean; // CSV
totalsRowSkipped: boolean;
truncated: boolean; // preview: more rows exist
mapping?: ColumnMapping; // the mapping applied
unmappedColumns?: string[]; // file column keys no field took
}
export interface ImportIssue {
row: number; // spreadsheet row (1-based); 0 for column- or file-level issues
field?: string; // the key in data rows: field name, or column key without a schema
column?: string; // source column key, for cell- and column-level issues
ref?: string; // 'C17'
code: ImportIssueCode;
message: string;
severity: 'error' | 'warning';
}
export type ImportIssueCode = 'TYPE' | 'REQUIRED' | 'MAPPING_MISSING' | 'ERROR_CELL' | 'EMPTY' | 'DATE_ORDER_AMBIGUOUS';
export interface ImportLocale {
decimal?: '.' | ','; // default '.'
group?: NumberGroup; // default '': no group separators
dateOrder?: 'auto' | 'YMD' | 'DMY' | 'MDY'; // numeric dates such as 15/01/2024; default 'auto'
}
export type NumberGroup = ',' | '.' | ' ' | "'" | '';
export interface ImportSchema {
fields: Record<string, FieldSpec>;
unmapped?: 'drop' | 'keep'; // default 'drop'
}
export interface FieldSpec { aliases?: string[]; required?: boolean; type?: ColumnType }
export type ColumnMapping = Record<string, string | null>; // field -> column key, or null
export interface ImportProgress { phase: 'unzip' | 'parse' | 'dataset'; ratio: number }
export interface DatasetLike {
columns: ReadonlyArray<{ key: string; title: string; letter?: string }>;
data: ReadonlyArray<Record<string, unknown>>;
rowNumbers?: readonly number[]; // for issue rows; default: index + 2
}
export interface TypeOptions { locale?: ImportLocale; dateZone?: 'local' | 'utc' }
export interface InferredColumn { key: string; type: ColumnType; dateOrder?: 'YMD' | 'DMY' | 'MDY' }
export interface CoerceResult { data: Array<Record<string, unknown>>; issues: ImportIssue[] }
export interface DetectHeaderOptions { range?: string; maxScan?: number; locale?: ImportLocale }
export interface HeaderDetection { rows: number[]; confidence: 'high' | 'low' }
export interface MappingResult { mapping: ColumnMapping; missing: string[]; unmapped: string[] }
export interface MappedDataset { columns: ImportedColumn[]; data: Array<Record<string, unknown>>; rowNumbers: number[]; issues: ImportIssue[] }The pipeline. importDataset runs these steps, each one a function above or an existing API:
- Format. A string is CSV text. Bytes are checked with
detectFormat. A zip goes toread, andreadrejects what it can't read (NOT_XLSX,UNSUPPORTED_FORMATfor.xls/encrypted ('cfb'),.xlsb,.ods). Bytes with no signature are CSV only when the file name (.csv,.tsv,.txt), the MIME type (text/csv,text/plain,text/tab-separated-values) orformat: 'csv'says so. Otherwise they are rejected withUNSUPPORTED_FORMAT,details.format: 'unknown'. AFile's ownnameandtypeare used whenfileNameandmimeTypeare not given. - Read.
- xlsx:
readSheetNameslists the sheets, thenreadparses only the chosen one. It usesstyles: falseandrichText: 'plain', and keeps formulas only so thatskipTotals: 'auto'can see the totals row. - CSV:
readCsvwithinferTypes: false, so step 5 applies the same rules to both formats. - With
maxRowsorpreview, the reader stops early:ReadOptions.maxRows(§5.2) for xlsx,maxRowsforreadCsv.
- xlsx:
- Sheet.
'first-visible'takes the first sheet whose state isvisible. Hidden sheets are only read when named or indexed. A name or index that doesn't exist throwsSHEET_NOT_FOUND. - Header.
'auto'runsdetectHeader. A number is the header row.{ row, rows, join }is a multi-row header, flattened bytoDataset'sheaderRows(§4.3), withrowdefaulting to the detected row.falsemeans no header (keys are column letters). ThentoDatasetbuilds the rows. - Types (below):
inferColumnTypes+coerceColumns. Explicittypesand schema fieldtypes force a conversion. - Mapping, with a schema:
mapColumns, thenapplyMapping. It is skipped in preview.
Behaviour.
- Empty input resolves with no columns and one
EMPTYissue (severitywarning), not an error. - Error cells (
#N/A,#REF!, …) becomenullwith anERROR_CELLwarning per cell (errorCells: 'null'), or stay{ error }('keep'). Formulas are never evaluated: a formula cell gives its cached value. maxRowscounts data rows. A bigger sheet or file is rejected withLIMIT_EXCEEDED(details.limit: 'maxRows'), found while reading, so the rest of the file isn't parsed. The reader stops after the header area (the 25 rowsdetectHeaderscans withheader: 'auto', or the given header rows) plusmaxRowsrows. A sheet that runs past that point is rejected even if some of its rows turn out empty.preview: nreads the header area plusndata rows, returns at mostnrows, setsmeta.truncatedwhen more exist, and doesn't map.- Progress comes from the reader (
unzip,parse), thendatasetwhile rows are converted. CSV reportsdatasetonly, becausereadCsvhas no progress events. - Abort works as everywhere:
signalreachesread/readCsvand is checked between steps. An abort rejects withsignal.reason. - Worker.
WorkerClient.importDataset(input, options)runs the same function in the worker (§5.5). The options hold no functions apart fromonProgress/onWarning, so they all cross.
detectHeader(sheet, { range, maxScan = 25, locale }) returns { rows, confidence }. rows holds zero-based sheet rows, one entry for a single header row and several for a multi-row one. It is deterministic and has no weights to tune:
- It scans the first
maxScanrows of the range (default 25, a choice, not a measurement; react-data-import's fixtures (RDI-6) check it). - Each cell counts as text, other (numbers, booleans, dates, errors) or empty. Text that parses as a number,
TRUE/FALSEor a date underlocalecounts as other, so an all-text CSV row of numbers isn't taken for a header. - The table width is the most common count of filled cells among the scanned rows that have more than one. A cell counts as filled when it has a value or is covered by a horizontal merge.
- Title rows are skipped: rows with at most one filled cell when the table is wider than one column, and rows whose one merge spans the table's full width.
- The header row is the first remaining row whose cells are all text and which fills at least the table width, provided some column has an "other" value in one of the next five non-empty rows. That gives
confidence: 'high'. When no single row qualifies, two adjacent all-text rows that fill the width together, whose lower row passes the stacking test below, are a two-row header, withconfidence: 'high'. This is a group row over its columns in CSV, such asName,Q1,over,Jan,Feb. Otherwise (an all-text table), it's the first row that is all text and fills the width, withconfidence: 'low'. If there is none, the first row of the range is used, also'low'. - Multi-row headers: rows directly above the header row join it while they are all text and either start a merge that reaches down into the next row (a vertically merged "Name") or hold a horizontal merge narrower than the table (a group title such as "Q1"). That is the header react-data-export's header groups write.
- Stacked header rows without merges (CSV): the row directly below a single high-confidence header row joins it when it is all text and every text cell in it sits on a column whose next five non-empty values below are all "other". A data row can't look like that, because it would make each of those columns mixed. So
Region,Sales,Salesover,Q1,Q2over numbers is a two-row header (flattened toSales / Q1), and so is a units row (Tempover°C). If that row is all text but only some of its text cells sit on such columns (Ada,n/aunderName,Amount), it stays data, and the confidence drops to'low'so a UI asks the user.
inferColumnTypes(dataset, { locale, dateZone }) returns one InferredColumn per column, { key, type, dateOrder? }. All-or-nothing: a column gets a type only if every non-empty value is of that type or is text that converts to it.
- Typed values come first. Numbers, booleans and
Dates from the reader keep their type. Dates are'datetime'if any has a time part indateZone, else'date'. - Text conversion, tried in order on all text values:
parseNumberwith the localeTRUE/FALSE(any case)parseDate: ISO 8601 always, and numeric dates in the column's date order
- Result: if every value converts, the column takes that type. Otherwise it is
'string'when all values are text,'mixed'when typed values of different kinds meet, and'empty'when it has no values. Text is trimmed for the test, and strings that stay strings are never trimmed. - Date order with
dateOrder: 'auto'is decided per column, from the data only:- A 4-digit first part means YMD.
- A first part above 12 means DMY; a second part above 12 means MDY.
- With no evidence, or evidence both ways, the column stays text with one
DATE_ORDER_AMBIGUOUSissue (row 0, severitywarning) naming the column. The browser's locale is never consulted.
coerceColumns(dataset, types, options) converts the values and returns { data, issues }. With an inferred type every value converts by construction. With a forced type (types, or a schema field's type), a value that doesn't convert becomes null with a TYPE issue (severity error), whose field and column are the column key. 'string' writes String(v), with dates as ISO 8601. 'mixed' and 'empty' leave values alone.
parseNumber(text, { decimal, group })
- Accepts an optional sign, digits with the group separator in groups of three after the first group, an optional decimal part, and an exponent (
1e3, only whendecimalis'.'). Surrounding whitespace is trimmed. - With
group: ' ', the no-break spaces U+00A0 and U+202F (French style) also count as group separators. - Plain digits without separators are always accepted.
- Rejected, giving
undefined:- leading zeros (
007, but0.5is fine) - integers beyond 2^53
- percent signs, currency symbols, parentheses for negatives
- a decimal separator equal to
group, and misplaced groups (1,23,456withgroup: ',')
- leading zeros (
- The defaults (
decimal: '.',group: '') accept exactly whatreadCsv'sinferTypesaccepts (§5.3).
parseDate(text, { order, zone })
- ISO 8601 as in §5.3.
- With
order, numeric datesd/m/yyyy,d.m.yyyyandd-m-yyyy(one separator throughout), optionally followed byHH:mm[:ss]. - Two-digit years are not accepted: the century would be a guess.
- Calendar-checked (no 31/04), in
zone(default'local').
mapColumns(columns, schema, mapping?) matches file columns to schema fields and returns { mapping, missing, unmapped }:
- Titles, keys, field names and aliases are compared after normalisation: Unicode NFKD, combining marks removed, lower case, and whitespace,
_,-and.removed. SoE-mail,emailandE MAILmatch. - Fields are matched in schema order. Each takes the first matching column in file order, and a column goes to one field at most. There is no fuzzy matching.
mappingentries override the automatic result, field by field. An entry naming a column that doesn't exist is aTypeError.missinglists required fields without a column.
applyMapping(dataset, mapping, schema) returns { columns, data, rowNumbers, issues }:
- Rows are keyed by field names, in schema order, and every row has every schema field: a field without a column is
nullin each row (JSE-21), so rows always have the schema's shape and a validator such as Zod's.nullable()accepts them.columnshas one entry per schema field; an unmapped field's entry hastitle: '',letter: '',type: 'empty'and itsfield. - With
unmapped: 'keep', the file's other columns follow under their own keys, suffixed_2,_3if a key equals a field name. - A required field without a column gives one
MAPPING_MISSINGissue (row 0, severityerror) and isnullin the rows; there is no per-rowREQUIREDissue for it. The rows are still returned, so a UI can fix the mapping and apply it again without reading the file. - A required field that is empty in a row gives a
REQUIREDissue (severityerror) with the row, cell and sourcecolumn.applyMappingsees only the values it is given, so a value thatcoerceColumnsturned intonullalso counts as empty here;importDatasetreports such a cell once, asTYPE(see "Issues" below).
importDataset reports problems in issues, never by throwing:
fieldis the key the value has indatarows: the schema field with a schema (a kept column's key,_2suffix included, withunmapped: 'keep'), the column key without one.columnis the source column's key, as inColumnMappingandmeta.unmappedColumns. It is set on cell- and column-level issues (TYPE,REQUIRED,ERROR_CELL,DATE_ORDER_AMBIGUOUS), not onMAPPING_MISSINGorEMPTY. The cell itself isref.- One error per cell. A value that doesn't convert to a forced type gives
TYPEonly, even in a required field: the cell wasn't empty. An error cell in a required field gives itsERROR_CELLwarning and theREQUIREDerror. - Issues on columns the mapping drops (
unmapped: 'drop', the default) are left out: they describe values that are not in the result.
Validation of rows (functions, Standard Schema, async checks) is react-data-import's. javascript-excel reserves its error code, VALIDATION_FAILED.
Renders a value with an Excel number format, as Excel shows it in a cell: 1234.5 with #,##0.00 is 1,234.50, serial 45306 with dddd, mmmm d, yyyy is Monday, January 15, 2024. It is used by viewers, previews and anything that needs a cell's displayed text. Part of 2.0, from 2.0.0-alpha.3 (§12 Q14).
export function formatValue(value: FormatInput, numFmt?: NumFmt, options?: FormatOptions): FormattedValue;
export function formatCell(cell: CellInput, options?: FormatOptions): FormattedValue; // value + cell.style.numFmt
export type FormatInput = number | string | boolean | Date | CellErrorValue | RichText | null | undefined;
export interface FormatOptions {
locale?: string; // BCP 47; default 'en-US'
date1904?: boolean; // workbook.date1904
dateZone?: 'local' | 'utc'; // only for Date inputs; default 'local', as the writer
generalWidth?: number; // characters for General; default 11
indexedColors?: readonly string[]; // workbook.indexedColors, for [ColorN]
}
export interface FormattedValue {
text: string; // without the repeat characters of a *x fill
color?: string; // ARGB from [Red], [Color10], ...; overrides the font colour
fill?: { char: string; at: number }; // *x: repeat char at index `at` until the cell is full
align: 'left' | 'center' | 'right'; // Excel's 'general' alignment for the value type
}Inputs.
- Numbers are serials for date formats. Formatting is pure arithmetic on the serial, never a
Datein the local zone, so the output is the same in every time zone. For exact results, a viewer reads withdates: 'serial'(§5.2). ADateinput is first converted withdateToSerial, usingdateZoneanddate1904, which is what the writer stores for it. - Text uses the format's text section: the fourth section, or a section with
@. Without one, text is shown as is. - Booleans show
TRUE/FALSE, errors as written, rich text as its plain text, whatever the format. formatCellformats a cell's value with its ownnumFmt. A formula cell shows its cached value; without one the text is empty.
Never throws. Format codes come from files. Characters the parser does not recognise are shown as literal text, unbalanced quotes and brackets end at the end of the section, and at most four sections are used. Parsing is linear in the code's length. Compiled codes are cached (up to 1,000).
| Feature | Codes | Notes |
|---|---|---|
| Sections | pos;neg;zero;text |
One section: all numbers, with a minus sign for negatives. Two: non-negative; negative without its sign. Three: positive; negative; zero. The fourth is for text |
| Conditions | [>100], [<=-5], [=0], [<>1] |
The first section whose condition holds wins, and the next section without a condition takes the rest. A section whose condition only admits negatives ([<0]) drops the minus sign, like the implicit negative section; other conditional sections keep it [to verify] |
| Colours | [Black] [Blue] [Cyan] [Green] [Magenta] [Red] [White] [Yellow], [Color1]–[Color56] |
Returned as color (ARGB). [ColorN] is indexed colour N + 7, from indexedColors or the default palette (§3.5.6) |
| Digit placeholders | 0 # ? |
0 pads with zeros, ? with spaces, # with nothing; extra integer digits go to the leftmost placeholder; literals between placeholders stay in place (000-00-0000) |
| Decimal point, grouping, scaling | . , |
A comma between integer placeholders groups thousands; commas after the last placeholder divide by 1,000 each (0.0,, shows millions) |
| Percent | % |
Multiplies by 100 per % |
| Scientific | E+ E- e+ e- |
0.00E+00; with # in a multi-digit integer part, the exponent is a multiple of its length (##0.0E+0, engineering) |
| Fractions | # ?/?, # ??/??, ?/8, # ??/16 |
Best approximation with at most as many denominator digits as placeholders, or a fixed denominator; a whole number blanks the fraction |
| Text | @, "…", \x, and characters Excel shows unquoted |
|
| Spacing and fill | _x, *x |
_x gives one space; *x is returned as fill, not repeated in text |
| General | General, also inside a section ("Total: "General) |
Up to generalWidth (11) characters: rounded to fit, scientific from 1E+11 and below 1E-04 |
| Dates | d dd ddd dddd, m mm mmm mmmm mmmmm, yy yyyy |
m/mm are minutes right after an hour or right before seconds. Day 0 of the 1900 system shows as 1900-01-00, serial 60 as 1900-02-29, and weekdays follow Excel (serial 1 is a Sunday) |
| Times | h hh m mm s ss, AM/PM am/pm A/P a/p, .0–.000 |
Times are rounded to the shown precision before splitting, so 0.99999999 days is the next day 00:00 |
| Elapsed time | [h] [hh] [m] [mm] [s] [ss] |
Totals beyond 24 hours / 60 minutes; negative values get a minus sign |
| Dates Excel can't show | negative serials, past 9999-12-31 | text: '' with fill: { char: '#' }: the cell fills with #, as in Excel |
| Locale tags | [$€-407], [$-409], [$-F800], [$-F400], [$-x-sysdate], [$-x-systime] |
The symbol is printed. The locale id switches month and day names for that section (common ids only, [to verify] per id). F800/x-sysdate is the locale's long date and F400/x-systime its time, from Intl [to verify against Windows settings] |
| Era and calendar tokens | e, b, bb, g |
e is the year; b/bb the Buddhist-era year (+543); g era names are not rendered [to verify] |
| Not rendered | [DBNum1], [NatNum1] and other bracket codes, B1/B2 calendar prefixes |
Ignored |
- Fixed ids: 1–4, 9–13, 15–21, 37–40 and 45–49 render the codes of §11.2.
- Short-date ids: 14 is the locale's short date, numeric with a four-digit year (
1/15/2024in en-US,15.01.2024in de-DE). 22 is that plush:mm. The East Asian ids 27–31, 36 and 50–58 show the short date too, and 32–35 showh:mm:ss[to verify per locale]. - Currency and accounting: ids 5–8 and 41–44 use their en-US codes (
"$"#,##0_);\("$"#,##0\)and so on)[to verify for other locales]. - Other ids render as General.
- Platform data. Separators, month and day names and the short-date pattern come from
Intl.NumberFormatandIntl.DateTimeFormatforlocale, so the module ships no locale tables. - Separators. The
.and,of a format code are replaced by the locale's decimal and group separators, as Excel does with the system settings[to verify]. The group separator is the locale's own character; for fr-FR it is a narrow no-break space. - Unchanged parts. Booleans stay
TRUE/FALSE,AM/PMis shown as written in the code, and grouping is always by three digits[to verify for locales such as en-IN]. - Invalid locales. A locale tag Intl rejects falls back to en-US.
Excel is the authority; LibreOffice is the automated reference.
- The check. The
LibreOfficeCI job writes every case oftest/format/cases.ts, plus every number-formatted cell of the conformance files10-number-formatsand11-number-formats-locale, to one workbook. It has LibreOffice export the workbook to CSV with "save cell contents as shown" in en-US, and compares each cell withformatCell(cell, { locale: 'en-US' })(test/format/libreoffice.test.ts). - Where LibreOffice differs. Every case where LibreOffice is known to differ is listed in that test with LibreOffice's output. The table below records it, with what this module does and why. Each is
[to verify]against Excel in the conformance checklist.
Result in CI (LibreOffice 26.2, en-US): 439 probes, 350 identical, 89 different for a known reason (1900 calendar 27, time rounding 28, General 12, dangling point 7, ? padding 9, am/pm case 5, Buddhist year 1), 0 unexplained. Built-in ids 39, 40 and 47 no longer differ: both use Excel's codes (§11.2). One mm:ss.0 probe now counts under time rounding. Every difference has one of the known causes below. Any other difference fails the job.
| Difference | LibreOffice | formatValue (Excel's behaviour, [to verify]) |
|---|---|---|
| Serials below 61 (the 1900 calendar) | Counts from 1899-12-30: serial 1 is 1899-12-31, no 1900-02-29, no day 0 | Serial 1 is 1900-01-01, 60 is 1900-02-29, below 1 is day 0 (1900-01-00), as Excel |
| Time rounding | Truncates to the shown unit: 0.6458333 is 15:29:59, 3:29 PM |
Rounds to the shown second first: 15:30:00, 3:30 PM; 45306.99999999 with yyyy-mm-dd is the next day |
| General | Up to 15 significant digits, no width limit, 3-digit exponents (0.333333333333333, 1E+021) |
Fits 11 characters (0.333333333, 1E+21, 1.23457E+11) |
| A decimal point with no digits after it | Dropped: #,##0.### shows 7 |
Kept: 7. |
? padding |
U+2007 FIGURE SPACE | A plain space, as text copied from Excel has |
am/pm and A/P case |
AM/PM upper-cased, A/P lower-cased |
As written in the code |
b, bb, bbbb |
Not known; printed as text | The Buddhist-era year (Gregorian + 543) |
Built-in ids 32–35 are rendered as h:mm:ss, which matches LibreOffice in en-US: they are times in the East Asian locales that define them [to verify].
What a spreadsheet viewer needs to draw a sheet, computed from a read workbook. It is framework-free and has no DOM access, so it runs in Node, in a worker and behind any UI (react-xlsx-viewer's design, decision Q2, puts it here). Part of 2.0, like /format (§5.7), from the 2.0 prerelease after its merge.
The render model provides:
- geometry: row and column offsets in CSS pixels, plus hit testing;
- a merge map;
- concrete styles:
#RRGGBBcolours and resolved fonts; - edge resolution: the border edge between two cells;
- display text, through an optional number-format hook;
- formula text for a formula bar;
- hyperlink checks;
- keyboard movement: one cell, and Ctrl+arrow data edges;
- copy: TSV and HTML for the clipboard, and a selection summary.
It leaves text measurement (overflow into neighbours, ####, shrink to fit, auto row height), RTL mirroring, zoom, focus and DOM work to the UI.
export function createRenderSheet(workbook: Workbook<CellInput>, sheet: number, options?: RenderOptions): RenderSheet; // reader output or a built workbook
export interface RenderOptions {
/** Display text. Pass `formatCell` from javascript-excel/format; default: `cellText` (raw values). */
format?: RenderFormatter;
locale?: string; // passed to `format`; default 'en-US'
maxDigitWidth?: number; // px of the default font's widest digit at 100 %; default 7 (Calibri 11, §3.3)
margin?: { rows?: number; cols?: number }; // empty rows/columns after the used range; default 50 / 10
hyperlinkSchemes?: string[]; // external link schemes allowed; default ['http', 'https', 'mailto'] (§12 Q16)
}
/** Any function with this shape; `formatCell` from javascript-excel/format fits. */
export type RenderFormatter = (cell: Cell, options: { locale?: string; date1904?: boolean; indexedColors?: readonly string[] }) =>
{ text: string; color?: string; fill?: { char: string; at: number }; align?: 'left' | 'center' | 'right' };
/** An opaque handle. Its caches live with it; drop the handle to free them. */
export interface RenderSheet { readonly sheet: number; readonly name: string }export function sheetExtent(s: RenderSheet): { rows: number; cols: number }; // used range + margin, capped at 1,048,576 x 16,384
export function sheetSettings(s: RenderSheet): {
freeze: { rows: number; cols: number }; rightToLeft: boolean; showGridLines: boolean; showHeaders: boolean;
zoom: number; activeCell: CellRef; selection: RangeRef | null; tabColor: string | null;
};
export function rowTop(s: RenderSheet, row: number): number; // px from the top of row 0 at zoom 100 %; rowTop(s, extent.rows) is the total height
export function rowHeight(s: RenderSheet, row: number): number;
export function colLeft(s: RenderSheet, col: number): number; // logical (left-to-right) offset; the UI mirrors for RTL
export function colWidth(s: RenderSheet, col: number): number;
export function rowAt(s: RenderSheet, y: number): number; // the visible row under y (binary search); clamped to the extent
export function colAt(s: RenderSheet, x: number): number;
export function isRowHidden(s: RenderSheet, row: number): boolean;
export function isColHidden(s: RenderSheet, col: number): boolean;
export function hasStoredRowHeight(s: RenderSheet, row: number): boolean; // the file sets this row's height
export function setRowHeights(s: RenderSheet, heights: ReadonlyArray<readonly [row: number, px: number]>): boolean; // auto-fit
export interface CellRef { row: number; col: number }
export interface RangeRef { start: CellRef; end: CellRef } // inclusive, start <= end- Extent. The used range is the sheet's
dimension(or the cells, merges, row and column properties present), plus the margin. Indices outside the extent are clamped. - Row heights. A row's height in points becomes CSS pixels as
pt × 96 / 72. Missing heights usesheet.defaultRowHeight, else 15 pt. - Column widths. A width in characters becomes pixels with the file-width formula and
maxDigitWidth(§3.3). Missing widths usesheet.defaultColWidth, else 8.43 characters (64 px at the default 7). - Hidden rows and columns. Hidden, or width/height 0, means size 0.
rowAt/colAtnever return a hidden index. - Cost. Offsets are prefix sums, built once in O(rows + columns) (
Float64Array).rowTop/colLeftare O(1), androwAt/colAtare O(log n). - Auto-fit (react-xlsx-viewer decision Q11). Excel fits rows without a stored height to their content (wrapped, rotated or larger text) when it opens a file. The render model can't measure text, so the viewer measures and calls
setRowHeightswith CSS px at zoom 100 %.- It only applies to rows without a stored height (
hasStoredRowHeightis false) that aren't hidden. - Heights are clamped to [the default row height, 409 pt], so auto-fit only grows rows.
- The offsets are rebuilt from the first changed row onwards, so a batch costs O(rows after it).
rowTop,rowHeightandrowAtreflect the new heights at once. - The model isn't changed, only the handle's geometry. Cells don't depend on row heights, so their cache is kept.
- It only applies to rows without a stored height (
- Settings. They come from
sheet.viewandsheet.tabColor:- zoom defaults to 100, the active cell to A1;
- grid lines and headers are shown unless the file turns them off;
- the tab colour is resolved to
#RRGGBB.
export function renderCell(s: RenderSheet, row: number, col: number): RenderCell | null;
export function mergeAt(s: RenderSheet, row: number, col: number): { anchor: CellRef; range: RangeRef } | null;
export interface RenderCell {
text: string; // displayed text (format hook, else cellText)
runs?: Array<{ text: string; font: RenderFont }>; // rich text, fonts merged over the cell font
value: CellValue | null; // the (cached) value
type: CellType;
formula?: string; // for a formula bar: '=' + text, display prefixes removed
arrayFormula?: boolean; // shown as {=…}
noCachedValue?: boolean; // a formula without a cached value: text is ''
style: RenderStyle; // concrete; shared by every cell with the same style object
edges: RenderEdges; // the borders this cell draws, after resolving with its neighbours
merge?: { rows: number; cols: number }; // on a merge's anchor
hyperlink?: RenderHyperlink;
align: 'left' | 'center' | 'right'; // the format's alignment under 'general': numbers right, text left, booleans/errors centred
color?: string; // a format section colour ([Red]) as #RRGGBB; overrides the font colour
fill?: { char: string; at: number }; // a *x fill from the format
}
export interface RenderStyle {
font: RenderFont;
background:
| { kind: 'none' }
| { kind: 'solid'; color: string }
| { kind: 'pattern'; pattern: PatternType; fg: string; bg: string }
| { kind: 'gradient'; gradient: 'linear' | 'path'; degree: number; stops: Array<{ position: number; color: string }> };
border: { top?: RenderBorder; right?: RenderBorder; bottom?: RenderBorder; left?: RenderBorder; diagonalUp?: RenderBorder; diagonalDown?: RenderBorder };
align: {
horizontal: 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
vertical: 'top' | 'center' | 'bottom' | 'justify' | 'distributed';
wrap: boolean; shrink: boolean; indent: number; rotation: number | 'vertical'; direction: 'auto' | 'ltr' | 'rtl';
};
}
export interface RenderFont {
family: string; sizePt: number; color: string; bold: boolean; italic: boolean;
underline: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting'; strike: boolean;
vertAlign: 'baseline' | 'superscript' | 'subscript';
}
export interface RenderBorder { style: BorderStyle; color: string }
export interface RenderEdges { top?: RenderBorder; left?: RenderBorder; right?: RenderBorder; bottom?: RenderBorder }
export type RenderHyperlink =
| { kind: 'external'; href: string; allowed: true; tooltip?: string }
| { kind: 'external'; href: string; allowed: false; reason: 'scheme' | 'malformed'; tooltip?: string }
| { kind: 'internal'; sheet: number | null; ref: string; tooltip?: string };renderCellis lazy. It returnsnullwhen there is nothing to draw: no value, no style from the cell, its row or its column, and no merge anchor. Covered cells of a merge returnnull; the anchor carries the value and style. Results are cached in a bounded cache, so redrawing a window costs no recomputation.- Style source. A cell uses its own style (the reader's complete
xf, §3.5.7). A cell without one takes the row style, then the column style. Fields missing from a style fall back to the workbook's default font (Calibri 11 when the file has none), black text, no fill, no borders, general/bottom alignment. - Shared styles.
RenderStyleobjects are cached in aWeakMapkeyed by the model's style object. The reader shares one frozenStyleperxf(§12 Q8), so a sheet with 20 distinct formats resolves 20 styles, whatever its size. - Colours. Every colour is concrete
#RRGGBB, resolved withresolveColor(§4.4) against the workbook's theme and indexed palette:- automatic and missing font colours are black;
- a pattern's missing foreground is black and its missing background white;
- borders without a colour are black.
- Border edges. Each cell draws its top and left edges, and its right and bottom edges only at the end of the extent. The shared edge between two cells is resolved once:
- the heavier style wins, by weight:
hair,dotted,dashDotDot,dashDot,dashed,thin,mediumDashDotDot,slantDashDot,mediumDashDot,mediumDashed,medium,double,thick[to verify: Excel's precedence on screen]; - on a tie, the right or lower cell wins.
- Neighbours are the next visible row or column. A merged neighbour is represented by its anchor's style.
- Along a multi-row or multi-column merge, the edge is resolved against the neighbour at the anchor's row or column
[approximation].
- the heavier style wins, by weight:
- Formula text.
'=' + formula, with the_xlfn.,_xlfn._xlws.and_xlpm.prefixes removed outside string literals[to verify: the full prefix list].arrayFormulais set when the cell hasarrayRef. A formula without a cached value hasnoCachedValue: trueand empty text; the render model never calculates. - Hyperlinks.
- External targets: trimmed. A target with control characters or no scheme is
malformed. One whose scheme isn't inhyperlinkSchemes(case-insensitive) isscheme. Both areallowed: false, so the UI shows the text without opening anything (§8). - Internal locations: a defined name, or a reference such as
'Sheet 2'!B4, is resolved to a sheet index and an A1 reference.sheet: nullwhen the sheet or name doesn't exist.
- External targets: trimmed. A target with control characters or no scheme is
- Display text. With a
formathook, it is the hook's text, colour (ARGB →#RRGGBB), fill and alignment. The hook getslocale,date1904and the workbook'sindexedColors. Without one, the text iscellText(cell)and the alignment follows the value type. For exact dates, read withdates: 'serial'(§5.2).
export type RenderDirection = 'up' | 'down' | 'left' | 'right';
export function step(s: RenderSheet, from: CellRef, dir: RenderDirection): CellRef; // arrow keys
export function edge(s: RenderSheet, from: CellRef, dir: RenderDirection): CellRef; // Ctrl+arrow
export function lastUsedCell(s: RenderSheet): CellRef; // Ctrl+Endstepmoves to the next visible cell. From inside a merge it moves from the merge's edge, and landing inside a merge returns its anchor. At the extent's edge it stays put.edgefollows Excel's rule:- from a non-empty cell whose next visible neighbour is non-empty, it moves to the last non-empty cell before a blank;
- otherwise it moves to the next non-empty cell, or to the extent's edge if there is none.
- Hidden rows and columns are skipped
[to verify against Excel]. - A cell is empty when it has no value and no formula. Styles don't count.
- The scan is linear in the rows or columns crossed.
lastUsedCellis the last row and column of the used range, as Excel's Ctrl+End.
export function rangeAsTsv(s: RenderSheet, range: RangeRef, options?: { values?: 'displayed' | 'raw' }): string;
export function rangeAsHtml(s: RenderSheet, range: RangeRef): string;
export function rangeStats(s: RenderSheet, range: RangeRef, limit?: number): { count: number; numericCount: number; sum: number; average: number | null; truncated: boolean };- TSV (
text/plain).- Rows are separated by CRLF and cells by TAB, with displayed text by default.
- A field containing a tab, a line break or a quote is quoted, with quotes doubled, as Excel writes it.
- Merged areas contribute their anchor's text once; covered cells are empty.
- Hidden rows and columns are included, as in Excel's default copy
[to verify]. - Nothing is guarded against formulas: it is the user's own clipboard (react-xlsx-viewer decision Q15).
- HTML (
text/html).- A
<table>withcolspan/rowspanfor merges inside the range. - Inline styles carry font weight, style, size, family and colour, plus background colour, horizontal alignment, wrapping and solid borders.
- Every text and attribute value is escaped, so file content can't add markup.
- A
rangeStatsis a status-bar summary over the cached values:count: the non-empty cells;numericCount,sumandaverage: over the numbers, including date serials;- it scans at most
limitcells (default 1,000,000) and setstruncatedpast that. - This is arithmetic on cached values, not formula evaluation.
bench/render.mjs (npm run bench:render; the CI job Benchmarks runs it and reports to its summary) measures the costs react-xlsx-viewer's design names (its §9). The workload is 10 columns of numbers with 8 shared styles, written and read back with dates: 'serial'. Measured on an Apple M2 laptop, Node 26.13.1:
| cells | create (ms) | memory retained by the handle (MB) | 50 × 20 window, first draw / cached (ms) | scrolling, per window, p50 / max (ms) | Ctrl+Down, full column (ms) | TSV + HTML of 10,000 cells (ms) |
|---|---|---|---|---|---|---|
| 100,000 | 1.0 | 0.11 | 1.65 / 0.09 | 0.05 / 0.73 | 1.6 | 16.2 |
| 1,000,000 | 3.6 | 0.77 | 0.22 / 0.04 | 0.05 / 0.54 | 14.3 | 15.1 |
- Memory. The handle costs O(rows + columns): about 8 bytes per row and per column for the offset tables. Per-cell results live in a cache capped at 20,000 cells, and styles are cached per distinct style object.
- Measurement notes. The first-draw figure at 100,000 cells includes JIT warm-up, since that size runs first. Ctrl+Down scans linearly: about 14 ms across 100,000 rows.
Internal. Not exported in 2.0, so its shape can still change; this is revisited when a real need appears (§12 Q10).
/** Compression only. The container format (headers, central directory, CRC-32) is in-house and not pluggable. */
interface ZipCodec {
/** Raw DEFLATE (RFC 1951), no zlib/gzip wrapper. Input arrives in chunks. */
deflateRaw(chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, signal?: AbortSignalLike): Promise<Uint8Array>;
/** Streams output; aborts with LIMIT_EXCEEDED as soon as maxOutputBytes or the ratio limit is passed. */
inflateRaw(
data: Uint8Array,
limits: { maxOutputBytes: number; maxRatio: number },
signal?: AbortSignalLike,
): AsyncIterable<Uint8Array>;
}Default implementation: new CompressionStream('deflate-raw') and new DecompressionStream('deflate-raw'). Container details:
- Writer: zip method 8 (deflate) or 0 (store); CRC-32 computed in-house over the uncompressed bytes; sizes known before each local header, so no data descriptors; UTF-8 names (general-purpose flag bit 11).
[Content_Types].xmlis the first entry, by convention. No zip64: an archive over 4 GiB − 1 or over 65,535 entries throwsZIP64_REQUIRED, which no realistic workbook reaches. - Reader: locates the end-of-central-directory record, then walks the central directory. Local headers are checked against it. It reads zip64 records (some tools write them for small files), supports methods 0 and 8 only (
ZIP_UNSUPPORTED_METHOD), rejects the encryption flag (ZIP_ENCRYPTED) and duplicate entry names (ZIP_INVALID), and verifies each entry's CRC-32 (ZIP_CRC_MISMATCH).
What this choice implies for the API:
- Async only. The compression streams have no synchronous form, so
toUint8Array,toBlobandreadreturn promises. There is nowriteSync. A synchronous API could come later through an optional adapter that implementsZipCodec(for example on fflate), without changing the model. - Runtime floor: Node.js 22 or later (
engines: { "node": ">=22" }), and browsers and workers that supportCompressionStream('deflate-raw')(§9.3). Node has supporteddeflate-rawin its globalCompressionStreamsince 21.2.0, so every Node 22 release has it. JSE-2 verified this on Node 22.0.0 and in CI. Other runtimes work if they have the API. The import itself never fails. The first call throwsENVIRONMENT_UNSUPPORTEDwith a clear message when the API is missing. - Zero runtime dependencies, and roughly native compression speed.
- Output size depends on the platform's deflate implementation (zlib in Chromium and Node). Output can differ by a few bytes between runtimes; content is identical.
export class ExcelError extends Error {
readonly code: ExcelErrorCode;
readonly details?: Record<string, unknown>; // e.g. { sheet, ref, limit, value }
constructor(code: ExcelErrorCode, message: string, options?: { cause?: unknown; details?: Record<string, unknown> });
}
export class ValidationError extends ExcelError {} // the model or options cannot be written
export class FormatError extends ExcelError {} // the input is not a readable xlsx/csv
export class LimitError extends ExcelError {} // a ReadLimits value was exceeded; details.limit names it
export class CsvError extends ExcelError {} // malformed CSV in strict mode
export class EnvironmentError extends ExcelError {} // a required platform API is missing
/** Works across ESM/CJS copies and realms; checks a brand, not the prototype chain. */
export function isExcelError(e: unknown): e is ExcelError;Aborts are not ExcelErrors: they reject with signal.reason, as fetch does.
| Code | Class | When |
|---|---|---|
NO_SHEETS |
Validation | Workbook has no sheets |
INVALID_SHEET_NAME / DUPLICATE_SHEET_NAME |
Validation | §3.3 |
INVALID_SHEET_PROPERTY |
Validation | A sheet property is out of range or of the wrong type: colProps, rowProps, default sizes, view, print, state; details.path names it |
INVALID_DEFINED_NAME |
Validation | A defined name breaks Excel's naming rules, is reserved (_xlnm.), is duplicated in its scope, or has an empty ref or a bad sheet |
INVALID_ACTIVE_SHEET |
Validation | Out of range, or the sheet is hidden |
INVALID_REF |
Validation | Malformed A1 reference or range |
OUT_OF_BOUNDS |
Validation | Row or column beyond the format limits |
INVALID_CELL |
Validation | type disagrees with value, or an unsupported value |
INVALID_NUMBER |
Validation | NaN or ±Infinity |
INVALID_DATE |
Validation | Invalid or out-of-range Date (§3.4.1) |
STRING_TOO_LONG |
Validation | More than 32,767 characters in a cell |
INVALID_STYLE |
Validation | Bad colour string, unknown enum value, out-of-range number |
INVALID_NUMFMT |
Validation | Empty code, or an id outside 0..163 given as a number |
INVALID_HYPERLINK |
Validation | Scheme not in hyperlinkSchemes (e.g. javascript:), no scheme (a relative path), control characters, an empty target or location, or an invalid hyperlinkSchemes option |
OVERLAPPING_MERGE |
Validation | Two merges overlap |
INVALID_COLUMN |
Validation | fromDataset: no usable accessor, or a forbidden path segment |
TOO_MANY_STYLES |
Validation | More than 64,000 distinct cell formats, Excel's limit. A file with exactly 64,000 opens without repair (confirmed in Excel for Mac, 2026-11-17) |
INVALID_PROPERTY |
Validation | A document property is invalid: not a string, an invalid Date, a duplicate or empty custom property name, a non-finite number |
ZIP64_REQUIRED |
Validation | §6 |
UNSUPPORTED_FORMAT |
Format | .xls/encrypted (CFB), .xlsb, .ods, and Strict OOXML if not mapped (§5.2); details.format says which |
NOT_XLSX |
Format | A zip without a workbook part |
ZIP_INVALID / ZIP_UNSUPPORTED_METHOD / ZIP_ENCRYPTED / ZIP_CRC_MISMATCH |
Format | §6 |
XML_MALFORMED |
Format | Not well-formed XML in a required part |
XML_DTD_FORBIDDEN |
Format | Any <!DOCTYPE (§8) |
SHEET_NOT_FOUND |
Validation | importDataset: the sheet name or index doesn't exist (§5.6) |
VALIDATION_FAILED |
Validation | Reserved for react-data-import: row validation stopped at an invalid row; details.issues |
LIMIT_EXCEEDED |
Limit | Any ReadLimits value, or importDataset's maxRows; details: { limit, value, max } |
CSV_MALFORMED |
Csv | Strict mode only |
ENVIRONMENT_UNSUPPORTED |
Environment | No CompressionStream, no DOM for /dom |
-
Writer: throw. Anything that cannot be written faithfully is a
ValidationError, raised before any output. The writer has no warnings, so a file that comes out is the file that was asked for. Unknown fields are ignored (forward compatibility, §9). -
Builders (
fromDataset,fromTable) coerce where the input is data rather than structure, and report throughonWarning(COERCION_FAILED,NON_FINITE_NUMBER). Structural mistakes (bad column definitions, bad sheet names) throw. -
Reader: throw when the file cannot be read as a workbook (format, zip, required XML part malformed, DTD) or a limit is exceeded. Collect when one feature is damaged or unsupported and the rest of the workbook is still usable:
Warning code Situation and recovery UNSUPPORTED_PARTCharts, drawings, pivots, comments, VBA, … dropped; one warning per kind INVALID_STYLE_INDEXCell refers to a missing xf; default style usedINVALID_SHARED_STRINGIndex out of range; cell left empty CELL_OUT_OF_BOUNDS/INVALID_CELL_REFCell skipped DUPLICATE_CELLSame cell twice; the last one wins INVALID_DATE_SERIALDate-formatted number that is not a valid date; returned as a number SHARED_FORMULA_UNRESOLVEDShared formula that could not be shifted; cached value only (§12 Q6) MISSING_PARTA relationship points to a missing optional part (styles, theme, shared strings); defaults used BROKEN_OPTIONAL_PARTMalformed XML in an optional part (docProps, theme); part skipped HYPERLINK_RANGE_REDUCED,SPLIT_PANE_IGNORED§3.6 ROWS_TRUNCATEDReadOptions.maxRowsreached; later rows of that sheet not read (§5.2)HYPERLINK_DROPPEDfromTable: a link whose scheme is not allowed; the cell keeps its textWARNINGS_TRUNCATEDmaxWarningsreached; later warnings dropped
export interface ExcelWarning {
code: string; // one of the codes above; the union is exported as ExcelWarningCode
message: string;
part?: string; // zip part, e.g. 'xl/worksheets/sheet2.xml'
sheet?: string;
ref?: string; // cell or range
}- CSV: lenient by default (warnings
CSV_UNTERMINATED_QUOTE,CSV_STRAY_QUOTE,CSV_FIELD_COUNT,CSV_INVALID_ENCODING);mode: 'strict'throwsCSV_MALFORMEDinstead.CSV_ROWS_TRUNCATED(maxRowsreached) is reported in both modes (§5.3).
Threat model. The reader and CSV parser receive files from untrusted users, often in a browser tab or on a server handling uploads. An attacker controls every byte. The goals: no code execution, no reads or requests beyond the input, no prototype pollution, bounded memory and CPU (reading fails with LimitError instead of exhausting them), and no surprise for downstream apps (formula injection).
| Threat | Defence |
|---|---|
| Zip bombs (tiny file, huge output; many entries; nested archives) | maxInputBytes, maxEntries, maxEntryBytes, maxTotalBytes, maxRatio (§5.2). Sizes are counted on the actual inflated stream, never trusted from headers, and inflation stops the moment a limit is passed. Nested archives are never opened. |
| Zip structure tricks (overlapping entries, local and central headers disagreeing, duplicate names) | Central directory is authoritative, local headers must agree, duplicates throw ZIP_INVALID. Entry names are opaque Map keys and never touch a file system, so path traversal does not apply. |
| XXE and entity expansion ("billion laughs") | The tokenizer rejects any <!DOCTYPE (XML_DTD_FORBIDDEN). Only the five predefined entities and numeric character references are decoded; references to invalid code points are errors. No external resource is ever fetched. |
| Deep nesting | maxXmlDepth. The tokenizer is iterative, never recursive. |
| Memory exhaustion by content | maxCells, maxSharedStrings, maxWarnings; sheets are streamed (§5.2). |
| Prototype pollution | Nothing read from a file becomes an object key. Lookups (styles, shared strings, relationships, defined names, custom properties) use Map or arrays. The only API that builds objects keyed by file content, toDataset, returns null-prototype objects (§4.3). fromDataset path accessors reject __proto__, prototype and constructor. |
| Formula execution | Formulas are never evaluated; they come back as text. |
| Formula injection into CSV | Guard on by default (§5.3). |
| Malicious hyperlinks | The writer allows only http, https and mailto by default, and rejects javascript:, data:, vbscript: and anything else not listed. The reader returns targets verbatim (it cannot know the consumer's policy): apps that render them, such as the viewer, must check the scheme. |
| External references | External links, OLE objects, DDE and data connections are not read or followed. The reader resolves relationships only within the package. |
| ReDoS | Hot paths (A1 parsing, number detection, CSV) use hand-written scanners or linear regexes with no nested quantifiers. Format codes are bounded by part size. |
| Encrypted, legacy and macro content | CFB containers (.xls, encrypted OOXML) throw UNSUPPORTED_FORMAT; VBA parts are dropped, never executed. |
Writer-side hygiene: all text and attributes are XML-escaped, and invalid XML characters are encoded (§3.4). A string that starts with = is text, never a formula. Sheet names and defined names are validated, and sheet names are quoted correctly in generated references ('It''s'!A1).
The limits are on by default. Raising them is an explicit limits option, and the README will say to keep them when the input is untrusted.
- Semantic Versioning. 2.0.0 is a breaking rewrite of 1.0.3. Prereleases ship on the
nextdist-tag:2.0.0-alpha.1to2.0.0-alpha.7while the API was still changing, then2.0.0-beta.0and2.0.0-beta.1, with the 2.0.0 feature set complete and only fixes.2.0.0is onlatest; later prereleases (for example of 2.1) ship onnext. - Public API: the exports of the five entry points, their TypeScript types, the error codes and warning codes, and the behaviour documented here.
ZipCodecand everything not exported are internal. - Breaking (major): removing or renaming an export, option or code; a narrower accepted input type; a different default that changes output (for example the injection guard or
dateZone); dropping a runtime from §9.3; required fields added to input types. - Not breaking (minor): new exports, options and optional model fields; the reader populating new optional fields (consumers must tolerate unknown fields); new warning codes; new error codes for inputs that were previously undefined behaviour.
- Patch: bug fixes, including output that Excel had to repair.
- Read-limit defaults may be tuned in minors, but only upward (more permissive) when backed by measurements. Making them stricter is a major.
- Deprecations are announced in a minor with a runtime-free JSDoc
@deprecatedand removed in the next major.
- Writes ECMA-376 transitional SpreadsheetML meant to open without repair in Excel (Windows and Mac, current), LibreOffice Calc, Apple Numbers and Google Sheets. Checked so far: every conformance file in Excel for Mac (by hand, 2026-11-17) and in LibreOffice Calc (in CI). Excel for Windows, Numbers and Google Sheets
[to verify: not checked by hand yet]. - Reads files produced by those four plus common generators. Tested today: files written by openpyxl and LibreOffice (reader fixtures) and the corpus re-saved by LibreOffice. Files saved by Excel, Numbers and Google Sheets
[to verify: no reader fixtures from those apps yet]. Other generators (SheetJS, ExcelJS, Apache POI)[to verify with fixtures]. The cross-checks, and why openpyxl replaced the planned SheetJS comparison, are in conformance.md.
| Runtime | Support | Basis |
|---|---|---|
| Node.js 22, 24 | Supported, tested in CI | engines: { "node": ">=22" } |
| Node.js 20 and older | Not supported | Node 20 reached end of life on 2026-04-30 |
| Chrome, Edge | 103+ (CompressionStream('deflate-raw')) |
MDN browser-compat-data (no browser job in CI yet) |
| Firefox | 113+ | MDN browser-compat-data (no browser job in CI yet) |
| Safari (macOS, iOS) | 16.4+ | MDN browser-compat-data (no browser job in CI yet) |
| Web Workers | Same versions as their browser | |
| Deno, Bun, Cloudflare Workers | Expected to work, untested | Same web APIs |
| TypeScript (consumers) | 5.0+, moduleResolution node16, nodenext or bundler |
Types are built with TypeScript 7; CI job Consumer TS |
| Bundlers | Vite, webpack 5, Next.js (App Router, SSR), esbuild, Rollup | exports map, sideEffects: false, no import-time globals |
The floor is set by deflate-raw support in CompressionStream/DecompressionStream. For Node it is fixed at 22 (decided). The browser versions above are the earliest with deflate-raw in both CompressionStream and DecompressionStream, according to MDN browser-compat-data 8.1.9 (checked 2026-11-16 in JSE-2).
TypeScript. The library is compiled, and its .d.ts files generated, with TypeScript 7. The declarations in this document use only long-established type-system features: interfaces, union and literal types, generics with defaults, Readonly/Record/Pick/Partial, and classes. There are no enums, no namespaces, no declare global and no ambient module augmentation. Nothing depends on compiler options or syntax that TypeScript 7 removed, which concern how code is compiled, not what declarations may contain. Consumers must resolve the package exports map, so their moduleResolution must be node16, nodenext or bundler. The oldest TypeScript version that can consume the published types is 5.0, the first release with moduleResolution: bundler. 4.7–4.9 handle node16/nodenext but not bundler. The CI job Consumer TS enforces this floor: it type-checks a consumer fixture against the packed tarball with every TypeScript minor from 5.0 to 7.0, under all three modes, with skipLibCheck off. If a declaration ever needs a newer compiler, that job fails, and either the floor moves up (README and this table) or the declaration changes. There is no typesVersions fallback: it would only serve moduleResolution: node (node10), which cannot resolve the exports subpaths the code itself is loaded from.
import { fromDataset, toBlob, borderAll } from 'javascript-excel';
import { download } from 'javascript-excel/dom';
const sheet = fromDataset(
{
columns: [
{ title: 'Name', key: 'name', width: 'auto' },
{ title: 'Joined', key: 'joined', type: 'date', numFmt: 'yyyy-mm-dd' },
{
title: 'Sales',
children: [
{ title: 'Q1', path: 'sales.q1', numFmt: '#,##0.00', total: 'sum' },
{ title: 'Q2', path: 'sales.q2', numFmt: '#,##0.00', total: 'sum' },
],
},
],
data: [
{ name: 'Ada', joined: new Date(2024, 0, 15), sales: { q1: 1200.5, q2: 980 } },
{ name: 'Grace', joined: new Date(2023, 5, 1), sales: { q1: 860, q2: 1430.25 } },
],
},
{
name: 'People',
freezeHeader: true,
autoFilter: true,
headerStyle: { font: { bold: true, color: 'FFFFFF' }, fill: '305496', border: borderAll({ style: 'thin' }) },
totals: { label: 'Total', style: { font: { bold: true } } },
},
);
const blob = await toBlob({ sheets: [sheet], properties: { title: 'People' } });
download(blob, 'people.xlsx');Exporting an HTML table:
import { toBlob } from 'javascript-excel';
import { fromTable, download } from 'javascript-excel/dom';
const sheet = fromTable(document.querySelector('table')!, { styles: 'computed', freezeHeader: true });
download(await toBlob({ sheets: [sheet] }), 'report.xlsx');The engine works directly in React. react-data-export 1.0 will wrap exactly this as exportDataset(), useExcelExport() and <ExcelExport>, so most apps should use it rather than the code below.
import { fromDataset, toBlob } from 'javascript-excel';
import { download } from 'javascript-excel/dom';
export function ExportButton({ rows }: { rows: Array<{ id: number; email: string }> }) {
const onClick = async () => {
const sheet = fromDataset({ columns: [{ title: 'ID', key: 'id' }, { title: 'Email', key: 'email' }], data: rows });
download(await toBlob({ sheets: [sheet] }), 'users.xlsx');
};
return <button onClick={onClick}>Export</button>;
}Nothing in javascript-excel touches the DOM at import, so this component renders on the server unchanged; download only runs in the click handler.
<script setup lang="ts">
import { fromDataset } from 'javascript-excel';
import { toCsvBlob } from 'javascript-excel/csv';
import { download } from 'javascript-excel/dom';
const props = defineProps<{ orders: Array<{ id: string; total: number; placed: Date }> }>();
function exportCsv() {
const sheet = fromDataset({
columns: [{ title: 'Order', key: 'id' }, { title: 'Total', key: 'total' }, { title: 'Placed', key: 'placed' }],
data: props.orders,
});
download(toCsvBlob(sheet, { delimiter: ';' }), 'orders.csv'); // BOM on, injection guard on
}
</script>
<template><button @click="exportCsv">Export CSV</button></template>import { readFile, writeFile } from 'node:fs/promises';
import { toUint8Array } from 'javascript-excel';
import { read } from 'javascript-excel/read';
// Write
const bytes = await toUint8Array({
sheets: [{
name: 'Report',
rows: [
['Item', 'Qty', 'Price', 'Line total'],
['Pens', 10, 1.5, { formula: 'B2*C2', value: 15 }],
['Pads', 4, 3.25, { formula: 'B3*C3', value: 13 }],
],
colProps: [{ width: 20 }],
view: { freeze: { rows: 1 } },
}],
properties: { creator: 'billing-service', created: new Date(), modified: new Date() },
}, { dateZone: 'utc' });
await writeFile('report.xlsx', bytes);
// Read an untrusted upload
const { workbook, warnings } = await read(await readFile('upload.xlsx'), {
sheets: [0],
styles: false,
dateZone: 'utc',
limits: { maxCells: 1_000_000 },
});
const first = workbook.sheets[0];
for (const row of first.rows) {
// row?.[c] is a Cell: { type, value, formula?, style? }
}
if (warnings.length) console.warn(warnings);import { createWorkerClient } from 'javascript-excel/worker';
const client = createWorkerClient(new Worker(new URL('./excel.worker.ts', import.meta.url), { type: 'module' }));
const controller = new AbortController();
cancelButton.onclick = () => controller.abort();
const bytes = await client.write(workbook, {
signal: controller.signal,
onProgress: ({ ratio }) => (progressBar.value = ratio),
});| Limit | Value | Source |
|---|---|---|
| Rows per sheet | 1,048,576 | Excel specifications and limits |
| Columns per sheet | 16,384 (A..XFD) | Excel specifications and limits |
| Characters in a cell | 32,767 | Excel specifications and limits |
| Sheet name length | 31 | Excel UI; §3.3 |
| Column width | 255 characters | Excel specifications and limits |
| Row height | 409 points | Excel specifications and limits |
| Unique cell formats | 64,000 | Excel specifications and limits; a file with 64,000 opens without repair (confirmed in Excel for Mac, 2026-11-17) |
| Formula length | 8,192 characters | Excel specifications and limits |
| Zoom | 10–400 % | CT_SheetView/@zoomScale |
Ids defined by the spec. Ids 14–17 and 22 render according to the user's locale in Excel even though the spec lists these codes. For 37–40 and 47 the table has the codes Excel itself uses (confirmed in Excel for Mac, 2026-11-17; conformance.md, 10-number-formats). ECMA-376 lists #,##0 ;(#,##0), #,##0 ;[Red](#,##0), #,##0.00;(#,##0.00), #,##0.00;[Red](#,##0.00) and mmss.0 for them. BUILTIN_NUM_FMTS and formatValue use Excel's codes from 2.0.0-beta.1. The writer writes only the id for a built-in format, so files are unaffected.
| Id | Code | Id | Code |
|---|---|---|---|
| 0 | General |
18 | h:mm AM/PM |
| 1 | 0 |
19 | h:mm:ss AM/PM |
| 2 | 0.00 |
20 | h:mm |
| 3 | #,##0 |
21 | h:mm:ss |
| 4 | #,##0.00 |
22 | m/d/yy h:mm |
| 9 | 0% |
37 | #,##0_);(#,##0) |
| 10 | 0.00% |
38 | #,##0_);[Red](#,##0) |
| 11 | 0.00E+00 |
39 | #,##0.00_);(#,##0.00) |
| 12 | # ?/? |
40 | #,##0.00_);[Red](#,##0.00) |
| 13 | # ??/?? |
45 | mm:ss |
| 14 | mm-dd-yy |
46 | [h]:mm:ss |
| 15 | d-mmm-yy |
47 | mm:ss.0 |
| 16 | d-mmm |
48 | ##0.0E+0 |
| 17 | mmm-yy |
49 | @ |
Ids 5–8, 23–36, 41–44 and 50–163 are not in this table: they are reserved or locale-specific (currency, accounting, East Asian dates). The writer accepts them as numbers, but their rendering depends on the user's Excel locale. Prefer custom codes.
The style model keeps the familiar shape (font, fill, border, alignment, numFmt) but renames a few keys. The react-data-export migration guide will carry this table.
| xlsx-style / react-data-export 0.x | javascript-excel 2.0 |
|---|---|
font.sz |
font.size |
font.color: { rgb: 'FFFF0000' } |
font.color: 'FF0000', or { rgb: 'FFFF0000' } |
fill: { patternType: 'solid', fgColor: { rgb } } |
fill: 'RRGGBB', or { pattern: 'solid', fgColor } |
alignment.textRotation: 135 |
alignment.rotation: -45 |
alignment.readingOrder: 2 |
alignment.readingOrder: 'rtl' |
border: { top: { style, color } } |
same; plus 'double', which the 0.x types lacked |
numFmt: '0.00%' |
same (string = custom code); numbers are built-in ids |
color.theme: { theme, tint } |
{ theme: number, tint?: number } |
These were the open questions of the review. Each one is decided, and the sections above state the outcome as the design. The numbering is kept stable so references such as "§12 Q6" stay valid.
Q1. Node floor. Decided (2026-11-15): Node ≥ 22. engines: { "node": ">=22" }, CI on 22 and 24 (§6, §9.3). Kept here so the question numbers stay stable.
Q2. Date time zone default. Decided (2026-11-16): 'local' by default everywhere, with dateZone: 'utc' available on every read, write and CSV call. A new Date(2024, 0, 15) built in the browser shows as 15 Jan in Excel, and read-then-write round-trips in the same zone. Servers running in UTC behave the same either way.
Q3. Plain-data model vs classes. Decided (2026-11-16): plain data plus free functions (§3.1). The model can cross postMessage, and stays tree-shakable and serialisable. A fluent wrapper may come later as a separate entry if users ask for it.
Q4. Style inheritance on write. Decided (2026-11-16): the writer deep-merges defaultStyle, then column, then row, then cell into each cell's style (§3.5.7). That is what users mean by "make column B bold", and fromDataset relies on it.
Q5. Number format strings. Decided (2026-11-16): strings are never mapped to built-in ids, except 'General' to id 0 (§3.5.5). A string always renders literally, and a number always means the built-in, locale-aware format.
Q6. Shared formulas. Decided (2026-11-16), implemented in JSE-6: JSE-6 builds a small A1 reference shifter that handles relative refs, $ anchors, ranges and sheet-qualified refs, and leaves structured references and R1C1 alone. When a formula cannot be shifted safely, the cell carries the cached value only, with warning SHARED_FORMULA_UNRESOLVED (§3.4.2, §7.3).
Q7. read() return shape. Decided (2026-11-16): read() returns { workbook, warnings } (§5.2). Warnings stay visible without polluting the model, and onWarning is there for streaming UIs.
Q8. Shared, frozen style objects in reader output. Decided (2026-11-16): cells with the same xf share one Object.freezed Style (§3.5.7). That is cheap on memory and fast to compare. The docs say to copy before editing.
Q9. ISO/IEC 29500 Strict files. Decided (2026-11-16): the reader reads them by namespace mapping if JSE-6 finds that cheap. JSE-6 found it free: the tokenizer ignores namespace prefixes and relationship types are matched by their last segment, so Strict files read with no extra code (§5.2). The writer writes transitional only.
Q10. Public ZipCodec. Decided (2026-11-16): internal in 2.0, so its shape can still change (§6). It is revisited with the first real request, for example a synchronous fflate path.
Q11. _xlfn. prefixes. Decided (2026-11-16): 2.0 writes and reads formula text verbatim, and the docs explain the prefix (§3.4.2). A 2.x minor adds opt-in auto-prefixing for post-2007 functions, plus a reader option that strips the prefixes for display.
Q12. CSV BOM default. Decided (2026-11-16): bom: true for toCsvBlob, because that file goes to Excel, which needs the BOM to detect UTF-8. bom: false for toCsv, which returns a string for the program to use (§5.3).
Q13. toDataset in 2.0. Decided (2026-11-16): 2.0 ships the minimal version in §4.3: a fixed header row, deduplicated keys and null-prototype rows. Header auto-detection, multi-row header flattening, column mapping and type inference follow with react-data-import, and live in the engine. They shipped in JSE-19 as javascript-excel/import (§5.6), as decided in react-data-import's API design (2026-11-16).
Q14. Number-format rendering. Decided (2026-11-16): javascript-excel/format (§5.7) ships in 2.0, from 2.0.0-alpha.3. It was first planned for a 2.x minor; react-xlsx-viewer's design needs it for its 1.0, and Afzal moved it into 2.0 together with /import. autoWidth still measures cellText(), not formatted text.
Q15. Worker packaging. Decided (2026-11-16): the app writes a two-line worker file (§5.5). Every major bundler handles new Worker(new URL(...)) in app code. Node worker_threads support may come later.
Q16. Hyperlink scheme allowlist. Decided (2026-11-16): by default the writer allows http, https and mailto, configurable through hyperlinkSchemes (§5.1, §8). fromTable uses the same list.
Q17. fullCalcOnLoad default. Decided (2026-11-16): 'auto'. The writer sets it only when some formula has no cached value (§3.4.2), so files that carry every cached value open without a forced recalculation.
Q18. key vs path in column definitions. Decided (2026-11-16): separate fields, with key read literally and path for nested data (§4.3). react-data-export may still accept a single field and map it.
Q19. Invalid sheet names in builders. Decided (2026-11-16): fromDataset and fromTable throw INVALID_SHEET_NAME, like the core. sanitizeSheetName() is exported for callers that take names from user data (§4.6).
End goal: read, write and view every kind of Excel and CSV file. 2.0 is the first phase. Later phases add the following, and the version that delivers each is the plan as of 2026-11-16, not a commitment.
| Phase | Adds |
|---|---|
| 2.0 | xlsx read and write (cells, styles, sheet features), CSV/TSV read and write, HTML table input |
| 2.x | .xlsm / .xltx / .xltm read and write-back with their extra parts preserved; preservation of unknown parts for lossless round trips; comments and notes; data validation; conditional formatting; images (read and write) |
| 3.x | formula parser and evaluator (javascript-excel/formula), charts and drawings (read, plus their part of the render model, §5.8) |
| 4.x | legacy .xls (BIFF8) read, then write; .xlsb read; encrypted files (password, ECMA-376 agile encryption) |
The 2.x row is designed in design/2x.md (decided 2026-11-16: phases 2.1–2.5, dependency order, and what each phase will not do).
These follow from the roadmap and apply to every 2.0 change.
- The model grows by optional fields. The writer ignores fields it does not know (§3.1, §9.1), so later phases add optional fields to
Workbook,SheetandCellin minor releases. Expected additions include sheet-level comments, data validations, conditional formats, drawings and images, and Excel tables, and workbook-level preserved parts. Their names and shapes are designed in the phase that adds them; until then no 2.0 field may use those meanings. - The writer's part list is open. Parts register their content types and relationships with an internal package registry (
[Content_Types].xmldefaults and overrides,_rels/.rels,workbook.xml.rels, and a relationships builder per sheet that hyperlinks already use). A new part, such asxl/comments1.xml, a drawing or an image, adds itself without changing the existing ones. - Format detection is a table.
detectFormat(§5.2) identifies each container and format separately, andUNSUPPORTED_FORMATnames the format indetails.format. Adding a reader for.xlsor.xlsblater means adding a table entry and a reader, not removing a wall. - The reader can keep what it does not model. Its part handling is designed so that a later phase can carry unmodelled parts through to the writer for lossless write-back.
- Formula text is always preserved, verbatim with its cached value (§3.4.2), so evaluation can come later without a model change.
- Unions may widen in later phases. For example,
ErrorCodemay gain newer Excel errors such as#SPILL!once the writer can write them (§3.4). Code that switches over model unions should keep a default branch.