locter 2.2.1 → 4.0.0-beta.0

package/dist/index.mjs

@@ -1,718 +1,1164 @@
-import { destr } from 'destr';
-import flat from 'flat';
-import fs from 'node:fs';
-import fg from 'fast-glob';
-import path from 'node:path';
-import { BaseError } from 'ebec';
-import { createJiti } from 'jiti';
-import { pathToFileURL } from 'node:url';
-import { parse } from 'yaml';
-
-
-// -- Shims --
-import cjsUrl from 'node:url';
-import cjsPath from 'node:path';
-import cjsModule from 'node:module';
-const __filename = cjsUrl.fileURLToPath(import.meta.url);
-const __dirname = cjsPath.dirname(__filename);
-const require = cjsModule.createRequire(import.meta.url);
+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 { flatten, unflatten } from "flat";
+import fs from "node:fs";
+import { createJiti } from "jiti";
+import { pathToFileURL } from "node:url";
+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 {
+	static [Symbol.hasInstance](input) {
+		return hasInstanceof(input, LOCTER_ERROR_MARKER);
+	}
+	path;
+	constructor(input = {}) {
+		if (typeof input === "string") super(input);
+		else {
+			const { path, ...rest } = input;
+			super(rest);
+			this.path = path;
+		}
+		markInstanceof(this, LOCTER_ERROR_MARKER);
+	}
+};
+//#endregion
+//#region src/errors/load.ts
+const LOCTER_LOAD_ERROR_MARKER = Symbol.for("@locter/load-error");
+var LocterLoadError = class extends LocterError {
+	static [Symbol.hasInstance](input) {
+		return hasInstanceof(input, LOCTER_LOAD_ERROR_MARKER);
+	}
+	constructor(input = {}) {
+		super(input);
+		markInstanceof(this, LOCTER_LOAD_ERROR_MARKER);
+	}
+};
+//#endregion
+//#region src/errors/not-found.ts
+const LOCTER_NOT_FOUND_ERROR_MARKER = Symbol.for("@locter/not-found-error");
+var LocterNotFoundError = class extends LocterError {
+	static [Symbol.hasInstance](input) {
+		return hasInstanceof(input, LOCTER_NOT_FOUND_ERROR_MARKER);
+	}
+	constructor(input = {}) {
+		super(input);
+		markInstanceof(this, LOCTER_NOT_FOUND_ERROR_MARKER);
+	}
+};
+//#endregion
+//#region src/errors/unknown-extension.ts
+const LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER = Symbol.for("@locter/unknown-extension-error");
+var LocterUnknownExtensionError = class extends LocterError {
+	static [Symbol.hasInstance](input) {
+		return hasInstanceof(input, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER);
+	}
+	constructor(input = {}) {
+		super(input);
+		markInstanceof(this, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER);
+	}
+};
+//#endregion
+//#region src/utils/has-property.ts
 function hasOwnProperty(obj, prop) {
-    return Object.prototype.hasOwnProperty.call(obj, prop);
+	return Object.prototype.hasOwnProperty.call(obj, prop);
 }
 function hasStringProperty(obj, prop) {
-    return hasOwnProperty(obj, prop) && typeof obj[prop] === 'string';
+	return hasOwnProperty(obj, prop) && typeof obj[prop] === "string";
 }
