xls-codec 0.0.0 → 1.0.0

package/dist/number-format.d.cts

@@ -0,0 +1,32 @@
+//#region src/number-format.d.ts
+/** What a format code says the value is. `elapsedTime` is kept distinct from `time` because a duration may exceed 24 hours and so has no wall-clock spelling in the schema. */
+type NumberFormatClass = {
+  kind: "number";
+} | {
+  kind: "text";
+} | {
+  kind: "percentage";
+} | {
+  kind: "currency";
+  code?: string;
+} | {
+  kind: "date";
+} | {
+  kind: "time";
+} | {
+  kind: "dateTime";
+} | {
+  kind: "elapsedTime";
+};
+/** Classifies a format code, reading the FIRST section only. Sections two through four are the negative/zero/text renderings of the same underlying value: they differ in colour, parentheses, and literal text, never in what kind of thing the cell holds, and a cell whose value happens to be negative must not classify differently from the identical cell holding a positive one. */
+declare function classifyNumberFormat(formatCode: string): NumberFormatClass;
+/**
+ * The built-in format codes, which a file never writes into its own Format records and every reader is expected to know.
+ *
+ * [MS-XLS] 2.4.126 constrains a Format record's own ifmt to 5-8, 23-26, 41-44, 63-66, and 164-382, so an XF pointing at any other identifier resolves through this table instead. The codes are ECMA-376 Part 1 SS18.8.30's table, which BIFF8 and xlsx share.
+ *
+ * Ids 23-36 are deliberately absent: that table leaves them reserved, and inventing codes for them would fabricate a mapping no specification defines -- an XF pointing at one resolves to no code at all, which the caller reports as absent rather than silently substituting General. These strings are fed through the SAME classifyNumberFormat as a producer-declared code, never a second table of pre-decided kinds, so the two feeds cannot drift apart.
+ */
+declare const BUILTIN_NUMBER_FORMATS: ReadonlyMap<number, string>;
+//#endregion
+export { BUILTIN_NUMBER_FORMATS, NumberFormatClass, classifyNumberFormat };

package/dist/number-format.d.ts

@@ -0,0 +1,32 @@
+//#region src/number-format.d.ts
+/** What a format code says the value is. `elapsedTime` is kept distinct from `time` because a duration may exceed 24 hours and so has no wall-clock spelling in the schema. */
+type NumberFormatClass = {
+  kind: "number";
+} | {
+  kind: "text";
+} | {
+  kind: "percentage";
+} | {
+  kind: "currency";
+  code?: string;
+} | {
+  kind: "date";
+} | {
+  kind: "time";
+} | {
+  kind: "dateTime";
+} | {
+  kind: "elapsedTime";
+};
+/** Classifies a format code, reading the FIRST section only. Sections two through four are the negative/zero/text renderings of the same underlying value: they differ in colour, parentheses, and literal text, never in what kind of thing the cell holds, and a cell whose value happens to be negative must not classify differently from the identical cell holding a positive one. */
+declare function classifyNumberFormat(formatCode: string): NumberFormatClass;
+/**
+ * The built-in format codes, which a file never writes into its own Format records and every reader is expected to know.
+ *
+ * [MS-XLS] 2.4.126 constrains a Format record's own ifmt to 5-8, 23-26, 41-44, 63-66, and 164-382, so an XF pointing at any other identifier resolves through this table instead. The codes are ECMA-376 Part 1 SS18.8.30's table, which BIFF8 and xlsx share.
+ *
+ * Ids 23-36 are deliberately absent: that table leaves them reserved, and inventing codes for them would fabricate a mapping no specification defines -- an XF pointing at one resolves to no code at all, which the caller reports as absent rather than silently substituting General. These strings are fed through the SAME classifyNumberFormat as a producer-declared code, never a second table of pre-decided kinds, so the two feeds cannot drift apart.
+ */
+declare const BUILTIN_NUMBER_FORMATS: ReadonlyMap<number, string>;
+//#endregion
+export { BUILTIN_NUMBER_FORMATS, NumberFormatClass, classifyNumberFormat };

package/dist/number-format.js

