locter 3.0.0 → 4.0.0-beta.0

package/dist/index.mjs

@@ -1,13 +1,13 @@
 import { createRequire } from "node:module";
 import { BaseError, hasInstanceof, markInstanceof } from "@ebec/core";
 import path from "node:path";
+import fg from "fast-glob";
 import { destr } from "destr";
-import { unflatten } from "flat";
+import { flatten, unflatten } from "flat";
 import fs from "node:fs";
-import fg from "fast-glob";
 import { createJiti } from "jiti";
 import { pathToFileURL } from "node:url";
-import { parse } from "yaml";
+import { isMap, isNode, isScalar, parse, parseDocument, stringify } from "yaml";
 //#region src/errors/base.ts
 const LOCTER_ERROR_MARKER = Symbol.for("@locter/error");
 var LocterError = class extends BaseError {
@@ -62,18 +62,6 @@ var LocterUnknownExtensionError = class extends LocterError {
 	}
 };
 //#endregion
-//#region src/utils/file-name.ts
-function getFileNameExtension(input, allowed) {
-	const extension = path.extname(input);
-	if (extension === "" || extension === ".") return;
-	if (typeof allowed === "undefined" || allowed.includes(extension)) return extension;
-}
-function removeFileNameExtension(input, extensions) {
-	const extension = getFileNameExtension(input, extensions);
-	if (extension) return input.substring(0, input.length - extension.length);
-	return input;
-}
-//#endregion
 //#region src/utils/has-property.ts
 function hasOwnProperty(obj, prop) {
 	return Object.prototype.hasOwnProperty.call(obj, prop);
@@ -111,6 +99,13 @@ function isVitestRuntimeEnvironment() {
 function isTsNodeRuntimeEnvironment() {
 	return !!process[Symbol.for("ts-node.register.instance")];
 }
+const TSX_MARKER_REGEX = /(?:^|=|[\\/])tsx(?:$|[\\/])/;
+function isTsxRuntimeEnvironment() {
+	if (typeof process === "undefined") return false;
+	if (Array.isArray(process.execArgv) && process.execArgv.some((arg) => TSX_MARKER_REGEX.test(arg))) return true;
+	const { _preload_modules: preloadModules } = process;
+	return Array.isArray(preloadModules) && preloadModules.some((el) => TSX_MARKER_REGEX.test(el));
+}
 //#endregion
 //#region src/utils/typescript.ts
 function isTypeScriptError(input) {
@@ -119,8 +114,20 @@ function isTypeScriptError(input) {
 	return typeof input.message === "string" && /TS\d+/.test(input.message);
 }
 //#endregion
+//#region src/errors/write.ts
+const LOCTER_WRITE_ERROR_MARKER = Symbol.for("@locter/write-error");
+var LocterWriteError = class extends LocterError {
+	static [Symbol.hasInstance](input) {
+		return hasInstanceof(input, LOCTER_WRITE_ERROR_MARKER);
+	}
+	constructor(input = {}) {
+		super(input);
+		markInstanceof(this, LOCTER_WRITE_ERROR_MARKER);
+	}
+};
+//#endregion
 //#region src/errors/wrap.ts
-const NOT_FOUND_CODES = new Set([
+const NOT_FOUND_CODES = /* @__PURE__ */ new Set([
 	"ENOENT",
 	"MODULE_NOT_FOUND",
 	"ERR_MODULE_NOT_FOUND"
@@ -142,6 +149,55 @@ function wrapLoaderError(input, path) {
 		path
 	});
 }
+function wrapWriteError(input, path) {
+	if (input instanceof LocterError) return input;
+	const code = isObject(input) && hasStringProperty(input, "code") ? input.code : void 0;
+	return new LocterWriteError({
+		message: isObject(input) && hasStringProperty(input, "message") ? input.message : `Failed to write: ${path}`,
+		code,
+		cause: input,
+		path
+	});
+}
+//#endregion
+//#region src/utils/twin.ts
+/**
+* Perform one effect inside a twin body: `const x = yield* op(a, s)`.
+*/
+function* op(asyncFn, syncFn) {
+	return yield {
+		async: asyncFn,
+		sync: syncFn
+	};
+}
+async function runTwinAsync(body) {
+	let step = body.next();
+	while (!step.done) {
+		let result;
+		try {
+			result = await step.value.async();
+		} catch (e) {
+			step = body.throw(e);
+			continue;
+		}
+		step = body.next(result);
+	}
+	return step.value;
+}
+function runTwinSync(body) {
+	let step = body.next();
+	while (!step.done) {
+		let result;
+		try {
+			result = step.value.sync();
+		} catch (e) {
+			step = body.throw(e);
+			continue;
+		}
+		step = body.next(result);
+	}
+	return step.value;
+}
 //#endregion
 //#region src/locator/utils.ts
 function buildLocatorPatterns(pattern) {
@@ -151,23 +207,12 @@ function buildLocatorOptions(options = {}) {
 	const cwd = options.cwd ? toArray(options.cwd) : [];
 	const ignore = options.ignore ? toArray(options.ignore) : [];
 	if (cwd.length === 0) cwd.push(process.cwd());
-	let onlyFiles;
-	let onlyDirectories;
-	if (options.onlyDirectories === options.onlyFiles) {
-		onlyDirectories = false;
-		onlyFiles = !options.onlyDirectories;
-	} else if (typeof options.onlyFiles === "undefined") {
-		onlyDirectories = options.onlyDirectories ?? false;
-		onlyFiles = !options.onlyDirectories;
-	} else {
-		onlyFiles = options.onlyFiles ?? true;
-		onlyDirectories = !options.onlyFiles;
-	}
+	const onlyDirectories = options.onlyDirectories ?? false;
 	return {
 		cwd,
 		ignore,
 		onlyDirectories,
-		onlyFiles,
+		onlyFiles: onlyDirectories ? false : options.onlyFiles ?? true,
 		dot: options.dot ?? false
 	};
 }
@@ -191,79 +236,57 @@ function buildFilePath(input) {
 	if (typeof input === "string") return input;
 	return input.path;
 }
-function buildFilePathWithoutExtension(input) {
-	let info;
-	if (typeof input === "string") info = pathToLocatorInfo(input);
-	else info = input;
-	return path.join(info.directory, info.name);
-}
 //#endregion
-//#region src/locator/async.ts
-async function locateMany(pattern, options) {
+//#region src/locator/core.ts
+function buildGlobJobs(pattern, options) {
 	const patterns = buildLocatorPatterns(pattern);
 	const opts = buildLocatorOptions(options);
-	const items = [];
-	for (const p of patterns) for (const cwd of opts.cwd) {
-		const files = await fg(p, {
+	const jobs = [];
+	for (const p of patterns) for (const cwd of opts.cwd) jobs.push({
+		pattern: p,
+		options: {
 			absolute: true,
 			cwd,
 			ignore: opts.ignore,
 			onlyFiles: opts.onlyFiles,
 			onlyDirectories: opts.onlyDirectories,
 			dot: opts.dot
-		});
+		}
+	});
+	return jobs;
+}
+function* glob(job) {
+	return yield* op(() => fg(job.pattern, job.options), () => fg.sync(job.pattern, job.options));
+}
+function* locateBody(pattern, options) {
+	for (const job of buildGlobJobs(pattern, options)) {
+		const element = (yield* glob(job)).shift();
+		if (element) return pathToLocatorInfo(element, true);
+	}
+}
+function* locateManyBody(pattern, options) {
+	const items = [];
+	for (const job of buildGlobJobs(pattern, options)) {
+		const files = yield* glob(job);
 		for (const file of files) items.push(pathToLocatorInfo(file, true));
 	}
 	return items;
 }
+//#endregion
+//#region src/locator/async.ts
+async function locateMany(pattern, options) {
+	return runTwinAsync(locateManyBody(pattern, options));
+}
 async function locate(pattern, options) {
-	const patterns = buildLocatorPatterns(pattern);
-	const opts = buildLocatorOptions(options);
-	for (const p of patterns) for (const cwd of opts.cwd) {
-		const element = (await fg(p, {
-			absolute: true,
-			cwd,
-			ignore: opts.ignore,
-			onlyFiles: opts.onlyFiles,
-			onlyDirectories: opts.onlyDirectories,
-			dot: opts.dot
-		})).shift();
-		if (element) return pathToLocatorInfo(element, true);
-	}
+	return runTwinAsync(locateBody(pattern, options));
 }
 //#endregion
 //#region src/locator/sync.ts
 function locateManySync(pattern, options) {
-	const patterns = buildLocatorPatterns(pattern);
-	const opts = buildLocatorOptions(options);
-	const items = [];
-	for (const p of patterns) for (const cwd of opts.cwd) {
-		const files = fg.sync(p, {
-			absolute: true,
-			cwd,
-			ignore: opts.ignore,
-			onlyFiles: opts.onlyFiles,
-			onlyDirectories: opts.onlyDirectories,
-			dot: opts.dot
-		});
-		for (const file of files) items.push(pathToLocatorInfo(file, true));
-	}
-	return items;
+	return runTwinSync(locateManyBody(pattern, options));
 }
 function locateSync(pattern, options) {
-	const patterns = buildLocatorPatterns(pattern);
-	const opts = buildLocatorOptions(options);
-	for (const p of patterns) for (const cwd of opts.cwd) {
-		const element = fg.sync(p, {
-			absolute: true,
-			cwd,
-			ignore: opts.ignore,
-			onlyFiles: opts.onlyFiles,
-			onlyDirectories: opts.onlyDirectories,
-			dot: opts.dot
-		}).shift();
-		if (element) return pathToLocatorInfo(element, true);
-	}
+	return runTwinSync(locateBody(pattern, options));
 }
 //#endregion
 //#region src/locator/up.ts
@@ -282,10 +305,10 @@ function nextDirectory(current, stopAt) {
 	if (parent === current) return;
 	return parent;
 }
-async function locateUp(pattern, options = {}) {
+function* locateUpBody(pattern, options) {
 	let walk = startWalk(options);
 	while (true) {
-		const found = await locate(pattern, {
+		const found = yield* locateBody(pattern, {
 			...walk.baseOptions,
 			cwd: walk.current
 		});
@@ -298,43 +321,96 @@ async function locateUp(pattern, options = {}) {
 		};
 	}
 }
+async function locateUp(pattern, options = {}) {
+	return runTwinAsync(locateUpBody(pattern, options));
+}
 function locateUpSync(pattern, options = {}) {
-	let walk = startWalk(options);
-	while (true) {
-		const found = locateSync(pattern, {
-			...walk.baseOptions,
-			cwd: walk.current
-		});
-		if (found) return found;
-		const next = nextDirectory(walk.current, walk.stopAt);
-		if (!next) return;
-		walk = {
-			...walk,
-			current: next
-		};
-	}
+	return runTwinSync(locateUpBody(pattern, options));
 }
 //#endregion
-//#region src/loader/built-in/conf/module.ts
-var ConfLoader = class {
-	async execute(input) {
-		const filePath = buildFilePath(input);
+//#region src/format/text-file/reader.ts
+/**
+* Base class for readers of text-based file formats: reads the file as
+* UTF-8, delegates to `parse`, and wraps I/O and parse errors in typed
+* LocterError subclasses. Subclasses implement `parse` only — both
+* `read` variants are derived from the same body.
+*/
+var TextFileReader = class {
+	async read(input) {
+		return runTwinAsync(this.body(input));
+	}
+	readSync(input) {
+		return runTwinSync(this.body(input));
+	}
+	*body(input) {
 		try {
-			const file = await fs.promises.readFile(filePath, { encoding: "utf-8" });
-			return this.parse(file);
+			const content = yield* op(() => fs.promises.readFile(input, { encoding: "utf-8" }), () => fs.readFileSync(input, { encoding: "utf-8" }));
+			return this.parse(content);
 		} catch (e) {
-			throw wrapLoaderError(e, filePath);
+			throw wrapLoaderError(e, input);
 		}
 	}
-	executeSync(input) {
-		const filePath = buildFilePath(input);
+};
+//#endregion
+//#region src/format/text-file/writer.ts
+function isNotFound(e) {
+	return e instanceof Error && "code" in e && e.code === "ENOENT";
+}
+/**
+* Base class for writers of text-based file formats: serializes via
+* `stringify`, creates missing parent directories, writes the file as
+* UTF-8 (always terminated by a single trailing newline), and wraps
+* failures in LocterWriteError. Subclasses implement `stringify` only —
+* both `write` variants are derived from the same body.
+*/
+var TextFileWriter = class {
+	/**
+	* Opt-in: when true, the body reads the target file first (undefined
+	* if absent) and passes its content to `stringify` as `existing` —
+	* the hook behind format-preserving write-back (YAML comment
+	* grafting, JSON indent detection).
+	*/
+	get usesExistingContent() {
+		return false;
+	}
+	async write(input, value) {
+		return runTwinAsync(this.body(input, value));
+	}
+	writeSync(input, value) {
+		runTwinSync(this.body(input, value));
+	}
+	*body(input, value) {
+		const filePath = input;
 		try {
-			const file = fs.readFileSync(filePath, { encoding: "utf-8" });
-			return this.parse(file);
+			let existing;
+			if (this.usesExistingContent) existing = yield* op(() => fs.promises.readFile(filePath, { encoding: "utf-8" }).catch((e) => {
+				if (isNotFound(e)) return;
+				throw e;
+			}), () => {
+				try {
+					return fs.readFileSync(filePath, { encoding: "utf-8" });
+				} catch (e) {
+					if (isNotFound(e)) return;
+					throw e;
+				}
+			});
+			let content = this.stringify(value, existing);
+			if (!content.endsWith("\n")) content += "\n";
+			const directory = path.dirname(filePath);
+			yield* op(async () => {
+				await fs.promises.mkdir(directory, { recursive: true });
+			}, () => {
+				fs.mkdirSync(directory, { recursive: true });
+			});
+			yield* op(() => fs.promises.writeFile(filePath, content, { encoding: "utf-8" }), () => fs.writeFileSync(filePath, content, { encoding: "utf-8" }));
 		} catch (e) {
-			throw wrapLoaderError(e, filePath);
+			throw wrapWriteError(e, filePath);
 		}
 	}
+};
+//#endregion
+//#region src/format/built-in/conf/reader.ts
+var ConfReader = class extends TextFileReader {
 	parse(contents) {
 		const config = {};
 		const lines = contents.split(/\n|\r|\r\n/);
@@ -356,70 +432,83 @@ var ConfLoader = class {
 	}
 };
 //#endregion
-//#region src/loader/built-in/json/module.ts
-var JSONLoader = class {
-	async execute(input) {
-		const filePath = buildFilePath(input);
-		try {
-			const file = await fs.promises.readFile(filePath, { encoding: "utf-8" });
-			return JSON.parse(file);
-		} catch (e) {
-			throw wrapLoaderError(e, filePath);
+//#region src/format/built-in/conf/writer.ts
+function serializeValue(value) {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+* Serializes an object to `key=value` lines (the inverse of ConfReader):
+* nested objects become dot-separated keys, arrays become repeated
+* `key[]=` lines. Round-trips are structural, not textual — comments,
+* blank lines, and line order of an existing file are not preserved,
+* and a string that parses as another type (e.g. '123') reads back as
+* that type.
+*/
+var ConfWriter = class extends TextFileWriter {
+	stringify(value) {
+		if (!isObject(value)) throw new Error("The value must be an object for the conf format.");
+		const flat = flatten(value, { safe: true });
+		const lines = [];
+		for (const key of Object.keys(flat)) {
+			const entry = flat[key];
+			if (typeof entry === "undefined") continue;
+			if (Array.isArray(entry)) {
+				for (const item of entry) lines.push(`${key}[]=${serializeValue(item)}`);
+				continue;
+			}
+			lines.push(`${key}=${serializeValue(entry)}`);
 		}
+		return lines.join("\n");
 	}
-	executeSync(input) {
-		const filePath = buildFilePath(input);
-		try {
-			const file = fs.readFileSync(filePath, { encoding: "utf-8" });
-			return JSON.parse(file);
-		} catch (e) {
-			throw wrapLoaderError(e, filePath);
-		}
+};
+//#endregion
+//#region src/format/built-in/json/reader.ts
+var JSONReader = class extends TextFileReader {
+	parse(content) {
+		return JSON.parse(content);
 	}
 };
 //#endregion
-//#region src/loader/built-in/module/utils.ts
-function isESModule(input) {
-	return isObject(input) && typeof input.__esModule !== "undefined";
+//#region src/format/built-in/json/writer.ts
+function detectIndent(content) {
+	const match = /^([ \t]+)\S/m.exec(content);
+	return match ? match[1] : void 0;
 }
-function toModuleRecord(data) {
-	if (isESModule(data)) {
-		if (isESModule(data.default) && data.default.default) return {
-			...data,
-			default: data.default.default
-		};
-		return data;
+var JSONWriter = class extends TextFileWriter {
+	options;
+	constructor(options = {}) {
+		super();
+		this.options = options;
 	}
-	const output = Object.create(null, {
-		__esModule: { value: true },
-		[Symbol.toStringTag]: { value: "Module" }
-	});
-	if (isObject(data)) for (const key in data) {
-		if (hasOwnProperty(output, key)) continue;
-		let descriptor = Object.getOwnPropertyDescriptor(data, key);
-		if (!descriptor || "get" in descriptor || descriptor.writable || descriptor.configurable) descriptor = {
-			enumerable: true,
-			get() {
-				return data[key];
-			}
-		};
-		Object.defineProperty(output, key, descriptor);
+	get usesExistingContent() {
+		return this.options.indent === "auto";
 	}
-	if (!hasOwnProperty(output, "default")) Object.defineProperty(output, "default", {
-		value: data,
-		enumerable: true
-	});
-	return Object.freeze(output);
-}
-function getModuleExport(data, filterFn) {
-	const keys = Object.keys(data);
-	for (const key of keys) if (filterFn(key, data[key])) return {
-		key,
-		value: data[key]
-	};
-}
+	stringify(value, existing) {
+		let indent;
+		if (this.options.indent === "auto") indent = existing ? detectIndent(existing) : void 0;
+		else indent = this.options.indent;
+		indent = indent ?? 4;
+		const output = JSON.stringify(value, null, indent);
+		if (typeof output === "undefined") throw new Error("The value is not JSON-serializable.");
+		return output;
+	}
+};
 //#endregion
-//#region src/loader/built-in/module/module.ts
+//#region src/format/built-in/module/constants.ts
+/**
+* Single source of truth for the extensions handled by the module loader:
+* consumed by BOTH the built-in routing registry and the jiti config.
+*/
+const MODULE_FILE_EXTENSIONS = [
+	".js",
+	".mjs",
+	".mts",
+	".cjs",
+	".cts",
+	".ts"
+];
+//#endregion
+//#region src/format/built-in/module/reader.ts
 const require = createRequire(import.meta.url);
 function originalPath(data) {
 	return typeof data === "string" ? data : buildFilePath(data);
@@ -428,46 +517,56 @@ function isUnrecoverableError(error) {
 	const underlying = error instanceof LocterError ? error.cause : error;
 	return underlying instanceof SyntaxError || underlying instanceof ReferenceError || isTypeScriptError(underlying);
 }
-var ModuleLoader = class {
+var ModuleReader = class {
 	instance;
 	loadFn;
 	loadSyncFn;
 	constructor(options = {}) {
-		this.instance = createJiti(void 0, { extensions: [
-			".js",
-			".mjs",
-			".mts",
-			".cjs",
-			".cts",
-			".ts"
-		] });
+		this.instance = createJiti(void 0, { extensions: [...MODULE_FILE_EXTENSIONS] });
 		this.loadFn = options.load;
 		this.loadSyncFn = options.loadSync;
 	}
+	/**
+	* Returns the previous configuration, so callers can restore it.
+	*/
 	configure(options) {
+		const previous = {
+			load: this.loadFn,
+			loadSync: this.loadSyncFn
+		};
 		if ("load" in options) this.loadFn = options.load;
 		if ("loadSync" in options) this.loadSyncFn = options.loadSync;
+		return previous;
 	}
-	async execute(input) {
-		let output;
+	/**
+	* Returns the raw module value (import / require / jiti output) —
+	* normalization to a module record happens once, at the
+	* FormatRegistry boundary.
+	*
+	* read/readSync are deliberately NOT derived from a shared body
+	* (unlike every other sync/async twin in this package): their
+	* recovery paths differ. The async variant falls back to loadSync
+	* under ts-node (jiti's async path does not cooperate with ts-node)
+	* and to the jiti instance otherwise; the sync variant only has the
+	* jiti fallback. The divergence is pinned by the fallback tests in
+	* test/unit/format/module.spec.ts.
+	*/
+	async read(input) {
 		try {
-			output = await this.load(input);
+			return await this.load(input);
 		} catch (e) {
 			if (isUnrecoverableError(e)) throw e;
-			if (isTsNodeRuntimeEnvironment()) output = this.loadSync(input);
-			else output = this.instance(input);
+			if (isTsNodeRuntimeEnvironment()) return this.loadSync(input);
+			return this.instance(input);
 		}
-		return toModuleRecord(output);
 	}
-	executeSync(input) {
-		let output;
+	readSync(input) {
 		try {
-			output = this.loadSync(input);
+			return this.loadSync(input);
 		} catch (e) {
 			if (isUnrecoverableError(e)) throw e;
-			output = this.instance(input);
+			return this.instance(input);
 		}
-		return toModuleRecord(output);
 	}
 	async load(data, options = {}) {
 		const id = this.build(data, options);
@@ -502,233 +601,564 @@ var ModuleLoader = class {
 	}
 };
 //#endregion
-//#region src/loader/built-in/yaml/module.ts
-var YAMLLoader = class {
-	async execute(input) {
-		const filePath = buildFilePath(input);
-		try {
-			return parse(await fs.promises.readFile(filePath, { encoding: "utf-8" }));
-		} catch (e) {
-			throw wrapLoaderError(e, filePath);
+//#region src/format/built-in/module/utils.ts
+/**
+* Brand carried by every record locter's read() produces. Deliberately a
+* module-private Symbol (NOT Symbol.for) so arbitrary parsed data cannot
+* forge it — unlike `__esModule`, its presence is trustworthy. write()
+* uses it to unwrap `.default` on round-trips.
+*/
+const MODULE_RECORD = Symbol("locter.record");
+/**
+* True when the value is a record produced by locter's read()/toModuleRecord.
+* Detection is brand-based; a plain object with an `__esModule` key is NOT
+* a module record.
+*/
+function isModuleRecord(input) {
+	return isObject(input) && MODULE_RECORD in input;
+}
+function brand(input) {
+	if (isObject(input) && Object.isExtensible(input)) Object.defineProperty(input, MODULE_RECORD, { value: true });
+	return input;
+}
+/**
+* Detect the transpiler interop marker (`__esModule`). Only meaningful for
+* values that came out of a module system — arbitrary parsed data can carry
+* an `__esModule` key without being a module, so callers must decide by
+* provenance whether this check applies (see FormatRegistry).
+*/
+function isESModule(input) {
+	return isObject(input) && typeof input.__esModule !== "undefined";
+}
+/**
+* Wrap an arbitrary value in a frozen module record: enumerable keys are
+* re-exposed as named exports and `default` is the value itself.
+*/
+function createModuleRecord(data) {
+	const output = Object.create(null, {
+		__esModule: { value: true },
+		[Symbol.toStringTag]: { value: "Module" },
+		[MODULE_RECORD]: { value: true }
+	});
+	if (isObject(data)) for (const key in data) {
+		if (hasOwnProperty(output, key)) continue;
+		let descriptor = Object.getOwnPropertyDescriptor(data, key);
+		if (!descriptor || "get" in descriptor || descriptor.writable || descriptor.configurable) descriptor = {
+			enumerable: true,
+			get() {
+				return data[key];
+			}
+		};
+		Object.defineProperty(output, key, descriptor);
+	}
+	if (!hasOwnProperty(output, "default")) Object.defineProperty(output, "default", {
+		value: data,
+		enumerable: true
+	});
+	return Object.freeze(output);
+}
+/**
+* Normalize module-loader output to a module record. Values already carrying
+* the `__esModule` marker pass through (module provenance makes the marker
+* trustworthy); everything else is wrapped via createModuleRecord.
+*
+* https://2ality.com/2017/01/babel-esm-spec-mode.html
+*/
+function toModuleRecord(data) {
+	if (isESModule(data)) {
+		if (isESModule(data.default) && data.default.default) return brand({
+			...data,
+			default: data.default.default
+		});
+		return brand(data);
+	}
+	return createModuleRecord(data);
+}
+function getModuleExport(data, filterFn) {
+	const keys = Object.keys(data);
+	for (const key of keys) if (filterFn(key, data[key])) return {
+		key,
+		value: data[key]
+	};
+}
+//#endregion
+//#region src/format/built-in/yaml/reader.ts
+var YAMLReader = class extends TextFileReader {
+	parse(content) {
+		return parse(content);
+	}
+};
+//#endregion
+//#region src/format/built-in/yaml/writer.ts
+function pairKey(key) {
+	return isScalar(key) ? String(key.value) : String(key);
+}
+/**
+* Merge a plain object into an existing YAML map node: added/changed keys
+* are set, absent keys are deleted, and nested objects recurse — so
+* comments, anchors, and formatting attached to surviving keys are
+* preserved. Arrays, scalars, and type changes replace the node wholesale
+* (comments inside the replaced subtree are lost).
+*/
+function graftMap(doc, node, value) {
+	for (const pair of [...node.items]) if (!hasOwnProperty(value, pairKey(pair.key))) node.delete(pair.key);
+	for (const key of Object.keys(value)) {
+		const entry = value[key];
+		const current = node.get(key, true);
+		if (isMap(current) && isObject(entry)) {
+			graftMap(doc, current, entry);
+			continue;
+		}
+		const replacement = doc.createNode(entry);
+		if (isNode(current)) {
+			replacement.commentBefore = current.commentBefore;
+			replacement.comment = current.comment;
+			replacement.spaceBefore = current.spaceBefore;
+		}
+		node.set(doc.createNode(key), replacement);
+	}
+}
+/**
+* Writes YAML preserving hand-edited structure where possible: when the
+* target file already exists, the new value is grafted into its parsed
+* document, so comments and anchors attached to surviving keys survive
+* the write-back. New files are plain `yaml.stringify` output. An
+* existing file that fails to parse throws (wrapped as LocterWriteError)
+* instead of being silently overwritten.
+*/
+var YAMLWriter = class extends TextFileWriter {
+	options;
+	constructor(options = {}) {
+		super();
+		this.options = options;
+	}
+	get usesExistingContent() {
+		return true;
+	}
+	stringify(value, existing) {
+		if (typeof existing === "undefined") return stringify(value, this.options);
+		const doc = parseDocument(existing);
+		if (doc.errors.length > 0) throw doc.errors[0];
+		if (isMap(doc.contents) && isObject(value)) graftMap(doc, doc.contents, value);
+		else doc.contents = doc.createNode(value);
+		return doc.toString(this.options);
+	}
+};
+//#endregion
+//#region src/format/built-in/registry.ts
+/**
+* Every built-in format, in one place. Keys are the format ids; each entry
+* couples routing and construction. The id union, the extension → format
+* table, lazy caching, and the typed `builtInReader()` accessor are all
+* DERIVED from this object. Adding a format = adding one entry.
+*
+* Intentionally NOT re-exported from any barrel (internal API).
+*/
+const BUILT_IN_PRESETS = {
+	module: {
+		extensions: MODULE_FILE_EXTENSIONS,
+		reader: () => new ModuleReader()
+	},
+	conf: {
+		extensions: [".conf"],
+		reader: () => new ConfReader(),
+		writer: () => new ConfWriter()
+	},
+	json: {
+		extensions: [".json"],
+		reader: () => new JSONReader(),
+		writer: () => new JSONWriter()
+	},
+	yaml: {
+		extensions: [".yml", ".yaml"],
+		reader: () => new YAMLReader(),
+		writer: () => new YAMLWriter()
+	}
+};
+//#endregion
+//#region src/format/registry/module.ts
+function compileSlot(slot) {
+	if (typeof slot === "undefined") return;
+	if (typeof slot !== "function") return () => slot;
+	const factory = slot;
+	let cached;
+	return () => {
+		if (!cached) cached = factory();
+		return cached;
+	};
+}
+var FormatRegistry = class {
+	/**
+	* User rules only — built-ins live in the extension table instead.
+	*/
+	rules;
+	/**
+	* Lazy per-instance cache of built-in reader instances.
+	*/
+	builtInReaderCache;
+	/**
+	* Lazy per-instance cache of built-in writer instances.
+	*/
+	builtInWriterCache;
+	/**
+	* extension → built-in format id, precomputed once from BUILT_IN_PRESETS.
+	*/
+	builtInExtensions;
+	ruleCounter;
+	constructor(options = {}) {
+		this.rules = [];
+		this.builtInReaderCache = /* @__PURE__ */ new Map();
+		this.builtInWriterCache = /* @__PURE__ */ new Map();
+		this.builtInExtensions = /* @__PURE__ */ new Map();
+		this.ruleCounter = 0;
+		const ids = Object.keys(BUILT_IN_PRESETS);
+		for (const id of ids) for (const extension of BUILT_IN_PRESETS[id].extensions) {
+			const existing = this.builtInExtensions.get(extension);
+			if (existing) throw new LocterError({ message: `Extension ${extension} is claimed by two built-in formats: ${existing}, ${id}.` });
+			this.builtInExtensions.set(extension, id);
 		}
+		if (options.rules) for (const rule of options.rules) this.register(rule);
+	}
+	register(rule) {
+		if (typeof rule.id !== "undefined" && hasOwnProperty(BUILT_IN_PRESETS, rule.id)) throw new LocterError({ message: `The id ${rule.id} is reserved by a built-in format.` });
+		if (typeof rule.reader === "undefined" && typeof rule.writer === "undefined") throw new LocterError({ message: "A rule requires at least one of: reader, writer." });
+		const id = rule.id ?? this.generateRuleId();
+		const entry = this.compile(id, rule);
+		const index = this.rules.findIndex((item) => item.id === id);
+		if (index === -1) this.rules.push(entry);
+		else this.rules[index] = entry;
+		return {
+			id,
+			test: rule.test,
+			builtIn: false
+		};
+	}
+	/**
+	* Remove a user-registered rule by id. Built-in ids cannot be
+	* unregistered (returns false).
+	*/
+	unregister(id) {
+		const index = this.rules.findIndex((item) => item.id === id);
+		if (index === -1) return false;
+		this.rules.splice(index, 1);
+		return true;
+	}
+	has(id) {
+		if (this.rules.some((item) => item.id === id)) return true;
+		return hasOwnProperty(BUILT_IN_PRESETS, id);
+	}
+	/**
+	* All registrations in effective match order: user rules
+	* (registration order) first, then the built-ins.
+	*/
+	entries() {
+		const output = this.rules.map((item) => ({
+			id: item.id,
+			test: item.test,
+			builtIn: false
+		}));
+		const ids = Object.keys(BUILT_IN_PRESETS);
+		for (const id of ids) output.push({
+			id,
+			test: [...BUILT_IN_PRESETS[id].extensions],
+			builtIn: true
+		});
+		return output;
+	}
+	/**
+	* Restore the registry to its construction state: drop all user rules
+	* and evict every cached reader instance (including a module reader
+	* configured via setModuleReader / configure).
+	*/
+	reset() {
+		this.rules = [];
+		this.builtInReaderCache.clear();
+		this.builtInWriterCache.clear();
+		this.ruleCounter = 0;
+	}
+	async read(input) {
+		return runTwinAsync(this.readBody(input));
 	}
-	executeSync(input) {
+	readSync(input) {
+		return runTwinSync(this.readBody(input));
+	}
+	/**
+	* Shared body of read/readSync: dispatch, read, normalize, wrap.
+	*/
+	*readBody(input) {
 		const filePath = buildFilePath(input);
+		const reader = this.findReader(filePath);
+		if (!reader) throw this.unknownExtensionError(filePath);
 		try {
-			return parse(fs.readFileSync(filePath, { encoding: "utf-8" }));
+			const output = yield* op(() => reader.read(filePath), () => reader.readSync(filePath));
+			return this.toRecord(output, reader);
 		} catch (e) {
 			throw wrapLoaderError(e, filePath);
 		}
 	}
-};
-//#endregion
-//#region src/loader/module.ts
-var LoaderManager = class {
-	loaders;
-	rules;
-	constructor() {
-		this.loaders = {};
-		this.rules = [
-			{
-				test: [
-					".js",
-					".mjs",
-					".mts",
-					".cjs",
-					".cts",
-					".ts"
-				],
-				loader: "module"
-			},
-			{
-				test: [".conf"],
-				loader: "conf"
-			},
-			{
-				test: [".json"],
-				loader: "json"
-			},
-			{
-				test: [".yml", ".yaml"],
-				loader: "yaml"
-			}
-		];
+	async write(input, value) {
+		return runTwinAsync(this.writeBody(input, value));
+	}
+	writeSync(input, value) {
+		runTwinSync(this.writeBody(input, value));
 	}
-	register(test, loader) {
-		if (typeof loader !== "undefined") {
-			this.rules.push({
-				test,
-				loader
+	/**
+	* Shared body of write/writeSync: dispatch, unwrap records, write, wrap.
+	* The inverse boundary of readBody: a record produced by read() (brand
+	* detected) is unwrapped to its `.default` value; anything else is
+	* written as-is.
+	*/
+	*writeBody(input, value) {
+		const filePath = buildFilePath(input);
+		if (!isFilePath(filePath)) throw new LocterWriteError({
+			message: `Cannot write to a bare module specifier: ${filePath}`,
+			path: filePath
+		});
+		const writer = this.findWriter(filePath);
+		if (!writer) {
+			if (this.findReader(filePath)) throw new LocterWriteError({
+				message: `The format of extension ${pathToLocatorInfo(filePath).extension} is read-only.`,
+				path: filePath
 			});
-			return;
+			throw this.unknownExtensionError(filePath);
 		}
-		this.rules.push(test);
-	}
-	async execute(input) {
-		const id = this.findLoader(input);
-		if (!id) throw this.unknownExtensionError(input);
-		const loader = this.resolve(id);
+		const plain = isModuleRecord(value) ? value.default : value;
 		try {
-			return await loader.execute(input);
+			yield* op(() => writer.write(filePath, plain), () => writer.writeSync(filePath, plain));
 		} catch (e) {
-			throw wrapLoaderError(e, input);
+			throw wrapWriteError(e, filePath);
 		}
 	}
-	executeSync(input) {
-		const id = this.findLoader(input);
-		if (!id) throw this.unknownExtensionError(input);
-		const loader = this.resolve(id);
-		try {
-			return loader.executeSync(input);
-		} catch (e) {
-			throw wrapLoaderError(e, input);
+	/**
+	* The single normalization boundary: every read result becomes a module
+	* record (`.default` is always the loaded value, top-level keys stay
+	* accessible as named exports). Provenance decides how: module-reader
+	* output may legitimately already be a record (`__esModule` is meaningful
+	* there); any other reader returns arbitrary parsed data, which is always
+	* wrapped — even if it happens to contain an `__esModule` key.
+	*/
+	toRecord(output, reader) {
+		if (reader instanceof ModuleReader) return toModuleRecord(output);
+		return createModuleRecord(output);
+	}
+	/**
+	* Typed accessor for the LIVE built-in reader instance (lazy, cached).
+	*/
+	builtInReader(id) {
+		let reader = this.builtInReaderCache.get(id);
+		if (!reader) {
+			reader = BUILT_IN_PRESETS[id].reader();
+			this.builtInReaderCache.set(id, reader);
 		}
+		return reader;
 	}
-	unknownExtensionError(input) {
-		return new LocterUnknownExtensionError({
-			message: `No loader registered for extension: ${pathToLocatorInfo(input).extension ?? "unknown"}`,
-			path: input
-		});
+	/**
+	* Typed accessor for the LIVE built-in writer instance (lazy, cached).
+	* Only writable format ids are accepted — read-only formats (module)
+	* are a compile error.
+	*/
+	builtInWriter(id) {
+		let writer = this.builtInWriterCache.get(id);
+		if (!writer) {
+			writer = BUILT_IN_PRESETS[id].writer();
+			this.builtInWriterCache.set(id, writer);
+		}
+		return writer;
+	}
+	/**
+	* Dispatch order:
+	*   1. bare specifier (no extension)  → module reader, always
+	*   2. user rules, registration order → first match wins (can override built-ins)
+	*   3. built-in extension table
+	*   4. undefined → read/readSync throw LocterUnknownExtensionError
+	*/
+	findReader(input) {
+		if (!isFilePath(input)) return this.builtInReader("module");
+		const rule = this.findRule(input, (item) => typeof item.getReader !== "undefined");
+		if (rule && rule.getReader) return rule.getReader();
+		const id = this.findBuiltInId(input);
+		if (id) return this.builtInReader(id);
 	}
-	findLoader(input) {
-		if (!isFilePath(input)) return "module";
+	/**
+	* Write-side dispatch. No bare-specifier step (there is nothing to
+	* write to); only rules with a writer slot participate, then built-in
+	* presets that declare a writer.
+	*/
+	findWriter(input) {
+		if (!isFilePath(input)) return;
+		const rule = this.findRule(input, (item) => typeof item.getWriter !== "undefined");
+		if (rule && rule.getWriter) return rule.getWriter();
+		const id = this.findBuiltInId(input);
+		if (id && "writer" in BUILT_IN_PRESETS[id]) return this.builtInWriter(id);
+	}
+	findRule(input, filter) {
 		const info = pathToLocatorInfo(input);
 		for (const rule of this.rules) {
+			if (!filter(rule)) continue;
 			const { test } = rule;
 			if (Array.isArray(test)) {
-				if (info.extension && test.includes(info.extension)) return rule.loader;
-			} else if (test.test(buildFilePath(info))) return rule.loader;
-		}
-	}
-	/**
-	* Resolve loader by id.
-	*
-	* @param id
-	*/
-	resolve(id) {
-		if (typeof id !== "string") return id;
-		if (Object.prototype.hasOwnProperty.call(this.loaders, id)) return this.loaders[id];
-		let loader;
-		switch (id) {
-			case "conf":
-				loader = new ConfLoader();
-				break;
-			case "module":
-				loader = new ModuleLoader();
-				break;
-			case "json":
-				loader = new JSONLoader();
-				break;
-			case "yaml":
-				loader = new YAMLLoader();
-				break;
-			/* istanbul ignore next */
-			default: {
-				const pluginPath = this.normalizePath(id);
-				loader = this.resolve("module").executeSync(pluginPath);
-				break;
+				if (info.extension && test.includes(info.extension)) return rule;
+			} else {
+				test.lastIndex = 0;
+				const matched = test.test(buildFilePath(info));
+				test.lastIndex = 0;
+				if (matched) return rule;
 			}
 		}
-		if (typeof loader !== "undefined") {
-			this.loaders[id] = loader;
-			return loader;
-		}
-		throw new LocterError({ message: `The loader ${id} could not be resolved.` });
 	}
-	/* istanbul ignore next */
-	normalizePath(input) {
-		if (path.isAbsolute(input) || input.startsWith("./")) return input;
-		if (input.startsWith("module:")) return input.substring(0, 7);
-		if (!input.startsWith("@")) return `@locter/${input}`;
-		return input;
+	findBuiltInId(input) {
+		const info = pathToLocatorInfo(input);
+		if (!info.extension) return;
+		return this.builtInExtensions.get(info.extension);
+	}
+	unknownExtensionError(input) {
+		return new LocterUnknownExtensionError({
+			message: `No format registered for extension: ${pathToLocatorInfo(input).extension ?? "unknown"}`,
+			path: input
+		});
+	}
+	compile(id, rule) {
+		return {
+			id,
+			test: rule.test,
+			getReader: compileSlot(rule.reader),
+			getWriter: compileSlot(rule.writer)
+		};
+	}
+	generateRuleId() {
+		let id;
+		do {
+			this.ruleCounter++;
+			id = `rule:${this.ruleCounter}`;
+		} while (this.rules.some((item) => item.id === id));
+		return id;
 	}
 };
 //#endregion
-//#region src/loader/singleton.ts
+//#region src/format/registry/singleton.ts
 let instance;
-function useLoader() {
+function useFormatRegistry() {
 	if (typeof instance !== "undefined") return instance;
-	instance = new LoaderManager();
+	instance = new FormatRegistry();
 	return instance;
 }
 //#endregion
-//#region src/loader/helpers.ts
-function registerLoader(test, loader) {
-	const manager = useLoader();
-	if (typeof loader !== "undefined") {
-		manager.register(test, loader);
-		return;
-	}
-	manager.register(test);
+//#region src/format/helpers.ts
+function registerFormat(rule) {
+	return useFormatRegistry().register(rule);
+}
+/**
+* Remove a rule from the process-global registry by its id
+* (as returned by registerFormat). Built-in ids cannot be unregistered.
+*/
+function unregisterFormat(id) {
+	return useFormatRegistry().unregister(id);
 }
-async function load(input) {
-	const manager = useLoader();
-	if (typeof input === "string") return manager.execute(input);
-	return manager.execute(buildFilePath(input));
+async function read(input) {
+	return useFormatRegistry().read(input);
 }
-function loadSync(input) {
-	const manager = useLoader();
-	if (typeof input === "string") return manager.executeSync(input);
-	return manager.executeSync(buildFilePath(input));
+function readSync(input) {
+	return useFormatRegistry().readSync(input);
+}
+async function write(input, value) {
+	return useFormatRegistry().write(input, value);
+}
+function writeSync(input, value) {
+	useFormatRegistry().writeSync(input, value);
 }
 /**
-* Override the built-in module loader's `import` / `require` calls.
+* Override the built-in module reader's `import` / `require` calls.
 *
 * Useful for test runners (e.g. Vitest) where the dynamic `import()` inside
 * `node_modules/locter` would bypass the runner's module graph. Calling this
 * from user code (e.g. a Vitest setup file) lets the runner rewrite the
 * `import()` so loaded modules share identity with statically imported ones.
 *
+* Returns a restore function that re-applies the previous configuration —
+* handy for scoped overrides (e.g. test teardown). The restore function is
+* scoped to the exact reader instance it configured: after a registry
+* reset() (which discards that instance) it becomes a no-op instead of
+* re-applying stale configuration to the fresh instance.
+*
 * @example
 * ```ts
 * // vitest setup file
-* import { setModuleLoader } from 'locter';
+* import { setModuleReader } from 'locter';
 *
-* setModuleLoader({
+* setModuleReader({
 *     load: (id) => import(id),
 * });
 * ```
 */
-function setModuleLoader(options) {
-	useLoader().resolve("module").configure(options);
+function setModuleReader(options) {
+	const reader = useFormatRegistry().builtInReader("module");
+	const previous = reader.configure(options);
+	return () => {
+		reader.configure(previous);
+	};
 }
 //#endregion
-//#region src/loader/package-field.ts
+//#region src/format/package-field.ts
 function extractField(pkg, field) {
 	if (!isObject(pkg) || !hasOwnProperty(pkg, field)) return;
 	return pkg[field];
 }
-async function loadPackageField(field, options = {}) {
-	let info;
-	if (options.walkUp) info = await locateUp("package.json", {
+function* locatePackageBody(options) {
+	if (options.walkUp) return yield* op(() => locateUp("package.json", {
 		cwd: options.cwd,
 		stopAt: options.stopAt
-	});
-	else info = await locate("package.json", { cwd: options.cwd });
-	if (!info) return;
-	try {
-		return extractField(await load(info), field);
-	} catch (e) {
-		if (e instanceof LocterNotFoundError) return;
-		throw e;
-	}
-}
-function loadPackageFieldSync(field, options = {}) {
-	let info;
-	if (options.walkUp) info = locateUpSync("package.json", {
+	}), () => locateUpSync("package.json", {
 		cwd: options.cwd,
 		stopAt: options.stopAt
-	});
-	else info = locateSync("package.json", { cwd: options.cwd });
+	}));
+	return yield* op(() => locate("package.json", { cwd: options.cwd }), () => locateSync("package.json", { cwd: options.cwd }));
+}
+function* readPackageFieldBody(field, options) {
+	const info = yield* locatePackageBody(options);
 	if (!info) return;
+	const reader = useFormatRegistry().builtInReader("json");
+	const filePath = buildFilePath(info);
 	try {
-		return extractField(loadSync(info), field);
+		return extractField(yield* op(() => reader.read(filePath), () => reader.readSync(filePath)), field);
 	} catch (e) {
 		if (e instanceof LocterNotFoundError) return;
 		throw e;
 	}
 }
+async function readPackageField(field, options = {}) {
+	return runTwinAsync(readPackageFieldBody(field, options));
+}
+function readPackageFieldSync(field, options = {}) {
+	return runTwinSync(readPackageFieldBody(field, options));
+}
+function* writePackageFieldBody(field, value, options) {
+	if (!isSafeObjectKey(field)) throw new LocterError({ message: `The field ${field} is not a safe object key.` });
+	const info = yield* locatePackageBody(options);
+	if (!info) throw new LocterNotFoundError({ message: "No package.json could be located." });
+	const reader = useFormatRegistry().builtInReader("json");
+	const filePath = buildFilePath(info);
+	const pkg = yield* op(() => reader.read(filePath), () => reader.readSync(filePath));
+	if (!isObject(pkg)) throw new LocterWriteError({
+		message: "The located package.json does not contain an object.",
+		path: filePath
+	});
+	pkg[field] = value;
+	const writer = new JSONWriter({ indent: "auto" });
+	yield* op(() => writer.write(filePath, pkg), () => writer.writeSync(filePath, pkg));
+}
+/**
+* Set a top-level field of the nearest `package.json` (same locate
+* semantics as readPackageField) and write it back, preserving the
+* file's existing indentation. Passing `undefined` removes the field.
+* Throws LocterNotFoundError when no package.json could be located.
+*/
+async function writePackageField(field, value, options = {}) {
+	return runTwinAsync(writePackageFieldBody(field, value, options));
+}
+function writePackageFieldSync(field, value, options = {}) {
+	runTwinSync(writePackageFieldBody(field, value, options));
+}
 //#endregion
-export { ConfLoader, JSONLoader, LOCTER_ERROR_MARKER, LOCTER_LOAD_ERROR_MARKER, LOCTER_NOT_FOUND_ERROR_MARKER, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER, LoaderManager, LocterError, LocterLoadError, LocterNotFoundError, LocterUnknownExtensionError, ModuleLoader, YAMLLoader, buildFilePath, buildFilePathWithoutExtension, buildLocatorOptions, buildLocatorPatterns, getFileNameExtension, getModuleExport, hasOwnProperty, hasStringProperty, isESModule, isFilePath, isJestRuntimeEnvironment, isLocatorInfo, isObject, isSafeObjectKey, isTsNodeRuntimeEnvironment, isTypeScriptError, isVitestRuntimeEnvironment, load, loadPackageField, loadPackageFieldSync, loadSync, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, pathToLocatorInfo, registerLoader, removeFileNameExtension, setModuleLoader, toArray, toModuleRecord, wrapLoaderError };
+export { ConfReader, ConfWriter, FormatRegistry, JSONReader, JSONWriter, LOCTER_ERROR_MARKER, LOCTER_LOAD_ERROR_MARKER, LOCTER_NOT_FOUND_ERROR_MARKER, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER, LOCTER_WRITE_ERROR_MARKER, LocterError, LocterLoadError, LocterNotFoundError, LocterUnknownExtensionError, LocterWriteError, MODULE_FILE_EXTENSIONS, ModuleReader, TextFileReader, TextFileWriter, YAMLReader, YAMLWriter, buildFilePath, getModuleExport, isJestRuntimeEnvironment, isLocatorInfo, isModuleRecord, isTsNodeRuntimeEnvironment, isTsxRuntimeEnvironment, isVitestRuntimeEnvironment, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, read, readPackageField, readPackageFieldSync, readSync, registerFormat, setModuleReader, unregisterFormat, useFormatRegistry, wrapLoaderError, wrapWriteError, write, writePackageField, writePackageFieldSync, writeSync };
 
 //# sourceMappingURL=index.mjs.map