xls-codec 4.9.0 → 4.11.0

package/dist/workbook/sheet-writer.cjs

@@ -8,8 +8,11 @@ const require_serial = require("../serial.cjs");
 const require_biff_builder = require("../biff/builder.cjs");
 const require_biff_record_writer = require("../biff/record-writer.cjs");
 const require_biff_bof_writer = require("../biff/bof-writer.cjs");
+const require_biff_string_writer = require("../biff/string-writer.cjs");
 const require_workbook_globals_writer = require("./globals-writer.cjs");
+const require_biff_ptg_writer = require("../biff/ptg-writer.cjs");
 const require_written_cells = require("../written-cells.cjs");
+const require_workbook_comment_writer = require("./comment-writer.cjs");
 //#region src/workbook/sheet-writer.ts
 /** BIFF8's own 16-bit row index and 8-bit column index ceilings ([MS-XLS] 2.4.221's Rw structure and 2.4.53's Col256U structure): 65536 rows (0-65535), 256 columns (0-255) -- unlike xlsx's much larger grid. A cell outside this range cannot be expressed in BIFF8 at all, so it is refused rather than silently truncated into a wrapped index. */
 const MAX_ROW_INDEX = 65535;
@@ -241,7 +244,50 @@ function writeCellValueRecord(cell, xfIndex, ctx) {
 			return require_biff_record_writer.writeRecord(513, cellHeader(cell, xfIndex).build());
 	}
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+/** [MS-XLS] 2.4.127's own FormulaValue tag vocabulary, restated here from workbook/sheet.ts's own read-side constants (not shared across the read/write boundary, matching this package's existing per-direction module convention): a cached result that is not a plain number tags byte 6-7 as 0xFFFF and names its own kind in byte 0. */
+const FORMULA_VALUE_TAGGED = 65535;
+const FORMULA_VALUE_STRING = 0;
+const FORMULA_VALUE_BOOLEAN = 1;
+const FORMULA_VALUE_ERROR = 2;
+/** The 8-byte FormulaValue field for a cached result that is not a plain number: byte 0 names which of string/boolean/error it is, byte 2 carries a boolean's own 0/1 or an error's own BIFF8 code, and the trailing u16 is the FORMULA_VALUE_TAGGED marker every reader checks for before trusting the field as a literal IEEE 754 double. */
+function taggedFormulaValueBytes(tag, valueByte) {
+	return new require_biff_builder.RecordBuilder().u8(tag).u8(0).u8(valueByte).u8(0).u16(0).u16(FORMULA_VALUE_TAGGED).build();
+}
+/** The Formula record's own 8-byte FormulaValue field for `cell.value` -- a plain little-endian f64 of the cell's own numeric/temporal serial for every numeric-shaped kind, or one of the tagged shapes above for a string, boolean, or error result. `empty` has no BIFF8 encoding that this package's own reader reads back as `empty` (a tagged-blank result reads back as an empty STRING, not an empty cell -- see workbook/sheet.ts's own taggedFormulaValue), so a formula whose value resolves to `empty` is refused outright rather than written as something the round trip would silently change the kind of. */
+function formulaValueBytes(cell) {
+	const value = cell.value;
+	switch (value.kind) {
+		case "number":
+		case "percentage":
+		case "currency": return new require_biff_builder.RecordBuilder().f64(value.value).build();
+		case "date": return new require_biff_builder.RecordBuilder().f64(require_serial.isoDateToSerial(value.value, false)).build();
+		case "time": return new require_biff_builder.RecordBuilder().f64(require_serial.isoTimeToSerial(value.value)).build();
+		case "dateTime": return new require_biff_builder.RecordBuilder().f64(require_serial.isoDateTimeToSerial(value.value, false)).build();
+		case "boolean": return taggedFormulaValueBytes(FORMULA_VALUE_BOOLEAN, value.value ? 1 : 0);
+		case "error": {
+			const code = require_biff_errors.errorCodeOf(value.value);
+			if (code === void 0) throw new require_biff_write_errors.BiffWriteError(`cell at row ${cell.row}, column ${cell.column} carries a formula whose cached result is error text ${JSON.stringify(value.value)}, which is not one of the eight error values [MS-XLS] 2.5.10 defines`);
+			return taggedFormulaValueBytes(FORMULA_VALUE_ERROR, code);
+		}
+		case "string": return taggedFormulaValueBytes(FORMULA_VALUE_STRING, 0);
+		case "empty": throw new require_biff_write_errors.BiffWriteError(`cell at row ${cell.row}, column ${cell.column} carries a formula whose value resolves to an empty cell, which this writer cannot express as a Formula record's cached result`);
+	}
+}
+/** Formula ([MS-XLS] 2.4.127): a Cell, the 8-byte FormulaValue above, a flags word and a 4-byte calculation cache this writer has no data for (both written zero -- see the module comment on RECORD_CALCCOUNT and friends for the same "nothing this schema models" reasoning), then a CellParsedFormula -- a two-byte cce and that many bytes of compiled Ptg tokens from biff/ptg-writer.ts's own compileFormulaText. Never carries an RgbExtra trailer: this writer's formula compiler refuses any construct (an array-constant literal, a shared/array formula) that would need one, so cce always accounts for the whole of rgce. A string-kind result is followed by a String record ([MS-XLS] 2.4.268) carrying the cached text, exactly as workbook/sheet.ts's own reader expects to find it. */
+function writeFormulaRecords(cell, xfIndex) {
+	const formula = cell.formula;
+	if (formula === void 0) throw new require_biff_write_errors.BiffWriteError(`internal error: writeFormulaRecords was called for the cell at row ${cell.row}, column ${cell.column}, which carries no formula`);
+	const rgce = require_biff_ptg_writer.compileFormulaText(formula);
+	const data = cellHeader(cell, xfIndex).bytes(formulaValueBytes(cell)).u16(0).u32(0).u16(rgce.length).bytes(rgce).build();
+	const records = [require_biff_record_writer.writeRecord(6, data)];
+	if (cell.value.kind === "string") records.push(require_biff_record_writer.writeRecord(519, require_biff_string_writer.writeXLUnicodeString(cell.value.value)));
+	return records;
+}
+/** The one or two records one cell contributes to the worksheet substream's cell table -- a Formula record (plus its String result, for a string-kind cell) when the cell carries a formula, the plain value record from writeCellValueRecord otherwise. */
+function writeCellRecords(cell, xfIndex, ctx) {
+	return cell.formula !== void 0 ? writeFormulaRecords(cell, xfIndex) : [writeCellValueRecord(cell, xfIndex, ctx)];
+}
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
 function buildWorksheetSubstream(sheet, ctx) {
 	for (const cell of sheet.cells) checkedCellPosition(cell);
 	const writtenCells = sheet.cells.filter(require_written_cells.writesCellRecord);
@@ -265,11 +311,13 @@ function buildWorksheetSubstream(sheet, ctx) {
 		pieces.push(writeRowRecord(rowIndex, cellsInRow, declaredRows.get(rowIndex)));
 		for (const cell of cellsInRow) {
 			const xfIndex = ctx.xfIndexForCell(cell);
-			pieces.push(writeCellValueRecord(cell, xfIndex, ctx));
+			pieces.push(...writeCellRecords(cell, xfIndex, ctx));
 		}
 	}
 	const merges = mergedRangesOf(sheet.cells);
 	if (merges.length > 0) pieces.push(writeMergeCellsRecord(merges));
+	const commentedCells = sheet.cells.filter((cell) => cell.comment !== void 0);
+	if (commentedCells.length > 0) pieces.push(...require_workbook_comment_writer.writeSheetComments(commentedCells));
 	pieces.push(require_biff_record_writer.writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
 	return require_biff_record_writer.concatRecords(...pieces);
 }

package/dist/workbook/sheet-writer.d.cts

@@ -6,7 +6,7 @@ interface SheetWriteContext {
   /** The shared string table index for a string cell's own text; every string a sheet writes must already be registered in the workbook-wide table before this is called. */
   sstIndexFor(text: string): number;
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
 declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext): Uint8Array<ArrayBuffer>;
 //#endregion
 export { SheetWriteContext, buildWorksheetSubstream };

package/dist/workbook/sheet-writer.d.ts

@@ -6,7 +6,7 @@ interface SheetWriteContext {
   /** The shared string table index for a string cell's own text; every string a sheet writes must already be registered in the workbook-wide table before this is called. */
   sstIndexFor(text: string): number;
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
 declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext): Uint8Array<ArrayBuffer>;
 //#endregion
 export { SheetWriteContext, buildWorksheetSubstream };

package/dist/workbook/sheet-writer.js

@@ -7,8 +7,11 @@ import { isoDateTimeToSerial, isoDateToSerial, isoTimeToSerial } from "../serial
 import { RecordBuilder } from "../biff/builder.js";
 import { concatRecords, writeRecord } from "../biff/record-writer.js";
 import { writeBofData } from "../biff/bof-writer.js";
+import { writeXLUnicodeString } from "../biff/string-writer.js";
 import { GENERAL_CELL_XF_INDEX } from "./globals-writer.js";
+import { compileFormulaText } from "../biff/ptg-writer.js";
 import { cellCarriesFormatting, writesCellRecord } from "../written-cells.js";
+import { writeSheetComments } from "./comment-writer.js";
 //#region src/workbook/sheet-writer.ts
 /** BIFF8's own 16-bit row index and 8-bit column index ceilings ([MS-XLS] 2.4.221's Rw structure and 2.4.53's Col256U structure): 65536 rows (0-65535), 256 columns (0-255) -- unlike xlsx's much larger grid. A cell outside this range cannot be expressed in BIFF8 at all, so it is refused rather than silently truncated into a wrapped index. */
 const MAX_ROW_INDEX = 65535;
@@ -240,7 +243,50 @@ function writeCellValueRecord(cell, xfIndex, ctx) {
 			return writeRecord(513, cellHeader(cell, xfIndex).build());
 	}
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+/** [MS-XLS] 2.4.127's own FormulaValue tag vocabulary, restated here from workbook/sheet.ts's own read-side constants (not shared across the read/write boundary, matching this package's existing per-direction module convention): a cached result that is not a plain number tags byte 6-7 as 0xFFFF and names its own kind in byte 0. */
+const FORMULA_VALUE_TAGGED = 65535;
+const FORMULA_VALUE_STRING = 0;
+const FORMULA_VALUE_BOOLEAN = 1;
+const FORMULA_VALUE_ERROR = 2;
+/** The 8-byte FormulaValue field for a cached result that is not a plain number: byte 0 names which of string/boolean/error it is, byte 2 carries a boolean's own 0/1 or an error's own BIFF8 code, and the trailing u16 is the FORMULA_VALUE_TAGGED marker every reader checks for before trusting the field as a literal IEEE 754 double. */
+function taggedFormulaValueBytes(tag, valueByte) {
+	return new RecordBuilder().u8(tag).u8(0).u8(valueByte).u8(0).u16(0).u16(FORMULA_VALUE_TAGGED).build();
+}
+/** The Formula record's own 8-byte FormulaValue field for `cell.value` -- a plain little-endian f64 of the cell's own numeric/temporal serial for every numeric-shaped kind, or one of the tagged shapes above for a string, boolean, or error result. `empty` has no BIFF8 encoding that this package's own reader reads back as `empty` (a tagged-blank result reads back as an empty STRING, not an empty cell -- see workbook/sheet.ts's own taggedFormulaValue), so a formula whose value resolves to `empty` is refused outright rather than written as something the round trip would silently change the kind of. */
+function formulaValueBytes(cell) {
+	const value = cell.value;
+	switch (value.kind) {
+		case "number":
+		case "percentage":
+		case "currency": return new RecordBuilder().f64(value.value).build();
+		case "date": return new RecordBuilder().f64(isoDateToSerial(value.value, false)).build();
+		case "time": return new RecordBuilder().f64(isoTimeToSerial(value.value)).build();
+		case "dateTime": return new RecordBuilder().f64(isoDateTimeToSerial(value.value, false)).build();
+		case "boolean": return taggedFormulaValueBytes(FORMULA_VALUE_BOOLEAN, value.value ? 1 : 0);
+		case "error": {
+			const code = errorCodeOf(value.value);
+			if (code === void 0) throw new BiffWriteError(`cell at row ${cell.row}, column ${cell.column} carries a formula whose cached result is error text ${JSON.stringify(value.value)}, which is not one of the eight error values [MS-XLS] 2.5.10 defines`);
+			return taggedFormulaValueBytes(FORMULA_VALUE_ERROR, code);
+		}
+		case "string": return taggedFormulaValueBytes(FORMULA_VALUE_STRING, 0);
+		case "empty": throw new BiffWriteError(`cell at row ${cell.row}, column ${cell.column} carries a formula whose value resolves to an empty cell, which this writer cannot express as a Formula record's cached result`);
+	}
+}
+/** Formula ([MS-XLS] 2.4.127): a Cell, the 8-byte FormulaValue above, a flags word and a 4-byte calculation cache this writer has no data for (both written zero -- see the module comment on RECORD_CALCCOUNT and friends for the same "nothing this schema models" reasoning), then a CellParsedFormula -- a two-byte cce and that many bytes of compiled Ptg tokens from biff/ptg-writer.ts's own compileFormulaText. Never carries an RgbExtra trailer: this writer's formula compiler refuses any construct (an array-constant literal, a shared/array formula) that would need one, so cce always accounts for the whole of rgce. A string-kind result is followed by a String record ([MS-XLS] 2.4.268) carrying the cached text, exactly as workbook/sheet.ts's own reader expects to find it. */
+function writeFormulaRecords(cell, xfIndex) {
+	const formula = cell.formula;
+	if (formula === void 0) throw new BiffWriteError(`internal error: writeFormulaRecords was called for the cell at row ${cell.row}, column ${cell.column}, which carries no formula`);
+	const rgce = compileFormulaText(formula);
+	const data = cellHeader(cell, xfIndex).bytes(formulaValueBytes(cell)).u16(0).u32(0).u16(rgce.length).bytes(rgce).build();
+	const records = [writeRecord(6, data)];
+	if (cell.value.kind === "string") records.push(writeRecord(519, writeXLUnicodeString(cell.value.value)));
+	return records;
+}
+/** The one or two records one cell contributes to the worksheet substream's cell table -- a Formula record (plus its String result, for a string-kind cell) when the cell carries a formula, the plain value record from writeCellValueRecord otherwise. */
+function writeCellRecords(cell, xfIndex, ctx) {
+	return cell.formula !== void 0 ? writeFormulaRecords(cell, xfIndex) : [writeCellValueRecord(cell, xfIndex, ctx)];
+}
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
 function buildWorksheetSubstream(sheet, ctx) {
 	for (const cell of sheet.cells) checkedCellPosition(cell);
 	const writtenCells = sheet.cells.filter(writesCellRecord);
@@ -264,11 +310,13 @@ function buildWorksheetSubstream(sheet, ctx) {
 		pieces.push(writeRowRecord(rowIndex, cellsInRow, declaredRows.get(rowIndex)));
 		for (const cell of cellsInRow) {
 			const xfIndex = ctx.xfIndexForCell(cell);
-			pieces.push(writeCellValueRecord(cell, xfIndex, ctx));
+			pieces.push(...writeCellRecords(cell, xfIndex, ctx));
 		}
 	}
 	const merges = mergedRangesOf(sheet.cells);
 	if (merges.length > 0) pieces.push(writeMergeCellsRecord(merges));
+	const commentedCells = sheet.cells.filter((cell) => cell.comment !== void 0);
+	if (commentedCells.length > 0) pieces.push(...writeSheetComments(commentedCells));
 	pieces.push(writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
 	return concatRecords(...pieces);
 }

package/dist/written-cells.cjs

@@ -14,12 +14,12 @@ function cellCarriesFormatting(cell) {
 	return borders.left !== void 0 || borders.right !== void 0 || borders.top !== void 0 || borders.bottom !== void 0;
 }
 /**
-* Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+* Whether the writer emits a cell record for this cell: a value record for anything carrying a value, a Formula record for anything carrying a formula, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
 *
-* An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+* An unformatted empty cell with no formula is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them. A formula is the identical case one level up: it lives only in a Formula record, so a cell carrying one is never dropped regardless of what its own cached `value` resolves to, even where that value alone would otherwise not have earned a record.
 */
 function writesCellRecord(cell) {
-	return cell.value.kind !== "empty" || cellCarriesFormatting(cell);
+	return cell.value.kind !== "empty" || cellCarriesFormatting(cell) || cell.formula !== void 0;
 }
 //#endregion
 exports.cellCarriesFormatting = cellCarriesFormatting;

package/dist/written-cells.d.cts

@@ -7,9 +7,9 @@ import { ContentSheetCell } from "document-schema.js";
  */
 declare function cellCarriesFormatting(cell: ContentSheetCell): boolean;
 /**
- * Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+ * Whether the writer emits a cell record for this cell: a value record for anything carrying a value, a Formula record for anything carrying a formula, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
  *
- * An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+ * An unformatted empty cell with no formula is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them. A formula is the identical case one level up: it lives only in a Formula record, so a cell carrying one is never dropped regardless of what its own cached `value` resolves to, even where that value alone would otherwise not have earned a record.
  */
 declare function writesCellRecord(cell: ContentSheetCell): boolean;
 //#endregion

package/dist/written-cells.d.ts

@@ -7,9 +7,9 @@ import { ContentSheetCell } from "document-schema.js";
  */
 declare function cellCarriesFormatting(cell: ContentSheetCell): boolean;
 /**
- * Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+ * Whether the writer emits a cell record for this cell: a value record for anything carrying a value, a Formula record for anything carrying a formula, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
  *
- * An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+ * An unformatted empty cell with no formula is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them. A formula is the identical case one level up: it lives only in a Formula record, so a cell carrying one is never dropped regardless of what its own cached `value` resolves to, even where that value alone would otherwise not have earned a record.
  */
 declare function writesCellRecord(cell: ContentSheetCell): boolean;
 //#endregion

package/dist/written-cells.js

@@ -13,12 +13,12 @@ function cellCarriesFormatting(cell) {
 	return borders.left !== void 0 || borders.right !== void 0 || borders.top !== void 0 || borders.bottom !== void 0;
 }
 /**
-* Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+* Whether the writer emits a cell record for this cell: a value record for anything carrying a value, a Formula record for anything carrying a formula, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
 *
-* An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+* An unformatted empty cell with no formula is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them. A formula is the identical case one level up: it lives only in a Formula record, so a cell carrying one is never dropped regardless of what its own cached `value` resolves to, even where that value alone would otherwise not have earned a record.
 */
 function writesCellRecord(cell) {
-	return cell.value.kind !== "empty" || cellCarriesFormatting(cell);
+	return cell.value.kind !== "empty" || cellCarriesFormatting(cell) || cell.formula !== void 0;
 }
 //#endregion
 export { cellCarriesFormatting, writesCellRecord };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xls-codec",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "description": "Hand-written reader for the legacy Excel Binary File Format (.xls, BIFF8) as specified by [MS-XLS], mapping a workbook's record stream onto the shared document-schema.js spreadsheet model - the .xls codec for the documents.js family.",
   "type": "module",
   "repository": {
@@ -70,7 +70,7 @@
   },
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "archive-codec": "1.9.2",
+    "archive-codec": "1.10.0",
     "document-schema.js": "7.5.0",
     "excel-number-format": "1.1.1"
   },