@@ -0,0 +1,296 @@
+//#region src/number-format.ts
+/** Excel honours at most four sections (positive; negative; zero; text); a fifth is malformed and is dropped rather than guessed at. */
+const MAX_SECTIONS = 4;
+/** Mirrors String.prototype.charAt's past-the-end contract, but over a CODE POINT array, so a rare astral currency symbol stays one token instead of splitting into two lone surrogates. */
+function at(chars, index) {
+	return chars[index] ?? "";
+}
+function tokenize(formatCode) {
+	const chars = [...formatCode];
+	const tokens = [];
+	let index = 0;
+	while (index < chars.length) {
+		const char = at(chars, index);
+		if (char === "\"") {
+			let text = "";
+			index += 1;
+			while (index < chars.length && at(chars, index) !== "\"") {
+				text += at(chars, index);
+				index += 1;
+			}
+			index += 1;
+			tokens.push({
+				kind: "literal",
+				text
+			});
+			continue;
+		}
+		if (char === "\\" || char === "_" || char === "*") {
+			tokens.push({
+				kind: "literal",
+				text: at(chars, index + 1)
+			});
+			index += 2;
+			continue;
+		}
+		if (char === "[") {
+			let body = "";
+			index += 1;
+			while (index < chars.length && at(chars, index) !== "]") {
+				body += at(chars, index);
+				index += 1;
+			}
+			index += 1;
+			tokens.push({
+				kind: "bracket",
+				body
+			});
+			continue;
+		}
+		if (char === ";") {
+			tokens.push({ kind: "separator" });
+			index += 1;
+			continue;
+		}
+		tokens.push({
+			kind: "code",
+			char
+		});
+		index += 1;
+	}
+	return tokens;
+}
+/** Splits on separator tokens only: a ';' inside a quote or bracket was already consumed as part of that token, so it can never split a section here. */
+function splitSections(tokens) {
+	const sections = [];
+	let current = [];
+	for (const token of tokens) {
+		if (token.kind === "separator") {
+			sections.push(current);
+			current = [];
+			continue;
+		}
+		current.push(token);
+	}
+	sections.push(current);
+	return sections.slice(0, MAX_SECTIONS);
+}
+/** The Unicode Currency_Symbol category IS the definition of "this character means money", so it is tested directly rather than against a hand-listed subset that would omit whichever symbol a real file happens to use. */
+const CURRENCY_SYMBOL = /\p{Sc}/u;
+/** `[$GBP-809]` carries an ISO 4217 code; `[$£-809]` carries a display symbol instead. Only the three-ASCII-letter shape counts as a code, because ContentCellValue's `currency` field is documented as the ISO code and there is no faithful symbol-to-code mapping ('$' alone is USD, CAD, AUD and a dozen others). */
+function isIsoCurrencyCodeShape(marker) {
+	if (marker.length !== 3) return false;
+	for (const char of marker) {
+		const upper = char.toUpperCase();
+		if (upper < "A" || upper > "Z") return false;
+	}
+	return true;
+}
+/** An elapsed-time bucket is a bracket holding one repeated h/m/s and nothing else -- the marker that the value is a DURATION, which may legitimately exceed 24 hours, rather than a time of day. */
+function isElapsedBracketBody(body) {
+	let letter;
+	for (const char of body) {
+		const lower = char.toLowerCase();
+		if (letter === void 0) {
+			if (lower !== "h" && lower !== "m" && lower !== "s") return false;
+			letter = lower;
+		} else if (lower !== letter) return false;
+	}
+	return letter !== void 0;
+}
+function classifyBracket(body) {
+	if (body.startsWith("$")) {
+		const rest = body.slice(1);
+		const dashIndex = rest.indexOf("-");
+		const marker = dashIndex === -1 ? rest : rest.slice(0, dashIndex);
+		if (marker === "") return { kind: "none" };
+		return isIsoCurrencyCodeShape(marker) ? {
+			kind: "currency",
+			code: marker.toUpperCase()
+		} : { kind: "currency" };
+	}
+	return isElapsedBracketBody(body) ? { kind: "elapsed" } : { kind: "none" };
+}
+const AMPM_MARKERS = ["am/pm", "a/p"];
+const AMPM_LETTER = "ampm";
+function matchesAt(chars, index, marker) {
+	return [...marker].every((char, offset) => at(chars, index + offset).toLowerCase() === char);
+}
+function codeRunsOf(section) {
+	const chars = [];
+	for (const token of section) if (token.kind === "code") chars.push(token.char);
+	const runs = [];
+	let index = 0;
+	while (index < chars.length) {
+		const marker = AMPM_MARKERS.find((candidate) => matchesAt(chars, index, candidate));
+		if (marker !== void 0) {
+			runs.push({
+				letter: AMPM_LETTER,
+				length: marker.length
+			});
+			index += marker.length;
+			continue;
+		}
+		const char = at(chars, index).toLowerCase();
+		let length = 0;
+		while (index + length < chars.length && at(chars, index + length).toLowerCase() === char) length += 1;
+		runs.push({
+			letter: char,
+			length
+		});
+		index += length;
+	}
+	return runs;
+}
+/** The letters an ambiguous 'm' looks past its neighbours for. 'm' itself is excluded: an unresolved 'm' carries no information for resolving another, so `hh:mm:mm` resolves both against the 'hh'. */
+const RESOLVING_LETTERS = [
+	"y",
+	"d",
+	"h",
+	"s"
+];
+function nearestResolvingLetter(runs, from, step) {
+	for (let index = from + step; index >= 0 && index < runs.length; index += step) {
+		const run = runs[index];
+		if (run !== void 0 && RESOLVING_LETTERS.includes(run.letter)) return run.letter;
+	}
+}
+/** Excel's minutes-vs-months rule: 'm'/'mm' is minutes when the nearest preceding date/time code is an hour or the nearest following one is a second, and a month otherwise. 'mmm' and longer are always month names. This is what makes `yyyy-mm-dd hh:mm:ss` resolve its two identical 'mm' runs oppositely. */
+function monthRunIsMinutes(runs, index) {
+	return nearestResolvingLetter(runs, index, -1) === "h" || nearestResolvingLetter(runs, index, 1) === "s";
+}
+const PLAIN_NUMBER = { kind: "number" };
+/** Digit placeholders ('0' required, '#' suppressed, '?' space-padded), the decimal and thousands separators. Scientific notation's 'e' is handled at its own run, since a bare 'e' also occurs inside the literal word "General". */
+const NUMERIC_CODES = [
+	"0",
+	"#",
+	"?",
+	".",
+	","
+];
+function collectSignals(section) {
+	const signals = {
+		hasDate: false,
+		hasTime: false,
+		hasElapsed: false,
+		hasPercent: false,
+		hasNumeric: false,
+		hasText: false,
+		hasCurrency: false
+	};
+	for (const token of section) {
+		if (token.kind === "literal" && CURRENCY_SYMBOL.test(token.text)) signals.hasCurrency = true;
+		if (token.kind === "bracket") {
+			const meaning = classifyBracket(token.body);
+			if (meaning.kind === "elapsed") signals.hasElapsed = true;
+			if (meaning.kind === "currency") {
+				signals.hasCurrency = true;
+				if (signals.currencyCode === void 0 && meaning.code !== void 0) signals.currencyCode = meaning.code;
+			}
+		}
+	}
+	const runs = codeRunsOf(section);
+	runs.forEach((run, index) => {
+		if (run.letter === "y" || run.letter === "d") {
+			signals.hasDate = true;
+			return;
+		}
+		if (run.letter === "h" || run.letter === "s" || run.letter === AMPM_LETTER) {
+			signals.hasTime = true;
+			return;
+		}
+		if (run.letter === "m") {
+			if (run.length <= 2 && monthRunIsMinutes(runs, index)) signals.hasTime = true;
+			else signals.hasDate = true;
+			return;
+		}
+		if (run.letter === "e") {
+			const next = runs[index + 1];
+			signals.hasNumeric = signals.hasNumeric || next?.letter === "+" || next?.letter === "-";
+			return;
+		}
+		if (run.letter === "%") {
+			signals.hasPercent = true;
+			return;
+		}
+		if (run.letter === "@") {
+			signals.hasText = true;
+			return;
+		}
+		if (NUMERIC_CODES.includes(run.letter)) {
+			signals.hasNumeric = true;
+			return;
+		}
+		if (CURRENCY_SYMBOL.test(run.letter)) signals.hasCurrency = true;
+	});
+	return signals;
+}
+/** Precedence when a format carries several signals at once, most specific first: an elapsed-time bracket beats everything (the only marker separating a duration from a time of day); any date code beats any time code (a format with both is a genuine combined date-and-time); a percent sign beats a currency marker (`[$GBP-809]0.00%` is still a percentage); and a text placeholder only wins when the section has no numeric placeholder to be a number with. */
+function classifySection(section) {
+	const signals = collectSignals(section);
+	if (signals.hasElapsed) return { kind: "elapsedTime" };
+	if (signals.hasDate) return signals.hasTime ? { kind: "dateTime" } : { kind: "date" };
+	if (signals.hasTime) return { kind: "time" };
+	if (signals.hasPercent) return { kind: "percentage" };
+	if (signals.hasCurrency) {
+		const code = signals.currencyCode;
+		return code === void 0 ? { kind: "currency" } : {
+			kind: "currency",
+			code
+		};
+	}
+	if (signals.hasText && !signals.hasNumeric) return { kind: "text" };
+	return PLAIN_NUMBER;
+}
+/** Classifies a format code, reading the FIRST section only. Sections two through four are the negative/zero/text renderings of the same underlying value: they differ in colour, parentheses, and literal text, never in what kind of thing the cell holds, and a cell whose value happens to be negative must not classify differently from the identical cell holding a positive one. */
+function classifyNumberFormat(formatCode) {
+	const first = splitSections(tokenize(formatCode))[0];
+	return first === void 0 ? PLAIN_NUMBER : classifySection(first);
+}
+/**
+* The built-in format codes, which a file never writes into its own Format records and every reader is expected to know.
+*
+* [MS-XLS] 2.4.126 constrains a Format record's own ifmt to 5-8, 23-26, 41-44, 63-66, and 164-382, so an XF pointing at any other identifier resolves through this table instead. The codes are ECMA-376 Part 1 SS18.8.30's table, which BIFF8 and xlsx share.
+*
+* Ids 23-36 are deliberately absent: that table leaves them reserved, and inventing codes for them would fabricate a mapping no specification defines -- an XF pointing at one resolves to no code at all, which the caller reports as absent rather than silently substituting General. These strings are fed through the SAME classifyNumberFormat as a producer-declared code, never a second table of pre-decided kinds, so the two feeds cannot drift apart.
+*/
+const BUILTIN_NUMBER_FORMATS = /* @__PURE__ */ new Map([
+	[0, "General"],
+	[1, "0"],
+	[2, "0.00"],
+	[3, "#,##0"],
+	[4, "#,##0.00"],
+	[5, "$#,##0_);($#,##0)"],
+	[6, "$#,##0_);[Red]($#,##0)"],
+	[7, "$#,##0.00_);($#,##0.00)"],
+	[8, "$#,##0.00_);[Red]($#,##0.00)"],
+	[9, "0%"],
+	[10, "0.00%"],
+	[11, "0.00E+00"],
+	[12, "# ?/?"],
+	[13, "# ??/??"],
+	[14, "mm-dd-yy"],
+	[15, "d-mmm-yy"],
+	[16, "d-mmm"],
+	[17, "mmm-yy"],
+	[18, "h:mm AM/PM"],
+	[19, "h:mm:ss AM/PM"],
+	[20, "h:mm"],
+	[21, "h:mm:ss"],
+	[22, "m/d/yy h:mm"],
+	[37, "#,##0 ;(#,##0)"],
+	[38, "#,##0 ;[Red](#,##0)"],
+	[39, "#,##0.00;(#,##0.00)"],
+	[40, "#,##0.00;[Red](#,##0.00)"],
+	[41, "_(* #,##0_);_(* \\(#,##0\\);_(* \"-\"_);_(@_)"],
+	[42, "_(\"$\"* #,##0_);_(\"$\"* \\(#,##0\\);_(\"$\"* \"-\"_);_(@_)"],
+	[43, "_(* #,##0.00_);_(* \\(#,##0.00\\);_(* \"-\"??_);_(@_)"],
+	[44, "_(\"$\"* #,##0.00_);_(\"$\"* \\(#,##0.00\\);_(\"$\"* \"-\"??_);_(@_)"],
+	[45, "mm:ss"],
+	[46, "[h]:mm:ss"],
+	[47, "mmss.0"],
+	[48, "##0.0E+0"],
+	[49, "@"]
+]);
+//#endregion
+export { BUILTIN_NUMBER_FORMATS, classifyNumberFormat };

