Directory Operations

/**
 * Synchronously create a directory
 * @param path - Directory path to create
 * @param options - Creation options including recursive and mode
 */
mkdirSync(path: string | Buffer, options?: MkdirOptions): void;
mkdirSync(path: string | Buffer, mode?: number): void;

/**
 * Asynchronously create a directory
 * @param path - Directory path to create
 * @param options - Creation options including recursive and mode
 * @param callback - Completion callback
 */
mkdir(path: string | Buffer, options?: MkdirOptions, callback?: (err?: Error) => void): void;
mkdir(path: string | Buffer, mode?: number, callback?: (err?: Error) => void): void;
mkdir(path: string | Buffer, callback: (err?: Error) => void): void;

interface MkdirOptions {
  /** Create parent directories if they don't exist */
  recursive?: boolean;
  /** Directory permissions mode */
  mode?: number;
}

// Create single directory
fs.mkdirSync('/uploads');

// Create with specific permissions
fs.mkdirSync('/secure', { mode: 0o755 });

// Create directory tree recursively
fs.mkdirSync('/app/data/cache', { recursive: true });

// Async directory creation
fs.mkdir('/temp', (err) => {
  if (!err) {
    console.log('Directory created');
  }
});

// Promise-based creation
await fs.promises.mkdir('/logs', { recursive: true });

/**
 * Synchronously read the contents of a directory
 * @param path - Directory path to read
 * @param options - Read options including encoding and withFileTypes
 * @returns Array of filenames, Buffers, or Dirent objects
 */
readdirSync(path: string | Buffer, options?: ReaddirOptions): string[] | Buffer[] | Dirent[];
readdirSync(path: string | Buffer, encoding?: string): string[] | Buffer[];

/**
 * Asynchronously read the contents of a directory
 * @param path - Directory path to read
 * @param options - Read options including encoding and withFileTypes
 * @param callback - Completion callback with directory entries
 */
readdir(path: string | Buffer, options?: ReaddirOptions, callback?: (err?: Error, files?: string[] | Buffer[] | Dirent[]) => void): void;
readdir(path: string | Buffer, encoding: string, callback: (err?: Error, files?: string[] | Buffer[]) => void): void;
readdir(path: string | Buffer, callback: (err?: Error, files?: string[]) => void): void;

interface ReaddirOptions {
  /** Text encoding for filenames */
  encoding?: string;
  /** Return Dirent objects with file type information */
  withFileTypes?: boolean;
}

interface Dirent {
  /** Entry name (filename or directory name) */
  name: string | Buffer;
  
  /** Check if entry is a regular file */
  isFile(): boolean;
  /** Check if entry is a directory */
  isDirectory(): boolean;
  /** Check if entry is a symbolic link */
  isSymbolicLink(): boolean;
  /** Check if entry is a block device */
  isBlockDevice(): boolean;
  /** Check if entry is a character device */
  isCharacterDevice(): boolean;
  /** Check if entry is a FIFO pipe */
  isFIFO(): boolean;
  /** Check if entry is a socket */
  isSocket(): boolean;
}

// List directory as string array
const files = fs.readdirSync('/home');
console.log(files); // ['documents', 'downloads', 'file.txt']

// Get detailed file information
const entries = fs.readdirSync('/home', { withFileTypes: true });
entries.forEach(entry => {
  if (entry.isFile()) {
    console.log(`File: ${entry.name}`);
  } else if (entry.isDirectory()) {
    console.log(`Directory: ${entry.name}`);
  }
});

// List with specific encoding
const bufferNames = fs.readdirSync('/data', { encoding: 'buffer' });

// Async directory listing
fs.readdir('/projects', (err, files) => {
  if (!err) {
    console.log('Project directories:', files);
  }
});

// Promise-based listing with file types
const entries = await fs.promises.readdir('/app', { withFileTypes: true });
const directories = entries
  .filter(entry => entry.isDirectory())
  .map(entry => entry.name);

/**
 * Synchronously remove a directory (must be empty)
 * @param path - Directory path to remove
 */
rmdirSync(path: string | Buffer): void;

/**
 * Asynchronously remove a directory (must be empty)
 * @param path - Directory path to remove
 * @param callback - Completion callback
 */
rmdir(path: string | Buffer, callback: (err?: Error) => void): void;

// Remove empty directory
try {
  fs.rmdirSync('/empty-dir');
  console.log('Directory removed');
} catch (err) {
  console.log('Error:', err.message); // Directory not empty
}

// Async directory removal
fs.rmdir('/temp-dir', (err) => {
  if (!err) {
    console.log('Directory removed successfully');
  } else {
    console.log('Cannot remove directory:', err.message);
  }
});

// Promise-based removal
await fs.promises.rmdir('/old-cache');

/**
 * Synchronously remove files and directories with advanced options
 * @param path - Path to remove (file or directory)
 * @param options - Removal options including recursive and force
 */
rmSync(path: string | Buffer, options?: RmOptions): void;

interface RmOptions {
  /** Remove directories and their contents recursively */
  recursive?: boolean;
  /** Don't throw error if path doesn't exist */
  force?: boolean;
}

// Remove file or empty directory
fs.rmSync('/target');

// Remove directory and all contents recursively
fs.rmSync('/project-folder', { recursive: true });

// Force removal (don't error if path doesn't exist)
fs.rmSync('/maybe-exists', { force: true });

// Recursive removal with force
fs.rmSync('/old-build', { recursive: true, force: true });

/**
 * Synchronously create a unique temporary directory
 * @param prefix - Directory name prefix
 * @param options - Creation options including encoding
 * @returns Path to created temporary directory
 */
mkdtempSync(prefix: string, options?: MktempOptions): string;

interface MktempOptions {
  /** Encoding for returned path */
  encoding?: string;
}

// Create temp directory with prefix
const tempDir = fs.mkdtempSync('/tmp/myapp-');
console.log(tempDir); // '/tmp/myapp-A1B2C3'

// Create with custom encoding
const tempPath = fs.mkdtempSync('/tmp/build-', { encoding: 'utf8' });

// Use temp directory for processing
const processingDir = fs.mkdtempSync('/tmp/process-');
try {
  // ... do work in processingDir
  fs.writeFileSync(`${processingDir}/data.json`, JSON.stringify(data));
  // ... process files
} finally {
  // Clean up temp directory
  fs.rmSync(processingDir, { recursive: true });
}

// Check if path is directory
const stats = fs.statSync('/path');
if (stats.isDirectory()) {
  console.log('Is a directory');
}

// Create nested directory structure
fs.mkdirSync('/app/public/assets/images', { recursive: true });

// List all files in directory tree (recursive helper)
function listAllFiles(dir) {
  const results = [];
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  
  for (const entry of entries) {
    const fullPath = `${dir}/${entry.name}`;
    if (entry.isDirectory()) {
      results.push(...listAllFiles(fullPath));
    } else {
      results.push(fullPath);
    }
  }
  
  return results;
}

const allFiles = listAllFiles('/project');