0
# File System Operations
1

2
Promise-based file system operations that provide modern async/await compatibility for Node.js fs operations. Includes graceful-fs integration when available and a custom exists() implementation.
3

4
## Capabilities
5

6
### File Reading Operations
7

8
Read file contents and metadata with promise support.
9

10
```javascript { .api }
11
/**
12
 * Read the entire contents of a file
13
 * @param path - File path to read
14
 * @param options - Encoding or options object
15
 * @returns Promise resolving to file contents
16
 */
17
function readFile(path, options): Promise<Buffer | string>;
18

19
/**
20
 * Read a directory to get list of files and subdirectories
21
 * @param path - Directory path to read
22
 * @param options - Options object or encoding
23
 * @returns Promise resolving to array of filenames or Dirent objects
24
 */
25
function readdir(path, options): Promise<string[] | Dirent[]>;
26

27
/**
28
 * Read the value of a symbolic link
29
 * @param path - Path to symbolic link
30
 * @param options - Options object or encoding
31
 * @returns Promise resolving to link target
32
 */
33
function readlink(path, options): Promise<string>;
34
```
35

36
### File Writing Operations
37

38
Write and modify file contents with promise support.
39

40
```javascript { .api }
41
/**
42
 * Write data to a file, replacing the file if it already exists
43
 * @param file - File path or file descriptor
44
 * @param data - Data to write
45
 * @param options - Options object or encoding
46
 * @returns Promise resolving when write completes
47
 */
48
function writeFile(file, data, options): Promise<void>;
49

50
/**
51
 * Append data to a file, creating the file if it doesn't exist
52
 * @param file - File path or file descriptor
53
 * @param data - Data to append
54
 * @param options - Options object or encoding
55
 * @returns Promise resolving when append completes
56
 */
57
function appendFile(file, data, options): Promise<void>;
58

59
/**
60
 * Write buffer to file at specified position
61
 * @param fd - File descriptor
62
 * @param buffer - Buffer containing data to write
63
 * @param offset - Offset in buffer to start reading from
64
 * @param length - Number of bytes to write
65
 * @param position - Position in file to write at
66
 * @returns Promise resolving to {bytesWritten, buffer}
67
 */
68
function write(fd, buffer, offset, length, position): Promise<{bytesWritten: number, buffer: Buffer}>;
69
```
70

71
### File System Metadata Operations
72

73
Get and modify file metadata, permissions, and timestamps.
74

75
```javascript { .api }
76
/**
77
 * Get file statistics
78
 * @param path - File path
79
 * @param options - Options object
80
 * @returns Promise resolving to Stats object
81
 */
82
function stat(path, options): Promise<Stats>;
83

84
/**
85
 * Get file statistics, following symbolic links
86
 * @param path - File path
87
 * @param options - Options object  
88
 * @returns Promise resolving to Stats object
89
 */
90
function lstat(path, options): Promise<Stats>;
91

92
/**
93
 * Get file statistics by file descriptor
94
 * @param fd - File descriptor
95
 * @param options - Options object
96
 * @returns Promise resolving to Stats object
97
 */
98
function fstat(fd, options): Promise<Stats>;
99

100
/**
101
 * Check if file exists (custom implementation)
102
 * @param path - File path to check
103
 * @returns Promise resolving to boolean indicating existence
104
 */
105
function exists(path): Promise<boolean>;
106
```
107

108
### File System Structure Operations
109

110
Create, remove, and modify file system structure.
111