package/dist/records-DVIqXFKk.d.cts

@@ -0,0 +1,20 @@
+//#region src/biff/records.d.ts
+/** A single record as the stream carries it: its type from the enumeration ([MS-XLS] 2.3), and its data component, exactly `size` bytes long. */
+interface BiffRecord {
+  readonly type: number;
+  readonly data: Uint8Array<ArrayBuffer>;
+  /** The record's own start offset in the stream. Carried because BoundSheet8's lbPlyPos ([MS-XLS] 2.4.28) addresses a sheet's substream by the byte offset of its BOF, so matching a sheet to its records means knowing where each record began. */
+  readonly offset: number;
+}
+/** Thrown when a byte sequence cannot be read as the structure [MS-XLS] specifies, at any level from the record framing up to a record's own fields. */
+declare class BiffFormatError extends Error {
+  constructor(message: string);
+}
+/**
+ * Splits a BIFF record stream into its records, in stream order.
+ *
+ * Every failure is thrown rather than tolerated, because there is no safe way to resume: a record's size field is the only thing that says where the next record begins, so a stream that stops making sense at one record makes no sense from there on, and returning the records read so far would be reporting a truncated workbook as a complete one.
+ */
+declare function readRecords(stream: Uint8Array<ArrayBuffer>): readonly BiffRecord[];
+//#endregion
+export { BiffRecord as n, readRecords as r, BiffFormatError as t };

