documonster 0.14.0 → 0.15.0

package/README.md

@@ -211,7 +211,7 @@ const buffer = await Workbook.toBuffer(wb);
 
 ```html
 <!-- Script tag (no bundler) — one IIFE per module, each under the shared `Documonster` global -->
-<script src="https://unpkg.com/documonster@0.14.0/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.15.0/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/README_zh.md

@@ -198,7 +198,7 @@ const buffer = await Workbook.toBuffer(wb);
 
 ```html
 <!-- Script 标签（无需打包工具）— 每个模块一个 IIFE，共享同一个 `Documonster` 全局 -->
-<script src="https://unpkg.com/documonster@0.14.0/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.15.0/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/dist/esm/modules/archive/compression/crc32.browser.js

@@ -1,33 +1,12 @@
 /**
- * CRC32 calculation utility for ZIP files (Browser version)
+ * CRC32 for ZIP files — browser variant.
  *
- * Uses lookup table optimization - no Node.js dependencies
+ * The portable lookup-table implementation, with no `zlib` and no Node built-in of any kind. `crc32.ts` is
+ * the sibling that uses native `zlib.crc32`.
  *
- * The polynomial used is the standard CRC-32 IEEE 802.3:
+ * The polynomial is the standard CRC-32 IEEE 802.3:
  * x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
- * Represented as 0xEDB88320 in reversed (LSB-first) form
- */
-export { crc32JS as crc32, crc32UpdateJS as crc32Update, crc32Finalize } from "./crc32.base.js";
-/**
- * Ensure CRC32 is ready (no-op in browser, for API compatibility)
- */
-export async function ensureCrc32() {
-    // No-op in browser
-}
-/**
- * Synchronously ensure CRC32 is ready (no-op in browser).
- * Exists for API compatibility with the Node.js version.
- */
-export function ensureZlibSync() {
-    // No-op in browser — CRC32 always uses JS implementation
-}
-/**
- * Calculate CRC32 incrementally (useful for streaming)
- * Call with initial crc of 0xffffffff, then finalize with crc32Finalize
- *
- * @param crc - Current CRC value (start with 0xffffffff)
- * @param data - Input data chunk
- * @returns Updated CRC value (not finalized)
+ * Represented as 0xEDB88320 in reversed (LSB-first) form.
  *
  * @example
  * ```ts
@@ -37,3 +16,4 @@ export function ensureZlibSync() {
  * const checksum = crc32Finalize(crc);
  * ```
  */
+export { crc32JS as crc32, crc32UpdateJS as crc32Update, crc32Finalize } from "./crc32.base.js";

package/dist/esm/modules/archive/compression/crc32.js

@@ -1,61 +1,20 @@
 /**
- * CRC32 calculation utility for ZIP files
+ * CRC32 for ZIP files — Node variant.
  *
- * - Node.js: Uses native zlib.crc32 (C++ implementation, ~100x faster)
- * - Browser: Uses lookup table optimization
+ * `zlib` is imported **statically**, and that is the invariant this file exists to hold. Loading it lazily
+ * leaves a window in which CRC32 runs on the portable lookup table instead, and the window cannot be closed
+ * synchronously from an ES module. `crc32.browser.ts` is the sibling that has no `zlib` and uses the table.
  *
- * The polynomial used is the standard CRC-32 IEEE 802.3:
+ * `zlib.crc32` has existed since Node 22.2 and `engines.node` is `>=22.13`, so it needs no capability probe.
+ *
+ * The polynomial is the standard CRC-32 IEEE 802.3:
  * x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
- * Represented as 0xEDB88320 in reversed (LSB-first) form
- */
-import { crc32JS, crc32UpdateJS, crc32Finalize } from "./crc32.base.js";
-import { isNode } from "../../../utils/env.js";
-// Lazy-loaded zlib module for Node.js
-let _zlib = null;
-let _zlibLoading = null;
-let _zlibInitStarted = false;
-/**
- * Lazily initialize zlib loading in Node.js.
- * Called on first use rather than at module load time.
+ * Represented as 0xEDB88320 in reversed (LSB-first) form.
  */