-
-/*
- * Copyright (c) 2022.
- * Author Peter Placzek (tada5hi)
- * For the full copyright and license information,
- * view the LICENSE file that was distributed with this source code.
- */ function isObject(item) {
-    return !!item && typeof item === 'object' && !Array.isArray(item);
+//#endregion
+//#region src/utils/object.ts
+function isObject(item) {
+	return !!item && typeof item === "object" && !Array.isArray(item);
 }
 function isSafeObjectKey(key) {
-    return key !== '__proto__' && key !== 'prototype' && key !== 'constructor';
-}
-
-function handleException(e) {
-    if (e instanceof Error) {
-        throw e;
-    }
-    const error = new Error('Can not process thrown exception.');
-    if (isObject(e)) {
-        if (hasOwnProperty(e, 'message') && typeof e.message === 'string') {
-            error.message = e.message;
-        }
-        if (hasOwnProperty(e, 'stack') && typeof e.stack === 'string') {
-            error.stack = e.stack;
-        }
-    }
-    throw error;
-}
-
-function getFileNameExtension(input, allowed) {
-    const extension = path.extname(input);
-    if (extension === '' || extension === '.') {
-        return undefined;
-    }
-    if (typeof allowed === 'undefined' || allowed.indexOf(extension) !== -1) {
-        return extension;
-    }
-    return undefined;
-}
-function removeFileNameExtension(input, extensions) {
-    const extension = getFileNameExtension(input, extensions);
-    if (extension) {
-        return input.substring(0, input.length - extension.length);
-    }
-    return input;
+	return key !== "__proto__" && key !== "prototype" && key !== "constructor";
 }
-
-/*
- * Copyright (c) 2022.
- * Author Peter Placzek (tada5hi)
- * For the full copyright and license information,
- * view the LICENSE file that was distributed with this source code.
- */ function toArray(input) {
-    return Array.isArray(input) ? input : [
-        input
-    ];
+//#endregion
+//#region src/utils/to-array.ts
+function toArray(input) {
+	return Array.isArray(input) ? input : [input];
 }
-
+//#endregion
+//#region src/utils/file-path.ts
 function isFilePath(input) {
-    const extension = path.extname(input);
-    return extension && extension !== '';
+	const extension = path.extname(input);
+	return extension && extension !== "";
 }
-
-/*
- * Copyright (c) 2024.
- * Author Peter Placzek (tada5hi)
- * For the full copyright and license information,
- * view the LICENSE file that was distributed with this source code.
- */ function isJestRuntimeEnvironment() {
-    return process.env && process.env.JEST_WORKER_ID !== undefined;
+//#endregion
+//#region src/utils/runtime.ts
+function isJestRuntimeEnvironment() {
+	return process.env && process.env.JEST_WORKER_ID !== void 0;
+}
+function isVitestRuntimeEnvironment() {
+	return typeof process !== "undefined" && process.env.VITEST === "true";
 }
 function isTsNodeRuntimeEnvironment() {
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    return !!process[Symbol.for('ts-node.register.instance')];
+	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) {
-    if (!isObject(input)) {
-        return false;
-    }
-    if (typeof input.diagnosticCodes !== 'undefined') {
-        return true;
-    }
-    return typeof input.message === 'string' && /TS\d+/.test(input.message);
+	if (!isObject(input)) return false;
+	if (typeof input.diagnosticCodes !== "undefined") return true;
+	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 = /* @__PURE__ */ new Set([
+	"ENOENT",
+	"MODULE_NOT_FOUND",
+	"ERR_MODULE_NOT_FOUND"
+]);
+function wrapLoaderError(input, path) {
+	if (input instanceof LocterError) return input;
+	const code = isObject(input) && hasStringProperty(input, "code") ? input.code : void 0;
+	const message = isObject(input) && hasStringProperty(input, "message") ? input.message : `Failed to load: ${path}`;
+	if (code && NOT_FOUND_CODES.has(code)) return new LocterNotFoundError({
+		message,
+		code,
+		cause: input,
+		path
+	});
+	return new LocterLoadError({
+		message,
+		code,
+		cause: input,
+		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) {
-    return Array.isArray(pattern) ? pattern : [
-        pattern
-    ];
+	return Array.isArray(pattern) ? pattern : [pattern];
 }
 function buildLocatorOptions(options = {}) {
-    const paths = options.path ? toArray(options.path) : [];
-    const ignore = options.ignore ? toArray(options.ignore) : [];
-    if (paths.length === 0) {
-        paths.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;
-    }
-    return {
-        path: paths,
-        ignore,
-        onlyDirectories,
-        onlyFiles
-    };
+	const cwd = options.cwd ? toArray(options.cwd) : [];
+	const ignore = options.ignore ? toArray(options.ignore) : [];
+	if (cwd.length === 0) cwd.push(process.cwd());
+	const onlyDirectories = options.onlyDirectories ?? false;
+	return {
+		cwd,
+		ignore,
+		onlyDirectories,
+		onlyFiles: onlyDirectories ? false : options.onlyFiles ?? true,
+		dot: options.dot ?? false
+	};
 }
 function pathToLocatorInfo(input, skipResolve) {
-    if (!skipResolve && !path.isAbsolute(input)) {
-        input = path.resolve(process.cwd(), input);
-    }
-    const info = path.parse(input);
-    return {
-        path: info.dir.split('/').join(path.sep),
-        name: info.name,
-        extension: info.ext ? info.ext : undefined
-    };
+	if (!skipResolve && !path.isAbsolute(input)) input = path.resolve(process.cwd(), input);
+	const info = path.parse(input);
+	const directory = info.dir.split("/").join(path.sep);
+	const extension = info.ext ? info.ext : void 0;
+	const filePath = extension ? path.join(directory, info.name) + extension : path.join(directory, info.name);
+	return {
+		directory,
+		name: info.name,
+		extension,
+		path: filePath
+	};
 }
 function isLocatorInfo(input) {
-    return isObject(input) && typeof input.path === 'string' && typeof input.name === 'string' && typeof input.extension === 'string';
+	return isObject(input) && typeof input.directory === "string" && typeof input.name === "string" && (typeof input.extension === "undefined" || typeof input.extension === "string") && typeof input.path === "string";
 }
 function buildFilePath(input) {
-    if (typeof input === 'string') {
-        return input;
-    }
-    if (input.extension) {
-        return path.join(input.path, input.name) + input.extension;
-    }
-    return path.join(input.path, input.name);
-}
-function buildFilePathWithoutExtension(input) {
-    let info;
-    if (typeof input === 'string') {
-        info = pathToLocatorInfo(input);
-    } else {
-        info = input;
-    }
-    return path.join(info.path, info.name);
+	if (typeof input === "string") return input;
+	return input.path;
 }
-
+//#endregion
+//#region src/locator/core.ts
+function buildGlobJobs(pattern, options) {
+	const patterns = buildLocatorPatterns(pattern);
+	const opts = buildLocatorOptions(options);
+	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) {
-    const patterns = buildLocatorPatterns(pattern);
-    const opts = buildLocatorOptions(options);
-    const items = [];
-    for(let i = 0; i < patterns.length; i++){
-        for(let j = 0; j < opts.path.length; j++){
-            const files = await fg(patterns[i], {
-                absolute: true,
-                cwd: opts.path[j],
-                ignore: opts.ignore,
-                onlyFiles: opts.onlyFiles,
-                onlyDirectories: opts.onlyDirectories
-            });
-            for(let k = 0; k < files.length; k++){
-                items.push(pathToLocatorInfo(files[k], true));
-            }
-        }
-    }
-    return items;
+	return runTwinAsync(locateManyBody(pattern, options));
 }
 async function locate(pattern, options) {
-    const patterns = buildLocatorPatterns(pattern);
-    const opts = buildLocatorOptions(options);
-    for(let i = 0; i < patterns.length; i++){
-        for(let j = 0; j < opts.path.length; j++){
-            const files = await fg(patterns[i], {
-                absolute: true,
-                cwd: opts.path[j],
-                ignore: opts.ignore,
-                onlyFiles: opts.onlyFiles,
-                onlyDirectories: opts.onlyDirectories
-            });
-            const element = files.shift();
-            if (element) {
-                return pathToLocatorInfo(element, true);
-            }
-        }
-    }
-    return undefined;
+	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(let i = 0; i < patterns.length; i++){
-        for(let j = 0; j < opts.path.length; j++){
-            const files = fg.sync(patterns[i], {
-                absolute: true,
-                cwd: opts.path[j],
-                ignore: opts.ignore,
-                onlyFiles: opts.onlyFiles,
-                onlyDirectories: opts.onlyDirectories
-            });
-            for(let k = 0; k < files.length; k++){
-                items.push(pathToLocatorInfo(files[k], true));
-            }
-        }
-    }
-    return items;
+	return runTwinSync(locateManyBody(pattern, options));
 }
 function locateSync(pattern, options) {
-    const patterns = buildLocatorPatterns(pattern);
-    const opts = buildLocatorOptions(options);
-    for(let i = 0; i < patterns.length; i++){
-        for(let j = 0; j < opts.path.length; j++){
-            const files = fg.sync(patterns[i], {
-                absolute: true,
-                cwd: opts.path[j],
-                ignore: opts.ignore,
-                onlyFiles: opts.onlyFiles,
-                onlyDirectories: opts.onlyDirectories
-            });
-            const element = files.shift();
-            if (element) {
-                return pathToLocatorInfo(element, true);
-            }
-        }
-    }
-    return undefined;
+	return runTwinSync(locateBody(pattern, options));
 }
-
-/*
- * Copyright (c) 2022-2023.
- * Author Peter Placzek (tada5hi)
- * For the full copyright and license information,
- * view the LICENSE file that was distributed with this source code.
- */ // Based on https://github.com/unjs/rc9 (MIT)
-class ConfLoader {
-    async execute(input) {
-        const filePath = buildFilePath(input);
-        try {
-            const file = await fs.promises.readFile(filePath, {
-                encoding: 'utf-8'
-            });
-            return this.parse(file);
-        } catch (e) {
-            return handleException(e);
-        }
-    }
-    executeSync(input) {
-        const filePath = buildFilePath(input);
-        try {
-            const file = fs.readFileSync(filePath, {
-                encoding: 'utf-8'
-            });
-            return this.parse(file);
-        } catch (e) {
-            return handleException(e);
-        }
-    }
-    parse(contents) {
-        const config = {};
-        const lines = contents.split(/\n|\r|\r\n/);
-        for(let i = 0; i < lines.length; i++){
-            const match = lines[i].match(/^\s*([^\s=]+)\s*=\s*(.*)?\s*$/);
-            if (!match) {
-                continue;
-            }
-            // Key
-            const key = match[1];
-            if (!key || !isSafeObjectKey(key)) {
-                continue;
-            }
-            const value = destr(match[2].trim());
-            if (key.endsWith('[]')) {
-                const arrKey = key.slice(0, Math.max(0, key.length - 2));
-                config[arrKey] = (config[arrKey] || []).concat(value);
-                continue;
-            }
-            config[key] = value;
-        }
-        return flat.unflatten(config, {
-            overwrite: true
-        });
-    }
+//#endregion
+//#region src/locator/up.ts
+function startWalk(options) {
+	const { cwd, stopAt, ...baseOptions } = options;
+	const current = path.resolve(cwd ?? process.cwd());
+	return {
+		current,
+		stopAt: stopAt ? path.resolve(current, stopAt) : path.parse(current).root,
+		baseOptions
+	};
 }
-
+function nextDirectory(current, stopAt) {
+	if (current === stopAt) return;
+	const parent = path.dirname(current);
+	if (parent === current) return;
+	return parent;
+}
+function* locateUpBody(pattern, options) {
+	let walk = startWalk(options);
+	while (true) {
+		const found = yield* locateBody(pattern, {
+			...walk.baseOptions,
+			cwd: walk.current
+		});
+		if (found) return found;
+		const next = nextDirectory(walk.current, walk.stopAt);
+		if (!next) return;
+		walk = {
+			...walk,
+			current: next
+		};
+	}
+}
+async function locateUp(pattern, options = {}) {
+	return runTwinAsync(locateUpBody(pattern, options));
+}
+function locateUpSync(pattern, options = {}) {
+	return runTwinSync(locateUpBody(pattern, options));
+}
+//#endregion
+//#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 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, 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 {
+			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 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/);
+		for (const line of lines) {
+			const match = line.match(/^\s*([^\s=]+)\s*=\s*(.*)?\s*$/);
+			if (!match) continue;
+			const key = match[1];
+			const rawValue = match[2];
+			if (!key || !isSafeObjectKey(key)) continue;
+			const value = destr(rawValue ? rawValue.trim() : "");
+			if (key.endsWith("[]")) {
+				const arrKey = key.slice(0, Math.max(0, key.length - 2));
+				config[arrKey] = (config[arrKey] || []).concat(value);
+				continue;
+			}
+			config[key] = value;
+		}
+		return unflatten(config, { overwrite: true });
+	}
+};
+//#endregion
+//#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");
+	}
+};
+//#endregion
+//#region src/format/built-in/json/reader.ts
+var JSONReader = class extends TextFileReader {
+	parse(content) {
+		return JSON.parse(content);
+	}
+};
+//#endregion
+//#region src/format/built-in/json/writer.ts
+function detectIndent(content) {
+	const match = /^([ \t]+)\S/m.exec(content);
+	return match ? match[1] : void 0;
+}
+var JSONWriter = class extends TextFileWriter {
+	options;
+	constructor(options = {}) {
+		super();
+		this.options = options;
+	}
+	get usesExistingContent() {
+		return this.options.indent === "auto";
+	}
+	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/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);
+}
+function isUnrecoverableError(error) {
+	const underlying = error instanceof LocterError ? error.cause : error;
+	return underlying instanceof SyntaxError || underlying instanceof ReferenceError || isTypeScriptError(underlying);
+}
+var ModuleReader = class {
+	instance;
+	loadFn;
+	loadSyncFn;
+	constructor(options = {}) {
+		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;
+	}
+	/**
+	* 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 {
+			return await this.load(input);
+		} catch (e) {
+			if (isUnrecoverableError(e)) throw e;
+			if (isTsNodeRuntimeEnvironment()) return this.loadSync(input);
+			return this.instance(input);
+		}
+	}
+	readSync(input) {
+		try {
+			return this.loadSync(input);
+		} catch (e) {
+			if (isUnrecoverableError(e)) throw e;
+			return this.instance(input);
+		}
+	}
+	async load(data, options = {}) {
+		const id = this.build(data, options);
+		try {
+			if (this.loadFn) return await this.loadFn(id);
+			if (isJestRuntimeEnvironment()) return require(id);
+			return await import(id);
+		} catch (e) {
+			/* istanbul ignore next */
+			if (!options.withFilePrefix && isObject(e) && hasStringProperty(e, "code") && (e.code === "ERR_UNSUPPORTED_ESM_URL_SCHEME" || e.code === "UNSUPPORTED_ESM_URL_SCHEME")) return this.load(data, {
+				...options,
+				withFilePrefix: true
+			});
+			throw wrapLoaderError(e, originalPath(data));
+		}
+	}
+	loadSync(data, options = {}) {
+		const id = this.build(data, options);
+		try {
+			if (this.loadSyncFn) return this.loadSyncFn(id);
+			return require(id);
+		} catch (e) {
+			throw wrapLoaderError(e, originalPath(data));
+		}
+	}
+	build(data, options = {}) {
+		if (isLocatorInfo(data) || isFilePath(data)) {
+			if (typeof data !== "string") data = buildFilePath(data);
+			if (options.withFilePrefix) data = pathToFileURL(data).href;
+		}
+		return data;
+	}
+};
+//#endregion
+//#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) && // eslint-disable-next-line no-underscore-dangle
-    typeof input.__esModule !== 'undefined';
+	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);
 }