package/dist/records-DVIqXFKk.d.ts

@@ -0,0 +1,20 @@
+//#region src/biff/records.d.ts
+/** A single record as the stream carries it: its type from the enumeration ([MS-XLS] 2.3), and its data component, exactly `size` bytes long. */
+interface BiffRecord {
+  readonly type: number;
+  readonly data: Uint8Array<ArrayBuffer>;
+  /** The record's own start offset in the stream. Carried because BoundSheet8's lbPlyPos ([MS-XLS] 2.4.28) addresses a sheet's substream by the byte offset of its BOF, so matching a sheet to its records means knowing where each record began. */
+  readonly offset: number;
+}
+/** Thrown when a byte sequence cannot be read as the structure [MS-XLS] specifies, at any level from the record framing up to a record's own fields. */
+declare class BiffFormatError extends Error {
+  constructor(message: string);
+}
+/**
+ * Splits a BIFF record stream into its records, in stream order.
+ *
+ * Every failure is thrown rather than tolerated, because there is no safe way to resume: a record's size field is the only thing that says where the next record begins, so a stream that stops making sense at one record makes no sense from there on, and returning the records read so far would be reporting a truncated workbook as a complete one.
+ */
+declare function readRecords(stream: Uint8Array<ArrayBuffer>): readonly BiffRecord[];
+//#endregion
+export { BiffRecord as n, readRecords as r, BiffFormatError as t };

