@socketsecurity/lib 6.0.2 → 6.0.4

package/dist/fs/read-json.js

@@ -1,192 +1,177 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var read_json_exports = {};
-__export(read_json_exports, {
-  clearReadJsonCache: () => import_read_json_cache.clearReadJsonCache,
-  getReadJsonCacheStats: () => import_read_json_cache.getReadJsonCacheStats,
-  readJson: () => readJson,
-  readJsonSync: () => readJsonSync,
-  setReadJsonCacheMax: () => import_read_json_cache.setReadJsonCacheMax,
-  setReadJsonCacheTtlMs: () => import_read_json_cache.setReadJsonCacheTtlMs
-});
-module.exports = __toCommonJS(read_json_exports);
-var import_read_json_cache = require("./read-json-cache");
-var import_parse = require("../json/parse");
-var import_fs = require("../node/fs");
-var import_error = require("../primordials/error");
-var import_number = require("../primordials/number");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+const require_primordials_number = require('../primordials/number.js');
+const require_node_fs = require('../node/fs.js');
+const require_fs_read_json_cache = require('./read-json-cache.js');
+const require_json_parse = require('../json/parse.js');
+
+//#region src/fs/read-json.ts
+/**
+* @file Read-and-parse helpers for JSON files. Wraps fs reads in actionable
+*   error messages keyed off `ENOENT` / `EACCES` / `EPERM` so callers see "JSON
+*   file not found" / "Permission denied" rather than the bare errno. Both
+*   variants honor `throws: false` to fall back to `undefined` on parse or read
+*   failure. Both variants cache parse results by default — keyed on `path +
+*   ino + size \+ mtimeMs`, with a defensive `structuredClone` on every hit so
+*   callers can mutate the returned object freely. See `_read-json-cache.ts`
+*   for the safety rationale + opt-out controls.
+*/
+/**
+* Read and parse a JSON file asynchronously. Reads the file as UTF-8 text and
+* parses it as JSON. Optionally accepts a reviver function to transform parsed
+* values.
+*
+* @example
+*   ;```ts
+*   // Read and parse package.json
+*   const pkg = await readJson('./package.json')
+*
+*   // Read JSON with custom reviver
+*   const data = await readJson('./data.json', {
+*     reviver: (key, value) => {
+*       if (key === 'date') return new Date(value)
+*       return value
+*     },
+*   })
+*
+*   // Don't throw on parse errors
+*   const config = await readJson('./config.json', { throws: false })
+*   if (config === undefined) {
+*     console.log('Failed to parse config')
+*   }
+*   ```
+*
+* @param filepath - Path to JSON file.
+* @param options - Read and parse options.
+*
+* @returns Promise resolving to parsed JSON value, or undefined if throws is
+*   false and an error occurs.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function readJson(filepath, options) {
-  const opts = typeof options === "string" ? { encoding: options } : options;
-  const { cache, reviver, throws, ...fsOptions } = {
-    __proto__: null,
-    ...opts
-  };
-  const shouldThrow = throws === void 0 || !!throws;
-  const cacheEnabled = cache !== false && reviver === void 0;
-  const fs = (0, import_fs.getNodeFs)();
-  const pathStr = String(filepath);
-  if (cacheEnabled) {
-    try {
-      const stat = await fs.promises.stat(filepath);
-      const cached = (0, import_read_json_cache.getCachedJson)(
-        pathStr,
-        (0, import_number.NumberCtor)(stat.ino),
-        (0, import_number.NumberCtor)(stat.size),
-        (0, import_number.NumberCtor)(stat.mtimeMs)
-      );
-      if (cached !== void 0) {
-        return cached;
-      }
-    } catch {
-    }
-  }
-  let content = "";
-  try {
-    content = await fs.promises.readFile(filepath, {
-      __proto__: null,
-      ...fsOptions,
-      encoding: "utf8"
-    });
-  } catch (e) {
-    if (shouldThrow) {
-      const code = e.code;
-      if (code === "ENOENT") {
-        throw new import_error.ErrorCtor(
-          `JSON file not found: ${filepath}
-Ensure the file exists or create it with the expected structure.`,
-          { cause: e }
-        );
-      }
-      if (code === "EACCES" || code === "EPERM") {
-        throw new import_error.ErrorCtor(
-          `Permission denied reading JSON file: ${filepath}
-Check file permissions or run with appropriate access.`,
-          { cause: e }
-        );
-      }
-      throw e;
-    }
-    return void 0;
-  }
-  const parsed = (0, import_parse.parseJson)(content, {
-    filepath: pathStr,
-    reviver,
-    throws: shouldThrow
-  });
-  if (cacheEnabled && parsed !== void 0) {
-    try {
-      const stat = await fs.promises.stat(filepath);
-      (0, import_read_json_cache.setCachedJson)(
-        pathStr,
-        (0, import_number.NumberCtor)(stat.ino),
-        (0, import_number.NumberCtor)(stat.size),
-        (0, import_number.NumberCtor)(stat.mtimeMs),
-        parsed
-      );
-    } catch {
-    }
-  }
-  return parsed;
+	const { cache, reviver, throws, ...fsOptions } = {
+		__proto__: null,
+		...typeof options === "string" ? { encoding: options } : options
+	};
+	const shouldThrow = throws === void 0 || !!throws;
+	const cacheEnabled = cache !== false && reviver === void 0;
+	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	const pathStr = String(filepath);
+	if (cacheEnabled) try {
+		const stat = await fs.promises.stat(filepath);
+		const cached = require_fs_read_json_cache.getCachedJson(pathStr, require_primordials_number.NumberCtor(stat.ino), require_primordials_number.NumberCtor(stat.size), require_primordials_number.NumberCtor(stat.mtimeMs));
+		if (cached !== void 0) return cached;
+	} catch {}
+	let content = "";
+	try {
+		content = await fs.promises.readFile(filepath, {
+			__proto__: null,
+			...fsOptions,
+			encoding: "utf8"
+		});
+	} catch (e) {
+		if (shouldThrow) {
+			const code = e.code;
+			if (code === "ENOENT") throw new require_primordials_error.ErrorCtor(`JSON file not found: ${filepath}\nEnsure the file exists or create it with the expected structure.`, { cause: e });
+			/* c8 ignore start */
+			if (code === "EACCES" || code === "EPERM") throw new require_primordials_error.ErrorCtor(`Permission denied reading JSON file: ${filepath}\nCheck file permissions or run with appropriate access.`, { cause: e });
+			/* c8 ignore stop */
+			throw e;
+		}
+		return;
+	}
+	const parsed = /* @__PURE__ */ require_json_parse.parseJson(content, {
+		filepath: pathStr,
+		reviver,
+		throws: shouldThrow
+	});
+	if (cacheEnabled && parsed !== void 0) try {
+		const stat = await fs.promises.stat(filepath);
+		require_fs_read_json_cache.setCachedJson(pathStr, require_primordials_number.NumberCtor(stat.ino), require_primordials_number.NumberCtor(stat.size), require_primordials_number.NumberCtor(stat.mtimeMs), parsed);
+	} catch {}
+	return parsed;
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Read and parse a JSON file synchronously. Reads the file as UTF-8 text and
+* parses it as JSON. Optionally accepts a reviver function to transform parsed
+* values.
+*
+* @example
+*   ;```ts
+*   // Read and parse tsconfig.json
+*   const tsconfig = readJsonSync('./tsconfig.json')
+*
+*   // Read JSON with custom reviver
+*   const data = readJsonSync('./data.json', {
+*     reviver: (key, value) => {
+*       if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+*         return new Date(value)
+*       }
+*       return value
+*     },
+*   })
+*
+*   // Don't throw on parse errors
+*   const config = readJsonSync('./config.json', { throws: false })
+*   ```
+*
+* @param filepath - Path to JSON file.
+* @param options - Read and parse options.
+*
+* @returns Parsed JSON value, or undefined if throws is false and an error
+*   occurs.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function readJsonSync(filepath, options) {
-  const opts = typeof options === "string" ? { encoding: options } : options;
-  const { cache, reviver, throws, ...fsOptions } = {
-    __proto__: null,
-    ...opts
-  };
-  const shouldThrow = throws === void 0 || !!throws;
-  const cacheEnabled = cache !== false && reviver === void 0;
-  const fs = (0, import_fs.getNodeFs)();
-  const pathStr = String(filepath);
-  if (cacheEnabled) {
-    try {
-      const stat = fs.statSync(filepath);
-      const cached = (0, import_read_json_cache.getCachedJson)(
-        pathStr,
-        (0, import_number.NumberCtor)(stat.ino),
-        (0, import_number.NumberCtor)(stat.size),
-        (0, import_number.NumberCtor)(stat.mtimeMs)
-      );
-      if (cached !== void 0) {
-        return cached;
-      }
-    } catch {
-    }
-  }
-  let content = "";
-  try {
-    content = fs.readFileSync(filepath, {
-      __proto__: null,
-      ...fsOptions,
-      encoding: "utf8"
-    });
-  } catch (e) {
-    if (shouldThrow) {
-      const code = e.code;
-      if (code === "ENOENT") {
-        throw new import_error.ErrorCtor(
-          `JSON file not found: ${filepath}
-Ensure the file exists or create it with the expected structure.`,
-          { cause: e }
-        );
-      }
-      if (code === "EACCES" || code === "EPERM") {
-        throw new import_error.ErrorCtor(
-          `Permission denied reading JSON file: ${filepath}
-Check file permissions or run with appropriate access.`,
-          { cause: e }
-        );
-      }
-      throw e;
-    }
-    return void 0;
-  }
-  const parsed = (0, import_parse.parseJson)(content, {
-    filepath: pathStr,
-    reviver,
-    throws: shouldThrow
-  });
-  if (cacheEnabled && parsed !== void 0) {
-    try {
-      const stat = fs.statSync(filepath);
-      (0, import_read_json_cache.setCachedJson)(
-        pathStr,
-        (0, import_number.NumberCtor)(stat.ino),
-        (0, import_number.NumberCtor)(stat.size),
-        (0, import_number.NumberCtor)(stat.mtimeMs),
-        parsed
-      );
-    } catch {
-    }
-  }
-  return parsed;
+	const { cache, reviver, throws, ...fsOptions } = {
+		__proto__: null,
+		...typeof options === "string" ? { encoding: options } : options
+	};
+	const shouldThrow = throws === void 0 || !!throws;
+	const cacheEnabled = cache !== false && reviver === void 0;
+	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	const pathStr = String(filepath);
+	if (cacheEnabled) try {
+		const stat = fs.statSync(filepath);
+		const cached = require_fs_read_json_cache.getCachedJson(pathStr, require_primordials_number.NumberCtor(stat.ino), require_primordials_number.NumberCtor(stat.size), require_primordials_number.NumberCtor(stat.mtimeMs));
+		if (cached !== void 0) return cached;
+	} catch {}
+	let content = "";
+	try {
+		content = fs.readFileSync(filepath, {
+			__proto__: null,
+			...fsOptions,
+			encoding: "utf8"
+		});
+	} catch (e) {
+		if (shouldThrow) {
+			const code = e.code;
+			if (code === "ENOENT") throw new require_primordials_error.ErrorCtor(`JSON file not found: ${filepath}\nEnsure the file exists or create it with the expected structure.`, { cause: e });
+			/* c8 ignore start */
+			if (code === "EACCES" || code === "EPERM") throw new require_primordials_error.ErrorCtor(`Permission denied reading JSON file: ${filepath}\nCheck file permissions or run with appropriate access.`, { cause: e });
+			/* c8 ignore stop */
+			throw e;
+		}
+		return;
+	}
+	const parsed = /* @__PURE__ */ require_json_parse.parseJson(content, {
+		filepath: pathStr,
+		reviver,
+		throws: shouldThrow
+	});
+	if (cacheEnabled && parsed !== void 0) try {
+		const stat = fs.statSync(filepath);
+		require_fs_read_json_cache.setCachedJson(pathStr, require_primordials_number.NumberCtor(stat.ino), require_primordials_number.NumberCtor(stat.size), require_primordials_number.NumberCtor(stat.mtimeMs), parsed);
+	} catch {}
+	return parsed;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  clearReadJsonCache,
-  getReadJsonCacheStats,
-  readJson,
-  readJsonSync,
-  setReadJsonCacheMax,
-  setReadJsonCacheTtlMs
-});
+
+//#endregion
+exports.clearReadJsonCache = require_fs_read_json_cache.clearReadJsonCache;
+exports.getReadJsonCacheStats = require_fs_read_json_cache.getReadJsonCacheStats;
+exports.readJson = readJson;
+exports.readJsonSync = readJsonSync;
+exports.setReadJsonCacheMax = require_fs_read_json_cache.setReadJsonCacheMax;
+exports.setReadJsonCacheTtlMs = require_fs_read_json_cache.setReadJsonCacheTtlMs;