-// https://2ality.com/2017/01/babel-esm-spec-mode.html
+/**
+* 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)) {
-        // @see https://github.com/testing-library/user-event/issues/813
-        // @see https://stackoverflow.com/questions/62717394/export-default-class-exports-double-nested-default
-        if (isESModule(data.default) && data.default.default) {
-            return {
-                ...data,
-                default: data.default.default
-            };
-        }
-        return data;
-    }
-    const output = Object.create(null, {
-        __esModule: {
-            value: true
-        },
-        [Symbol.toStringTag]: {
-            value: 'Module'
-        }
-    });
-    if (isObject(data)) {
-        // eslint-disable-next-line no-restricted-syntax
-        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);
+	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(let i = 0; i < keys.length; i++){
-        if (filterFn(keys[i], data[keys[i]])) {
-            return {
-                key: keys[i],
-                value: data[keys[i]]
-            };
-        }
-    }
-    return undefined;
+	const keys = Object.keys(data);
+	for (const key of keys) if (filterFn(key, data[key])) return {
+		key,
+		value: data[key]
+	};
 }
-
-class ModuleLoader {
-    async execute(input) {
-        let output;
-        try {
-            output = await this.load(input);
-        } catch (e) {
-            if (e instanceof SyntaxError || e instanceof ReferenceError || isTypeScriptError(e)) {
-                throw e;
-            }
-            // jiti + ts-node
-            // issue: https://github.com/nuxt/bridge/issues/228
-            if (isTsNodeRuntimeEnvironment()) {
-                output = this.loadSync(input);
-            } else {
-                output = this.instance(input);
-            }
-        }
-        return toModuleRecord(output);
-    }
-    executeSync(input) {
-        let output;
-        try {
-            output = this.loadSync(input);
-        } catch (e) {
-            if (e instanceof SyntaxError || e instanceof ReferenceError || isTypeScriptError(e)) {
-                throw e;
-            }
-            output = this.instance(input);
-        }
-        return toModuleRecord(output);
-    }
-    // ---------------------------------------------------------------------------
-    async load(data, options = {}) {
-        const id = this.build(data, options);
-        try {
-            // segmentation fault
-            // issue: https://github.com/nodejs/node/issues/35889
-            if (isJestRuntimeEnvironment()) {
-                // eslint-disable-next-line global-require,import/no-dynamic-require
-                return require(id);
-            }
-            return await import(id);
-        } catch (e) {
-            /* istanbul ignore next */ if (isObject(e) && hasStringProperty(e, 'code')) {
-                if (!options.withFilePrefix && (e.code === 'ERR_UNSUPPORTED_ESM_URL_SCHEME' || e.code === 'UNSUPPORTED_ESM_URL_SCHEME')) {
-                    return this.load(data, {
-                        ...options,
-                        withFilePrefix: true
-                    });
-                }
-                throw new BaseError({
-                    code: e.code,
-                    message: hasStringProperty(e, 'message') ? e.message : undefined,
-                    stack: hasStringProperty(e, 'stack') ? e.stack : undefined
-                });
-            }
-            /* istanbul ignore next */ return handleException(e);
-        }
-    }
-    loadSync(data, options = {}) {
-        const id = this.build(data, options);
-        try {
-            // eslint-disable-next-line global-require,import/no-dynamic-require
-            return require(id);
-        } catch (e) {
-            /* istanbul ignore next */ if (isObject(e) && hasStringProperty(e, 'code')) {
-                throw new BaseError({
-                    code: e.code,
-                    message: hasStringProperty(e, 'message') ? e.message : undefined,
-                    stack: hasStringProperty(e, 'stack') ? e.stack : undefined
-                });
-            }
-            return handleException(e);
-        }
-    }
-    build(data, options = {}) {
-        if (isLocatorInfo(data) || isFilePath(data)) {
-            if (typeof data !== 'string') {
-                data = buildFilePath(data);
-            }
-            if (options.withFilePrefix) {
-                data = pathToFileURL(data).href;
-            }
-        }
-        return data;
-    }
-    constructor(){
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        this.instance = createJiti(undefined, {
-            extensions: [
-                '.js',
-                '.mjs',
-                '.mts',
-                '.cjs',
-                '.cts',
-                '.ts'
-            ]
-        });
-    }
+//#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);
 }
