locter 4.0.0-beta.2 → 4.1.0

package/dist/index.mjs

@@ -28,7 +28,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 +40,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 +52,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);
 	}
@@ -128,7 +128,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 +148,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 +164,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,
@@ -372,7 +372,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 {
@@ -444,11 +444,39 @@ var ConfReader = class extends TextFileReader {
 	}
 };
 //#endregion
-//#region src/format/built-in/conf/writer.ts
-function serializeValue(value) {
-	return typeof value === "string" ? value : JSON.stringify(value);
+//#region src/format/value.ts
+/**
+* Lenient VALUE codec (env-var / key-value philosophy): primitives
+* serialize to their bare string form, RegExp and BigInt to their
+* string representation (also nested), everything else to JSON.
+* The counterpart of deserializeValue — used per value by the conf
+* format, and exported for consumers building lenient custom formats.
+*/
+function serializeValue(input) {
+	if (typeof input === "string") return input;
+	if (typeof input === "undefined") return "undefined";
+	if (input === null) return "null";
+	if (typeof input === "boolean") return input ? "true" : "false";
+	if (typeof input === "number") return `${input}`;
+	if (typeof input === "bigint") return input.toString();
+	if (input instanceof RegExp) return input.toString();
+	return JSON.stringify(input, (_key, item) => {
+		if (item instanceof RegExp) return item.toString();
+		if (typeof item === "bigint") return item.toString();
+		return item;
+	}) ?? String(input);
 }
 /**
+* Lenient parse of a serialized value: coerces 'true'/'123'/'null'/
+* 'undefined' to their primitive, parses JSON payloads, and falls back
+* to returning the raw string — it never throws.
+*/
+function deserializeValue(input) {
+	return destr(input);
+}
+//#endregion
+//#region src/format/built-in/conf/writer.ts
+/**
 * 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,
@@ -694,6 +722,32 @@ function getModuleExport(data, filterFn) {
 	};
 }
 //#endregion
+//#region src/format/built-in/text/reader.ts
+/**
+* Raw text: the file content, as-is. No value coercion — a .txt
+* containing '123' reads as the string '123' (use deserializeValue
+* for lenient value semantics).
+*/
+var TextReader = class extends TextFileReader {
+	parse(content) {
+		return content;
+	}
+};
+//#endregion
+//#region src/format/built-in/text/writer.ts
+/**
+* Raw text: accepts strings only — coercing arbitrary values would be
+* lossy ([object Object]); serialize explicitly (e.g. serializeValue)
+* before writing. Output ends with a single trailing newline, like
+* every text writer.
+*/
+var TextWriter = class extends TextFileWriter {
+	stringify(value) {
+		if (typeof value !== "string") throw new Error("The value must be a string for the text format.");
+		return value;
+	}
+};
+//#endregion
 //#region src/format/built-in/yaml/reader.ts
 var YAMLReader = class extends TextFileReader {
 	parse(content) {
@@ -735,7 +789,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 {
@@ -785,6 +839,11 @@ const BUILT_IN_PRESETS = {
 		extensions: [".yml", ".yaml"],
 		reader: () => new YAMLReader(),
 		writer: () => new YAMLWriter()
+	},
+	text: {
+		extensions: [".txt"],
+		reader: () => new TextReader(),
+		writer: () => new TextWriter()
 	}
 };
 //#endregion
@@ -894,12 +953,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
@@ -907,28 +970,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 {
@@ -939,32 +1004,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));
@@ -1013,7 +1091,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");
@@ -1034,6 +1112,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) {
@@ -1055,11 +1170,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,
@@ -1102,12 +1220,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
@@ -1115,17 +1237,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.
@@ -1182,7 +1309,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;
 	}
 }
@@ -1195,11 +1322,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
 	});
@@ -1211,7 +1338,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));
@@ -1220,6 +1347,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, YAMLReader, YAMLWriter, buildFilePath, getFileNameExtension, getModuleExport, isJestRuntimeEnvironment, isLocatorInfo, isModuleRecord, isTsNodeRuntimeEnvironment, isTsxRuntimeEnvironment, isVitestRuntimeEnvironment, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, read, readAsModule, readAsModuleSync, readPackageField, readPackageFieldSync, readSync, registerFormat, removeFileNameExtension, 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