@theholocron/json-utils 1.9.2 → 1.10.0

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+//#region src/stringify-json.d.ts
+export interface StringifyJsonOptions {
+  /**
+   * Indent for each level: a number of spaces (a non-negative integer) or a
+   * string of spaces and tabs (e.g. `"\t"`). Any length works, unlike
+   * `JSON.stringify`'s own ten-character cap. Default `2`.
+   */
+  indent?: number | string;
+  /**
+   * The existing file's text. Its detected indent and line endings are used
+   * instead of `indent`, so rewriting a file doesn't reformat it. Falls back
+   * to `indent` when no indent can be detected (empty or single-line input).
+   * A file that mixes `\r\n` and `\n` keeps whichever it uses more (`\n` on a tie).
+   */
+  like?: string;
+}
+/**
+ * The indentation one level of nesting adds in a JSON document — the leading
+ * whitespace (spaces or a tab) of the first line after the first one, less any
+ * padding the root value's own line starts with. `undefined` when there is
+ * none, e.g. a minified or single-line document.
+ *
+ * Raw newlines can't occur inside a JSON string, so any line that starts with
+ * whitespace is structural indentation.
+ */
+export declare function detectIndent(text: string): string | undefined;
+/**
+ * `JSON.stringify` pretty-printed and ending in exactly one newline — the shape
+ * every `package.json`-style file on disk should have.
+ *
+ * Pass the file's current text as `like` to keep its own indent (tabs, 4
+ * spaces, …) and line endings (`\r\n`) when rewriting it.
+ *
+ * @throws {TypeError} when `value` has no JSON representation (`undefined`, a
+ * function, a symbol) — `JSON.stringify` would return `undefined` for it — or
+ * when `indent` isn't a non-negative integer or a string of spaces and tabs
+ * (anything else would produce text no JSON parser accepts).
+ */
+export declare function stringifyJson(value: unknown, options?: StringifyJsonOptions): string;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,62 @@
+//#region src/stringify-json.ts
+/**
+* The indentation one level of nesting adds in a JSON document — the leading
+* whitespace (spaces or a tab) of the first line after the first one, less any
+* padding the root value's own line starts with. `undefined` when there is
+* none, e.g. a minified or single-line document.
+*
+* Raw newlines can't occur inside a JSON string, so any line that starts with
+* whitespace is structural indentation.
+*/
+function detectIndent(text) {
+	const lines = text.split(/\r?\n/);
+	const rootAt = lines.findIndex((line) => line.trim() !== "");
+	if (rootAt === -1) return void 0;
+	const rootPad = /^[ \t]*/.exec(lines[rootAt])[0];
+	for (const line of lines.slice(rootAt + 1)) {
+		const match = /^([ \t]+)\S/.exec(line);
+		if (!match) continue;
+		const pad = match[1];
+		const nested = pad.startsWith(rootPad) ? pad.slice(rootPad.length) : pad;
+		if (nested) return nested;
+	}
+}
+/** `\r\n` when it is the file's majority line ending, else `\n`. */
+function detectEol(text) {
+	const crlf = text.match(/\r\n/g)?.length ?? 0;
+	return crlf > (text.match(/\n/g)?.length ?? 0) - crlf ? "\r\n" : "\n";
+}
+function resolveIndent(indent) {
+	if (typeof indent === "number") {
+		if (!Number.isInteger(indent) || indent < 0) throw new TypeError(`indent must be a non-negative integer, got ${indent}`);
+		return " ".repeat(indent);
+	}
+	if (!/^[ \t]*$/.test(indent)) throw new TypeError(`indent must contain only spaces and tabs, got ${JSON.stringify(indent)}`);
+	return indent;
+}
+/**
+* `JSON.stringify` pretty-printed and ending in exactly one newline — the shape
+* every `package.json`-style file on disk should have.
+*
+* Pass the file's current text as `like` to keep its own indent (tabs, 4
+* spaces, …) and line endings (`\r\n`) when rewriting it.
+*
+* @throws {TypeError} when `value` has no JSON representation (`undefined`, a
+* function, a symbol) — `JSON.stringify` would return `undefined` for it — or
+* when `indent` isn't a non-negative integer or a string of spaces and tabs
+* (anything else would produce text no JSON parser accepts).
+*/
+function stringifyJson(value, options = {}) {
+	let indent = resolveIndent(options.indent ?? 2);
+	let eol = "\n";
+	if (options.like !== void 0) {
+		indent = detectIndent(options.like) ?? indent;
+		eol = detectEol(options.like);
+	}
+	const json = indent === "" ? JSON.stringify(value) : JSON.stringify(value, null, "	");
+	if (json === void 0) throw new TypeError("Cannot stringify a value that has no JSON representation");
+	const indented = indent === "" || indent === "	" ? json : json.replace(/^\t+/gm, (tabs) => indent.repeat(tabs.length));
+	return (eol === "\n" ? indented : indented.replace(/\n/g, eol)) + eol;
+}
+//#endregion
+export { detectIndent, stringifyJson };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/json-utils",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Stringify JSON with a trailing newline, preserving a file's own indent and line endings.",
   "keywords": [
     "json",