xls-codec 0.0.0 → 1.0.1

package/dist/workbook/sheet.d.cts

@@ -0,0 +1,58 @@
+import { RecordGroup } from "../biff/substreams.cjs";
+//#region src/workbook/sheet.d.ts
+/** A cell's value as its own record carries it, before number-format classification decides whether a number is really a date, a percentage, or an amount of money. */
+type RawCellValue = {
+  kind: "number";
+  value: number;
+} | {
+  kind: "string";
+  value: string;
+} | {
+  kind: "boolean";
+  value: boolean;
+} | {
+  kind: "error";
+  value: string;
+} | {
+  kind: "blank";
+};
+/** One cell of the cell table. */
+interface RawCell {
+  readonly row: number;
+  readonly column: number;
+  /** The cell's own ixfe ([MS-XLS] 2.5.168): an index into the globals substream's XF table. */
+  readonly xfIndex: number;
+  readonly value: RawCellValue;
+  /** True when the value is a Formula record's CACHED result rather than a literal. The formula expression itself is not read: BIFF8 stores it as a compiled Ptg token stream, not as text. */
+  readonly fromFormula: boolean;
+}
+interface RawRow {
+  readonly index: number;
+  /** The row's declared height in points, absent when the record declared none. */
+  readonly heightPt?: number;
+  readonly hidden: boolean;
+}
+interface RawColumn {
+  readonly index: number;
+  readonly widthPt?: number;
+  readonly hidden: boolean;
+}
+interface RawRange {
+  readonly startRow: number;
+  readonly startColumn: number;
+  readonly endRow: number;
+  readonly endColumn: number;
+}
+/** One worksheet's records, read but not yet mapped onto the shared schema. */
+interface RawSheet {
+  readonly cells: readonly RawCell[];
+  readonly rows: readonly RawRow[];
+  readonly columns: readonly RawColumn[];
+  readonly merges: readonly RawRange[];
+  /** The used range from the Dimensions record ([MS-XLS] 2.4.90), when the sheet declared one. */
+  readonly usedRange?: RawRange;
+}
+/** Reads one worksheet substream's records. */
+declare function readSheetRecords(records: readonly RecordGroup[], sharedStrings: readonly string[]): RawSheet;
+//#endregion
+export { RawCell, RawCellValue, RawColumn, RawRange, RawRow, RawSheet, readSheetRecords };

package/dist/workbook/sheet.d.ts

@@ -0,0 +1,58 @@
+import { RecordGroup } from "../biff/substreams.js";
+//#region src/workbook/sheet.d.ts
+/** A cell's value as its own record carries it, before number-format classification decides whether a number is really a date, a percentage, or an amount of money. */
+type RawCellValue = {
+  kind: "number";
+  value: number;
+} | {
+  kind: "string";
+  value: string;
+} | {
+  kind: "boolean";
+  value: boolean;
+} | {
+  kind: "error";
+  value: string;
+} | {
+  kind: "blank";
+};
+/** One cell of the cell table. */
+interface RawCell {
+  readonly row: number;
+  readonly column: number;
+  /** The cell's own ixfe ([MS-XLS] 2.5.168): an index into the globals substream's XF table. */
+  readonly xfIndex: number;
+  readonly value: RawCellValue;
+  /** True when the value is a Formula record's CACHED result rather than a literal. The formula expression itself is not read: BIFF8 stores it as a compiled Ptg token stream, not as text. */
+  readonly fromFormula: boolean;
+}
+interface RawRow {
+  readonly index: number;
+  /** The row's declared height in points, absent when the record declared none. */
+  readonly heightPt?: number;
+  readonly hidden: boolean;
+}
+interface RawColumn {
+  readonly index: number;
+  readonly widthPt?: number;
+  readonly hidden: boolean;
+}
+interface RawRange {
+  readonly startRow: number;
+  readonly startColumn: number;
+  readonly endRow: number;
+  readonly endColumn: number;
+}
+/** One worksheet's records, read but not yet mapped onto the shared schema. */
+interface RawSheet {
+  readonly cells: readonly RawCell[];
+  readonly rows: readonly RawRow[];
+  readonly columns: readonly RawColumn[];
+  readonly merges: readonly RawRange[];
+  /** The used range from the Dimensions record ([MS-XLS] 2.4.90), when the sheet declared one. */
+  readonly usedRange?: RawRange;
+}
+/** Reads one worksheet substream's records. */
+declare function readSheetRecords(records: readonly RecordGroup[], sharedStrings: readonly string[]): RawSheet;
+//#endregion
+export { RawCell, RawCellValue, RawColumn, RawRange, RawRow, RawSheet, readSheetRecords };

