xls-codec 0.0.0 → 1.0.0

package/dist/biff/substreams.js

@@ -0,0 +1,69 @@
+import "./record-types.js";
+import { BiffFormatError } from "./records.js";
+//#region src/biff/substreams.ts
+/** Joins each record to the Continue records following it, keeping the blocks separate. */
+function groupRecords(records) {
+	const groups = [];
+	for (const record of records) {
+		if (record.type === 60) {
+			const current = groups[groups.length - 1];
+			if (current === void 0) throw new BiffFormatError("Continue record with no preceding record to continue");
+			current.blocks.push(record.data);
+			continue;
+		}
+		groups.push({
+			type: record.type,
+			blocks: [record.data],
+			offset: record.offset
+		});
+	}
+	return groups;
+}
+/** The BOF record's own fixed prefix: a two-byte vers followed by a two-byte dt. */
+const BOF_PREFIX_SIZE = 4;
+/** Splits a grouped record sequence into its substreams, verifying each BOF declares BIFF8. */
+function splitSubstreams(groups) {
+	const substreams = [];
+	let current;
+	for (const group of groups) {
+		if (group.type === 2057) {
+			if (current !== void 0) substreams.push({
+				...current,
+				index: substreams.length
+			});
+			current = {
+				documentType: readBofDocumentType(group),
+				records: [],
+				offset: group.offset
+			};
+			continue;
+		}
+		if (group.type === 10) {
+			if (current !== void 0) {
+				substreams.push({
+					...current,
+					index: substreams.length
+				});
+				current = void 0;
+			}
+			continue;
+		}
+		current?.records.push(group);
+	}
+	if (current !== void 0) substreams.push({
+		...current,
+		index: substreams.length
+	});
+	return substreams;
+}
+/** Reads a BOF's vers and dt ([MS-XLS] 2.4.21), rejecting anything that is not BIFF8. */
+function readBofDocumentType(group) {
+	const data = group.blocks[0];
+	if (data === void 0 || data.length < BOF_PREFIX_SIZE) throw new BiffFormatError(`BOF record carries ${data?.length ?? 0} bytes, too few for its own version and document type`);
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	const version = view.getUint16(0, true);
+	if (version !== 1536) throw new BiffFormatError(`BOF declares BIFF version 0x${version.toString(16).padStart(4, "0")}; this reader implements BIFF8 (0x0600) only`);
+	return view.getUint16(2, true);
+}
+//#endregion
+export { groupRecords, splitSubstreams };

package/dist/container.cjs

