0
# File System Operations
1

2
Asynchronous file system utilities for checking file existence with proper error handling, designed for robust file operations in Node.js applications.
3

4
## Capabilities
5

6
### File Existence Check
7

8
Asynchronously check if a file exists and return file statistics or false if it doesn't exist.
9

10
```typescript { .api }
11
/**
12
 * Check if a file exists asynchronously
13
 * @param file - Path to file to check
14
 * @returns Promise resolving to Stats object if file exists, false otherwise
15
 */
16
function exists(file: string): Promise<Stats | false>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { exists } from "utility";
23
import { Stats } from "node:fs";
24

25
// Basic file existence check
26
const fileExists = await exists('./config.json');
27
if (fileExists) {
28
  console.log('File exists and has size:', fileExists.size);
29
  console.log('Last modified:', fileExists.mtime);
30
} else {
31
  console.log('File does not exist');
32
}
33

34
// Directory existence check
35
const dirExists = await exists('./uploads');
36
if (dirExists && dirExists.isDirectory()) {
37
  console.log('Directory exists');
38
} else if (dirExists && dirExists.isFile()) {
39
  console.log('Path exists but is a file, not directory');
40
} else {
41
  console.log('Directory does not exist');
42
}
43

44
// Conditional file operations
45
async function readConfigIfExists(configPath: string) {
46
  const stats = await exists(configPath);
47
  if (stats) {
48
    console.log(`Config file found (${stats.size} bytes)`);
49
    const content = await fs.readFile(configPath, 'utf8');
50
    return JSON.parse(content);
51
  } else {
52
    console.log('Config file not found, using defaults');
53
    return getDefaultConfig();
54
  }
55
}
56

57
// File validation before processing
58
async function processFile(filePath: string) {
59
  const stats = await exists(filePath);
60
  
61
  if (!stats) {
62
    throw new Error(`File not found: ${filePath}`);
63
  }
64
  
65
  if (stats.size === 0) {
66
    throw new Error(`File is empty: ${filePath}`);
67
  }
68
  
69
  if (stats.size > 10 * 1024 * 1024) { // 10MB limit
70
    throw new Error(`File too large: ${filePath} (${stats.size} bytes)`);
71
  }
72
  
73
  // File is valid, proceed with processing
74
  return processValidFile(filePath);
75
}
76

77
// Batch file existence checks
78
async function checkMultipleFiles(filePaths: string[]) {
79
  const results = await Promise.all(
80
    filePaths.map(async (path) => ({
81
      path,
82
      exists: await exists(path)
83
    }))
84
  );
85
  
86
  const existing = results.filter(r => r.exists);
87
  const missing = results.filter(r => !r.exists);
88
  
89
  return { existing, missing };
90
}
91

92
// Error handling (errors other than ENOENT are thrown)
93
try {
94
  const stats = await exists('/root/protected-file');
95
  if (stats) {
96
    console.log('File exists and accessible');
97
  }
98
} catch (error) {
99
  // Will catch permission errors, not ENOENT
100
  console.error('Access error:', error.message);
101
}
102
```