sheetfence

read and write xlsx in pure typescript. zero deps, no native build.

npm i sheetfence

why

the package most projects use for xlsx has millions of weekly downloads, and its newest version on the npm registry is from march 2022. two advisories are open against it there, and neither has a fixed release on npm — the maintainers moved to their own cdn and did not publish the patch back. so scanners keep reporting it and there is no upgrade to run. the usual fallback was last published in october 2023 and has hundreds of open issues with issue creation turned off.

sheetfence fills that gap, and the two reported problem classes are ruled out by design rather than patched:

• untrusted keys stay keys. every map built from file content is created with Object.create(null), so a column header named __proto__ is an ordinary property and never reaches Object.prototype.
• parsing is linear. there is no regex anywhere in the parser. it is a hand written character scanner, so pathological input cannot make it backtrack.

use

import { read, write, toObjects } from 'sheetfence'
import { readFileSync, writeFileSync } from 'node:fs'

const book = read(readFileSync('report.xlsx'))

book.names                    // ['Sheet1', 'Q2']
book.sheet('Q2').rows         // [['name', 'qty'], ['widget', 42]]
toObjects(book.sheet('Q2'))   // [{ name: 'widget', qty: 42 }]

writeFileSync('out.xlsx', write([
  { name: 'results', rows: [['name', 'qty'], ['widget', 42, new Date()]] }
]))

values come back as string | number | boolean | Date | null. dates are real Date objects — the serial is decoded using the number format, and the 1900 leap year quirk is handled on both sides of the gap, so 1900-03-01 reads back as 1900-03-01 and not a day out.

limits on untrusted input

a xlsx is a zip full of xml, so a reader has to be careful before any spreadsheet parsing starts. these all raise a typed error instead of being followed:

| input | result | |---|---| | an entry name that escapes the archive root | ZipError BAD_NAME | | an entry whose declared size is implausible | ZipError TOO_LARGE | | a document defining its own xml entities | never expanded, kept as text | | a document referencing an external file | never fetched | | xml nested thousands of levels deep | XmlError | | a single cell declared at the far corner of the grid | SheetError TOO_BIG | | an encrypted archive | ZipError ENCRYPTED |

the budgets are yours to set:

read(buf, {
  maxCells: 5_000_000,      // grid size
  maxTotalBytes: 256 << 20, // after decompression
  maxEntries: 4096
})

csv export

import { toCsv } from 'sheetfence'
toCsv(book.sheet(0))

a cell beginning =, +, - or @ is treated as a formula by excel and sheets when the csv is opened. those cells get a leading ' so the text stays text. pass { safe: false } if the output is going to a machine.

api

• read(bytes, opts?) → Book
• write(sheets) → Uint8Array
• book.sheet(nameOrIndex) → Sheet | undefined
• book.names → string[]
• toObjects(sheet, opts?) → rows keyed by the header row
• fromObjects(rows) → a grid, header row first
• toCsv(sheet, opts?) → string
• parseRef / makeRef / colName — A1 notation
• fromSerial / toSerial — excel dates

errors are SheetError, ZipError, XmlError and WriteError, each with a code so you can branch without matching on messages.

runs anywhere

the only import is node:zlib. no node-gyp, no prebuilt binaries, no postinstall step. that means it also works where native addons cannot — cloudflare workers, deno, bun and bare.

correctness

45 tests, 17 of them covering the input handling above.

the ones that matter most are the interop tests: openpyxl reads what we write, and we read what openpyxl writes, including shared string tables, which our own writer does not emit — so a round trip alone would never exercise that path. that test caught a real bug where our content types were malformed in a way only an outside reader could notice.

what it does not do

no formulas, charts, pivot tables, macros or formatting. it reads and writes cell values. if you need excel, use excel.

license

MIT