package/dist/serial.cjs

@@ -0,0 +1,62 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/serial.ts
+const MS_PER_DAY = 864e5;
+const MS_PER_HOUR = 36e5;
+const MS_PER_MINUTE = 6e4;
+const MS_PER_SECOND = 1e3;
+/** The serial the 1900 system reserves for a day that never existed: 1900-02-29. Lotus 1-2-3 treated 1900 as a leap year and Excel reproduced the bug for file compatibility, so serials at or above 61 are one day ahead of a true day count from 1899-12-31, and serial 60 itself denotes a date with no place on the calendar. */
+const PHANTOM_LEAP_DAY_SERIAL = 60;
+/** The three day-count origins, named once so a serial and its parts can never be counted from different days. Below the phantom leap day the 1900 system is a true offset from 1899-12-31 (serial 1 = 1900-01-01); at and above it every serial is one too high, expressed by moving the origin back a day rather than by subtracting from the count. The 1904 system is a plain day count from its own epoch, with serial 0 being 1904-01-01 -- no phantom day, since 1904 genuinely was a leap year and the count starts after February. */
+const ORIGIN_1900_BELOW_PHANTOM_UTC_MS = Date.UTC(1899, 11, 31);
+const ORIGIN_1900_ABOVE_PHANTOM_UTC_MS = Date.UTC(1899, 11, 30);
+const ORIGIN_1904_UTC_MS = Date.UTC(1904, 0, 1);
+/** Rounding the fractional part to the nearest millisecond is what recovers a clean wall-clock time from a serial a producer stored to fifteen significant digits (14:30 is commonly stored as 0.604166666666667, whose exact product with 86400000 is 52199999.999999 ms). Rounding can legitimately reach a full day -- 0.9999999 rounds to 86400000 ms -- which rolls into the next day rather than producing an impossible 24:00:00. */
+function splitSerial(serial) {
+	const days = Math.floor(serial);
+	const msWithinDay = Math.round((serial - days) * MS_PER_DAY);
+	return msWithinDay >= MS_PER_DAY ? {
+		days: days + 1,
+		msWithinDay: 0
+	} : {
+		days,
+		msWithinDay
+	};
+}
+function pad(value, length) {
+	return String(value).padStart(length, "0");
+}
+/** Every calculation is done in UTC deliberately: a serial carries no timezone, and local-time Date methods would shift a date across a day boundary for any host west of Greenwich. */
+function isoDateOfUtcMs(ms) {
+	const date = new Date(ms);
+	return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+}
+/** The day-count half of a serial, as a calendar date -- undefined when the serial names no real date, which the caller degrades to a plain number rather than emitting an invalid one. Two cases produce that: a negative serial (no date exists before either epoch), and serial 60 in the 1900 system (the phantom leap day). */
+function isoDateOfDayCount(days, date1904) {
+	if (days < 0) return;
+	if (date1904) return isoDateOfUtcMs(ORIGIN_1904_UTC_MS + days * MS_PER_DAY);
+	if (days === PHANTOM_LEAP_DAY_SERIAL) return;
+	return isoDateOfUtcMs((days < PHANTOM_LEAP_DAY_SERIAL ? ORIGIN_1900_BELOW_PHANTOM_UTC_MS : ORIGIN_1900_ABOVE_PHANTOM_UTC_MS) + days * MS_PER_DAY);
+}
+function isoTimeOfMsWithinDay(msWithinDay) {
+	const hours = Math.floor(msWithinDay / MS_PER_HOUR);
+	const minutes = Math.floor(msWithinDay % MS_PER_HOUR / MS_PER_MINUTE);
+	const seconds = Math.floor(msWithinDay % MS_PER_MINUTE / MS_PER_SECOND);
+	return `${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds, 2)}`;
+}
+function serialToIsoDate(serial, date1904) {
+	return Number.isFinite(serial) ? isoDateOfDayCount(splitSerial(serial).days, date1904) : void 0;
+}
+/** A time-of-day format renders only the fractional part -- a serial of 2.5 under `h:mm` displays as noon, not as "two days and twelve hours" -- so the day count is discarded here rather than made an error. Sub-second precision is discarded too: ContentCellValue's own 'time' spelling is fixed at HH:MM:SS. */
+function serialToIsoTime(serial) {
+	return Number.isFinite(serial) && serial >= 0 ? isoTimeOfMsWithinDay(splitSerial(serial).msWithinDay) : void 0;
+}
+function serialToIsoDateTime(serial, date1904) {
+	if (!Number.isFinite(serial)) return;
+	const { days, msWithinDay } = splitSerial(serial);
+	const date = isoDateOfDayCount(days, date1904);
+	return date === void 0 ? void 0 : `${date}T${isoTimeOfMsWithinDay(msWithinDay)}`;
+}
+//#endregion
+exports.serialToIsoDate = serialToIsoDate;
+exports.serialToIsoDateTime = serialToIsoDateTime;
+exports.serialToIsoTime = serialToIsoTime;

