@socketsecurity/lib 5.18.1 → 5.19.0

package/dist/fs.d.ts

@@ -1,16 +1,16 @@
-import type { Abortable } from 'events';
-import type { MakeDirectoryOptions, ObjectEncodingOptions, OpenMode, PathLike } from 'fs';
-import type { JsonReviver } from './json/types';
+/**
+ * @fileoverview File system utilities with cross-platform path handling.
+ * Provides enhanced fs operations, glob matching, and directory traversal functions.
+ */
 import { type Remap } from './objects';
+import type { Abortable } from 'node:events';
+import type { MakeDirectoryOptions, ObjectEncodingOptions, OpenMode, PathLike } from 'node:fs';
+import type { JsonReviver } from './json/types';
 /**
  * Supported text encodings for Node.js Buffers.
  * Includes ASCII, UTF-8/16, base64, binary, and hexadecimal encodings.
  */
 export type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
-/**
- * Represents any valid JSON content type.
- */
-export type JsonContent = unknown;
 /**
  * Options for asynchronous `findUp` operations.
  */
@@ -72,20 +72,9 @@ export interface IsDirEmptyOptions {
     ignore?: string[] | readonly string[] | undefined;
 }
 /**
- * Options for read operations with abort support.
+ * Represents any valid JSON content type.
  */
-export interface ReadOptions extends Abortable {
-    /**
-     * Character encoding to use for reading.
-     * @default 'utf8'
-     */
-    encoding?: BufferEncoding | string | undefined;
-    /**
-     * File system flag for reading behavior.
-     * @default 'r'
-     */
-    flag?: string | undefined;
-}
+export type JsonContent = unknown;
 /**
  * Options for reading directories with filtering and sorting.
  */
@@ -130,6 +119,21 @@ export type ReadJsonOptions = Remap<ReadFileOptions & {
      */
     reviver?: Parameters<typeof JSON.parse>[1] | undefined;
 }>;
+/**
+ * Options for read operations with abort support.
+ */
+export interface ReadOptions extends Abortable {
+    /**
+     * Character encoding to use for reading.
+     * @default 'utf8'
+     */
+    encoding?: BufferEncoding | string | undefined;
+    /**
+     * File system flag for reading behavior.
+     * @default 'r'
+     */
+    flag?: string | undefined;
+}
 /**
  * Options for file/directory removal operations.
  */
@@ -171,25 +175,19 @@ export interface SafeReadOptions extends ReadOptions {
     defaultValue?: unknown | undefined;
 }
 /**
- * Options for write operations with encoding and mode control.
+ * Result of file readability validation.
+ * Contains lists of valid and invalid file paths.
  */
-export interface WriteOptions extends Abortable {
-    /**
-     * Character encoding for writing.
-     * @default 'utf8'
-     */
-    encoding?: BufferEncoding | string | undefined;
+export interface ValidateFilesResult {
     /**
-     * File mode (permissions) to set.
-     * Uses standard Unix permission bits (e.g., 0o644).
-     * @default 0o666 (read/write for all, respecting umask)
+     * File paths that passed validation and are readable.
      */
-    mode?: number | undefined;
+    validPaths: string[];
     /**
-     * File system flag for write behavior.
-     * @default 'w' (create or truncate)
+     * File paths that failed validation (unreadable, permission denied, or non-existent).
+     * Common with Yarn Berry PnP virtual filesystem, pnpm symlinks, or filesystem race conditions.
      */
-    flag?: string | undefined;
+    invalidPaths: string[];
 }
 /**
  * Options for writing JSON files with formatting control.
@@ -229,6 +227,27 @@ export interface WriteJsonOptions extends WriteOptions {
      */
     spaces?: number | string | undefined;
 }
