locter 4.0.0 → 4.1.1

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { BaseError, hasInstanceof, markInstanceof } from "@ebec/core";
 import path from "node:path";
+import { op, runTwinAsync, runTwinSync } from "twinop";
 import fg from "fast-glob";
 import { destr } from "destr";
 import { flatten, unflatten } from "flat";
@@ -28,7 +29,7 @@ var LocterError = class extends BaseError {
 //#endregion
 //#region src/errors/load.ts
 const LOCTER_LOAD_ERROR_MARKER = Symbol.for("@locter/load-error");
-var LocterLoadError = class extends LocterError {
+var LoadError = class extends LocterError {
 	static [Symbol.hasInstance](input) {
 		return hasInstanceof(input, LOCTER_LOAD_ERROR_MARKER);
 	}
@@ -40,7 +41,7 @@ var LocterLoadError = class extends LocterError {
 //#endregion
 //#region src/errors/not-found.ts
 const LOCTER_NOT_FOUND_ERROR_MARKER = Symbol.for("@locter/not-found-error");
-var LocterNotFoundError = class extends LocterError {
+var NotFoundError = class extends LocterError {
 	static [Symbol.hasInstance](input) {
 		return hasInstanceof(input, LOCTER_NOT_FOUND_ERROR_MARKER);
 	}
@@ -52,7 +53,7 @@ var LocterNotFoundError = class extends LocterError {
 //#endregion
 //#region src/errors/unknown-extension.ts
 const LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER = Symbol.for("@locter/unknown-extension-error");
-var LocterUnknownExtensionError = class extends LocterError {
+var UnknownExtensionError = class extends LocterError {
 	static [Symbol.hasInstance](input) {
 		return hasInstanceof(input, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER);
 	}
@@ -108,15 +109,29 @@ function isJestRuntimeEnvironment() {
 function isVitestRuntimeEnvironment() {
 	return typeof process !== "undefined" && process.env.VITEST === "true";
 }
+const MODULE_OPTION_REGEX = /^(?:-r|--require|--import|--(?:experimental-)?loader)(?:=(.*))?$/;
+function matchesProcessMarker(regex) {
+	if (typeof process === "undefined") return false;
+	const { execArgv } = process;
+	if (Array.isArray(execArgv)) for (let i = 0; i < execArgv.length; i++) {
+		const arg = execArgv[i];
+		if (typeof arg !== "string") continue;
+		const option = MODULE_OPTION_REGEX.exec(arg);
+		if (!option) continue;
+		const value = typeof option[1] === "string" ? option[1] : execArgv[i + 1];
+		if (typeof value === "string" && regex.test(value)) return true;
+	}
+	const { _preload_modules: preloadModules } = process;
+	return Array.isArray(preloadModules) && preloadModules.some((el) => regex.test(el));
+}
+const TS_NODE_MARKER_REGEX = /(?:^|=|[\\/"'])ts-node(?:$|[\\/"'])/;
 function isTsNodeRuntimeEnvironment() {
-	return !!process[Symbol.for("ts-node.register.instance")];
+	if (process[Symbol.for("ts-node.register.instance")]) return true;
+	return matchesProcessMarker(TS_NODE_MARKER_REGEX);
 }
-const TSX_MARKER_REGEX = /(?:^|=|[\\/])tsx(?:$|[\\/])/;
+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));
+	return matchesProcessMarker(TSX_MARKER_REGEX);
 }
 //#endregion
 //#region src/utils/typescript.ts
@@ -128,7 +143,7 @@ function isTypeScriptError(input) {
 //#endregion
 //#region src/errors/write.ts
 const LOCTER_WRITE_ERROR_MARKER = Symbol.for("@locter/write-error");
-var LocterWriteError = class extends LocterError {
+var WriteError = class extends LocterError {
 	static [Symbol.hasInstance](input) {
 		return hasInstanceof(input, LOCTER_WRITE_ERROR_MARKER);
 	}
@@ -148,13 +163,13 @@ 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({
+	if (code && NOT_FOUND_CODES.has(code)) return new NotFoundError({
 		message,
 		code,
 		cause: input,
 		path
 	});
-	return new LocterLoadError({
+	return new LoadError({
 		message,
 		code,
 		cause: input,
@@ -164,7 +179,7 @@ function wrapLoaderError(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({
+	return new WriteError({
 		message: isObject(input) && hasStringProperty(input, "message") ? input.message : `Failed to write: ${path}`,
 		code,
 		cause: input,
@@ -172,45 +187,6 @@ function wrapWriteError(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];
@@ -372,7 +348,7 @@ function isNotFound(e) {
 * 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 —
+* failures in WriteError. Subclasses implement `stringify` only —
 * both `write` variants are derived from the same body.
 */
 var TextFileWriter = class {
@@ -789,7 +765,7 @@ function graftMap(doc, node, value) {
 * 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)
+* existing file that fails to parse throws (wrapped as WriteError)
 * instead of being silently overwritten.
 */
 var YAMLWriter = class extends TextFileWriter {
@@ -953,12 +929,16 @@ var FormatRegistry = class {
 	* normalized module record — a module IS a record, and the
 	* normalization only irons out the CJS/ESM interop divergence so
 	* both twin variants agree on one shape.
+	*
+	* options.format names a registered format id to use instead of
+	* extension dispatch (e.g. { format: 'text' } reads module source
+	* without evaluating it).
 	*/
-	async read(input) {
-		return runTwinAsync(this.readBody(input));
+	async read(input, options = {}) {
+		return runTwinAsync(this.readBody(input, options));
 	}
-	readSync(input) {
-		return runTwinSync(this.readBody(input));
+	readSync(input, options = {}) {
+		return runTwinSync(this.readBody(input, options));
 	}
 	/**
 	* Read a file/module and present the result as a normalized module
@@ -966,28 +946,30 @@ var FormatRegistry = class {
 	* `.default` always holds the loaded value, top-level keys are
 	* re-exposed as named exports.
 	*/
-	async readAsModule(input) {
-		return runTwinAsync(this.readAsModuleBody(input));
+	async readAsModule(input, options = {}) {
+		return runTwinAsync(this.readAsModuleBody(input, options));
 	}
-	readAsModuleSync(input) {
-		return runTwinSync(this.readAsModuleBody(input));
+	readAsModuleSync(input, options = {}) {
+		return runTwinSync(this.readAsModuleBody(input, options));
 	}
-	*readBody(input) {
-		const { output, reader } = yield* this.executeBody(input);
+	*readBody(input, options) {
+		const { output, reader } = yield* this.executeBody(input, options);
 		if (reader instanceof ModuleReader) return toModuleRecord(output);
 		return output;
 	}
-	*readAsModuleBody(input) {
-		const { output, reader } = yield* this.executeBody(input);
+	*readAsModuleBody(input, options) {
+		const { output, reader } = yield* this.executeBody(input, options);
 		return this.toRecord(output, reader);
 	}
 	/**
 	* Shared dispatch + execution of both read bodies: resolve the
 	* reader, run it, wrap errors. Normalization is the caller's call.
 	*/
-	*executeBody(input) {
+	*executeBody(input, options) {
 		const filePath = buildFilePath(input);
-		const reader = this.findReader(filePath);
+		let reader;
+		if (typeof options.format === "undefined") reader = this.findReader(filePath);
+		else reader = this.resolveReader(options.format);
 		if (!reader) throw this.unknownExtensionError(filePath);
 		try {
 			return {
@@ -998,32 +980,45 @@ var FormatRegistry = class {
 			throw wrapLoaderError(e, filePath);
 		}
 	}
-	async write(input, value) {
-		return runTwinAsync(this.writeBody(input, value));
+	/**
+	* options.format names a registered format id to use instead of
+	* extension dispatch — see writeBody for the boundary semantics.
+	*/
+	async write(input, value, options = {}) {
+		return runTwinAsync(this.writeBody(input, value, options));
 	}
-	writeSync(input, value) {
-		runTwinSync(this.writeBody(input, value));
+	writeSync(input, value, options = {}) {
+		runTwinSync(this.writeBody(input, value, options));
 	}
 	/**
 	* Shared body of write/writeSync: dispatch, unwrap records, write, wrap.
 	* The inverse boundary of readAsModuleBody: a record produced by
 	* readAsModule() (brand detected) is unwrapped to its `.default` value;
 	* anything else is written as-is.
+	*
+	* An explicit options.format skips extension dispatch entirely —
+	* including the bare-specifier guard: naming the format resolves the
+	* ambiguity the guard exists for, so extensionless paths become
+	* writable.
 	*/
-	*writeBody(input, value) {
+	*writeBody(input, value, options) {
 		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.`,
+		let writer;
+		if (typeof options.format === "undefined") {
+			if (!isFilePath(filePath)) throw new WriteError({
+				message: `Cannot write to a bare module specifier: ${filePath}`,
 				path: filePath
 			});
-			throw this.unknownExtensionError(filePath);
-		}
+			const found = this.findWriter(filePath);
+			if (!found) {
+				if (this.findReader(filePath)) throw new WriteError({
+					message: `The format of extension ${pathToLocatorInfo(filePath).extension} is read-only.`,
+					path: filePath
+				});
+				throw this.unknownExtensionError(filePath);
+			}
+			writer = found;
+		} else writer = this.resolveWriter(options.format, filePath);
 		const plain = isModuleRecord(value) ? value.default : value;
 		try {
 			yield* op(() => writer.write(filePath, plain), () => writer.writeSync(filePath, plain));
@@ -1072,7 +1067,7 @@ var FormatRegistry = class {
 	*   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
+	*   4. undefined → read/readSync throw UnknownExtensionError
 	*/
 	findReader(input) {
 		if (!isFilePath(input)) return this.builtInReader("module");
@@ -1093,6 +1088,43 @@ var FormatRegistry = class {
 		const id = this.findBuiltInId(input);
 		if (id && "writer" in BUILT_IN_PRESETS[id]) return this.builtInWriter(id);
 	}
+	/**
+	* Resolve a reader by EXPLICIT format id (the per-call override) —
+	* a user rule id or a built-in id — bypassing extension dispatch.
+	* Unknown ids and writer-only rules throw.
+	*/
+	resolveReader(id) {
+		const rule = this.rules.find((item) => item.id === id);
+		if (rule) {
+			if (rule.getReader) return rule.getReader();
+			throw new LocterError({ message: `The format ${id} has no reader.` });
+		}
+		if (hasOwnProperty(BUILT_IN_PRESETS, id)) return this.builtInReader(id);
+		throw this.unknownFormatError(id);
+	}
+	/**
+	* Write-side counterpart of resolveReader. Reader-only rules and
+	* read-only built-ins (module) throw WriteError, mirroring
+	* what extension dispatch throws for read-only extensions.
+	*/
+	resolveWriter(id, path) {
+		const rule = this.rules.find((item) => item.id === id);
+		if (rule) {
+			if (rule.getWriter) return rule.getWriter();
+			throw new WriteError({
+				message: `The format ${id} is read-only.`,
+				path
+			});
+		}
+		if (hasOwnProperty(BUILT_IN_PRESETS, id)) {
+			if ("writer" in BUILT_IN_PRESETS[id]) return this.builtInWriter(id);
+			throw new WriteError({
+				message: `The format ${id} is read-only.`,
+				path
+			});
+		}
+		throw this.unknownFormatError(id);
+	}
 	findRule(input, filter) {
 		const info = pathToLocatorInfo(input);
 		for (const rule of this.rules) {
@@ -1114,11 +1146,14 @@ var FormatRegistry = class {
 		return this.builtInExtensions.get(info.extension);
 	}
 	unknownExtensionError(input) {
-		return new LocterUnknownExtensionError({
+		return new UnknownExtensionError({
 			message: `No format registered for extension: ${pathToLocatorInfo(input).extension ?? "unknown"}`,
 			path: input
 		});
 	}
+	unknownFormatError(id) {
+		return new LocterError({ message: `No format registered with id: ${id}` });
+	}
 	compile(id, rule) {
 		return {
 			id,
@@ -1161,12 +1196,16 @@ function unregisterFormat(id) {
 * (json/yaml/conf and custom readers — mutable, round-trip-symmetric
 * with write); for modules the normalized module record (a module IS a
 * record; normalization only irons out CJS/ESM interop divergence).
+*
+* options.format forces a registered format id instead of extension
+* dispatch — e.g. { format: 'text' } reads a module file's source
+* WITHOUT evaluating it.
 */
-async function read(input) {
-	return useFormatRegistry().read(input);
+async function read(input, options) {
+	return useFormatRegistry().read(input, options);
 }
-function readSync(input) {
-	return useFormatRegistry().readSync(input);
+function readSync(input, options) {
+	return useFormatRegistry().readSync(input, options);
 }
 /**
 * Read a file/module and present the result as a normalized module
@@ -1174,17 +1213,22 @@ function readSync(input) {
 * always holds the loaded value, top-level keys are re-exposed as
 * named exports.
 */
-async function readAsModule(input) {
-	return useFormatRegistry().readAsModule(input);
+async function readAsModule(input, options) {
+	return useFormatRegistry().readAsModule(input, options);
 }
-function readAsModuleSync(input) {
-	return useFormatRegistry().readAsModuleSync(input);
+function readAsModuleSync(input, options) {
+	return useFormatRegistry().readAsModuleSync(input, options);
 }
-async function write(input, value) {
-	return useFormatRegistry().write(input, value);
+/**
+* options.format forces a registered format id instead of extension
+* dispatch — this also lifts the bare-specifier guard (extensionless
+* paths) and the read-only block on module extensions.
+*/
+async function write(input, value, options) {
+	return useFormatRegistry().write(input, value, options);
 }
-function writeSync(input, value) {
-	useFormatRegistry().writeSync(input, value);
+function writeSync(input, value, options) {
+	useFormatRegistry().writeSync(input, value, options);
 }
 /**
 * Override the built-in module reader's `import` / `require` calls.
@@ -1241,7 +1285,7 @@ function* readPackageFieldBody(field, options) {
 	try {
 		return extractField(yield* op(() => reader.read(filePath), () => reader.readSync(filePath)), field);
 	} catch (e) {
-		if (e instanceof LocterNotFoundError) return;
+		if (e instanceof NotFoundError) return;
 		throw e;
 	}
 }
@@ -1254,11 +1298,11 @@ function readPackageFieldSync(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." });
+	if (!info) throw new NotFoundError({ 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({
+	if (!isObject(pkg)) throw new WriteError({
 		message: "The located package.json does not contain an object.",
 		path: filePath
 	});
@@ -1270,7 +1314,7 @@ function* writePackageFieldBody(field, value, options) {
 * 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.
+* Throws NotFoundError when no package.json could be located.
 */
 async function writePackageField(field, value, options = {}) {
 	return runTwinAsync(writePackageFieldBody(field, value, options));
@@ -1279,6 +1323,6 @@ 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, TextReader, TextWriter, YAMLReader, YAMLWriter, buildFilePath, deserializeValue, getFileNameExtension, getModuleExport, isJestRuntimeEnvironment, isLocatorInfo, isModuleRecord, isTsNodeRuntimeEnvironment, isTsxRuntimeEnvironment, isVitestRuntimeEnvironment, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, read, readAsModule, readAsModuleSync, readPackageField, readPackageFieldSync, readSync, registerFormat, removeFileNameExtension, serializeValue, setModuleReader, unregisterFormat, useFormatRegistry, wrapLoaderError, wrapWriteError, write, writePackageField, writePackageFieldSync, writeSync };
+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, LoadError, LocterError, MODULE_FILE_EXTENSIONS, ModuleReader, NotFoundError, TextFileReader, TextFileWriter, TextReader, TextWriter, UnknownExtensionError, WriteError, YAMLReader, YAMLWriter, buildFilePath, deserializeValue, getFileNameExtension, getModuleExport, isJestRuntimeEnvironment, isLocatorInfo, isModuleRecord, isTsNodeRuntimeEnvironment, isTsxRuntimeEnvironment, isVitestRuntimeEnvironment, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, read, readAsModule, readAsModuleSync, readPackageField, readPackageFieldSync, readSync, registerFormat, removeFileNameExtension, serializeValue, setModuleReader, unregisterFormat, useFormatRegistry, wrapLoaderError, wrapWriteError, write, writePackageField, writePackageFieldSync, writeSync };
 
 //# sourceMappingURL=index.mjs.map