package/dist/serial.d.cts

@@ -0,0 +1,7 @@
+//#region src/serial.d.ts
+declare function serialToIsoDate(serial: number, date1904: boolean): string | undefined;
+/** A time-of-day format renders only the fractional part -- a serial of 2.5 under `h:mm` displays as noon, not as "two days and twelve hours" -- so the day count is discarded here rather than made an error. Sub-second precision is discarded too: ContentCellValue's own 'time' spelling is fixed at HH:MM:SS. */
+declare function serialToIsoTime(serial: number): string | undefined;
+declare function serialToIsoDateTime(serial: number, date1904: boolean): string | undefined;
+//#endregion
+export { serialToIsoDate, serialToIsoDateTime, serialToIsoTime };

package/dist/serial.d.ts

@@ -0,0 +1,7 @@
+//#region src/serial.d.ts
+declare function serialToIsoDate(serial: number, date1904: boolean): string | undefined;
+/** A time-of-day format renders only the fractional part -- a serial of 2.5 under `h:mm` displays as noon, not as "two days and twelve hours" -- so the day count is discarded here rather than made an error. Sub-second precision is discarded too: ContentCellValue's own 'time' spelling is fixed at HH:MM:SS. */
+declare function serialToIsoTime(serial: number): string | undefined;
+declare function serialToIsoDateTime(serial: number, date1904: boolean): string | undefined;
+//#endregion
+export { serialToIsoDate, serialToIsoDateTime, serialToIsoTime };

package/dist/serial.js

