Main Navigation Guide API Playground Changelog GitHub

Appearance

Sidebar Navigation

Start

Getting started

Writing a workbook

Reading a workbook

Styles and number formats

Structure: merges, widths, panes and tables

Streaming

Errors

In the browser

Migrating from ExcelJS

Under the hood

Architecture

Agent correctness playbook

API reference

Addresses & ranges

Autofilter

Axis Handle

Cell

Cell values

Color Resolution

Column

Comment Thread

Conditional Formatting

CSV

Csv Errors

Customui Errors

Customui Ribbon

Data Validation

Date

Errors

Grid limits

Grid Shift

Hyperlink

Images

Opc Errors

Opc Read Options

Page Setup

Pivot tables

Preserved

Protection

Range

Reading .xlsx

Row

Streaming reads

Streaming writes

Styles

Table Style

Tables

Text metrics

Theme

Vba Errors

Vba Project

Vba Project Editor

Workbook

Workbook Styles

Worksheet

Worksheet Pictures

Writing .xlsx

Xlsb Errors

Xlsb Read

Xlsx Edit Vba

Xlsx Errors

Xlsx Theme Xml

Xml Errors

Decisions

Decision records

ADR 0001: Rewrite runtime and toolchain, run .ts directly, defer the bundler

ADR 0002: Microsoft OpenXmlValidator as an external conformance oracle

ADR 0003: Zip container is fflate; the write path emits XML directly

ADR 0004: The XML read path is a lean, hand-written SAX pull parser

ADR 0005: WorksheetModel stays a semantic value; attached parts are out of scope

ADR 0006: API docs generated from the types, not a docs framework

ADR 0007: Spec reference, vendored OOXML schemas plus Microsoft Learn MCP

ADR 0008: Upgrade to TypeScript 6; hold at 6 (not 7) until the printer API ports

ADR 0009: Tighten the lint/type gates where free; decline isolatedDeclarations

ADR 0010: Make the correctness net easy for agents to dispatch

ADR 0011: Type-check the harness, migrating test/ and scripts/ to strict .ts

ADR 0012: Three tiers of correctness evidence; round-trip proves consistency, not conformance

ADR 0013: Excel Desktop is an automatable Tier-3 oracle for state-observable behavior

ADR 0014: Charts, vector shapes, slicers, and form controls stay round-trip-only for 1.0

ADR 0015: Package name, SemVer, and the first published version

ADR 0016: The VBA project is readable through a typed view; authoring stays deferred

ADR 0017: VBA authoring is in scope; the consumer gate is lifted

ADR 0018: Editing an existing macro's source is done by splicing the original .bin, not re-synthesizing it

ADR 0019: VBA authoring needs real, compiled p-code; the "recompile cookie" premise is retracted

ADR 0020: The customUI ribbon is readable through a typed view; authoring stays deferred

ADR 0021: The VBA project signature is readable as presence, not verified as validity

ADR 0022: Verification is one cached, parallel entrypoint

ADR 0023: Seven subpath entry points, disjoint by construction, with the error taxonomy as its own face

ADR 0024: Async is one writer, not a mirrored pair

ADR 0025: The workbook default font is declared, not assumed

ADR 0026: Releasing is a GitHub release, and npm follows with no credential

ADR 0027: Dependencies are updated by a bot, and CI is the reviewer

ADR 0028: Move to TypeScript 7; the compiler API scripts move to unstable/

ADR 0029: Toolchain standup, Biome for lint/format, node --test kept, tsc for type tests

ADR 0030: src/io/xlsx/ stays flat; the read/write directory split is rejected

ADR 0031: The emitted declarations are typechecked too; two more gate flags go on

ADR 0032: Package output is reproducible, with entry timestamps pinned rather than clocked

ADR 0033: The OOXML oracle is a shared package, not a repo-owned .NET tool

ADR 0034: The schema reference is a queryable graph, not a vendored XSD dump

ADR 0035: Coverage is the union of both suites, measured with node's own implementation

ADR 0036: oxlint and oxfmt replace Biome, and the type-aware rules come from tsgolint

ADR 0037: Every tree the linter type-checks has a tsconfig.json the linter can find

ADR 0038: The corpus keeps its untyped boundary, and it costs six rules rather than sixteen

ADR 0039: The website is generated from the docs tree, and drift is a build error

ADR 0040: The browser boundary is an entry point, and a gate walks the graph to prove it

ADR 0041: One date-format vocabulary, and it is the spreadsheet's

ADR 0042: A hyperlink belongs to the sheet, not to a cell's value

Evidence

Behaviour spec notes

A splice must not push geometry off the grid

The image source contract: buffer/path, with URLs handled deliberately

