@helpers4/node 3.0.5 → 3.0.6

package/README.md

@@ -15,6 +15,7 @@ A set of helpers for working with URLs.
 - isBuffer
 - isNodeStream
 - isSharedArrayBuffer
+- safeReadJsonFile
 <!-- /AUTOMATIC-METHODS -->
 
 ## See

package/lib/index.d.ts

@@ -70,4 +70,36 @@ declare function isNodeStream(value: unknown): value is {
  */
 declare function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer;
 
-export { isBuffer, isNodeStream, isSharedArrayBuffer };
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Reads a file and parses its contents as JSON, returning `null` (or a
+ * fallback) on any failure — a missing/unreadable file and invalid content
+ * are both treated the same way.
+ *
+ * Also tolerates JSONC (line/block comments and trailing commas — the
+ * dialect used by `tsconfig.json`, VS Code's `settings.json`, etc.): strict
+ * `JSON.parse` is tried first, and only on failure is the content re-parsed
+ * with comments/trailing commas stripped, so plain JSON pays no extra cost.
+ *
+ * Unlike `readFileSync` + `JSON.parse`, this never throws.
+ *
+ * @param filePath - Path to the JSON (or JSONC) file to read.
+ * @param fallback - Value returned on failure. Defaults to `null` when omitted.
+ * @returns The parsed value typed as `T`, or `fallback` on failure.
+ * @example
+ * safeReadJsonFile<{ name: string }>('./package.json') // => { name: 'helpers4', ... }
+ * safeReadJsonFile('./missing.json')                   // => null
+ * safeReadJsonFile('./missing.json', {})               // => {}
+ * @example
+ * // tsconfig.json-style JSONC (comments + trailing comma) also parses:
+ * safeReadJsonFile('./tsconfig.json') // => { compilerOptions: { strict: true }, ... }
+ * @since 3.0.6
+ */
+declare function safeReadJsonFile<T>(filePath: string): T | null;
+declare function safeReadJsonFile<T>(filePath: string, fallback: T): T;
+
+export { isBuffer, isNodeStream, isSharedArrayBuffer, safeReadJsonFile };

package/lib/index.js

@@ -1,3 +1,6 @@
+//#region \0rolldown/runtime.js
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+//#endregion
 //#region helpers/node/isBuffer.ts
 /**
 * This file is part of helpers4.
@@ -77,6 +80,114 @@ function isSharedArrayBuffer(value) {
 	return typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
 }
 //#endregion
-export { isBuffer, isNodeStream, isSharedArrayBuffer };
+//#region helpers/node/_stripJsonComments.ts
+var import___vite_browser_external = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
+	module.exports = {};
+})))();
+/**
+* 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.
+*/
+/**
+* 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.
+* @ignore
+*/
+function stripJsonComments(input) {
+	let output = "";
+	let inString = false;
+	let pendingComma = "";
+	const flushPendingComma = () => {
+		if (pendingComma) {
+			output += pendingComma;
+			pendingComma = "";
+		}
+	};
+	let i = 0;
+	while (i < input.length) {
+		const char = input[i];
+		if (inString) {
+			output += char;
+			if (char === "\\") {
+				i++;
+				if (i < input.length) output += input[i];
+			} else if (char === "\"") inString = false;
+			i++;
+			continue;
+		}
+		if (char === "\"") {
+			flushPendingComma();
+			inString = true;
+			output += char;
+			i++;
+			continue;
+		}
+		if (char === "/" && input[i + 1] === "/") {
+			i += 2;
+			while (i < input.length && input[i] !== "\n" && input[i] !== "\r") i++;
+			continue;
+		}
+		if (char === "/" && input[i + 1] === "*") {
+			i += 2;
+			while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+			i += 2;
+			continue;
+		}
+		if (char === ",") {
+			flushPendingComma();
+			pendingComma = char;
+			i++;
+			continue;
+		}
+		if (char === "}" || char === "]") {
+			pendingComma = "";
+			output += char;
+			i++;
+			continue;
+		}
+		if (char === " " || char === "	" || char === "\n" || char === "\r") {
+			if (pendingComma) pendingComma += char;
+			else output += char;
+			i++;
+			continue;
+		}
+		flushPendingComma();
+		output += char;
+		i++;
+	}
+	flushPendingComma();
+	return output;
+}
+//#endregion
+//#region helpers/node/safeReadJsonFile.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function safeReadJsonFile(filePath, fallback) {
+	try {
+		const content = (0, import___vite_browser_external.readFileSync)(filePath, "utf-8");
+		try {
+			return JSON.parse(content);
+		} catch {
+			return JSON.parse(stripJsonComments(content));
+		}
+	} catch {
+		return arguments.length < 2 ? null : fallback;
+	}
+}
+//#endregion
+export { isBuffer, isNodeStream, isSharedArrayBuffer, safeReadJsonFile };
 
 //# sourceMappingURL=index.js.map

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"],"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"],"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/node/isBuffer.ts","../../../helpers/node/isNodeStream.ts","../../../helpers/node/isSharedArrayBuffer.ts","../../../__vite-browser-external","../../../helpers/node/_stripJsonComments.ts","../../../helpers/node/safeReadJsonFile.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","module.exports = {}","/**\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"],"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;;;;CCvBA,OAAO,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;ACoBlB,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,WAAA,GAAA,+BAAA,aAAA,CAAuB,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"}

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/node
 
 > Tree-shakable TypeScript utility functions for the `node` domain.
-> Package: `@helpers4/node` — Version: 3.0.5
+> Package: `@helpers4/node` — Version: 3.0.6
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,7 +15,7 @@ pnpm add @helpers4/node
 ## Usage
 
 ```typescript
-import { isBuffer, isNodeStream, isSharedArrayBuffer } from '@helpers4/node';
+import { isBuffer, isNodeStream, isSharedArrayBuffer, ... } from '@helpers4/node';
 ```
 
 ## Functions
@@ -25,6 +25,7 @@ import { isBuffer, isNodeStream, isSharedArrayBuffer } from '@helpers4/node';
 | `isBuffer` | Checks if a value is a Node.js Buffer instance.  `Buffer` extends `Uint8Array` and is specific to No |
 | `isNodeStream` | Checks if a value is a Node.js stream (has a `.pipe()` method).  Uses duck-typing: any object with a |
 | `isSharedArrayBuffer` | Checks if a value is a `SharedArrayBuffer` instance.  `SharedArrayBuffer` enables shared memory betw |
+| `safeReadJsonFile` | Reads a file and parses its contents as JSON, returning `null` (or a fallback) on any failure — a mi |
 
 ---
 
@@ -173,3 +174,85 @@ function sendToWorker(buffer: unknown): void {
 ```
 
 ---
+
+### `safeReadJsonFile`
+
+Reads a file and parses its contents as JSON, returning `null` (or a
+fallback) on any failure — a missing/unreadable file and invalid content
+are both treated the same way.
+
+Also tolerates JSONC (line/block comments and trailing commas — the
+dialect used by `tsconfig.json`, VS Code's `settings.json`, etc.): strict
+`JSON.parse` is tried first, and only on failure is the content re-parsed
+with comments/trailing commas stripped, so plain JSON pays no extra cost.
+
+Unlike `readFileSync` + `JSON.parse`, this never throws.
+
+```typescript
+import { safeReadJsonFile } from '@helpers4/node';
+
+safeReadJsonFile<T>(filePath: string): T | null
+```
+
+**Parameters:**
+
+- `filePath: string` — Path to the JSON (or JSONC) file to read.
+
+**Returns:** `T | null` — The parsed value typed as `T`, or `fallback` on failure.
+
+```typescript
+import { safeReadJsonFile } from '@helpers4/node';
+
+safeReadJsonFile<T>(filePath: string, fallback: T): T
+```
+
+**Parameters:**
+
+- `filePath: string` — Path to the JSON (or JSONC) file to read.
+- `fallback: T` — Value returned on failure. Defaults to `null` when omitted.
+
+**Returns:** `T` — The parsed value typed as `T`, or `fallback` on failure.
+
+**Examples:**
+
+*Read and parse a JSON file*
+
+Returns the parsed value when the file exists and contains valid JSON.
+
+```typescript
+safeReadJsonFile<{ name: string }>('./package.json')
+// => { name: 'my-package', ... }
+```
+
+*Return null when the file is missing*
+
+Returns null instead of throwing when the file does not exist.
+
+```typescript
+safeReadJsonFile('./does-not-exist.json')
+// => null
+```
+
+*Use a fallback value*
+
+Returns the provided fallback when the file is missing or invalid.
+
+```typescript
+safeReadJsonFile('./does-not-exist.json', {})
+// => {}
+```
+
+*Also reads JSONC (comments + trailing commas)*
+
+tsconfig.json/settings.json-style content — line/block comments and a trailing comma — parses too.
+
+```typescript
+safeReadJsonFile('./tsconfig.json')
+// {
+//   // enable strict type-checking
+//   "compilerOptions": { "strict": true },
+// }
+// => { compilerOptions: { strict: true } }
+```
+
+---

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "node",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "functions": [
     {
       "name": "isBuffer",
@@ -109,6 +109,82 @@
         }
       ],
       "sourceFile": "isSharedArrayBuffer.ts"
+    },
+    {
+      "name": "safeReadJsonFile",
+      "kind": "function",
+      "description": "Reads a file and parses its contents as JSON, returning `null` (or a\nfallback) on any failure — a missing/unreadable file and invalid content\nare both treated the same way.\n\nAlso tolerates JSONC (line/block comments and trailing commas — the\ndialect 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\nwith comments/trailing commas stripped, so plain JSON pays no extra cost.\n\nUnlike `readFileSync` + `JSON.parse`, this never throws.",
+      "since": "3.0.6",
+      "signatures": [
+        {
+          "signature": "safeReadJsonFile<T>(filePath: string): T | null",
+          "description": "Reads a file and parses its contents as JSON, returning `null` (or a\nfallback) on any failure — a missing/unreadable file and invalid content\nare both treated the same way.\n\nAlso tolerates JSONC (line/block comments and trailing commas — the\ndialect 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\nwith comments/trailing commas stripped, so plain JSON pays no extra cost.\n\nUnlike `readFileSync` + `JSON.parse`, this never throws.",
+          "params": [
+            {
+              "name": "filePath",
+              "type": "string",
+              "description": "Path to the JSON (or JSONC) file to read."
+            }
+          ],
+          "returns": {
+            "type": "T | null",
+            "description": "The parsed value typed as `T`, or `fallback` on failure."
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        },
+        {
+          "signature": "safeReadJsonFile<T>(filePath: string, fallback: T): T",
+          "description": "Reads a file and parses its contents as JSON, returning `null` (or a\nfallback) on any failure — a missing/unreadable file and invalid content\nare both treated the same way.\n\nAlso tolerates JSONC (line/block comments and trailing commas — the\ndialect 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\nwith comments/trailing commas stripped, so plain JSON pays no extra cost.\n\nUnlike `readFileSync` + `JSON.parse`, this never throws.",
+          "params": [
+            {
+              "name": "filePath",
+              "type": "string",
+              "description": "Path to the JSON (or JSONC) file to read."
+            },
+            {
+              "name": "fallback",
+              "type": "T",
+              "description": "Value returned on failure. Defaults to `null` when omitted."
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "The parsed value typed as `T`, or `fallback` on failure."
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Read and parse a JSON file",
+          "description": "Returns the parsed value when the file exists and contains valid JSON.",
+          "code": "safeReadJsonFile<{ name: string }>('./package.json')\n// => { name: 'my-package', ... }"
+        },
+        {
+          "title": "Return null when the file is missing",
+          "description": "Returns null instead of throwing when the file does not exist.",
+          "code": "safeReadJsonFile('./does-not-exist.json')\n// => null"
+        },
+        {
+          "title": "Use a fallback value",
+          "description": "Returns the provided fallback when the file is missing or invalid.",
+          "code": "safeReadJsonFile('./does-not-exist.json', {})\n// => {}"
+        },
+        {
+          "title": "Also reads JSONC (comments + trailing commas)",
+          "description": "tsconfig.json/settings.json-style content — line/block comments and a trailing comma — parses too.",
+          "code": "safeReadJsonFile('./tsconfig.json')\n// {\n//   // enable strict type-checking\n//   \"compilerOptions\": { \"strict\": true },\n// }\n// => { compilerOptions: { strict: true } }"
+        }
+      ],
+      "sourceFile": "safeReadJsonFile.ts"
     }
   ]
 }

package/meta/examples.json

@@ -45,6 +45,31 @@
           "code": "function sendToWorker(buffer: unknown): void {\n  if (isSharedArrayBuffer(buffer)) {\n    // buffer is SharedArrayBuffer — can be shared directly\n    // worker.postMessage({ buffer });\n  } else {\n    // must transfer or copy\n  }\n}"
         }
       ]
+    },
+    {
+      "name": "safeReadJsonFile",
+      "examples": [
+        {
+          "title": "Read and parse a JSON file",
+          "description": "Returns the parsed value when the file exists and contains valid JSON.",
+          "code": "safeReadJsonFile<{ name: string }>('./package.json')\n// => { name: 'my-package', ... }"
+        },
+        {
+          "title": "Return null when the file is missing",
+          "description": "Returns null instead of throwing when the file does not exist.",
+          "code": "safeReadJsonFile('./does-not-exist.json')\n// => null"
+        },
+        {
+          "title": "Use a fallback value",
+          "description": "Returns the provided fallback when the file is missing or invalid.",
+          "code": "safeReadJsonFile('./does-not-exist.json', {})\n// => {}"
+        },
+        {
+          "title": "Also reads JSONC (comments + trailing commas)",
+          "description": "tsconfig.json/settings.json-style content — line/block comments and a trailing comma — parses too.",
+          "code": "safeReadJsonFile('./tsconfig.json')\n// {\n//   // enable strict type-checking\n//   \"compilerOptions\": { \"strict\": true },\n// }\n// => { compilerOptions: { strict: true } }"
+        }
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/node",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for node.",
   "author": "baxyz <craft@baxyz.dev>",
   "license": "LGPL-3.0",
@@ -29,7 +29,8 @@
     "node",
     "isBuffer",
     "isNodeStream",
-    "isSharedArrayBuffer"
+    "isSharedArrayBuffer",
+    "safeReadJsonFile"
   ],
   "files": [
     "lib/index.js",