package/dist/workbook/sheet.js

@@ -0,0 +1,371 @@
+import "../biff/record-types.js";
+import { BiffFormatError } from "../biff/records.js";
+import { BlockCursor } from "../biff/cursor.js";
+import { readXLUnicodeString } from "../biff/strings.js";
+import { errorTextOf } from "../biff/errors.js";
+import { decodeRkNumber } from "../biff/rk.js";
+import { columnWidthToPoints, twipsToPoints } from "../units.js";
+//#region src/workbook/sheet.ts
+/** Row record flag bits, in the 32-bit field following unused1 ([MS-XLS] 2.4.221). */
+const ROW_FLAG_HIDDEN = 32;
+/** fUnsynced: the row height was set manually. When clear the height is the sheet default rather than a per-row declaration. */
+const ROW_FLAG_UNSYNCED = 64;
+/** ColInfo flag bits ([MS-XLS] 2.4.53). */
+const COLINFO_FLAG_HIDDEN = 1;
+/** A FormulaValue whose fExprO field is this is not an Xnum but a tagged non-numeric value ([MS-XLS] 2.5.133). */
+const FORMULA_VALUE_TAGGED = 65535;
+/** The tag byte's own vocabulary in that case. */
+const FORMULA_VALUE_STRING = 0;
+const FORMULA_VALUE_BOOLEAN = 1;
+const FORMULA_VALUE_ERROR = 2;
+const FORMULA_VALUE_BLANK = 3;
+/** MulRk carries rw, colFirst, N six-byte RkRecs, then colLast; MulBlank the same with two-byte ixfe entries. */
+const MUL_FIXED_BYTES = 6;
+const MULRK_ENTRY_BYTES = 6;
+const MULBLANK_ENTRY_BYTES = 2;
+/** Reads one worksheet substream's records. */
+function readSheetRecords(records, sharedStrings) {
+	const cells = [];
+	const rows = [];
+	const columns = [];
+	const merges = [];
+	let usedRange;
+	for (let index = 0; index < records.length; index += 1) {
+		const record = records[index];
+		if (record === void 0) continue;
+		switch (record.type) {
+			case 512:
+				usedRange = readDimensions(record);
+				break;
+			case 520:
+				rows.push(readRow(record));
+				break;
+			case 125:
+				columns.push(...readColInfo(record));
+				break;
+			case 229:
+				merges.push(...readMergeCells(record));
+				break;
+			case 513:
+				cells.push(readBlank(record));
+				break;
+			case 190:
+				cells.push(...readMulBlank(record));
+				break;
+			case 638:
+				cells.push(readRk(record));
+				break;
+			case 189:
+				cells.push(...readMulRk(record));
+				break;
+			case 515:
+				cells.push(readNumber(record));
+				break;
+			case 517: {
+				const cell = readBoolErr(record);
+				if (cell !== void 0) cells.push(cell);
+				break;
+			}
+			case 253:
+				cells.push(readLabelSst(record, sharedStrings));
+				break;
+			case 516:
+				cells.push(readLabel(record));
+				break;
+			case 6: cells.push(readFormula(record, stringResultAfter(records, index)));
+		}
+	}
+	return usedRange === void 0 ? {
+		cells,
+		rows,
+		columns,
+		merges
+	} : {
+		cells,
+		rows,
+		columns,
+		merges,
+		usedRange
+	};
+}
+/**
+* Finds the String record carrying a Formula's cached string result, if it has one.
+*
+* [MS-XLS] 2.5.133 says the String "immediately follows" the Formula, but the FORMULA production of [MS-XLS] 2.1.7.20.6 is wider than that -- `[Uncalced] Formula [Array / Table / ShrFmla / SUB] [String *Continue]` -- so an array formula, a data table, or a member of a shared-formula run puts one record in between. Skipping exactly those three finds the String in both shapes; anything else ends the search, so a Formula with no string result never reaches past its own cell into the next one's records.
+*/
+function stringResultAfter(records, formulaIndex) {
+	for (let index = formulaIndex + 1; index < records.length; index += 1) {
+		const candidate = records[index];
+		if (candidate === void 0) return;
+		if (candidate.type === 519) return candidate;
+		if (candidate.type !== 545 && candidate.type !== 566 && candidate.type !== 1212) return;
+	}
+}
+/** Dimensions ([MS-XLS] 2.4.90): a four-byte first row, a four-byte past-the-end row, a two-byte first column, and a two-byte past-the-end column. */
+function readDimensions(record) {
+	const cursor = new BlockCursor(record.blocks);
+	const rwMic = cursor.u32();
+	const rwMac = cursor.u32();
+	const colMic = cursor.u16();
+	const colMac = cursor.u16();
+	if (rwMac === 0 || colMac === 0) return;
+	return {
+		startRow: rwMic,
+		startColumn: colMic,
+		endRow: rwMac - 1,
+		endColumn: colMac - 1
+	};
+}
+/** Row ([MS-XLS] 2.4.221): sixteen bytes, of which this reader uses the index, the height, and the hidden and manually-set flags. */
+function readRow(record) {
+	const cursor = new BlockCursor(record.blocks);
+	const index = cursor.u16();
+	cursor.skip(4);
+	const heightTwips = cursor.u16();
+	cursor.skip(4);
+	const flags = cursor.u8();
+	const hidden = (flags & ROW_FLAG_HIDDEN) !== 0;
+	const declared = (flags & ROW_FLAG_UNSYNCED) !== 0;
+	const heightPt = twipsToPoints(heightTwips);
+	return declared && heightPt > 0 ? {
+		index,
+		heightPt,
+		hidden
+	} : {
+		index,
+		hidden
+	};
+}
+/** ColInfo ([MS-XLS] 2.4.53): one record covering an inclusive RANGE of columns, so it expands to one entry per column it names. */
+function readColInfo(record) {
+	const cursor = new BlockCursor(record.blocks);
+	const first = cursor.u16();
+	const last = cursor.u16();
+	const coldx = cursor.u16();
+	cursor.skip(2);
+	const hidden = (cursor.u16() & COLINFO_FLAG_HIDDEN) !== 0;
+	const widthPt = columnWidthToPoints(coldx);
+	const columns = [];
+	const end = Math.min(last, 255);
+	for (let index = first; index <= end; index += 1) columns.push(widthPt > 0 ? {
+		index,
+		widthPt,
+		hidden
+	} : {
+		index,
+		hidden
+	});
+	return columns;
+}
+/** MergeCells ([MS-XLS] 2.4.168): a count then that many Ref8 structures ([MS-XLS] 2.5.208), each an inclusive row and column range. */
+function readMergeCells(record) {
+	const cursor = new BlockCursor(record.blocks);
+	const count = cursor.u16();
+	const ranges = [];
+	for (let index = 0; index < count; index += 1) {
+		const startRow = cursor.u16();
+		const endRow = cursor.u16();
+		const startColumn = cursor.u16();
+		const endColumn = cursor.u16();
+		ranges.push({
+			startRow,
+			startColumn,
+			endRow,
+			endColumn
+		});
+	}
+	return ranges;
+}
+/** The Cell structure ([MS-XLS] 2.5.19) every single-cell record opens with. */
+function readCellHeader(cursor) {
+	return {
+		row: cursor.u16(),
+		column: cursor.u16(),
+		xfIndex: cursor.u16()
+	};
+}
+function readBlank(record) {
+	return {
+		...readCellHeader(new BlockCursor(record.blocks)),
+		value: { kind: "blank" },
+		fromFormula: false
+	};
+}
+/** MulBlank ([MS-XLS] 2.4.174): a run of blank cells in one row, each with its own format index. The entry count is derived from the record's own length rather than from colLast, which sits AFTER the variable-length array. */
+function readMulBlank(record) {
+	const cursor = new BlockCursor(record.blocks);
+	const row = cursor.u16();
+	const first = cursor.u16();
+	const count = mulEntryCount(record, MULBLANK_ENTRY_BYTES);
+	const cells = [];
+	for (let offset = 0; offset < count; offset += 1) cells.push({
+		row,
+		column: first + offset,
+		xfIndex: cursor.u16(),
+		value: { kind: "blank" },
+		fromFormula: false
+	});
+	return cells;
+}
+function readRk(record) {
+	const cursor = new BlockCursor(record.blocks);
+	return {
+		row: cursor.u16(),
+		column: cursor.u16(),
+		xfIndex: cursor.u16(),
+		value: {
+			kind: "number",
+			value: decodeRkNumber(cursor.u32())
+		},
+		fromFormula: false
+	};
+}
+/** MulRk ([MS-XLS] 2.4.175): a run of RK-encoded numeric cells in one row, each an RkRec ([MS-XLS] 2.5.218) of a format index and an RK word. */
+function readMulRk(record) {
+	const cursor = new BlockCursor(record.blocks);
+	const row = cursor.u16();
+	const first = cursor.u16();
+	const count = mulEntryCount(record, MULRK_ENTRY_BYTES);
+	const cells = [];
+	for (let offset = 0; offset < count; offset += 1) {
+		const xfIndex = cursor.u16();
+		cells.push({
+			row,
+			column: first + offset,
+			xfIndex,
+			value: {
+				kind: "number",
+				value: decodeRkNumber(cursor.u32())
+			},
+			fromFormula: false
+		});
+	}
+	return cells;
+}
+/** Both Mul records put colLast after their variable-length array, so the entry count follows from the record's own length: total = rw + colFirst + N*entry + colLast. */
+function mulEntryCount(record, entryBytes) {
+	const total = record.blocks.reduce((sum, block) => sum + block.length, 0);
+	const payload = total - MUL_FIXED_BYTES;
+	if (payload < 0 || payload % entryBytes !== 0) throw new BiffFormatError(`multiple-cell record of ${total} bytes does not hold a whole number of ${entryBytes}-byte entries`);
+	return payload / entryBytes;
+}
+function readNumber(record) {
+	const cursor = new BlockCursor(record.blocks);
+	return {
+		...readCellHeader(cursor),
+		value: {
+			kind: "number",
+			value: cursor.f64()
+		},
+		fromFormula: false
+	};
+}
+/** BoolErr ([MS-XLS] 2.4.24): a Cell then a Bes ([MS-XLS] 2.5.10), whose second byte says whether the first is a boolean or an error code. An error code the specification does not define yields no cell at all rather than a fabricated spelling. */
+function readBoolErr(record) {
+	const cursor = new BlockCursor(record.blocks);
+	const header = readCellHeader(cursor);
+	const value = cursor.u8();
+	if (!(cursor.u8() !== 0)) return {
+		...header,
+		value: {
+			kind: "boolean",
+			value: value !== 0
+		},
+		fromFormula: false
+	};
+	const text = errorTextOf(value);
+	return text === void 0 ? void 0 : {
+		...header,
+		value: {
+			kind: "error",
+			value: text
+		},
+		fromFormula: false
+	};
+}
+/** LabelSst ([MS-XLS] 2.4.149): a Cell then a four-byte index into the shared string table. An index the table does not hold yields an empty string rather than throwing, since one dangling index should not fail a whole workbook. */
+function readLabelSst(record, sharedStrings) {
+	const cursor = new BlockCursor(record.blocks);
+	const header = readCellHeader(cursor);
+	const index = cursor.u32();
+	return {
+		...header,
+		value: {
+			kind: "string",
+			value: sharedStrings[index] ?? ""
+		},
+		fromFormula: false
+	};
+}
+/**
+* Label ([MS-XLS] 2.4.148): a Cell then an inline XLUnicodeString.
+*
+* In BIFF8 proper a string cell is a LabelSst indexing the shared string table, and [MS-XLS] documents this record in its charting sense. It is read as a string cell anyway because the layout is identical either way and third-party producers -- and files converted up from BIFF5, where Label WAS the string cell record -- still emit it in a worksheet's cell table, where reading it costs nothing and skipping it would silently drop real text.
+*/
+function readLabel(record) {
+	const cursor = new BlockCursor(record.blocks);
+	return {
+		...readCellHeader(cursor),
+		value: {
+			kind: "string",
+			value: readXLUnicodeString(cursor)
+		},
+		fromFormula: false
+	};
+}
+/**
+* Formula ([MS-XLS] 2.4.127): a Cell, an eight-byte FormulaValue, flags, a calculation cache, then the compiled expression.
+*
+* Only the cached VALUE is read. The expression is a CellParsedFormula -- a compiled Ptg token stream rather than text -- and turning one back into a formula string means implementing the whole Ptg vocabulary plus shared-formula and external-reference resolution, which is its own substantial piece of work. So the cell's displayed value is correct and its `formula` field stays absent, rather than a plausible-looking expression being invented for it.
+*/
+function readFormula(record, next) {
+	const cursor = new BlockCursor(record.blocks);
+	const header = readCellHeader(cursor);
+	const bytes = cursor.take(8);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (!(view.getUint16(6, true) === FORMULA_VALUE_TAGGED)) return {
+		...header,
+		value: {
+			kind: "number",
+			value: view.getFloat64(0, true)
+		},
+		fromFormula: true
+	};
+	return {
+		...header,
+		value: taggedFormulaValue(view, next),
+		fromFormula: true
+	};
+}
+/** The non-numeric readings of a FormulaValue ([MS-XLS] 2.5.133), selected by its first byte. */
+function taggedFormulaValue(view, next) {
+	switch (view.getUint8(0)) {
+		case FORMULA_VALUE_STRING:
+			if (next?.type !== 519) return {
+				kind: "string",
+				value: ""
+			};
+			return {
+				kind: "string",
+				value: readXLUnicodeString(new BlockCursor(next.blocks))
+			};
+		case FORMULA_VALUE_BOOLEAN: return {
+			kind: "boolean",
+			value: view.getUint8(2) !== 0
+		};
+		case FORMULA_VALUE_ERROR: {
+			const text = errorTextOf(view.getUint8(2));
+			return text === void 0 ? { kind: "blank" } : {
+				kind: "error",
+				value: text
+			};
+		}
+		case FORMULA_VALUE_BLANK: return {
+			kind: "string",
+			value: ""
+		};
+		default: return { kind: "blank" };
+	}
+}
+//#endregion
+export { readSheetRecords };