Async-iterable reader types must compile against a declared minimum

File writes must be atomic and never leave a zero-byte or partial file

AutoFilter should support suppressing the dropdown button on chosen columns

Bounded memory when reading and writing workbooks

Serialization must be iterative, not deeply recursive, so large data cannot overflow the stack

Browser-safe I/O boundary

Streaming read from a seekable source (browser Blob / random-access bytes)

The streaming workbook writer must work in the browser over a platform-neutral sink

What number-format code to report for locale-dependent builtin date format ids

Cell full-address descriptor: row and col are numbers

A cell should report its role in a merge

Cell "padding": be honest about indent, don't invent unroundtrippable padding

A unified accessor for a cell's raw and displayed value

Charts survive a load-modify-save of a template

A number format declared on a column must reach that column's cells

Column definitions must be a partial write-side type, distinct from the read-side column

Column keys and a write-then-read round-trip

Column-level value type

A cell comment can be given an explicit size

Conditional formatting: string-literal quoting and per-cell expression translation

Copy rows/ranges across worksheets preserving styles, formulas, and merges

CSV write must make multi-sheet selection explicit, not silently drop sheets

CSV write must stream into a sink with incremental flush and backpressure

Custom table styles: a cross-part claim, and what may be refused

Dark Mode repaints authored cell colours, and no encoding of a colour opts out

Data-validation prompt/error message length limits must not silently corrupt the file

Data validation scope when inserting rows into a table

Data-bar colors and "ignored errors" suppression on write

Writing a JS Date must follow a documented, configurable timezone projection

Declarative multi-level (nested) column headers

The default font must be honored, not assumed, when computing column widths

A document-wide default font must be settable once, per workbook (and per worksheet)

A defined name may hold an arbitrary formula, not only a range

Defined names must be able to carry a per-sheet scope

Defined names must tolerate tokens that are not cell references

Native DrawingML shapes must be authorable, enumerable, and round-trip-preserved

Duplicate a contiguous block of rows, N copies at a time

Duplicating a row carries and translates formulas

Read and write embedded charts

The primary import must construct correctly on every toolchain

Producing .xlsx files Excel opens without a "repair" prompt

External-workbook reference formulas need package machinery, not a magic string

A deletion-safe accessor for the first existing worksheet

Read-modify-write of a foreign-generated file must stay valid

Tolerate the row-number quirks foreign generators emit that Excel accepts

Form controls: preserve on round-trip, model where feasible

A formula-cell value must be constructible from just the formula (no mandatory date-system flag)

Formula recalculation: the library is not a formula engine

A frozen pane's header ink can go missing until the cell is clicked, and no package can prevent it

A row's height and a column's width are bounded by Excel, not by the schema

Authoring images in page headers and footers

AutoFilter on a table is explicitly controllable, independent of the header row

Author a rich-text cell value from an inline-styled markup fragment

Hyperlink cells get the built-in link appearance by default

Image accessibility: title, alt-text description, and a decorative flag

Authoring an image anchor: rotation, explicit extent, and sub-cell offset are first-class inputs

Image anchor offsets must derive from real column/row geometry

Adding an image by filesystem path is a Node-only capability

Carrying image-bearing content between workbooks must copy the media or fail loudly

Center an image within a cell or range, preserving aspect ratio

Distinguish a cell-embedded ("in-cell") image from a floating anchored drawing

Reading in-cell ("Place in Cell") rich-value images

Indexed-palette colors must resolve to a concrete color, not surface a raw index

Positional accessors must make their 1-based vs 0-based convention unambiguous

Internal (in-workbook) hyperlinks must be portable across consumers

Large-workbook writes must be linear-time and bounded-memory

A single lean ZIP container layer over native DEFLATE

Inline list validation silently breaks past the 255-character formula limit

The load API must accept ArrayBuffer and typed arrays, not only Node Buffer

Merged-cell registration must scale linearly, not quadratically

The dependency tree must stay small, current, and audit-clean

Format loaders behind tree-shakeable entry points

A workbook must support multiple pivot tables (including from one shared source)

Multi-select dropdown validation: a request the format cannot natively satisfy

OOXML reading must be namespace-agnostic, BOM-tolerant, and order-independent

Native iteration protocol on collection-shaped API objects

Column keys must address nested properties of row objects

Importing the library must not mutate global built-ins

CSP-safe: no eval, no new Function, no Function(...)

Literal letter runs in a number format: quote them so a consumer cannot mis-tokenize them

The filesystem-path reader is Node-only and must fail clearly elsewhere

Phonetic guides (furigana) survive a read and a save

PivotTable per-field aggregation metrics (Count and the rest, not just Sum)