@@ -0,0 +1,59 @@
+//#region src/serial.ts
+const MS_PER_DAY = 864e5;
+const MS_PER_HOUR = 36e5;
+const MS_PER_MINUTE = 6e4;
+const MS_PER_SECOND = 1e3;
+/** The serial the 1900 system reserves for a day that never existed: 1900-02-29. Lotus 1-2-3 treated 1900 as a leap year and Excel reproduced the bug for file compatibility, so serials at or above 61 are one day ahead of a true day count from 1899-12-31, and serial 60 itself denotes a date with no place on the calendar. */
+const PHANTOM_LEAP_DAY_SERIAL = 60;
+/** The three day-count origins, named once so a serial and its parts can never be counted from different days. Below the phantom leap day the 1900 system is a true offset from 1899-12-31 (serial 1 = 1900-01-01); at and above it every serial is one too high, expressed by moving the origin back a day rather than by subtracting from the count. The 1904 system is a plain day count from its own epoch, with serial 0 being 1904-01-01 -- no phantom day, since 1904 genuinely was a leap year and the count starts after February. */
+const ORIGIN_1900_BELOW_PHANTOM_UTC_MS = Date.UTC(1899, 11, 31);
+const ORIGIN_1900_ABOVE_PHANTOM_UTC_MS = Date.UTC(1899, 11, 30);
+const ORIGIN_1904_UTC_MS = Date.UTC(1904, 0, 1);
+/** Rounding the fractional part to the nearest millisecond is what recovers a clean wall-clock time from a serial a producer stored to fifteen significant digits (14:30 is commonly stored as 0.604166666666667, whose exact product with 86400000 is 52199999.999999 ms). Rounding can legitimately reach a full day -- 0.9999999 rounds to 86400000 ms -- which rolls into the next day rather than producing an impossible 24:00:00. */
+function splitSerial(serial) {
+	const days = Math.floor(serial);
+	const msWithinDay = Math.round((serial - days) * MS_PER_DAY);
+	return msWithinDay >= MS_PER_DAY ? {
+		days: days + 1,
+		msWithinDay: 0
+	} : {
+		days,
+		msWithinDay
+	};
+}
+function pad(value, length) {
+	return String(value).padStart(length, "0");
+}
+/** Every calculation is done in UTC deliberately: a serial carries no timezone, and local-time Date methods would shift a date across a day boundary for any host west of Greenwich. */
+function isoDateOfUtcMs(ms) {
+	const date = new Date(ms);
+	return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+}
+/** The day-count half of a serial, as a calendar date -- undefined when the serial names no real date, which the caller degrades to a plain number rather than emitting an invalid one. Two cases produce that: a negative serial (no date exists before either epoch), and serial 60 in the 1900 system (the phantom leap day). */
+function isoDateOfDayCount(days, date1904) {
+	if (days < 0) return;
+	if (date1904) return isoDateOfUtcMs(ORIGIN_1904_UTC_MS + days * MS_PER_DAY);
+	if (days === PHANTOM_LEAP_DAY_SERIAL) return;
+	return isoDateOfUtcMs((days < PHANTOM_LEAP_DAY_SERIAL ? ORIGIN_1900_BELOW_PHANTOM_UTC_MS : ORIGIN_1900_ABOVE_PHANTOM_UTC_MS) + days * MS_PER_DAY);
+}
+function isoTimeOfMsWithinDay(msWithinDay) {
+	const hours = Math.floor(msWithinDay / MS_PER_HOUR);
+	const minutes = Math.floor(msWithinDay % MS_PER_HOUR / MS_PER_MINUTE);
+	const seconds = Math.floor(msWithinDay % MS_PER_MINUTE / MS_PER_SECOND);
+	return `${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds, 2)}`;
+}
+function serialToIsoDate(serial, date1904) {
+	return Number.isFinite(serial) ? isoDateOfDayCount(splitSerial(serial).days, date1904) : void 0;
+}
+/** A time-of-day format renders only the fractional part -- a serial of 2.5 under `h:mm` displays as noon, not as "two days and twelve hours" -- so the day count is discarded here rather than made an error. Sub-second precision is discarded too: ContentCellValue's own 'time' spelling is fixed at HH:MM:SS. */
+function serialToIsoTime(serial) {
+	return Number.isFinite(serial) && serial >= 0 ? isoTimeOfMsWithinDay(splitSerial(serial).msWithinDay) : void 0;
+}
+function serialToIsoDateTime(serial, date1904) {
+	if (!Number.isFinite(serial)) return;
+	const { days, msWithinDay } = splitSerial(serial);
+	const date = isoDateOfDayCount(days, date1904);
+	return date === void 0 ? void 0 : `${date}T${isoTimeOfMsWithinDay(msWithinDay)}`;
+}
+//#endregion
+export { serialToIsoDate, serialToIsoDateTime, serialToIsoTime };

package/dist/units.cjs