@@ -0,0 +1,46 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_records = require("./biff/records.cjs");
+let archive_codec = require("archive-codec");
+//#region src/container.ts
+/** The stream a BIFF8 workbook lives in. Matched exactly and case-sensitively, which is how archive-codec reports a directory entry's name. */
+const WORKBOOK_STREAM = "Workbook";
+/** BIFF5 and BIFF7 workbooks name their stream "Book" instead. Recognised only to say so in an error, never read: those are different formats record-for-record, not older spellings of this one. */
+const LEGACY_WORKBOOK_STREAM = "Book";
+/**
+* Extracts the BIFF8 record stream from a .xls file's compound-file container.
+*
+* Throws rather than returning undefined for anything that is not a readable BIFF8 workbook: a caller wanting a soft answer asks isXlsFile first.
+*/
+function readWorkbookStream(bytes) {
+	if (!(0, archive_codec.isCompoundFile)(bytes)) throw new require_biff_records.BiffFormatError("not a compound file: a .xls workbook is a [MS-CFB] container holding a 'Workbook' stream");
+	const streams = readWorkbookContainer(bytes);
+	const workbook = streams.find((stream) => stream.path === WORKBOOK_STREAM);
+	if (workbook !== void 0) return workbook.bytes;
+	if (streams.some((stream) => stream.path === LEGACY_WORKBOOK_STREAM)) throw new require_biff_records.BiffFormatError("compound file holds a 'Book' stream rather than a 'Workbook' stream, so it is a BIFF5/BIFF7 workbook; this reader implements BIFF8 only");
+	throw new require_biff_records.BiffFormatError("compound file holds no 'Workbook' stream, so it is not a .xls workbook");
+}
+/** archive-codec's own reader, with its typed error left to propagate and every other failure wrapped, so a caller catching BiffFormatError sees one error type for "this is not a workbook this package can read". */
+function readWorkbookContainer(bytes) {
+	try {
+		return (0, archive_codec.readCompoundFile)(bytes);
+	} catch (error) {
+		if (error instanceof archive_codec.CompoundFileFormatError) throw new require_biff_records.BiffFormatError(`compound-file container could not be read: ${error.message}`);
+		throw new require_biff_records.BiffFormatError(`compound-file container could not be read: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Whether these bytes are a workbook this package can read.
+*
+* Checks for the compound-file container AND a "Workbook" stream inside it, rather than the container magic alone: .doc, .ppt, .msg, and a dozen other things are compound files too, so the magic bytes on their own would claim a Word document is a spreadsheet. A Microsoft Works .xlr passes, deliberately -- it carries the same BIFF8 "Workbook" stream.
+*/
+function isXlsFile(bytes) {
+	if (!(0, archive_codec.isCompoundFile)(bytes)) return false;
+	try {
+		return (0, archive_codec.readCompoundFile)(bytes).some((stream) => stream.path === WORKBOOK_STREAM);
+	} catch {
+		return false;
+	}
+}
+//#endregion
+exports.isXlsFile = isXlsFile;
+exports.readWorkbookStream = readWorkbookStream;

package/dist/container.d.cts

@@ -0,0 +1,15 @@
+//#region src/container.d.ts
+/**
+ * Extracts the BIFF8 record stream from a .xls file's compound-file container.
+ *
+ * Throws rather than returning undefined for anything that is not a readable BIFF8 workbook: a caller wanting a soft answer asks isXlsFile first.
+ */
+declare function readWorkbookStream(bytes: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+/**
+ * Whether these bytes are a workbook this package can read.
+ *
+ * Checks for the compound-file container AND a "Workbook" stream inside it, rather than the container magic alone: .doc, .ppt, .msg, and a dozen other things are compound files too, so the magic bytes on their own would claim a Word document is a spreadsheet. A Microsoft Works .xlr passes, deliberately -- it carries the same BIFF8 "Workbook" stream.
+ */
+declare function isXlsFile(bytes: Uint8Array<ArrayBuffer>): boolean;
+//#endregion
+export { isXlsFile, readWorkbookStream };

package/dist/container.d.ts

@@ -0,0 +1,15 @@
+//#region src/container.d.ts
+/**
+ * Extracts the BIFF8 record stream from a .xls file's compound-file container.
+ *
+ * Throws rather than returning undefined for anything that is not a readable BIFF8 workbook: a caller wanting a soft answer asks isXlsFile first.
+ */
+declare function readWorkbookStream(bytes: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+/**
+ * Whether these bytes are a workbook this package can read.
+ *
+ * Checks for the compound-file container AND a "Workbook" stream inside it, rather than the container magic alone: .doc, .ppt, .msg, and a dozen other things are compound files too, so the magic bytes on their own would claim a Word document is a spreadsheet. A Microsoft Works .xlr passes, deliberately -- it carries the same BIFF8 "Workbook" stream.
+ */
+declare function isXlsFile(bytes: Uint8Array<ArrayBuffer>): boolean;
+//#endregion
+export { isXlsFile, readWorkbookStream };

package/dist/container.js

@@ -0,0 +1,44 @@
+import { BiffFormatError } from "./biff/records.js";
+import { CompoundFileFormatError, isCompoundFile, readCompoundFile } from "archive-codec";
+//#region src/container.ts
+/** The stream a BIFF8 workbook lives in. Matched exactly and case-sensitively, which is how archive-codec reports a directory entry's name. */
+const WORKBOOK_STREAM = "Workbook";
+/** BIFF5 and BIFF7 workbooks name their stream "Book" instead. Recognised only to say so in an error, never read: those are different formats record-for-record, not older spellings of this one. */
+const LEGACY_WORKBOOK_STREAM = "Book";
+/**
+* Extracts the BIFF8 record stream from a .xls file's compound-file container.
+*
+* Throws rather than returning undefined for anything that is not a readable BIFF8 workbook: a caller wanting a soft answer asks isXlsFile first.
+*/
+function readWorkbookStream(bytes) {
+	if (!isCompoundFile(bytes)) throw new BiffFormatError("not a compound file: a .xls workbook is a [MS-CFB] container holding a 'Workbook' stream");
+	const streams = readWorkbookContainer(bytes);
+	const workbook = streams.find((stream) => stream.path === WORKBOOK_STREAM);
+	if (workbook !== void 0) return workbook.bytes;
+	if (streams.some((stream) => stream.path === LEGACY_WORKBOOK_STREAM)) throw new BiffFormatError("compound file holds a 'Book' stream rather than a 'Workbook' stream, so it is a BIFF5/BIFF7 workbook; this reader implements BIFF8 only");
+	throw new BiffFormatError("compound file holds no 'Workbook' stream, so it is not a .xls workbook");
+}
+/** archive-codec's own reader, with its typed error left to propagate and every other failure wrapped, so a caller catching BiffFormatError sees one error type for "this is not a workbook this package can read". */
+function readWorkbookContainer(bytes) {
+	try {
+		return readCompoundFile(bytes);
+	} catch (error) {
+		if (error instanceof CompoundFileFormatError) throw new BiffFormatError(`compound-file container could not be read: ${error.message}`);
+		throw new BiffFormatError(`compound-file container could not be read: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Whether these bytes are a workbook this package can read.
+*
+* Checks for the compound-file container AND a "Workbook" stream inside it, rather than the container magic alone: .doc, .ppt, .msg, and a dozen other things are compound files too, so the magic bytes on their own would claim a Word document is a spreadsheet. A Microsoft Works .xlr passes, deliberately -- it carries the same BIFF8 "Workbook" stream.
+*/
+function isXlsFile(bytes) {
+	if (!isCompoundFile(bytes)) return false;
+	try {
+		return readCompoundFile(bytes).some((stream) => stream.path === WORKBOOK_STREAM);
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { isXlsFile, readWorkbookStream };

package/dist/content.cjs

@@ -0,0 +1,230 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("./biff/record-types.cjs");
+const require_biff_records = require("./biff/records.cjs");
+const require_container = require("./container.cjs");
+const require_biff_substreams = require("./biff/substreams.cjs");
+const require_number_format = require("./number-format.cjs");
+const require_serial = require("./serial.cjs");
+const require_workbook_globals = require("./workbook/globals.cjs");
+const require_workbook_sheet = require("./workbook/sheet.cjs");
+let document_schema_js = require("document-schema.js");
+//#region src/content.ts
+/** Which BoundSheet8 dt values name a sheet this reader maps. 0x00 is a worksheet or dialog sheet; macro sheets, chart sheets, and VBA modules carry no cell table for ContentSheet to hold. */
+const SHEET_TYPE_WORKSHEET = 0;
+/**
+* Print settings this package emits rather than reads.
+*
+* ContentSheetPrintSettings makes pageSize, margins, gridlines, headers, and pageOrder REQUIRED, so a sheet cannot be produced without them, and BIFF8 spreads the real values across the Setup, LeftMargin/RightMargin/TopMargin/BottomMargin, PrintGrid, and PrintRowCol records plus a paper-size code table. None of those is read yet, so these are Excel's own documented "Normal" preset -- the same constants ooxml.js falls back to for an xlsx carrying no pageMargins element -- and they are honest defaults rather than the file's own settings. Reading the real ones is tracked as remaining scope rather than guessed at from unverified field offsets.
+*/
+const POINTS_PER_INCH = 72;
+const DEFAULT_PRINT_SETTINGS = {
+	pageSize: document_schema_js.PAGE_SIZE_LETTER,
+	margins: {
+		topPt: .75 * POINTS_PER_INCH,
+		rightPt: .7 * POINTS_PER_INCH,
+		bottomPt: .75 * POINTS_PER_INCH,
+		leftPt: .7 * POINTS_PER_INCH
+	},
+	gridlines: false,
+	headers: false,
+	pageOrder: "downThenOver"
+};
+/**
+* Reads a .xls file's bytes into a ContentDocument.
+*
+* The counterpart of ooxml.js's readXlsxContent, producing the same shape from the older format.
+*/
+function readXlsContent(bytes) {
+	const substreams = require_biff_substreams.splitSubstreams(require_biff_substreams.groupRecords(require_biff_records.readRecords(require_container.readWorkbookStream(bytes))));
+	const globalsSubstream = substreams[0];
+	if (globalsSubstream === void 0) throw new require_biff_records.BiffFormatError("workbook stream holds no substreams, so it carries no globals substream");
+	if (globalsSubstream.records.some((rec) => rec.type === 47)) throw new require_biff_records.BiffFormatError("workbook is encrypted (its globals substream carries a FilePass record); this reader does not decrypt");
+	const globals = require_workbook_globals.readWorkbookGlobals(globalsSubstream.records);
+	return {
+		kind: "spreadsheet",
+		metadata: {},
+		sheets: globals.sheets.filter((entry) => entry.sheetType === SHEET_TYPE_WORKSHEET).map((entry) => readSheet(entry, substreams, globals))
+	};
+}
+/** The tree-form read: readXlsContent composed with the schema's own structural transform, exactly as ooxml.js's readXlsx wraps readXlsxContent. */
+function readXls(bytes) {
+	return (0, document_schema_js.assembleTree)(readXlsContent(bytes));
+}
+/**
+* Locates a sheet's own substream and maps it.
+*
+* The substream is found by the byte offset BoundSheet8's lbPlyPos names, not by position: the order sheets appear in the workbook (which is BoundSheet8 order, and therefore the order of `globals.sheets`) is not required to match the order their substreams were written in. A sheet whose substream cannot be found still produces a ContentSheet, empty -- losing the sheet entirely would be a worse answer than losing its cells, since its name and position are real information the workbook did state.
+*/
+function readSheet(entry, substreams, globals) {
+	const substream = substreams.find((candidate) => candidate.offset === entry.bofPosition && candidate.documentType === 16);
+	const raw = substream === void 0 ? {
+		cells: [],
+		rows: [],
+		columns: [],
+		merges: []
+	} : require_workbook_sheet.readSheetRecords(substream.records, globals.sharedStrings);
+	return {
+		name: entry.name,
+		cells: mapCells(raw, globals),
+		columns: mapColumns(raw),
+		rows: mapRows(raw),
+		images: [],
+		printSettings: DEFAULT_PRINT_SETTINGS
+	};
+}
+function mapRows(raw) {
+	const rows = [];
+	for (const row of raw.rows) {
+		if (row.heightPt === void 0 && !row.hidden) continue;
+		const entry = { index: row.index };
+		if (row.heightPt !== void 0) entry.heightPt = row.heightPt;
+		if (row.hidden) entry.hidden = true;
+		rows.push(entry);
+	}
+	return rows;
+}
+function mapColumns(raw) {
+	const columns = [];
+	for (const column of raw.columns) {
+		if (column.widthPt === void 0 && !column.hidden) continue;
+		const entry = { index: column.index };
+		if (column.widthPt !== void 0) entry.widthPt = column.widthPt;
+		if (column.hidden) entry.hidden = true;
+		columns.push(entry);
+	}
+	return columns;
+}
+/** Maps the raw cells, then stamps merged-range spans onto their anchor cells. */
+function mapCells(raw, globals) {
+	const cells = [];
+	for (const cell of raw.cells) {
+		const mapped = mapCell(cell, globals);
+		if (mapped !== void 0) cells.push(mapped);
+	}
+	applyMerges(cells, raw);
+	return cells;
+}
+/**
+* Maps one raw cell, or drops it.
+*
+* A blank cell carrying no merge is dropped: ContentSheet's cell array is documented as sparse, holding only cells with something to show, and a Blank or MulBlank record states formatting this reader does not map yet. Dropping it keeps the array honest rather than filling a sheet with thousands of empty entries -- applyMerges below re-materialises the few blanks that anchor a merged range.
+*/
+function mapCell(cell, globals) {
+	if (cell.value.kind === "blank") return;
+	const formatCode = require_workbook_globals.formatCodeOf(globals, cell.xfIndex);
+	const value = resolveValue(cell, formatCode, globals.date1904);
+	const mapped = {
+		row: cell.row,
+		column: cell.column,
+		value,
+		displayText: displayTextOf(value)
+	};
+	if (formatCode !== void 0) mapped.numberFormatCode = formatCode;
+	return mapped;
+}
+/**
+* Resolves a raw value into a ContentCellValue, classifying a number through its own format code.
+*
+* This is where BIFF8's lack of temporal and percentage cell types is undone: every date, time, percentage, and currency amount is stored as a bare number, and only the format its XF points at says which. A format naming a date the calendar does not have (the 1900 system's phantom leap day, or a negative serial) degrades to the plain number rather than emitting an invalid ISO string.
+*/
+function resolveValue(cell, formatCode, date1904) {
+	if (cell.value.kind === "blank") return { kind: "empty" };
+	if (cell.value.kind !== "number") return cell.value;
+	const num = cell.value.value;
+	if (formatCode === void 0) return {
+		kind: "number",
+		value: num
+	};
+	const format = require_number_format.classifyNumberFormat(formatCode);
+	switch (format.kind) {
+		case "percentage": return {
+			kind: "percentage",
+			value: num
+		};
+		case "currency": return format.code === void 0 ? {
+			kind: "currency",
+			value: num
+		} : {
+			kind: "currency",
+			value: num,
+			currency: format.code
+		};
+		case "date": {
+			const iso = require_serial.serialToIsoDate(num, date1904);
+			return iso === void 0 ? {
+				kind: "number",
+				value: num
+			} : {
+				kind: "date",
+				value: iso
+			};
+		}
+		case "time": {
+			const iso = require_serial.serialToIsoTime(num);
+			return iso === void 0 ? {
+				kind: "number",
+				value: num
+			} : {
+				kind: "time",
+				value: iso
+			};
+		}
+		case "dateTime": {
+			const iso = require_serial.serialToIsoDateTime(num, date1904);
+			return iso === void 0 ? {
+				kind: "number",
+				value: num
+			} : {
+				kind: "dateTime",
+				value: iso
+			};
+		}
+		default: return {
+			kind: "number",
+			value: num
+		};
+	}
+}
+/** The typed value's own spelling, matching ooxml.js's derivation exactly so the same cell reads identically from either format. Deliberately not the producer's rendered string: this package classifies number formats but does not render through them. */
+function displayTextOf(value) {
+	switch (value.kind) {
+		case "number":
+		case "percentage":
+		case "currency": return String(value.value);
+		case "boolean": return value.value ? "TRUE" : "FALSE";
+		case "date":
+		case "time":
+		case "dateTime":
+		case "string":
+		case "error": return value.value;
+		case "empty": return "";
+		default: return "";
+	}
+}
+/**
+* Stamps each merged range's span onto its anchor cell, materialising an empty anchor when the range's top-left cell had no value of its own.
+*
+* ContentSheetCell documents colSpan/rowSpan as belonging to the anchor cell alone, and only when greater than one. A merged range whose anchor is blank is common -- merging cells in Excel keeps only the top-left value, and a range merged over an empty cell has no value anywhere -- so the anchor is created here rather than left absent, which would lose the merge entirely.
+*/
+function applyMerges(cells, raw) {
+	for (const range of raw.merges) {
+		const rowSpan = range.endRow - range.startRow + 1;
+		const colSpan = range.endColumn - range.startColumn + 1;
+		if (rowSpan <= 1 && colSpan <= 1) continue;
+		let anchor = cells.find((cell) => cell.row === range.startRow && cell.column === range.startColumn);
+		if (anchor === void 0) {
+			anchor = {
+				row: range.startRow,
+				column: range.startColumn,
+				value: { kind: "empty" },
+				displayText: ""
+			};
+			cells.push(anchor);
+		}
+		if (colSpan > 1) anchor.colSpan = colSpan;
+		if (rowSpan > 1) anchor.rowSpan = rowSpan;
+	}
+}
+//#endregion
+exports.readXls = readXls;
+exports.readXlsContent = readXlsContent;

package/dist/content.d.cts

@@ -0,0 +1,20 @@
+import { ContentDocument, DocumentTree } from "document-schema.js";
+//#region src/content.d.ts
+/**
+ * The spreadsheet member of ContentDocument's own discriminated union.
+ *
+ * Named and returned in place of the bare union, which is what ooxml.js's readXlsxContent declares. A .xls is a spreadsheet by construction -- there is no input this reader could accept that produced a wordprocessing or presentation document -- so returning the union would force every caller to re-narrow on `kind` to reach `sheets`, discarding a fact this function already knows. The narrowed type stays assignable to ContentDocument, so a caller holding one (documents.js's conversion registry among them) is unaffected.
+ */
+type XlsContentDocument = Extract<ContentDocument, {
+  kind: "spreadsheet";
+}>;
+/**
+ * Reads a .xls file's bytes into a ContentDocument.
+ *
+ * The counterpart of ooxml.js's readXlsxContent, producing the same shape from the older format.
+ */
+declare function readXlsContent(bytes: Uint8Array<ArrayBuffer>): XlsContentDocument;
+/** The tree-form read: readXlsContent composed with the schema's own structural transform, exactly as ooxml.js's readXlsx wraps readXlsxContent. */
+declare function readXls(bytes: Uint8Array<ArrayBuffer>): DocumentTree;
+//#endregion
+export { XlsContentDocument, readXls, readXlsContent };

package/dist/content.d.ts

@@ -0,0 +1,20 @@
+import { ContentDocument, DocumentTree } from "document-schema.js";
+//#region src/content.d.ts
+/**
+ * The spreadsheet member of ContentDocument's own discriminated union.
+ *
+ * Named and returned in place of the bare union, which is what ooxml.js's readXlsxContent declares. A .xls is a spreadsheet by construction -- there is no input this reader could accept that produced a wordprocessing or presentation document -- so returning the union would force every caller to re-narrow on `kind` to reach `sheets`, discarding a fact this function already knows. The narrowed type stays assignable to ContentDocument, so a caller holding one (documents.js's conversion registry among them) is unaffected.
+ */
+type XlsContentDocument = Extract<ContentDocument, {
+  kind: "spreadsheet";
+}>;
+/**
+ * Reads a .xls file's bytes into a ContentDocument.
+ *
+ * The counterpart of ooxml.js's readXlsxContent, producing the same shape from the older format.
+ */
+declare function readXlsContent(bytes: Uint8Array<ArrayBuffer>): XlsContentDocument;
+/** The tree-form read: readXlsContent composed with the schema's own structural transform, exactly as ooxml.js's readXlsx wraps readXlsxContent. */
+declare function readXls(bytes: Uint8Array<ArrayBuffer>): DocumentTree;
+//#endregion
+export { XlsContentDocument, readXls, readXlsContent };