amendsheet 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,325 @@
+/**
+ * `code` is what to branch on. Messages are meant to be read by people and may
+ * be reworded.
+ *
+ * Two codes mean the caller passed something the library cannot use, and are
+ * the ones worth answering with a different value: `bad-reference` and
+ * `unwritable-value`. Every other code is about the file, or the runtime
+ * reading it, not a value you passed.
+ *
+ * The union is open. An existing code will not change without a major version,
+ * but new ones arrive in minor releases, because there is no knowing today
+ * every way an xlsx can be malformed. A switch over this needs a default.
+ */
+type XlsxErrorCode = 'not-a-zip' | 'missing-part' | 'unreadable-part' | 'malformed-xml'
+/** Well formed xml that says something no reader can honour. */
+ | 'invalid-content'
+/** A part decompresses to more bytes than this runtime can hold at once. */
+ | 'part-too-large' | 'bad-reference' | 'unwritable-value' | (string & {});
+/**
+ * Where a failure happened, as tightly as the throw site knows it. A cell
+ * failure carries all three of `part`, `sheet` and `reference`; a part-level
+ * failure carries `part`; only a whole-file failure with nowhere finer to point
+ * (a non-zip, a low-level parse offset already in the message) carries just
+ * `cause`. The argument is required so no throw can silently drop the location.
+ */
+interface XlsxErrorContext {
+    readonly part?: string;
+    /** The worksheet name, when a cell or sheet is the locus. */
+    readonly sheet?: string;
+    readonly reference?: string;
+    readonly cause?: unknown;
+}
+declare class XlsxError extends Error {
+    readonly code: XlsxErrorCode;
+    /** Where in the document the failure was, as tightly as it was known. */
+    readonly part: string | undefined;
+    readonly sheet: string | undefined;
+    readonly reference: string | undefined;
+    constructor(code: XlsxErrorCode, message: string, context: XlsxErrorContext);
+}
+
+/** An expression without the leading `=`, so text starting with `=` stays text. */
+interface FormulaInput {
+    readonly formula: string;
+}
+type CellInput = number | string | boolean | Date | null | FormulaInput;
+/**
+ * What a caller may still do once the worksheet is protected. Each is `true` when
+ * the action stays permitted; omitted falls to Excel's default — the format,
+ * insert, delete, sort and filter family locked, and selecting cells allowed.
+ * Cells resist editing per their own `locked` flag, which only bites here.
+ */
+interface SheetProtection {
+    readonly selectLockedCells?: boolean;
+    readonly selectUnlockedCells?: boolean;
+    readonly formatCells?: boolean;
+    readonly formatColumns?: boolean;
+    readonly formatRows?: boolean;
+    readonly insertColumns?: boolean;
+    readonly insertRows?: boolean;
+    readonly insertHyperlinks?: boolean;
+    readonly deleteColumns?: boolean;
+    readonly deleteRows?: boolean;
+    readonly sort?: boolean;
+    readonly autoFilter?: boolean;
+    readonly pivotTables?: boolean;
+    /** Editing drawing objects; Excel locks this by default when protecting. */
+    readonly editObjects?: boolean;
+    /** Editing scenarios; Excel locks this by default when protecting. */
+    readonly editScenarios?: boolean;
+}
+
+interface CellAddress {
+    /** One based, matching how references are written. */
+    readonly row: number;
+    readonly column: number;
+}
+/**
+ * Bijective base 26: there is no zero digit, so A-Z then AA, not A-Z then BA.
+ * The result may be past the last column a sheet can hold, because reading is
+ * lenient and this is the conversion reading goes through.
+ */
+declare function columnToIndex(letters: string): number;
+declare function indexToColumn(index: number): string;
+/** Scanned rather than matched: this runs once per cell. */
+declare function parseReference(reference: string): CellAddress;
+declare function formatReference(address: CellAddress): string;
+
+/** `true` and `'single'` both write a bare `<u/>`; the accounting and double
+ * variants carry a `val`. A read reports `true` for a plain single underline. */
+type UnderlineStyle = 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
+type FontVerticalAlign = 'baseline' | 'superscript' | 'subscript';
+/**
+ * A colour a cell can carry: an `RRGGBB`/`AARRGGBB` hex literal, a reference into
+ * the workbook theme's colour scheme (`tint` lightens or darkens it, -1 to 1), or
+ * an index into the legacy palette. A theme or indexed colour is a reference, not
+ * a value, so it is kept as one rather than flattened to the hex it resolves to.
+ */
+type Color = string | {
+    readonly theme: number;
+    readonly tint?: number;
+} | {
+    readonly indexed: number;
+};
+interface FontFormat {
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly strike?: boolean;
+    readonly underline?: boolean | UnderlineStyle;
+    readonly verticalAlign?: FontVerticalAlign;
+    readonly size?: number;
+    readonly color?: Color;
+    readonly name?: string;
+}
+/** ECMA-376 ST_PatternType, minus `none` (no fill) and `solid` (its own arm). */
+type PatternStyle = 'gray125' | 'gray0625' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
+interface SolidFill {
+    readonly type: 'solid';
+    /** The cell's background colour. */
+    readonly color: Color;
+}
+interface PatternFill {
+    readonly type: 'pattern';
+    readonly pattern: PatternStyle;
+    /** The pattern's foreground colour. */
+    readonly color: Color;
+    /** The colour behind the pattern; the default window background when absent. */
+    readonly background?: Color;
+}
+type FillFormat = SolidFill | PatternFill;
+/** ECMA-376 ST_BorderStyle; `none` is expressed by leaving the side out. */
+type BorderStyle = 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'mediumDashDot' | 'dashDotDot' | 'mediumDashDotDot' | 'slantDashDot';
+interface BorderSide {
+    readonly style: BorderStyle;
+    /** The side's line colour. */
+    readonly color?: Color;
+}
+interface BorderFormat {
+    readonly top?: BorderSide;
+    readonly bottom?: BorderSide;
+    readonly left?: BorderSide;
+    readonly right?: BorderSide;
+    /** Applied to all four sides; a specific side overrides it. */
+    readonly all?: BorderSide;
+}
+type HorizontalAlignment = 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
+type VerticalAlignment = 'top' | 'center' | 'bottom' | 'justify' | 'distributed';
+interface Alignment {
+    readonly horizontal?: HorizontalAlignment;
+    readonly vertical?: VerticalAlignment;
+    readonly wrapText?: boolean;
+    /** Degrees anticlockwise, 0–180; 255 stacks the text top to bottom. */
+    readonly textRotation?: number;
+    readonly indent?: number;
+}
+interface CellProtection {
+    /** Whether the cell resists editing once the sheet is protected. */
+    readonly locked?: boolean;
+    /** Whether the cell's formula is hidden once the sheet is protected. */
+    readonly hidden?: boolean;
+}
+
+type SheetState = 'visible' | 'hidden' | 'veryHidden';
+
+type CellValue = {
+    readonly kind: 'number';
+    readonly value: number;
+} | {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'boolean';
+    readonly value: boolean;
+} | {
+    readonly kind: 'error';
+    readonly value: string;
+} | {
+    readonly kind: 'empty';
+}
+/**
+ * The stored number is kept so a date can be written back unchanged. Which
+ * formats count as dates is a heuristic and may change in any release, so a
+ * cell can move between `number` and `date`; `serial` and `value` are the
+ * same double, and reading whichever is there survives that.
+ */
+ | {
+    readonly kind: 'date';
+    readonly value: Date;
+    readonly serial: number;
+};
+/**
+ * A shared formula stores its source once, on the cell that owns the range.
+ * The dependents carry a cached value and no source of their own, which is why
+ * this is a union rather than a string that is sometimes empty.
+ */
+type CellFormula = 
+/** Without the leading `=`. */
+{
+    readonly kind: 'expression';
+    readonly expression: string;
+}
+/** `master` is absent when the sheet holds no cell owning that group. */
+ | {
+    readonly kind: 'shared';
+    readonly master?: string;
+};
+interface Cell {
+    readonly address: CellAddress;
+    /**
+     * Canonical, so it always equals `formatReference(cell.address)`. The one
+     * exception is an address no column letter can name, which a lenient read
+     * accepts and which keeps the spelling the file gave it.
+     */
+    readonly reference: string;
+    readonly value: CellValue;
+    readonly formula?: CellFormula;
+    readonly numberFormat?: string;
+    /** Absent when the cell uses the default font, so carries none of its own. */
+    readonly font?: FontFormat;
+    /** Absent unless the cell has a solid fill. */
+    readonly fill?: FillFormat;
+    /** Absent unless at least one side has a border. */
+    readonly border?: BorderFormat;
+    /** Absent unless the cell sets an alignment of its own. */
+    readonly alignment?: Alignment;
+    /** Absent unless the cell sets a `locked` or `hidden` protection of its own. */
+    readonly protection?: CellProtection;
+}
+interface Worksheet {
+    readonly name: string;
+    readonly state: SheetState;
+    /**
+     * As the workbook part spells it, so a defined name or a part this library
+     * does not interpret can be matched against the sheet it refers to.
+     */
+    readonly sheetId: string;
+    /**
+     * The worksheet protection in force, in the shape `protect()` takes, or
+     * undefined when the sheet is not protected. Reflects a pending `protect()` or
+     * `unprotect()` as well as what the file was read with.
+     */
+    readonly protection?: SheetProtection;
+    /**
+     * Every cell the sheet stores. A cell that was cleared, or that carries only
+     * formatting, is still stored, and arrives with a value of `kind: 'empty'`.
+     *
+     * Each call re-reads the sheet, so a call per cell is quadratic.
+     */
+    cells(): Iterable<Cell>;
+    /** Undefined when the sheet stores nothing at that reference. */
+    cell(reference: string): Cell | undefined;
+    /**
+     * Visible to `cells()` and `cell()` immediately, written by `toBytes()`.
+     * A `numberFormat` is a format code such as `"$"#,##0.00`; without one the
+     * cell keeps the formatting it already had.
+     *
+     * Throws `XlsxError` with code `unwritable-value` for a value the format
+     * cannot hold, and records nothing when it does, so the rest of a batch of
+     * edits still writes.
+     */
+    set(reference: string, value: CellInput, options?: SetOptions): void;
+    /**
+     * Applies formatting to a cell without changing its value or formula, so a
+     * formula cell can be restyled without losing its expression. A cell that is
+     * not there yet is created empty with the formatting. Unlike `set`, this is
+     * refused by nothing: restyling a shared-formula master or a merged cell is
+     * safe, since only the cell format changes.
+     */
+    format(reference: string, options: SetOptions): void;
+    /**
+     * Turns on worksheet protection, which is what makes a cell's `locked` and
+     * `hidden` flags bite. Without `options` it matches Excel's Protect Sheet
+     * default; `options` names the actions that stay permitted. Replaces any
+     * protection the sheet already declared. Passwords are not written.
+     */
+    protect(options?: SheetProtection): void;
+    /** Removes worksheet protection, if the sheet had any. */
+    unprotect(): void;
+    /**
+     * Merges a rectangular range like `A1:B2`, joining any merges the sheet
+     * already has. Excel shows only the top-left cell's value; the others keep
+     * whatever they hold, since a merge does not clear them. Refuses a range that
+     * is not two references either side of a colon.
+     */
+    merge(range: string): void;
+    /**
+     * Sets a row's height in points, marking it a custom height so a reader keeps
+     * it. Refuses a row number below 1 or a height that is not a finite number at
+     * least zero.
+     */
+    setRowHeight(row: number, height: number): void;
+    /**
+     * Sets a column's width, in the units Excel shows, splitting a `cols` range
+     * that spans more than the column so the rest keeps its own width. The column
+     * is a letter like `A`. Refuses a width that is not a finite number at least
+     * zero.
+     */
+    setColumnWidth(column: string, width: number): void;
+}
+interface SetOptions {
+    /** A number format code, applied to the cell being written. */
+    readonly numberFormat?: string;
+    /** Font to apply, merged onto the font the cell already carries. */
+    readonly font?: FontFormat;
+    /** Solid fill colour for the cell's background. */
+    readonly fill?: FillFormat;
+    /** Borders to apply, merged onto the sides the cell already has. */
+    readonly border?: BorderFormat;
+    /** Alignment to apply, merged onto the alignment the cell already has. */
+    readonly alignment?: Alignment;
+    /** Protection to apply, merged onto the protection the cell already has. */
+    readonly protection?: CellProtection;
+}
+interface Workbook {
+    readonly sheets: readonly Worksheet[];
+    /** Undefined when no sheet has that name. Names are compared exactly. */
+    sheet(name: string): Worksheet | undefined;
+    /** Which year serials count from. A 1904 workbook is 1462 days behind. */
+    readonly epoch: 1900 | 1904;
+    /** Parts that were never interpreted are written exactly as they were read. */
+    toBytes(): Uint8Array;
+}
+declare function readWorkbook(bytes: Uint8Array): Workbook;
+
+export { type Alignment, type BorderFormat, type BorderSide, type BorderStyle, type Cell, type CellAddress, type CellFormula, type CellInput, type CellProtection, type CellValue, type Color, type FillFormat, type FontFormat, type FontVerticalAlign, type FormulaInput, type HorizontalAlignment, type PatternFill, type PatternStyle, type SetOptions, type SheetProtection, type SheetState, type SolidFill, type UnderlineStyle, type VerticalAlignment, type Workbook, type Worksheet, XlsxError, type XlsxErrorCode, type XlsxErrorContext, columnToIndex, formatReference, indexToColumn, parseReference, readWorkbook };

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+/**
+ * `code` is what to branch on. Messages are meant to be read by people and may
+ * be reworded.
+ *
+ * Two codes mean the caller passed something the library cannot use, and are
+ * the ones worth answering with a different value: `bad-reference` and
+ * `unwritable-value`. Every other code is about the file, or the runtime
+ * reading it, not a value you passed.
+ *
+ * The union is open. An existing code will not change without a major version,
+ * but new ones arrive in minor releases, because there is no knowing today
+ * every way an xlsx can be malformed. A switch over this needs a default.
+ */
+type XlsxErrorCode = 'not-a-zip' | 'missing-part' | 'unreadable-part' | 'malformed-xml'
+/** Well formed xml that says something no reader can honour. */
+ | 'invalid-content'
+/** A part decompresses to more bytes than this runtime can hold at once. */
+ | 'part-too-large' | 'bad-reference' | 'unwritable-value' | (string & {});
+/**
+ * Where a failure happened, as tightly as the throw site knows it. A cell
+ * failure carries all three of `part`, `sheet` and `reference`; a part-level
+ * failure carries `part`; only a whole-file failure with nowhere finer to point
+ * (a non-zip, a low-level parse offset already in the message) carries just
+ * `cause`. The argument is required so no throw can silently drop the location.
+ */
+interface XlsxErrorContext {
+    readonly part?: string;
+    /** The worksheet name, when a cell or sheet is the locus. */
+    readonly sheet?: string;
+    readonly reference?: string;
+    readonly cause?: unknown;
+}
+declare class XlsxError extends Error {
+    readonly code: XlsxErrorCode;
+    /** Where in the document the failure was, as tightly as it was known. */
+    readonly part: string | undefined;
+    readonly sheet: string | undefined;
+    readonly reference: string | undefined;
+    constructor(code: XlsxErrorCode, message: string, context: XlsxErrorContext);
+}
+
+/** An expression without the leading `=`, so text starting with `=` stays text. */
+interface FormulaInput {
+    readonly formula: string;
+}
+type CellInput = number | string | boolean | Date | null | FormulaInput;
+/**
+ * What a caller may still do once the worksheet is protected. Each is `true` when
+ * the action stays permitted; omitted falls to Excel's default — the format,
+ * insert, delete, sort and filter family locked, and selecting cells allowed.
+ * Cells resist editing per their own `locked` flag, which only bites here.
+ */
+interface SheetProtection {
+    readonly selectLockedCells?: boolean;
+    readonly selectUnlockedCells?: boolean;
+    readonly formatCells?: boolean;
+    readonly formatColumns?: boolean;
+    readonly formatRows?: boolean;
+    readonly insertColumns?: boolean;
+    readonly insertRows?: boolean;
+    readonly insertHyperlinks?: boolean;
+    readonly deleteColumns?: boolean;
+    readonly deleteRows?: boolean;
+    readonly sort?: boolean;
+    readonly autoFilter?: boolean;
+    readonly pivotTables?: boolean;
+    /** Editing drawing objects; Excel locks this by default when protecting. */
+    readonly editObjects?: boolean;
+    /** Editing scenarios; Excel locks this by default when protecting. */
+    readonly editScenarios?: boolean;
+}
+
+interface CellAddress {
+    /** One based, matching how references are written. */
+    readonly row: number;
+    readonly column: number;
+}
+/**
+ * Bijective base 26: there is no zero digit, so A-Z then AA, not A-Z then BA.
+ * The result may be past the last column a sheet can hold, because reading is
+ * lenient and this is the conversion reading goes through.
+ */
+declare function columnToIndex(letters: string): number;
+declare function indexToColumn(index: number): string;
+/** Scanned rather than matched: this runs once per cell. */
+declare function parseReference(reference: string): CellAddress;
+declare function formatReference(address: CellAddress): string;
+
+/** `true` and `'single'` both write a bare `<u/>`; the accounting and double
+ * variants carry a `val`. A read reports `true` for a plain single underline. */
+type UnderlineStyle = 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
+type FontVerticalAlign = 'baseline' | 'superscript' | 'subscript';
+/**
+ * A colour a cell can carry: an `RRGGBB`/`AARRGGBB` hex literal, a reference into
+ * the workbook theme's colour scheme (`tint` lightens or darkens it, -1 to 1), or
+ * an index into the legacy palette. A theme or indexed colour is a reference, not
+ * a value, so it is kept as one rather than flattened to the hex it resolves to.
+ */
+type Color = string | {
+    readonly theme: number;
+    readonly tint?: number;
+} | {
+    readonly indexed: number;
+};
+interface FontFormat {
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly strike?: boolean;
+    readonly underline?: boolean | UnderlineStyle;
+    readonly verticalAlign?: FontVerticalAlign;
+    readonly size?: number;
+    readonly color?: Color;
+    readonly name?: string;
+}
+/** ECMA-376 ST_PatternType, minus `none` (no fill) and `solid` (its own arm). */
+type PatternStyle = 'gray125' | 'gray0625' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
+interface SolidFill {
+    readonly type: 'solid';
+    /** The cell's background colour. */
+    readonly color: Color;
+}
+interface PatternFill {
+    readonly type: 'pattern';
+    readonly pattern: PatternStyle;
+    /** The pattern's foreground colour. */
+    readonly color: Color;
+    /** The colour behind the pattern; the default window background when absent. */
+    readonly background?: Color;
+}
+type FillFormat = SolidFill | PatternFill;
+/** ECMA-376 ST_BorderStyle; `none` is expressed by leaving the side out. */
+type BorderStyle = 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'mediumDashDot' | 'dashDotDot' | 'mediumDashDotDot' | 'slantDashDot';
+interface BorderSide {
+    readonly style: BorderStyle;
+    /** The side's line colour. */
+    readonly color?: Color;
+}
+interface BorderFormat {
+    readonly top?: BorderSide;
+    readonly bottom?: BorderSide;
+    readonly left?: BorderSide;
+    readonly right?: BorderSide;
+    /** Applied to all four sides; a specific side overrides it. */
+    readonly all?: BorderSide;
+}
+type HorizontalAlignment = 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
+type VerticalAlignment = 'top' | 'center' | 'bottom' | 'justify' | 'distributed';
+interface Alignment {
+    readonly horizontal?: HorizontalAlignment;
+    readonly vertical?: VerticalAlignment;
+    readonly wrapText?: boolean;
+    /** Degrees anticlockwise, 0–180; 255 stacks the text top to bottom. */
+    readonly textRotation?: number;
+    readonly indent?: number;
+}
+interface CellProtection {
+    /** Whether the cell resists editing once the sheet is protected. */
+    readonly locked?: boolean;
+    /** Whether the cell's formula is hidden once the sheet is protected. */
+    readonly hidden?: boolean;
+}
+
+type SheetState = 'visible' | 'hidden' | 'veryHidden';
+
+type CellValue = {
+    readonly kind: 'number';
+    readonly value: number;
+} | {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'boolean';
+    readonly value: boolean;
+} | {
+    readonly kind: 'error';
+    readonly value: string;
+} | {
+    readonly kind: 'empty';
+}
+/**
+ * The stored number is kept so a date can be written back unchanged. Which
+ * formats count as dates is a heuristic and may change in any release, so a
+ * cell can move between `number` and `date`; `serial` and `value` are the
+ * same double, and reading whichever is there survives that.
+ */
+ | {
+    readonly kind: 'date';
+    readonly value: Date;
+    readonly serial: number;
+};
+/**
+ * A shared formula stores its source once, on the cell that owns the range.
+ * The dependents carry a cached value and no source of their own, which is why
+ * this is a union rather than a string that is sometimes empty.
+ */
+type CellFormula = 
+/** Without the leading `=`. */
+{
+    readonly kind: 'expression';
+    readonly expression: string;
+}
+/** `master` is absent when the sheet holds no cell owning that group. */
+ | {
+    readonly kind: 'shared';
+    readonly master?: string;
+};
+interface Cell {
+    readonly address: CellAddress;
+    /**
+     * Canonical, so it always equals `formatReference(cell.address)`. The one
+     * exception is an address no column letter can name, which a lenient read
+     * accepts and which keeps the spelling the file gave it.
+     */
+    readonly reference: string;
+    readonly value: CellValue;
+    readonly formula?: CellFormula;
+    readonly numberFormat?: string;
+    /** Absent when the cell uses the default font, so carries none of its own. */
+    readonly font?: FontFormat;
+    /** Absent unless the cell has a solid fill. */
+    readonly fill?: FillFormat;
+    /** Absent unless at least one side has a border. */
+    readonly border?: BorderFormat;
+    /** Absent unless the cell sets an alignment of its own. */
+    readonly alignment?: Alignment;
+    /** Absent unless the cell sets a `locked` or `hidden` protection of its own. */
+    readonly protection?: CellProtection;
+}
+interface Worksheet {
+    readonly name: string;
+    readonly state: SheetState;
+    /**
+     * As the workbook part spells it, so a defined name or a part this library
+     * does not interpret can be matched against the sheet it refers to.
+     */
+    readonly sheetId: string;
+    /**
+     * The worksheet protection in force, in the shape `protect()` takes, or
+     * undefined when the sheet is not protected. Reflects a pending `protect()` or
+     * `unprotect()` as well as what the file was read with.
+     */
+    readonly protection?: SheetProtection;
+    /**
+     * Every cell the sheet stores. A cell that was cleared, or that carries only
+     * formatting, is still stored, and arrives with a value of `kind: 'empty'`.
+     *
+     * Each call re-reads the sheet, so a call per cell is quadratic.
+     */
+    cells(): Iterable<Cell>;
+    /** Undefined when the sheet stores nothing at that reference. */
+    cell(reference: string): Cell | undefined;
+    /**
+     * Visible to `cells()` and `cell()` immediately, written by `toBytes()`.
+     * A `numberFormat` is a format code such as `"$"#,##0.00`; without one the
+     * cell keeps the formatting it already had.
+     *
+     * Throws `XlsxError` with code `unwritable-value` for a value the format
+     * cannot hold, and records nothing when it does, so the rest of a batch of
+     * edits still writes.
+     */
+    set(reference: string, value: CellInput, options?: SetOptions): void;
+    /**
+     * Applies formatting to a cell without changing its value or formula, so a
+     * formula cell can be restyled without losing its expression. A cell that is
+     * not there yet is created empty with the formatting. Unlike `set`, this is
+     * refused by nothing: restyling a shared-formula master or a merged cell is
+     * safe, since only the cell format changes.
+     */
+    format(reference: string, options: SetOptions): void;
+    /**
+     * Turns on worksheet protection, which is what makes a cell's `locked` and
+     * `hidden` flags bite. Without `options` it matches Excel's Protect Sheet
+     * default; `options` names the actions that stay permitted. Replaces any
+     * protection the sheet already declared. Passwords are not written.
+     */
+    protect(options?: SheetProtection): void;
+    /** Removes worksheet protection, if the sheet had any. */
+    unprotect(): void;
+    /**
+     * Merges a rectangular range like `A1:B2`, joining any merges the sheet
+     * already has. Excel shows only the top-left cell's value; the others keep
+     * whatever they hold, since a merge does not clear them. Refuses a range that
+     * is not two references either side of a colon.
+     */
+    merge(range: string): void;
+    /**
+     * Sets a row's height in points, marking it a custom height so a reader keeps
+     * it. Refuses a row number below 1 or a height that is not a finite number at
+     * least zero.
+     */
+    setRowHeight(row: number, height: number): void;
+    /**
+     * Sets a column's width, in the units Excel shows, splitting a `cols` range
+     * that spans more than the column so the rest keeps its own width. The column
+     * is a letter like `A`. Refuses a width that is not a finite number at least
+     * zero.
+     */
+    setColumnWidth(column: string, width: number): void;
+}
+interface SetOptions {
+    /** A number format code, applied to the cell being written. */
+    readonly numberFormat?: string;
+    /** Font to apply, merged onto the font the cell already carries. */
+    readonly font?: FontFormat;
+    /** Solid fill colour for the cell's background. */
+    readonly fill?: FillFormat;
+    /** Borders to apply, merged onto the sides the cell already has. */
+    readonly border?: BorderFormat;
+    /** Alignment to apply, merged onto the alignment the cell already has. */
+    readonly alignment?: Alignment;
+    /** Protection to apply, merged onto the protection the cell already has. */
+    readonly protection?: CellProtection;
+}
+interface Workbook {
+    readonly sheets: readonly Worksheet[];
+    /** Undefined when no sheet has that name. Names are compared exactly. */
+    sheet(name: string): Worksheet | undefined;
+    /** Which year serials count from. A 1904 workbook is 1462 days behind. */
+    readonly epoch: 1900 | 1904;
+    /** Parts that were never interpreted are written exactly as they were read. */
+    toBytes(): Uint8Array;
+}
+declare function readWorkbook(bytes: Uint8Array): Workbook;
+
+export { type Alignment, type BorderFormat, type BorderSide, type BorderStyle, type Cell, type CellAddress, type CellFormula, type CellInput, type CellProtection, type CellValue, type Color, type FillFormat, type FontFormat, type FontVerticalAlign, type FormulaInput, type HorizontalAlignment, type PatternFill, type PatternStyle, type SetOptions, type SheetProtection, type SheetState, type SolidFill, type UnderlineStyle, type VerticalAlignment, type Workbook, type Worksheet, XlsxError, type XlsxErrorCode, type XlsxErrorContext, columnToIndex, formatReference, indexToColumn, parseReference, readWorkbook };