@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/fs.d.ts

@@ -1,916 +0,0 @@
-/**
- * @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';
-/**
- * Options for asynchronous `findUp` operations.
- */
-export interface FindUpOptions {
-    /**
-     * Starting directory for the search.
-     * @default process.cwd()
-     */
-    cwd?: string | undefined;
-    /**
-     * Only match directories, not files.
-     * @default false
-     */
-    onlyDirectories?: boolean | undefined;
-    /**
-     * Only match files, not directories.
-     * @default true
-     */
-    onlyFiles?: boolean | undefined;
-    /**
-     * Abort signal to cancel the search operation.
-     */
-    signal?: AbortSignal | undefined;
-}
-/**
- * Options for synchronous `findUpSync` operations.
- */
-export interface FindUpSyncOptions {
-    /**
-     * Starting directory for the search.
-     * @default process.cwd()
-     */
-    cwd?: string | undefined;
-    /**
-     * Directory to stop searching at (inclusive).
-     * When provided, search will stop at this directory even if the root hasn't been reached.
-     */
-    stopAt?: string | undefined;
-    /**
-     * Only match directories, not files.
-     * @default false
-     */
-    onlyDirectories?: boolean | undefined;
-    /**
-     * Only match files, not directories.
-     * @default true
-     */
-    onlyFiles?: boolean | undefined;
-}
-/**
- * Options for checking if a directory is empty.
- */
-export interface IsDirEmptyOptions {
-    /**
-     * Glob patterns for files to ignore when checking emptiness.
-     * Files matching these patterns are not counted.
-     * @default defaultIgnore
-     */
-    ignore?: string[] | readonly string[] | undefined;
-}
-/**
- * Represents any valid JSON content type.
- */
-export type JsonContent = unknown;
-/**
- * Options for reading directories with filtering and sorting.
- */
-export interface ReadDirOptions {
-    /**
-     * Glob patterns for directories to ignore.
-     * @default undefined
-     */
-    ignore?: string[] | readonly string[] | undefined;
-    /**
-     * Include empty directories in results.
-     * When `false`, empty directories are filtered out.
-     * @default true
-     */
-    includeEmpty?: boolean | undefined;
-    /**
-     * Sort directory names alphabetically using natural sort order.
-     * @default true
-     */
-    sort?: boolean | undefined;
-}
-/**
- * Options for reading files with encoding and abort support.
- * Can be either an options object, an encoding string, or null.
- */
-export type ReadFileOptions = Remap<ObjectEncodingOptions & Abortable & {
-    flag?: OpenMode | undefined;
-}> | BufferEncoding | null;
-/**
- * Options for reading and parsing JSON files.
- */
-export type ReadJsonOptions = Remap<ReadFileOptions & {
-    /**
-     * Whether to throw errors on parse failure.
-     * When `false`, returns `undefined` on error instead of throwing.
-     * @default true
-     */
-    throws?: boolean | undefined;
-    /**
-     * JSON reviver function to transform parsed values.
-     * Same as the second parameter to `JSON.parse()`.
-     */
-    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.
- */
-export interface RemoveOptions {
-    /**
-     * Force deletion even outside normally safe directories.
-     * When `false`, prevents deletion outside temp, cacache, and ~/.socket.
-     * @default true for safe directories, false otherwise
-     */
-    force?: boolean | undefined;
-    /**
-     * Maximum number of retry attempts on failure.
-     * @default 3
-     */
-    maxRetries?: number | undefined;
-    /**
-     * Recursively delete directories and contents.
-     * @default true
-     */
-    recursive?: boolean | undefined;
-    /**
-     * Delay in milliseconds between retry attempts.
-     * @default 200
-     */
-    retryDelay?: number | undefined;
-    /**
-     * Abort signal to cancel the operation.
-     */
-    signal?: AbortSignal | undefined;
-}
-/**
- * Options for safe read operations that don't throw on errors.
- */
-export interface SafeReadOptions extends ReadOptions {
-    /**
-     * Default value to return on read failure.
-     * If not provided, `undefined` is returned on error.
-     */
-    defaultValue?: unknown | undefined;
-}
-/**
- * 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[];
-}
-/**
- * Options for writing JSON files with formatting control.
- */
-export interface WriteJsonOptions extends WriteOptions {
-    /**
-     * End-of-line sequence to use.
-     * @default '\n'
-     * @example
-     * ```ts
-     * // Windows-style line endings
-     * writeJson('data.json', data, { EOL: '\r\n' })
-     * ```
-     */
-    EOL?: string | undefined;
-    /**
-     * Whether to add a final newline at end of file.
-     * @default true
-     */
-    finalEOL?: boolean | undefined;
-    /**
-     * JSON replacer function to transform values during stringification.
-     * Same as the second parameter to `JSON.stringify()`.
-     */
-    replacer?: JsonReviver | undefined;
-    /**
-     * Number of spaces for indentation, or string to use for indentation.
-     * @default 2
-     * @example
-     * ```ts
-     * // Use tabs instead of spaces
-     * writeJson('data.json', data, { spaces: '\t' })
-     *
-     * // Use 4 spaces for indentation
-     * writeJson('data.json', data, { spaces: 4 })
-     * ```
-     */
-    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.
- * Useful for finding configuration files or project roots.
- *
- * @param name - Filename(s) to search for
- * @param options - Search options including cwd and type filters
- * @returns Normalized absolute path if found, undefined otherwise
- *
- * @example
- * ```ts
- * // Find package.json starting from current directory
- * const pkgPath = await findUp('package.json')
- *
- * // Find any of multiple config files
- * const configPath = await findUp(['.config.js', '.config.json'])
- *
- * // Find a directory instead of file
- * const nodeModules = await findUp('node_modules', { onlyDirectories: true })
- * ```
- */
-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.
- * Searches from the starting directory upward to the filesystem root or `stopAt` directory.
- * Useful for finding configuration files or project roots in synchronous contexts.
- *
- * @param name - Filename(s) to search for
- * @param options - Search options including cwd, stopAt, and type filters
- * @returns Normalized absolute path if found, undefined otherwise
- *
- * @example
- * ```ts
- * // Find package.json starting from current directory
- * const pkgPath = findUpSync('package.json')
- *
- * // Find .git directory but stop at home directory
- * const gitPath = findUpSync('.git', {
- *   onlyDirectories: true,
- *   stopAt: process.env.HOME
- * })
- *
- * // Find any of multiple config files
- * const configPath = findUpSync(['.eslintrc.js', '.eslintrc.json'])
- * ```
- */
-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.
- *
- * @internal Used for test rewiring
- *
- * @example
- * ```typescript
- * invalidatePathCache()
- * // Cached allowed directories are now cleared
- * ```
- */
-export declare function invalidatePathCache(): void;
-/**
- * Check if a path is a directory asynchronously.
- * 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 (await isDir('./src')) {
- *   console.log('src is a directory')
- * }
- * ```
- */
-export declare function isDir(filepath: PathLike): Promise<boolean>;
-/**
- * Check if a directory is empty synchronously.
- * A directory is considered empty if it contains no files after applying ignore patterns.
- * Uses glob patterns to filter ignored files.
- *
- * @param dirname - Directory path to check
- * @param options - Options including ignore patterns
- * @returns `true` if directory is empty (or doesn't exist), `false` otherwise
- *
- * @example
- * ```ts
- * // Check if directory is completely empty
- * isDirEmptySync('./build')
- *
- * // Check if directory is empty, ignoring .DS_Store files
- * isDirEmptySync('./cache', { ignore: ['.DS_Store'] })
- * ```
- */
-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.
- *
- * @param filepath - Path to check
- * @returns `true` if path is a symbolic link, `false` otherwise
- *
- * @example
- * ```ts
- * if (isSymLinkSync('./my-link')) {
- *   console.log('Path is a symbolic link')
- * }
- * ```
- */
-export declare function isSymLinkSync(filepath: PathLike): boolean;
-/**
- * Normalize encoding string to canonical form.
- * Handles common encodings inline for performance, delegates to slowCases for others.
- *
- * Based on Node.js internal/util.js normalizeEncoding implementation.
- * @see https://github.com/nodejs/node/blob/ae62b36d442b7bf987e85ae6e0df0f02cc1bb17f/lib/internal/util.js#L247-L310
- *
- * @param enc - Encoding to normalize (can be null/undefined)
- * @returns Normalized encoding string, defaults to 'utf8'
- *
- * @example
- * ```ts
- * normalizeEncoding('UTF-8') // Returns 'utf8'
- * normalizeEncoding('binary') // Returns 'latin1'
- * normalizeEncoding('ucs-2') // Returns 'utf16le'
- * normalizeEncoding(null) // Returns 'utf8'
- * ```
- */
-export declare function normalizeEncoding(enc: BufferEncoding | string | null | undefined): BufferEncoding;
-/**
- * Move the "slow cases" to a separate function to make sure this function gets
- * inlined properly. That prioritizes the common case.
- *
- * Based on Node.js internal/util.js normalizeEncoding implementation.
- * @see https://github.com/nodejs/node/blob/ae62b36d442b7bf987e85ae6e0df0f02cc1bb17f/lib/internal/util.js#L247-L310
- *
- * @param enc - Encoding to normalize
- * @returns Normalized encoding string, defaults to 'utf8' for unknown encodings
- *
- * @example
- * ```typescript
- * normalizeEncodingSlow('ucs2')    // 'utf16le'
- * normalizeEncodingSlow('LATIN1')  // 'latin1'
- * normalizeEncodingSlow('binary')  // 'latin1'
- * ```
- */
-export declare function normalizeEncodingSlow(enc: string): BufferEncoding;
-/**
- * Read directory names asynchronously with filtering and sorting.
- * Returns only directory names (not files), with optional filtering for empty directories
- * and glob-based ignore patterns. Results are naturally sorted by default.
- *
- * @param dirname - Directory path to read
- * @param options - Options for filtering and sorting
- * @returns Array of directory names, empty array on error
- *
- * @example
- * ```ts
- * // Get all subdirectories, sorted naturally
- * const dirs = await readDirNames('./packages')
- *
- * // Get non-empty directories only
- * const nonEmpty = await readDirNames('./cache', { includeEmpty: false })
- *
- * // Get directories without sorting
- * const unsorted = await readDirNames('./src', { sort: false })
- * ```
- */
-export declare function readDirNames(dirname: PathLike, options?: ReadDirOptions | undefined): Promise<string[]>;
-/**
- * Read directory names synchronously with filtering and sorting.
- * Returns only directory names (not files), with optional filtering for empty directories
- * and glob-based ignore patterns. Results are naturally sorted by default.
- *
- * @param dirname - Directory path to read
- * @param options - Options for filtering and sorting
- * @returns Array of directory names, empty array on error
- *
- * @example
- * ```ts
- * // Get all subdirectories, sorted naturally
- * const dirs = readDirNamesSync('./packages')
- *
- * // Get non-empty directories only, ignoring node_modules
- * const nonEmpty = readDirNamesSync('./src', {
- *   includeEmpty: false,
- *   ignore: ['node_modules']
- * })
- * ```
- */
-export declare function readDirNamesSync(dirname: PathLike, options?: ReadDirOptions): string[];
-/**
- * Read a file as binary data asynchronously.
- * Returns a Buffer without encoding the contents.
- * Useful for reading images, archives, or other binary formats.
- *
- * @param filepath - Path to file
- * @param options - Read options (encoding is forced to null for binary)
- * @returns Promise resolving to Buffer containing file contents
- *
- * @example
- * ```ts
- * // Read an image file
- * const imageBuffer = await readFileBinary('./image.png')
- *
- * // Read with abort signal
- * const buffer = await readFileBinary('./data.bin', { signal: abortSignal })
- * ```
- */
-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.
- *
- * @param filepath - Path to file
- * @param options - Read options (encoding is forced to null for binary)
- * @returns Buffer containing file contents
- *
- * @example
- * ```ts
- * // Read an image file
- * const imageBuffer = readFileBinarySync('./logo.png')
- *
- * // Read a compressed file
- * const gzipData = readFileBinarySync('./archive.gz')
- * ```
- */
-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.
- * This is the most common way to read text files synchronously.
- *
- * @param filepath - Path to file
- * @param options - Read options including encoding
- * @returns String containing file contents
- *
- * @example
- * ```ts
- * // Read a configuration file
- * const config = readFileUtf8Sync('./config.txt')
- *
- * // Read with custom options
- * const data = readFileUtf8Sync('./data.txt', { encoding: 'utf8' })
- * ```
- */
-export declare function readFileUtf8Sync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
-/**
- * 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.
- *
- * @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
- *
- * @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')
- * }
- * ```
- */
-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.
- *
- * @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
- *
- * @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 })
- * ```
- */
-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.
- *
- * 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
- *
- * @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
- *
- * @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 })
- * ```
- */
-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
- *
- * @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
- *
- * @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 })
- * ```
- */
-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
- *
- * @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
- *
- * @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 })
- * ```
- */
-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
- *
- * @param path - Directory path to create
- * @param options - Options including recursive (default: true) and mode settings
- *
- * @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 })
- * ```
- */
-export declare function safeMkdirSync(path: PathLike, options?: MakeDirectoryOptions | undefined): void;
-/**
- * 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.
- *
- * @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
- *
- * @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 })
- * ```
- */
-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.
- *
- * @param filepath - Path to file
- * @param options - Read options including encoding and default value
- * @returns File contents (string by default), or undefined on error
- *
- * @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 })
- * ```
- */
-export declare function safeReadFileSync(filepath: PathLike, options: SafeReadOptions & {
-    encoding: null;
-}): Buffer | undefined;
-export declare function safeReadFileSync(filepath: PathLike, options?: SafeReadOptions | undefined): string | undefined;
-/**
- * Safely get file stats asynchronously, 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
- * @returns Promise resolving to Stats object, or undefined on error
- *
- * @example
- * ```ts
- * // Check if file exists and get its stats
- * const stats = await safeStats('./file.txt')
- * if (stats) {
- *   console.log('File size:', stats.size)
- *   console.log('Modified:', stats.mtime)
- * }
- * ```
- */
-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
- * @returns Stats object, or undefined on error
- *
- * @example
- * ```ts
- * // Check if file exists and get its size
- * const stats = safeStatsSync('./file.txt')
- * if (stats) {
- *   console.log('File size:', stats.size)
- *   console.log('Is directory:', stats.isDirectory())
- * }
- * ```
- */
-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.
- * Useful for creating files without overwriting existing ones.
- *
- * @param filepath - Desired file path
- * @returns Normalized unique filepath (original if it doesn't exist, or with number suffix)
- *
- * @example
- * ```ts
- * // If 'report.pdf' exists, returns 'report-1.pdf'
- * const uniquePath = uniqueSync('./report.pdf')
- *
- * // If 'data.json' and 'data-1.json' exist, returns 'data-2.json'
- * const path = uniqueSync('./data.json')
- *
- * // If 'backup' doesn't exist, returns 'backup' unchanged
- * const backupPath = uniqueSync('./backup')
- * ```
- */
-export declare function uniqueSync(filepath: PathLike): string;
-/**
- * Validate that file paths are readable before processing.
- * Filters out files from glob results that cannot be accessed (common with
- * Yarn Berry PnP virtual filesystem, pnpm content-addressable store symlinks,
- * or filesystem race conditions in CI/CD environments).
- *
- * This defensive pattern prevents ENOENT errors when files exist in glob
- * results but are not accessible via standard filesystem operations.
- *
- * @param filepaths - Array of file paths to validate
- * @returns Object with `validPaths` (readable) and `invalidPaths` (unreadable)
- *
- * @example
- * ```ts
- * import { validateFiles } from '@socketsecurity/lib/fs'
- *
- * const files = ['package.json', '.pnp.cjs/virtual-file.json']
- * const { validPaths, invalidPaths } = validateFiles(files)
- *
- * console.log(`Valid: ${validPaths.length}`)
- * console.log(`Invalid: ${invalidPaths.length}`)
- * ```
- *
- * @example
- * ```ts
- * // Typical usage in Socket CLI commands
- * const packagePaths = await getPackageFilesForScan(targets)
- * const { validPaths } = validateFiles(packagePaths)
- * await sdk.uploadManifestFiles(orgSlug, validPaths)
- * ```
- */
-export declare function validateFiles(filepaths: string[] | readonly string[]): ValidateFilesResult;
-/**
- * Write JSON content to a file asynchronously with formatting.
- * Stringifies the value with configurable indentation and line endings.
- * Automatically adds a final newline by default for POSIX compliance.
- *
- * @param filepath - Path to write to
- * @param jsonContent - Value to stringify and write
- * @param options - Write options including formatting and encoding
- * @returns Promise that resolves when write completes
- *
- * @example
- * ```ts
- * // Write formatted JSON with default 2-space indentation
- * await writeJson('./data.json', { name: 'example', version: '1.0.0' })
- *
- * // Write with custom indentation
- * await writeJson('./config.json', config, { spaces: 4 })
- *
- * // Write with tabs instead of spaces
- * await writeJson('./data.json', data, { spaces: '\t' })
- *
- * // Write without final newline
- * await writeJson('./inline.json', obj, { finalEOL: false })
- *
- * // Write with Windows line endings
- * await writeJson('./win.json', data, { EOL: '\r\n' })
- * ```
- */
-export declare function writeJson(filepath: PathLike, jsonContent: unknown, options?: WriteJsonOptions | string): Promise<void>;
-/**
- * Write JSON content to a file synchronously with formatting.
- * Stringifies the value with configurable indentation and line endings.
- * Automatically adds a final newline by default for POSIX compliance.
- *
- * @param filepath - Path to write to
- * @param jsonContent - Value to stringify and write
- * @param options - Write options including formatting and encoding
- *
- * @example
- * ```ts
- * // Write formatted JSON with default 2-space indentation
- * writeJsonSync('./package.json', pkg)
- *
- * // Write with custom indentation
- * writeJsonSync('./tsconfig.json', tsconfig, { spaces: 4 })
- *
- * // Write with tabs for indentation
- * writeJsonSync('./data.json', data, { spaces: '\t' })
- *
- * // Write compacted (no indentation)
- * writeJsonSync('./compact.json', data, { spaces: 0 })
- * ```
- */
-export declare function writeJsonSync(filepath: PathLike, jsonContent: unknown, options?: WriteJsonOptions | string | undefined): void;