0
# Core Walking Interface
1

2
The main walkdir function provides the foundational directory traversal functionality with multiple calling patterns and return types based on configuration options.
3

4
## Capabilities
5

6
### Main Walkdir Function
7

8
The primary entry point for directory traversal with flexible return types.
9

10
```javascript { .api }
11
/**
12
 * Walk a directory tree, emitting events or returning results based on options
13
 * @param {string} path - Directory path to walk
14
 * @param {WalkOptions|WalkEventListener} [options] - Walk options or event listener function
15
 * @param {WalkEventListener} [eventListener] - Optional event listener function
16
 * @returns {WalkEmitter|string[]|Object<string,fs.Stats>} - Return type depends on options
17
 */
18
function walkdir(path, options, eventListener);
19
```
20

21
**Return Behavior:**
22
- **Async mode** (default): Returns `WalkEmitter` for event-based handling
23
- **Sync mode** (`options.sync: true`): Returns `string[]` or `{[path]: stat}` object
24
- **Return object** (`options.return_object: true`): Returns object with path keys and stat values
25

26
**Usage Examples:**
27

28
```javascript
29
const walkdir = require('walkdir');
30

31
// Event emitter (async)
32
const emitter = walkdir('./directory');
33
emitter.on('path', (path, stat) => {
34
  console.log('Found:', path);
35
});
36

37
// With callback
38
walkdir('./directory', (path, stat) => {
39
  console.log('Path:', path, 'Type:', stat.isDirectory() ? 'dir' : 'file');
40
});
41

42
// With options and callback
43
walkdir('./directory', { max_depth: 2 }, (path, stat) => {
44
  console.log('Found at depth ≤2:', path);
45
});
46

47
// Callback has access to emitter control methods via 'this'
48
walkdir('./project', function(path, stat) {
49
  console.log('Processing:', path);
50
  
51
  // Skip node_modules directories using this.ignore()
52
  if (path.endsWith('node_modules')) {
53
    this.ignore(path); // 'this' refers to the WalkEmitter
54
  }
55
  
56
  // Can also use this.pause(), this.resume(), this.end(), this.stop()
57
  if (someCondition) {
58
    this.end(); // Stop the walk from within the callback
59
  }
60
});
61

62
// Sync mode - returns array
63
const paths = walkdir('./directory', { sync: true });
64
console.log('All paths:', paths);
65

66
// Sync mode - returns object
67
const stats = walkdir('./directory', { sync: true, return_object: true });
68
for (const [path, stat] of Object.entries(stats)) {
69
  console.log(path, stat.size);
70
}
71
```
72

73
### Function Aliases
74

75
The main walkdir function is available under multiple names for convenience.
76

77
```javascript { .api }
78
/**
79
 * All three are identical - just different names for the same function
80
 */
81
walkdir.find === walkdir.walk === walkdir; // true
82

83
// These all work exactly the same:
84
walkdir('./directory', options, callback);
85
walkdir.find('./directory', options, callback);  
86
walkdir.walk('./directory', options, callback);
87
```
88

89
## Parameter Flexibility
90

91
The main function supports flexible parameter patterns:
92

93
```javascript
94
// Path only - returns emitter
95
walkdir('./dir')
96

97
// Path + callback - returns emitter, calls callback for each path
98
walkdir('./dir', (path, stat) => {})
99

100
// Path + options - returns emitter or sync result based on options.sync
101
walkdir('./dir', { max_depth: 3 })
102

103
// Path + options + callback - full parameter set
104
walkdir('./dir', { max_depth: 3 }, (path, stat) => {})
105
```
106

107
The function automatically detects whether the second parameter is an options object or callback function based on its type.
108

109
## Error Handling
110

111
The core function handles errors differently based on mode:
112

113
- **Async mode**: Emits `error` events for target path issues, `fail` events for nested path issues
114
- **Sync mode**: Throws exceptions for target path issues, silently skips problematic nested paths
115
- **Promise mode**: Rejects promise for target path issues, includes failed paths in error details