112
```javascript { .api }
113
/**
114
 * Create a directory
115
 * @param path - Directory path to create
116
 * @param options - Options object or mode
117
 * @returns Promise resolving when directory is created
118
 */
119
function mkdir(path, options): Promise<void>;
120

121
/**
122
 * Remove a directory
123
 * @param path - Directory path to remove
124
 * @param options - Options object
125
 * @returns Promise resolving when directory is removed
126
 */
127
function rmdir(path, options): Promise<void>;
128

129
/**
130
 * Rename a file or directory
131
 * @param oldPath - Current path
132
 * @param newPath - New path
133
 * @returns Promise resolving when rename completes
134
 */
135
function rename(oldPath, newPath): Promise<void>;
136

137
/**
138
 * Delete a file
139
 * @param path - File path to delete
140
 * @returns Promise resolving when file is deleted
141
 */
142
function unlink(path): Promise<void>;
143

144
/**
145
 * Create a hard link
146
 * @param existingPath - Path to existing file
147
 * @param newPath - Path for new link
148
 * @returns Promise resolving when link is created
149
 */
150
function link(existingPath, newPath): Promise<void>;
151

152
/**
153
 * Create a symbolic link
154
 * @param target - Target path
155
 * @param path - Link path
156
 * @param type - Link type (file, dir, junction)
157
 * @returns Promise resolving when symlink is created
158
 */
159
function symlink(target, path, type): Promise<void>;
160
```
161

162
### File Permissions and Ownership
163

164
Modify file permissions and ownership.
165

166
```javascript { .api }
167
/**
168
 * Change file permissions
169
 * @param path - File path
170
 * @param mode - Permission mode
171
 * @returns Promise resolving when permissions are changed
172
 */
173
function chmod(path, mode): Promise<void>;
174

175
/**
176
 * Change file permissions by file descriptor
177
 * @param fd - File descriptor
178
 * @param mode - Permission mode
179
 * @returns Promise resolving when permissions are changed
180
 */
181
function fchmod(fd, mode): Promise<void>;
182

183
/**
184
 * Change file ownership
185
 * @param path - File path
186
 * @param uid - User ID
187
 * @param gid - Group ID
188
 * @returns Promise resolving when ownership is changed
189
 */
190
function chown(path, uid, gid): Promise<void>;
191

192
/**
193
 * Change file ownership by file descriptor
194
 * @param fd - File descriptor
195
 * @param uid - User ID
196
 * @param gid - Group ID
197
 * @returns Promise resolving when ownership is changed
198
 */
199
function fchown(fd, uid, gid): Promise<void>;
200

201
/**
202
 * Change symbolic link ownership
203
 * @param path - Link path
204
 * @param uid - User ID
205
 * @param gid - Group ID
206
 * @returns Promise resolving when ownership is changed
207
 */
208
function lchown(path, uid, gid): Promise<void>;
209
```
210

211
### File Access and Timestamps
212

213
Test file access and modify timestamps.
214

215
```javascript { .api }
216
/**
217
 * Test file access permissions (if available in Node.js version)
218
 * @param path - File path
219
 * @param mode - Access mode constants
220
 * @returns Promise resolving when access test completes
221
 */
222
function access(path, mode): Promise<void>;
223

224
/**
225
 * Change file timestamps
226
 * @param path - File path
227
 * @param atime - Access time
228
 * @param mtime - Modification time
229
 * @returns Promise resolving when timestamps are changed
230
 */
231
function utimes(path, atime, mtime): Promise<void>;
232

233
/**
234
 * Change file timestamps by file descriptor
235
 * @param fd - File descriptor
236
 * @param atime - Access time
237
 * @param mtime - Modification time
238
 * @returns Promise resolving when timestamps are changed
239
 */
240
function futimes(fd, atime, mtime): Promise<void>;
241
```
242

243
### Low-Level File Operations
244

245
Direct file descriptor operations and synchronization.
246

