@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/fs/read-file.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @file File-content readers — UTF-8 / binary / safe variants (sync + async).
+ *   The `safe*` versions trap errors and return `undefined` (or a
+ *   caller-supplied `defaultValue`) so they fit the non-throwing-fallback shape
+ *   used elsewhere in the lib. The encoding `null` overload returns a `Buffer`;
+ *   the default and any string encoding return a string. The runtime fast-path
+ *   normalizes encoding once and forwards untouched options to `node:fs`.
+ */
+import type { PathLike } from 'node:fs';
+import type { ReadFileOptions, SafeReadOptions } from './types';
+/**
+ * Read a file as binary data asynchronously. Returns a Buffer without encoding
+ * the contents. Useful for reading images, archives, or other binary formats.
+ *
+ * @example
+ *   ;```ts
+ *   // Read an image file
+ *   const imageBuffer = await readFileBinary('./image.png')
+ *
+ *   // Read with abort signal
+ *   const buffer = await readFileBinary('./data.bin', { signal: abortSignal })
+ *   ```
+ *
+ * @param filepath - Path to file.
+ * @param options - Read options (encoding is forced to null for binary)
+ *
+ * @returns Promise resolving to Buffer containing file contents
+ */
+export declare function readFileBinary(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<NonSharedBuffer>;
+/**
+ * Read a file as binary data synchronously. Returns a Buffer without encoding
+ * the contents. Useful for reading images, archives, or other binary formats.
+ *
+ * @example
+ *   ;```ts
+ *   // Read an image file
+ *   const imageBuffer = readFileBinarySync('./logo.png')
+ *
+ *   // Read a compressed file
+ *   const gzipData = readFileBinarySync('./archive.gz')
+ *   ```
+ *
+ * @param filepath - Path to file.
+ * @param options - Read options (encoding is forced to null for binary)
+ *
+ * @returns Buffer containing file contents
+ */
+export declare function readFileBinarySync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
+/**
+ * Read a file as UTF-8 text asynchronously. Returns a string with the file
+ * contents decoded as UTF-8. This is the most common way to read text files.
+ *
+ * @example
+ *   ;```ts
+ *   // Read a text file
+ *   const content = await readFileUtf8('./README.md')
+ *
+ *   // Read with custom encoding
+ *   const content = await readFileUtf8('./data.txt', { encoding: 'utf-8' })
+ *   ```
+ *
+ * @param filepath - Path to file.
+ * @param options - Read options including encoding and abort signal.
+ *
+ * @returns Promise resolving to string containing file contents
+ */
+export declare function readFileUtf8(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<string>;
+/**
+ * Read a file as UTF-8 text synchronously. Returns a string with the file
+ * contents decoded as UTF-8. This is the most common way to read text files
+ * synchronously.
+ *
+ * @example
+ *   ;```ts
+ *   // Read a configuration file
+ *   const config = readFileUtf8Sync('./config.txt')
+ *
+ *   // Read with custom options
+ *   const data = readFileUtf8Sync('./data.txt', { encoding: 'utf8' })
+ *   ```
+ *
+ * @param filepath - Path to file.
+ * @param options - Read options including encoding.
+ *
+ * @returns String containing file contents
+ */
+export declare function readFileUtf8Sync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
+/**
+ * Safely read a file asynchronously, returning undefined on error. Useful when
+ * you want to attempt reading a file without handling errors explicitly.
+ * Returns undefined for any error (file not found, permission denied, etc.).
+ * Defaults to UTF-8 encoding, returning a string unless encoding is explicitly
+ * set to null.
+ *
+ * @example
+ *   ;```ts
+ *   // Try to read a file as UTF-8 string (default), get undefined if it doesn't exist
+ *   const content = await safeReadFile('./optional-config.txt')
+ *   if (content) {
+ *     console.log('Config found:', content)
+ *   }
+ *
+ *   // Read with specific encoding
+ *   const data = await safeReadFile('./data.txt', { encoding: 'utf8' })
+ *
+ *   // Read as Buffer by setting encoding to null
+ *   const buffer = await safeReadFile('./binary.dat', { encoding: null })
+ *   ```
+ *
+ * @param filepath - Path to file.
+ * @param options - Read options including encoding and default value.
+ *
+ * @returns Promise resolving to file contents (string by default), or undefined
+ *   on error.
+ */
+export declare function safeReadFile(filepath: PathLike, options: SafeReadOptions & {
+    encoding: null;
+}): Promise<Buffer | undefined>;
+export declare function safeReadFile(filepath: PathLike, options?: SafeReadOptions | undefined): Promise<string | undefined>;
+/**
+ * Safely read a file synchronously, returning undefined on error. Useful when
+ * you want to attempt reading a file without handling errors explicitly.
+ * Returns undefined for any error (file not found, permission denied, etc.).
+ * Defaults to UTF-8 encoding, returning a string unless encoding is explicitly
+ * set to null.
+ *
+ * @example
+ *   ;```ts
+ *   // Try to read a config file as UTF-8 string (default)
+ *   const config = safeReadFileSync('./config.txt')
+ *   if (config) {
+ *     console.log('Config loaded successfully')
+ *   }
+ *
+ *   // Read with explicit encoding
+ *   const data = safeReadFileSync('./data.txt', { encoding: 'utf8' })
+ *
+ *   // Read binary file by setting encoding to null
+ *   const buffer = safeReadFileSync('./image.png', { encoding: null })
+ *   ```
+ *
+ * @param filepath - Path to file.
+ * @param options - Read options including encoding and default value.
+ *
+ * @returns File contents (string by default), or undefined on error
+ */
+export declare function safeReadFileSync(filepath: PathLike, options: SafeReadOptions & {
+    encoding: null;
+}): Buffer | undefined;
+export declare function safeReadFileSync(filepath: PathLike, options?: SafeReadOptions | undefined): string | undefined;

package/dist/fs/read-file.js

@@ -0,0 +1,131 @@
+"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_file_exports = {};
+__export(read_file_exports, {
+  readFileBinary: () => readFileBinary,
+  readFileBinarySync: () => readFileBinarySync,
+  readFileUtf8: () => readFileUtf8,
+  readFileUtf8Sync: () => readFileUtf8Sync,
+  safeReadFile: () => safeReadFile,
+  safeReadFileSync: () => safeReadFileSync
+});
+module.exports = __toCommonJS(read_file_exports);
+var import_abort = require("../process/abort");
+var import_fs = require("../node/fs");
+var import_buffer = require("../primordials/buffer");
+var import_encoding = require("./encoding");
+const abortSignal = (0, import_abort.getAbortSignal)();
+// @__NO_SIDE_EFFECTS__
+async function readFileBinary(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const fs = (0, import_fs.getNodeFs)();
+  return await fs.promises.readFile(filepath, {
+    signal: abortSignal,
+    ...opts,
+    encoding: void 0
+  });
+}
+// @__NO_SIDE_EFFECTS__
+function readFileBinarySync(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const fs = (0, import_fs.getNodeFs)();
+  return fs.readFileSync(filepath, {
+    ...opts,
+    encoding: void 0
+  });
+}
+// @__NO_SIDE_EFFECTS__
+async function readFileUtf8(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const fs = (0, import_fs.getNodeFs)();
+  return await fs.promises.readFile(filepath, {
+    signal: abortSignal,
+    ...opts,
+    encoding: "utf8"
+  });
+}
+// @__NO_SIDE_EFFECTS__
+function readFileUtf8Sync(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const fs = (0, import_fs.getNodeFs)();
+  return fs.readFileSync(filepath, {
+    ...opts,
+    encoding: "utf8"
+  });
+}
+// @__NO_SIDE_EFFECTS__
+async function safeReadFile(filepath, options) {
+  const opts = typeof options === "string" ? { __proto__: null, encoding: options } : { __proto__: null, ...options };
+  const { defaultValue, ...rawReadOpts } = opts;
+  const readOpts = { __proto__: null, ...rawReadOpts };
+  const shouldReturnBuffer = readOpts.encoding === null;
+  const encoding = shouldReturnBuffer ? void 0 : (0, import_encoding.normalizeEncoding)(readOpts.encoding);
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    return await fs.promises.readFile(filepath, {
+      __proto__: null,
+      signal: abortSignal,
+      ...readOpts,
+      encoding
+    });
+  } catch {
+  }
+  if (defaultValue === void 0) {
+    return void 0;
+  }
+  if (shouldReturnBuffer) {
+    return (0, import_buffer.BufferIsBuffer)(defaultValue) ? defaultValue : void 0;
+  }
+  return typeof defaultValue === "string" ? defaultValue : String(defaultValue);
+}
+// @__NO_SIDE_EFFECTS__
+function safeReadFileSync(filepath, options) {
+  const opts = typeof options === "string" ? { __proto__: null, encoding: options } : { __proto__: null, ...options };
+  const { defaultValue, ...rawReadOpts } = opts;
+  const readOpts = { __proto__: null, ...rawReadOpts };
+  const shouldReturnBuffer = readOpts.encoding === null;
+  const encoding = shouldReturnBuffer ? void 0 : (0, import_encoding.normalizeEncoding)(readOpts.encoding);
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    return fs.readFileSync(filepath, {
+      __proto__: null,
+      ...readOpts,
+      encoding
+    });
+  } catch {
+  }
+  if (defaultValue === void 0) {
+    return void 0;
+  }
+  if (shouldReturnBuffer) {
+    return (0, import_buffer.BufferIsBuffer)(defaultValue) ? defaultValue : void 0;
+  }
+  return typeof defaultValue === "string" ? defaultValue : String(defaultValue);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  readFileBinary,
+  readFileBinarySync,
+  readFileUtf8,
+  readFileUtf8Sync,
+  safeReadFile,
+  safeReadFileSync
+});