PivotTable support for multiple value fields and the "Values" axis

PivotTable page fields (report filters)

A pivot table can preserve the worksheet's column widths instead of its style's sizing

Pivot table preservation and support

Preserve drawing shapes (autoshapes, text boxes) on round-trip

Granting sort/AutoFilter on a protected sheet needs an unlocked window, not just the flag

The public type surface must expose every real runtime accessor and option

Public type surface must be portable across Node and browser/bundler tsconfigs

Published types must resolve for TypeScript, ESM, and CommonJS consumers

Render a cell range as a styled image ("copy as picture")

Reading cell comments backed by a legacy VML drawing must terminate

How rich text composes with cell alignment: alignment is cell-level, runs are character-level

The writer must not crash on a malformed rich-text-shaped cell value

A rich-text run's font is all-or-nothing: it inherits nothing from its cell

The reader must not crash on a foreign-shaped rich-text shared string

A read→write round-trip must preserve row/column visibility

Row iteration must support terminating early without throwing

A row's value collection must not carry a phantom leading empty slot

A row with no stated height is auto-fitted on open, and the auto-fit saturates

Apply a style to a whole cell range in one call

Sheet-protection password hashing and cross-application compatibility

The sheet-values accessor returns row values, not Row objects

The sheetPr child order: outlinePr must precede pageSetUpPr

Sheet-view boolean flags, and showFormulas is not formula-bar visibility

Serialize a single worksheet part, and swap a sheet into an existing package

Sort worksheet rows by one or more key columns

Excel decodes xHHHH in cell text, in a threaded comment, and in a print header, in one left-to-right pass

The library's writable streams must honor the Node stream contract (pipe returns the destination)

Streaming CSV reader: rows as an async iterable

Remove an uncommitted worksheet from the streaming writer

The streaming writer must emit a valid ZIP (ZIP64 when large) and reject over-limit row counts

Streaming read of date cells: cached/compact styles

Streaming read must emit every worksheet, including large sheet counts

Streaming read-modify-write: edit a large template without materializing it in memory

Streaming read must resolve shared strings regardless of part order

Streaming read must resolve styles before emitting cells, and must not stall

The streaming reader surfaces merged-cell ranges

The streaming reader must release its temporary resources when iteration is abandoned early

Streaming reader options: styles caching, its default, and the "dates are a style" footgun

Embedding images in the streaming write path

Streaming write memory, and the shared-strings tradeoff

Streaming write must release committed-row memory per worksheet

Streaming writer must deliver bytes to the sink incrementally

Bounded memory in the streaming writer: row commit must expose backpressure

Declaring a table in the streaming workbook writer

The streaming writer must honor sheet views assigned after a worksheet is created

Streaming writer: row/column splice on the worksheet

The streaming writer's worksheet type is a narrowed, forward-only reflection

Value-based style deduplication on write, and merging a style onto a cell

A table column definition should accept an inline display width

A table accessor must return a usable table handle, not a nested wrapper

Template placeholder replacement: fill a design template from a data context

Authoring a theme generates over the existing one, and stops at the format scheme

theme="n" does not index the order the theme part is written in

Modern threaded comments, and why we own their legacy fallback

A "time" data-validation type, parallel to the date type

Streaming and buffered I/O should be one implementation, not two

Reject non-.xlsx input with a clear, typed error, not raw zip internals

Read and write workbooks over WHATWG Web Streams (edge/serverless runtimes)

Whole-column data-validation ranges must not explode into per-cell state

Whole-file password encryption of workbook documents

Authoring workbook-level structure protection

Duplicating and merging worksheets must be a safe, first-class, deep-copy operation

The worksheet column collection must be honest about mutability

Worksheet-default cell protection: unlock all cells without per-cell style bloat

A worksheet-level (and workbook-level) default style, mapped to OOXML defaulting

Worksheet enumeration and lookup must work on foreign-generated files

A range-of-columns accessor, symmetric with the row-range accessor

Robust duplicate-worksheet-name detection

Worksheet paper size: complete type coverage and custom dimensions

Export a worksheet (or range) to an HTML fragment

Writing to an in-memory buffer must return an honestly-typed binary container

Reading and writing the binary XLSB format

Preserve VBA on round-trip of macro-enabled workbooks (.xlsm)

Control automatic date detection when reading xlsx

On this page

Axis Handle

`AxisHandle`

_class

ts

class AxisHandle {

}

Edit this page on GitHub

Pager

Previous pageAutofilter

Next pageCell

Released under the MIT License.

Copyright (c) shbernal

Axis Handle ​

AxisHandle ​

Axis Handle

`AxisHandle`