247
```javascript { .api }
248
/**
249
 * Open a file
250
 * @param path - File path
251
 * @param flags - File access flags
252
 * @param mode - File mode (permissions)
253
 * @returns Promise resolving to file descriptor
254
 */
255
function open(path, flags, mode): Promise<number>;
256

257
/**
258
 * Close a file descriptor
259
 * @param fd - File descriptor to close
260
 * @returns Promise resolving when file is closed
261
 */
262
function close(fd): Promise<void>;
263

264
/**
265
 * Read data from file descriptor
266
 * @param fd - File descriptor
267
 * @param buffer - Buffer to read into
268
 * @param offset - Offset in buffer to start writing
269
 * @param length - Number of bytes to read
270
 * @param position - Position in file to read from
271
 * @returns Promise resolving to {bytesRead, buffer}
272
 */
273
function read(fd, buffer, offset, length, position): Promise<{bytesRead: number, buffer: Buffer}>;
274

275
/**
276
 * Synchronize file data to storage
277
 * @param fd - File descriptor
278
 * @returns Promise resolving when sync completes
279
 */
280
function fsync(fd): Promise<void>;
281

282
/**
283
 * Synchronize file data (not metadata) to storage
284
 * @param fd - File descriptor
285
 * @returns Promise resolving when sync completes
286
 */
287
function fdatasync(fd): Promise<void>;
288

289
/**
290
 * Truncate file to specified length
291
 * @param path - File path
292
 * @param len - Length to truncate to
293
 * @returns Promise resolving when truncate completes
294
 */
295
function truncate(path, len): Promise<void>;
296

297
/**
298
 * Truncate file by file descriptor
299
 * @param fd - File descriptor
300
 * @param len - Length to truncate to
301
 * @returns Promise resolving when truncate completes
302
 */
303
function ftruncate(fd, len): Promise<void>;
304

305
/**
306
 * Resolve real path of file
307
 * @param path - Path to resolve
308
 * @param options - Options object or encoding
309
 * @returns Promise resolving to resolved path
310
 */
311
function realpath(path, options): Promise<string>;
312
```
313

314
### Node.js Version-Dependent Operations
315

316
Operations available in newer Node.js versions (conditionally exported).
317

318
```javascript { .api }
319
/**
320
 * Copy a file (if available in Node.js version)
321
 * @param src - Source file path
322
 * @param dest - Destination file path
323
 * @param flags - Copy operation flags
324
 * @returns Promise resolving when copy completes
325
 */
326
function copyFile(src, dest, flags): Promise<void>;
327

328
/**
329
 * Create a temporary directory (if available in Node.js version)
330
 * @param prefix - Prefix for directory name
331
 * @param options - Options object or encoding
332
 * @returns Promise resolving to created directory path
333
 */
334
function mkdtemp(prefix, options): Promise<string>;
335
```
336

337
**Usage Examples:**
338

339
```javascript
340
const fs = require('mz/fs');
341

342
// Read and write files
343
async function processFile() {
344
  try {
345
    // Check if file exists
346
    if (await fs.exists('input.txt')) {
347
      // Read file content
348
      const content = await fs.readFile('input.txt', 'utf8');
349
      
350
      // Process content
351
      const processed = content.toUpperCase();
352
      
353
      // Write processed content
354
      await fs.writeFile('output.txt', processed);
355
      
356
      // Get file stats
357
      const stats = await fs.stat('output.txt');
358
      console.log('File size:', stats.size);
359
    }
360
  } catch (error) {
361
    console.error('File operation failed:', error);
362
  }
363
}
364

365
// Directory operations
366
async function listFiles() {
367
  try {
368
    const files = await fs.readdir('./');
369
    console.log('Files:', files);
370
  } catch (error) {
371
    console.error('Failed to read directory:', error);
372
  }
373
}
374

375
// Callback support is still available
376
fs.readFile('example.txt', 'utf8', (err, data) => {
377
  if (err) {
378
    console.error('Error:', err);
379
  } else {
380
    console.log('File content:', data);
381
  }
382
});
383
```
384

385
## Implementation Notes
386

387
- Uses `graceful-fs` when available, falls back to native `fs` module
388
- All functions support both promise and callback interfaces
389
- Custom `exists()` implementation that always resolves (never rejects)
390
- Conditionally exports newer Node.js methods when available
391
- Maintains complete compatibility with native fs module behavior