@effected/toml 0.1.0

package/internal/semantic.js

@@ -0,0 +1,253 @@
+import { RawTomlError } from "./diagnostics.js";
+import { TomlArray, TomlArrayTableHeader, TomlInlineTable, TomlTableHeader, TomlTrivia } from "../TomlNode.js";
+
+//#region src/internal/semantic.ts
+const makeNode = (kind, sectionId = 0) => ({
+	kind,
+	table: /* @__PURE__ */ new Map(),
+	elements: [],
+	sectionId
+});
+const raise = (code, message, key) => {
+	throw new RawTomlError({
+		code,
+		message,
+		offset: key.offset,
+		length: key.length
+	});
+};
+/**
+* Header navigation (G8 rules 1 and 2, shared prefix): walk every segment but
+* the last, creating `table-implicit` for absent names, passing through
+* tables (dotted included — the corpus deviation) and descending into the
+* last element of an array of tables.
+*/
+const navigateHeaderPrefix = (root, keyPath) => {
+	let current = root;
+	for (let i = 0; i < keyPath.length - 1; i++) {
+		const key = keyPath[i];
+		const existing = current.table.get(key.value);
+		if (existing === void 0) {
+			const child = makeNode("table-implicit");
+			current.table.set(key.value, child);
+			current = child;
+			continue;
+		}
+		switch (existing.kind) {
+			case "table-explicit":
+			case "table-implicit":
+			case "table-dotted":
+				current = existing;
+				break;
+			case "array-tables":
+				current = existing.elements[existing.elements.length - 1];
+				break;
+			case "inline": return raise("InlineTableExtended", `inline table "${key.value}" cannot be extended`, key);
+			case "static-array": return raise("ArrayOfTablesConflict", `"${key.value}" is a static array, not an array of tables`, key);
+			case "value": return raise("TableRedefined", `"${key.value}" is already defined as a value`, key);
+		}
+	}
+	return current;
+};
+/** G8 rule 1, final segment: create `table-explicit`, promote `table-implicit`, or error. */
+const openTable = (root, keyPath) => {
+	const parent = navigateHeaderPrefix(root, keyPath);
+	const key = keyPath[keyPath.length - 1];
+	const existing = parent.table.get(key.value);
+	if (existing === void 0) {
+		const node = makeNode("table-explicit");
+		parent.table.set(key.value, node);
+		return node;
+	}
+	if (existing.kind === "table-implicit") {
+		existing.kind = "table-explicit";
+		return existing;
+	}
+	return raise("TableRedefined", `table "${key.value}" is already defined`, key);
+};
+/** G8 rule 2, final segment: create the array and its first element, append to an existing one, or error. */
+const openArrayTable = (root, keyPath) => {
+	const parent = navigateHeaderPrefix(root, keyPath);
+	const key = keyPath[keyPath.length - 1];
+	const existing = parent.table.get(key.value);
+	if (existing === void 0) {
+		const array = makeNode("array-tables");
+		const element = makeNode("table-explicit");
+		array.elements.push(element);
+		parent.table.set(key.value, array);
+		return {
+			element,
+			index: 0
+		};
+	}
+	if (existing.kind === "array-tables") {
+		const element = makeNode("table-explicit");
+		existing.elements.push(element);
+		return {
+			element,
+			index: existing.elements.length - 1
+		};
+	}
+	return raise("ArrayOfTablesConflict", `"${key.value}" cannot be redefined as an array of tables`, key);
+};
+/**
+* G8 rule 3: a (possibly dotted) key assignment scoped to `table` under
+* `sectionId`. Intermediates must be absent (create `table-dotted`) or
+* `table-dotted` from the same section; the final key must be absent.
+*/
+const assignEntry = (table, sectionId, keyPath, value, context) => {
+	let current = table;
+	for (let i = 0; i < keyPath.length - 1; i++) {
+		const key = keyPath[i];
+		const existing = current.table.get(key.value);
+		if (existing === void 0) {
+			const child = makeNode("table-dotted", sectionId);
+			current.table.set(key.value, child);
+			current = child;
+			continue;
+		}
+		if (existing.kind === "table-dotted" && existing.sectionId === sectionId) {
+			current = existing;
+			continue;
+		}
+		if (existing.kind === "inline") raise("InlineTableExtended", `inline table "${key.value}" cannot be extended`, key);
+		raise("DottedKeyConflict", `dotted key cannot extend "${key.value}"`, key);
+	}
+	const key = keyPath[keyPath.length - 1];
+	if (current.table.has(key.value)) raise("DuplicateKey", `duplicate key "${key.value}"`, key);
+	current.table.set(key.value, nodeForValue(value, context));
+};
+/** The provenance node for an assigned value; validates inline tables (arrays included) on the way. */
+const nodeForValue = (value, context) => {
+	if (value instanceof TomlInlineTable) return inlineNode(value, context);
+	if (value instanceof TomlArray) {
+		for (const item of value.items) checkArrayItem(item, context);
+		return makeNode("static-array");
+	}
+	return makeNode("value");
+};
+/** Inline tables hide anywhere inside a static array; validate them all. Depth is parser-capped. */
+const checkArrayItem = (item, context) => {
+	if (item instanceof TomlInlineTable) {
+		inlineNode(item, context);
+		return;
+	}
+	if (item instanceof TomlArray) for (const inner of item.items) checkArrayItem(inner, context);
+};
+/**
+* G8 rule 4: build an inline table's own scope (dotted keys follow rule 3
+* inside it), then freeze it — the returned node's `inline` kind makes every
+* later navigation through it an `InlineTableExtended` error.
+*/
+const inlineNode = (node, context) => {
+	const scopeId = context.nextId++;
+	const sem = makeNode("table-dotted", scopeId);
+	for (const entry of node.entries) assignEntry(sem, scopeId, entry.keyPath, entry.value, context);
+	sem.kind = "inline";
+	return sem;
+};
+/**
+* Walk the expressions through the G8 state machine, firing the visitor after
+* each expression validates; throws `RawTomlError` at the first violation.
+*/
+const analyze = (expressions, visitor) => {
+	const root = makeNode("table-explicit");
+	const context = { nextId: 1 };
+	let currentTable = root;
+	let currentSectionId = 0;
+	let currentPrefix = [];
+	visitor?.onTableStart?.([], void 0);
+	for (const expression of expressions) {
+		if (expression instanceof TomlTrivia) continue;
+		if (expression instanceof TomlTableHeader) {
+			currentTable = openTable(root, expression.keyPath);
+			currentSectionId = context.nextId++;
+			currentPrefix = expression.keyPath.map((key) => key.value);
+			visitor?.onTableStart?.(currentPrefix, expression);
+			continue;
+		}
+		if (expression instanceof TomlArrayTableHeader) {
+			const { element, index } = openArrayTable(root, expression.keyPath);
+			currentTable = element;
+			currentSectionId = context.nextId++;
+			currentPrefix = expression.keyPath.map((key) => key.value);
+			visitor?.onArrayTableStart?.(currentPrefix, index, expression);
+			continue;
+		}
+		assignEntry(currentTable, currentSectionId, expression.keyPath, expression.value, context);
+		visitor?.onKeyValue?.([...currentPrefix, ...expression.keyPath.map((key) => key.value)], expression);
+	}
+};
+/** Set a key as an own data property — `__proto__` included (yaml/jsonc precedent). */
+const setOwnProperty = (target, key, value) => {
+	if (key === "__proto__") Object.defineProperty(target, key, {
+		value,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	});
+	else target[key] = value;
+};
+/** Own-property read that never leaks through the prototype chain (`__proto__` included). */
+const getOwnProperty = (target, key) => Object.hasOwn(target, key) ? target[key] : void 0;
+/**
+* Navigate `path` in the output tree, creating plain objects for absent names
+* and descending into the LAST element of arrays (mirrors the array-of-tables
+* rule — `analyze` has already proven every step legal). Iterative.
+*/
+const navigateOutput = (target, path) => {
+	let current = target;
+	for (const segment of path) {
+		let child = getOwnProperty(current, segment);
+		if (child === void 0) {
+			child = {};
+			setOwnProperty(current, segment, child);
+		}
+		if (Array.isArray(child)) child = child[child.length - 1];
+		current = child;
+	}
+	return current;
+};
+/** Materialize a CST value node into a plain value. Recursion is parser-depth-capped. */
+const materialize = (value) => {
+	if (value instanceof TomlArray) return value.items.map(materialize);
+	if (value instanceof TomlInlineTable) {
+		const output = {};
+		for (const entry of value.entries) {
+			const parent = navigateOutput(output, entry.keyPath.slice(0, -1).map((key) => key.value));
+			setOwnProperty(parent, entry.keyPath[entry.keyPath.length - 1].value, materialize(entry.value));
+		}
+		return output;
+	}
+	return value.value;
+};
+/**
+* `analyze` + plain-value construction in a single pass: the value builder is
+* the default visitor riding the same walk. Scalars materialize to their
+* decoded values (`TomlInteger` → number | bigint, `TomlDateTimeLiteral` →
+* its date-time class instance), arrays to plain arrays, tables and inline
+* tables to plain objects with `__proto__` as an own data property.
+*/
+const buildValue = (expressions) => {
+	const result = {};
+	analyze(expressions, {
+		onTableStart: (path, _header) => {
+			navigateOutput(result, path);
+		},
+		onArrayTableStart: (path, _index, _header) => {
+			const parent = navigateOutput(result, path.slice(0, -1));
+			const key = path[path.length - 1];
+			const existing = getOwnProperty(parent, key);
+			if (Array.isArray(existing)) existing.push({});
+			else setOwnProperty(parent, key, [{}]);
+		},
+		onKeyValue: (path, expr) => {
+			const parent = navigateOutput(result, path.slice(0, -1));
+			setOwnProperty(parent, path[path.length - 1], materialize(expr.value));
+		}
+	});
+	return result;
+};
+
+//#endregion
+export { analyze, buildValue };