-
-class JSONLoader {
-    async execute(input) {
-        const filePath = buildFilePath(input);
-        try {
-            const file = await fs.promises.readFile(filePath, {
-                encoding: 'utf-8'
-            });
-            return JSON.parse(file);
-        } catch (e) {
-            return handleException(e);
-        }
-    }
-    executeSync(input) {
-        const filePath = buildFilePath(input);
-        try {
-            const file = fs.readFileSync(filePath, {
-                encoding: 'utf-8'
-            });
-            return JSON.parse(file);
-        } catch (e) {
-            return handleException(e);
-        }
-    }
+/**
+* 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);
+	}
 }
-
-class YAMLLoader {
-    async execute(input) {
-        const filePath = buildFilePath(input);
-        try {
-            const file = await fs.promises.readFile(filePath, {
-                encoding: 'utf-8'
-            });
-            return parse(file);
-        } catch (e) {
-            return handleException(e);
-        }
-    }
-    executeSync(input) {
-        const filePath = buildFilePath(input);
-        try {
-            const file = fs.readFileSync(filePath, {
-                encoding: 'utf-8'
-            });
-            return parse(file);
-        } catch (e) {
-            return handleException(e);
-        }
-    }
+/**
+* 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;
+	};
 }
-
-/*
- * Copyright (c) 2023.
- * Author Peter Placzek (tada5hi)
- * For the full copyright and license information,
- * view the LICENSE file that was distributed with this source code.
- */ var LoaderId = /*#__PURE__*/ function(LoaderId) {
-    LoaderId["MODULE"] = "module";
-    LoaderId["JSON"] = "json";
-    LoaderId["CONF"] = "conf";
-    LoaderId["YAML"] = "yaml";
-    return LoaderId;
-}({});
-
-class LoaderManager {
-    register(test, loader) {
-        if (typeof loader !== 'undefined') {
-            this.rules.push({
-                test,
-                loader
-            });
-            return;
-        }
-        this.rules.push(test);
-    }
-    async execute(input) {
-        const id = this.findLoader(input);
-        if (!id) {
-            const info = pathToLocatorInfo(input);
-            throw new Error(`No loader registered for extension: "${info.extension}"`);
-        }
-        const loader = this.resolve(id);
-        return loader.execute(input);
-    }
-    executeSync(input) {
-        const id = this.findLoader(input);
-        if (!id) {
-            const info = pathToLocatorInfo(input);
-            throw new Error(`No loader registered for extension: ${info.extension || 'unknown'}`);
-        }
-        const loader = this.resolve(id);
-        return loader.executeSync(input);
-    }
-    findLoader(input) {
-        if (!isFilePath(input)) {
-            return LoaderId.MODULE;
-        }
-        const info = pathToLocatorInfo(input);
-        for(let i = 0; i < this.rules.length; i++){
-            const { test } = this.rules[i];
-            if (Array.isArray(test)) {
-                if (info.extension && test.indexOf(info.extension) !== -1) {
-                    return this.rules[i].loader;
-                }
-            } else if (test.test(buildFilePath(info))) {
-                return this.rules[i].loader;
-            }
-        }
-        return undefined;
-    }
-    /**
-     * 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;
-        // built-in
-        switch(id){
-            case LoaderId.CONF:
-                {
-                    loader = new ConfLoader();
-                    break;
-                }
-            case LoaderId.MODULE:
-                {
-                    loader = new ModuleLoader();
-                    break;
-                }
-            case LoaderId.JSON:
-                {
-                    loader = new JSONLoader();
-                    break;
-                }
-            case LoaderId.YAML:
-                {
-                    loader = new YAMLLoader();
-                    break;
-                }
-            /* istanbul ignore next */ default:
-                {
-                    const pluginPath = this.normalizePath(id);
-                    const moduleLoader = this.resolve(LoaderId.MODULE);
-                    loader = moduleLoader.executeSync(pluginPath);
-                    break;
-                }
-        }
-        if (typeof loader !== 'undefined') {
-            this.loaders[id] = loader;
-            return loader;
-        }
-        throw new Error(`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, 'module:'.length);
-        }
-        if (!input.startsWith('@')) {
-            return `@locter/${input}`;
-        }
-        return input;
-    }
-    constructor(){
-        this.loaders = {};
-        this.rules = [
-            {
-                test: [
-                    '.js',
-                    '.mjs',
-                    '.mts',
-                    '.cjs',
-                    '.cts',
-                    '.ts'
-                ],
-                loader: LoaderId.MODULE
-            },
-            {
-                test: [
-                    '.conf'
-                ],
-                loader: LoaderId.CONF
-            },
-            {
-                test: [
-                    '.json'
-                ],
-                loader: LoaderId.JSON
-            },
-            {
-                test: [
-                    '.yml',
-                    '.yaml'
-                ],
-                loader: LoaderId.YAML
-            }
-        ];
-    }
-}
-
+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));
+	}
+	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 {
+			const output = yield* op(() => reader.read(filePath), () => reader.readSync(filePath));
+			return this.toRecord(output, reader);
+		} catch (e) {
+			throw wrapLoaderError(e, filePath);
+		}
+	}
+	async write(input, value) {
+		return runTwinAsync(this.writeBody(input, value));
+	}
+	writeSync(input, value) {
+		runTwinSync(this.writeBody(input, value));
+	}
+	/**
+	* 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
+			});
+			throw this.unknownExtensionError(filePath);
+		}
+		const plain = isModuleRecord(value) ? value.default : value;
+		try {
+			yield* op(() => writer.write(filePath, plain), () => writer.writeSync(filePath, plain));
+		} catch (e) {
+			throw wrapWriteError(e, filePath);
+		}
+	}
+	/**
+	* 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;
+	}
+	/**
+	* 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);
+	}
+	/**
+	* 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;
+			} else {
+				test.lastIndex = 0;
+				const matched = test.test(buildFilePath(info));
+				test.lastIndex = 0;
+				if (matched) return rule;
+			}
+		}
+	}
+	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/format/registry/singleton.ts
 let instance;
-function useLoader() {
-    if (typeof instance !== 'undefined') {
-        return instance;
-    }
-    instance = new LoaderManager();
-    return instance;
+function useFormatRegistry() {
+	if (typeof instance !== "undefined") return instance;
+	instance = new FormatRegistry();
+	return instance;
 }
-
-function registerLoader(test, loader) {
-    const manager = useLoader();
-    if (typeof loader !== 'undefined') {
-        manager.register(test, loader);
-        return;
-    }
-    manager.register(test);
-}
-async function load(input) {
-    const manager = useLoader();
-    if (typeof input === 'string') {
-        return manager.execute(input);
-    }
-    return manager.execute(buildFilePath(input));
-}
-function loadSync(input) {
-    const manager = useLoader();
-    if (typeof input === 'string') {
-        return manager.executeSync(input);
-    }
-    return manager.executeSync(buildFilePath(input));
+//#endregion
+//#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 read(input) {
+	return useFormatRegistry().read(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 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 { setModuleReader } from 'locter';
+*
+* setModuleReader({
+*     load: (id) => import(id),
+* });
+* ```
+*/
+function setModuleReader(options) {
+	const reader = useFormatRegistry().builtInReader("module");
+	const previous = reader.configure(options);
+	return () => {
+		reader.configure(previous);
+	};
+}
+//#endregion
+//#region src/format/package-field.ts
+function extractField(pkg, field) {
+	if (!isObject(pkg) || !hasOwnProperty(pkg, field)) return;
+	return pkg[field];
+}
+function* locatePackageBody(options) {
+	if (options.walkUp) return yield* op(() => locateUp("package.json", {
+		cwd: options.cwd,
+		stopAt: options.stopAt
+	}), () => locateUpSync("package.json", {
+		cwd: options.cwd,
+		stopAt: options.stopAt
+	}));
+	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(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 { 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 };
 
-export { ConfLoader, JSONLoader, LoaderManager, ModuleLoader, buildFilePath, buildFilePathWithoutExtension, buildLocatorOptions, buildLocatorPatterns, getFileNameExtension, getModuleExport, handleException, hasOwnProperty, hasStringProperty, isESModule, isFilePath, isJestRuntimeEnvironment, isLocatorInfo, isObject, isSafeObjectKey, isTsNodeRuntimeEnvironment, isTypeScriptError, load, loadSync, locate, locateMany, locateManySync, locateSync, pathToLocatorInfo, registerLoader, removeFileNameExtension, toArray, toModuleRecord };
-//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map