package/dist/fs/resolve-module.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file `require.resolve`-from-an-arbitrary-base. Node's bare
+ *   `require.resolve(spec)` resolves relative to the calling module; these
+ *   helpers resolve a specifier as if required from a DIFFERENT directory —
+ *   useful for "find the copy of `typescript` that THIS project would load,"
+ *   not the copy socket-lib itself loads. Returns the resolved absolute file
+ *   path, or (in `nothrow` form) `undefined` when the specifier can't be
+ *   resolved.
+ */
+/**
+ * Resolve a module specifier as if `require`'d from `fromDir`.
+ *
+ * Equivalent to running `require.resolve(specifier)` inside a module located at
+ * `fromDir`. Accepts package specifiers (`'typescript'`, `'pkg/sub/path'`) and
+ * relative paths (`'./foo'`).
+ *
+ * @example
+ *   ;```ts
+ *   // The `typescript` the project at /repo would load:
+ *   requireResolveFrom('/repo', 'typescript')
+ *   //=> '/repo/node_modules/typescript/lib/typescript.js'
+ *
+ *   requireResolveFrom('/repo', './missing', { nothrow: true })
+ *   //=> undefined
+ *   ```
+ *
+ * @param fromDir - Directory to resolve as if the require originated there.
+ * @param specifier - Module specifier or relative path to resolve.
+ * @param options - `nothrow: true` returns `undefined` instead of throwing.
+ *
+ * @returns Absolute resolved path (or `undefined` when `nothrow` and
+ *   unresolved).
+ *
+ * @throws When the specifier can't be resolved and `nothrow` is not set.
+ */
+export declare function requireResolveFrom(fromDir: string, specifier: string, options: {
+    nothrow: true;
+}): string | undefined;
+export declare function requireResolveFrom(fromDir: string, specifier: string, options?: {
+    nothrow?: false | undefined;
+} | undefined): string;
+/**
+ * Resolve a module specifier as if `require`'d from `process.cwd()`. Alias for
+ * {@link requireResolveFrom} anchored at the current directory.
+ *
+ * @param specifier - Module specifier or relative path to resolve.
+ * @param options - `nothrow: true` returns `undefined` instead of throwing.
+ *
+ * @returns Absolute resolved path (or `undefined` when `nothrow` and
+ *   unresolved).
+ */
+export declare function requireResolveFromCwd(specifier: string, options: {
+    nothrow: true;
+}): string | undefined;
+export declare function requireResolveFromCwd(specifier: string, options?: {
+    nothrow?: false | undefined;
+} | undefined): string;

