@vectojs/numera-xlsx

Guarded XLSX import and export for the Numera family.

@vectojs/numera-xlsx converts between environment-neutral Uint8Array XLSX archives and the pure @vectojs/numera-core workbook model. It owns OOXML mapping, resource limits, ZIP preflight, and Excel unit conversion; it has no Canvas, DOM, filesystem, CLI, or MCP responsibility.

Status

The package is under initial implementation and is not published yet. Its first release will expose asynchronous encode/decode functions after fixture, security, and browser verification.

encodeXlsx(workbook) is now available for ordered Core workbooks. It maps sparse literals, formulas with cached results, supported cell formats, logical axis defaults/overrides, and active-sheet intent into standard OOXML without iterating the whole logical grid.

decodeXlsx(bytes, { limits }) preflights the archive before parsing, then imports compatible cells, basic formats, sparse dimensions, sheet order, and active tab into a Core workbook. Unsupported rich text, non-#REF! Excel errors, and text that Core cannot represent without a literal escape fail with stable typed errors rather than being silently changed.

Archive safety

preflightXlsxArchive(bytes, limits) validates the classic ZIP central directory without decompressing workbook content. It rejects malformed, multi-disk, ZIP64, encrypted, oversized, and excessive-entry archives through stable XlsxError codes before bytes reach the OOXML parser.

Default limits allow a 64 MiB input, 4,096 archive entries, and 512 MiB of declared expanded content. DEFAULT_XLSX_LIMITS also defines post-parse sheet, axis, and populated-cell bounds for the decoder. Callers can derive a complete limit object with resolveXlsxLimits(overrides).

Development

bun install --frozen-lockfile
just verify

Release

Public interface changes require a Changeset. Publishing is triggered only by an exact @vectojs/numera-xlsx@<version> Git tag after CI and CodeQL pass.

License

MIT © 2026 Xuepoo