File Operations

/**
 * Synchronously write data to a file, replacing the file if it already exists
 * @param path - File path to write to
 * @param data - Data to write (string or Buffer)
 * @param options - Write options including encoding, mode, and flags
 */
writeFileSync(path: string | Buffer, data: string | Buffer, options?: WriteFileOptions): void;

/**
 * Asynchronously write data to a file, replacing the file if it already exists
 * @param path - File path to write to
 * @param data - Data to write (string or Buffer)
 * @param options - Write options including encoding, mode, and flags
 * @param callback - Completion callback
 */
writeFile(path: string | Buffer, data: string | Buffer, options?: WriteFileOptions, callback?: (err?: Error) => void): void;
writeFile(path: string | Buffer, data: string | Buffer, callback: (err?: Error) => void): void;

interface WriteFileOptions {
  /** Text encoding for string data */
  encoding?: string;
  /** File mode (permissions) */
  mode?: number;
  /** File open flags */
  flag?: string;
}

// Write string content
fs.writeFileSync('/config.json', JSON.stringify({setting: true}));

// Write with specific encoding and mode
fs.writeFileSync('/data.txt', 'Hello World', {
  encoding: 'utf8',
  mode: 0o644,
  flag: 'w'
});

// Write binary data
const buffer = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
fs.writeFileSync('/binary.dat', buffer);

// Async write with callback
fs.writeFile('/async.txt', 'Async content', (err) => {
  if (err) throw err;
  console.log('File written successfully');
});

// Promise-based write
await fs.promises.writeFile('/promise.txt', 'Promise content');

/**
 * Synchronously read the entire contents of a file
 * @param path - File path to read from
 * @param options - Read options including encoding and flags
 * @returns File contents as string (if encoding specified) or Buffer
 */
readFileSync(path: string | Buffer, options?: ReadFileOptions): string | Buffer;
readFileSync(path: string | Buffer, encoding: string): string;

/**
 * Asynchronously read the entire contents of a file
 * @param path - File path to read from
 * @param options - Read options including encoding and flags
 * @param callback - Completion callback with file data
 */
readFile(path: string | Buffer, options?: ReadFileOptions, callback?: (err?: Error, data?: string | Buffer) => void): void;
readFile(path: string | Buffer, encoding: string, callback: (err?: Error, data?: string) => void): void;
readFile(path: string | Buffer, callback: (err?: Error, data?: Buffer) => void): void;

interface ReadFileOptions {
  /** Text encoding (returns string if specified, Buffer otherwise) */
  encoding?: string;
  /** File open flags */
  flag?: string;
}

// Read as Buffer (default)
const buffer = fs.readFileSync('/binary.dat');
console.log(buffer); // <Buffer 48 65 6c 6c 6f>

// Read as string with encoding
const text = fs.readFileSync('/data.txt', 'utf8');
console.log(text); // "Hello World"

// Read with options object
const content = fs.readFileSync('/config.json', { encoding: 'utf8' });
const config = JSON.parse(content);

// Async read with callback
fs.readFile('/async.txt', 'utf8', (err, data) => {
  if (err) throw err;
  console.log('File content:', data);
});

// Promise-based read
const data = await fs.promises.readFile('/promise.txt', 'utf8');

/**
 * Synchronously test whether or not the given path exists
 * @param path - File or directory path to check
 * @returns true if the path exists, false otherwise
 */
existsSync(path: string | Buffer): boolean;

// Check if file exists
if (fs.existsSync('/config.json')) {
  const config = fs.readFileSync('/config.json', 'utf8');
  console.log('Config loaded');
} else {
  console.log('Config file not found');
}

// Check directory existence
const hasUploads = fs.existsSync('/uploads');
if (!hasUploads) {
  fs.mkdirSync('/uploads');
}

/**
 * Synchronously test user's permissions for the file or directory
 * @param path - File or directory path to check
 * @param mode - Accessibility mode (defaults to fs.constants.F_OK)
 */
accessSync(path: string | Buffer, mode?: number): void;

/**
 * Asynchronously test user's permissions for the file or directory
 * @param path - File or directory path to check
 * @param mode - Accessibility mode (defaults to fs.constants.F_OK)
 * @param callback - Completion callback
 */
