@nhtio/adk 0.1.0-master-e6c58205 → 0.1.0-master-89b47bec

package/batteries/media/engines/sheetjs.cjs

@@ -0,0 +1,438 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Cek0wNdY.js");
+const require_tool_registry = require("../../../tool_registry-DwZ6pzN4.js");
+require("../../../guards.cjs");
+const require_batteries_media_contracts = require("../contracts.cjs");
+const require_exceptions = require("../../../exceptions-D79HIKeX.js");
+const require_formats = require("../../../formats-DZVuqZUN.js");
+//#region src/batteries/media/engines/sheetjs.ts
+/**
+* The SheetJS-backed spreadsheet {@link @nhtio/adk/batteries/media/contracts!MediaEngine}:
+* the in-process, cross-environment spreadsheet converter, generator, and structural editor.
+*
+* @module @nhtio/adk/batteries/media/engines/sheetjs
+*
+* @remarks
+* SheetJS (the `xlsx` package) reads and writes the widest spreadsheet matrix of any pure-JS
+* library — XLSX/XLSM/XLSB, every XLS BIFF era, ODS/FODS, CSV, SYLK, DIF, DBF, HTML, RTF,
+* Apple NUMBERS — with no binary, no native bindings, in any environment. This engine exposes
+* that matrix three ways:
+*
+* - **convert**: any readable spreadsheet MIME → any writable format token.
+* - **generate**: `EMPTY_MIME` → any writable token (a blank `Sheet1` workbook, written out).
+* - **edit**: the `sheet.*` structural ops via CSF cell-object surgery. ⚠️ SheetJS Community
+*   Edition does NOT model cell styling — fonts, fills, and comments are STRIPPED by any edit
+*   or convert that round-trips a styled workbook (styling is a SheetJS Pro feature). For
+*   fidelity-preserving edits compose the exceljs engine FIRST in the engines array; this
+*   engine's edits are for unstyled/data workbooks and for breadth (it edits ODS, XLS, and
+*   every other readable format by normalizing through CSF).
+*
+* ⚠️ **Install from the SheetJS CDN, not the npm registry.** The registry copy of `xlsx` is
+* frozen at 0.18.5 (2023) and carries CVE-2023-30533 and CVE-2024-22363; this engine requires
+* `>=0.20.2`. Install: `pnpm add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`
+* (SheetJS recommends vendoring the tarball — see docs.sheetjs.com).
+*
+* `xlsx` is an optional peer dependency, lazily imported on first actual use. The NUMBERS
+* write target additionally loads the ZAHL payload (`xlsx/dist/xlsx.zahl.mjs`, ~110 KB) on
+* first request of that specific target.
+*/
+/** Every format token this engine can write, mapped to the SheetJS bookType that produces it. */
+var BOOKTYPE_BY_TARGET = {
+	xlsx: "xlsx",
+	xlsm: "xlsm",
+	xlsb: "xlsb",
+	xls: "biff8",
+	ods: "ods",
+	fods: "fods",
+	csv: "csv",
+	txt: "txt",
+	html: "html",
+	rtf: "rtf",
+	sylk: "sylk",
+	dif: "dif",
+	dbf: "dbf",
+	numbers: "numbers"
+};
+/** The convert/generation target tokens, json included. */
+var SHEET_WRITE_TARGETS = [...Object.keys(BOOKTYPE_BY_TARGET), "json"];
+/** Output MIME per target token. */
+var MIME_BY_TARGET = {
+	xlsx: require_formats.MIME.XLSX,
+	xlsm: require_formats.MIME.XLSM,
+	xlsb: require_formats.MIME.XLSB,
+	xls: require_formats.MIME.XLS,
+	ods: require_formats.MIME.ODS,
+	fods: require_formats.MIME.FODS,
+	csv: require_formats.MIME.CSV,
+	txt: require_formats.MIME.TXT,
+	html: require_formats.MIME.HTML,
+	rtf: "application/rtf",
+	sylk: require_formats.MIME.SYLK,
+	dif: require_formats.MIME.DIF,
+	dbf: require_formats.MIME.DBF,
+	numbers: require_formats.MIME.NUMBERS,
+	json: require_formats.MIME.JSON
+};
+/**
+* Every spreadsheet MIME this engine reads. SheetJS sniffs the actual format from the bytes
+* (zip vs CFB vs text heuristics), so one entry serves the whole read matrix. Formats SheetJS
+* can parse but that have no standard MIME (Quattro Pro, Works, Lotus variants) are readable
+* whenever a resolver hands us one of these MIMEs for them — the MIME is the only addressable
+* contract the battery has.
+*/
+var SHEET_READ_MIMES = [
+	require_formats.MIME.XLSX,
+	require_formats.MIME.XLSM,
+	require_formats.MIME.XLSB,
+	require_formats.MIME.XLS,
+	require_formats.MIME.ODS,
+	require_formats.MIME.FODS,
+	require_formats.MIME.CSV,
+	require_formats.MIME.NUMBERS,
+	require_formats.MIME.SYLK,
+	require_formats.MIME.DIF,
+	require_formats.MIME.DBF
+];
+/** The structural ops this engine edits (same names the verb table uses). */
+var SHEET_OPS = [
+	"sheet.add_rows",
+	"sheet.add_columns",
+	"sheet.update_cells",
+	"sheet.delete_rows",
+	"sheet.delete_columns",
+	"sheet.rename_sheet",
+	"sheet.add_sheet",
+	"sheet.remove_sheet",
+	"sheet.reorder_sheets",
+	"sheet.transform_table"
+];
+/**
+* Construct the SheetJS-backed spreadsheet engine.
+*
+* @param options - Optional module resolver overrides.
+* @returns The engine.
+*/
+var sheetjsEngine = (options = {}) => {
+	let modPromise;
+	const getXlsx = () => {
+		modPromise ??= Promise.resolve(options.xlsx ? options.xlsx() : Promise.resolve().then(() => require("../../../xlsx-B0sTpEC2.js"))).catch((err) => {
+			throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`the sheetjs engine could not load its peer dependency "xlsx": ${require_tool_registry.isError(err) ? err.message : String(err)} — install it FROM THE SHEETJS CDN (the npm registry copy is stale and vulnerable): pnpm add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`]);
+		});
+		return modPromise;
+	};
+	let zahlPromise;
+	const getZahl = () => {
+		zahlPromise ??= Promise.resolve(options.zahl ? options.zahl() : Promise.resolve().then(() => require("../../../xlsx.zahl-ZIcUQVv8.js"))).then((m) => m.default ?? m, (err) => {
+			const detail = require_tool_registry.isError(err) ? err.message : String(err);
+			throw new Error(`NUMBERS output needs the SheetJS ZAHL payload (xlsx/dist/xlsx.zahl.mjs) and it could not be loaded: ${detail}`);
+		});
+		return zahlPromise;
+	};
+	/** Write `wb` to the requested target token. */
+	const writeOut = async (X, wb, to) => {
+		if (to === "json") {
+			const ws = wb.Sheets[wb.SheetNames[0]];
+			const rows = ws ? X.utils.sheet_to_json(ws, { header: 1 }) : [];
+			return {
+				bytes: new TextEncoder().encode(JSON.stringify(rows)),
+				mimeType: require_formats.MIME.JSON
+			};
+		}
+		const bookType = BOOKTYPE_BY_TARGET[to];
+		if (!bookType) throw new Error(`sheetjs cannot write "${to}"; supported: ${SHEET_WRITE_TARGETS.join(", ")}`);
+		const writeOpts = {
+			bookType,
+			type: "array"
+		};
+		if (to === "numbers") writeOpts.numbers = await getZahl();
+		const out = X.write(wb, writeOpts);
+		return {
+			bytes: ArrayBuffer.isView(out) ? out : new Uint8Array(out),
+			mimeType: MIME_BY_TARGET[to] ?? "application/octet-stream"
+		};
+	};
+	const convert = async (request) => {
+		const X = await getXlsx();
+		const mime = request.mimeType.toLowerCase().split(";")[0].trim();
+		let wb;
+		if (mime === "application/x-adk-empty") {
+			wb = X.utils.book_new();
+			const seed = request.to === "numbers" ? [[""]] : [[]];
+			X.utils.book_append_sheet(wb, X.utils.aoa_to_sheet(seed), "Sheet1");
+		} else {
+			wb = X.read(request.bytes);
+			if (wb.SheetNames.length === 0) throw new Error(`sheetjs parsed ${request.mimeType} but found no worksheets — the file may be corrupt or not actually a spreadsheet`);
+		}
+		const { bytes, mimeType } = await writeOut(X, wb, request.to);
+		return { outputs: [{
+			bytes,
+			mimeType
+		}] };
+	};
+	const edit = async (request) => {
+		const X = await getXlsx();
+		const wb = X.read(request.bytes);
+		if (wb.SheetNames.length === 0) throw new Error("sheetjs parsed the workbook but found no worksheets");
+		const summary = applyEdit(X, wb, request.op, request.args);
+		const { bytes, mimeType } = await writeOut(X, wb, "xlsx");
+		return {
+			bytes,
+			mimeType,
+			summary
+		};
+	};
+	return {
+		id: "sheetjs",
+		converts: [{
+			from: [require_batteries_media_contracts.EMPTY_MIME],
+			to: SHEET_WRITE_TARGETS,
+			convert
+		}, {
+			from: SHEET_READ_MIMES,
+			to: SHEET_WRITE_TARGETS,
+			convert
+		}],
+		edits: [{
+			over: SHEET_READ_MIMES,
+			ops: SHEET_OPS,
+			edit
+		}]
+	};
+};
+var asAoa = (X, ws) => X.utils.sheet_to_json(ws, {
+	header: 1,
+	defval: null
+});
+var resolveSheetName = (wb, sheetArg) => {
+	if (sheetArg === void 0 || sheetArg === null) {
+		const first = wb.SheetNames[0];
+		if (!first) throw new Error("the workbook has no worksheets");
+		return first;
+	}
+	if (typeof sheetArg === "number") {
+		const byIndex = wb.SheetNames[sheetArg - 1];
+		if (byIndex) return byIndex;
+		if (wb.SheetNames.includes(String(sheetArg))) throw new Error(`no sheet at index ${sheetArg}, but a sheet NAMED "${sheetArg}" exists — quote it: sheet="${sheetArg}"`);
+		throw new Error(`sheet index ${sheetArg} is out of range (1-based; the workbook has ${wb.SheetNames.length})`);
+	}
+	const name = String(sheetArg);
+	if (!wb.SheetNames.includes(name)) {
+		const names = wb.SheetNames.map((n) => `"${n}"`).join(", ");
+		throw new Error(`no sheet named "${name}" (sheets: ${names})`);
+	}
+	return name;
+};
+/** Column letters → 1-based number (`A` → 1, `AA` → 27). */
+var columnLetterToNumber = (letters) => {
+	let n = 0;
+	for (const ch of letters.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64);
+	return n;
+};
+/** Parse an A1 address into 1-based row/col. */
+var parseA1 = (address) => {
+	const m = /^([A-Za-z]+)(\d+)$/.exec(address.trim());
+	if (!m) throw new Error(`invalid cell address "${address}" (expected A1 form)`);
+	return {
+		row: Number(m[2]),
+		col: columnLetterToNumber(m[1])
+	};
+};
+var rebuild = (X, wb, name, aoa) => {
+	wb.Sheets[name] = X.utils.aoa_to_sheet(aoa.length > 0 ? aoa : [[]]);
+};
+/** Apply one structural op to the workbook in place; returns the change summary. */
+var applyEdit = (X, wb, op, args) => {
+	switch (op) {
+		case "sheet.add_rows": {
+			const name = resolveSheetName(wb, args.sheet);
+			const rows = args.rows;
+			if (!Array.isArray(rows) || rows.length === 0 || !rows.every(Array.isArray)) throw new Error("rows must be a non-empty array of arrays");
+			const aoa = asAoa(X, wb.Sheets[name]);
+			const before = args.before;
+			const after = args.after;
+			const insertAt = before !== void 0 ? before - 1 : after !== void 0 ? after : aoa.length;
+			aoa.splice(insertAt, 0, ...rows);
+			rebuild(X, wb, name, aoa);
+			return { added: rows.length };
+		}
+		case "sheet.add_columns": {
+			const name = resolveSheetName(wb, args.sheet);
+			const headers = args.headers;
+			const descriptors = args.columns ?? headers?.map((header) => ({ header }));
+			if (!Array.isArray(descriptors) || descriptors.length === 0) throw new Error(`provide headers=a,b or columns='[{"header":"X","values":[1]}]'`);
+			const aoa = asAoa(X, wb.Sheets[name]);
+			const before = args.before;
+			const after = args.after;
+			const width = aoa.reduce((w, r) => Math.max(w, r.length), 0);
+			const insertAt = before !== void 0 ? before - 1 : after !== void 0 ? after : width;
+			for (const [i, col] of descriptors.entries()) {
+				if (typeof col?.header !== "string") throw new Error("every column needs a string header");
+				const columnCells = [col.header, ...col.values ?? []];
+				const rowsNeeded = Math.max(aoa.length, columnCells.length);
+				for (let r = 0; r < rowsNeeded; r++) {
+					aoa[r] ??= [];
+					while (aoa[r].length < insertAt + i) aoa[r].push(null);
+					aoa[r].splice(insertAt + i, 0, columnCells[r] ?? null);
+				}
+			}
+			rebuild(X, wb, name, aoa);
+			return { added: descriptors.length };
+		}
+		case "sheet.update_cells": {
+			const name = resolveSheetName(wb, args.sheet);
+			const updates = args.updates;
+			if (!Array.isArray(updates) || updates.length === 0) throw new Error("updates must be a non-empty array");
+			const ws = wb.Sheets[name];
+			for (const update of updates) {
+				let row;
+				let col;
+				if (typeof update.address === "string") ({row, col} = parseA1(update.address));
+				else {
+					row = Number(update.row);
+					col = typeof update.col === "string" ? columnLetterToNumber(update.col) : Number(update.col);
+					if (!Number.isFinite(row) || !Number.isFinite(col)) throw new Error("each update needs an address (A1) or row+col");
+				}
+				const addr = X.utils.encode_cell({
+					r: row - 1,
+					c: col - 1
+				});
+				const value = update.value;
+				if (typeof value === "string" && value.startsWith("=")) ws[addr] = {
+					t: "n",
+					f: value.slice(1)
+				};
+				else if (value === null || value === void 0) delete ws[addr];
+				else if (typeof value === "number") ws[addr] = {
+					t: "n",
+					v: value
+				};
+				else if (typeof value === "boolean") ws[addr] = {
+					t: "b",
+					v: value
+				};
+				else ws[addr] = {
+					t: "s",
+					v: String(value)
+				};
+				const range = ws["!ref"] ? X.utils.decode_range(ws["!ref"]) : {
+					s: {
+						r: row - 1,
+						c: col - 1
+					},
+					e: {
+						r: row - 1,
+						c: col - 1
+					}
+				};
+				range.s.r = Math.min(range.s.r, row - 1);
+				range.s.c = Math.min(range.s.c, col - 1);
+				range.e.r = Math.max(range.e.r, row - 1);
+				range.e.c = Math.max(range.e.c, col - 1);
+				ws["!ref"] = X.utils.encode_range(range);
+			}
+			return { modified: updates.length };
+		}
+		case "sheet.delete_rows": {
+			const name = resolveSheetName(wb, args.sheet);
+			const rows = args.rows;
+			if (!Array.isArray(rows) || rows.length === 0) throw new Error("rows must be a non-empty array");
+			const aoa = asAoa(X, wb.Sheets[name]);
+			for (const r of [...rows].sort((a, b) => b - a)) aoa.splice(r - 1, 1);
+			rebuild(X, wb, name, aoa);
+			return { removed: rows.length };
+		}
+		case "sheet.delete_columns": {
+			const name = resolveSheetName(wb, args.sheet);
+			const columns = args.columns;
+			if (!Array.isArray(columns) || columns.length === 0) throw new Error("columns must be a non-empty array");
+			const aoa = asAoa(X, wb.Sheets[name]);
+			for (const c of [...columns].sort((a, b) => b - a)) for (const row of aoa) if (row.length >= c) row.splice(c - 1, 1);
+			rebuild(X, wb, name, aoa);
+			return { removed: columns.length };
+		}
+		case "sheet.rename_sheet": {
+			const from = String(args.sheet ?? "");
+			const to = String(args.to ?? "");
+			if (!wb.SheetNames.includes(from)) {
+				const names = wb.SheetNames.map((n) => `"${n}"`).join(", ");
+				throw new Error(`rename targets a sheet NAME; no sheet named "${from}". Sheets: ${names}`);
+			}
+			if (wb.SheetNames.includes(to)) throw new Error(`a sheet named "${to}" already exists`);
+			wb.SheetNames[wb.SheetNames.indexOf(from)] = to;
+			wb.Sheets[to] = wb.Sheets[from];
+			delete wb.Sheets[from];
+			return { modified: 1 };
+		}
+		case "sheet.add_sheet": {
+			const name = String(args.name ?? "");
+			if (!name) throw new Error("add_sheet requires a name");
+			if (wb.SheetNames.includes(name)) throw new Error(`a sheet named "${name}" already exists`);
+			const at = args.at;
+			X.utils.book_append_sheet(wb, X.utils.aoa_to_sheet([[]]), name);
+			if (at !== void 0) {
+				const idx = wb.SheetNames.indexOf(name);
+				wb.SheetNames.splice(idx, 1);
+				wb.SheetNames.splice(Math.max(0, at - 1), 0, name);
+			}
+			return { added: 1 };
+		}
+		case "sheet.remove_sheet": {
+			const name = String(args.sheet ?? "");
+			if (!wb.SheetNames.includes(name)) {
+				const names = wb.SheetNames.map((n) => `"${n}"`).join(", ");
+				throw new Error(`no sheet named "${name}" (sheets: ${names})`);
+			}
+			if (wb.SheetNames.length === 1) throw new Error("cannot remove the only worksheet");
+			wb.SheetNames.splice(wb.SheetNames.indexOf(name), 1);
+			delete wb.Sheets[name];
+			return { removed: 1 };
+		}
+		case "sheet.reorder_sheets": {
+			const order = args.order;
+			if (!Array.isArray(order) || order.length !== wb.SheetNames.length) throw new Error(`order must include every worksheet exactly once (the workbook has ${wb.SheetNames.length})`);
+			const resolved = order.map((ref) => typeof ref === "number" ? wb.SheetNames[ref - 1] : String(ref));
+			if (new Set(resolved).size !== resolved.length || resolved.some((n) => !n || !wb.SheetNames.includes(n))) throw new Error("order must reference every existing worksheet exactly once");
+			wb.SheetNames.length = 0;
+			wb.SheetNames.push(...resolved);
+			return { modified: resolved.length };
+		}
+		case "sheet.transform_table": {
+			const name = resolveSheetName(wb, args.sheet);
+			const headerRow = Number(args.header_row ?? 1);
+			const aoa = asAoa(X, wb.Sheets[name]);
+			const header = (aoa[headerRow - 1] ?? []).map((h) => h === null ? "" : String(h));
+			let modified = 0;
+			const rename = args.rename;
+			if (rename) for (const { from, to } of rename) {
+				const idx = header.indexOf(from);
+				if (idx !== -1) {
+					aoa[headerRow - 1][idx] = to;
+					header[idx] = to;
+					modified++;
+				}
+			}
+			const drop = args.drop;
+			const select = args.select;
+			const toRemove = /* @__PURE__ */ new Set();
+			if (drop) for (const h of drop) {
+				const idx = header.indexOf(h);
+				if (idx !== -1) toRemove.add(idx);
+			}
+			if (select) {
+				for (const [i, element] of header.entries()) if (!select.includes(element)) toRemove.add(i);
+			}
+			if (toRemove.size > 0) {
+				const sorted = [...toRemove].sort((a, b) => b - a);
+				for (const row of aoa) for (const idx of sorted) if (row.length > idx) row.splice(idx, 1);
+				modified += toRemove.size;
+			}
+			rebuild(X, wb, name, aoa);
+			return { modified };
+		}
+		default: throw new Error(`sheetjs does not implement edit op "${op}"`);
+	}
+};
+//#endregion
+exports.sheetjsEngine = sheetjsEngine;
+
+//# sourceMappingURL=sheetjs.cjs.map

