xls-codec 1.0.2 → 2.0.0

package/dist/number-format.d.ts

@@ -1,32 +0,0 @@
-//#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

@@ -1,296 +0,0 @@
-//#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 };