@alosha/xlsx 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,825 @@
+declare enum CellType {
+    Null = 0,
+    Number = 1,
+    String = 2,
+    Boolean = 3,
+    Date = 4,
+    Error = 5,
+    RichText = 6,
+    Hyperlink = 7,
+    Formula = 8,
+    Merge = 9,
+    SharedString = 10
+}
+declare enum FormulaType {
+    None = 0,
+    Master = 1,
+    Shared = 2
+}
+type ErrorCode = "#N/A" | "#REF!" | "#NAME?" | "#DIV/0!" | "#NULL!" | "#VALUE!" | "#NUM!";
+
+interface Color {
+    argb?: string;
+    theme?: number;
+    indexed?: number;
+}
+interface Font {
+    name?: string;
+    size?: number;
+    family?: number;
+    scheme?: "minor" | "major" | "none";
+    charset?: number;
+    color?: Color;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean | "none" | "single" | "double" | "singleAccounting" | "doubleAccounting";
+    vertAlign?: "superscript" | "subscript";
+    strike?: boolean;
+    outline?: boolean;
+}
+type FillPattern = "none" | "solid" | "darkVertical" | "darkHorizontal" | "darkGrid" | "darkTrellis" | "darkDown" | "darkUp" | "lightVertical" | "lightHorizontal" | "lightGrid" | "lightTrellis" | "lightDown" | "lightUp" | "darkGray" | "mediumGray" | "lightGray" | "gray125" | "gray0625";
+interface GradientStop {
+    position: number;
+    color: Color;
+}
+type Fill = {
+    type: "pattern";
+    pattern: FillPattern;
+    fgColor?: Color;
+    bgColor?: Color;
+} | {
+    type: "gradient";
+    gradient: "angle";
+    degree: number;
+    stops: GradientStop[];
+} | {
+    type: "gradient";
+    gradient: "path";
+    center: {
+        left: number;
+        top: number;
+    };
+    stops: GradientStop[];
+};
+type BorderStyle = "thin" | "dotted" | "hair" | "medium" | "double" | "thick" | "dashed" | "dashDot" | "dashDotDot" | "slantDashDot" | "mediumDashed" | "mediumDashDotDot" | "mediumDashDot";
+interface Border {
+    style?: BorderStyle;
+    color?: Color;
+}
+interface BorderDiagonal extends Border {
+    up?: boolean;
+    down?: boolean;
+}
+interface Borders {
+    top?: Border;
+    left?: Border;
+    bottom?: Border;
+    right?: Border;
+    diagonal?: BorderDiagonal;
+}
+interface Alignment {
+    horizontal?: "left" | "center" | "right" | "fill" | "justify" | "centerContinuous" | "distributed";
+    vertical?: "top" | "middle" | "bottom" | "distributed" | "justify";
+    wrapText?: boolean;
+    shrinkToFit?: boolean;
+    indent?: number;
+    readingOrder?: "rtl" | "ltr";
+    textRotation?: number | "vertical";
+}
+interface Protection {
+    locked?: boolean;
+    hidden?: boolean;
+}
+interface Style {
+    numFmt?: string;
+    font?: Font;
+    alignment?: Alignment;
+    protection?: Protection;
+    border?: Borders;
+    fill?: Fill;
+}
+/**
+ * Resolve a cell's effective style: row default and column default merged field-by-field — row
+ * wins over column — then the cell's own style overrides both (see docs/API-AUDIT.md §4's
+ * `_mergeStyle` precedence note). `fill` is a discriminated union so it is replaced wholesale
+ * rather than merged (mixing a `pattern` fill's fields with a `gradient` fill's would be
+ * incoherent). Returns a new object; never mutates any input.
+ */
+declare function resolveCellStyle(rowStyle?: Style, colStyle?: Style, cellStyle?: Style): Style;
+
+interface RichTextRun {
+    text: string;
+    font?: Font;
+}
+interface RichText {
+    richText: RichTextRun[];
+}
+interface Hyperlink {
+    text: string;
+    hyperlink: string;
+    tooltip?: string;
+}
+interface CellError {
+    error: ErrorCode;
+}
+interface CellFormula {
+    formula?: string;
+    sharedFormula?: string;
+    ref?: string;
+    shareType?: "shared" | "array";
+    result?: number | string | boolean | Date | CellError;
+}
+/** What callers pass to `cell.value = …` and read back. */
+type CellValue = null | number | string | boolean | Date | CellError | RichText | Hyperlink | CellFormula;
+/** Internal normalized storage on the cell model (discriminated on `type`). */
+type StoredValue = {
+    type: CellType.Null;
+} | {
+    type: CellType.Number;
+    value: number;
+} | {
+    type: CellType.String;
+    value: string;
+} | {
+    type: CellType.Boolean;
+    value: boolean;
+} | {
+    type: CellType.Date;
+    value: Date;
+} | {
+    type: CellType.Error;
+    value: CellError;
+} | {
+    type: CellType.RichText;
+    value: RichText;
+} | {
+    type: CellType.Hyperlink;
+    value: Hyperlink;
+} | {
+    type: CellType.Formula;
+    value: CellFormula;
+} | {
+    type: CellType.Merge;
+    master: string;
+} | {
+    type: CellType.SharedString;
+    value: number;
+};
+/**
+ * Duck-type a `CellValue` into a `CellType`, mirroring ExcelJS's `Value.getType` check order:
+ * null → string → number → boolean → date → hyperlink (`text`&`hyperlink`) → formula
+ * (`formula`|`sharedFormula`) → richText → error. Throws {@link InvalidCellValueError} for
+ * anything else.
+ */
+declare function detectType(v: CellValue): CellType;
+/** Normalizes an ergonomic `CellValue` into its discriminated `StoredValue` form. */
+declare function toStored(v: CellValue): StoredValue;
+/**
+ * Recovers the ergonomic `CellValue` from a `StoredValue`. `Merge` (resolved via the master cell)
+ * and `SharedString` (resolved via the shared-strings pool, Stage 1.3) have no `CellValue`
+ * equivalent of their own and read back as `null`.
+ */
+declare function fromStored(s: StoredValue): CellValue;
+/** For a formula cell, the type of its cached `result`; else the cell's own type. */
+declare function effectiveType(s: StoredValue): CellType;
+/** Display string for a stored value (no number-format application — that's Stage 1.3). */
+declare function toText(s: StoredValue): string;
+/** CSV-escaped rendering of a stored value: quotes the field and doubles internal quotes when it
+ *  contains a comma, quote, or newline. */
+declare function toCsv(s: StoredValue): string;
+
+/** A row's cell values: a contiguous/sparse array, a column-key-keyed object, or absent. */
+type RowValues = CellValue[] | {
+    [key: string]: CellValue;
+} | undefined | null;
+
+interface RowModel {
+    number: number;
+    cells: CellModel[];
+    height?: number;
+    hidden?: boolean;
+    outlineLevel?: number;
+    style?: Style;
+}
+type EachCellCb$1 = (cell: Cell, colNumber: number) => void;
+declare class Row {
+    readonly worksheet: WorksheetHost;
+    readonly number: number;
+    height?: number;
+    hidden: boolean;
+    outlineLevel: number;
+    /** Sparse, 1-indexed by column number; index 0 is never assigned. */
+    private _cells;
+    private _style;
+    constructor(worksheet: WorksheetHost, number: number);
+    get collapsed(): boolean;
+    private resolveColNumber;
+    getCell(col: number | string): Cell;
+    findCell(col: number): Cell | undefined;
+    eachCell(cb: EachCellCb$1): void;
+    eachCell(opts: {
+        includeEmpty: boolean;
+    }, cb: EachCellCb$1): void;
+    get hasValues(): boolean;
+    get cellCount(): number;
+    get actualCellCount(): number;
+    get dimensions(): {
+        min: number;
+        max: number;
+    } | null;
+    get values(): RowValues;
+    set values(v: RowValues);
+    splice(start: number, count: number, ...inserts: CellValue[]): void;
+    private applyToCells;
+    get style(): Style;
+    set style(s: Style);
+    get numFmt(): string | undefined;
+    set numFmt(v: string | undefined);
+    get font(): Font | undefined;
+    set font(v: Font | undefined);
+    get alignment(): Alignment | undefined;
+    set alignment(v: Alignment | undefined);
+    get border(): Borders | undefined;
+    set border(v: Borders | undefined);
+    get fill(): Fill | undefined;
+    set fill(v: Fill | undefined);
+    get protection(): Protection | undefined;
+    set protection(v: Protection | undefined);
+    get model(): RowModel;
+    set model(m: RowModel);
+}
+
+interface WorksheetHost {
+    getColumn(col: number | string): Column;
+    getColumnKey(key: string): Column | undefined;
+    getRow(row: number): Row;
+    eachRow(cb: (row: Row, n: number) => void): void;
+    eachRow(opts: {
+        includeEmpty: boolean;
+    }, cb: (row: Row, n: number) => void): void;
+    readonly properties: {
+        outlineLevelCol: number;
+        outlineLevelRow: number;
+    } & Record<string, unknown>;
+}
+
+declare const DEFAULT_COLUMN_WIDTH = 9;
+interface ColumnDefn {
+    key?: string;
+    header?: string | string[];
+    width?: number;
+    hidden?: boolean;
+    outlineLevel?: number;
+    style?: Style;
+}
+/** Run-length range as compressed by `Column.toModel` — OOXML `<col min max .../>` attributes only. */
+interface ColumnRange {
+    min: number;
+    max: number;
+    width?: number;
+    hidden?: boolean;
+    outlineLevel?: number;
+    style?: Style;
+}
+type EachCellCb = (cell: Cell, rowNumber: number) => void;
+declare class Column {
+    private readonly host;
+    readonly number: number;
+    key?: string;
+    width?: number;
+    hidden: boolean;
+    outlineLevel: number;
+    private _header;
+    private _style;
+    constructor(host: WorksheetHost, number: number, defn?: Partial<ColumnDefn> | false);
+    get letter(): string;
+    get collapsed(): boolean;
+    get isCustomWidth(): boolean;
+    get isDefault(): boolean;
+    get header(): string | string[] | undefined;
+    /** Writes the header text(s) into this column's top cell(s): row 1 for a string, rows 1..N
+     *  for a string array (SPEC §6 — "header assignment writes the top row cells' values"). */
+    set header(h: string | string[] | undefined);
+    get values(): CellValue[];
+    set values(vals: CellValue[]);
+    eachCell(cb: EachCellCb): void;
+    eachCell(opts: {
+        includeEmpty: boolean;
+    }, cb: EachCellCb): void;
+    private applyToCells;
+    get style(): Style;
+    set style(s: Style);
+    get numFmt(): string | undefined;
+    set numFmt(v: string | undefined);
+    get font(): Font | undefined;
+    set font(v: Font | undefined);
+    get alignment(): Alignment | undefined;
+    set alignment(v: Alignment | undefined);
+    get border(): Borders | undefined;
+    set border(v: Borders | undefined);
+    get fill(): Fill | undefined;
+    set fill(v: Fill | undefined);
+    get protection(): Protection | undefined;
+    set protection(v: Protection | undefined);
+    get defn(): ColumnDefn;
+    set defn(d: ColumnDefn);
+    /** Whether two columns share the same OOXML-relevant attributes (used to compress runs). */
+    equivalentTo(other: Column): boolean;
+    private static rangeOf;
+    /** Run-length compress an array of Columns into `<col min max>` ranges. */
+    static toModel(columns: Column[]): ColumnRange[] | undefined;
+    /** Expands `<col min max>` ranges back into individual Columns. */
+    static fromModel(host: WorksheetHost, cols: ColumnRange[]): Column[] | null;
+}
+
+interface CellModel {
+    address: string;
+    type: CellType;
+    value?: unknown;
+    formula?: string;
+    result?: unknown;
+    style?: Style;
+}
+declare class Cell {
+    private readonly rowRef;
+    private readonly columnRef;
+    readonly address: string;
+    private _stored;
+    private _style;
+    private _master;
+    constructor(rowRef: Row, columnRef: Column, address: string);
+    get row(): number;
+    get col(): number;
+    get $col$row(): string;
+    /** The stored value this cell resolves through: itself, or (if merged) its master. */
+    private get resolvedStored();
+    get value(): CellValue;
+    set value(v: CellValue);
+    /** This cell's own marker type — `Merge` for a slave, even though `value`/`text` delegate. */
+    get type(): CellType;
+    get effectiveType(): CellType;
+    get text(): string;
+    toString(): string;
+    toCsvString(): string;
+    get isMerged(): boolean;
+    /** The master cell of this cell's merge region; itself if unmerged. */
+    get master(): Cell;
+    merge(master: Cell, ignoreStyle?: boolean): void;
+    unmerge(): void;
+    get formula(): string | undefined;
+    get result(): unknown;
+    get formulaType(): FormulaType;
+    get style(): Style;
+    set style(s: Style);
+    get numFmt(): string | undefined;
+    set numFmt(v: string | undefined);
+    get font(): Font | undefined;
+    set font(v: Font | undefined);
+    get alignment(): Alignment | undefined;
+    set alignment(v: Alignment | undefined);
+    get border(): Borders | undefined;
+    set border(v: Borders | undefined);
+    get fill(): Fill | undefined;
+    set fill(v: Fill | undefined);
+    get protection(): Protection | undefined;
+    set protection(v: Protection | undefined);
+    get model(): CellModel;
+    set model(m: CellModel);
+}
+
+/** 1-based rows/cols everywhere in this module's public surface. */
+interface Decoded {
+    row: number;
+    col: number;
+    address: string;
+}
+/** `decodeEx` result: adds the absolute `$col$row` form and an optional sheet qualifier. */
+interface DecodedEx extends Decoded {
+    $col$row: string;
+    sheetName?: string;
+}
+/** 'A'->1, 'Z'->26, 'AA'->27. Throws {@link InvalidAddressError} on non-letters. */
+declare function colLetterToNumber(letter: string): number;
+/** 1->'A', 27->'AA'. */
+declare function colNumberToLetter(col: number): string;
+/** (row=1,col=2) -> 'B1'. */
+declare function encodeAddress(row: number, col: number): string;
+/** 'B1' -> { row:1, col:2, address:'B1' }. Cached. */
+declare function decodeAddress(address: string): Decoded;
+/** Handles '$B$1', "'Sheet 1'!B1", Sheet1!B1, absolute/relative `$` markers. */
+declare function decodeEx(address: string): DecodedEx;
+/** Throws {@link InvalidAddressError} if not a well-formed A1 cell address. */
+declare function validateAddress(address: string): void;
+
+type RangeSource = string | [string, string] | [number, number, number, number] | Range | Decoded;
+/** A normalized bounding box (`top<=bottom`, `left<=right`) over 1-based cell addresses. */
+declare class Range {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    sheetName?: string;
+    constructor(source?: RangeSource);
+    constructor(top: number, left: number, bottom: number, right: number);
+    /** Top-left address, e.g. 'A1'. */
+    get tl(): string;
+    /** Bottom-right address, e.g. 'B2'. */
+    get br(): string;
+    /** 'A1:B2'. */
+    get range(): string;
+    /** Total cell count covered by the box. */
+    get count(): number;
+    /** Grows the box to include the given box (union of bounds). */
+    expand(top: number, left: number, bottom: number, right: number): void;
+    /** Whether the given address falls within this box. */
+    contains(address: string): boolean;
+    /** Whether this box overlaps another box. */
+    intersects(other: Range): boolean;
+    /** Visits every address in the box, row-major (row-by-row, left-to-right within a row). */
+    forEachAddress(cb: (address: string, row: number, col: number) => void): void;
+}
+
+/** Sheet properties. `outlineLevelCol`/`outlineLevelRow` back the `collapsed` derivation on
+ *  Column/Row; the rest is plain round-tripped data. */
+interface WorksheetProperties {
+    tabColor?: Color;
+    outlineLevelCol: number;
+    outlineLevelRow: number;
+    defaultRowHeight: number;
+    defaultColWidth?: number;
+    dyDescent: number;
+    showGridLines?: boolean;
+    [key: string]: unknown;
+}
+/** Freeze/split panes, zoom, gridlines — stored as plain data (round-trips through the model). */
+interface WorksheetView {
+    state?: "normal" | "frozen" | "split";
+    showGridLines?: boolean;
+    zoomScale?: number;
+    [key: string]: unknown;
+}
+/** Options accepted by `Workbook.addWorksheet`. */
+interface AddWorksheetOptions {
+    state: "visible" | "hidden" | "veryHidden";
+    properties: Partial<WorksheetProperties>;
+    views: WorksheetView[];
+    pageSetup: unknown;
+    headerFooter: unknown;
+}
+/** Replaces ExcelJS's cryptic `'i' | 'o' | 'i+' | 'o+' | 'n'` style DSL (API-AUDIT §2). */
+type RowInheritOption = {
+    inheritFrom?: "above" | "below";
+    includeEmpty?: boolean;
+} | undefined;
+/** The serializable snapshot of a worksheet. */
+interface WorksheetModel {
+    id: number;
+    name: string;
+    orderNo: number;
+    state: "visible" | "hidden" | "veryHidden";
+    properties: WorksheetProperties;
+    views: WorksheetView[];
+    columns?: ColumnRange[];
+    rows: RowModel[];
+    merges: string[];
+    pageSetup?: unknown;
+    headerFooter?: unknown;
+}
+type EachRowCb = (row: Row, n: number) => void;
+type RowData = CellValue[] | Record<string, CellValue>;
+declare class Worksheet implements WorksheetHost {
+    orderNo: number;
+    state: "visible" | "hidden" | "veryHidden";
+    readonly workbook: Workbook;
+    properties: WorksheetProperties;
+    views: WorksheetView[];
+    pageSetup?: unknown;
+    headerFooter?: unknown;
+    private _id;
+    private _name;
+    private readonly _rows;
+    private readonly _columns;
+    private readonly _columnsByKey;
+    /** Active merge regions keyed by their master (top-left) cell address. */
+    private readonly _merges;
+    constructor(workbook: Workbook, id: number, name: string, orderNo: number);
+    get id(): number;
+    get name(): string;
+    set name(value: string);
+    getRow(row: number): Row;
+    getRows(start: number, length: number): Row[] | undefined;
+    findRow(row: number): Row | undefined;
+    addRow(data: RowData, options?: RowInheritOption): Row;
+    addRows(rows: RowData[], options?: RowInheritOption): Row[];
+    insertRow(pos: number, value: RowData, options?: RowInheritOption): Row;
+    private applyInheritance;
+    duplicateRow(rowNum: number, count: number, insert?: boolean): void;
+    spliceRows(start: number, count: number, ...inserts: RowData[]): void;
+    private snapshotRow;
+    private restoreRow;
+    eachRow(cb: EachRowCb): void;
+    eachRow(opts: {
+        includeEmpty: boolean;
+    }, cb: EachRowCb): void;
+    getSheetValues(): RowValues[];
+    get rowCount(): number;
+    get actualRowCount(): number;
+    get lastRow(): Row | undefined;
+    get columns(): Column[];
+    set columns(defns: Partial<ColumnDefn>[]);
+    getColumn(idOrKey: number | string): Column;
+    private getOrCreateColumn;
+    get columnCount(): number;
+    get actualColumnCount(): number;
+    get lastColumn(): Column | undefined;
+    spliceColumns(start: number, count: number, ...inserts: CellValue[][]): void;
+    getColumnKey(key: string): Column | undefined;
+    setColumnKey(key: string, column: Column): void;
+    deleteColumnKey(key: string): void;
+    eachColumnKey(cb: (column: Column, key: string) => void): void;
+    getCell(r: number | string, c?: number | string): Cell;
+    findCell(r: number | string, c?: number | string): Cell | undefined;
+    private toColNumber;
+    mergeCells(...cells: unknown[]): void;
+    unMergeCells(...cells: unknown[]): void;
+    /** Links the slave cells of `range` to its top-left master and records the region. */
+    private applyMerge;
+    get hasMerges(): boolean;
+    get dimensions(): Range;
+    get model(): WorksheetModel;
+    set model(m: WorksheetModel);
+}
+
+/** Workbook-wide flags — notably the 1904 date system. */
+interface WorkbookProperties {
+    date1904?: boolean;
+    [key: string]: unknown;
+}
+/** Calculation chain flags (e.g. `fullCalcOnLoad`). */
+interface CalculationProperties {
+    fullCalcOnLoad?: boolean;
+    [key: string]: unknown;
+}
+/** Window layout / active-tab state — stored as plain data (round-trips through the model). */
+interface WorkbookView {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    activeTab?: number;
+    visibility?: string;
+    [key: string]: unknown;
+}
+/** The serializable snapshot of a workbook. */
+interface WorkbookModel {
+    creator?: string;
+    lastModifiedBy?: string;
+    created: Date;
+    modified: Date;
+    lastPrinted?: Date;
+    title?: string;
+    subject?: string;
+    keywords?: string;
+    category?: string;
+    description?: string;
+    company?: string;
+    manager?: string;
+    properties: WorkbookProperties;
+    calcProperties: CalculationProperties;
+    views: WorkbookView[];
+    sheets: WorksheetModel[];
+    nextId: number;
+}
+declare class Workbook {
+    creator?: string;
+    lastModifiedBy?: string;
+    created: Date;
+    modified: Date;
+    lastPrinted?: Date;
+    title?: string;
+    subject?: string;
+    keywords?: string;
+    category?: string;
+    description?: string;
+    company?: string;
+    manager?: string;
+    properties: WorkbookProperties;
+    calcProperties: CalculationProperties;
+    views: WorkbookView[];
+    private readonly _byId;
+    private _sheets;
+    private _nextId;
+    constructor();
+    /** Ordered, O(n). A fresh copy so callers cannot mutate the backing order. */
+    get worksheets(): Worksheet[];
+    addWorksheet(name?: string, options?: Partial<AddWorksheetOptions>): Worksheet;
+    private uniqueSheetName;
+    getWorksheet(idOrName?: number | string): Worksheet | undefined;
+    removeWorksheet(idOrName: number | string): void;
+    /** Keeps `orderNo` equal to array position after a removal. */
+    private reindex;
+    eachSheet(cb: (ws: Worksheet, id: number) => void): void;
+    get model(): WorkbookModel;
+    set model(m: WorkbookModel);
+}
+
+/** Convert a `Date` to its Excel day serial (fractional part carries the time of day). */
+declare function dateToSerial(d: Date, date1904?: boolean): number;
+/** Convert an Excel day serial back to a `Date` (UTC-based instant). */
+declare function serialToDate(serial: number, date1904?: boolean): Date;
+
+/** Reserved for future read options (e.g. `ignoreStyles`). None are required for v1. */
+interface ReadOptions {
+}
+/** Parse a buffered `.xlsx` into a `Workbook`. Environment-agnostic (no `fs`); see `readWorkbookFile`. */
+declare function readWorkbookBuffer(bytes: Uint8Array, _options?: ReadOptions): Workbook;
+/** Node-only convenience: read and parse a `.xlsx` from disk. Isolated here so browser bundles that
+ *  only use {@link readWorkbookBuffer} never pull in `node:fs`. */
+declare function readWorkbookFile(path: string, options?: ReadOptions): Promise<Workbook>;
+
+interface SharedStrings {
+    /** Intern a plain string or rich text; returns its 0-based index. Repeated values return the same
+     *  index (but still count as a reference). */
+    add(value: string | RichText): number;
+    /** Total references added (the sum of `add` calls). */
+    readonly count: number;
+    /** Distinct entries in the pool. */
+    readonly uniqueCount: number;
+    /** Render xl/sharedStrings.xml, or `undefined` when the pool is empty (the part is then omitted). */
+    toXml(): string | undefined;
+}
+declare function createSharedStrings(): SharedStrings;
+
+interface Styles {
+    /** Intern a resolved cell Style; returns its cellXf index (the value for a cell's `s=""` attr). A cell
+     *  with no style — or a structurally-default one — returns 0, the seeded default cellXf. */
+    addStyle(style: Style | undefined): number;
+    /** Render the complete xl/styles.xml. Always non-empty (the baseline seeds are always present). */
+    toXml(): string;
+}
+declare function createStyles(): Styles;
+
+interface WriteOptions {
+    /** Emit a shared-string table (string cells store an index). When `false`, strings render inline.
+     *  Default `true`. */
+    useSharedStrings?: boolean;
+    /** Intern cell/row/column styles into styles.xml. When `false`, cells render unstyled (`s` omitted)
+     *  and styles.xml carries only the mandatory baseline. Default `true`. */
+    useStyles?: boolean;
+}
+/** Serialize a workbook to `.xlsx` bytes. Environment-agnostic (no `fs`); see `writeWorkbookFile`. */
+declare function writeWorkbookBuffer(wb: Workbook, options?: WriteOptions): Uint8Array;
+/** Node-only convenience: serialize and write to disk. Isolated here so browser bundles that only
+ *  use {@link writeWorkbookBuffer} never pull in `node:fs`. */
+declare function writeWorkbookFile(wb: Workbook, path: string, options?: WriteOptions): Promise<void>;
+
+/**
+ * Typed error hierarchy for @alosha/xlsx.
+ *
+ * Every error thrown by the library extends {@link AloshaXlsxError}, so callers can do:
+ *
+ *   try { ws.name = 'a/b'; }
+ *   catch (e) {
+ *     if (e instanceof AloshaXlsxError) console.log(e.code); // stable, minify-safe
+ *   }
+ *
+ * The `code` string is the stable programmatic handle (safe across bundling/minification, unlike
+ * `name`/`instanceof` across realms). Prefer switching on `code`. Design goal (see docs/API-AUDIT.md §5):
+ * replace ExcelJS's `console.warn`/`console.trace` side effects with thrown, inspectable errors.
+ */
+type AloshaXlsxErrorCode = "INVALID_ADDRESS" | "INVALID_RANGE" | "INVALID_WORKSHEET_NAME" | "RESERVED_WORKSHEET_NAME" | "DUPLICATE_WORKSHEET_NAME" | "WORKSHEET_NAME_TOO_LONG" | "MERGE_CONFLICT" | "INVALID_ROW_NUMBER" | "INVALID_CELL_VALUE" | "UNSUPPORTED_FEATURE" | "INVALID_PACKAGE";
+/**
+ * Base class for all library errors. Abstract — never thrown directly; always a concrete subclass.
+ * Sets `name` from the concrete class and repairs the prototype chain so `instanceof` holds even when
+ * compiled to older targets.
+ */
+declare abstract class AloshaXlsxError extends Error {
+    /** Stable, machine-readable discriminator. Prefer this over `name`/`instanceof`. */
+    abstract readonly code: AloshaXlsxErrorCode;
+    constructor(message: string);
+}
+/** Narrowing type guard for library errors. */
+declare function isAloshaXlsxError(e: unknown): e is AloshaXlsxError;
+/** A cell address or column letter could not be parsed (e.g. `''`, `'A0'`, `'1A'`, `'@'`). */
+declare class InvalidAddressError extends AloshaXlsxError {
+    readonly address: string;
+    readonly code: "INVALID_ADDRESS";
+    constructor(address: string);
+}
+/** A range could not be parsed from the supplied source (e.g. `'A1:'`, malformed tuple). */
+declare class InvalidRangeError extends AloshaXlsxError {
+    readonly range: unknown;
+    readonly code: "INVALID_RANGE";
+    constructor(range: unknown);
+}
+/** Why a worksheet name was rejected (illegal-character/empty/edge-quote cases). */
+type InvalidWorksheetNameReason = "empty" | "illegal-characters" | "edge-quote";
+/** Worksheet name is empty, contains `* ? : / \ [ ]`, or starts/ends with a single quote. */
+declare class InvalidWorksheetNameError extends AloshaXlsxError {
+    readonly worksheetName: string;
+    readonly reason: InvalidWorksheetNameReason;
+    readonly code: "INVALID_WORKSHEET_NAME";
+    constructor(worksheetName: string, reason: InvalidWorksheetNameReason);
+    private static messageFor;
+}
+/** Worksheet name uses a reserved word (Excel reserves `"History"`). */
+declare class ReservedWorksheetNameError extends AloshaXlsxError {
+    readonly worksheetName: string;
+    readonly code: "RESERVED_WORKSHEET_NAME";
+    constructor(worksheetName: string);
+}
+/** A worksheet with this name already exists in the workbook (comparison is case-insensitive). */
+declare class DuplicateWorksheetNameError extends AloshaXlsxError {
+    readonly worksheetName: string;
+    readonly code: "DUPLICATE_WORKSHEET_NAME";
+    constructor(worksheetName: string);
+}
+/**
+ * Worksheet name exceeds Excel's limit. Unlike ExcelJS (which warns + silently truncates), the model
+ * throws so the caller decides — see docs/STAGE-1.2-SPEC.md §7.
+ */
+declare class WorksheetNameTooLongError extends AloshaXlsxError {
+    readonly worksheetName: string;
+    readonly maxLength: number;
+    readonly code: "WORKSHEET_NAME_TOO_LONG";
+    /** Excel's hard cap on sheet-name length. */
+    static readonly MAX_LENGTH = 31;
+    constructor(worksheetName: string, maxLength?: number);
+}
+/** Attempted to merge a region that overlaps an existing merge (merges are atomic — API-AUDIT §2). */
+declare class MergeConflictError extends AloshaXlsxError {
+    readonly range: string;
+    readonly code: "MERGE_CONFLICT";
+    constructor(range: string);
+}
+/** A row model's `number` does not match the row it is being assigned to (model round-trip guard). */
+declare class InvalidRowNumberError extends AloshaXlsxError {
+    readonly expected: number;
+    readonly actual: number;
+    readonly code: "INVALID_ROW_NUMBER";
+    constructor(expected: number, actual: number);
+}
+/** A value passed to `cell.value` is not a supported {@link import('./model/cell-value').CellValue}. */
+declare class InvalidCellValueError extends AloshaXlsxError {
+    readonly value: unknown;
+    readonly code: "INVALID_CELL_VALUE";
+    constructor(value: unknown);
+    private static describe;
+}
+/**
+ * A feature not implemented in the current stage was invoked (pivot tables, conditional formatting,
+ * drawings, tables, data validation, comments, protection — deferred to Stage 2; see STAGE-1.2-SPEC §9).
+ * Use to fail loudly on stubs instead of silently no-op'ing.
+ */
+declare class UnsupportedFeatureError extends AloshaXlsxError {
+    readonly feature: string;
+    readonly code: "UNSUPPORTED_FEATURE";
+    constructor(feature: string);
+}
+/**
+ * The `.xlsx` package's OPC structure (zip / rels / parts) is missing or malformed: a truncated/corrupt
+ * zip, a missing `_rels/.rels` or workbook part, or a relationship that cannot be resolved. Thrown by
+ * `openPackage` before any SpreadsheetML parsing begins.
+ */
+declare class InvalidPackageError extends AloshaXlsxError {
+    readonly reason: string;
+    readonly code: "INVALID_PACKAGE";
+    constructor(reason: string);
+}
+
+/**
+ * @alosha/xlsx — a modern TypeScript library for reading and writing XLSX
+ * spreadsheets, inspired by exceljs.
+ *
+ * This is the public entry point: the Stage 1.2 document model plus the Stage 1.3 OOXML writer. The
+ * writer is exposed two ways — the free functions from `./xlsx` (the environment-agnostic core) and
+ * an ExcelJS-style `workbook.xlsx.writeBuffer/writeFile` accessor attached here at the composition
+ * root, so the model layer keeps no dependency on the serializer.
+ */
+
+/** A source of chunks for {@link XlsxAccessor.read}; a Node `Readable` satisfies this structurally. */
+type ByteStream = AsyncIterable<Uint8Array>;
+/** The ExcelJS-compatible read/write surface reached via `workbook.xlsx`. `load`/`readFile`/`read`
+ *  mutate the receiving workbook in place and return it, matching ExcelJS. */
+interface XlsxAccessor {
+    /** Serialize the workbook to `.xlsx` bytes. Async to mirror ExcelJS; wraps the sync core. */
+    writeBuffer(options?: WriteOptions): Promise<Uint8Array>;
+    /** Node-only: serialize and write to `path`. */
+    writeFile(path: string, options?: WriteOptions): Promise<void>;
+    /** Parse `.xlsx` bytes into this workbook (replaces its contents), returning it. */
+    load(data: Uint8Array, options?: ReadOptions): Promise<Workbook>;
+    /** Node-only: read and parse a `.xlsx` from `path` into this workbook, returning it. */
+    readFile(path: string, options?: ReadOptions): Promise<Workbook>;
+    /** Drain a byte stream (e.g. a Node `Readable`) and parse it into this workbook, returning it. */
+    read(stream: ByteStream, options?: ReadOptions): Promise<Workbook>;
+}
+declare module "./model/workbook.js" {
+    interface Workbook {
+        /** ExcelJS-style read/write accessor (see {@link XlsxAccessor}). */
+        readonly xlsx: XlsxAccessor;
+    }
+}
+/** The semantic version of the library. */
+declare const version = "0.0.0";
+
+export { type AddWorksheetOptions, type Alignment, AloshaXlsxError, type AloshaXlsxErrorCode, type Border, type BorderDiagonal, type BorderStyle, type Borders, type CalculationProperties, Cell, type CellError, type CellFormula, type CellModel, CellType, type CellValue, type Color, Column, type ColumnDefn, type ColumnRange, DEFAULT_COLUMN_WIDTH, type Decoded, type DecodedEx, DuplicateWorksheetNameError, type ErrorCode, type Fill, type FillPattern, type Font, FormulaType, type GradientStop, type Hyperlink, InvalidAddressError, InvalidCellValueError, InvalidPackageError, InvalidRangeError, InvalidRowNumberError, InvalidWorksheetNameError, type InvalidWorksheetNameReason, MergeConflictError, type Protection, Range, type RangeSource, type ReadOptions, ReservedWorksheetNameError, type RichText, type RichTextRun, Row, type RowInheritOption, type RowModel, type RowValues, type SharedStrings, type StoredValue, type Style, type Styles, UnsupportedFeatureError, Workbook, type WorkbookModel, type WorkbookProperties, type WorkbookView, Worksheet, type WorksheetHost, type WorksheetModel, WorksheetNameTooLongError, type WorksheetProperties, type WorksheetView, type WriteOptions, type XlsxAccessor, colLetterToNumber, colNumberToLetter, createSharedStrings, createStyles, dateToSerial, decodeAddress, decodeEx, detectType, effectiveType, encodeAddress, fromStored, isAloshaXlsxError, readWorkbookBuffer, readWorkbookFile, resolveCellStyle, serialToDate, toCsv, toStored, toText, validateAddress, version, writeWorkbookBuffer, writeWorkbookFile };