+/**
+ * Options for write operations with encoding and mode control.
+ */
+export interface WriteOptions extends Abortable {
+    /**
+     * Character encoding for writing.
+     * @default 'utf8'
+     */
+    encoding?: BufferEncoding | string | undefined;
+    /**
+     * File mode (permissions) to set.
+     * Uses standard Unix permission bits (e.g., 0o644).
+     * @default 0o666 (read/write for all, respecting umask)
+     */
+    mode?: number | undefined;
+    /**
+     * File system flag for write behavior.
+     * @default 'w' (create or truncate)
+     */
+    flag?: string | undefined;
+}
 /**
  * Find a file or directory by traversing up parent directories.
  * Searches from the starting directory upward to the filesystem root.
@@ -250,7 +269,6 @@ export interface WriteJsonOptions extends WriteOptions {
  * const nodeModules = await findUp('node_modules', { onlyDirectories: true })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function findUp(name: string | string[] | readonly string[], options?: FindUpOptions | undefined): Promise<string | undefined>;
 /**
  * Synchronously find a file or directory by traversing up parent directories.
@@ -276,8 +294,7 @@ export declare function findUp(name: string | string[] | readonly string[], opti
  * const configPath = findUpSync(['.eslintrc.js', '.eslintrc.json'])
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function findUpSync(name: string | string[] | readonly string[], options?: FindUpSyncOptions | undefined): string;
+export declare function findUpSync(name: string | string[] | readonly string[], options?: FindUpSyncOptions | undefined): string | undefined;
 /**
  * Invalidate the cached allowed directories.
  * Called automatically by the paths/rewire module when paths are overridden in tests.
@@ -305,24 +322,7 @@ export declare function invalidatePathCache(): void;
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isDir(filepath: PathLike): Promise<boolean>;
-/**
- * Check if a path is a directory synchronously.
- * Returns `true` for directories, `false` for files or non-existent paths.
- *
- * @param filepath - Path to check
- * @returns `true` if path is a directory, `false` otherwise
- *
- * @example
- * ```ts
- * if (isDirSync('./src')) {
- *   console.log('src is a directory')
- * }
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function isDirSync(filepath: PathLike): boolean;
 /**
  * Check if a directory is empty synchronously.
  * A directory is considered empty if it contains no files after applying ignore patterns.
@@ -341,8 +341,22 @@ export declare function isDirSync(filepath: PathLike): boolean;
  * isDirEmptySync('./cache', { ignore: ['.DS_Store'] })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isDirEmptySync(dirname: PathLike, options?: IsDirEmptyOptions | undefined): boolean;
+/**
+ * Check if a path is a directory synchronously.
+ * Returns `true` for directories, `false` for files or non-existent paths.
+ *
+ * @param filepath - Path to check
+ * @returns `true` if path is a directory, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * if (isDirSync('./src')) {
+ *   console.log('src is a directory')
+ * }
+ * ```
+ */
+export declare function isDirSync(filepath: PathLike): boolean;
 /**
  * Check if a path is a symbolic link synchronously.
  * Uses `lstat` to check the link itself, not the target.
@@ -357,7 +371,6 @@ export declare function isDirEmptySync(dirname: PathLike, options?: IsDirEmptyOp
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isSymLinkSync(filepath: PathLike): boolean;
 /**
  * Normalize encoding string to canonical form.
@@ -377,7 +390,6 @@ export declare function isSymLinkSync(filepath: PathLike): boolean;
  * normalizeEncoding(null) // Returns 'utf8'
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function normalizeEncoding(enc: BufferEncoding | string | null | undefined): BufferEncoding;
 /**
  * Move the "slow cases" to a separate function to make sure this function gets
@@ -396,7 +408,6 @@ export declare function normalizeEncoding(enc: BufferEncoding | string | null |
  * normalizeEncodingSlow('binary')  // 'latin1'
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function normalizeEncodingSlow(enc: string): BufferEncoding;
 /**
  * Read directory names asynchronously with filtering and sorting.
@@ -419,7 +430,6 @@ export declare function normalizeEncodingSlow(enc: string): BufferEncoding;
  * const unsorted = await readDirNames('./src', { sort: false })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function readDirNames(dirname: PathLike, options?: ReadDirOptions | undefined): Promise<string[]>;
 /**
  * Read directory names synchronously with filtering and sorting.
@@ -442,7 +452,6 @@ export declare function readDirNames(dirname: PathLike, options?: ReadDirOptions
  * })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function readDirNamesSync(dirname: PathLike, options?: ReadDirOptions): string[];
 /**
  * Read a file as binary data asynchronously.
@@ -462,28 +471,7 @@ export declare function readDirNamesSync(dirname: PathLike, options?: ReadDirOpt
  * const buffer = await readFileBinary('./data.bin', { signal: abortSignal })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function readFileBinary(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<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.
- *
- * @param filepath - Path to file
- * @param options - Read options including encoding and abort signal
- * @returns Promise resolving to string containing file contents
- *
- * @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' })
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function readFileUtf8(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<string>;
 /**
  * Read a file as binary data synchronously.
  * Returns a Buffer without encoding the contents.
@@ -502,8 +490,26 @@ export declare function readFileUtf8(filepath: PathLike, options?: ReadFileOptio
  * const gzipData = readFileBinarySync('./archive.gz')
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 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.
+ *
+ * @param filepath - Path to file
+ * @param options - Read options including encoding and abort signal
+ * @returns Promise resolving to string containing file contents
+ *
+ * @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' })
+ * ```
+ */
+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.
@@ -522,7 +528,6 @@ export declare function readFileBinarySync(filepath: PathLike, options?: ReadFil
  * const data = readFileUtf8Sync('./data.txt', { encoding: 'utf8' })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function readFileUtf8Sync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
 /**
  * Read and parse a JSON file asynchronously.
@@ -553,8 +558,7 @@ export declare function readFileUtf8Sync(filepath: PathLike, options?: ReadFileO
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function readJson(filepath: PathLike, options?: ReadJsonOptions | string | undefined): Promise<import("./json/types").JsonValue>;
+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.
@@ -583,8 +587,7 @@ export declare function readJson(filepath: PathLike, options?: ReadJsonOptions |
  * const config = readJsonSync('./config.json', { throws: false })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function readJsonSync(filepath: PathLike, options?: ReadJsonOptions | string | undefined): import("./json/types").JsonValue;
+export declare function readJsonSync(filepath: PathLike, options?: ReadJsonOptions | string | undefined): import("./json/types").JsonValue | undefined;
 /**
  * Safely delete a file or directory asynchronously with built-in protections.
  *
@@ -733,11 +736,9 @@ export declare function safeMkdirSync(path: PathLike, options?: MakeDirectoryOpt
  * const buffer = await safeReadFile('./binary.dat', { encoding: null })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function safeReadFile(filepath: PathLike, options: SafeReadOptions & {
     encoding: null;
 }): Promise<Buffer | undefined>;
-/*@__NO_SIDE_EFFECTS__*/
 export declare function safeReadFile(filepath: PathLike, options?: SafeReadOptions | undefined): Promise<string | undefined>;
 /**
  * Safely read a file synchronously, returning undefined on error.
@@ -764,11 +765,9 @@ export declare function safeReadFile(filepath: PathLike, options?: SafeReadOptio
  * const buffer = safeReadFileSync('./image.png', { encoding: null })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function safeReadFileSync(filepath: PathLike, options: SafeReadOptions & {
     encoding: null;
 }): Buffer | undefined;
-/*@__NO_SIDE_EFFECTS__*/
 export declare function safeReadFileSync(filepath: PathLike, options?: SafeReadOptions | undefined): string | undefined;
 /**
  * Safely get file stats asynchronously, returning undefined on error.
@@ -788,15 +787,13 @@ export declare function safeReadFileSync(filepath: PathLike, options?: SafeReadO
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function safeStats(filepath: PathLike): Promise<import("fs").Stats>;
+export declare function safeStats(filepath: PathLike): Promise<import("fs").Stats | undefined>;
 /**
  * Safely get file stats synchronously, returning undefined on error.
  * Useful for checking file existence and properties without error handling.
  * Returns undefined for any error (file not found, permission denied, etc.).
  *
  * @param filepath - Path to check
- * @param options - Read options (currently unused but kept for API consistency)
  * @returns Stats object, or undefined on error
  *
  * @example
@@ -809,8 +806,7 @@ export declare function safeStats(filepath: PathLike): Promise<import("fs").Stat
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function safeStatsSync(filepath: PathLike, options?: ReadFileOptions | undefined): import("fs").BigIntStats | import("fs").Stats;
+export declare function safeStatsSync(filepath: PathLike): import("fs").BigIntStats | import("fs").Stats | undefined;
 /**
  * Generate a unique filepath by adding number suffix if the path exists.
  * Appends `-1`, `-2`, etc. before the file extension until a non-existent path is found.
@@ -831,23 +827,7 @@ export declare function safeStatsSync(filepath: PathLike, options?: ReadFileOpti
  * const backupPath = uniqueSync('./backup')
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function uniqueSync(filepath: PathLike): string;
-/**
- * Result of file readability validation.
- * Contains lists of valid and invalid file paths.
- */
-export interface ValidateFilesResult {
-    /**
-     * File paths that passed validation and are readable.
-     */
-    validPaths: string[];
-    /**
-     * File paths that failed validation (unreadable, permission denied, or non-existent).
-     * Common with Yarn Berry PnP virtual filesystem, pnpm symlinks, or filesystem race conditions.
-     */
-    invalidPaths: string[];
-}
 /**
  * Validate that file paths are readable before processing.
  * Filters out files from glob results that cannot be accessed (common with
@@ -879,7 +859,6 @@ export interface ValidateFilesResult {
  * await sdk.uploadManifestFiles(orgSlug, validPaths)
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function validateFiles(filepaths: string[] | readonly string[]): ValidateFilesResult;
 /**
  * Write JSON content to a file asynchronously with formatting.

package/dist/fs.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -61,25 +62,18 @@ __export(fs_exports, {
 });
 module.exports = __toCommonJS(fs_exports);
 var import_node_process = __toESM(require("node:process"));
-var import_process = require("./constants/process");
 var import_arrays = require("./arrays");
-var import_promises = require("./promises");
+var import_process = require("./constants/process");
 var import_globs = require("./globs");
 var import_parse = require("./json/parse");
 var import_objects = require("./objects");
 var import_normalize = require("./paths/normalize");
 var import_rewire = require("./paths/rewire");
 var import_socket = require("./paths/socket");
+var import_promises = require("./promises");
 var import_sorts = require("./sorts");
-let _del;
-// @__NO_SIDE_EFFECTS__
-function getDel() {
-  if (_del === void 0) {
-    _del = require("./external/del");
-  }
-  return _del;
-}
 const abortSignal = (0, import_process.getAbortSignal)();
+const NEWLINE_REGEX = /\n/g;
 const defaultRemoveOptions = (0, import_objects.objectFreeze)({
   __proto__: null,
   force: true,
@@ -87,7 +81,11 @@ const defaultRemoveOptions = (0, import_objects.objectFreeze)({
   recursive: true,
   retryDelay: 200
 });
+let _del;
 let _cachedAllowedDirs;
+let _buffer;
+let _fs;
+let _path;
 function getAllowedDirectories() {
   if (_cachedAllowedDirs === void 0) {
     const path = /* @__PURE__ */ getPath();
@@ -99,27 +97,31 @@ function getAllowedDirectories() {
   }
   return _cachedAllowedDirs;
 }