package/dist/fs/resolve-module.js

@@ -0,0 +1,40 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_node_path = require('../node/path.js');
+let node_module = require("node:module");
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+
+//#region src/fs/resolve-module.ts
+/**
+* @file `require.resolve`-from-an-arbitrary-base. Node's bare
+*   `require.resolve(spec)` resolves relative to the calling module; these
+*   helpers resolve a specifier as if required from a DIFFERENT directory —
+*   useful for "find the copy of `typescript` that THIS project would load,"
+*   not the copy socket-lib itself loads. Returns the resolved absolute file
+*   path, or (in `nothrow` form) `undefined` when the specifier can't be
+*   resolved.
+*/
+function requireResolveFrom(fromDir, specifier, options) {
+	const { nothrow = false } = {
+		__proto__: null,
+		...options
+	};
+	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const anchor = path.join(path.resolve(fromDir), "noop.js");
+	try {
+		return (0, node_module.createRequire)(anchor).resolve(specifier);
+	} catch (e) {
+		if (nothrow) return;
+		throw e;
+	}
+}
+function requireResolveFromCwd(specifier, options) {
+	return options && options.nothrow ? requireResolveFrom(node_process.default.cwd(), specifier, { nothrow: true }) : requireResolveFrom(node_process.default.cwd(), specifier);
+}
+
+//#endregion
+exports.requireResolveFrom = requireResolveFrom;
+exports.requireResolveFromCwd = requireResolveFromCwd;