@effected/toml 0.1.0

package/TomlDocument.js

@@ -0,0 +1,133 @@
+import { isRawTomlError } from "./internal/diagnostics.js";
+import { isGuardExceeded } from "./internal/limits.js";
+import { TomlExpression } from "./TomlNode.js";
+import { parseExpressions } from "./internal/parser.js";
+import { analyze, buildValue } from "./internal/semantic.js";
+import { TomlDiagnostic } from "./TomlDiagnostic.js";
+import { TomlParseError } from "./Toml.js";
+import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+
+//#region src/TomlDocument.ts
+/**
+* Materialize an engine throw into the typed error: `RawTomlError` becomes a
+* positioned diagnostic and a `GuardExceeded` depth trip becomes a
+* `NestingDepthExceeded` diagnostic. Anything else is a genuine defect and
+* rethrows.
+*/
+const materializeError = (text, defect) => {
+	if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
+	if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
+		code: "NestingDepthExceeded",
+		message: defect.message,
+		offset: defect.offset,
+		length: 0
+	})] });
+	throw defect;
+};
+/**
+* A parsed TOML document that never loses a byte: the `source` text, the
+* linear {@link (TomlExpression:type)} CST whose spans tile the source
+* exactly, and
+* any semantic violations as {@link TomlDiagnostic} data.
+*
+* @remarks
+* `parse` fails typed only on lex/parse errors; a syntactically valid but
+* semantically illegal document (say, a duplicate key) still parses with the
+* violation recorded in `diagnostics`, so the text stays inspectable and
+* editable. `stringify` reconstructs the source by concatenating expression
+* spans — that the result equals `source` is the span-bookkeeping proof, held
+* byte-exact across the full toml-test corpus. `toValue` refuses on a
+* non-empty `diagnostics`.
+*
+* Construct via {@link TomlDocument.parse}; `TomlDocument.make` is for
+* synthetic documents.
+*
+* @example
+* ```ts
+* import { TomlDocument } from "@effected/toml";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const doc = yield* TomlDocument.parse('name = "Alice"\n');
+*   doc.stringify(); // 'name = "Alice"\n' — byte-exact
+*   return yield* doc.toValue(); // { name: "Alice" }
+* });
+* ```
+*
+* @public
+*/
+var TomlDocument = class TomlDocument extends Schema.Class("TomlDocument")({
+	source: Schema.String,
+	expressions: Schema.Array(TomlExpression),
+	diagnostics: Schema.Array(TomlDiagnostic)
+}) {
+	/**
+	* Parse TOML text into a lossless document. Fails with
+	* {@link TomlParseError} only on lex/parse errors — including a
+	* nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
+	* diagnostic, never an unhandled defect. Semantic violations do not fail:
+	* they land in `diagnostics` as data (first violation wins, so there is at
+	* most one today; the array shape is the contract).
+	*/
+	static parse = Effect.fn("TomlDocument.parse")(function* (text) {
+		const expressions = yield* Effect.try({
+			try: () => parseExpressions(text),
+			catch: (defect) => materializeError(text, defect)
+		});
+		const diagnostics = [];
+		try {
+			analyze(expressions);
+		} catch (defect) {
+			if (!isRawTomlError(defect)) throw defect;
+			diagnostics.push(TomlDiagnostic.fromRaw(text, defect.diagnostic));
+		}
+		return TomlDocument.make({
+			source: text,
+			expressions,
+			diagnostics
+		});
+	});
+	/**
+	* A `Schema<TomlDocument, string>` decoding TOML text into a full document
+	* (source, expressions, diagnostics) and encoding a document back to its
+	* byte-exact text.
+	*
+	* Schema-producing: each call returns a fresh schema whose derivation
+	* caches are not shared across calls; bind the result to a `const` on hot
+	* paths.
+	*/
+	static schema() {
+		return Schema.String.pipe(Schema.decodeTo(Schema.instanceOf(TomlDocument), SchemaTransformation.transformOrFail({
+			decode: (input) => TomlDocument.parse(input).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(input), { message: error.message }))),
+			encode: (doc) => Effect.succeed(doc.stringify())
+		})));
+	}
+	/**
+	* Materialize the document's plain JavaScript value. Fails with
+	* {@link TomlParseError} carrying the stored `diagnostics` when the parse
+	* recorded semantic violations; otherwise builds the value from the
+	* expression list (already validated, so the defensive materialization
+	* wrapper is belt-and-suspenders).
+	*/
+	toValue() {
+		if (this.diagnostics.length > 0) return Effect.fail(new TomlParseError({ diagnostics: this.diagnostics }));
+		return Effect.try({
+			try: () => buildValue(this.expressions),
+			catch: (defect) => materializeError(this.source, defect)
+		});
+	}
+	/**
+	* Reconstruct the document text by concatenating each expression's source
+	* span in order. The expression spans tile the source exactly, so the
+	* result equals `source` byte-for-byte — the round-trip contract this
+	* class exists to prove. Pure and total.
+	*/
+	stringify() {
+		let out = "";
+		for (const expression of this.expressions) out += this.source.slice(expression.offset, expression.offset + expression.length);
+		return out;
+	}
+};
+
+//#endregion
+export { TomlDocument };

package/TomlEdit.js

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+
+//#region src/TomlEdit.ts
+/**
+* A range within a TOML document, expressed as a zero-based character
+* `offset` and a `length` in UTF-16 code units. Pass to `TomlFormat.format`
+* to restrict formatting to the expressions intersecting a region.
+*
+* @public
+*/
+var TomlRange = class extends Schema.Class("TomlRange")({
+	offset: Schema.Number,
+	length: Schema.Number
+}) {};
+/**
+* A non-mutating text edit: replace the span `[offset, offset + length)` with
+* `content`. Set `length` to `0` to insert, `content` to `""` to delete.
+*
+* @remarks
+* Structurally identical to `@effected/jsonc`'s and `@effected/yaml`'s edit
+* shapes (same field names, types and semantics) per the jsonc/yaml parity
+* convention, so consumer code can be written once over "a document codec's
+* Edit/Range/Path".
+*
+* @public
+*/
+var TomlEdit = class extends Schema.Class("TomlEdit")({
+	offset: Schema.Number,
+	length: Schema.Number,
+	content: Schema.String
+}) {
+	/**
+	* Apply `edits` to `text`, producing a new string. Edits are applied in
+	* reverse-offset order so earlier offsets stay valid; the input `edits`
+	* array is not mutated. Overlapping edits are a programmer error and throw
+	* as a defect — `TomlFormat` never produces them.
+	*/
+	static applyAll(text, edits) {
+		const sorted = [...edits].sort((a, b) => b.offset - a.offset);
+		for (let i = 0; i + 1 < sorted.length; i++) {
+			const upper = sorted[i];
+			const lower = sorted[i + 1];
+			if (lower.offset + lower.length > upper.offset) throw new Error(`TomlEdit.applyAll received overlapping edits at offsets ${lower.offset} and ${upper.offset} — overlapping edits are a programmer error`);
+		}
+		let result = text;
+		for (const edit of sorted) result = result.slice(0, edit.offset) + edit.content + result.slice(edit.offset + edit.length);
+		return result;
+	}
+};
+
+//#endregion
+export { TomlEdit, TomlRange };