@@ -0,0 +1,30 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/units.ts
+/** Points per inch, and the pixel grid Excel's column-width formula is defined against (96 px/inch, its screen-rendering assumption). */
+const POINTS_PER_INCH = 72;
+const PIXELS_PER_INCH = 96;
+/** A twip is a twentieth of a point; a Row record's miyRw is in twips ([MS-XLS] 2.4.221). */
+const TWIPS_PER_POINT = 20;
+/**
+* The "maximum digit width": the widest rendered width, in pixels, of the digits 0-9 in the workbook's Normal-style font, which is the unit a column width is expressed in multiples of.
+*
+* 7 is the Calibri-11-at-96dpi value every mainstream spreadsheet tool assumes by default, and the same constant ooxml.js's xlsx reader uses -- so a column of a given width reads back the same number of points whether it arrived as .xls or .xlsx. This package has no font-metrics engine and so cannot compute a workbook's actual digit width from whatever font its Normal style really uses: a workbook using a materially narrower or wider font reads column widths that are honestly approximate rather than exact.
+*/
+const MAX_DIGIT_WIDTH_PX = 7;
+/** A Row record's height, in twips, as points. */
+function twipsToPoints(twips) {
+	return twips / TWIPS_PER_POINT;
+}
+/**
+* A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
+*
+* The pixel step reproduces Excel's own integer-pixel-grid truncation rather than smoothing it into a continuous formula, so a width read here matches the pixel count Excel itself would render, and matches what ooxml.js computes for the equivalent xlsx column.
+*/
+function columnWidthToPoints(coldx) {
+	const chars = coldx / 256;
+	const digitWidthAllowance = Math.trunc(128 / MAX_DIGIT_WIDTH_PX);
+	return Math.trunc((256 * chars + digitWidthAllowance) / 256 * MAX_DIGIT_WIDTH_PX) / PIXELS_PER_INCH * POINTS_PER_INCH;
+}
+//#endregion
+exports.columnWidthToPoints = columnWidthToPoints;
+exports.twipsToPoints = twipsToPoints;

package/dist/units.d.cts

@@ -0,0 +1,11 @@
+//#region src/units.d.ts
+/** A Row record's height, in twips, as points. */
+declare function twipsToPoints(twips: number): number;
+/**
+ * A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
+ *
+ * The pixel step reproduces Excel's own integer-pixel-grid truncation rather than smoothing it into a continuous formula, so a width read here matches the pixel count Excel itself would render, and matches what ooxml.js computes for the equivalent xlsx column.
+ */
+declare function columnWidthToPoints(coldx: number): number;
+//#endregion
+export { columnWidthToPoints, twipsToPoints };

package/dist/units.d.ts

@@ -0,0 +1,11 @@
+//#region src/units.d.ts
+/** A Row record's height, in twips, as points. */
+declare function twipsToPoints(twips: number): number;
+/**
+ * A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
+ *
+ * The pixel step reproduces Excel's own integer-pixel-grid truncation rather than smoothing it into a continuous formula, so a width read here matches the pixel count Excel itself would render, and matches what ooxml.js computes for the equivalent xlsx column.
+ */
+declare function columnWidthToPoints(coldx: number): number;
+//#endregion
+export { columnWidthToPoints, twipsToPoints };

package/dist/units.js

@@ -0,0 +1,28 @@
+//#region src/units.ts
+/** Points per inch, and the pixel grid Excel's column-width formula is defined against (96 px/inch, its screen-rendering assumption). */
+const POINTS_PER_INCH = 72;
+const PIXELS_PER_INCH = 96;
+/** A twip is a twentieth of a point; a Row record's miyRw is in twips ([MS-XLS] 2.4.221). */
+const TWIPS_PER_POINT = 20;
+/**
+* The "maximum digit width": the widest rendered width, in pixels, of the digits 0-9 in the workbook's Normal-style font, which is the unit a column width is expressed in multiples of.
+*
+* 7 is the Calibri-11-at-96dpi value every mainstream spreadsheet tool assumes by default, and the same constant ooxml.js's xlsx reader uses -- so a column of a given width reads back the same number of points whether it arrived as .xls or .xlsx. This package has no font-metrics engine and so cannot compute a workbook's actual digit width from whatever font its Normal style really uses: a workbook using a materially narrower or wider font reads column widths that are honestly approximate rather than exact.
+*/
+const MAX_DIGIT_WIDTH_PX = 7;
+/** A Row record's height, in twips, as points. */
+function twipsToPoints(twips) {
+	return twips / TWIPS_PER_POINT;
+}
+/**
+* A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
+*
+* The pixel step reproduces Excel's own integer-pixel-grid truncation rather than smoothing it into a continuous formula, so a width read here matches the pixel count Excel itself would render, and matches what ooxml.js computes for the equivalent xlsx column.
+*/
+function columnWidthToPoints(coldx) {
+	const chars = coldx / 256;
+	const digitWidthAllowance = Math.trunc(128 / MAX_DIGIT_WIDTH_PX);
+	return Math.trunc((256 * chars + digitWidthAllowance) / 256 * MAX_DIGIT_WIDTH_PX) / PIXELS_PER_INCH * POINTS_PER_INCH;
+}
+//#endregion
+export { columnWidthToPoints, twipsToPoints };