package/dist/fs/read-json.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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.
+ */
+import type { PathLike } from 'node:fs';
+import type { ReadJsonOptions } from './types';
+/**
+ * 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.
+ */
+export declare function readJson(filepath: PathLike, options?: ReadJsonOptions | string | undefined): Promise<import("../json/types").JsonValue | undefined>;
+/**
+ * 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.
+ */
+export declare function readJsonSync(filepath: PathLike, options?: ReadJsonOptions | string | undefined): import("../json/types").JsonValue | undefined;

package/dist/fs/read-json.js

@@ -0,0 +1,120 @@
+"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, {
+  readJson: () => readJson,
+  readJsonSync: () => readJsonSync
+});
+module.exports = __toCommonJS(read_json_exports);
+var import_parse = require("../json/parse");
+var import_fs = require("../node/fs");
+var import_error = require("../primordials/error");
+// @__NO_SIDE_EFFECTS__
+async function readJson(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const { reviver, throws, ...fsOptions } = {
+    __proto__: null,
+    ...opts
+  };
+  const shouldThrow = throws === void 0 || !!throws;
+  const fs = (0, import_fs.getNodeFs)();
+  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;
+  }
+  return (0, import_parse.parseJson)(content, {
+    filepath: String(filepath),
+    reviver,
+    throws: shouldThrow
+  });
+}
+// @__NO_SIDE_EFFECTS__
+function readJsonSync(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const { reviver, throws, ...fsOptions } = {
+    __proto__: null,
+    ...opts
+  };
+  const shouldThrow = throws === void 0 || !!throws;
+  const fs = (0, import_fs.getNodeFs)();
+  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;
+  }
+  return (0, import_parse.parseJson)(content, {
+    filepath: String(filepath),
+    reviver,
+    throws: shouldThrow
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  readJson,
+  readJsonSync
+});

