@effected/toml 0.1.0

package/TomlFormat.js

@@ -0,0 +1,611 @@
+import { isRawTomlError } from "./internal/diagnostics.js";
+import { isGuardExceeded } from "./internal/limits.js";
+import { TomlArray, TomlArrayTableHeader, TomlInlineTable, TomlKeyValue, TomlString, TomlTableHeader, TomlTrivia } from "./TomlNode.js";
+import { parseExpressions } from "./internal/parser.js";
+import { analyze } from "./internal/semantic.js";
+import { renderInlineValue, renderKey } from "./internal/stringifyValue.js";
+import { TomlDiagnostic } from "./TomlDiagnostic.js";
+import { TomlDocument } from "./TomlDocument.js";
+import { TomlEdit } from "./TomlEdit.js";
+import { Effect, Schema } from "effect";
+
+//#region src/TomlFormat.ts
+/**
+* Options controlling formatting and modification behavior. The only knob is
+* `newline`: for `format` it normalizes every newline outside multi-line
+* strings; for `modify` it overrides the dominant newline inherited by
+* inserted lines.
+*
+* @public
+*/
+var TomlFormattingOptions = class extends Schema.Class("TomlFormattingOptions")({ newline: Schema.optionalKey(Schema.Literals(["\n", "\r\n"])) }) {};
+/**
+* Raised when `TomlFormat.modify` cannot resolve the requested path against
+* the document's semantic view, when the insertion target refuses (an inline
+* table or an implicitly created table), or when the replacement value
+* cannot render as TOML. Carries one structured {@link TomlDiagnostic} —
+* never a collapsed `reason` string.
+*
+* @public
+*/
+var TomlModificationError = class extends Schema.TaggedErrorClass()("TomlModificationError", { diagnostic: TomlDiagnostic }) {
+	get message() {
+		return `TOML modification failed: ${this.diagnostic.code} ${this.diagnostic.message}`;
+	}
+};
+const TAB = 9;
+const LF = 10;
+const CR = 13;
+const SPACE = 32;
+const BANG = 33;
+const HASH = 35;
+const BOM = 65279;
+const isWs = (code) => code === SPACE || code === TAB;
+const scanWs = (source, pos, end) => {
+	let i = pos;
+	while (i < end && isWs(source.charCodeAt(i))) i++;
+	return i;
+};
+const scanWsBack = (source, pos, start) => {
+	let i = pos;
+	while (i > start && isWs(source.charCodeAt(i - 1))) i--;
+	return i;
+};
+/** The document's dominant newline: CRLF only when CRLF pairs outnumber bare LFs. */
+const dominantNewline = (source) => {
+	let lf = 0;
+	let crlf = 0;
+	for (let i = 0; i < source.length; i++) if (source.charCodeAt(i) === LF) if (i > 0 && source.charCodeAt(i - 1) === CR) crlf++;
+	else lf++;
+	return crlf > lf ? "\r\n" : "\n";
+};
+/** Multi-line string value spans — the bytes formatting must never touch. */
+const collectMultilineSpans = (node, out) => {
+	if (node instanceof TomlString) {
+		if (node.style === "multiline-basic" || node.style === "multiline-literal") out.push([node.offset, node.offset + node.length]);
+		return;
+	}
+	if (node instanceof TomlArray) {
+		for (const item of node.items) collectMultilineSpans(item, out);
+		return;
+	}
+	if (node instanceof TomlInlineTable) for (const entry of node.entries) collectMultilineSpans(entry.value, out);
+};
+/** Accumulates format edits for one document; drops no-op splices to keep format idempotent. */
+var FormatEmitter = class {
+	source;
+	edits = [];
+	constructor(source) {
+		this.source = source;
+	}
+	push(expr, offset, length, newText) {
+		if (this.source.slice(offset, offset + length) !== newText) this.edits.push({
+			offset,
+			length,
+			newText,
+			exprOffset: expr.offset,
+			exprEnd: expr.offset + expr.length
+		});
+	}
+};
+/** Rule 2: strip the expression's leading indentation (the first line's BOM excluded). */
+const formatLeading = (source, emit, expr) => {
+	let start = expr.offset;
+	if (start === 0 && source.charCodeAt(0) === BOM) start = 1;
+	const end = scanWs(source, start, expr.offset + expr.length);
+	if (end > start) emit.push(expr, start, end - start, "");
+};
+/** Rule 4 (space after `#`) and the rule-3 trailing-whitespace strip, for one comment body. */
+const formatCommentBody = (source, emit, expr, bodyStart, lineEnd) => {
+	const bodyEnd = scanWsBack(source, lineEnd, bodyStart);
+	if (bodyEnd < lineEnd) emit.push(expr, bodyEnd, lineEnd - bodyEnd, "");
+	if (bodyEnd > bodyStart) {
+		const code = source.charCodeAt(bodyStart);
+		if (code !== SPACE && code !== TAB && code !== BANG) emit.push(expr, bodyStart, 0, " ");
+	}
+};
+/** Rule 3: the run between an expression's content end and its newline — trailing ws and the comment gap. */
+const formatTail = (source, emit, expr, contentEnd) => {
+	let nlStart = expr.offset + expr.length;
+	if (nlStart > contentEnd && source.charCodeAt(nlStart - 1) === LF) {
+		nlStart -= 1;
+		if (nlStart > contentEnd && source.charCodeAt(nlStart - 1) === CR) nlStart -= 1;
+	}
+	const hashIdx = scanWs(source, contentEnd, nlStart);
+	if (hashIdx >= nlStart || source.charCodeAt(hashIdx) !== HASH) {
+		if (nlStart > contentEnd) emit.push(expr, contentEnd, nlStart - contentEnd, "");
+		return;
+	}
+	emit.push(expr, contentEnd, hashIdx - contentEnd, " ");
+	formatCommentBody(source, emit, expr, hashIdx + 1, nlStart);
+};
+/** Rules 2–4 over a trivia run's blank and comment-only lines. */
+const formatTrivia = (source, emit, expr) => {
+	const end = expr.offset + expr.length;
+	let i = expr.offset;
+	while (i < end) {
+		const lineStart = i;
+		let j = i;
+		while (j < end && source.charCodeAt(j) !== LF && source.charCodeAt(j) !== CR) j++;
+		let start = lineStart;
+		if (start === 0 && source.charCodeAt(0) === BOM) start = 1;
+		const wsEnd = scanWs(source, start, j);
+		if (wsEnd >= j) {
+			if (j > start) emit.push(expr, start, j - start, "");
+		} else {
+			if (wsEnd > start) emit.push(expr, start, wsEnd - start, "");
+			formatCommentBody(source, emit, expr, wsEnd + 1, j);
+		}
+		if (j < end && source.charCodeAt(j) === CR && j + 1 < end && source.charCodeAt(j + 1) === LF) j += 2;
+		else if (j < end) j += 1;
+		i = j;
+	}
+};
+/** Rule 6: normalize every newline within the expression span, skipping the protected string spans. */
+const normalizeNewlines = (source, emit, expr, protectedSpans, target) => {
+	const end = expr.offset + expr.length;
+	let p = 0;
+	let i = expr.offset;
+	while (i < end) {
+		while (p < protectedSpans.length && protectedSpans[p][1] <= i) p++;
+		if (p < protectedSpans.length && i >= protectedSpans[p][0]) {
+			i = protectedSpans[p][1];
+			continue;
+		}
+		const code = source.charCodeAt(i);
+		if (code === CR && i + 1 < end && source.charCodeAt(i + 1) === LF) {
+			if (target === "\n") emit.push(expr, i, 2, "\n");
+			i += 2;
+		} else if (code === LF) {
+			if (target === "\r\n") emit.push(expr, i, 1, "\r\n");
+			i += 1;
+		} else i += 1;
+	}
+};
+/** The position just past a header's closing bracket(s). */
+const headerContentEnd = (source, expr) => {
+	const lastKey = expr.keyPath[expr.keyPath.length - 1];
+	return scanWs(source, lastKey.offset + lastKey.length, expr.offset + expr.length) + (expr instanceof TomlArrayTableHeader ? 2 : 1);
+};
+/** All six format rules over the expression list; `[]` on malformed input (never corrupt it). */
+const computeFormatEdits = (source, options) => {
+	let expressions;
+	try {
+		expressions = parseExpressions(source);
+	} catch {
+		return [];
+	}
+	const emit = new FormatEmitter(source);
+	const target = options?.newline;
+	for (const expr of expressions) {
+		let protectedSpans = [];
+		if (expr instanceof TomlTrivia) formatTrivia(source, emit, expr);
+		else if (expr instanceof TomlKeyValue) {
+			formatLeading(source, emit, expr);
+			const lastKey = expr.keyPath[expr.keyPath.length - 1];
+			const keyEnd = lastKey.offset + lastKey.length;
+			emit.push(expr, keyEnd, expr.value.offset - keyEnd, " = ");
+			formatTail(source, emit, expr, expr.value.offset + expr.value.length);
+			if (target !== void 0) {
+				const spans = [];
+				collectMultilineSpans(expr.value, spans);
+				protectedSpans = spans;
+			}
+		} else {
+			formatLeading(source, emit, expr);
+			formatTail(source, emit, expr, headerContentEnd(source, expr));
+		}
+		if (target !== void 0) normalizeNewlines(source, emit, expr, protectedSpans, target);
+	}
+	if (expressions.length > 0 && source.charCodeAt(source.length - 1) !== LF) {
+		const last = expressions[expressions.length - 1];
+		emit.push(last, source.length, 0, target ?? dominantNewline(source));
+	}
+	return emit.edits;
+};
+const mkTable = (origin, sectionIndex = 0, relPath = []) => ({
+	kind: "table",
+	origin,
+	entries: /* @__PURE__ */ new Map(),
+	sectionIndex,
+	relPath
+});
+/** Descend into a navigable node: tables pass through, array-of-tables yield their last element. */
+const intoTable = (node) => {
+	if (node !== void 0 && node.kind === "array-tables") return node.elements[node.elements.length - 1];
+	if (node !== void 0 && node.kind === "table") return node;
+	throw new Error("invariant: semantic pass admitted a value where a table was navigated");
+};
+/**
+* Build the resolution tree and section list by riding `analyze`'s visitor.
+* The expressions were validated at parse time, so the walk cannot throw;
+* `onKeyValue` paths are name-only, so array-of-tables element association
+* comes from descending into the LAST element — expressions arrive in
+* document order, so the last element is always the current one.
+*/
+const buildSemanticIndex = (expressions) => {
+	const sections = [{
+		header: void 0,
+		insertAfter: void 0
+	}];
+	for (const expr of expressions) if (expr instanceof TomlTableHeader || expr instanceof TomlArrayTableHeader) sections.push({
+		header: expr,
+		insertAfter: expr.offset + expr.length
+	});
+	else if (!(expr instanceof TomlTrivia)) sections[sections.length - 1].insertAfter = expr.offset + expr.length;
+	const root = mkTable("root");
+	let sectionCounter = 0;
+	const navigateHeaderPrefix = (path) => {
+		let current = root;
+		for (let i = 0; i < path.length - 1; i++) {
+			let child = current.entries.get(path[i]);
+			if (child === void 0) {
+				child = mkTable("implicit");
+				current.entries.set(path[i], child);
+			}
+			current = intoTable(child);
+		}
+		return current;
+	};
+	analyze(expressions, {
+		onTableStart: (path, header) => {
+			if (header === void 0) return;
+			sectionCounter += 1;
+			const parent = navigateHeaderPrefix(path);
+			const name = path[path.length - 1];
+			const existing = parent.entries.get(name);
+			if (existing !== void 0 && existing.kind === "table") {
+				existing.origin = "explicit";
+				existing.sectionIndex = sectionCounter;
+			} else parent.entries.set(name, mkTable("explicit", sectionCounter));
+		},
+		onArrayTableStart: (path, _index, _header) => {
+			sectionCounter += 1;
+			const parent = navigateHeaderPrefix(path);
+			const name = path[path.length - 1];
+			const existing = parent.entries.get(name);
+			if (existing !== void 0 && existing.kind === "array-tables") existing.elements.push(mkTable("element", sectionCounter));
+			else parent.entries.set(name, {
+				kind: "array-tables",
+				elements: [mkTable("element", sectionCounter)]
+			});
+		},
+		onKeyValue: (path, expr) => {
+			const names = expr.keyPath.map((key) => key.value);
+			let current = root;
+			for (let i = 0; i < path.length - names.length; i++) current = intoTable(current.entries.get(path[i]));
+			for (let j = 0; j < names.length - 1; j++) {
+				let child = current.entries.get(names[j]);
+				if (child === void 0) {
+					child = mkTable("dotted", sectionCounter, names.slice(0, j + 1));
+					current.entries.set(names[j], child);
+				}
+				current = intoTable(child);
+			}
+			current.entries.set(names[names.length - 1], {
+				kind: "value",
+				node: expr.value,
+				expr
+			});
+		}
+	});
+	return {
+		root,
+		sections
+	};
+};
+/** Thrown by the pure resolution helpers; `modify` materializes {@link TomlModificationError}. */
+var ModifyFailure = class extends Error {
+	code;
+	offset;
+	len;
+	constructor(code, message, offset, len) {
+		super(message);
+		this.code = code;
+		this.offset = offset;
+		this.len = len;
+		this.name = "ModifyFailure";
+	}
+};
+const failResolve = (code, message, offset = 0, length = 0) => {
+	throw new ModifyFailure(code, message, offset, length);
+};
+const requireIndex = (segment, what, offset, length) => {
+	if (typeof segment !== "number" || !Number.isInteger(segment) || segment < 0) return failResolve("DottedKeyConflict", `${what} requires a non-negative integer index, received "${String(segment)}"`, offset, length);
+	return segment;
+};
+/** Wrap a CST value as a cursor; inline tables open as an entry scope (dotted keys included). */
+const cstCursor = (node, del) => node instanceof TomlInlineTable ? {
+	t: "inline",
+	table: node,
+	candidates: node.entries.map((entry, index) => ({
+		entry,
+		index
+	})),
+	depth: 0
+} : {
+	t: "cst",
+	node,
+	del
+};
+const stepInline = (cur, key) => {
+	const matches = cur.candidates.filter((candidate) => candidate.entry.keyPath[cur.depth].value === key);
+	return {
+		matches,
+		full: matches.length === 1 && matches[0].entry.keyPath.length === cur.depth + 1 ? matches[0] : void 0
+	};
+};
+/** One navigation step (never the terminal segment). */
+const step = (cur, segment) => {
+	if (cur.t === "table") {
+		const key = String(segment);
+		const child = cur.table.entries.get(key);
+		if (child === void 0) return failResolve("DottedKeyConflict", `key "${key}" does not resolve — intermediate tables are never auto-created`);
+		if (child.kind === "table") return {
+			t: "table",
+			table: child
+		};
+		if (child.kind === "array-tables") return {
+			t: "array-tables",
+			node: child
+		};
+		return cstCursor(child.node, {
+			kind: "expression",
+			expr: child.expr
+		});
+	}
+	if (cur.t === "array-tables") {
+		const idx = requireIndex(segment, "an array of tables", 0, 0);
+		if (idx >= cur.node.elements.length) return failResolve("DottedKeyConflict", `array-of-tables index ${idx} is out of bounds`);
+		return {
+			t: "table",
+			table: cur.node.elements[idx]
+		};
+	}
+	if (cur.t === "inline") {
+		const key = String(segment);
+		const { matches, full } = stepInline(cur, key);
+		if (matches.length === 0) return failResolve("DottedKeyConflict", `key "${key}" does not resolve in the inline table`, cur.table.offset, cur.table.length);
+		if (full !== void 0) return cstCursor(full.entry.value, {
+			kind: "inline-entry",
+			table: cur.table,
+			index: full.index
+		});
+		return {
+			t: "inline",
+			table: cur.table,
+			candidates: matches,
+			depth: cur.depth + 1
+		};
+	}
+	const node = cur.node;
+	if (node instanceof TomlArray) {
+		const idx = requireIndex(segment, "an array", node.offset, node.length);
+		if (idx >= node.items.length) return failResolve("DottedKeyConflict", `array index ${idx} is out of bounds`, node.offset, node.length);
+		return cstCursor(node.items[idx], {
+			kind: "array-item",
+			array: node,
+			index: idx
+		});
+	}
+	return failResolve("DottedKeyConflict", "cannot navigate through a scalar value", node.offset, node.length);
+};
+/** Delete one array item, splicing the separator: leading comma for a last item, trailing for the rest. */
+const spliceArrayItem = (array, index) => {
+	const items = array.items;
+	if (items.length === 1) return {
+		offset: array.offset + 1,
+		length: array.length - 2,
+		newText: ""
+	};
+	if (index < items.length - 1) return {
+		offset: items[index].offset,
+		length: items[index + 1].offset - items[index].offset,
+		newText: ""
+	};
+	const prevEnd = items[index - 1].offset + items[index - 1].length;
+	return {
+		offset: prevEnd,
+		length: items[index].offset + items[index].length - prevEnd,
+		newText: ""
+	};
+};
+/** Delete one inline-table entry with the same separator-splicing rule. */
+const spliceInlineEntry = (table, index) => {
+	const entries = table.entries;
+	if (entries.length === 1) return {
+		offset: table.offset + 1,
+		length: table.length - 2,
+		newText: ""
+	};
+	if (index < entries.length - 1) return {
+		offset: entries[index].offset,
+		length: entries[index + 1].offset - entries[index].offset,
+		newText: ""
+	};
+	const prevEnd = entries[index - 1].offset + entries[index - 1].length;
+	return {
+		offset: prevEnd,
+		length: entries[index].offset + entries[index].length - prevEnd,
+		newText: ""
+	};
+};
+/** The pinned insertion-placement rules: where a new `key = value` line lands and how its key renders. */
+const insertEdit = (table, key, value, ctx) => {
+	if (table.origin === "implicit") return failResolve("DottedKeyConflict", "the table was created implicitly by a longer header and has no section of its own to insert into");
+	const line = `${(table.origin === "dotted" ? [...table.relPath, key] : [key]).map(renderKey).join(".")} = ${renderInlineValue(value)}`;
+	let offset;
+	if (table.sectionIndex === 0) {
+		const firstHeader = ctx.sections.length > 1 ? ctx.sections[1].header : void 0;
+		offset = ctx.sections[0].insertAfter ?? firstHeader?.offset ?? 0;
+	} else offset = ctx.sections[table.sectionIndex].insertAfter ?? 0;
+	const needLeading = offset > 0 && ctx.source.charCodeAt(offset - 1) !== LF;
+	return {
+		offset,
+		length: 0,
+		newText: `${needLeading ? ctx.nl : ""}${line}${ctx.nl}`
+	};
+};
+/** Resolve the final segment against the parent cursor and produce the terminal edits. */
+const terminal = (cur, segment, value, ctx) => {
+	if (cur.t === "table") {
+		const key = String(segment);
+		const existing = cur.table.entries.get(key);
+		if (value === void 0) {
+			if (existing === void 0) return [];
+			if (existing.kind !== "value") return failResolve("DottedKeyConflict", `"${key}" is a table section, not a deletable value`);
+			return [{
+				offset: existing.expr.offset,
+				length: existing.expr.length,
+				newText: ""
+			}];
+		}
+		if (existing === void 0) return [insertEdit(cur.table, key, value, ctx)];
+		if (existing.kind !== "value") return failResolve("DottedKeyConflict", `"${key}" is already defined as a table and cannot become a value`);
+		return [{
+			offset: existing.node.offset,
+			length: existing.node.length,
+			newText: renderInlineValue(value)
+		}];
+	}
+	if (cur.t === "array-tables") {
+		const idx = requireIndex(segment, "an array of tables", 0, 0);
+		if (value === void 0 && idx >= cur.node.elements.length) return [];
+		return failResolve("DottedKeyConflict", idx < cur.node.elements.length ? `array-of-tables element ${idx} is a table section, not an addressable value` : `array-of-tables index ${idx} is out of bounds`);
+	}
+	if (cur.t === "inline") {
+		const key = String(segment);
+		const { matches, full } = stepInline(cur, key);
+		if (value === void 0) {
+			if (matches.length === 0) return [];
+			if (full === void 0) return failResolve("DottedKeyConflict", `"${key}" is a dotted-key group inside an inline table, not a single entry`, cur.table.offset, cur.table.length);
+			return [spliceInlineEntry(cur.table, full.index)];
+		}
+		if (matches.length === 0) return failResolve("InlineTableExtended", `inline table cannot be extended with new key "${key}"`, cur.table.offset, cur.table.length);
+		if (full === void 0) return failResolve("DottedKeyConflict", `"${key}" is a dotted-key group inside an inline table, not a single entry`, cur.table.offset, cur.table.length);
+		return [{
+			offset: full.entry.value.offset,
+			length: full.entry.value.length,
+			newText: renderInlineValue(value)
+		}];
+	}
+	const node = cur.node;
+	if (node instanceof TomlArray) {
+		const idx = requireIndex(segment, "an array", node.offset, node.length);
+		if (value === void 0) {
+			if (idx >= node.items.length) return [];
+			return [spliceArrayItem(node, idx)];
+		}
+		if (idx >= node.items.length) return failResolve("DottedKeyConflict", `array index ${idx} is out of bounds — modify never appends array elements`, node.offset, node.length);
+		return [{
+			offset: node.items[idx].offset,
+			length: node.items[idx].length,
+			newText: renderInlineValue(value)
+		}];
+	}
+	return failResolve("DottedKeyConflict", "cannot address a key beneath a scalar value", node.offset, node.length);
+};
+/**
+* Formatting and modification statics. Not instantiable.
+*
+* @remarks
+* `format`/`formatToString` are pure and total: malformed input yields no
+* edits rather than corrupting the document, and every edit derives from an
+* expression or value span, so bytes inside multi-line strings are
+* untouchable by construction. `modify`/`modifyToString` carry a real error
+* channel — {@link TomlParseError} when the source does not parse and
+* {@link TomlModificationError} for path-resolution and insertion-target
+* failures — and every document they produce reparses cleanly.
+*
+* @public
+*/
+var TomlFormat = class TomlFormat {
+	constructor() {}
+	/**
+	* Compute conservative formatting edits: one space around `=`, leading
+	* indentation stripped, trailing whitespace stripped with one space before
+	* a trailing `#`, one space after a non-empty `#` (unless it starts with
+	* space, tab or `!`), a single final newline, and — when
+	* `options.newline` is set — every newline normalized outside multi-line
+	* strings. Nothing else: no reordering, no blank-line collapsing, no value
+	* rewriting. `range` restricts edits to the expressions intersecting it.
+	* Non-mutating — apply with `TomlEdit.applyAll` (or use
+	* {@link TomlFormat.formatToString}).
+	*/
+	static format(text, range, options) {
+		const tagged = computeFormatEdits(text, options);
+		return (range === void 0 ? tagged : tagged.filter((edit) => Math.max(edit.exprOffset, range.offset) <= Math.min(edit.exprEnd, range.offset + range.length))).map((edit) => TomlEdit.make({
+			offset: edit.offset,
+			length: edit.length,
+			content: edit.newText
+		}));
+	}
+	/**
+	* Format `text` and apply the resulting edits in one step
+	* (`TomlEdit.applyAll ∘ format`). Pure and total.
+	*/
+	static formatToString(text, range, options) {
+		return TomlEdit.applyAll(text, TomlFormat.format(text, range, options));
+	}
+	/**
+	* Compute the edits that replace, delete, or insert a value at `path`,
+	* resolved through the document's semantic view. Every segment but the
+	* last must resolve — intermediate tables are never auto-created. A
+	* `value` of `undefined` deletes: a key-value's whole line, an inline
+	* entry, or an array item, splicing separators. A new key inserts per the
+	* pinned placement rules: root keys land after the last root expression
+	* (before the first header), section keys after the section's last
+	* expression, dotted-table keys as dotted keys appended to the defining
+	* section; inline and implicitly created tables refuse. Inserted lines
+	* inherit the document's dominant newline unless `options.newline`
+	* overrides it. Every modified document reparses cleanly.
+	*/
+	static modify = Effect.fn("TomlFormat.modify")(function* (text, path, value, options) {
+		const failWith = (code, message, offset = 0, length = 0) => new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, {
+			code,
+			message,
+			offset,
+			length
+		}) });
+		if (path.length === 0) return yield* failWith("DottedKeyConflict", "an empty path does not address a value");
+		if (path.length > 256) return yield* failWith("NestingDepthExceeded", `path depth ${path.length} exceeds the ${256} cap`);
+		const doc = yield* TomlDocument.parse(text);
+		if (doc.diagnostics.length > 0) return yield* new TomlModificationError({ diagnostic: doc.diagnostics[0] });
+		const { root, sections } = buildSemanticIndex(doc.expressions);
+		const ctx = {
+			source: text,
+			sections,
+			nl: options?.newline ?? dominantNewline(text)
+		};
+		let raw;
+		try {
+			let cursor = {
+				t: "table",
+				table: root
+			};
+			for (let i = 0; i < path.length - 1; i++) cursor = step(cursor, path[i]);
+			raw = terminal(cursor, path[path.length - 1], value, ctx);
+		} catch (defect) {
+			if (defect instanceof ModifyFailure) return yield* failWith(defect.code, defect.message, defect.offset, defect.len);
+			if (isRawTomlError(defect)) return yield* new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, defect.diagnostic) });
+			if (isGuardExceeded(defect)) return yield* failWith("NestingDepthExceeded", defect.message, defect.offset);
+			throw defect;
+		}
+		return raw.map((edit) => TomlEdit.make({
+			offset: edit.offset,
+			length: edit.length,
+			content: edit.newText
+		}));
+	});
+	/**
+	* Modify `text` and apply the resulting edits in one step
+	* (`TomlEdit.applyAll ∘ modify`).
+	*/
+	static modifyToString = Effect.fn("TomlFormat.modifyToString")(function* (text, path, value, options) {
+		const edits = yield* TomlFormat.modify(text, path, value, options);
+		return TomlEdit.applyAll(text, edits);
+	});
+};
+
+//#endregion
+export { TomlFormat, TomlFormattingOptions, TomlModificationError };