package/package.json

@@ -1,5 +1,88 @@
 {
   "name": "xls-codec",
-  "version": "0.0.0",
-  "private": false
+  "version": "1.0.1",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/ExaDev/documents.js.git",
+    "directory": "packages/xls-codec"
+  },
+  "homepage": "https://github.com/ExaDev/documents.js/tree/main/packages/xls-codec",
+  "bugs": {
+    "url": "https://github.com/ExaDev/documents.js/issues"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./*": {
+      "types": {
+        "import": "./dist/*.d.ts",
+        "require": "./dist/*.d.cts"
+      },
+      "import": "./dist/*.js",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "turbo run _build",
+    "_build": "tsdown",
+    "prepublishOnly": "pnpm run lint && pnpm run typecheck && tsdown && publint && attw --pack",
+    "lint": "turbo run _lint",
+    "_lint": "eslint . --fix --cache --max-warnings 0",
+    "lint:check": "eslint . --max-warnings 0",
+    "typecheck": "turbo run _typecheck _typecheck:attw",
+    "_typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.node.json",
+    "_typecheck:attw": "attw --pack",
+    "test": "turbo run _test",
+    "_test": "vitest run --project unit",
+    "test:watch": "vitest --project unit",
+    "test:workers": "turbo run _test:workers",
+    "_test:workers": "vitest run --config vitest.workers.config.ts",
+    "test:smoke": "turbo run _test:smoke",
+    "_test:smoke": "vitest run --project smoke",
+    "prepare": "husky"
+  },
+  "packageManager": "pnpm@11.6.0",
+  "dependencies": {
+    "archive-codec": "^1.3.0",
+    "document-schema.js": "^5.4.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@cloudflare/vitest-pool-workers": "^0.20.1",
+    "@types/node": "^26.1.2",
+    "eslint": "^10.8.0",
+    "husky": "^9.1.7",
+    "publint": "^0.3.21",
+    "tsdown": "^0.22.13",
+    "turbo": "^2.10.8",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "lint-staged": {
+    "*.ts": "eslint --fix"
+  }
 }