File Operations

/**
 * Download a file from remote server
 * @param remotePath - Path to remote file
 * @param dst - Destination: string path, stream, or undefined for buffer
 * @param options - Optional transfer options
 * @param addListeners - Whether to add event listeners (default: true)
 * @returns Promise resolving to string path, stream, or buffer
 */
get(remotePath, dst, options, addListeners = true): Promise<String|Stream|Buffer>;

// Download to local file
await sftp.get('/remote/file.txt', '/local/file.txt');

// Download to buffer
const buffer = await sftp.get('/remote/data.bin');
console.log(buffer.length);

// Download to stream
const fs = require('fs');
const writeStream = fs.createWriteStream('/local/output.txt');
await sftp.get('/remote/input.txt', writeStream);

// Download with options
await sftp.get('/remote/file.txt', '/local/file.txt', {
  readStreamOptions: { start: 100, end: 500 },
  writeStreamOptions: { mode: 0o644 }
});

/**
 * Upload a file to remote server
 * @param localSrc - Source: string path, buffer, or stream
 * @param remotePath - Destination path on remote server
 * @param options - Optional transfer options
 * @returns Promise resolving to success message
 */
put(localSrc, remotePath, options): Promise<String>;

// Upload from local file
await sftp.put('/local/file.txt', '/remote/file.txt');

// Upload from buffer
const buffer = Buffer.from('Hello, world!');
await sftp.put(buffer, '/remote/hello.txt');

// Upload from stream
const fs = require('fs');
const readStream = fs.createReadStream('/local/large-file.dat');
await sftp.put(readStream, '/remote/large-file.dat');

// Upload with options
await sftp.put('/local/file.txt', '/remote/file.txt', {
  readStreamOptions: { highWaterMark: 64 * 1024 },
  writeStreamOptions: { mode: 0o755 }
});

/**
 * Download file using parallel reads for faster throughput
 * @param remotePath - Path to remote file
 * @param localPath - Local destination path
 * @param options - Optional fastGet options
 * @returns Promise resolving to success message
 */
fastGet(remotePath, localPath, options): Promise<String>;

// Basic fast download
await sftp.fastGet('/remote/large-file.zip', '/local/large-file.zip');

// Fast download with options
await sftp.fastGet('/remote/data.db', '/local/data.db', {
  concurrency: 8,        // Number of parallel connections
  chunkSize: 32768,      // Chunk size in bytes
  step: (total_transferred, chunk, total) => {
    console.log(`Transferred: ${total_transferred}/${total}`);
  }
});

/**
 * Upload file using parallel writes for faster throughput
 * @param localPath - Path to local file
 * @param remotePath - Destination path on remote server
 * @param options - Optional fastPut options
 * @returns Promise resolving to success message
 */
fastPut(localPath, remotePath, options): Promise<String>;

// Basic fast upload
await sftp.fastPut('/local/large-file.zip', '/remote/large-file.zip');

// Fast upload with options
await sftp.fastPut('/local/video.mp4', '/remote/video.mp4', {
  concurrency: 4,        // Number of parallel connections
  chunkSize: 65536,      // Chunk size in bytes
  step: (total_transferred, chunk, total) => {
    console.log(`Uploaded: ${total_transferred}/${total}`);
  }
});

/**
 * Append data to an existing remote file
 * @param input - Data to append: buffer or stream (not string path)
 * @param remotePath - Path to remote file
 * @param options - Optional append options
 * @returns Promise resolving to success message
 */
append(input, remotePath, options = {}): Promise<String>;

// Append buffer data
const newData = Buffer.from('\nAppended line');
await sftp.append(newData, '/remote/log.txt');

// Append from stream
const fs = require('fs');
const appendStream = fs.createReadStream('/local/additional-data.txt');
await sftp.append(appendStream, '/remote/combined.txt');

// Append with options
await sftp.append(buffer, '/remote/file.txt', {
  mode: 0o644,
  flags: 'a'
});

interface StreamOptions {
  flags?: string;         // File open flags ('r', 'w', 'a', etc.)
  encoding?: string;      // File encoding
  mode?: number;          // File permissions (octal)
  autoClose?: boolean;    // Auto close stream when done
  start?: number;         // Start byte position
  end?: number;           // End byte position
  highWaterMark?: number; // Buffer size for streaming
}

interface TransferOptions {
  readStreamOptions?: StreamOptions;
  writeStreamOptions?: StreamOptions;
  pipeOptions?: Object;   // Pipe operation options
}

interface FastTransferOptions {
  concurrency?: number;   // Number of parallel connections (default: 25)
  chunkSize?: number;     // Size of each chunk in bytes (default: 32768)
  step?: (total_transferred: number, chunk: number, total: number) => void;
}