0
# File Operations
1

2
Core file transfer operations including upload, download, streaming support, and high-performance parallel transfers for efficient data handling.
3

4
## Capabilities
5

6
### Get File
7

8
Downloads a file from the remote server with flexible destination options.
9

10
```javascript { .api }
11
/**
12
 * Download a file from remote server
13
 * @param remotePath - Path to remote file
14
 * @param dst - Destination: string path, stream, or undefined for buffer
15
 * @param options - Optional transfer options
16
 * @param addListeners - Whether to add event listeners (default: true)
17
 * @returns Promise resolving to string path, stream, or buffer
18
 */
19
get(remotePath, dst, options, addListeners = true): Promise<String|Stream|Buffer>;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// Download to local file
26
await sftp.get('/remote/file.txt', '/local/file.txt');
27

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

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

37
// Download with options
38
await sftp.get('/remote/file.txt', '/local/file.txt', {
39
  readStreamOptions: { start: 100, end: 500 },
40
  writeStreamOptions: { mode: 0o644 }
41
});
42
```
43

44
### Put File
45

46
Uploads a file to the remote server from various source types.
47

48
```javascript { .api }
49
/**
50
 * Upload a file to remote server
51
 * @param localSrc - Source: string path, buffer, or stream
52
 * @param remotePath - Destination path on remote server
53
 * @param options - Optional transfer options
54
 * @returns Promise resolving to success message
55
 */
56
put(localSrc, remotePath, options): Promise<String>;
57
```
58

59
**Usage Examples:**
60

61
```javascript
62
// Upload from local file
63
await sftp.put('/local/file.txt', '/remote/file.txt');
64

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

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

74
// Upload with options
75
await sftp.put('/local/file.txt', '/remote/file.txt', {
76
  readStreamOptions: { highWaterMark: 64 * 1024 },
77
  writeStreamOptions: { mode: 0o755 }
78
});
79
```
80

81
### Fast Get
82

83
High-performance parallel download using SSH2's fastGet functionality.
84

85
```javascript { .api }
86
/**
87
 * Download file using parallel reads for faster throughput
88
 * @param remotePath - Path to remote file
89
 * @param localPath - Local destination path
90
 * @param options - Optional fastGet options
91
 * @returns Promise resolving to success message
92
 */
93
fastGet(remotePath, localPath, options): Promise<String>;
94
```
95

96
**Important Note**: fastGet functionality depends on remote SFTP server capabilities. Not all servers support parallel reads fully.
97

98
**Usage Examples:**
99

100
```javascript
101
// Basic fast download
102
await sftp.fastGet('/remote/large-file.zip', '/local/large-file.zip');
103

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

114
### Fast Put
115

116
High-performance parallel upload using SSH2's fastPut functionality.
117

118
```javascript { .api }
119
/**
120
 * Upload file using parallel writes for faster throughput
121
 * @param localPath - Path to local file
122
 * @param remotePath - Destination path on remote server
123
 * @param options - Optional fastPut options
124
 * @returns Promise resolving to success message
125
 */
126
fastPut(localPath, remotePath, options): Promise<String>;
127
```
128

129
**Important Note**: fastPut functionality depends on remote SFTP server capabilities. Many servers do not fully support parallel writes.
130

131
**Usage Examples:**
132

133
```javascript
134
// Basic fast upload
135
await sftp.fastPut('/local/large-file.zip', '/remote/large-file.zip');
136

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

147
### Append to File
148

149
Appends data to an existing remote file.
150

151
```javascript { .api }
152
/**
153
 * Append data to an existing remote file
154
 * @param input - Data to append: buffer or stream (not string path)
155
 * @param remotePath - Path to remote file
156
 * @param options - Optional append options
157
 * @returns Promise resolving to success message
158
 */
159
append(input, remotePath, options = {}): Promise<String>;
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
// Append buffer data
166
const newData = Buffer.from('\nAppended line');
167
await sftp.append(newData, '/remote/log.txt');
168

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

174
// Append with options
175
await sftp.append(buffer, '/remote/file.txt', {
176
  mode: 0o644,
177
  flags: 'a'
178
});
179
```
180

181
## Transfer Options
182

183
### Stream Options
184

185
Control read and write stream behavior:
186

187
```javascript { .api }
188
interface StreamOptions {
189
  flags?: string;         // File open flags ('r', 'w', 'a', etc.)
190
  encoding?: string;      // File encoding
191
  mode?: number;          // File permissions (octal)
192
  autoClose?: boolean;    // Auto close stream when done
193
  start?: number;         // Start byte position
194
  end?: number;           // End byte position
195
  highWaterMark?: number; // Buffer size for streaming
196
}
197

198
interface TransferOptions {
199
  readStreamOptions?: StreamOptions;
200
  writeStreamOptions?: StreamOptions;
201
  pipeOptions?: Object;   // Pipe operation options
202
}
203
```
204

205
### Fast Transfer Options
206

207
Options for high-performance transfers:
208

209
```javascript { .api }
210
interface FastTransferOptions {
211
  concurrency?: number;   // Number of parallel connections (default: 25)
212
  chunkSize?: number;     // Size of each chunk in bytes (default: 32768)
213
  step?: (total_transferred: number, chunk: number, total: number) => void;
214
}
215
```
216

217
## Performance Considerations
218

219
- **Use fastGet/fastPut** for large files when server supports parallel operations
220
- **Stream operations** for memory-efficient handling of large files
221
- **Buffer operations** for small files and in-memory processing
222
- **Chunk size tuning** can significantly impact transfer performance
223
- **Concurrency limits** prevent overwhelming the server or network
224

225
## Error Handling
226

227
File operation errors include detailed context:
228

229
- `ERR_BAD_PATH`: Invalid file path or permissions
230
- `ENOENT`: File or directory does not exist
231
- `EACCES`: Permission denied
232
- `EISDIR`: Expected file but found directory
233
- Network errors with connection context