@openjsxl/core 0.2.1 → 0.4.0

package/README.md

@@ -5,8 +5,9 @@
 [![license: MIT](https://img.shields.io/npm/l/@openjsxl/core?color=blue)](./LICENSE)
 
 The zero-dependency OOXML engine behind [`openjsxl`](https://www.npmjs.com/package/openjsxl):
-the `zip → xml → ooxml → reader` layers that turn an `.xlsx` into typed cells, built only on
-platform Web APIs (`DecompressionStream`, `TextDecoder`, …). No runtime dependencies.
+the `zip → xml → ooxml → reader` layers that turn an `.xlsx` into typed cells — and the mirror
+`writer` layer that turns plain data back into `.xlsx` bytes. Built only on platform Web APIs
+(`DecompressionStream`, `CompressionStream`, `TextDecoder`, …). No runtime dependencies.
 
 **Most users should install [`openjsxl`](https://www.npmjs.com/package/openjsxl) instead** — it
 re-exports everything here and is the stable public surface. Install `@openjsxl/core` directly
@@ -26,8 +27,10 @@ const wb = await openXlsx(await readFile('data.xlsx'))
 const sheet = wb.sheet('Sheet1')
 
 sheet.cell('A1') // { ref, type, value } — narrow on `type` for a typed value
+sheet.style('B2') // { font?, fill?, border?, alignment?, numberFormat? } | undefined
 sheet.numberFormat('C1') // "mm-dd-yy" | undefined
 sheet.mergedCells // ["A1:B1", …]
+sheet.freeze // { rows?, cols? } | undefined — plus columns, rowProperties, state, …
 
 // Constant-memory streaming for large sheets — one row at a time.
 for await (const row of streamSheetRows(await readFile('huge.xlsx'))) {
@@ -39,11 +42,37 @@ Malformed input throws a typed `XlsxError` with a discriminating `.code`
 (`'not-a-zip' | 'not-xlsx' | 'missing-part' | 'corrupt-zip' | 'part-too-large' | …`), never a
 bare `TypeError` from a corrupt file.
 
+## Writing
+
+```ts
+import { writeXlsx, workbookToInput } from '@openjsxl/core'
+
+// Author from plain data — cell types inferred from the JS values.
+const bytes = await writeXlsx({
+	sheets: [{ name: 'Report', rows: [['Item', 'Added'], ['Apples', new Date('2024-01-15')]] }],
+})
+
+// Or read → modify → write.
+const input = await workbookToInput(await openXlsx(bytes))
+input.sheets[0].rows.push(['Pears', new Date('2024-02-01')])
+const updated = await writeXlsx(input)
+```
+
+Cells can carry styles (`{ value, style }` — the same shape `style(ref)` returns), and sheets
+take `columns` (widths), `rowProperties` (heights), `freeze`, `merges`, `hyperlinks`, and a
+visibility `state`. Output is deterministic; unrepresentable input (no sheets, bad/duplicate
+sheet name, non-finite number, invalid `Date`, XML-illegal characters, malformed or overlapping
+merges) throws `XlsxError` with `code: 'invalid-input'`. The round trip is lossless for values,
+types, sheet names/order, styles, geometry, merges, hyperlinks, and visibility.
+
 ## Exports
 
 - **Reader:** `openXlsx`, `streamSheetRows`, `Workbook`, `Worksheet`, `ReadOptions`
+- **Writer:** `writeXlsx`, `workbookToInput`, `WorkbookInput`, `SheetInput`, `CellInput`,
+  `StyledCell`, `CellValue`, `WriteOptions`
 - **Errors:** `XlsxError`, `XlsxErrorCode`
-- **Types:** `Row`, `Cell`, `CellType`, `Comment`, `Hyperlink`, `SheetInfo`, `CellRef`
+- **Types:** `Row`, `Cell`, `CellType`, `CellStyle` (+ font/fill/border/alignment/color parts),
+  `ColumnProps`, `RowProps`, `FreezePane`, `Comment`, `Hyperlink`, `SheetInfo`, `SheetState`, `CellRef`
 - **A1 & dates:** `columnToIndex`, `indexToColumn`, `parseRef`, `formatRef`, `serialToDate`
 
 Full guide, design notes, and roadmap: <https://github.com/joaquimserafim/openjsxl>

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-type XlsxErrorCode = 'not-a-zip' | 'not-xlsx' | 'missing-part' | 'corrupt-zip' | 'unsupported' | 'no-such-sheet' | 'part-too-large';
+type XlsxErrorCode = "not-a-zip" | "not-xlsx" | "missing-part" | "corrupt-zip" | "unsupported" | "no-such-sheet" | "part-too-large" | "invalid-input";
 declare class XlsxError extends Error {
     /** Machine-readable discriminant; branch on this rather than the message. */
     readonly code: XlsxErrorCode;
@@ -19,38 +19,47 @@ declare function parseRef(ref: string): CellRef;
 declare function formatRef(ref: CellRef): string;
 
 declare function serialToDate(serial: number, date1904?: boolean): Date;
+declare function dateToSerial(date: Date, date1904?: boolean): number;
 
-type CellType = 'empty' | 'string' | 'number' | 'boolean' | 'date' | 'error';
+type CellType = "empty" | "string" | "number" | "boolean" | "date" | "error";
 interface CellBase {
     /** A1 reference, e.g. "B2". */
     readonly ref: string;
 }
 type Cell = (CellBase & {
-    readonly type: 'empty';
+    readonly type: "empty";
     readonly value: null;
 }) | (CellBase & {
-    readonly type: 'string';
+    readonly type: "string";
     readonly value: string;
 }) | (CellBase & {
-    readonly type: 'number';
+    readonly type: "number";
     readonly value: number;
 }) | (CellBase & {
-    readonly type: 'boolean';
+    readonly type: "boolean";
     readonly value: boolean;
 }) | (CellBase & {
-    readonly type: 'date';
+    readonly type: "date";
     readonly value: Date;
 }) | (CellBase & {
-    readonly type: 'error';
+    readonly type: "error";
     readonly value: string;
 });
+/**
+ * A sheet tab's visibility (the `state` attribute on `<sheet>`). `hidden` sheets can be re-shown
+ * from Excel's UI; `veryHidden` ones only through VBA or by editing the file. An absent or
+ * unrecognized state reads as `visible` (the spec's default).
+ */
+type SheetState = "visible" | "hidden" | "veryHidden";
 interface SheetInfo {
     /** Sheet name as shown on Excel's tab. */
     readonly name: string;
     /** Workbook-relative part path, resolved via the relationship graph. */
     readonly path: string;
-    /** false for hidden or very-hidden sheets. */
+    /** false for hidden or very-hidden sheets. Kept alongside {@link state} (which it derives from). */
     readonly visible: boolean;
+    /** The tab's visibility state (F4.6). `visible` is `state === "visible"`. */
+    readonly state: SheetState;
 }
 interface Comment {
     /** The cell the comment is anchored to, e.g. "B2". */
@@ -75,6 +84,114 @@ interface Hyperlink {
     /** Display-text override for the link, if any. */
     readonly display?: string;
 }
+/** Width/visibility for a 1-based column range (`min`–`max` inclusive), from `<cols>`. */
+interface ColumnProps {
+    readonly min: number;
+    readonly max: number;
+    /** Column width in characters of the default font (Excel's unit), 0 < width ≤ 255. */
+    readonly width?: number;
+    readonly hidden?: boolean;
+}
+/** Height/visibility of one row, from `<row ht hidden>`. */
+interface RowProps {
+    /** Row height in points, 0 < height ≤ 409.5 (Excel's ceiling). */
+    readonly height?: number;
+    readonly hidden?: boolean;
+}
+/**
+ * A frozen pane: the top `rows` rows and/or leftmost `cols` columns stay visible while the rest
+ * scrolls. Split (non-frozen) panes are not modelled and read as no freeze.
+ */
+interface FreezePane {
+    readonly rows?: number;
+    readonly cols?: number;
+}
+/**
+ * A color as OOXML stores it — kept RAW, never resolved. `rgb` is ARGB hex (e.g. `"FFFF0000"`);
+ * `theme` indexes the workbook theme's color scheme with an optional `tint` (−1…1); `indexed` is
+ * a legacy palette index; `auto` lets the consumer pick (usually black). Theme colors are NOT
+ * resolved to rgb on read: resolution needs a theme1.xml parser and is lossy on rewrite (a
+ * theme-aware consumer could no longer re-tint) — the raw form is what round-trips faithfully,
+ * and it is exactly what openpyxl stores too.
+ */
+type Color = {
+    readonly rgb: string;
+} | {
+    readonly theme: number;
+    readonly tint?: number;
+} | {
+    readonly indexed: number;
+} | {
+    readonly auto: true;
+};
+/**
+ * Underline style. The exotic accounting variants (`singleAccounting`/`doubleAccounting`)
+ * degrade to no underline on read and are rejected on write (deferred, documented).
+ */
+type UnderlineStyle = "single" | "double";
+interface FontStyle {
+    readonly name?: string;
+    /** Font size in points. */
+    readonly size?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: UnderlineStyle;
+    readonly strike?: boolean;
+    readonly color?: Color;
+}
+/** Fill pattern kinds (ECMA-376 §18.18.55). `gray125` is the workbook-reserved fill 1. */
+type PatternType = "none" | "solid" | "mediumGray" | "darkGray" | "lightGray" | "darkHorizontal" | "darkVertical" | "darkDown" | "darkUp" | "darkGrid" | "darkTrellis" | "lightHorizontal" | "lightVertical" | "lightDown" | "lightUp" | "lightGrid" | "lightTrellis" | "gray125" | "gray0625";
+/**
+ * A pattern fill. For the everyday solid fill, the visible color is `fgColor` (OOXML's rule —
+ * `bgColor` shows only through pattern gaps). Gradient fills are not modelled (deferred): a
+ * gradient-filled cell reads as having no fill.
+ */
+interface FillStyle {
+    readonly patternType: PatternType;
+    readonly fgColor?: Color;
+    readonly bgColor?: Color;
+}
+/** Border line styles (ECMA-376 §18.18.3). An edge with no style is simply absent. */
+type BorderLineStyle = "thin" | "medium" | "thick" | "dashed" | "dotted" | "double" | "hair" | "mediumDashed" | "dashDot" | "mediumDashDot" | "dashDotDot" | "mediumDashDotDot" | "slantDashDot";
+interface BorderEdge {
+    readonly style: BorderLineStyle;
+    readonly color?: Color;
+}
+/** Per-edge borders. Diagonal borders are not modelled (deferred). */
+interface BorderStyle {
+    readonly top?: BorderEdge;
+    readonly right?: BorderEdge;
+    readonly bottom?: BorderEdge;
+    readonly left?: BorderEdge;
+}
+type HorizontalAlignment = "left" | "center" | "right" | "justify" | "fill" | "centerContinuous" | "distributed";
+type VerticalAlignment = "top" | "center" | "bottom" | "justify" | "distributed";
+interface Alignment {
+    readonly horizontal?: HorizontalAlignment;
+    readonly vertical?: VerticalAlignment;
+    readonly wrapText?: boolean;
+    readonly shrinkToFit?: boolean;
+    /** Indent level (whole units of about 3 spaces), 0–250. */
+    readonly indent?: number;
+    /**
+     * Text rotation in degrees, 0–180 (91–180 mean 1–90° downward, per the spec). The legacy
+     * marker 255 ("vertical stacked") is not modelled and degrades to no rotation.
+     */
+    readonly textRotation?: number;
+}
+/**
+ * The resolved style of one cell. Every component is optional; a cell whose effective format is
+ * the workbook default resolves to no style at all (`Worksheet.style(ref)` returns `undefined`).
+ * `numberFormat` is always the format CODE string (e.g. `"yyyy-mm-dd"`, `"0.00%"`) — ids are a
+ * file-internal detail and never appear in the API.
+ */
+interface CellStyle {
+    readonly numberFormat?: string;
+    readonly font?: FontStyle;
+    readonly fill?: FillStyle;
+    readonly border?: BorderStyle;
+    readonly alignment?: Alignment;
+}
 
 interface StyleTable {
     /** True when the cell format at this `s` index applies a date/time number format. */
@@ -85,6 +202,12 @@ interface StyleTable {
      * built-in with no portable code, or the index is out of range.
      */
     formatCode(styleIndex: number | undefined): string | undefined;
+    /**
+     * The full resolved style at this `s` index — number format code, font, fill, border, and
+     * alignment. `undefined` when the index is out of range or the xf resolves to the workbook
+     * default (no distinguishing component). Cached: repeated calls return the same object.
+     */
+    cellStyle(styleIndex: number | undefined): CellStyle | undefined;
 }
 
 interface DecodeContext {
@@ -101,7 +224,7 @@ interface Relationship {
     readonly type: string;
     /** Target exactly as written; resolve internal ones with resolveTarget. */
     readonly target: string;
-    readonly targetMode: 'Internal' | 'External';
+    readonly targetMode: "Internal" | "External";
 }
 
 interface Row {
@@ -120,6 +243,8 @@ declare class Worksheet {
     get path(): string;
     /** false for hidden or very-hidden sheets. */
     get visible(): boolean;
+    /** The tab's visibility state (F4.6): `"visible"`, `"hidden"`, or `"veryHidden"`. */
+    get state(): SheetState;
     /**
      * Merged-cell ranges in A1 notation (e.g. `['A1:B1', 'A2:A4']`), in document order. Only the
      * top-left cell of a merge holds a value; the rest read as `empty`. Empty when none.
@@ -138,6 +263,15 @@ declare class Worksheet {
      * 0, usually `"General"`), mirroring how date detection defaults.
      */
     numberFormat(ref: string): string | undefined;
+    /**
+     * The resolved style of the cell at `ref` — number format code, font, fill, border, and
+     * alignment (F4.1). Resolution shares the same effective-style map as {@link numberFormat}
+     * (cell `s` → row `customFormat` default → column default), so the two always agree.
+     * `undefined` for an unstyled cell, an absent cell, or a workbook with no style table —
+     * "no style" and "the default style" are deliberately the same answer. Objects are cached
+     * per distinct format record: two cells sharing a format return the same object.
+     */
+    style(ref: string): CellStyle | undefined;
     /**
      * The sheet's declared used range in A1 notation (e.g. `"A1:E10"`, or a single cell), from
      * the worksheet's `<dimension>`. `undefined` when the producer omits it — it is an optional
@@ -149,6 +283,22 @@ declare class Worksheet {
      * resolved `author`, and plain `text`. Empty when the sheet has no comments part.
      */
     get comments(): readonly Comment[];
+    /**
+     * Column width/visibility declarations (`<cols>`), in document order (F4.5). Entries carrying
+     * only a column-default STYLE are not geometry and are omitted — `style(ref)` already resolves
+     * them. Empty when the sheet declares none.
+     */
+    get columns(): readonly ColumnProps[];
+    /**
+     * Per-row height/visibility, keyed by 1-based row index (F4.5). Only rows that declare a
+     * height or hidden flag appear. Empty map when none do.
+     */
+    get rowProperties(): ReadonlyMap<number, RowProps>;
+    /**
+     * The sheet's frozen pane, or `undefined` when nothing is frozen (F4.5). Split (non-frozen)
+     * panes are not modelled and read as `undefined`.
+     */
+    get freeze(): FreezePane | undefined;
     /** The cell at an A1 reference. Absent cells read as `empty` (Excel treats them blank). */
     cell(ref: string): Cell;
     /** Stream the populated rows in document order. Sparse: empty rows/cells are absent. */
@@ -178,4 +328,94 @@ declare function openXlsx(source: Uint8Array | ArrayBuffer, options?: ReadOption
  */
 declare function streamSheetRows(source: Uint8Array | ArrayBuffer, sheetName?: string, options?: ReadOptions): AsyncGenerator<Row>;
 
-export { type Cell, type CellRef, type CellType, type Comment, type Hyperlink, type ReadOptions, type Row, type SheetInfo, Workbook, Worksheet, XlsxError, type XlsxErrorCode, columnToIndex, formatRef, indexToColumn, openXlsx, parseRef, serialToDate, streamSheetRows };
+/**
+ * A value a cell can hold when writing. The OOXML cell type is inferred from it:
+ * `string` → inline string, `number` → numeric, `boolean` → `b`, `Date` → date-styled serial.
+ * `null` / `undefined` (including array holes) → an empty cell, omitted from the output.
+ */
+type CellValue = string | number | boolean | Date | null | undefined;
+/**
+ * A cell with a {@link CellStyle} attached (F4.2). `value` is required but nullable — a styled
+ * BLANK cell (`{ value: null, style }`) is real and emits `<c r s/>`, which is how a border or
+ * fill lands on a cell with nothing in it. The style type is exactly what `Worksheet.style(ref)`
+ * returns, so read → modify → write carries styles as a pass-through.
+ */
+interface StyledCell {
+    readonly value: CellValue;
+    readonly style?: CellStyle;
+}
+/**
+ * One cell in a row: a bare value, or a value with a style. Discrimination is total — `null` /
+ * `undefined` mean empty, `Date` instances are dates, and any OTHER object must be a
+ * {@link StyledCell} (an object without a `value` property throws `invalid-input`, catching stray
+ * objects loudly). Bare-value rows are untouched: pre-F4.2 input keeps its exact meaning AND its
+ * exact output bytes.
+ */
+type CellInput = CellValue | StyledCell;
+interface SheetInput {
+    /** Tab name. 1–31 chars, unique (case-insensitively), free of `\ / ? * [ ] :`. */
+    readonly name: string;
+    /**
+     * Rows top-to-bottom; each a left-to-right array of cells. `rows[0][0]` is A1. A hole or
+     * `undefined` row is an empty row (the bridge produces sparse arrays; hand-written input may
+     * too) — matching how `null`/`undefined`/holes inside a row mean empty cells.
+     */
+    readonly rows: readonly (readonly CellInput[] | undefined)[];
+    /**
+     * Column width/visibility declarations (F4.5) — the same shape `Worksheet.columns` returns.
+     * Ranges are 1-based and inclusive; entries need a `width` and/or `hidden: true`.
+     */
+    readonly columns?: readonly ColumnProps[];
+    /**
+     * Per-row height/visibility keyed by 1-based row index (F4.5) — the same records
+     * `Worksheet.rowProperties` holds. A row may have properties without having any cells.
+     */
+    readonly rowProperties?: Readonly<Record<number, RowProps>>;
+    /** Freeze the top `rows` rows and/or leftmost `cols` columns (F4.5). */
+    readonly freeze?: FreezePane;
+    /**
+     * Merged-cell ranges in canonical A1 form, top-left:bottom-right (e.g. `"A1:B2"`) — the same
+     * strings `Worksheet.mergedCells` returns (F4.6). Malformed, single-cell, out-of-grid, and
+     * overlapping ranges are rejected: Excel repair-prompts on them.
+     */
+    readonly merges?: readonly string[];
+    /**
+     * Hyperlinks on this sheet (F4.6) — the same records `Worksheet.hyperlinks` returns. Each needs
+     * a `ref` (cell or range) plus an external `target` and/or an in-workbook `location`; `tooltip`
+     * and `display` are optional. External targets get the sheet's relationships part.
+     */
+    readonly hyperlinks?: readonly Hyperlink[];
+    /**
+     * Tab visibility (F4.6). Defaults to `"visible"`; at least one sheet in the workbook must
+     * remain visible, or Excel refuses the file.
+     */
+    readonly state?: SheetState;
+}
+interface WorkbookInput {
+    /** At least one sheet, in tab order. */
+    readonly sheets: readonly SheetInput[];
+}
+interface WriteOptions {
+    /** Use the 1904 date epoch (legacy Mac) instead of the default 1900 system. */
+    readonly date1904?: boolean;
+}
+
+/**
+ * Convert an open {@link Workbook} into {@link WorkbookInput} for {@link writeXlsx}. Each populated
+ * cell is placed at its own A1 reference with its resolved style (if any), preserving sheet names
+ * and tab order. Rows/columns are left sparse (array holes) — the writer treats a hole as an empty
+ * cell — so a workbook with a few far-apart cells does not materialize a dense grid. An unstyled
+ * workbook yields bare values only: the exact pre-styles WorkbookInput, and the exact same bytes
+ * on rewrite.
+ */
+declare function workbookToInput(workbook: Workbook): Promise<WorkbookInput>;
+
+/**
+ * Serialize a workbook to `.xlsx` bytes. Async because compression runs on the platform's
+ * CompressionStream. Throws {@link XlsxError} with code `invalid-input` for anything that can't be
+ * represented — no sheets, a bad sheet name, or a cell value that isn't a string, finite number,
+ * boolean, Date, or null.
+ */
+declare function writeXlsx(workbook: WorkbookInput, options?: WriteOptions): Promise<Uint8Array>;
+
+export { type Alignment, type BorderEdge, type BorderLineStyle, type BorderStyle, type Cell, type CellInput, type CellRef, type CellStyle, type CellType, type CellValue, type Color, type ColumnProps, type Comment, type FillStyle, type FontStyle, type FreezePane, type HorizontalAlignment, type Hyperlink, type PatternType, type ReadOptions, type Row, type RowProps, type SheetInfo, type SheetInput, type SheetState, type StyledCell, type UnderlineStyle, type VerticalAlignment, Workbook, type WorkbookInput, Worksheet, type WriteOptions, XlsxError, type XlsxErrorCode, columnToIndex, dateToSerial, formatRef, indexToColumn, openXlsx, parseRef, serialToDate, streamSheetRows, workbookToInput, writeXlsx };