@office-kit/xlsx 0.8.0

package/dist/cell-D9CaNKnU.mjs

@@ -0,0 +1,320 @@
+import { o as OpenXmlSchemaError } from "./exceptions-D-CFwxgm.mjs";
+import { a as columnLetterFromIndex, n as MAX_ROW, t as MAX_COL } from "./coordinate-96Ecci4d.mjs";
+import { t as ERROR_CODES } from "./inference-B3ES3KEJ.mjs";
+//#region src/cell/rich-text.ts
+function makeTextRun(text, font) {
+	if (typeof text !== "string") throw new OpenXmlSchemaError("makeTextRun: text must be a string");
+	return Object.freeze(font !== void 0 ? {
+		text,
+		font
+	} : { text });
+}
+function makeRichText(runs) {
+	const out = runs.map((r) => Object.isFrozen(r) ? r : makeTextRun(r.text, r.font));
+	return Object.freeze(out);
+}
+/**
+* Concatenate the plain-text content of a rich-text value (rich-text
+* read paths often want the raw text without formatting).
+*/
+function richTextToString(rt) {
+	let out = "";
+	for (const r of rt) out += r.text;
+	return out;
+}
+//#endregion
+//#region src/cell/cell.ts
+const validateCoord = (row, col) => {
+	if (!Number.isInteger(row) || row < 1 || row > 1048576) throw new OpenXmlSchemaError(`Cell row ${row} out of range [1, ${MAX_ROW}]`);
+	if (!Number.isInteger(col) || col < 1 || col > 16384) throw new OpenXmlSchemaError(`Cell col ${col} out of range [1, ${MAX_COL}]`);
+};
+/** Build a fresh Cell. Validates coordinates against the OOXML grid bounds. */
+function makeCell(row, col, value = null, styleId = 0) {
+	validateCoord(row, col);
+	return {
+		row,
+		col,
+		value,
+		styleId
+	};
+}
+/** Format a Cell's coordinate as the canonical "A1" string. */
+function getCoordinate(c) {
+	return `${columnLetterFromIndex(c.col)}${c.row}`;
+}
+/**
+* Direct value setter. No type inference, no validation beyond the union — the
+* caller is in charge. Use {@link bindValue} for the "do what I mean" path.
+*/
+function setCellValue(c, value) {
+	c.value = value;
+}
+/**
+* "Smart" setter: infers the cell value from a JS runtime value.
+* - `string` starting with `=` → formula
+* - `string` matching an Excel error token → error variant
+* - other primitives / Date / null pass through verbatim
+*
+* Intentionally not the default — explicit is clearer for typed code, and
+* inferring on every write costs measurable time on the worksheet write hot
+* path.
+*/
+function bindValue(c, value) {
+	if (typeof value === "string") {
+		if (value.length > 0 && value.charCodeAt(0) === 61) {
+			setFormula(c, value.slice(1));
+			return;
+		}
+		if (ERROR_CODES.has(value)) {
+			c.value = {
+				kind: "error",
+				code: value
+			};
+			return;
+		}
+		c.value = value;
+		return;
+	}
+	c.value = value;
+}
+/** Plain `=A1+B1` style formula. Cached value is optional but recommended for round-trip. */
+function setFormula(c, formula, opts) {
+	c.value = {
+		kind: "formula",
+		t: "normal",
+		formula,
+		...opts?.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
+	};
+}
+/** Array (CSE) formula spanning a `ref` range. */
+function setArrayFormula(c, ref, formula, opts) {
+	c.value = {
+		kind: "formula",
+		t: "array",
+		formula,
+		ref,
+		...opts?.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
+	};
+}
+/**
+* Shared formula. The first cell in the group carries the formula text + ref;
+* subsequent cells with the same `si` carry only the index and Excel
+* reconstructs the formula via reference shifting.
+*/
+function setSharedFormula(c, si, formula, ref, opts) {
+	if (!Number.isInteger(si) || si < 0) throw new OpenXmlSchemaError(`setSharedFormula: si must be a non-negative integer; got ${si}`);
+	c.value = {
+		kind: "formula",
+		t: "shared",
+		formula: formula ?? "",
+		si,
+		...ref !== void 0 ? { ref } : {},
+		...opts?.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
+	};
+}
+/**
+* Set a data-table formula on a cell. Preserves all the dt-specific attributes
+* so the writer can re-emit `<f t="dataTable" r1="..." />` verbatim and Excel
+* keeps treating the cell as a Data Table cell.
+*/
+function setDataTableFormula(c, formula, opts) {
+	c.value = {
+		kind: "formula",
+		t: "dataTable",
+		formula,
+		ref: opts.ref,
+		...opts.r1 !== void 0 ? { r1: opts.r1 } : {},
+		...opts.r2 !== void 0 ? { r2: opts.r2 } : {},
+		...opts.dt2D !== void 0 ? { dt2D: opts.dt2D } : {},
+		...opts.dtr !== void 0 ? { dtr: opts.dtr } : {},
+		...opts.del1 !== void 0 ? { del1: opts.del1 } : {},
+		...opts.del2 !== void 0 ? { del2: opts.del2 } : {},
+		...opts.aca !== void 0 ? { aca: opts.aca } : {},
+		...opts.ca !== void 0 ? { ca: opts.ca } : {},
+		...opts.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
+	};
+}
+/** Build a `{ kind: 'error', code }` cell value. */
+function makeErrorValue(code) {
+	if (!ERROR_CODES.has(code)) throw new OpenXmlSchemaError(`makeErrorValue: unknown error code "${code}"`);
+	return Object.freeze({
+		kind: "error",
+		code
+	});
+}
+/** Build a `{ kind: 'duration', ms }` cell value. */
+function makeDurationValue(ms) {
+	if (!Number.isFinite(ms)) throw new OpenXmlSchemaError(`makeDurationValue: ms "${ms}" is not finite`);
+	return Object.freeze({
+		kind: "duration",
+		ms
+	});
+}
+/** True iff `c.value` is the formula variant. */
+function isFormulaCell(c) {
+	return isFormulaValue(c.value);
+}
+/** True iff `c.value` is the rich-text variant. */
+function isRichTextCell(c) {
+	return isRichTextValue(c.value);
+}
+/** Returns true iff the cell has no content. */
+function isEmptyCell(c) {
+	return c.value === null;
+}
+/**
+* Type guard for `MergedCell` — true iff the cell is a placeholder for a
+* merged-range covered cell (the top-left of a merged range holds the value;
+* the rest are `MergedCell`). Use this to filter merge-placeholders out of
+* value-walking loops.
+*/
+function isMergedCell(c) {
+	return c.merged === true;
+}
+/** Returns true iff the cell holds an Excel error value (`#REF!`, `#NAME?`, …). */
+function isErrorCell(c) {
+	return isErrorValue(c.value);
+}
+/**
+* Get the formula text from a formula-bearing cell, or `undefined` for
+* non-formula cells. Equivalent to: isFormulaValue(c.value) ? c.value.formula :
+* undefined but spares callers the type-narrow + member access.
+*/
+function getFormulaText(c) {
+	return isFormulaValue(c.value) ? c.value.formula : void 0;
+}
+/**
+* Get the cached value Excel last computed for a formula cell, or `undefined`
+* for non-formula / uncached cells. Useful for `data_only` read paths that want
+* the displayed result without re-evaluating.
+*/
+function getCachedFormulaValue(c) {
+	return isFormulaValue(c.value) ? c.value.cachedValue : void 0;
+}
+/** True iff `v` is the formula variant. */
+function isFormulaValue(v) {
+	return typeof v === "object" && v !== null && v.kind === "formula";
+}
+/** True iff `v` is the rich-text variant. */
+function isRichTextValue(v) {
+	return typeof v === "object" && v !== null && v.kind === "rich-text";
+}
+/** True iff `v` is the error variant. */
+function isErrorValue(v) {
+	return typeof v === "object" && v !== null && v.kind === "error";
+}
+/** True iff `v` is the duration variant. */
+function isDurationValue(v) {
+	return typeof v === "object" && v !== null && v.kind === "duration";
+}
+/**
+* Coerce a CellValue to its plain-string display form. Numbers / booleans
+* convert via `String`; rich text concatenates run text; formulas yield the
+* cached value (or empty string when uncached); errors yield their Excel token;
+* durations yield `"<ms> ms"` with no formatting; Dates yield
+* `Date.toISOString()`; `null` yields `""`.
+*
+* Pass `opts.dateFormat` to override the Date renderer (e.g. a locale-specific
+* format) and `opts.emptyText` to substitute a different placeholder for
+* `null` cells.
+*/
+function cellValueAsString(v, opts) {
+	const emptyText = opts?.emptyText ?? "";
+	if (v === null) return emptyText;
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean") return String(v);
+	if (v instanceof Date) return opts?.dateFormat ? opts.dateFormat(v) : v.toISOString();
+	if (isRichTextValue(v)) return richTextToString(v.runs);
+	if (isFormulaValue(v)) {
+		if (v.cachedValue === void 0) return "";
+		return typeof v.cachedValue === "string" ? v.cachedValue : String(v.cachedValue);
+	}
+	if (isErrorValue(v)) return v.code;
+	if (isDurationValue(v)) return `${v.ms} ms`;
+	return "";
+}
+/**
+* Coerce a CellValue to `boolean | undefined`. Booleans pass through; `'TRUE'`
+* / `'true'` and `'FALSE'` / `'false'` (case-insensitive) parse to true /
+* false; numbers yield `false` for 0 and `true` for any other finite value
+* (matching Excel's truthy-number coercion); formula cells return their cached
+* boolean if any. Everything else (null, Date, error, duration, rich-text,
+* non-bool strings) yields `undefined`.
+*/
+function cellValueAsBoolean(v) {
+	if (typeof v === "boolean") return v;
+	if (typeof v === "number") {
+		if (!Number.isFinite(v)) return void 0;
+		return v !== 0;
+	}
+	if (typeof v === "string") {
+		const lc = v.toLowerCase();
+		if (lc === "true") return true;
+		if (lc === "false") return false;
+		return;
+	}
+	if (isFormulaValue(v) && typeof v.cachedValue === "boolean") return v.cachedValue;
+}
+/**
+* Coerce a CellValue to a `Date` when one is meaningful. Pass-through for
+* `Date`-typed values; ISO-8601 strings (anything `new Date(s)` parses to a
+* finite time) round-trip; durations are interpreted as `new Date(ms)`.
+* Numbers, booleans, formulas, errors, rich text, and null all return
+* `undefined` — this helper does **not** apply the Excel-serial-to-Date
+* conversion (use `excelToDate` for that).
+*/
+function cellValueAsDate(v) {
+	if (v instanceof Date) return v;
+	if (typeof v === "string") {
+		if (v === "") return void 0;
+		const t = Date.parse(v);
+		if (!Number.isFinite(t)) return void 0;
+		return new Date(t);
+	}
+	if (isDurationValue(v)) return new Date(v.ms);
+}
+/**
+* Coerce a CellValue to a number when one is meaningful. Booleans yield 0/1;
+* numeric strings parse via `Number(s)`; rich-text concats then parses;
+* formulas with a numeric cached value pass through. Returns `undefined` when
+* there's no sensible numeric reading (text strings, errors, dates, durations,
+* null, empty).
+*/
+function cellValueAsNumber(v) {
+	if (v === null) return void 0;
+	if (typeof v === "number") return Number.isFinite(v) ? v : void 0;
+	if (typeof v === "boolean") return v ? 1 : 0;
+	if (typeof v === "string") {
+		if (v === "") return void 0;
+		const n = Number(v);
+		return Number.isFinite(n) ? n : void 0;
+	}
+	if (isFormulaValue(v) && typeof v.cachedValue === "number") return v.cachedValue;
+}
+/**
+* Map a CellValue to the most natural JS primitive for display / export.
+* Unlike `cellValueAsString`/`cellValueAsNumber`/etc., which each force a
+* single target type and return `undefined` when the value can't be coerced,
+* this returns whatever primitive best represents the union variant:
+*
+* - `null` → `null`
+* - `string` / `number` / `boolean` / `Date` → passthrough
+* - rich text → joined run text (`string`)
+* - formula → recursive on `cachedValue` (`null` when uncached)
+* - error → error code (`string`)
+* - duration → `ms` (`number`)
+*/
+function cellValueAsPrimitive(v) {
+	if (v === null) return null;
+	if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+	if (v instanceof Date) return v;
+	if (isRichTextValue(v)) return richTextToString(v.runs);
+	if (isFormulaValue(v)) return v.cachedValue === void 0 ? null : v.cachedValue;
+	if (isErrorValue(v)) return v.code;
+	if (isDurationValue(v)) return v.ms;
+	return null;
+}
+//#endregion
+export { setCellValue as C, makeRichText as D, setSharedFormula as E, makeTextRun as O, setArrayFormula as S, setFormula as T, isRichTextCell as _, cellValueAsPrimitive as a, makeDurationValue as b, getCoordinate as c, isEmptyCell as d, isErrorCell as f, isMergedCell as g, isFormulaValue as h, cellValueAsNumber as i, richTextToString as k, getFormulaText as l, isFormulaCell as m, cellValueAsBoolean as n, cellValueAsString as o, isErrorValue as p, cellValueAsDate as r, getCachedFormulaValue as s, bindValue as t, isDurationValue as u, isRichTextValue as v, setDataTableFormula as w, makeErrorValue as x, makeCell as y };
+
+//# sourceMappingURL=cell-D9CaNKnU.mjs.map