access(path: string | Buffer, mode?: number, callback?: (err?: Error) => void): void;
access(path: string | Buffer, callback: (err?: Error) => void): void;

// Check if file exists (F_OK is default)
try {
  fs.accessSync('/important.txt');
  console.log('File exists');
} catch (err) {
  console.log('File does not exist');
}

// Check specific permissions
try {
  fs.accessSync('/sensitive.txt', fs.constants.R_OK | fs.constants.W_OK);
  console.log('File is readable and writable');
} catch (err) {
  console.log('Cannot read or write file');
}

// Async permission check
fs.access('/data.txt', fs.constants.R_OK, (err) => {
  if (!err) {
    console.log('File is readable');
  } else {
    console.log('Cannot read file');
  }
});

/**
 * Synchronously remove a file or symbolic link
 * @param path - File path to remove
 */
unlinkSync(path: string | Buffer): void;

/**
 * Asynchronously remove a file or symbolic link
 * @param path - File path to remove
 * @param callback - Completion callback
 */
unlink(path: string | Buffer, callback: (err?: Error) => void): void;

// Remove file synchronously
try {
  fs.unlinkSync('/temp.txt');
  console.log('File deleted');
} catch (err) {
  console.log('Error deleting file:', err.message);
}

// Remove file asynchronously
fs.unlink('/temp.txt', (err) => {
  if (!err) {
    console.log('File deleted successfully');
  } else {
    console.log('Error:', err.message);
  }
});

// Promise-based deletion
await fs.promises.unlink('/temp.txt');

/**
 * Synchronously copy src to dest, overwriting dest if it already exists
 * @param src - Source file path
 * @param dest - Destination file path
 * @param flags - Copy operation flags (optional)
 */
copyFileSync(src: string | Buffer, dest: string | Buffer, flags?: number): void;

/**
 * Asynchronously copy src to dest
 * @param src - Source file path
 * @param dest - Destination file path
 * @param flags - Copy operation flags (optional)
 * @param callback - Completion callback
 */
copyFile(src: string | Buffer, dest: string | Buffer, flags?: number, callback?: (err?: Error) => void): void;
copyFile(src: string | Buffer, dest: string | Buffer, callback: (err?: Error) => void): void;

// Simple file copy
fs.copyFileSync('/source.txt', '/backup.txt');

// Copy with exclusive flag (fail if destination exists)
try {
  fs.copyFileSync('/source.txt', '/backup.txt', fs.constants.COPYFILE_EXCL);
  console.log('File copied');
} catch (err) {
  console.log('Destination already exists');
}

// Async copy
fs.copyFile('/source.txt', '/backup.txt', (err) => {
  if (!err) {
    console.log('File copied successfully');
  }
});

// Promise-based copy
await fs.promises.copyFile('/source.txt', '/backup.txt');

/**
 * Synchronously truncate a file to a specified length
 * @param path - File path or file descriptor
 * @param len - Target length in bytes (defaults to 0)
 */
truncateSync(path: string | Buffer | number, len?: number): void;

/**
 * Asynchronously truncate a file to a specified length
 * @param path - File path or file descriptor
 * @param len - Target length in bytes (defaults to 0)
 * @param callback - Completion callback
 */
truncate(path: string | Buffer, len?: number, callback?: (err?: Error) => void): void;
truncate(path: string | Buffer, callback: (err?: Error) => void): void;

// Truncate file to 0 bytes (empty it)
fs.truncateSync('/large-file.txt');

// Truncate to specific length
fs.truncateSync('/data.txt', 100); // Keep only first 100 bytes

// Async truncation
fs.truncate('/log.txt', 1000, (err) => {
  if (!err) {
    console.log('File truncated to 1000 bytes');
  }
});

// Promise-based truncation
await fs.promises.truncate('/data.txt', 50);

// File access constants
F_OK: 0  // File exists
R_OK: 4  // File is readable
W_OK: 2  // File is writable
X_OK: 1  // File is executable

// Copy file constants
COPYFILE_EXCL: 1      // Fail if destination exists
COPYFILE_FICLONE: 2   // Clone file if possible