Compabitility with KDL v1

The parse function in this package only supports KDL v2 documents. If your program wants to be compatible with KDL v1 as well, this package exposes an extra entry point: @bgotink/kdl/v1-compat.

Loading compatibility code

The compatibility endpoint is a lot larger and slower than the regular @bgotink/kdl endpoint. Programs that want to provide compatiblity are therefore encouraged to lazy-load the compatibility code, for example:

import {readFile} from "node:fs/promises";
import {parse} from "@bgotink/kdl";

export async function loadConfiguration(path) {
	const content = await readFile(path);

	try {
		return parse(content);
	} catch (e) {
		const {parseWithoutFormatting} = await import("@bgotink/kdl/v1-compat");
		try {
			return parseWithoutFormatting(content);
		} catch (e2) {
			throw new AggregateError(
				[e, e2],
				`Failed to parse configuration at ${path}`,
			);
		}
	}
}

Numbers

Here's a comparison of @bgotink/kdl and @bgotink/kdl/v1-compat in numbers:

Two compatibility functions

The compatibility endpoint exposes two functions that parse a KDL v1 text into a Document. Even though both functions yield documents that are functionally equivalent, they serve very different purposes:

• parseWithoutFormatting reads the KDL v1 text without storing any formatting, whitespace, comments, etc. The resulting document can be used everywhere a regular KDL v2 document can be used, but stringifying the document via format() will throw out any comments and formatting its author added.
• parseAndTransform reads the KDL v1 text and transforms any formatting, whitespace, comments, etc. into their KDL v2 equivalent. The resulting document can safely be stringified via format() to overwrite the original KDL v1 text to automate the migration from KDL v1 to KDL v2.