package/batteries/media/engines/sheetjs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheetjs.cjs","names":[],"sources":["../../../../src/batteries/media/engines/sheetjs.ts"],"sourcesContent":["/**\n * The SheetJS-backed spreadsheet {@link @nhtio/adk/batteries/media/contracts!MediaEngine}:\n * the in-process, cross-environment spreadsheet converter, generator, and structural editor.\n *\n * @module @nhtio/adk/batteries/media/engines/sheetjs\n *\n * @remarks\n * SheetJS (the `xlsx` package) reads and writes the widest spreadsheet matrix of any pure-JS\n * library — XLSX/XLSM/XLSB, every XLS BIFF era, ODS/FODS, CSV, SYLK, DIF, DBF, HTML, RTF,\n * Apple NUMBERS — with no binary, no native bindings, in any environment. This engine exposes\n * that matrix three ways:\n *\n * - **convert**: any readable spreadsheet MIME → any writable format token.\n * - **generate**: `EMPTY_MIME` → any writable token (a blank `Sheet1` workbook, written out).\n * - **edit**: the `sheet.*` structural ops via CSF cell-object surgery. ⚠️ SheetJS Community\n *   Edition does NOT model cell styling — fonts, fills, and comments are STRIPPED by any edit\n *   or convert that round-trips a styled workbook (styling is a SheetJS Pro feature). For\n *   fidelity-preserving edits compose the exceljs engine FIRST in the engines array; this\n *   engine's edits are for unstyled/data workbooks and for breadth (it edits ODS, XLS, and\n *   every other readable format by normalizing through CSF).\n *\n * ⚠️ **Install from the SheetJS CDN, not the npm registry.** The registry copy of `xlsx` is\n * frozen at 0.18.5 (2023) and carries CVE-2023-30533 and CVE-2024-22363; this engine requires\n * `>=0.20.2`. Install: `pnpm add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`\n * (SheetJS recommends vendoring the tarball — see docs.sheetjs.com).\n *\n * `xlsx` is an optional peer dependency, lazily imported on first actual use. The NUMBERS\n * write target additionally loads the ZAHL payload (`xlsx/dist/xlsx.zahl.mjs`, ~110 KB) on\n * first request of that specific target.\n */\n\nimport { MIME } from '../formats'\nimport { EMPTY_MIME } from '../contracts'\nimport { isError } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type * as XlsxNS from 'xlsx'\nimport type {\n  MediaEngine,\n  ConvertRequest,\n  ConvertResult,\n  EditRequest,\n  EditResult,\n} from '../contracts'\n\ntype XlsxModule = typeof XlsxNS\n\n/** Options for {@link sheetjsEngine}. */\nexport interface SheetjsEngineOptions {\n  /** Override the module resolution (tests / custom builds). Default: `import('xlsx')`. */\n  xlsx?: () => XlsxModule | Promise<XlsxModule>\n  /**\n   * Override the ZAHL payload resolution for NUMBERS output (tests / custom builds).\n   * Default: `import('xlsx/dist/xlsx.zahl.mjs')`.\n   */\n  zahl?: () => unknown | Promise<unknown>\n}\n\n/** Every format token this engine can write, mapped to the SheetJS bookType that produces it. */\nconst BOOKTYPE_BY_TARGET: Record<string, string> = {\n  xlsx: 'xlsx',\n  xlsm: 'xlsm',\n  xlsb: 'xlsb',\n  xls: 'biff8',\n  ods: 'ods',\n  fods: 'fods',\n  csv: 'csv',\n  txt: 'txt',\n  html: 'html',\n  rtf: 'rtf',\n  sylk: 'sylk',\n  dif: 'dif',\n  dbf: 'dbf',\n  numbers: 'numbers',\n  // json is synthesized via sheet_to_json, not a bookType — handled separately.\n}\n\n/** The convert/generation target tokens, json included. */\nconst SHEET_WRITE_TARGETS: readonly string[] = [...Object.keys(BOOKTYPE_BY_TARGET), 'json']\n\n/** Output MIME per target token. */\nconst MIME_BY_TARGET: Record<string, string> = {\n  xlsx: MIME.XLSX,\n  xlsm: MIME.XLSM,\n  xlsb: MIME.XLSB,\n  xls: MIME.XLS,\n  ods: MIME.ODS,\n  fods: MIME.FODS,\n  csv: MIME.CSV,\n  txt: MIME.TXT,\n  html: MIME.HTML,\n  rtf: 'application/rtf',\n  sylk: MIME.SYLK,\n  dif: MIME.DIF,\n  dbf: MIME.DBF,\n  numbers: MIME.NUMBERS,\n  json: MIME.JSON,\n}\n\n/**\n * Every spreadsheet MIME this engine reads. SheetJS sniffs the actual format from the bytes\n * (zip vs CFB vs text heuristics), so one entry serves the whole read matrix. Formats SheetJS\n * can parse but that have no standard MIME (Quattro Pro, Works, Lotus variants) are readable\n * whenever a resolver hands us one of these MIMEs for them — the MIME is the only addressable\n * contract the battery has.\n */\nconst SHEET_READ_MIMES: readonly string[] = [\n  MIME.XLSX,\n  MIME.XLSM,\n  MIME.XLSB,\n  MIME.XLS,\n  MIME.ODS,\n  MIME.FODS,\n  MIME.CSV,\n  MIME.NUMBERS,\n  MIME.SYLK,\n  MIME.DIF,\n  MIME.DBF,\n]\n\n/** The structural ops this engine edits (same names the verb table uses). */\nconst SHEET_OPS: readonly string[] = [\n  'sheet.add_rows',\n  'sheet.add_columns',\n  'sheet.update_cells',\n  'sheet.delete_rows',\n  'sheet.delete_columns',\n  'sheet.rename_sheet',\n  'sheet.add_sheet',\n  'sheet.remove_sheet',\n  'sheet.reorder_sheets',\n  'sheet.transform_table',\n]\n\n/**\n * Construct the SheetJS-backed spreadsheet engine.\n *\n * @param options - Optional module resolver overrides.\n * @returns The engine.\n */\nexport const sheetjsEngine = (options: SheetjsEngineOptions = {}): MediaEngine => {\n  let modPromise: Promise<XlsxModule> | undefined\n  const getXlsx = (): Promise<XlsxModule> => {\n    modPromise ??= Promise.resolve(options.xlsx ? options.xlsx() : import('xlsx')).catch((err) => {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `the sheetjs engine could not load its peer dependency \"xlsx\": ${detail} — install it FROM THE SHEETJS CDN (the npm registry copy is stale and vulnerable): pnpm add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`,\n      ])\n    })\n    return modPromise\n  }\n\n  let zahlPromise: Promise<unknown> | undefined\n  const getZahl = (): Promise<unknown> => {\n    zahlPromise ??= Promise.resolve(\n      options.zahl ? options.zahl() : import('xlsx/dist/xlsx.zahl.mjs' as string)\n    ).then(\n      (m) => (m as { default?: unknown }).default ?? m,\n      (err) => {\n        const detail = isError(err) ? err.message : String(err)\n        throw new Error(\n          `NUMBERS output needs the SheetJS ZAHL payload (xlsx/dist/xlsx.zahl.mjs) and it could not be loaded: ${detail}`\n        )\n      }\n    )\n    return zahlPromise\n  }\n\n  /** Write `wb` to the requested target token. */\n  const writeOut = async (\n    X: XlsxModule,\n    wb: XlsxNS.WorkBook,\n    to: string\n  ): Promise<{ bytes: Uint8Array; mimeType: string }> => {\n    if (to === 'json') {\n      const ws = wb.Sheets[wb.SheetNames[0]]\n      const rows = ws ? X.utils.sheet_to_json(ws, { header: 1 }) : []\n      return {\n        bytes: new TextEncoder().encode(JSON.stringify(rows)),\n        mimeType: MIME.JSON,\n      }\n    }\n    const bookType = BOOKTYPE_BY_TARGET[to]\n    if (!bookType) {\n      throw new Error(`sheetjs cannot write \"${to}\"; supported: ${SHEET_WRITE_TARGETS.join(', ')}`)\n    }\n    const writeOpts: XlsxNS.WritingOptions = {\n      bookType: bookType as XlsxNS.BookType,\n      type: 'array',\n    }\n    if (to === 'numbers') {\n      ;(writeOpts as { numbers?: unknown }).numbers = await getZahl()\n    }\n    const out = X.write(wb, writeOpts) as ArrayBuffer | Uint8Array\n    const bytes = ArrayBuffer.isView(out) ? out : new Uint8Array(out)\n    return { bytes, mimeType: MIME_BY_TARGET[to] ?? 'application/octet-stream' }\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const X = await getXlsx()\n    const mime = request.mimeType.toLowerCase().split(';')[0].trim()\n    let wb: XlsxNS.WorkBook\n    if (mime === EMPTY_MIME) {\n      // Generation: a blank workbook with one empty Sheet1 (steps expect ≥1 worksheet).\n      // NUMBERS refuses a zero-cell sheet, so that target seeds one blank cell.\n      wb = X.utils.book_new()\n      const seed = request.to === 'numbers' ? [['']] : [[]]\n      X.utils.book_append_sheet(wb, X.utils.aoa_to_sheet(seed), 'Sheet1')\n    } else {\n      wb = X.read(request.bytes)\n      if (wb.SheetNames.length === 0) {\n        throw new Error(\n          `sheetjs parsed ${request.mimeType} but found no worksheets — the file may be corrupt or not actually a spreadsheet`\n        )\n      }\n    }\n    const { bytes, mimeType } = await writeOut(X, wb, request.to)\n    return { outputs: [{ bytes, mimeType }] }\n  }\n\n  const edit = async (request: EditRequest): Promise<EditResult> => {\n    const X = await getXlsx()\n    const wb = X.read(request.bytes)\n    if (wb.SheetNames.length === 0) {\n      throw new Error('sheetjs parsed the workbook but found no worksheets')\n    }\n    const summary = applyEdit(X, wb, request.op, request.args)\n    const { bytes, mimeType } = await writeOut(X, wb, 'xlsx')\n    return { bytes, mimeType, summary }\n  }\n\n  return {\n    id: 'sheetjs',\n    converts: [\n      // Generation: blank Sheet1 workbook, written to any target.\n      { from: [EMPTY_MIME], to: SHEET_WRITE_TARGETS, convert },\n      // The read matrix: format is sniffed from bytes, so one entry serves every MIME.\n      { from: SHEET_READ_MIMES, to: SHEET_WRITE_TARGETS, convert },\n    ],\n    edits: [\n      // ⚠️ CE strips styling (fonts/fills/comments) — compose exceljs first for fidelity.\n      { over: SHEET_READ_MIMES, ops: SHEET_OPS, edit },\n    ],\n  }\n}\n\n// ── CSF structural edits ──────────────────────────────────────────────────────\n// SheetJS CE models a worksheet as a cell map; these ops normalize to array-of-arrays,\n// operate, and rebuild. Styling does not survive this (CE has none to carry).\n\nconst asAoa = (X: XlsxModule, ws: XlsxNS.WorkSheet): unknown[][] =>\n  X.utils.sheet_to_json(ws, { header: 1, defval: null }) as unknown[][]\n\nconst resolveSheetName = (wb: XlsxNS.WorkBook, sheetArg: unknown): string => {\n  if (sheetArg === undefined || sheetArg === null) {\n    const first = wb.SheetNames[0]\n    if (!first) throw new Error('the workbook has no worksheets')\n    return first\n  }\n  if (typeof sheetArg === 'number') {\n    const byIndex = wb.SheetNames[sheetArg - 1]\n    if (byIndex) return byIndex\n    if (wb.SheetNames.includes(String(sheetArg))) {\n      throw new Error(\n        `no sheet at index ${sheetArg}, but a sheet NAMED \"${sheetArg}\" exists — quote it: sheet=\"${sheetArg}\"`\n      )\n    }\n    throw new Error(\n      `sheet index ${sheetArg} is out of range (1-based; the workbook has ${wb.SheetNames.length})`\n    )\n  }\n  const name = String(sheetArg)\n  if (!wb.SheetNames.includes(name)) {\n    const names = wb.SheetNames.map((n) => `\"${n}\"`).join(', ')\n    throw new Error(`no sheet named \"${name}\" (sheets: ${names})`)\n  }\n  return name\n}\n\n/** Column letters → 1-based number (`A` → 1, `AA` → 27). */\nconst columnLetterToNumber = (letters: string): number => {\n  let n = 0\n  for (const ch of letters.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64)\n  return n\n}\n\n/** Parse an A1 address into 1-based row/col. */\nconst parseA1 = (address: string): { row: number; col: number } => {\n  const m = /^([A-Za-z]+)(\\d+)$/.exec(address.trim())\n  if (!m) throw new Error(`invalid cell address \"${address}\" (expected A1 form)`)\n  return { row: Number(m[2]), col: columnLetterToNumber(m[1]) }\n}\n\nconst rebuild = (X: XlsxModule, wb: XlsxNS.WorkBook, name: string, aoa: unknown[][]): void => {\n  wb.Sheets[name] = X.utils.aoa_to_sheet(aoa.length > 0 ? aoa : [[]])\n}\n\n/** Apply one structural op to the workbook in place; returns the change summary. */\nconst applyEdit = (\n  X: XlsxModule,\n  wb: XlsxNS.WorkBook,\n  op: string,\n  args: Record<string, unknown>\n): { added?: number; removed?: number; modified?: number; warnings?: string[] } => {\n  switch (op) {\n    case 'sheet.add_rows': {\n      const name = resolveSheetName(wb, args.sheet)\n      const rows = args.rows as unknown[][]\n      if (!Array.isArray(rows) || rows.length === 0 || !rows.every(Array.isArray)) {\n        throw new Error('rows must be a non-empty array of arrays')\n      }\n      const aoa = asAoa(X, wb.Sheets[name])\n      const before = args.before as number | undefined\n      const after = args.after as number | undefined\n      const insertAt = before !== undefined ? before - 1 : after !== undefined ? after : aoa.length\n      aoa.splice(insertAt, 0, ...rows)\n      rebuild(X, wb, name, aoa)\n      return { added: rows.length }\n    }\n    case 'sheet.add_columns': {\n      const name = resolveSheetName(wb, args.sheet)\n      const headers = args.headers as string[] | undefined\n      const descriptors: Array<{ header: string; values?: unknown[] }> | undefined =\n        (args.columns as Array<{ header: string; values?: unknown[] }> | undefined) ??\n        headers?.map((header) => ({ header }))\n      if (!Array.isArray(descriptors) || descriptors.length === 0) {\n        throw new Error(`provide headers=a,b or columns='[{\"header\":\"X\",\"values\":[1]}]'`)\n      }\n      const aoa = asAoa(X, wb.Sheets[name])\n      const before = args.before as number | undefined\n      const after = args.after as number | undefined\n      const width = aoa.reduce((w, r) => Math.max(w, r.length), 0)\n      const insertAt = before !== undefined ? before - 1 : after !== undefined ? after : width\n      for (const [i, col] of descriptors.entries()) {\n        if (typeof col?.header !== 'string') throw new Error('every column needs a string header')\n        const columnCells = [col.header, ...(col.values ?? [])]\n        const rowsNeeded = Math.max(aoa.length, columnCells.length)\n        for (let r = 0; r < rowsNeeded; r++) {\n          aoa[r] ??= []\n          while (aoa[r].length < insertAt + i) aoa[r].push(null)\n          aoa[r].splice(insertAt + i, 0, columnCells[r] ?? null)\n        }\n      }\n      rebuild(X, wb, name, aoa)\n      return { added: descriptors.length }\n    }\n    case 'sheet.update_cells': {\n      const name = resolveSheetName(wb, args.sheet)\n      const updates = args.updates as Array<Record<string, unknown>>\n      if (!Array.isArray(updates) || updates.length === 0) {\n        throw new Error('updates must be a non-empty array')\n      }\n      const ws = wb.Sheets[name]\n      for (const update of updates) {\n        let row: number\n        let col: number\n        if (typeof update.address === 'string') {\n          ;({ row, col } = parseA1(update.address))\n        } else {\n          row = Number(update.row)\n          col =\n            typeof update.col === 'string' ? columnLetterToNumber(update.col) : Number(update.col)\n          if (!Number.isFinite(row) || !Number.isFinite(col)) {\n            throw new Error('each update needs an address (A1) or row+col')\n          }\n        }\n        const addr = X.utils.encode_cell({ r: row - 1, c: col - 1 })\n        const value = update.value\n        if (typeof value === 'string' && value.startsWith('=')) {\n          ws[addr] = { t: 'n', f: value.slice(1) }\n        } else if (value === null || value === undefined) {\n          delete ws[addr]\n        } else if (typeof value === 'number') {\n          ws[addr] = { t: 'n', v: value }\n        } else if (typeof value === 'boolean') {\n          ws[addr] = { t: 'b', v: value }\n        } else {\n          ws[addr] = { t: 's', v: String(value) }\n        }\n        const range = ws['!ref']\n          ? X.utils.decode_range(ws['!ref'] as string)\n          : { s: { r: row - 1, c: col - 1 }, e: { r: row - 1, c: col - 1 } }\n        range.s.r = Math.min(range.s.r, row - 1)\n        range.s.c = Math.min(range.s.c, col - 1)\n        range.e.r = Math.max(range.e.r, row - 1)\n        range.e.c = Math.max(range.e.c, col - 1)\n        ws['!ref'] = X.utils.encode_range(range)\n      }\n      return { modified: updates.length }\n    }\n    case 'sheet.delete_rows': {\n      const name = resolveSheetName(wb, args.sheet)\n      const rows = args.rows as number[]\n      if (!Array.isArray(rows) || rows.length === 0)\n        throw new Error('rows must be a non-empty array')\n      const aoa = asAoa(X, wb.Sheets[name])\n      for (const r of [...rows].sort((a, b) => b - a)) aoa.splice(r - 1, 1)\n      rebuild(X, wb, name, aoa)\n      return { removed: rows.length }\n    }\n    case 'sheet.delete_columns': {\n      const name = resolveSheetName(wb, args.sheet)\n      const columns = args.columns as number[]\n      if (!Array.isArray(columns) || columns.length === 0) {\n        throw new Error('columns must be a non-empty array')\n      }\n      const aoa = asAoa(X, wb.Sheets[name])\n      for (const c of [...columns].sort((a, b) => b - a)) {\n        for (const row of aoa) if (row.length >= c) row.splice(c - 1, 1)\n      }\n      rebuild(X, wb, name, aoa)\n      return { removed: columns.length }\n    }\n    case 'sheet.rename_sheet': {\n      const from = String(args.sheet ?? '')\n      const to = String(args.to ?? '')\n      if (!wb.SheetNames.includes(from)) {\n        const names = wb.SheetNames.map((n) => `\"${n}\"`).join(', ')\n        throw new Error(`rename targets a sheet NAME; no sheet named \"${from}\". Sheets: ${names}`)\n      }\n      if (wb.SheetNames.includes(to)) throw new Error(`a sheet named \"${to}\" already exists`)\n      wb.SheetNames[wb.SheetNames.indexOf(from)] = to\n      wb.Sheets[to] = wb.Sheets[from]\n      delete wb.Sheets[from]\n      return { modified: 1 }\n    }\n    case 'sheet.add_sheet': {\n      const name = String(args.name ?? '')\n      if (!name) throw new Error('add_sheet requires a name')\n      if (wb.SheetNames.includes(name)) throw new Error(`a sheet named \"${name}\" already exists`)\n      const at = args.at as number | undefined\n      X.utils.book_append_sheet(wb, X.utils.aoa_to_sheet([[]]), name)\n      if (at !== undefined) {\n        const idx = wb.SheetNames.indexOf(name)\n        wb.SheetNames.splice(idx, 1)\n        wb.SheetNames.splice(Math.max(0, at - 1), 0, name)\n      }\n      return { added: 1 }\n    }\n    case 'sheet.remove_sheet': {\n      const name = String(args.sheet ?? '')\n      if (!wb.SheetNames.includes(name)) {\n        const names = wb.SheetNames.map((n) => `\"${n}\"`).join(', ')\n        throw new Error(`no sheet named \"${name}\" (sheets: ${names})`)\n      }\n      if (wb.SheetNames.length === 1) throw new Error('cannot remove the only worksheet')\n      wb.SheetNames.splice(wb.SheetNames.indexOf(name), 1)\n      delete wb.Sheets[name]\n      return { removed: 1 }\n    }\n    case 'sheet.reorder_sheets': {\n      const order = args.order as Array<string | number>\n      if (!Array.isArray(order) || order.length !== wb.SheetNames.length) {\n        throw new Error(\n          `order must include every worksheet exactly once (the workbook has ${wb.SheetNames.length})`\n        )\n      }\n      const resolved = order.map((ref) =>\n        typeof ref === 'number' ? wb.SheetNames[ref - 1] : String(ref)\n      )\n      if (\n        new Set(resolved).size !== resolved.length ||\n        resolved.some((n) => !n || !wb.SheetNames.includes(n))\n      ) {\n        throw new Error('order must reference every existing worksheet exactly once')\n      }\n      wb.SheetNames.length = 0\n      wb.SheetNames.push(...resolved)\n      return { modified: resolved.length }\n    }\n    case 'sheet.transform_table': {\n      const name = resolveSheetName(wb, args.sheet)\n      const headerRow = Number(args.header_row ?? 1)\n      const aoa = asAoa(X, wb.Sheets[name])\n      const header = (aoa[headerRow - 1] ?? []).map((h) => (h === null ? '' : String(h)))\n      let modified = 0\n      const rename = args.rename as Array<{ from: string; to: string }> | undefined\n      if (rename) {\n        for (const { from, to } of rename) {\n          const idx = header.indexOf(from)\n          if (idx !== -1) {\n            aoa[headerRow - 1][idx] = to\n            header[idx] = to\n            modified++\n          }\n        }\n      }\n      const drop = args.drop as string[] | undefined\n      const select = args.select as string[] | undefined\n      const toRemove = new Set<number>()\n      if (drop)\n        for (const h of drop) {\n          const idx = header.indexOf(h)\n          if (idx !== -1) toRemove.add(idx)\n        }\n      if (select) {\n        for (const [i, element] of header.entries()) {\n          if (!select.includes(element)) toRemove.add(i)\n        }\n      }\n      if (toRemove.size > 0) {\n        const sorted = [...toRemove].sort((a, b) => b - a)\n        for (const row of aoa) for (const idx of sorted) if (row.length > idx) row.splice(idx, 1)\n        modified += toRemove.size\n      }\n      rebuild(X, wb, name, aoa)\n      return { modified }\n    }\n    default:\n      throw new Error(`sheetjs does not implement edit op \"${op}\"`)\n  }\n}\n"],"mappings":"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"}

package/batteries/media/engines/sheetjs.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The SheetJS-backed spreadsheet {@link @nhtio/adk/batteries/media/contracts!MediaEngine}:
+ * the in-process, cross-environment spreadsheet converter, generator, and structural editor.
+ *
+ * @module @nhtio/adk/batteries/media/engines/sheetjs
+ *
+ * @remarks
+ * SheetJS (the `xlsx` package) reads and writes the widest spreadsheet matrix of any pure-JS
+ * library — XLSX/XLSM/XLSB, every XLS BIFF era, ODS/FODS, CSV, SYLK, DIF, DBF, HTML, RTF,
+ * Apple NUMBERS — with no binary, no native bindings, in any environment. This engine exposes
+ * that matrix three ways:
+ *
+ * - **convert**: any readable spreadsheet MIME → any writable format token.
+ * - **generate**: `EMPTY_MIME` → any writable token (a blank `Sheet1` workbook, written out).
+ * - **edit**: the `sheet.*` structural ops via CSF cell-object surgery. ⚠️ SheetJS Community
+ *   Edition does NOT model cell styling — fonts, fills, and comments are STRIPPED by any edit
+ *   or convert that round-trips a styled workbook (styling is a SheetJS Pro feature). For
+ *   fidelity-preserving edits compose the exceljs engine FIRST in the engines array; this
+ *   engine's edits are for unstyled/data workbooks and for breadth (it edits ODS, XLS, and
+ *   every other readable format by normalizing through CSF).
+ *
+ * ⚠️ **Install from the SheetJS CDN, not the npm registry.** The registry copy of `xlsx` is
+ * frozen at 0.18.5 (2023) and carries CVE-2023-30533 and CVE-2024-22363; this engine requires
+ * `>=0.20.2`. Install: `pnpm add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`
+ * (SheetJS recommends vendoring the tarball — see docs.sheetjs.com).
+ *
+ * `xlsx` is an optional peer dependency, lazily imported on first actual use. The NUMBERS
+ * write target additionally loads the ZAHL payload (`xlsx/dist/xlsx.zahl.mjs`, ~110 KB) on
+ * first request of that specific target.
+ */
+import type * as XlsxNS from "../../../bundled_xlsx";
+import type { MediaEngine } from "../contracts";
+type XlsxModule = typeof XlsxNS;
+/** Options for {@link sheetjsEngine}. */
+export interface SheetjsEngineOptions {
+    /** Override the module resolution (tests / custom builds). Default: `import('xlsx')`. */
+    xlsx?: () => XlsxModule | Promise<XlsxModule>;
+    /**
+     * Override the ZAHL payload resolution for NUMBERS output (tests / custom builds).
+     * Default: `import('xlsx/dist/xlsx.zahl.mjs')`.
+     */
+    zahl?: () => unknown | Promise<unknown>;
+}
+/**
+ * Construct the SheetJS-backed spreadsheet engine.
+ *
+ * @param options - Optional module resolver overrides.
+ * @returns The engine.
+ */
+export declare const sheetjsEngine: (options?: SheetjsEngineOptions) => MediaEngine;
+export {};