-function ensureZlibLoading() {
-    if (_zlibInitStarted) {
-        return;
-    }
-    _zlibInitStarted = true;
-    if (isNode()) {
-        _zlibLoading = import("zlib")
-            .then(module => {
-            _zlib = module.default ?? module;
-            return _zlib;
-        })
-            .catch(() => {
-            _zlib = null;
-            return null;
-        });
-    }
-}
-/**
- * Synchronously ensure zlib is loaded for Node.js.
- * Used by the sync deflate path where the async dynamic import may not have
- * resolved yet. Falls back to `require()` which is synchronous in Node.js.
- */
-export function ensureZlibSync() {
-    if (_zlib || !isNode()) {
-        return;
-    }
-    try {
-        // oxlint-disable-next-line typescript/no-require-imports
-        _zlib = require("zlib");
-        _zlibInitStarted = true;
-    }
-    catch {
-        // Bundler or non-Node environment — JS fallback will be used
-    }
-}
+import { crc32 as nativeCrc32 } from "zlib";
+import { crc32Finalize } from "./crc32.base.js";
 /**
  * Calculate CRC32 checksum for the given data
- * Uses native zlib.crc32 in Node.js for ~100x better performance
  *
  * @param data - Input data as Uint8Array or Buffer
  * @returns CRC32 checksum as unsigned 32-bit integer
@@ -68,28 +27,13 @@ export function ensureZlibSync() {
  * ```
  */
 export function crc32(data) {
-    ensureZlibLoading();
-    // Use native zlib.crc32 if available (Node.js)
-    if (_zlib && typeof _zlib.crc32 === "function") {
-        return _zlib.crc32(data) >>> 0;
-    }
-    // Fallback to JS implementation
-    return crc32JS(data);
-}
-/**
- * Ensure zlib is loaded (for use before calling crc32)
- */
-export async function ensureCrc32() {
-    ensureZlibLoading();
-    if (_zlibLoading) {
-        await _zlibLoading;
-    }
+    return nativeCrc32(data) >>> 0;
 }
 /**
  * Calculate CRC32 incrementally (useful for streaming)
  * Call with initial crc of 0xffffffff, then finalize with crc32Finalize
- * In Node.js, this uses native zlib.crc32 when available for performance.
- * The internal CRC state remains the same as the JS table implementation:
+ *
+ * The internal state matches the lookup-table implementation, so the two are interchangeable:
  * - initial state: 0xffffffff
  * - finalize: xor with 0xffffffff
  *
@@ -106,17 +50,11 @@ export async function ensureCrc32() {
  * ```
  */
 export function crc32Update(crc, data) {
-    ensureZlibLoading();
-    // If available, use native zlib.crc32 but preserve our internal state shape.
-    // zlib.crc32 returns a finalized CRC value and can accept the previous finalized
-    // CRC as the second parameter (chainable). Our internal state is the inverted
-    // (non-finalized) CRC, so convert with xor before/after.
-    if (_zlib && typeof _zlib.crc32 === "function") {
-        const prevFinal = (crc ^ 0xffffffff) >>> 0;
-        const nextFinal = _zlib.crc32(data, prevFinal) >>> 0;
-        return (nextFinal ^ 0xffffffff) >>> 0;
-    }
-    return crc32UpdateJS(crc, data);
+    // `zlib.crc32` takes and returns a *finalized* CRC and chains through its second argument. The state here
+    // is the inverted (non-finalized) form, so convert on the way in and out.
+    const prevFinal = (crc ^ 0xffffffff) >>> 0;
+    const nextFinal = nativeCrc32(data, prevFinal) >>> 0;
+    return (nextFinal ^ 0xffffffff) >>> 0;
 }
 /**
  * Finalize CRC32 calculation

package/dist/esm/modules/archive/zip/stream.js

@@ -5,7 +5,7 @@
  * - In Node builds it uses `./compression/crc32` + `./compression/streaming-compress` (zlib-backed).
  * - In browser builds the bundler aliases those imports to their browser variants.
  */
-import { crc32Update, crc32Finalize, ensureZlibSync } from "#platform/modules/archive/compression/crc32";
+import { crc32Update, crc32Finalize } from "#platform/modules/archive/compression/crc32";
 import { createDeflateStream, SyncDeflater, hasNativeAsyncDeflate } from "#platform/modules/archive/compression/streaming-compress";
 import { EMPTY_UINT8ARRAY } from "../core/bytes.js";
 import { DEFAULT_ZIP_LEVEL, DEFAULT_ZIP_TIMESTAMPS } from "../core/defaults.js";