-let _buffer;
 // @__NO_SIDE_EFFECTS__
 function getBuffer() {
   if (_buffer === void 0) {
-    _buffer = require("buffer");
+    _buffer = require("node:buffer");
   }
   return _buffer;
 }
-let _fs;
+// @__NO_SIDE_EFFECTS__
+function getDel() {
+  if (_del === void 0) {
+    _del = require("./external/del");
+  }
+  return _del;
+}
 // @__NO_SIDE_EFFECTS__
 function getFs() {
   if (_fs === void 0) {
-    _fs = require("fs");
+    _fs = require("node:fs");
   }
   return _fs;
 }
-let _path;
 // @__NO_SIDE_EFFECTS__
 function getPath() {
   if (_path === void 0) {
-    _path = require("path");
+    _path = require("node:path");
   }
   return _path;
 }
@@ -142,7 +144,7 @@ function innerReadDirNames(dirents, dirname, options) {
 function stringify(json, EOL, finalEOL, replacer, spaces = 2) {
   const EOF = finalEOL ? EOL : "";
   const str = JSON.stringify(json, replacer, spaces);
-  return `${str.replace(/\n/g, EOL)}${EOF}`;
+  return `${str.replace(NEWLINE_REGEX, EOL)}${EOF}`;
 }
 // @__NO_SIDE_EFFECTS__
 async function findUp(name, options) {
@@ -245,16 +247,11 @@ function findUpSync(name, options) {
 function invalidatePathCache() {
   _cachedAllowedDirs = void 0;
 }
-(0, import_rewire.registerCacheInvalidation)(invalidatePathCache);
 // @__NO_SIDE_EFFECTS__
 async function isDir(filepath) {
   return !!(await /* @__PURE__ */ safeStats(filepath))?.isDirectory();
 }
 // @__NO_SIDE_EFFECTS__
-function isDirSync(filepath) {
-  return !!(/* @__PURE__ */ safeStatsSync(filepath))?.isDirectory();
-}
-// @__NO_SIDE_EFFECTS__
 function isDirEmptySync(dirname, options) {
   const { ignore = import_globs.defaultIgnore } = {
     __proto__: null,
@@ -286,6 +283,10 @@ function isDirEmptySync(dirname, options) {
   }
 }
 // @__NO_SIDE_EFFECTS__
+function isDirSync(filepath) {
+  return !!(/* @__PURE__ */ safeStatsSync(filepath))?.isDirectory();
+}
+// @__NO_SIDE_EFFECTS__
 function isSymLinkSync(filepath) {
   const fs = /* @__PURE__ */ getFs();
   try {
@@ -410,22 +411,22 @@ async function readFileBinary(filepath, options) {
   });
 }
 // @__NO_SIDE_EFFECTS__
-async function readFileUtf8(filepath, options) {
+function readFileBinarySync(filepath, options) {
   const opts = typeof options === "string" ? { encoding: options } : options;
   const fs = /* @__PURE__ */ getFs();
-  return await fs.promises.readFile(filepath, {
-    signal: abortSignal,
+  return fs.readFileSync(filepath, {
     ...opts,
-    encoding: "utf8"
+    encoding: null
   });
 }
 // @__NO_SIDE_EFFECTS__
-function readFileBinarySync(filepath, options) {
+async function readFileUtf8(filepath, options) {
   const opts = typeof options === "string" ? { encoding: options } : options;
   const fs = /* @__PURE__ */ getFs();
-  return fs.readFileSync(filepath, {
+  return await fs.promises.readFile(filepath, {
+    signal: abortSignal,
     ...opts,
-    encoding: null
+    encoding: "utf8"
   });
 }
 // @__NO_SIDE_EFFECTS__
@@ -620,7 +621,7 @@ async function safeMkdir(path, options) {
   try {
     await fs.promises.mkdir(path, opts);
   } catch (e) {
-    if (typeof e === "object" && e !== null && "code" in e && e.code !== "EEXIST") {
+    if (typeof e !== "object" || e === null || !("code" in e) || e.code !== "EEXIST") {
       throw e;
     }
   }
@@ -631,7 +632,7 @@ function safeMkdirSync(path, options) {
   try {
     fs.mkdirSync(path, opts);
   } catch (e) {
-    if (typeof e === "object" && e !== null && "code" in e && e.code !== "EEXIST") {
+    if (typeof e !== "object" || e === null || !("code" in e) || e.code !== "EEXIST") {
       throw e;
     }
   }
@@ -697,14 +698,12 @@ async function safeStats(filepath) {
   return void 0;
 }
 // @__NO_SIDE_EFFECTS__
-function safeStatsSync(filepath, options) {
-  const opts = typeof options === "string" ? { encoding: options } : options;
+function safeStatsSync(filepath) {
   const fs = /* @__PURE__ */ getFs();
   try {
     return fs.statSync(filepath, {
       __proto__: null,
-      throwIfNoEntry: false,
-      ...opts
+      throwIfNoEntry: false
     });
   } catch {
   }
@@ -785,6 +784,7 @@ function writeJsonSync(filepath, jsonContent, options) {
     __proto__: null
   });
 }
+(0, import_rewire.registerCacheInvalidation)(invalidatePathCache);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   findUp,