@helpers4/node 3.1.2 → 3.1.4

package/README.md

@@ -30,6 +30,7 @@ A set of helpers for working with URLs.
 - [function](../function)
 - [guard](../guard)
 - [id](../id)
+- [json](../json)
 - [license](../license)
 - [map](../map)
 - [markdown](../markdown)
@@ -58,6 +59,7 @@ A set of helpers for working with URLs.
 | function | [@helpers4/function](https://www.npmjs.com/package/@helpers4/function) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/function) | Function utilities and type guards |
 | guard | [@helpers4/guard](https://www.npmjs.com/package/@helpers4/guard) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/guard) | Runtime type guard utilities |
 | id | [@helpers4/id](https://www.npmjs.com/package/@helpers4/id) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/id) | Unique identifier generation utilities |
+| json | [@helpers4/json](https://www.npmjs.com/package/@helpers4/json) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/json) | JSON parsing and serialization, with its common variants |
 | license | [@helpers4/license](https://www.npmjs.com/package/@helpers4/license) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/license) | License string classification and comparison |
 | map | [@helpers4/map](https://www.npmjs.com/package/@helpers4/map) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/map) | Native Map manipulation utilities |
 | markdown | [@helpers4/markdown](https://www.npmjs.com/package/@helpers4/markdown) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/markdown) | Markdown formatting and escaping utilities |

package/lib/index.js

@@ -81,24 +81,27 @@ function isSharedArrayBuffer(value) {
 	return typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
 }
 //#endregion
-//#region helpers/node/_stripJsonComments.ts
+//#region helpers/_shared/_stripJsonComments.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 *
-* Internal helper used by safeReadJsonFile.ts to support JSONC (JSON with
-* line and block comments, plus trailing commas) — the dialect used by
-* tsconfig.json, VS Code's settings.json, etc. Not exported from the package
-* barrel — tests live in _stripJsonComments.test.ts.
+* Internal helper used by `node/safeReadJsonFile` and `json/parse` to support JSONC (JSON with
+* line and block comments, plus trailing commas) — the dialect used by tsconfig.json, VS Code's
+* settings.json, etc. Not exported from any package barrel — tests live in
+* _stripJsonComments.test.ts.
 */
 /**
-* Strips line comments (starting with two slashes), block comments (slash-star
-* ... star-slash), and trailing commas (before `}` or `]`) from a JSONC
-* string, so the result can be safely passed to `JSON.parse`. String literals
-* are tracked so a comment-like or comma character occurring *inside* a JSON
-* string (e.g. a URL) is left untouched — this is a string-boundary-aware
-* pass, not a naive regex strip.
+* Blanks out line comments (starting with two slashes), block comments (slash-star ... star-slash),
+* and trailing commas (before `}` or `]`) in a JSONC string, so the result can be passed to
+* `JSON.parse`. String literals are tracked so a comment-like or comma character occurring
+* *inside* a JSON string (e.g. a URL) is left untouched — this is a string-boundary-aware pass,
+* not a naive regex strip.
+*
+* Everything removed is replaced by spaces (line breaks inside a block comment are kept), so the
+* output has exactly the same length and line layout as the input: a position `JSON.parse`
+* reports in an error on the output points at the same place in the original JSONC text.
 * @ignore
 */
 function stripJsonComments(input) {
@@ -106,10 +109,12 @@ function stripJsonComments(input) {
 	let inString = false;
 	let pendingComma = "";
 	const flushPendingComma = () => {
-		if (pendingComma) {
-			output += pendingComma;
-			pendingComma = "";
-		}
+		output += pendingComma;
+		pendingComma = "";
+	};
+	const emitFiller = (text) => {
+		if (pendingComma) pendingComma += text;
+		else output += text;
 	};
 	let i = 0;
 	while (i < input.length) {
@@ -131,14 +136,18 @@ function stripJsonComments(input) {
 			continue;
 		}
 		if (char === "/" && input[i + 1] === "/") {
+			const start = i;
 			i += 2;
 			while (i < input.length && input[i] !== "\n" && input[i] !== "\r") i++;
+			emitFiller(" ".repeat(i - start));
 			continue;
 		}
 		if (char === "/" && input[i + 1] === "*") {
+			const start = i;
 			i += 2;
 			while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
-			i += 2;
+			i = Math.min(i + 2, input.length);
+			emitFiller(input.slice(start, i).replace(/[^\r\n]/g, " "));
 			continue;
 		}
 		if (char === ",") {
@@ -148,14 +157,14 @@ function stripJsonComments(input) {
 			continue;
 		}
 		if (char === "}" || char === "]") {
+			output += pendingComma.replace(",", " ");
 			pendingComma = "";
 			output += char;
 			i++;
 			continue;
 		}
 		if (char === " " || char === "	" || char === "\n" || char === "\r") {
-			if (pendingComma) pendingComma += char;
-			else output += char;
+			emitFiller(char);
 			i++;
 			continue;
 		}

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/node/isBuffer.ts","../../../helpers/node/isNodeStream.ts","../../../helpers/node/isSharedArrayBuffer.ts","../../../helpers/node/_stripJsonComments.ts","../../../helpers/node/safeReadJsonFile.ts","../../../helpers/node/withTempDir.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a Node.js Buffer instance.\n *\n * `Buffer` extends `Uint8Array` and is specific to Node.js, Bun, and Deno.\n * In browser-only environments where `Buffer` is not defined, this function\n * always returns `false`.\n *\n * Useful for filtering or type-narrowing in a functional pipeline:\n * `values.filter(isBuffer)`\n *\n * @param value - The value to check\n * @returns True if value is a Buffer\n * @example\n * isBuffer(Buffer.from('hello')) // => true\n * isBuffer(new Uint8Array(8))    // => false\n * isBuffer('hello')              // => false\n * @since 2.0.0\n */\nexport function isBuffer(value: unknown): value is Buffer {\n  return typeof Buffer !== 'undefined' && value instanceof Buffer;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a Node.js stream (has a `.pipe()` method).\n *\n * Uses duck-typing: any object with a `pipe` function qualifies, covering\n * `Readable`, `Writable`, `Duplex`, `Transform`, and custom stream-compatible\n * objects without importing from `node:stream`.\n *\n * @param value - The value to check\n * @returns `true` if value is a Node.js stream\n * @example\n * import { Readable } from 'node:stream';\n * isNodeStream(new Readable()) // => true\n * isNodeStream({})             // => false\n * isNodeStream(null)           // => false\n * @since 2.0.3\n */\nexport function isNodeStream(value: unknown): value is { pipe: (...args: unknown[]) => unknown } {\n  return (\n    // Intentionally `object`-only, unlike `isPromiseLike` (see type/isPromiseLike.ts):\n    // a callable function exposing `.pipe()` would be an unusual, contrived stream shape.\n    value !== null &&\n    typeof value === 'object' &&\n    typeof (value as Record<string, unknown>)['pipe'] === 'function'\n  );\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a `SharedArrayBuffer` instance.\n *\n * `SharedArrayBuffer` enables shared memory between the main thread and worker\n * threads. In browsers without COOP/COEP headers, `SharedArrayBuffer` may be\n * unavailable; this function returns `false` in that case.\n *\n * @param value - The value to check\n * @returns `true` if value is a SharedArrayBuffer\n * @example\n * isSharedArrayBuffer(new SharedArrayBuffer(8)) // => true\n * isSharedArrayBuffer(new ArrayBuffer(8))       // => false\n * isSharedArrayBuffer(null)                     // => false\n * @since 2.0.3\n */\nexport function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer {\n  return typeof SharedArrayBuffer !== 'undefined' && value instanceof SharedArrayBuffer;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n *\n * Internal helper used by safeReadJsonFile.ts to support JSONC (JSON with\n * line and block comments, plus trailing commas) — the dialect used by\n * tsconfig.json, VS Code's settings.json, etc. Not exported from the package\n * barrel — tests live in _stripJsonComments.test.ts.\n */\n\n/**\n * Strips line comments (starting with two slashes), block comments (slash-star\n * ... star-slash), and trailing commas (before `}` or `]`) from a JSONC\n * string, so the result can be safely passed to `JSON.parse`. String literals\n * are tracked so a comment-like or comma character occurring *inside* a JSON\n * string (e.g. a URL) is left untouched — this is a string-boundary-aware\n * pass, not a naive regex strip.\n * @ignore\n */\nexport function stripJsonComments(input: string): string {\n  let output = '';\n  let inString = false;\n  // A comma seen outside a string is held back instead of emitted immediately:\n  // if the next significant token turns out to be `}`/`]`, it was a trailing\n  // comma and gets dropped; otherwise it (and any whitespace/comments held\n  // alongside it) is flushed once a real token confirms it wasn't trailing.\n  let pendingComma = '';\n  const flushPendingComma = () => {\n    if (pendingComma) {\n      output += pendingComma;\n      pendingComma = '';\n    }\n  };\n\n  let i = 0;\n  while (i < input.length) {\n    const char = input[i];\n\n    if (inString) {\n      output += char;\n      if (char === '\\\\') {\n        // Copy the escaped character as-is (whatever it is) so an escaped\n        // quote (`\\\"`) doesn't get mistaken for the string's end.\n        i++;\n        if (i < input.length) output += input[i];\n      } else if (char === '\"') {\n        inString = false;\n      }\n      i++;\n      continue;\n    }\n\n    if (char === '\"') {\n      flushPendingComma();\n      inString = true;\n      output += char;\n      i++;\n      continue;\n    }\n\n    if (char === '/' && input[i + 1] === '/') {\n      i += 2;\n      // Stop at any line-ending character, not just \\n — a bare \\r (classic\n      // Mac line endings, or a lone \\r before a later \\n) also ends the line,\n      // otherwise everything up to the next \\n (or EOF) gets silently eaten.\n      while (i < input.length && input[i] !== '\\n' && input[i] !== '\\r') i++;\n      continue;\n    }\n\n    if (char === '/' && input[i + 1] === '*') {\n      i += 2;\n      while (i < input.length && !(input[i] === '*' && input[i + 1] === '/')) i++;\n      i += 2;\n      continue;\n    }\n\n    if (char === ',') {\n      flushPendingComma();\n      pendingComma = char;\n      i++;\n      continue;\n    }\n\n    if (char === '}' || char === ']') {\n      pendingComma = ''; // drop — it was trailing\n      output += char;\n      i++;\n      continue;\n    }\n\n    if (char === ' ' || char === '\\t' || char === '\\n' || char === '\\r') {\n      // Whitespace doesn't resolve a pending comma either way — buffer it\n      // alongside so it's dropped too if the comma turns out to be trailing.\n      if (pendingComma) {\n        pendingComma += char;\n      } else {\n        output += char;\n      }\n      i++;\n      continue;\n    }\n\n    flushPendingComma();\n    output += char;\n    i++;\n  }\n\n  flushPendingComma();\n  return output;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\nimport { readFileSync } from 'node:fs';\nimport { stripJsonComments } from './_stripJsonComments';\n\n/**\n * Reads a file and parses its contents as JSON, returning `null` (or a\n * fallback) on any failure — a missing/unreadable file and invalid content\n * are both treated the same way.\n *\n * Also tolerates JSONC (line/block comments and trailing commas — the\n * dialect used by `tsconfig.json`, VS Code's `settings.json`, etc.): strict\n * `JSON.parse` is tried first, and only on failure is the content re-parsed\n * with comments/trailing commas stripped, so plain JSON pays no extra cost.\n *\n * Unlike `readFileSync` + `JSON.parse`, this never throws.\n *\n * @param filePath - Path to the JSON (or JSONC) file to read.\n * @param fallback - Value returned on failure. Defaults to `null` when omitted.\n * @returns The parsed value typed as `T`, or `fallback` on failure.\n * @example\n * safeReadJsonFile<{ name: string }>('./package.json') // => { name: 'helpers4', ... }\n * safeReadJsonFile('./missing.json')                   // => null\n * safeReadJsonFile('./missing.json', {})               // => {}\n * @example\n * // tsconfig.json-style JSONC (comments + trailing comma) also parses:\n * safeReadJsonFile('./tsconfig.json') // => { compilerOptions: { strict: true }, ... }\n * @since 3.0.6\n */\nexport function safeReadJsonFile<T>(filePath: string): T | null;\nexport function safeReadJsonFile<T>(filePath: string, fallback: T): T;\nexport function safeReadJsonFile<T>(filePath: string, fallback?: T): T | null {\n  try {\n    const content = readFileSync(filePath, 'utf-8');\n    try {\n      return JSON.parse(content) as T;\n    } catch {\n      // Not strict JSON — retry tolerating JSONC comments/trailing commas\n      // before giving up.\n      return JSON.parse(stripJsonComments(content)) as T;\n    }\n  } catch {\n    // Distinguish \"no fallback provided\" (→ null) from \"fallback is undefined\"\n    // (→ undefined as T) to keep runtime behaviour aligned with the overloads.\n    return arguments.length < 2 ? null : (fallback as T);\n  }\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\nimport { mkdtemp, rm } from 'node:fs/promises';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\n\n/**\n * Creates a fresh temporary directory under the OS temp root, runs `fn` with its path, and\n * always removes it (recursively) afterward — including when `fn` throws.\n * @param prefix - Prepended to the generated directory name, to make it identifiable\n * @param fn - Receives the temp directory's absolute path; its (possibly synchronous) return\n * value is returned\n * @returns Whatever `fn` returns or resolves to\n * @example\n * await withTempDir('my-tool', async (dir) => {\n *   await writeFile(`${dir}/output.txt`, 'data');\n *   return readFile(`${dir}/output.txt`, 'utf-8');\n * });\n * // => 'data' (the directory no longer exists once this resolves)\n * @since 3.1.1\n */\nexport async function withTempDir<T>(prefix: string, fn: (dir: string) => T | Promise<T>): Promise<T> {\n  const dir = await mkdtemp(join(tmpdir(), `${prefix}-`));\n  try {\n    return await fn(dir);\n  } finally {\n    await rm(dir, { recursive: true, force: true });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,SAAS,OAAiC;CACxD,OAAO,OAAO,WAAW,eAAe,iBAAiB;AAC3D;;;;;;;;;;;;;;;;;;;;;;;;ACJA,SAAgB,aAAa,OAAoE;CAC/F,OAGE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAkC,YAAY;AAE1D;;;;;;;;;;;;;;;;;;;;;;;ACTA,SAAgB,oBAAoB,OAA4C;CAC9E,OAAO,OAAO,sBAAsB,eAAe,iBAAiB;AACtE;;;;;;;;;;;;;;;;;;;;;;ACHA,SAAgB,kBAAkB,OAAuB;CACvD,IAAI,SAAS;CACb,IAAI,WAAW;CAKf,IAAI,eAAe;CACnB,MAAM,0BAA0B;EAC9B,IAAI,cAAc;GAChB,UAAU;GACV,eAAe;EACjB;CACF;CAEA,IAAI,IAAI;CACR,OAAO,IAAI,MAAM,QAAQ;EACvB,MAAM,OAAO,MAAM;EAEnB,IAAI,UAAU;GACZ,UAAU;GACV,IAAI,SAAS,MAAM;IAGjB;IACA,IAAI,IAAI,MAAM,QAAQ,UAAU,MAAM;GACxC,OAAO,IAAI,SAAS,MAClB,WAAW;GAEb;GACA;EACF;EAEA,IAAI,SAAS,MAAK;GAChB,kBAAkB;GAClB,WAAW;GACX,UAAU;GACV;GACA;EACF;EAEA,IAAI,SAAS,OAAO,MAAM,IAAI,OAAO,KAAK;GACxC,KAAK;GAIL,OAAO,IAAI,MAAM,UAAU,MAAM,OAAO,QAAQ,MAAM,OAAO,MAAM;GACnE;EACF;EAEA,IAAI,SAAS,OAAO,MAAM,IAAI,OAAO,KAAK;GACxC,KAAK;GACL,OAAO,IAAI,MAAM,UAAU,EAAE,MAAM,OAAO,OAAO,MAAM,IAAI,OAAO,MAAM;GACxE,KAAK;GACL;EACF;EAEA,IAAI,SAAS,KAAK;GAChB,kBAAkB;GAClB,eAAe;GACf;GACA;EACF;EAEA,IAAI,SAAS,OAAO,SAAS,KAAK;GAChC,eAAe;GACf,UAAU;GACV;GACA;EACF;EAEA,IAAI,SAAS,OAAO,SAAS,OAAQ,SAAS,QAAQ,SAAS,MAAM;GAGnE,IAAI,cACF,gBAAgB;QAEhB,UAAU;GAEZ;GACA;EACF;EAEA,kBAAkB;EAClB,UAAU;EACV;CACF;CAEA,kBAAkB;CAClB,OAAO;AACT;;;;;;;;AC3EA,SAAgB,iBAAoB,UAAkB,UAAwB;CAC5E,IAAI;EACF,MAAM,UAAU,aAAa,UAAU,OAAO;EAC9C,IAAI;GACF,OAAO,KAAK,MAAM,OAAO;EAC3B,QAAQ;GAGN,OAAO,KAAK,MAAM,kBAAkB,OAAO,CAAC;EAC9C;CACF,QAAQ;EAGN,OAAO,UAAU,SAAS,IAAI,OAAQ;CACxC;AACF;;;;;;;;;;;;;;;;;;;;;;;ACzBA,eAAsB,YAAe,QAAgB,IAAiD;CACpG,MAAM,MAAM,MAAM,QAAQ,KAAK,OAAO,GAAG,GAAG,OAAO,EAAE,CAAC;CACtD,IAAI;EACF,OAAO,MAAM,GAAG,GAAG;CACrB,UAAU;EACR,MAAM,GAAG,KAAK;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;CAChD;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/node/isBuffer.ts","../../../helpers/node/isNodeStream.ts","../../../helpers/node/isSharedArrayBuffer.ts","../../../helpers/_shared/_stripJsonComments.ts","../../../helpers/node/safeReadJsonFile.ts","../../../helpers/node/withTempDir.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a Node.js Buffer instance.\n *\n * `Buffer` extends `Uint8Array` and is specific to Node.js, Bun, and Deno.\n * In browser-only environments where `Buffer` is not defined, this function\n * always returns `false`.\n *\n * Useful for filtering or type-narrowing in a functional pipeline:\n * `values.filter(isBuffer)`\n *\n * @param value - The value to check\n * @returns True if value is a Buffer\n * @example\n * isBuffer(Buffer.from('hello')) // => true\n * isBuffer(new Uint8Array(8))    // => false\n * isBuffer('hello')              // => false\n * @since 2.0.0\n */\nexport function isBuffer(value: unknown): value is Buffer {\n  return typeof Buffer !== 'undefined' && value instanceof Buffer;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a Node.js stream (has a `.pipe()` method).\n *\n * Uses duck-typing: any object with a `pipe` function qualifies, covering\n * `Readable`, `Writable`, `Duplex`, `Transform`, and custom stream-compatible\n * objects without importing from `node:stream`.\n *\n * @param value - The value to check\n * @returns `true` if value is a Node.js stream\n * @example\n * import { Readable } from 'node:stream';\n * isNodeStream(new Readable()) // => true\n * isNodeStream({})             // => false\n * isNodeStream(null)           // => false\n * @since 2.0.3\n */\nexport function isNodeStream(value: unknown): value is { pipe: (...args: unknown[]) => unknown } {\n  return (\n    // Intentionally `object`-only, unlike `isPromiseLike` (see type/isPromiseLike.ts):\n    // a callable function exposing `.pipe()` would be an unusual, contrived stream shape.\n    value !== null &&\n    typeof value === 'object' &&\n    typeof (value as Record<string, unknown>)['pipe'] === 'function'\n  );\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a `SharedArrayBuffer` instance.\n *\n * `SharedArrayBuffer` enables shared memory between the main thread and worker\n * threads. In browsers without COOP/COEP headers, `SharedArrayBuffer` may be\n * unavailable; this function returns `false` in that case.\n *\n * @param value - The value to check\n * @returns `true` if value is a SharedArrayBuffer\n * @example\n * isSharedArrayBuffer(new SharedArrayBuffer(8)) // => true\n * isSharedArrayBuffer(new ArrayBuffer(8))       // => false\n * isSharedArrayBuffer(null)                     // => false\n * @since 2.0.3\n */\nexport function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer {\n  return typeof SharedArrayBuffer !== 'undefined' && value instanceof SharedArrayBuffer;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n *\n * Internal helper used by `node/safeReadJsonFile` and `json/parse` to support JSONC (JSON with\n * line and block comments, plus trailing commas) — the dialect used by tsconfig.json, VS Code's\n * settings.json, etc. Not exported from any package barrel — tests live in\n * _stripJsonComments.test.ts.\n */\n\n/**\n * Blanks out line comments (starting with two slashes), block comments (slash-star ... star-slash),\n * and trailing commas (before `}` or `]`) in a JSONC string, so the result can be passed to\n * `JSON.parse`. String literals are tracked so a comment-like or comma character occurring\n * *inside* a JSON string (e.g. a URL) is left untouched — this is a string-boundary-aware pass,\n * not a naive regex strip.\n *\n * Everything removed is replaced by spaces (line breaks inside a block comment are kept), so the\n * output has exactly the same length and line layout as the input: a position `JSON.parse`\n * reports in an error on the output points at the same place in the original JSONC text.\n * @ignore\n */\nexport function stripJsonComments(input: string): string {\n  let output = '';\n  let inString = false;\n  // A comma seen outside a string is held back instead of emitted immediately:\n  // if the next significant token turns out to be `}`/`]`, it was a trailing\n  // comma and gets blanked; otherwise it (and any whitespace/comments held\n  // alongside it) is flushed once a real token confirms it wasn't trailing.\n  let pendingComma = '';\n  const flushPendingComma = () => {\n    output += pendingComma;\n    pendingComma = '';\n  };\n  // Whitespace and blanked-out comments don't resolve a pending comma either way, so they're\n  // buffered alongside it to keep the output in the original order.\n  const emitFiller = (text: string) => {\n    if (pendingComma) {\n      pendingComma += text;\n    } else {\n      output += text;\n    }\n  };\n\n  let i = 0;\n  while (i < input.length) {\n    const char = input[i];\n\n    if (inString) {\n      output += char;\n      if (char === '\\\\') {\n        // Copy the escaped character as-is (whatever it is) so an escaped\n        // quote (`\\\"`) doesn't get mistaken for the string's end.\n        i++;\n        if (i < input.length) output += input[i];\n      } else if (char === '\"') {\n        inString = false;\n      }\n      i++;\n      continue;\n    }\n\n    if (char === '\"') {\n      flushPendingComma();\n      inString = true;\n      output += char;\n      i++;\n      continue;\n    }\n\n    if (char === '/' && input[i + 1] === '/') {\n      const start = i;\n      i += 2;\n      // Stop at any line-ending character, not just \\n — a bare \\r (classic\n      // Mac line endings, or a lone \\r before a later \\n) also ends the line,\n      // otherwise everything up to the next \\n (or EOF) gets silently eaten.\n      while (i < input.length && input[i] !== '\\n' && input[i] !== '\\r') i++;\n      emitFiller(' '.repeat(i - start));\n      continue;\n    }\n\n    if (char === '/' && input[i + 1] === '*') {\n      const start = i;\n      i += 2;\n      while (i < input.length && !(input[i] === '*' && input[i + 1] === '/')) i++;\n      // An unterminated block comment runs to the end of the input.\n      i = Math.min(i + 2, input.length);\n      emitFiller(input.slice(start, i).replace(/[^\\r\\n]/g, ' '));\n      continue;\n    }\n\n    if (char === ',') {\n      flushPendingComma();\n      pendingComma = char;\n      i++;\n      continue;\n    }\n\n    if (char === '}' || char === ']') {\n      // Blank the comma — it was trailing — but keep what was buffered after it.\n      output += pendingComma.replace(',', ' ');\n      pendingComma = '';\n      output += char;\n      i++;\n      continue;\n    }\n\n    if (char === ' ' || char === '\\t' || char === '\\n' || char === '\\r') {\n      emitFiller(char);\n      i++;\n      continue;\n    }\n\n    flushPendingComma();\n    output += char;\n    i++;\n  }\n\n  flushPendingComma();\n  return output;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\nimport { readFileSync } from 'node:fs';\nimport { stripJsonComments } from '../_shared/_stripJsonComments';\n\n/**\n * Reads a file and parses its contents as JSON, returning `null` (or a\n * fallback) on any failure — a missing/unreadable file and invalid content\n * are both treated the same way.\n *\n * Also tolerates JSONC (line/block comments and trailing commas — the\n * dialect used by `tsconfig.json`, VS Code's `settings.json`, etc.): strict\n * `JSON.parse` is tried first, and only on failure is the content re-parsed\n * with comments/trailing commas stripped, so plain JSON pays no extra cost.\n *\n * Unlike `readFileSync` + `JSON.parse`, this never throws.\n *\n * @param filePath - Path to the JSON (or JSONC) file to read.\n * @param fallback - Value returned on failure. Defaults to `null` when omitted.\n * @returns The parsed value typed as `T`, or `fallback` on failure.\n * @example\n * safeReadJsonFile<{ name: string }>('./package.json') // => { name: 'helpers4', ... }\n * safeReadJsonFile('./missing.json')                   // => null\n * safeReadJsonFile('./missing.json', {})               // => {}\n * @example\n * // tsconfig.json-style JSONC (comments + trailing comma) also parses:\n * safeReadJsonFile('./tsconfig.json') // => { compilerOptions: { strict: true }, ... }\n * @since 3.0.6\n */\nexport function safeReadJsonFile<T>(filePath: string): T | null;\nexport function safeReadJsonFile<T>(filePath: string, fallback: T): T;\nexport function safeReadJsonFile<T>(filePath: string, fallback?: T): T | null {\n  try {\n    const content = readFileSync(filePath, 'utf-8');\n    try {\n      return JSON.parse(content) as T;\n    } catch {\n      // Not strict JSON — retry tolerating JSONC comments/trailing commas\n      // before giving up.\n      return JSON.parse(stripJsonComments(content)) as T;\n    }\n  } catch {\n    // Distinguish \"no fallback provided\" (→ null) from \"fallback is undefined\"\n    // (→ undefined as T) to keep runtime behaviour aligned with the overloads.\n    return arguments.length < 2 ? null : (fallback as T);\n  }\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\nimport { mkdtemp, rm } from 'node:fs/promises';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\n\n/**\n * Creates a fresh temporary directory under the OS temp root, runs `fn` with its path, and\n * always removes it (recursively) afterward — including when `fn` throws.\n * @param prefix - Prepended to the generated directory name, to make it identifiable\n * @param fn - Receives the temp directory's absolute path; its (possibly synchronous) return\n * value is returned\n * @returns Whatever `fn` returns or resolves to\n * @example\n * await withTempDir('my-tool', async (dir) => {\n *   await writeFile(`${dir}/output.txt`, 'data');\n *   return readFile(`${dir}/output.txt`, 'utf-8');\n * });\n * // => 'data' (the directory no longer exists once this resolves)\n * @since 3.1.1\n */\nexport async function withTempDir<T>(prefix: string, fn: (dir: string) => T | Promise<T>): Promise<T> {\n  const dir = await mkdtemp(join(tmpdir(), `${prefix}-`));\n  try {\n    return await fn(dir);\n  } finally {\n    await rm(dir, { recursive: true, force: true });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,SAAS,OAAiC;CACxD,OAAO,OAAO,WAAW,eAAe,iBAAiB;AAC3D;;;;;;;;;;;;;;;;;;;;;;;;ACJA,SAAgB,aAAa,OAAoE;CAC/F,OAGE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAkC,YAAY;AAE1D;;;;;;;;;;;;;;;;;;;;;;;ACTA,SAAgB,oBAAoB,OAA4C;CAC9E,OAAO,OAAO,sBAAsB,eAAe,iBAAiB;AACtE;;;;;;;;;;;;;;;;;;;;;;;;;ACAA,SAAgB,kBAAkB,OAAuB;CACvD,IAAI,SAAS;CACb,IAAI,WAAW;CAKf,IAAI,eAAe;CACnB,MAAM,0BAA0B;EAC9B,UAAU;EACV,eAAe;CACjB;CAGA,MAAM,cAAc,SAAiB;EACnC,IAAI,cACF,gBAAgB;OAEhB,UAAU;CAEd;CAEA,IAAI,IAAI;CACR,OAAO,IAAI,MAAM,QAAQ;EACvB,MAAM,OAAO,MAAM;EAEnB,IAAI,UAAU;GACZ,UAAU;GACV,IAAI,SAAS,MAAM;IAGjB;IACA,IAAI,IAAI,MAAM,QAAQ,UAAU,MAAM;GACxC,OAAO,IAAI,SAAS,MAClB,WAAW;GAEb;GACA;EACF;EAEA,IAAI,SAAS,MAAK;GAChB,kBAAkB;GAClB,WAAW;GACX,UAAU;GACV;GACA;EACF;EAEA,IAAI,SAAS,OAAO,MAAM,IAAI,OAAO,KAAK;GACxC,MAAM,QAAQ;GACd,KAAK;GAIL,OAAO,IAAI,MAAM,UAAU,MAAM,OAAO,QAAQ,MAAM,OAAO,MAAM;GACnE,WAAW,IAAI,OAAO,IAAI,KAAK,CAAC;GAChC;EACF;EAEA,IAAI,SAAS,OAAO,MAAM,IAAI,OAAO,KAAK;GACxC,MAAM,QAAQ;GACd,KAAK;GACL,OAAO,IAAI,MAAM,UAAU,EAAE,MAAM,OAAO,OAAO,MAAM,IAAI,OAAO,MAAM;GAExE,IAAI,KAAK,IAAI,IAAI,GAAG,MAAM,MAAM;GAChC,WAAW,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,QAAQ,YAAY,GAAG,CAAC;GACzD;EACF;EAEA,IAAI,SAAS,KAAK;GAChB,kBAAkB;GAClB,eAAe;GACf;GACA;EACF;EAEA,IAAI,SAAS,OAAO,SAAS,KAAK;GAEhC,UAAU,aAAa,QAAQ,KAAK,GAAG;GACvC,eAAe;GACf,UAAU;GACV;GACA;EACF;EAEA,IAAI,SAAS,OAAO,SAAS,OAAQ,SAAS,QAAQ,SAAS,MAAM;GACnE,WAAW,IAAI;GACf;GACA;EACF;EAEA,kBAAkB;EAClB,UAAU;EACV;CACF;CAEA,kBAAkB;CAClB,OAAO;AACT;;;;;;;;ACtFA,SAAgB,iBAAoB,UAAkB,UAAwB;CAC5E,IAAI;EACF,MAAM,UAAU,aAAa,UAAU,OAAO;EAC9C,IAAI;GACF,OAAO,KAAK,MAAM,OAAO;EAC3B,QAAQ;GAGN,OAAO,KAAK,MAAM,kBAAkB,OAAO,CAAC;EAC9C;CACF,QAAQ;EAGN,OAAO,UAAU,SAAS,IAAI,OAAQ;CACxC;AACF;;;;;;;;;;;;;;;;;;;;;;;ACzBA,eAAsB,YAAe,QAAgB,IAAiD;CACpG,MAAM,MAAM,MAAM,QAAQ,KAAK,OAAO,GAAG,GAAG,OAAO,EAAE,CAAC;CACtD,IAAI;EACF,OAAO,MAAM,GAAG,GAAG;CACrB,UAAU;EACR,MAAM,GAAG,KAAK;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;CAChD;AACF"}

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/node
 
 > Tree-shakable TypeScript utility functions for the `node` domain.
-> Package: `@helpers4/node` — Version: 3.1.2
+> Package: `@helpers4/node` — Version: 3.1.4
 > License: LGPL-3.0-or-later
 
 ## Installation

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "node",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "functions": [
     {
       "name": "isBuffer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/node",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for node.",
   "author": "baxyz <craft@baxyz.dev>",
   "license": "LGPL-3.0",