package/internal/stringifyValue.js

@@ -0,0 +1,191 @@
+import { RawTomlError } from "./diagnostics.js";
+import { GuardExceeded } from "./limits.js";
+import { TomlLocalDate, TomlLocalDateTime, TomlLocalTime, TomlOffsetDateTime } from "../TomlDateTime.js";
+
+//#region src/internal/stringifyValue.ts
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+const INT64_FLOAT_BOUND = 2 ** 63;
+const BARE_KEY = /^[A-Za-z0-9_-]+$/;
+const raise = (code, message) => {
+	throw new RawTomlError({
+		code,
+		message,
+		offset: 0,
+		length: 0
+	});
+};
+const guardDepth = (depth) => {
+	if (depth > 256) throw new GuardExceeded("NestingDepthExceeded", 256, depth, 0);
+};
+/** Render an error path for diagnostics: dotted keys, bracketed indices. */
+const renderPath = (path) => {
+	if (path.length === 0) return "(root)";
+	let out = "";
+	for (const segment of path) if (typeof segment === "number") out += `[${segment}]`;
+	else out += out === "" ? renderKey(segment) : `.${renderKey(segment)}`;
+	return out;
+};
+/** The JS type name for an UnsupportedValue message. */
+const jsTypeName = (value) => {
+	if (value === null) return "null";
+	if (typeof value !== "object") return typeof value;
+	const name = Object.getPrototypeOf(value)?.constructor?.name;
+	return typeof name === "string" && name.length > 0 ? name : "object";
+};
+/** A basic single-line string: `"` `\` and control characters escaped. */
+const renderString = (value) => {
+	let out = "\"";
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code === 34) out += "\\\"";
+		else if (code === 92) out += "\\\\";
+		else if (code === 8) out += "\\b";
+		else if (code === 9) out += "\\t";
+		else if (code === 10) out += "\\n";
+		else if (code === 12) out += "\\f";
+		else if (code === 13) out += "\\r";
+		else if (code < 32 || code === 127) out += `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+		else out += value[i];
+	}
+	return `${out}"`;
+};
+/** A key: bare when it matches the bare-key grammar, else basic-quoted. */
+const renderKey = (key) => BARE_KEY.test(key) ? key : renderString(key);
+/** A dotted header path, quoting per-segment by the key rule. */
+const renderHeaderPath = (path) => path.map(renderKey).join(".");
+/**
+* A `number`: integral values inside the int64 range emit as decimal integers
+* (a JS `1.0` is indistinguishable from `1` — every JS emitter shares this
+* divergence); `-0` emits as `-0.0`; integral values outside the int64 range
+* emit as floats so they round-trip instead of overflowing at parse time;
+* non-integral values emit as the shortest round-trip decimal with a
+* guaranteed `.` or `e`; the specials emit as `inf`/`-inf`/`nan`.
+*/
+const renderNumber = (value) => {
+	if (Number.isNaN(value)) return "nan";
+	if (value === Number.POSITIVE_INFINITY) return "inf";
+	if (value === Number.NEGATIVE_INFINITY) return "-inf";
+	if (Object.is(value, -0)) return "-0.0";
+	if (Number.isInteger(value) && value >= -INT64_FLOAT_BOUND && value < INT64_FLOAT_BOUND) return String(value);
+	const text = String(value);
+	return /[.eE]/.test(text) ? text : `${text}.0`;
+};
+const isTomlDateTime = (value) => value instanceof TomlOffsetDateTime || value instanceof TomlLocalDateTime || value instanceof TomlLocalDate || value instanceof TomlLocalTime;
+/** Plain objects only (null-prototype included) — never arrays or class instances. */
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+};
+/** Scalar rendering; `undefined` means "not a scalar" (arrays/objects/rejects). */
+const renderScalar = (value, path) => {
+	switch (typeof value) {
+		case "string": return renderString(value);
+		case "boolean": return value ? "true" : "false";
+		case "number": return renderNumber(value);
+		case "bigint":
+			if (value < INT64_MIN || value > INT64_MAX) raise("IntegerOutOfRange", `integer ${value} at ${renderPath(path)} is outside the 64-bit signed range`);
+			return value.toString();
+		default:
+			if (isTomlDateTime(value)) return value.toString();
+			return;
+	}
+};
+const checkCircular = (value, ancestors, path) => {
+	if (ancestors.has(value)) raise("CircularReference", `circular reference at ${renderPath(path)}`);
+};
+/** One value as an inline fragment: scalars, inline arrays, inline tables. */
+const renderInline = (value, path, depth, ancestors) => {
+	const scalar = renderScalar(value, path);
+	if (scalar !== void 0) return scalar;
+	if (Array.isArray(value)) {
+		guardDepth(depth);
+		checkCircular(value, ancestors, path);
+		ancestors.add(value);
+		const items = value.map((item, index) => renderInline(item, [...path, index], depth + 1, ancestors));
+		ancestors.delete(value);
+		return `[${items.join(", ")}]`;
+	}
+	if (isPlainObject(value)) {
+		guardDepth(depth);
+		checkCircular(value, ancestors, path);
+		ancestors.add(value);
+		const parts = Object.keys(value).map((key) => `${renderKey(key)} = ${renderInline(value[key], [...path, key], depth + 1, ancestors)}`);
+		ancestors.delete(value);
+		return parts.length === 0 ? "{}" : `{ ${parts.join(", ")} }`;
+	}
+	return raise("UnsupportedValue", `unsupported ${jsTypeName(value)} value at ${renderPath(path)}`);
+};
+/**
+* Render a single value as an inline TOML fragment (scalars, arrays and
+* objects all inline). The single-value seam the document modify entry point
+* rides on.
+*/
+const renderInlineValue = (value) => renderInline(value, [], 0, /* @__PURE__ */ new Set());
+const classify = (table) => {
+	const pairs = [];
+	const tables = [];
+	const arrayTables = [];
+	for (const key of Object.keys(table)) {
+		const value = table[key];
+		if (isPlainObject(value)) tables.push(key);
+		else if (Array.isArray(value) && value.length > 0 && value.every(isPlainObject)) arrayTables.push(key);
+		else pairs.push(key);
+	}
+	return {
+		pairs,
+		tables,
+		arrayTables
+	};
+};
+/** Push a header line, preceded by a blank line except at document start. */
+const pushHeader = (lines, header) => {
+	if (lines.length > 0) lines.push("");
+	lines.push(header);
+};
+/**
+* Emit one table's body: pairs, then sub-table sections, then
+* array-of-tables sections. `headerPath` carries the dotted section path
+* (strings only); `errorPath` additionally carries array indices.
+*/
+const emitTable = (table, headerPath, errorPath, lines, depth, ancestors) => {
+	guardDepth(depth);
+	checkCircular(table, ancestors, errorPath);
+	ancestors.add(table);
+	const { pairs, tables, arrayTables } = classify(table);
+	for (const key of pairs) lines.push(`${renderKey(key)} = ${renderInline(table[key], [...errorPath, key], depth + 1, ancestors)}`);
+	for (const key of tables) {
+		pushHeader(lines, `[${renderHeaderPath([...headerPath, key])}]`);
+		emitTable(table[key], [...headerPath, key], [...errorPath, key], lines, depth + 1, ancestors);
+	}
+	for (const key of arrayTables) {
+		const array = table[key];
+		checkCircular(array, ancestors, [...errorPath, key]);
+		ancestors.add(array);
+		for (let index = 0; index < array.length; index++) {
+			pushHeader(lines, `[[${renderHeaderPath([...headerPath, key])}]]`);
+			emitTable(array[index], [...headerPath, key], [
+				...errorPath,
+				key,
+				index
+			], lines, depth + 1, ancestors);
+		}
+		ancestors.delete(array);
+	}
+	ancestors.delete(table);
+};
+/**
+* Stringify a plain value as a canonical TOML document. The root must be a
+* plain object (a TOML document is a table); an empty root emits the empty
+* string, anything else ends with `newline`.
+*/
+const stringifyValue = (value, newline) => {
+	if (!isPlainObject(value)) return raise("UnsupportedValue", `unsupported ${jsTypeName(value)} value at ${renderPath([])} — a TOML document is a table`);
+	const lines = [];
+	emitTable(value, [], [], lines, 0, /* @__PURE__ */ new Set());
+	return lines.length === 0 ? "" : `${lines.join(newline)}${newline}`;
+};
+
+//#endregion
+export { renderInlineValue, renderKey, stringifyValue };

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@effected/toml",
+	"version": "0.1.0",
+	"private": false,
+	"description": "TOML 1.0.0 parsing, editing and formatting as Effect schemas: typed diagnostics, a lossless CST and first-class date-time values.",
+	"keywords": [
+		"toml",
+		"parser",
+		"config",
+		"cst",
+		"effect",
+		"schema",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/toml#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/toml"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "4.0.0-beta.98"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}