@happyvertical/smrt-spreadsheets 0.0.0-stage → 0.61.0

package/dist/import/index.js

@@ -0,0 +1,975 @@
+import { a as validatePlan, i as loadOrder, n as IMPORT_FIELD_TYPES, o as ImportPlanError, r as PLAN_KEY_PATTERN, s as ImportRunError, t as DEFAULT_PLAN_LIMITS } from "../chunks/plan-BAV2jEzl.js";
+import { address, range } from "@happyvertical/spreadsheets";
+//#region src/import/coerce.ts
+var EMPTY = {
+	value: null,
+	type: "empty"
+};
+var DECIMAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
+var ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+function plainDecimal(value) {
+	const text = String(value);
+	const match = /^(-?)(\d+)(?:\.(\d+))?e([+-]\d+)$/.exec(text);
+	if (!match) return text;
+	const [, sign, whole, fraction = "", exp] = match;
+	const digits = whole + fraction;
+	const point = whole.length + Number(exp);
+	if (point <= 0) return `${sign}0.${"0".repeat(-point)}${digits}`;
+	if (point >= digits.length) return sign + digits + "0".repeat(point - digits.length);
+	return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+function failure(code, detail) {
+	return {
+		ok: false,
+		code,
+		detail
+	};
+}
+function isoDate(date) {
+	return date.toISOString().slice(0, 10);
+}
+function describeCell(cell) {
+	if (!cell || cell.type === "empty" || cell.value === null) return cell?.type === "error" ? cell.error ?? "#VALUE!" : "";
+	const value = cell.value;
+	const text = value instanceof Date ? value.toISOString() : typeof value === "number" ? cell.originalText ?? plainDecimal(value) : String(value);
+	return text.length > 80 ? `${text.slice(0, 77)}...` : text;
+}
+function isBlankCell(cell, trim = true) {
+	if (!cell || cell.type === "empty" || cell.value === null) return cell?.type !== "error";
+	if (cell.type === "error") return false;
+	if (typeof cell.value === "string") return trim ? cell.value.trim().length === 0 : cell.value.length === 0;
+	return false;
+}
+function numberText(cell) {
+	return cell.originalText ?? plainDecimal(cell.value);
+}
+function digitCount(text) {
+	return text.replace(/[^0-9]/g, "").length;
+}
+function hasLeadingZeros(text) {
+	return /^[+-]?0\d/.test(text.trim());
+}
+function decimalOf(cell, code) {
+	if (cell.type === "number" && typeof cell.value === "number") {
+		if (!Number.isFinite(cell.value)) return {
+			ok: false,
+			result: failure(code, "not a finite number")
+		};
+		return {
+			ok: true,
+			value: cell.value
+		};
+	}
+	if (cell.type === "text" && typeof cell.value === "string") {
+		const text = cell.value.trim();
+		if (!DECIMAL.test(text)) return {
+			ok: false,
+			result: failure(code, `"${text}" is not a number`)
+		};
+		if (hasLeadingZeros(text)) return {
+			ok: false,
+			result: failure(code, `"${text}" has leading zeros; keep it as text`)
+		};
+		if (digitCount(text) >= 16) return {
+			ok: false,
+			result: failure(code === "not-integer" ? "unsafe-integer" : "unsafe-number", `"${text}" has too many digits to hold as a number`)
+		};
+		const value = Number(text);
+		if (!Number.isFinite(value)) return {
+			ok: false,
+			result: failure(code, "not a finite number")
+		};
+		return {
+			ok: true,
+			value
+		};
+	}
+	return {
+		ok: false,
+		result: failure(code, `a ${cell.type} cell is not a number`)
+	};
+}
+var TRUE_WORDS = /* @__PURE__ */ new Set([
+	"true",
+	"yes",
+	"y",
+	"1"
+]);
+var FALSE_WORDS = /* @__PURE__ */ new Set([
+	"false",
+	"no",
+	"n",
+	"0"
+]);
+function validDate(year, month, day) {
+	const probe = new Date(Date.UTC(year, month - 1, day));
+	return probe.getUTCFullYear() === year && probe.getUTCMonth() === month - 1 && probe.getUTCDate() === day;
+}
+function coerceCell(cell, field, choiceSet) {
+	const c = cell ?? EMPTY;
+	if (c.type === "error") return failure("cell-error", c.error ?? "#VALUE!");
+	if (field.type === "reference") return failure("not-coercible", "reference values resolve through a lookup");
+	if (isBlankCell(c, field.type !== "text")) return {
+		ok: true,
+		value: null
+	};
+	switch (field.type) {
+		case "text":
+			if (typeof c.value === "string") return {
+				ok: true,
+				value: c.value
+			};
+			if (c.type === "number") return {
+				ok: true,
+				value: numberText(c)
+			};
+			if (c.value instanceof Date) return {
+				ok: true,
+				value: isoDate(c.value)
+			};
+			return {
+				ok: true,
+				value: String(c.value)
+			};
+		case "number": {
+			const parsed = decimalOf(c, "not-number");
+			return parsed.ok ? {
+				ok: true,
+				value: parsed.value + 0
+			} : parsed.result;
+		}
+		case "integer": {
+			const parsed = decimalOf(c, "not-integer");
+			if (!parsed.ok) return parsed.result;
+			if (!Number.isInteger(parsed.value)) return failure("not-integer", `${plainDecimal(parsed.value)} is not whole`);
+			if (!Number.isSafeInteger(parsed.value)) return failure("unsafe-integer", "beyond the safe integer range");
+			return {
+				ok: true,
+				value: parsed.value + 0
+			};
+		}
+		case "boolean": {
+			if (c.type === "boolean") return {
+				ok: true,
+				value: c.value
+			};
+			const word = c.type === "number" && typeof c.value === "number" ? String(c.value) : typeof c.value === "string" ? c.value.trim().toLowerCase() : "";
+			if (TRUE_WORDS.has(word)) return {
+				ok: true,
+				value: true
+			};
+			if (FALSE_WORDS.has(word)) return {
+				ok: true,
+				value: false
+			};
+			return failure("not-boolean", `"${describeCell(c)}" is not yes/no`);
+		}
+		case "date":
+			if (c.value instanceof Date) return {
+				ok: true,
+				value: isoDate(c.value)
+			};
+			if (c.type === "text" && typeof c.value === "string") {
+				const match = ISO_DATE.exec(c.value.trim());
+				if (match && validDate(+match[1], +match[2], +match[3])) return {
+					ok: true,
+					value: `${match[1]}-${match[2]}-${match[3]}`
+				};
+			}
+			return failure("not-date", `"${describeCell(c)}" is not a date`);
+		case "money": {
+			const parsed = decimalOf(c, "not-money");
+			if (!parsed.ok) return parsed.result;
+			const scale = field.money?.scale ?? 0;
+			const minor = parsed.value * 10 ** scale;
+			const rounded = Math.round(minor);
+			if (!Number.isFinite(minor) || Math.abs(minor - rounded) > 1e-6 || !Number.isSafeInteger(rounded)) return failure("not-money", `${plainDecimal(parsed.value)} does not fit ${scale} decimal places`);
+			return {
+				ok: true,
+				value: rounded + 0
+			};
+		}
+		case "choice": {
+			const text = typeof c.value === "string" ? c.value.trim() : c.type === "number" ? numberText(c) : String(c.value);
+			if (choiceSet ? choiceSet.has(text) : field.choices?.includes(text)) return {
+				ok: true,
+				value: text
+			};
+			return failure("not-choice", `"${text}" is not one of the choices`);
+		}
+	}
+}
+//#endregion
+//#region src/import/limits.ts
+var DEFAULT_MAX_CELLS = 25e4;
+var DEFAULT_MAX_ROWS_PER_TABLE = 1e4;
+var DEFAULT_MAX_WORK = 2e7;
+var DEFAULT_IMPORT_LIMITS = Object.freeze({
+	maxCells: DEFAULT_MAX_CELLS,
+	maxRowsPerTable: DEFAULT_MAX_ROWS_PER_TABLE,
+	maxWork: DEFAULT_MAX_WORK
+});
+//#endregion
+//#region src/import/evaluate.ts
+function lastOccupiedRow(sheet) {
+	let last = 0;
+	for (const [row] of sheet.cells.rows()) last = Math.max(last, row);
+	return last;
+}
+var WorkBudget = class {
+	constructor(maxWork) {
+		this.maxWork = maxWork;
+	}
+	maxWork;
+	used = 0;
+	charge(units) {
+		this.used += units;
+		if (this.used > this.maxWork) throw new ImportRunError("work-over-limit", `Reading the workbook needs more than ${this.maxWork} units of work.`, { maxWork: this.maxWork });
+	}
+};
+var Evaluation = class {
+	constructor(plan, budget) {
+		this.budget = budget;
+		for (const table of plan.tables) {
+			budget.charge(1 + table.fields.length);
+			const byKey = /* @__PURE__ */ new Map();
+			for (const field of table.fields) {
+				byKey.set(field.key, field);
+				if (field.choices) {
+					budget.charge(field.choices.length);
+					this.choiceSets.set(field, new Set(field.choices));
+				}
+			}
+			this.fields.set(table.key, byKey);
+		}
+	}
+	budget;
+	rows = /* @__PURE__ */ new Map();
+	/** table key -> field key -> field. */
+	fields = /* @__PURE__ */ new Map();
+	/** Fields with choices -> their choices as a set. */
+	choiceSets = /* @__PURE__ */ new Map();
+	charge(units) {
+		this.budget.charge(units);
+	}
+	occupied(sheet) {
+		let known = this.rows.get(sheet);
+		if (!known) {
+			this.charge(sheet.cells.size);
+			known = [...sheet.cells.rows()];
+			this.rows.set(sheet, known);
+		}
+		return known;
+	}
+};
+function lowerBound(rows, row) {
+	let low = 0;
+	let high = rows.length;
+	while (low < high) {
+		const mid = low + high >> 1;
+		if (rows[mid][0] < row) low = mid + 1;
+		else high = mid;
+	}
+	return low;
+}
+function fieldColumns(field) {
+	const columns = [];
+	if (field.column !== void 0) columns.push(field.column);
+	if (field.reference) columns.push(...field.reference.columns);
+	if (field.cachedColumn !== void 0) columns.push(field.cachedColumn);
+	return columns;
+}
+function digitsAsNumber(cell) {
+	if (!cell) return void 0;
+	let text;
+	if (cell.type === "text" && typeof cell.value === "string") text = cell.value.trim();
+	else if (cell.type === "number" && typeof cell.value === "number") {
+		text = cell.originalText;
+		if (text === void 0) return Number.isInteger(cell.value) && Math.abs(cell.value) >= 0x38d7ea4c68000 ? String(cell.value) : void 0;
+	}
+	if (text === void 0 || !/^[+-]?\d+$/.test(text)) return void 0;
+	if (text.replace(/^[+-]/, "").length >= 16) return text;
+	if (hasLeadingZeros(text)) return text;
+}
+function keyText(values) {
+	return JSON.stringify(values);
+}
+function evaluatePlan(plan, workbook, sink, budget = new WorkBudget(DEFAULT_MAX_WORK)) {
+	const evaluation = new Evaluation(plan, budget);
+	const result = /* @__PURE__ */ new Map();
+	for (const table of plan.tables) result.set(table.key, evaluateTable(table, workbook, sink, evaluation));
+	return result;
+}
+function evaluateTable(table, workbook, sink, evaluation) {
+	const out = {
+		table,
+		readable: false,
+		rows: [],
+		read: 0,
+		skipped: 0,
+		rejected: 0
+	};
+	const { sheet: sheetName, range: a1, headerRow } = table.source;
+	const sheet = workbook.sheets.find((candidate) => candidate.name === sheetName);
+	if (!sheet) {
+		sink.add({
+			code: "sheet-missing",
+			severity: "error",
+			table: table.key,
+			sheet: sheetName,
+			message: `Sheet "${sheetName}" is not in the workbook.`
+		});
+		return out;
+	}
+	let box;
+	try {
+		box = range(a1);
+	} catch {
+		sink.add({
+			code: "range-invalid",
+			severity: "error",
+			table: table.key,
+			sheet: sheetName,
+			message: `Range "${a1}" is not a valid A1 range.`
+		});
+		return out;
+	}
+	let structural = false;
+	if (headerRow < box.start.row || headerRow > box.end.row) {
+		structural = true;
+		sink.add({
+			code: "header-outside-range",
+			severity: "error",
+			table: table.key,
+			sheet: sheetName,
+			row: headerRow,
+			message: `Header row ${headerRow} is outside ${a1}.`
+		});
+	}
+	for (const field of table.fields) for (const column of fieldColumns(field)) if (column < box.start.col || column > box.end.col) {
+		structural = true;
+		sink.add({
+			code: "column-outside-range",
+			severity: "error",
+			table: table.key,
+			field: field.key,
+			sheet: sheetName,
+			column,
+			message: `Column ${column} of field "${field.key}" is outside ${a1}.`
+		});
+	}
+	if (structural) return out;
+	out.readable = true;
+	const skip = new Set(table.source.skipRows ?? []);
+	const first = Math.max(headerRow + 1, box.start.row);
+	const occupiedRows = evaluation.occupied(sheet);
+	const lastRow = occupiedRows.length > 0 ? occupiedRows[occupiedRows.length - 1][0] : 0;
+	const last = Math.min(box.end.row, lastRow);
+	const total = Math.max(0, last - first + 1);
+	const mapped = new Set(table.fields.flatMap(fieldColumns));
+	const readFields = table.fields.filter((field) => field.column !== void 0 || field.reference);
+	const sources = [...mapped];
+	evaluation.charge(1 + table.fields.length + mapped.size);
+	const keyFieldsOf = /* @__PURE__ */ new Map();
+	for (const field of readFields) {
+		if (!field.reference) continue;
+		const target = evaluation.fields.get(field.reference.table);
+		keyFieldsOf.set(field, field.reference.by.map((key) => target?.get(key)));
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const unmapped = /* @__PURE__ */ new Map();
+	let occupied = 0;
+	for (let at = lowerBound(occupiedRows, first); at < occupiedRows.length && occupiedRows[at][0] <= last; at++) {
+		const [row, rowCells] = occupiedRows[at];
+		occupied++;
+		evaluation.charge(1 + rowCells.size + sources.length);
+		if (skip.has(row)) {
+			out.skipped++;
+			continue;
+		}
+		for (const [column, cell] of rowCells) {
+			if (table.source.distinct || mapped.has(column) || column < box.start.col || column > box.end.col) continue;
+			if (isBlankCell(cell)) continue;
+			const entry = unmapped.get(column) ?? {
+				count: 0,
+				formula: false
+			};
+			entry.count++;
+			if (cell.formula) entry.formula = true;
+			unmapped.set(column, entry);
+		}
+		if (sources.every((column) => isBlankCell(rowCells.get(column)))) {
+			out.skipped++;
+			continue;
+		}
+		const record = {
+			sourceRow: row,
+			values: {},
+			references: {}
+		};
+		let refused = false;
+		const refuse = (code, field, column, message, expected) => {
+			refused = true;
+			const cell = sheet.cells.get(row, column);
+			sink.add({
+				code,
+				severity: "error",
+				table: table.key,
+				field: field.key,
+				sheet: sheetName,
+				cell: address({
+					row,
+					col: column
+				}),
+				row,
+				expected,
+				actual: describeCell(cell),
+				message
+			});
+		};
+		for (const field of readFields) {
+			if (field.reference) {
+				const parts = [];
+				let blanks = 0;
+				let failed = false;
+				const keyFields = keyFieldsOf.get(field) ?? [];
+				field.reference.columns.forEach((column2, index) => {
+					const keyField = keyFields[index];
+					const cell2 = rowCells.get(column2);
+					if (!keyField) {
+						failed = true;
+						return;
+					}
+					const coerced2 = coerceCell(cell2, keyField, evaluation.choiceSets.get(keyField));
+					if (!coerced2.ok) {
+						failed = true;
+						refuse("coerce-failed", field, column2, `Row ${row}: ${coerced2.detail} [${coerced2.code}]`, keyField.type);
+						return;
+					}
+					if (coerced2.value === null) blanks++;
+					parts.push(coerced2.value);
+				});
+				if (failed) continue;
+				if (blanks === parts.length) {
+					if (field.required) refuse("required-blank", field, field.reference.columns[0], `Row ${row}: "${field.key}" is required.`, "a value");
+					continue;
+				}
+				if (blanks > 0) {
+					refuse("reference-unresolved", field, field.reference.columns[0], `Row ${row}: the key for "${field.key}" is partly blank.`, field.reference.table);
+					continue;
+				}
+				record.references[field.key] = {
+					table: field.reference.table,
+					key: parts
+				};
+				continue;
+			}
+			const column = field.column;
+			const cell = rowCells.get(column);
+			if (field.type === "number" || field.type === "integer") {
+				const digits = digitsAsNumber(cell);
+				if (digits !== void 0) {
+					refuse("digits-as-number", field, column, `Row ${row}: "${digits}" looks like an identifier; map "${field.key}" as text.`, "text");
+					continue;
+				}
+			}
+			const coerced = coerceCell(cell, field, evaluation.choiceSets.get(field));
+			if (!coerced.ok) {
+				refuse("coerce-failed", field, column, `Row ${row}: ${coerced.detail} [${coerced.code}]`, field.type);
+				continue;
+			}
+			if (coerced.value === null && field.required) {
+				refuse("required-blank", field, column, `Row ${row}: "${field.key}" is required.`, "a value");
+				continue;
+			}
+			record.values[field.key] = coerced.value;
+		}
+		if (refused) {
+			out.rejected++;
+			continue;
+		}
+		if (table.source.distinct) {
+			const identity = keyText(readFields.map((field) => field.reference ? record.references[field.key]?.key ?? null : record.values[field.key] ?? null));
+			if (seen.has(identity)) continue;
+			seen.add(identity);
+		}
+		out.rows.push(record);
+	}
+	evaluation.charge(unmapped.size);
+	out.read = total;
+	out.skipped += total - occupied;
+	const headerLabel = (column) => describeCell(sheet.cells.get(headerRow, column));
+	for (const [column, entry] of [...unmapped].sort(([a], [b]) => a - b)) {
+		if (entry.formula) continue;
+		sink.add({
+			code: "unmapped-column",
+			severity: "warning",
+			table: table.key,
+			sheet: sheetName,
+			cell: address({
+				row: headerRow,
+				col: column
+			}),
+			column,
+			actual: headerLabel(column),
+			message: `Column ${column} ("${headerLabel(column)}") holds ${entry.count} values that no field uses.`
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/import/findings.ts
+var MAX_EXAMPLES = 20;
+var FindingSink = class {
+	groups = /* @__PURE__ */ new Map();
+	add(finding) {
+		const key = `${finding.code}\0${finding.table ?? ""}\0${finding.field ?? ""}`;
+		let group = this.groups.get(key);
+		if (!group) {
+			group = {
+				total: 0,
+				items: []
+			};
+			this.groups.set(key, group);
+		}
+		group.total++;
+		if (group.items.length < 20) group.items.push(finding);
+	}
+	/** Insertion order of first occurrence, then row order within a group. */
+	list() {
+		const out = [];
+		for (const group of this.groups.values()) for (const item of group.items) out.push({
+			...item,
+			count: group.total
+		});
+		return out;
+	}
+	hasErrors() {
+		for (const group of this.groups.values()) if (group.items.some((item) => item.severity === "error")) return true;
+		return false;
+	}
+};
+function hasErrors(findings) {
+	return findings.some((finding) => finding.severity === "error");
+}
+//#endregion
+//#region src/import/checks.ts
+var SUMMED = /* @__PURE__ */ new Set([
+	"number",
+	"integer",
+	"money"
+]);
+function compensatedSum(values) {
+	let sum = 0;
+	let compensation = 0;
+	for (const value of values) {
+		const next = sum + value;
+		compensation += Math.abs(sum) >= Math.abs(value) ? sum - next + value : value - next + sum;
+		sum = next;
+	}
+	return sum + compensation;
+}
+function columnSum(rows, field) {
+	if (field.type === "number") return {
+		value: compensatedSum(rows.map((row) => Number(row.values[field.key] ?? 0))),
+		safe: true
+	};
+	let total = 0n;
+	for (const row of rows) {
+		const value = row.values[field.key];
+		if (typeof value === "number") total += BigInt(value);
+	}
+	const safe = total <= BigInt(Number.MAX_SAFE_INTEGER) && total >= BigInt(Number.MIN_SAFE_INTEGER);
+	return {
+		value: Number(total),
+		safe
+	};
+}
+function crossChecks(tables, sink, budget) {
+	const keyIndex = /* @__PURE__ */ new Map();
+	for (const evaluated of tables.values()) {
+		const { table } = evaluated;
+		if (!table.lookupKey) continue;
+		const keys = /* @__PURE__ */ new Set();
+		const firstRow = /* @__PURE__ */ new Map();
+		const columnOf = new Map(table.fields.map((f) => [f.key, f.column]));
+		budget.charge(1 + table.fields.length + evaluated.rows.length * table.lookupKey.length);
+		for (const row of evaluated.rows) {
+			const parts = table.lookupKey.map((key) => row.values[key] ?? null);
+			const blankIndex = parts.indexOf(null);
+			if (blankIndex >= 0) {
+				const field = table.lookupKey[blankIndex];
+				const column = columnOf.get(field);
+				sink.add({
+					code: "lookup-key-blank",
+					severity: "error",
+					table: table.key,
+					field,
+					sheet: table.source.sheet,
+					row: row.sourceRow,
+					...column !== void 0 ? { cell: address({
+						row: row.sourceRow,
+						col: column
+					}) } : {},
+					message: `Row ${row.sourceRow}: lookup key field "${field}" is blank.`
+				});
+				continue;
+			}
+			const text = keyText(parts);
+			const earlier = firstRow.get(text);
+			if (earlier !== void 0) {
+				sink.add({
+					code: "lookup-key-not-unique",
+					severity: "error",
+					table: table.key,
+					field: table.lookupKey.join(","),
+					sheet: table.source.sheet,
+					row: row.sourceRow,
+					actual: parts.join(" | "),
+					message: `Row ${row.sourceRow}: lookup key (${parts.join(", ")}) already appears on row ${earlier}.`
+				});
+				continue;
+			}
+			firstRow.set(text, row.sourceRow);
+			keys.add(text);
+		}
+		keyIndex.set(table.key, keys);
+	}
+	for (const evaluated of tables.values()) {
+		const { table } = evaluated;
+		for (const field of table.fields) {
+			if (!field.reference) continue;
+			const known = keyIndex.get(field.reference.table) ?? /* @__PURE__ */ new Set();
+			budget.charge(1 + evaluated.rows.length);
+			for (const row of evaluated.rows) {
+				const ref = row.references[field.key];
+				if (!ref || known.has(keyText(ref.key))) continue;
+				const column = field.reference.columns[0];
+				sink.add({
+					code: "reference-unresolved",
+					severity: "error",
+					table: table.key,
+					field: field.key,
+					sheet: table.source.sheet,
+					cell: address({
+						row: row.sourceRow,
+						col: column
+					}),
+					row: row.sourceRow,
+					expected: field.reference.table,
+					actual: ref.key.join(" | "),
+					message: `Row ${row.sourceRow}: no ${field.reference.table} row has key (${ref.key.join(", ")}).`
+				});
+			}
+		}
+	}
+}
+function checkPlan(plan, workbook, _profile, limits = {}, budget = new WorkBudget(limits.maxWork ?? DEFAULT_IMPORT_LIMITS.maxWork)) {
+	const sink = new FindingSink();
+	const tables = evaluatePlan(plan, workbook, sink, budget);
+	crossChecks(tables, sink, budget);
+	const facts = {
+		tables: {},
+		sums: {}
+	};
+	for (const [key, evaluated] of tables) {
+		facts.tables[key] = {
+			read: evaluated.read,
+			skipped: evaluated.skipped,
+			rejected: evaluated.rejected,
+			planned: evaluated.rows.length
+		};
+		const sums = {};
+		for (const field of evaluated.table.fields) {
+			if (field.column === void 0 || !SUMMED.has(field.type)) continue;
+			budget.charge(1 + evaluated.rows.length);
+			const sum = columnSum(evaluated.rows, field);
+			if (!sum.safe) sink.add({
+				code: "sum-unsafe",
+				severity: "error",
+				table: key,
+				field: field.key,
+				message: `The column sum of "${field.key}" exceeds the safe integer range.`
+			});
+			sums[field.key] = sum.value;
+		}
+		facts.sums[key] = sums;
+	}
+	const findings = sink.list();
+	return {
+		ok: !hasErrors(findings),
+		findings,
+		facts,
+		work: budget.used
+	};
+}
+function relativelyEqual(a, b, tolerance = 1e-9) {
+	if (!Number.isFinite(a) || !Number.isFinite(b)) return false;
+	if (a === b) return true;
+	return Math.abs(a - b) <= tolerance * Math.max(Math.abs(a), Math.abs(b));
+}
+function asNumber(value) {
+	if (typeof value === "number") return value;
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+function asBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (value === 1 || value === "1") return true;
+	if (value === 0 || value === "0") return false;
+}
+function asIsoDate(value) {
+	if (value instanceof Date) return isoDate(value);
+	if (typeof value === "string") return /^\d{4}-\d{2}-\d{2}/.test(value) ? value.slice(0, 10) : void 0;
+}
+function invalidCalculated(field, actual) {
+	if (actual === null || actual === void 0) return void 0;
+	const whole = field.type === "integer" || field.type === "money";
+	if (!whole && field.type !== "number") return void 0;
+	if (typeof actual === "bigint") return actual <= BigInt(Number.MAX_SAFE_INTEGER) && actual >= BigInt(Number.MIN_SAFE_INTEGER) ? void 0 : `${actual} is beyond the safe integer range`;
+	const n = actual;
+	if (typeof n !== "number" || !Number.isFinite(n)) return `${String(actual)} is not a finite number`;
+	if (whole && !Number.isInteger(n)) return `${n} is not a whole number`;
+	if (whole && !Number.isSafeInteger(n)) return `${n} is beyond the safe integer range`;
+}
+function cachedAgrees(field, cached, actual) {
+	if (isBlankCell(cached, false) || cached?.type === "error") return actual === null || actual === void 0;
+	if (actual === null || actual === void 0) return false;
+	const value = cached?.value;
+	switch (field.type) {
+		case "number": {
+			const a = asNumber(actual);
+			return typeof value === "number" && a !== void 0 && relativelyEqual(value, a);
+		}
+		case "integer": {
+			const a = asNumber(actual);
+			return typeof value === "number" && a !== void 0 && value === a;
+		}
+		case "money": {
+			const a = asNumber(actual);
+			if (typeof value !== "number" || a === void 0) return false;
+			const minor = value * 10 ** (field.money?.scale ?? 0);
+			const rounded = Math.round(minor);
+			return Math.abs(minor - rounded) <= 1e-6 && rounded === a;
+		}
+		case "boolean": return typeof value === "boolean" && asBoolean(actual) === value;
+		case "date": return value instanceof Date && asIsoDate(actual) === isoDate(value);
+		default: return typeof value === "string" ? value === String(actual) : describeCell(cached) === String(actual);
+	}
+}
+function verificationWork(plan, facts) {
+	let work = 0;
+	for (const table of plan.tables) {
+		const planned = facts.tables[table.key]?.planned ?? 0;
+		const calculated = table.fields.filter((f) => f.calculated !== void 0);
+		const summed = table.fields.filter((f) => f.column !== void 0 && SUMMED.has(f.type));
+		work += 1 + summed.length;
+		if (calculated.length > 0) work += (planned + 1) * (1 + calculated.length);
+	}
+	return work;
+}
+async function checkLoaded(plan, workbook, target, facts, budget = new WorkBudget(Number.POSITIVE_INFINITY)) {
+	const sink = new FindingSink();
+	for (const table of plan.tables) {
+		const planned = facts.tables[table.key]?.planned ?? 0;
+		const count = await target.count(table.key);
+		if (count !== planned) sink.add({
+			code: "row-count-mismatch",
+			severity: "error",
+			table: table.key,
+			expected: planned,
+			actual: count,
+			message: `"${table.key}" holds ${count} rows; the workbook plans ${planned}.`
+		});
+		for (const field of table.fields) {
+			if (field.column === void 0 || !SUMMED.has(field.type)) continue;
+			const expected = facts.sums[table.key]?.[field.key];
+			if (expected === void 0) continue;
+			const actual = Number(await target.sum(table.key, field.key));
+			if (!(field.type === "number" ? relativelyEqual(expected, actual) : expected === actual)) sink.add({
+				code: "sum-mismatch",
+				severity: "error",
+				table: table.key,
+				field: field.key,
+				expected,
+				actual,
+				message: `"${table.key}.${field.key}" sums to ${actual}; the workbook sums to ${expected}.`
+			});
+		}
+		await checkCalculated(table, workbook, target, sink, budget, planned + 1);
+	}
+	const findings = sink.list();
+	return {
+		ok: !hasErrors(findings),
+		findings
+	};
+}
+async function checkCalculated(table, workbook, target, sink, budget, maxRows) {
+	const sheet = workbook.sheets.find((s) => s.name === table.source.sheet);
+	const calculated = table.fields.filter((f) => f.calculated !== void 0);
+	if (calculated.length === 0) return;
+	let seen = 0;
+	for await (const row of target.values(table.key, calculated.map((f) => f.key))) {
+		if (++seen > maxRows) break;
+		budget.charge(1 + calculated.length);
+		for (const field of calculated) {
+			const column = field.cachedColumn;
+			const actual = row.values[field.key];
+			const shown = actual === null || actual === void 0 ? null : typeof actual === "object" ? JSON.stringify(actual) : typeof actual === "bigint" ? String(actual) : actual;
+			const invalid = invalidCalculated(field, actual);
+			if (invalid !== void 0) {
+				sink.add({
+					code: "calculated-invalid",
+					severity: "error",
+					table: table.key,
+					field: field.key,
+					row: row.sourceRow,
+					actual: shown,
+					message: `Row ${row.sourceRow}: "${field.key}" holds ${invalid}.`
+				});
+				continue;
+			}
+			if (column === void 0 || !sheet) continue;
+			const cached = sheet.cells.get(row.sourceRow, column);
+			if (cachedAgrees(field, cached, actual)) continue;
+			sink.add({
+				code: "calculated-mismatch",
+				severity: "error",
+				table: table.key,
+				field: field.key,
+				sheet: table.source.sheet,
+				cell: address({
+					row: row.sourceRow,
+					col: column
+				}),
+				row: row.sourceRow,
+				expected: describeCell(cached),
+				actual: shown,
+				message: `Row ${row.sourceRow}: "${field.key}" is ${String(actual)} in the target; the workbook cached ${describeCell(cached)}.`
+			});
+		}
+	}
+}
+//#endregion
+//#region src/import/load.ts
+var DEFAULT_BATCH_SIZE = 500;
+function admit(workbook, limits = {}, plan) {
+	const { maxCells, maxRowsPerTable } = {
+		...DEFAULT_IMPORT_LIMITS,
+		...limits
+	};
+	let cells = 0;
+	for (const sheet of workbook.sheets) {
+		cells += sheet.cells.size;
+		if (cells > maxCells) throw new ImportRunError("cells-over-limit", `The workbook holds more than ${maxCells} cells.`, { maxCells });
+	}
+	const over = (what, rows) => {
+		throw new ImportRunError("rows-over-limit", `${what} holds ${rows} rows; the limit is ${maxRowsPerTable}.`, {
+			maxRowsPerTable,
+			rows
+		});
+	};
+	const lastRows = /* @__PURE__ */ new Map();
+	const lastRowOf = (sheet) => {
+		let known = lastRows.get(sheet);
+		if (known === void 0) {
+			known = lastOccupiedRow(sheet);
+			lastRows.set(sheet, known);
+		}
+		return known;
+	};
+	if (plan) {
+		const sheets = new Map(workbook.sheets.map((sheet) => [sheet.name, sheet]));
+		for (const table of plan.tables) {
+			const sheet = sheets.get(table.source.sheet);
+			if (!sheet) continue;
+			let box;
+			try {
+				box = range(table.source.range);
+			} catch {
+				continue;
+			}
+			const first = Math.max(table.source.headerRow + 1, box.start.row);
+			const rows = Math.min(box.end.row, lastRowOf(sheet)) - first + 1;
+			if (rows > maxRowsPerTable) over(`Table "${table.key}"`, rows);
+		}
+		return;
+	}
+	for (const sheet of workbook.sheets) {
+		const rows = lastRowOf(sheet);
+		if (rows > maxRowsPerTable) over(`Sheet "${sheet.name}"`, rows);
+	}
+}
+function planLoad(plan, workbook, options = {}) {
+	const batchSize = options.batchSize ?? 500;
+	if (!Number.isSafeInteger(batchSize) || batchSize < 1) throw new RangeError("batchSize must be a positive integer");
+	const sink = new FindingSink();
+	const tables = evaluatePlan(plan, workbook, sink, options.budget ?? new WorkBudget(options.limits?.maxWork ?? DEFAULT_IMPORT_LIMITS.maxWork));
+	const unreadable = [...tables.values()].filter((t) => !t.readable);
+	if (unreadable.length > 0) throw new ImportRunError("source-invalid", `The source of ${unreadable.map((t) => `"${t.table.key}"`).join(", ")} cannot be read; run checkPlan.`, { findings: sink.list().filter((f) => f.severity === "error") });
+	const order = loadOrder(plan);
+	return {
+		order,
+		*batches() {
+			for (const key of order) {
+				const evaluated = tables.get(key);
+				for (let at = 0, index = 0; at < evaluated.rows.length; at += batchSize) yield {
+					table: key,
+					index: index++,
+					records: evaluated.rows.slice(at, at + batchSize)
+				};
+			}
+		}
+	};
+}
+//#endregion
+//#region src/import/run.ts
+async function runImport(options) {
+	const plan = validatePlan(options.plan);
+	admit(options.workbook, options.limits, plan);
+	const budget = new WorkBudget(options.limits?.maxWork ?? DEFAULT_IMPORT_LIMITS.maxWork);
+	const planned = checkPlan(plan, options.workbook, void 0, options.limits, budget);
+	if (!planned.ok) return {
+		ok: false,
+		findings: planned.findings,
+		facts: planned.facts,
+		loaded: {},
+		plan,
+		work: budget.used
+	};
+	const load = planLoad(plan, options.workbook, {
+		batchSize: options.batchSize,
+		limits: options.limits,
+		budget
+	});
+	const batches = [...load.batches()];
+	budget.charge(verificationWork(plan, planned.facts));
+	const structure = await options.target.describe();
+	const existing = new Set(structure.tables.map((table) => table.key));
+	const clash = plan.tables.filter((table) => existing.has(table.key));
+	if (clash.length > 0) throw new ImportRunError("target-not-empty", `The target already has ${clash.map((t) => `"${t.key}"`).join(", ")}; this import is first-time only.`, { tables: clash.map((table) => table.key) });
+	await options.target.applyStructure(plan);
+	const loaded = {};
+	for (const table of load.order) loaded[table] = 0;
+	for (const batch of batches) {
+		const result = await options.target.load(batch);
+		loaded[batch.table] += result.loaded;
+	}
+	const verified = await checkLoaded(plan, options.workbook, options.target, planned.facts);
+	const findings = [...planned.findings, ...verified.findings];
+	return {
+		ok: !hasErrors(findings),
+		findings,
+		facts: planned.facts,
+		loaded,
+		plan,
+		work: budget.used
+	};
+}
+//#endregion
+export { DEFAULT_BATCH_SIZE, DEFAULT_IMPORT_LIMITS, DEFAULT_MAX_CELLS, DEFAULT_MAX_ROWS_PER_TABLE, DEFAULT_MAX_WORK, DEFAULT_PLAN_LIMITS, IMPORT_FIELD_TYPES, ImportPlanError, ImportRunError, MAX_EXAMPLES, PLAN_KEY_PATTERN, WorkBudget, admit, checkLoaded, checkPlan, coerceCell, compensatedSum, loadOrder, planLoad, runImport, validatePlan };
+
+//# sourceMappingURL=index.js.map