@office-kit/xlsx 0.14.0 → 0.16.0

package/README.md

@@ -36,7 +36,7 @@ paywall.
 |------------------------|----------------------------------------------------------------------------------|-----------------------------------------------------------------------|
 | TypeScript types       | hand-written `.d.ts` retrofitted (SheetJS) or community typings (xlsx-populate, excel4node) | first-party, written in TS under `exactOptionalPropertyTypes` + `noUncheckedIndexedAccess` |
 | Bundle size            | ExcelJS unpacks to 21.8 MB; xlsx ~7.5 MB                                         | full lib ≤120 KB min+brotli (currently ~85 KB); streaming entry ~49 KB |
-| Streaming              | SheetJS docs explicitly note the zip central-directory layout prevents true streaming; ExcelJS supports both directions but the lib is heavy | both read iter and write append, with fixed-memory budget for tens of millions of rows |
+| Streaming              | SheetJS docs explicitly note the zip central-directory layout prevents true streaming; ExcelJS supports both directions but the lib is heavy | both read iter and write append, with bounded row buffering and string retention |
 | Charts (write)         | none in ExcelJS, xlsx-js-style, SheetJS CE; gated behind SheetJS Pro             | 16 legacy `c:` + 8 modern `cx:` chart kinds (Sunburst, Treemap, Waterfall, Histogram, Pareto, Funnel, BoxWhisker, RegionMap) |
 | Pivots / VBA / OLE     | ExcelJS drops pivot tables on read ([#261][exceljs-pivot]); others vary           | byte-identical passthrough so Excel 365 still renders parts we don't model |
 | Maintenance            | ExcelJS stalled since 2023; excel4node archived 2022; xlsx-js-style frozen 2022; SheetJS npm artifact frozen 2022 (still distributed via private CDN) | active                                                                |
@@ -201,7 +201,33 @@ const response = await fetch('/sheet.xlsx');
 const wb = await loadWorkbook(fromResponse(response));
 ```
 
-### Streaming write — millions of rows in a fixed memory budget
+### Add hyperlinks and comments in bulk
+
+Use `setHyperlinks` and `setComments` when many cells need links or notes. Each
+batch runs in linear time over the existing entries and additions.
+
+```ts
+import { createWorkbook, addWorksheet } from '@office-kit/xlsx/workbook';
+import { setHyperlinks, setComments } from '@office-kit/xlsx/worksheet';
+
+const wb = createWorkbook();
+const ws = addWorksheet(wb, 'Report');
+setHyperlinks(ws, [
+  { ref: 'A2', target: 'https://example.com/items/1' },
+  { ref: 'A3', target: 'https://example.com/items/2' },
+]);
+setComments(ws, [
+  { ref: 'A2', author: 'Reviewer', text: 'Verified' },
+  { ref: 'A3', author: 'Reviewer', text: 'Check the source' },
+]);
+```
+
+Entries are applied in order: replacing a hyperlink moves it to the end;
+replacing a comment keeps its position. Hyperlink entries must supply `target`
+or `location`; the entire batch is validated before the sheet is changed.
+Both APIs preserve the public arrays and allow direct edits between calls.
+
+### Streaming write — bounded row buffering and string retention
 
 ```ts
 import { createWriteOnlyWorkbook } from '@office-kit/xlsx/streaming';
@@ -211,7 +237,7 @@ const sink = toFile('big.xlsx');
 const wb = await createWriteOnlyWorkbook(sink);
 const ws = await wb.addWorksheet('Data');
 ws.setColumnWidth(1, 24); // must precede the first appendRow
-for (let r = 0; r < 10_000_000; r++) {
+for (let r = 0; r < 1_000_000; r++) {
   await ws.appendRow([r, `row-${r}`, r * Math.PI]);
 }
 await ws.close();
@@ -220,10 +246,20 @@ await wb.finalize();
 
 The streaming writer pushes each row through deflate as it arrives, and
 `toFile` forwards each deflated chunk to disk (honouring write-stream
-backpressure) — peak memory stays at one pending-row buffer plus deflate
-scratch, regardless of total archive size. The same is true of `toWritable`;
-buffered sinks (`toBuffer` / `toBlob` / `toArrayBuffer`) instead keep the
-full archive resident so `result()` can hand it back in one piece.
+backpressure). Row buffering stays at approximately 64 KiB plus the current
+row and deflate scratch. Plain and rich-text strings share a workbook-wide
+table capped at 100,000 entries and an 8 MiB accounting budget for retained
+keys and serialized XML (two bytes per UTF-16 code unit). This is a payload
+budget, not a total JavaScript heap limit. Once a new value cannot fit, all
+subsequent new values are written as inline strings; previously registered
+values still reuse their shared-string IDs, including on later sheets.
+
+Styles and sheet metadata remain resident, so keep their counts bounded when
+exporting large datasets. `toWritable` also streams output; buffered sinks
+(`toBuffer` / `toBlob` / `toArrayBuffer`) keep the full archive resident for
+`result()`. Excel allows at most 1,048,576 rows per sheet; split larger datasets
+across sheets. See [write-only string storage](docs/write-only-strings.md) for
+the storage policy and compatibility details.
 
 ### Streaming read — iterate row-by-row without materialising the sheet
 

package/dist/{cell-style-BFmJOmcx.mjs → cell-style-CNsET6WU.mjs}

@@ -1,5 +1,5 @@
 import { o as OpenXmlSchemaError } from "./exceptions-D-CFwxgm.mjs";
-import { Tn as makeColor, cn as parseRange, vn as colorToHex, y as ensureCell } from "./worksheet-4xW-i8j9.mjs";
+import { Dn as makeColor, bn as colorToHex, un as parseRange, y as ensureCell } from "./worksheet-B2NOQ6dM.mjs";
 //#region src/utils/stable-stringify.ts
 const sortKeysReplacer = (_key, value) => {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
@@ -1615,4 +1615,4 @@ function setRangeBorderBox(wb, ws, range, opts = { style: "thin" }) {
 //#endregion
 export { BUILTIN_NAMED_STYLES as $, makeAlignment as $t, setCellBorder as A, isBuiltinFormat as At, setItalic as B, PATTERN_TYPES as Bt, setBold as C, FORMAT_NUMBER_00 as Ct, setCellAsNumber as D, builtinFormatCode as Dt, setCellAsDate as E, FORMAT_TEXT as Et, setCellProtection as F, FONT_SCHEMES as Ft, setRangeNumberFormat as G, makePatternFill as Gt, setRangeBackgroundColor as H, makeFill as Ht, setCellStyle as I, UNDERLINE_STYLES as It, setRangeWrapText as J, makeBorder as Jt, setRangeProtection as K, SIDE_STYLES as Kt, setFontColor as L, VERT_ALIGNS as Lt, setCellFill as M, isTimedeltaFormat as Mt, setCellFont as N, makeNumberFormat as Nt, setCellAsPercent as O, builtinFormatId as Ot, setCellNumberFormat as P, DEFAULT_FONT as Pt, makeProtection as Q, alignmentToCss as Qt, setFontName as R, fontToCss as Rt, rotateCellText as S, FORMAT_NUMBER as St, setCellAsCurrency as T, FORMAT_PERCENTAGE_00 as Tt, setRangeBorderBox as U, makeGradientFill as Ut, setRangeAlignment as V, fillToCss as Vt, setRangeFont as W, makeGradientStop as Wt, setUnderline as X, HORIZONTAL_ALIGNMENTS as Xt, setStrikethrough as Y, makeSide as Yt, wrapCellText as Z, VERTICAL_ALIGNMENTS as Zt, getCellNumberFormat as _, BUILTIN_FORMATS_MAX_SIZE as _t, cellStyleToCss as a, addFill as at, patchCellFont as b, FORMAT_DATE_YYYYMMDD2 as bt, clearCellStyle as c, buildXfPatch as ct, copyCellStyle as d, listCellStyleXfs as dt, stableStringify as en, addNamedStyle as et, formatAsHeader as f, listCellXfs as ft, getCellFont as g, BUILTIN_FORMATS as gt, getCellFill as h, makeStylesheet as ht, applyNamedStyle as i, addCellXf as it, setCellBorderAll as j, isDateFormat as jt, setCellBackgroundColor as k, classifyDateFormat as kt, clearRangeStyle as l, defaultCellXf as lt, getCellBorder as m, listFonts as mt, alignCellVertical as n, addBorder as nt, centerCell as o, addFont as ot, getCellAlignment as p, listFills as pt, setRangeStyle as q, borderToCss as qt, applyBuiltinStyle as r, addCellStyleXf as rt, clearCellBackground as s, addNumFmt as st, alignCellHorizontal as t, ensureBuiltinStyle as tt, cloneCellStyle as u, listBorders as ut, getCellProtection as v, FORMAT_DATE_DATETIME as vt, setCellAlignment as w, FORMAT_PERCENTAGE as wt, registerCellStyle as x, FORMAT_GENERAL as xt, indentCell as y, FORMAT_DATE_TIMEDELTA as yt, setFontSize as z, makeFont as zt };
 
-//# sourceMappingURL=cell-style-BFmJOmcx.mjs.map
+//# sourceMappingURL=cell-style-CNsET6WU.mjs.map