package/dist/cell-D9CaNKnU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-D9CaNKnU.mjs","names":[],"sources":["../src/cell/rich-text.ts","../src/cell/cell.ts"],"sourcesContent":["// Inline rich-text runs.\n//\n// A rich-text cell value is `{ kind: 'rich-text', runs }`. Each run is\n// a string segment with an optional InlineFont describing the in-line\n// formatting (font name, size, bold / italic / underline, colour, …).\n// Run-level fields use OOXML's short attribute names (`sz`, `b`, `i`,\n// `u`) so the writer can splice them into `<rPr>` directly without\n// renaming.\n\nimport type { Color } from '../styles/colors';\nimport { OpenXmlSchemaError } from '../utils/exceptions';\n\n/** Underline styles per openpyxl's cell-level NestedNoneSet. */\nexport type InlineUnderline = 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';\n\nexport type InlineVertAlign = 'baseline' | 'superscript' | 'subscript';\n\nexport interface InlineFont {\n  readonly name?: string;\n  readonly sz?: number;\n  readonly b?: boolean;\n  readonly i?: boolean;\n  readonly u?: InlineUnderline;\n  readonly strike?: boolean;\n  readonly outline?: boolean;\n  readonly shadow?: boolean;\n  readonly condense?: boolean;\n  readonly extend?: boolean;\n  readonly vertAlign?: InlineVertAlign;\n  readonly color?: Color;\n  readonly family?: number;\n  readonly charset?: number;\n  readonly scheme?: 'major' | 'minor';\n}\n\nexport interface TextRun {\n  readonly text: string;\n  readonly font?: InlineFont;\n}\n\n/** A frozen array of TextRuns. The shared cell value shape under `kind: 'rich-text'`. */\nexport type RichText = ReadonlyArray<TextRun>;\n\nexport function makeTextRun(text: string, font?: InlineFont): TextRun {\n  if (typeof text !== 'string') {\n    throw new OpenXmlSchemaError('makeTextRun: text must be a string');\n  }\n  return Object.freeze(font !== undefined ? { text, font } : { text });\n}\n\nexport function makeRichText(runs: ReadonlyArray<TextRun | { text: string; font?: InlineFont }>): RichText {\n  const out = runs.map((r) => (Object.isFrozen(r) ? (r as TextRun) : makeTextRun(r.text, r.font)));\n  return Object.freeze(out);\n}\n\n/**\n * Concatenate the plain-text content of a rich-text value (rich-text\n * read paths often want the raw text without formatting).\n */\nexport function richTextToString(rt: RichText): string {\n  let out = '';\n  for (const r of rt) out += r.text;\n  return out;\n}\n","// Cell value model. Mirrors openpyxl/openpyxl/cell/cell.py.\n//\n// A Cell is a plain mutable object: the worksheet stores millions of these, so\n// per-cell freezes / spreads aren't viable on the hot path. The public surface\n// stays small — makeCell + getCoordinate + targeted setters — and uses\n// discriminated unions for the special CellValue shapes (formula, rich text,\n// duration, error).\n\nimport { columnLetterFromIndex, MAX_COL, MAX_ROW } from '../utils/coordinate';\nimport { OpenXmlSchemaError } from '../utils/exceptions';\nimport { ERROR_CODES } from '../utils/inference';\nimport { type RichText, richTextToString } from './rich-text';\n\n/** Excel error tokens. */\nexport type ExcelErrorCode = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#GETTING_DATA';\n\n/** Formula sub-kind — drives the OOXML `<f t=\"…\">` attribute. */\nexport type FormulaKind = 'normal' | 'array' | 'shared' | 'dataTable';\n\nexport interface FormulaValue {\n  readonly kind: 'formula';\n  readonly formula: string;\n  readonly t: FormulaKind;\n  /** Cached value Excel last computed for the cell, used when `data_only` reads it back. */\n  readonly cachedValue?: number | string | boolean;\n  /** Range string (`\"A1:A10\"`) for array / shared / dataTable formulas. */\n  readonly ref?: string;\n  /** Shared-formula index. */\n  readonly si?: number;\n  /** Data-table specific fields (mirrors openpyxl DataTableFormula). */\n  readonly r1?: string;\n  readonly r2?: string;\n  readonly dt2D?: boolean;\n  readonly dtr?: boolean;\n  readonly del1?: boolean;\n  readonly del2?: boolean;\n  readonly aca?: boolean;\n  readonly ca?: boolean;\n}\n\nexport type CellValue =\n  | number\n  | string\n  | boolean\n  | Date\n  | { kind: 'duration'; ms: number }\n  | { kind: 'error'; code: ExcelErrorCode }\n  | { kind: 'rich-text'; runs: RichText }\n  | FormulaValue\n  | null;\n\nexport interface Cell {\n  /** 1-based row index. */\n  row: number;\n  /** 1-based column index. */\n  col: number;\n  /** Effective cell value. `null` represents an empty cell. */\n  value: CellValue;\n  /** Index into Workbook.styles.cellXfs. 0 = default. */\n  styleId: number;\n  /** Optional reference to a Hyperlink registered on the worksheet. */\n  hyperlinkId?: number;\n  /** Optional reference to a Comment registered on the worksheet. */\n  commentId?: number;\n}\n\n/** Marker subtype for the placeholder cells inside a merged range (top-left holds the value). */\nexport interface MergedCell extends Cell {\n  merged: true;\n}\n\nconst validateCoord = (row: number, col: number): void => {\n  if (!Number.isInteger(row) || row < 1 || row > MAX_ROW) {\n    throw new OpenXmlSchemaError(`Cell row ${row} out of range [1, ${MAX_ROW}]`);\n  }\n  if (!Number.isInteger(col) || col < 1 || col > MAX_COL) {\n    throw new OpenXmlSchemaError(`Cell col ${col} out of range [1, ${MAX_COL}]`);\n  }\n};\n\n/** Build a fresh Cell. Validates coordinates against the OOXML grid bounds. */\nexport function makeCell(row: number, col: number, value: CellValue = null, styleId = 0): Cell {\n  validateCoord(row, col);\n  return { row, col, value, styleId };\n}\n\n/** Format a Cell's coordinate as the canonical \"A1\" string. */\nexport function getCoordinate(c: Cell): string {\n  return `${columnLetterFromIndex(c.col)}${c.row}`;\n}\n\n/**\n * Direct value setter. No type inference, no validation beyond the union — the\n * caller is in charge. Use {@link bindValue} for the \"do what I mean\" path.\n */\nexport function setCellValue(c: Cell, value: CellValue): void {\n  c.value = value;\n}\n\n/**\n * \"Smart\" setter: infers the cell value from a JS runtime value.\n * - `string` starting with `=` → formula\n * - `string` matching an Excel error token → error variant\n * - other primitives / Date / null pass through verbatim\n *\n * Intentionally not the default — explicit is clearer for typed code, and\n * inferring on every write costs measurable time on the worksheet write hot\n * path.\n */\nexport function bindValue(c: Cell, value: number | string | boolean | Date | null): void {\n  if (typeof value === 'string') {\n    if (value.length > 0 && value.charCodeAt(0) === 61 /* '=' */) {\n      setFormula(c, value.slice(1));\n      return;\n    }\n    if (ERROR_CODES.has(value)) {\n      c.value = { kind: 'error', code: value as ExcelErrorCode };\n      return;\n    }\n    c.value = value;\n    return;\n  }\n  c.value = value;\n}\n\n// ---- formula setters -------------------------------------------------------\n\n/** Plain `=A1+B1` style formula. Cached value is optional but recommended for round-trip. */\nexport function setFormula(c: Cell, formula: string, opts?: { cachedValue?: FormulaValue['cachedValue'] }): void {\n  const v: FormulaValue = {\n    kind: 'formula',\n    t: 'normal',\n    formula,\n    ...(opts?.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  };\n  c.value = v;\n}\n\n/** Array (CSE) formula spanning a `ref` range. */\nexport function setArrayFormula(\n  c: Cell,\n  ref: string,\n  formula: string,\n  opts?: { cachedValue?: FormulaValue['cachedValue'] },\n): void {\n  const v: FormulaValue = {\n    kind: 'formula',\n    t: 'array',\n    formula,\n    ref,\n    ...(opts?.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  };\n  c.value = v;\n}\n\n/**\n * Shared formula. The first cell in the group carries the formula text + ref;\n * subsequent cells with the same `si` carry only the index and Excel\n * reconstructs the formula via reference shifting.\n */\nexport function setSharedFormula(\n  c: Cell,\n  si: number,\n  formula?: string,\n  ref?: string,\n  opts?: { cachedValue?: FormulaValue['cachedValue'] },\n): void {\n  if (!Number.isInteger(si) || si < 0) {\n    throw new OpenXmlSchemaError(`setSharedFormula: si must be a non-negative integer; got ${si}`);\n  }\n  const v: FormulaValue = {\n    kind: 'formula',\n    t: 'shared',\n    formula: formula ?? '',\n    si,\n    ...(ref !== undefined ? { ref } : {}),\n    ...(opts?.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  };\n  c.value = v;\n}\n\n/**\n * Excel data-table formula (`<f t=\"dataTable\">`). These appear as the \"What-if\n * Analysis → Data Table\" feature output: a 1- or 2-variable sensitivity grid\n * where the formula references one or two input cells. The wire format mirrors\n * openpyxl's `DataTableFormula`:\n *\n * - `ref`     — inclusive cell range the formula spans.\n * - `r1`, `r2`— input cell coordinates (\"$A$1\" etc.).\n * - `dt2D`    — true for two-variable tables (uses both r1 and r2).\n * - `dtr`     — row-direction flag (true) vs column-direction (false).\n * - `del1`/`del2` — Excel marks one of these true when the\n * corresponding input cell has been deleted; the formula keeps round-tripping\n * so Excel can show the warning state.\n * - `aca`/`ca` — alwaysCalculate / calculate flags.\n */\nexport interface DataTableFormulaOpts {\n  ref: string;\n  r1?: string;\n  r2?: string;\n  dt2D?: boolean;\n  dtr?: boolean;\n  del1?: boolean;\n  del2?: boolean;\n  aca?: boolean;\n  ca?: boolean;\n  cachedValue?: FormulaValue['cachedValue'];\n}\n\n/**\n * Set a data-table formula on a cell. Preserves all the dt-specific attributes\n * so the writer can re-emit `<f t=\"dataTable\" r1=\"...\" />` verbatim and Excel\n * keeps treating the cell as a Data Table cell.\n */\nexport function setDataTableFormula(c: Cell, formula: string, opts: DataTableFormulaOpts): void {\n  const v: FormulaValue = {\n    kind: 'formula',\n    t: 'dataTable',\n    formula,\n    ref: opts.ref,\n    ...(opts.r1 !== undefined ? { r1: opts.r1 } : {}),\n    ...(opts.r2 !== undefined ? { r2: opts.r2 } : {}),\n    ...(opts.dt2D !== undefined ? { dt2D: opts.dt2D } : {}),\n    ...(opts.dtr !== undefined ? { dtr: opts.dtr } : {}),\n    ...(opts.del1 !== undefined ? { del1: opts.del1 } : {}),\n    ...(opts.del2 !== undefined ? { del2: opts.del2 } : {}),\n    ...(opts.aca !== undefined ? { aca: opts.aca } : {}),\n    ...(opts.ca !== undefined ? { ca: opts.ca } : {}),\n    ...(opts.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  };\n  c.value = v;\n}\n\n// ---- value-shape helpers ---------------------------------------------------\n\n/** Build a `{ kind: 'error', code }` cell value. */\nexport function makeErrorValue(code: ExcelErrorCode): { kind: 'error'; code: ExcelErrorCode } {\n  if (!ERROR_CODES.has(code)) {\n    throw new OpenXmlSchemaError(`makeErrorValue: unknown error code \"${code}\"`);\n  }\n  return Object.freeze({ kind: 'error', code });\n}\n\n/** Build a `{ kind: 'duration', ms }` cell value. */\nexport function makeDurationValue(ms: number): { kind: 'duration'; ms: number } {\n  if (!Number.isFinite(ms)) {\n    throw new OpenXmlSchemaError(`makeDurationValue: ms \"${ms}\" is not finite`);\n  }\n  return Object.freeze({ kind: 'duration', ms });\n}\n\n/** True iff `c.value` is the formula variant. */\nexport function isFormulaCell(c: Cell): boolean {\n  return isFormulaValue(c.value);\n}\n\n/** True iff `c.value` is the rich-text variant. */\nexport function isRichTextCell(c: Cell): boolean {\n  return isRichTextValue(c.value);\n}\n\n/** Returns true iff the cell has no content. */\nexport function isEmptyCell(c: Cell): boolean {\n  return c.value === null;\n}\n\n/**\n * Type guard for `MergedCell` — true iff the cell is a placeholder for a\n * merged-range covered cell (the top-left of a merged range holds the value;\n * the rest are `MergedCell`). Use this to filter merge-placeholders out of\n * value-walking loops.\n */\nexport function isMergedCell(c: Cell): c is MergedCell {\n  return (c as MergedCell).merged === true;\n}\n\n/** Returns true iff the cell holds an Excel error value (`#REF!`, `#NAME?`, …). */\nexport function isErrorCell(c: Cell): boolean {\n  return isErrorValue(c.value);\n}\n\n/**\n * Get the formula text from a formula-bearing cell, or `undefined` for\n * non-formula cells. Equivalent to: isFormulaValue(c.value) ? c.value.formula :\n * undefined but spares callers the type-narrow + member access.\n */\nexport function getFormulaText(c: Cell): string | undefined {\n  return isFormulaValue(c.value) ? c.value.formula : undefined;\n}\n\n/**\n * Get the cached value Excel last computed for a formula cell, or `undefined`\n * for non-formula / uncached cells. Useful for `data_only` read paths that want\n * the displayed result without re-evaluating.\n */\nexport function getCachedFormulaValue(c: Cell): number | string | boolean | undefined {\n  return isFormulaValue(c.value) ? c.value.cachedValue : undefined;\n}\n\n// ---- value-level type guards + coercion ----------------------------------\n\n/** True iff `v` is the formula variant. */\nexport function isFormulaValue(v: CellValue): v is FormulaValue {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'formula';\n}\n\n/** True iff `v` is the rich-text variant. */\nexport function isRichTextValue(v: CellValue): v is { kind: 'rich-text'; runs: RichText } {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'rich-text';\n}\n\n/** True iff `v` is the error variant. */\nexport function isErrorValue(v: CellValue): v is { kind: 'error'; code: ExcelErrorCode } {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'error';\n}\n\n/** True iff `v` is the duration variant. */\nexport function isDurationValue(v: CellValue): v is { kind: 'duration'; ms: number } {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'duration';\n}\n\nexport interface CellValueAsStringOptions {\n  /** Renderer for `Date` cells. Defaults to `d => d.toISOString()`. */\n  dateFormat?: (value: Date) => string;\n  /** Replacement for the `null` cell value. Defaults to `''`. */\n  emptyText?: string;\n}\n\n/**\n * Coerce a CellValue to its plain-string display form. Numbers / booleans\n * convert via `String`; rich text concatenates run text; formulas yield the\n * cached value (or empty string when uncached); errors yield their Excel token;\n * durations yield `\"<ms> ms\"` with no formatting; Dates yield\n * `Date.toISOString()`; `null` yields `\"\"`.\n *\n * Pass `opts.dateFormat` to override the Date renderer (e.g. a locale-specific\n * format) and `opts.emptyText` to substitute a different placeholder for\n * `null` cells.\n */\nexport function cellValueAsString(v: CellValue, opts?: CellValueAsStringOptions): string {\n  const emptyText = opts?.emptyText ?? '';\n  if (v === null) return emptyText;\n  if (typeof v === 'string') return v;\n  if (typeof v === 'number' || typeof v === 'boolean') return String(v);\n  if (v instanceof Date) return opts?.dateFormat ? opts.dateFormat(v) : v.toISOString();\n  if (isRichTextValue(v)) return richTextToString(v.runs);\n  if (isFormulaValue(v)) {\n    if (v.cachedValue === undefined) return '';\n    return typeof v.cachedValue === 'string' ? v.cachedValue : String(v.cachedValue);\n  }\n  if (isErrorValue(v)) return v.code;\n  if (isDurationValue(v)) return `${v.ms} ms`;\n  return '';\n}\n\n/**\n * Coerce a CellValue to `boolean | undefined`. Booleans pass through; `'TRUE'`\n * / `'true'` and `'FALSE'` / `'false'` (case-insensitive) parse to true /\n * false; numbers yield `false` for 0 and `true` for any other finite value\n * (matching Excel's truthy-number coercion); formula cells return their cached\n * boolean if any. Everything else (null, Date, error, duration, rich-text,\n * non-bool strings) yields `undefined`.\n */\nexport function cellValueAsBoolean(v: CellValue): boolean | undefined {\n  if (typeof v === 'boolean') return v;\n  if (typeof v === 'number') {\n    if (!Number.isFinite(v)) return undefined;\n    return v !== 0;\n  }\n  if (typeof v === 'string') {\n    const lc = v.toLowerCase();\n    if (lc === 'true') return true;\n    if (lc === 'false') return false;\n    return undefined;\n  }\n  if (isFormulaValue(v) && typeof v.cachedValue === 'boolean') return v.cachedValue;\n  return undefined;\n}\n\n/**\n * Coerce a CellValue to a `Date` when one is meaningful. Pass-through for\n * `Date`-typed values; ISO-8601 strings (anything `new Date(s)` parses to a\n * finite time) round-trip; durations are interpreted as `new Date(ms)`.\n * Numbers, booleans, formulas, errors, rich text, and null all return\n * `undefined` — this helper does **not** apply the Excel-serial-to-Date\n * conversion (use `excelToDate` for that).\n */\nexport function cellValueAsDate(v: CellValue): Date | undefined {\n  if (v instanceof Date) return v;\n  if (typeof v === 'string') {\n    if (v === '') return undefined;\n    const t = Date.parse(v);\n    if (!Number.isFinite(t)) return undefined;\n    return new Date(t);\n  }\n  if (isDurationValue(v)) return new Date(v.ms);\n  return undefined;\n}\n\n/**\n * Coerce a CellValue to a number when one is meaningful. Booleans yield 0/1;\n * numeric strings parse via `Number(s)`; rich-text concats then parses;\n * formulas with a numeric cached value pass through. Returns `undefined` when\n * there's no sensible numeric reading (text strings, errors, dates, durations,\n * null, empty).\n */\nexport function cellValueAsNumber(v: CellValue): number | undefined {\n  if (v === null) return undefined;\n  if (typeof v === 'number') return Number.isFinite(v) ? v : undefined;\n  if (typeof v === 'boolean') return v ? 1 : 0;\n  if (typeof v === 'string') {\n    if (v === '') return undefined;\n    const n = Number(v);\n    return Number.isFinite(n) ? n : undefined;\n  }\n  if (isFormulaValue(v) && typeof v.cachedValue === 'number') return v.cachedValue;\n  return undefined;\n}\n\n/**\n * Map a CellValue to the most natural JS primitive for display / export.\n * Unlike `cellValueAsString`/`cellValueAsNumber`/etc., which each force a\n * single target type and return `undefined` when the value can't be coerced,\n * this returns whatever primitive best represents the union variant:\n *\n * - `null` → `null`\n * - `string` / `number` / `boolean` / `Date` → passthrough\n * - rich text → joined run text (`string`)\n * - formula → recursive on `cachedValue` (`null` when uncached)\n * - error → error code (`string`)\n * - duration → `ms` (`number`)\n */\nexport function cellValueAsPrimitive(v: CellValue): string | number | boolean | Date | null {\n  if (v === null) return null;\n  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') return v;\n  if (v instanceof Date) return v;\n  if (isRichTextValue(v)) return richTextToString(v.runs);\n  if (isFormulaValue(v)) {\n    return v.cachedValue === undefined ? null : v.cachedValue;\n  }\n  if (isErrorValue(v)) return v.code;\n  if (isDurationValue(v)) return v.ms;\n  return null;\n}\n"],"mappings":"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"}