@@ -77,7 +77,6 @@ export class ZipDeflateFile {
         this._inputPos = 0;
         // Synchronous compression state for pushSync() path.
         this._syncDeflater = null;
-        this._syncZlibReady = false;
         const resolvedName = options?.path ? normalizeZipPath(name, options.path) : name;
         this.name = resolvedName;
         const modTime = options?.modTime ?? new Date();
@@ -723,12 +722,6 @@ export class ZipDeflateFile {
         if (this._finalized) {
             throw new ArchiveError("Cannot push to finalized ZipDeflateFile");
         }
-        // Ensure native CRC32 is available before the first _writeDataSync call.
-        // Without this, the JS fallback is ~60x slower.
-        if (!this._syncZlibReady) {
-            ensureZlibSync();
-            this._syncZlibReady = true;
-        }
         if (this._deflateWanted === null) {
             this._accumulateSampleLen(data);
             if (!this._shouldDecide(final)) {

package/dist/esm/modules/excel/core/worksheet-core.js

@@ -4,7 +4,7 @@ import { Enums } from "./enums.js";
 import { rangeCreate, rangeRange } from "./range.js";
 import { rowCreate, rowFindCell, rowHasValues, rowValues, resolveColumnKeyValue } from "./row.js";
 import { invalidateSharedCellStyle, sharedCellFacet } from "./style-sharing.js";
-import { ExcelError, InvalidAddressError } from "../errors.js";
+import { ColumnOutOfBoundsError, ExcelError, InvalidAddressError } from "../errors.js";
 import { colCache } from "../utils/col-cache.js";
 import { copyStyle } from "../utils/copy-style.js";
 // =============================================================================
@@ -34,6 +34,40 @@ export function eachColumnKey(ws, f) {
 // =============================================================================
 // Columns
 // =============================================================================
+/**
+ * The 1-based column number for a key, a letter or a number — **without**
+ * creating the column record, unlike {@link getColumn}.
+ *
+ * A read addressed by column reference needs the number and nothing else (the
+ * cells live in the rows, not in the column record), so it resolves the
+ * reference through this instead of walking through a handle: `getColumn` pads
+ * `ws._columns` up to the column asked for, which moves `Worksheet.columns`
+ * and is a mutation on a read path — see `core/__tests__/read-side-effects.test.ts`.
+ *
+ * Unlike `getColumn` it also *validates*, so a reference that names no column
+ * fails the same way whichever form it took. Without that a numeric reference is
+ * the worst case of all: `0`, `-1`, `1.5` and `NaN` all index the cell array with
+ * something no row can hold, so the read reports an empty column rather than a
+ * bad argument.
+ */
+export function findColumnNumber(ws, c) {
+    if (typeof c === "string") {
+        // Own-property only. `ws._keys` is a plain object, so a bare `ws._keys[c]`
+        // resolves `"toString"` / `"constructor"` against `Object.prototype` and
+        // yields a function, whose `.number` is `undefined` — an unreadable column
+        // instead of an unknown key.
+        const keyed = Object.prototype.hasOwnProperty.call(ws._keys, c) ? ws._keys[c] : undefined;
+        return keyed ? keyed.number : colCache.l2n(c);
+    }
+    if (!Number.isInteger(c)) {
+        throw new ColumnOutOfBoundsError(c);
+    }
+    // `n2l` owns the 1..16384 bound and throws `ColumnOutOfBoundsError` past it,
+    // so the numeric form is rejected exactly as `l2n` rejects `"XFE"` above
+    // rather than duplicating the limit here.
+    colCache.n2l(c);
+    return c;
+}
 export function getColumn(ws, c) {
     let colNum;
     if (typeof c === "string") {
@@ -313,34 +347,58 @@ export function columnEachCell(c, optOrCallback, maybeCallback) {
     });
 }
 export function columnValues(c) {
+    return columnValuesAt(c.worksheet, c.number);
+}
+/**
+ * The values down a column, addressed by column number rather than by a handle —
+ * so a caller holding only a reference does not have to materialise the column
+ * record to read through it.
+ *
+ * `base` is the index row 1 lands on: `1` keys the array by row number and
+ * leaves an empty leading slot (what `Column.values` returns), `0` makes it a
+ * plain array (`Column.getValues`). Either way an empty cell is a hole.
+ */
+export function columnValuesAt(ws, colNumber, base = 1) {
     const v = [];
     // Deliberately not via `columnEachCell`: its callback signature demands a
     // `CellData`, so it materialises a cell on every row of the column. This is a
     // getter, so walk the rows non-destructively instead.
-    const rows = c.worksheet._rows;
+    const rows = ws._rows;
     for (let i = 0; i < rows.length; i++) {
         const row = rows[i];
         if (!row) {
             continue;
         }
-        const cell = rowFindCell(row, c.number);
+        const cell = rowFindCell(row, colNumber);
         if (cell && cellType(cell) !== Enums.ValueType.Null) {
-            v[row.number] = cellGetValue(cell);
+            v[row.number - 1 + base] = cellGetValue(cell);
         }
     }
     return v;
 }
-export function columnSetValues(c, v) {
+/**
+ * Write values down a column, addressed by column number.
+ *
+ * The array is read as **1-based by row number** when index 0 is a hole — the
+ * shape {@link columnValuesAt} hands back, so a read round-trips — and as
+ * 0-based when index 0 is present, so a plain array starts at row 1. The two
+ * cannot be told apart when a 0-based array's first slot is *also* a hole; that
+ * ambiguity is inherent to the protocol, and `rowSetValues` shares it.
+ *
+ * Only the indices the array actually carries are written: unlike
+ * `rowSetValues`, which resets the row, this leaves every other cell in the
+ * column alone.
+ */
+export function columnSetValuesAt(ws, colNumber, v) {
     if (!v) {
         return;
     }
-    const colNumber = c.number;
     let offset = 0;
     if (Object.prototype.hasOwnProperty.call(v, "0")) {
         offset = 1;
     }
     v.forEach((value, index) => {
-        cellSetValue(getCell(c.worksheet, index + offset, colNumber), value);
+        cellSetValue(getCell(ws, index + offset, colNumber), value);
     });
 }
 // =============================================================================

package/dist/esm/modules/excel/core/worksheet.js

@@ -1979,4 +1979,4 @@ function _resolveOrigin(origin, rowCount) {
 }
 // Re-export the worksheet-core container layer so `@excel/worksheet` remains the
 // canonical import path for all worksheet operations.
-export { addRow, addRows, getColumnKey, setColumnKey, deleteColumnKey, getColumn, _commitRow, findRow, findRows, getRow, getRows, eachRow, getSheetValues, findCell, getCell, getSheetName, getSheetWorkbook, getTable, getTables, rowGetCell, rowGetCellEx, rowSetValues, rowEachCell, rowSplice, rowCommit, rowSetModel, columnCreate, columnSetDefn, columnSetHeader, columnSetKey, columnEachCell, columnValues, columnSetValues, columnFromModel, columnSetNumFmt, columnSetFont, columnSetAlignment, columnSetProtection, columnSetBorder, columnSetFill, freeze, split, unfreeze, panes, setAutoFilter, autoFilter } from "./worksheet-core.js";
+export { addRow, addRows, getColumnKey, setColumnKey, deleteColumnKey, getColumn, _commitRow, findRow, findRows, getRow, getRows, eachRow, getSheetValues, findCell, getCell, getSheetName, getSheetWorkbook, getTable, getTables, rowGetCell, rowGetCellEx, rowSetValues, rowEachCell, rowSplice, rowCommit, rowSetModel, columnCreate, columnSetDefn, columnSetHeader, columnSetKey, columnEachCell, columnValues, columnSetValuesAt, columnFromModel, columnSetNumFmt, columnSetFont, columnSetAlignment, columnSetProtection, columnSetBorder, columnSetFill, freeze, split, unfreeze, panes, setAutoFilter, autoFilter } from "./worksheet-core.js";

package/dist/esm/modules/excel/surface/column.js

@@ -1,6 +1,6 @@
 import { columnAddPageBreak, columnDefn, columnHidden, columnLetter, columnOutlineLevel, columnSetHidden, columnSetOutlineLevel } from "../core/column.js";
 import { invalidateSharedCellStyle } from "../core/style-sharing.js";
-import { getColumn, columnSetHeader, columnSetKey, columnSetNumFmt, columnSetStyle } from "../core/worksheet-core.js";
+import { columnSetHeader, columnSetKey, columnSetNumFmt, columnSetStyle, columnSetValuesAt, columnValuesAt, findColumnNumber, getColumn } from "../core/worksheet-core.js";
 // --- identity ---
 /**
  * The 1-based column number for a key, letter or number.
@@ -111,6 +111,93 @@ export function setNumFmt(ws, col, value) {
 export function getDefinition(ws, col) {
     return columnDefn(getColumn(ws, col));
 }
+// --- values ---
+/**
+ * Read the values down a column as a **0-based sparse** array: the value in row
+ * 1 is at index `0`, row 2 at index `1`, and so on, and an empty cell is a hole
+ * rather than a `null`.
+ *
+ * Contrast with {@link values}, which is indexed by row *number* and therefore
+ * composes directly with the `Cell` namespace. That is also the one to pass back
+ * to {@link setValues} — see the ambiguity noted there.
+ *
+ * The read is non-destructive: it walks the rows that exist rather than asking
+ * each one for a cell, so it neither materialises cells down the column nor
+ * declares the column itself. The metadata and style accessors in this namespace
+ * resolve their reference through a column *record*, which pads
+ * `Worksheet.columns` up to the column asked for.
+ *
+ * @example
+ * ```typescript
+ * import { Column, Workbook, Worksheet } from "documonster/excel";
+ *
+ * const wb = Workbook.create();
+ * const ws = Workbook.addWorksheet(wb, "Sales");
+ * Worksheet.setColumns(ws, [{ key: "total", header: "Total" }]);
+ * Column.setValues(ws, "total", [10, 20, 30]);
+ * const [first] = Column.getValues(ws, "total"); // 10 — row 1
+ * ```
+ */
+export function getValues(ws, col) {
+    return columnValuesAt(ws, findColumnNumber(ws, col), 0);
+}
+/**
+ * Read the values down a column as a **sparse** array indexed by **row number**:
+ * index `0` is always an empty leading slot, the value in row 1 is at index `1`,
+ * and so on. This mirrors Excel's 1-based row numbering, so the index can be
+ * handed straight to the `Cell` namespace, and it is the form {@link setValues}
+ * reads back unambiguously.
+ *
+ * Use {@link getValues} when the values are wanted as a plain 0-based array. Like
+ * it, this read materialises nothing.
+ *
+ * @example
+ * ```typescript
+ * import { Cell, Column, Workbook } from "documonster/excel";
+ *
+ * const wb = Workbook.create();
+ * const ws = Workbook.addWorksheet(wb, "Sales");
+ * Column.setValues(ws, "C", [120, -40, 75]);
+ *
+ * // Colour the losses red. The index *is* the row number, and `Column.getNumber`
+ * // turns the reference into the column number `Cell` takes.
+ * const colNumber = Column.getNumber(ws, "C");
+ * Column.values(ws, "C").forEach((value, rowNumber) => {
+ *   if (typeof value === "number" && value < 0) {
+ *     Cell.setFont(ws, rowNumber, colNumber, { color: { argb: "FFC00000" } });
+ *   }
+ * });
+ * ```
+ */
+export function values(ws, col) {
+    return columnValuesAt(ws, findColumnNumber(ws, col));
+}
+/**
+ * Write values down a column. Takes anything `Cell.setValue` takes — a number, a
+ * string, a formula, rich text, a hyperlink, a `Date` or a civil `Temporal`.
+ *
+ * The array is read as **1-based by row number** when index 0 is a hole — the
+ * shape {@link values} hands back, so that read round-trips — and as **0-based**
+ * when index 0 is present, so a plain array starts at row 1:
+ *
+ * ```typescript
+ * Column.setValues(ws, "A", [1, 2, 3]); // rows 1, 2, 3
+ * Column.setValues(ws, "A", [, 1, 2, 3]); // rows 1, 2, 3 — the same thing
+ * ```
+ *
+ * The two are indistinguishable when a 0-based array's own first slot is a hole,
+ * so pass {@link values} rather than {@link getValues} when writing a read back —
+ * a `getValues` array whose row 1 was empty lands a row high. `Row.setValues` has
+ * the same ambiguity.
+ *
+ * **This writes, it does not replace.** Only the indices the array carries are
+ * touched — unlike `Row.setValues`, which resets the row — so a shorter array
+ * does not truncate the column and a value already in a row the array skips
+ * survives. Clear a cell by passing `null` at its index.
+ */
+export function setValues(ws, col, v) {
+    columnSetValuesAt(ws, findColumnNumber(ws, col), v);
+}
 // --- printing ---
 /**
  * Add a manual vertical page break to the **right** of `col`, the equivalent of

package/dist/esm/modules/excel/utils/col-cache.js

@@ -32,7 +32,12 @@ const colCache = {
         "Z"
     ],
     _l2nFill: 0,
-    _l2n: {},
+    // Prototype-less: this is keyed by caller-supplied strings, so a plain object
+    // resolves `"toString"` / `"constructor"` / `"valueOf"` against
+    // `Object.prototype` and `l2n` returns that *function* instead of throwing —
+    // the truthiness guards below both pass. A column reference named after an
+    // `Object.prototype` member then reads as a column number of `NaN`.
+    _l2n: Object.create(null),
     _n2l: [],
     _level(n) {
         if (n <= 26) {