@helpers4/node 3.1.8 → 3.1.10

package/README.md

@@ -43,6 +43,7 @@ A set of helpers for working with URLs.
 - [number](../number)
 - [object](../object)
 - [observable](../observable)
+- [package](../package)
 - [promise](../promise)
 - [set](../set)
 - [string](../string)
@@ -59,7 +60,7 @@ A set of helpers for working with URLs.
 |------|---------|-------------|-------------|
 | animation | [@helpers4/animation](https://www.npmjs.com/package/@helpers4/animation) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/animation) | Timing and interpolation for animations |
 | array | [@helpers4/array](https://www.npmjs.com/package/@helpers4/array) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/array) | Array manipulation utilities |
-| binary | [@helpers4/binary](https://www.npmjs.com/package/@helpers4/binary) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/binary) | Read and write binary formats |
+| binary | [@helpers4/binary](https://www.npmjs.com/package/@helpers4/binary) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/binary) | Read, write and identify binary formats |
 | browser | [@helpers4/browser](https://www.npmjs.com/package/@helpers4/browser) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/browser) | Browser-specific utilities |
 | ci | [@helpers4/ci](https://www.npmjs.com/package/@helpers4/ci) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/ci) | CI/CD workflow status utilities |
 | color | [@helpers4/color](https://www.npmjs.com/package/@helpers4/color) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/color) | Color conversion and validation utilities |
@@ -79,6 +80,7 @@ A set of helpers for working with URLs.
 | number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | Number utility functions and validation |
 | object | [@helpers4/object](https://www.npmjs.com/package/@helpers4/object) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/object) | Object manipulation utilities |
 | observable | [@helpers4/observable](https://www.npmjs.com/package/@helpers4/observable) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/observable) | Observable utilities and combinators |
+| package | [@helpers4/package](https://www.npmjs.com/package/@helpers4/package) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/package) | Package metadata parsers |
 | promise | [@helpers4/promise](https://www.npmjs.com/package/@helpers4/promise) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/promise) | Promise utilities and error handling |
 | set | [@helpers4/set](https://www.npmjs.com/package/@helpers4/set) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/set) | Native Set manipulation utilities |
 | string | [@helpers4/string](https://www.npmjs.com/package/@helpers4/string) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/string) | String manipulation and formatting utilities |

package/lib/index.js

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-//#region helpers/node/isBuffer.ts
+// helpers/node/isBuffer.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -29,8 +29,7 @@ import { join } from "node:path";
 function isBuffer(value) {
 	return typeof Buffer !== "undefined" && value instanceof Buffer;
 }
-//#endregion
-//#region helpers/node/isNodeStream.ts
+// helpers/node/isNodeStream.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -55,8 +54,7 @@ function isBuffer(value) {
 function isNodeStream(value) {
 	return value !== null && typeof value === "object" && typeof value["pipe"] === "function";
 }
-//#endregion
-//#region helpers/node/isSharedArrayBuffer.ts
+// helpers/node/isSharedArrayBuffer.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -80,8 +78,7 @@ function isNodeStream(value) {
 function isSharedArrayBuffer(value) {
 	return typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
 }
-//#endregion
-//#region helpers/_shared/_stripJsonComments.ts
+// helpers/_shared/_stripJsonComments.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -175,8 +172,7 @@ function stripJsonComments(input) {
 	flushPendingComma();
 	return output;
 }
-//#endregion
-//#region helpers/node/safeReadJsonFile.ts
+// helpers/node/safeReadJsonFile.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -194,8 +190,7 @@ function safeReadJsonFile(filePath, fallback) {
 		return arguments.length < 2 ? null : fallback;
 	}
 }
-//#endregion
-//#region helpers/node/withTempDir.ts
+// helpers/node/withTempDir.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -227,7 +222,6 @@ async function withTempDir(prefix, fn) {
 		});
 	}
 }
-//#endregion
 export { isBuffer, isNodeStream, isSharedArrayBuffer, safeReadJsonFile, withTempDir };
 
 //# 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","../../../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 * @returns The parsed value typed as `T`, or `null` on failure (pass a `fallback` to get it instead)\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;\n/**\n * Overload taking a `fallback`: returns it instead of `null` on invalid input.\n *\n * @param filePath - Path to the JSON (or JSONC) file to read\n * @param fallback - Value returned on failure\n * @returns The parsed value typed as `T`, or `fallback` on failure\n * @since 3.0.6\n */\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;;;;;;;;AC/EA,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;;;;;;;;;;;;;;;;;;;;;;;AChCA,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 * @returns The parsed value typed as `T`, or `null` on failure (pass a `fallback` to get it instead)\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;\n/**\n * Overload taking a `fallback`: returns it instead of `null` on invalid input.\n *\n * @param filePath - Path to the JSON (or JSONC) file to read\n * @param fallback - Value returned on failure\n * @returns The parsed value typed as `T`, or `fallback` on failure\n * @since 3.0.6\n */\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;;;;;;;AC/EA,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;;;;;;;;;;;;;;;;;;;;;;AChCA,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.8
+> Package: `@helpers4/node` — Version: 3.1.10
 > License: LGPL-3.0-or-later
 
 ## Installation

package/meta/api.json

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

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@helpers4/node",
-  "version": "3.1.8",
+  "version": "3.1.10",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for node.",
   "author": "baxyz <craft@baxyz.dev>",
-  "license": "LGPL-3.0",
+  "license": "LGPL-3.0-or-later",
   "homepage": "https://helpers4.dev/typescript/categories/node/",
   "repository": {
     "type": "git",