package/dist/fs/safe.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @file Safe deletion + idempotent directory creation. The delete helpers gate
+ *   destructive operations behind an "allowed directories" allow-list (temp
+ *   dir, cacache dir, ~/.socket); paths outside those need an explicit `force:
+ *   true`. The mkdir helpers default to `recursive: true` and swallow `EEXIST`
+ *   so concurrent callers don't race-condition each other.
+ */
+import './path-cache';
+import type { MakeDirectoryOptions, PathLike } from 'node:fs';
+import type { deleteAsync as deleteAsyncType, deleteSync as deleteSyncType } from '../external/del';
+import type { RemoveOptions } from './types';
+export declare function getDel(): {
+    deleteAsync: typeof deleteAsyncType;
+    deleteSync: typeof deleteSyncType;
+};
+/**
+ * Safely delete a file or directory asynchronously with built-in protections.
+ *
+ * Uses [`del`](https://socket.dev/npm/package/del/overview/8.0.1) for safer
+ * deletion with these safety features:
+ *
+ * - By default, prevents deleting the current working directory (cwd) and above
+ * - Allows deleting within cwd (descendant paths) without force option
+ * - Automatically uses force: true for temp directory, cacache, and ~/.socket
+ *   subdirectories
+ * - Protects against accidental deletion of parent directories via `../` paths
+ *
+ * @example
+ *   ;```ts
+ *   // Delete files within cwd (safe by default)
+ *   await safeDelete('./build')
+ *   await safeDelete('./dist')
+ *
+ *   // Delete with glob patterns
+ *   await safeDelete(['./temp/**', '!./temp/keep.txt'])
+ *
+ *   // Delete with custom retry settings
+ *   await safeDelete('./flaky-dir', { maxRetries: 5, retryDelay: 500 })
+ *
+ *   // Force delete cwd or above (requires explicit force: true)
+ *   await safeDelete('../parent-dir', { force: true })
+ *   ```
+ *
+ * @param filepath - Path or array of paths to delete (supports glob patterns)
+ * @param options - Deletion options including force, retries, and recursion.
+ * @param options.force - Set to true to allow deleting cwd and above (use with
+ *   caution)
+ *
+ * @throws {Error} When attempting to delete protected paths without force
+ *   option.
+ */
+export declare function safeDelete(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): Promise<void>;
+/**
+ * Safely delete a file or directory synchronously with built-in protections.
+ *
+ * Uses [`del`](https://socket.dev/npm/package/del/overview/8.0.1) for safer
+ * deletion with these safety features:
+ *
+ * - By default, prevents deleting the current working directory (cwd) and above
+ * - Allows deleting within cwd (descendant paths) without force option
+ * - Automatically uses force: true for temp directory, cacache, and ~/.socket
+ *   subdirectories
+ * - Protects against accidental deletion of parent directories via `../` paths
+ *
+ * @example
+ *   ;```ts
+ *   // Delete files within cwd (safe by default)
+ *   safeDeleteSync('./build')
+ *   safeDeleteSync('./dist')
+ *
+ *   // Delete with glob patterns
+ *   safeDeleteSync(['./temp/**', '!./temp/keep.txt'])
+ *
+ *   // Delete multiple paths
+ *   safeDeleteSync(['./coverage', './reports'])
+ *
+ *   // Force delete cwd or above (requires explicit force: true)
+ *   safeDeleteSync('../parent-dir', { force: true })
+ *   ```
+ *
+ * @param filepath - Path or array of paths to delete (supports glob patterns)
+ * @param options - Deletion options including force, retries, and recursion.
+ * @param options.force - Set to true to allow deleting cwd and above (use with
+ *   caution)
+ *
+ * @throws {Error} When attempting to delete protected paths without force
+ *   option.
+ */
+export declare function safeDeleteSync(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): void;
+/**
+ * Safely create a directory asynchronously, ignoring EEXIST errors. This
+ * function wraps fs.promises.mkdir and handles the race condition where the
+ * directory might already exist, which is common in concurrent code.
+ *
+ * Unlike fs.promises.mkdir with recursive:true, this function: - Silently
+ * ignores EEXIST errors (directory already exists) - Re-throws all other errors
+ * (permissions, invalid path, etc.) - Works reliably in
+ * multi-process/concurrent scenarios - Defaults to recursive: true for
+ * convenient nested directory creation.
+ *
+ * @example
+ *   ;```ts
+ *   // Create a directory recursively by default, no error if it exists
+ *   await safeMkdir('./config')
+ *
+ *   // Create nested directories (recursive: true is the default)
+ *   await safeMkdir('./data/cache/temp')
+ *
+ *   // Create with specific permissions
+ *   await safeMkdir('./secure', { mode: 0o700 })
+ *
+ *   // Explicitly disable recursive behavior
+ *   await safeMkdir('./single-level', { recursive: false })
+ *   ```
+ *
+ * @param path - Directory path to create.
+ * @param options - Options including recursive (default: true) and mode
+ *   settings.
+ *
+ * @returns Promise that resolves when directory is created or already exists
+ */
+export declare function safeMkdir(path: PathLike, options?: MakeDirectoryOptions | undefined): Promise<void>;
+/**
+ * Safely create a directory synchronously, ignoring EEXIST errors. This
+ * function wraps fs.mkdirSync and handles the race condition where the
+ * directory might already exist, which is common in concurrent code.
+ *
+ * Unlike fs.mkdirSync with recursive:true, this function: - Silently ignores
+ * EEXIST errors (directory already exists) - Re-throws all other errors
+ * (permissions, invalid path, etc.) - Works reliably in
+ * multi-process/concurrent scenarios - Defaults to recursive: true for
+ * convenient nested directory creation.
+ *
+ * @example
+ *   ;```ts
+ *   // Create a directory recursively by default, no error if it exists
+ *   safeMkdirSync('./config')
+ *
+ *   // Create nested directories (recursive: true is the default)
+ *   safeMkdirSync('./data/cache/temp')
+ *
+ *   // Create with specific permissions
+ *   safeMkdirSync('./secure', { mode: 0o700 })
+ *
+ *   // Explicitly disable recursive behavior
+ *   safeMkdirSync('./single-level', { recursive: false })
+ *   ```
+ *
+ * @param path - Directory path to create.
+ * @param options - Options including recursive (default: true) and mode
+ *   settings.
+ */
+export declare function safeMkdirSync(path: PathLike, options?: MakeDirectoryOptions | undefined): void;