0
# Walkdir
1

2
Walkdir is a Node.js library that provides comprehensive directory traversal capabilities with multiple interface options. It walks directory trees of any depth and emits events based on what it finds, offering callback, event emitter, synchronous, and promise-based patterns for maximum flexibility across different use cases.
3

4
## Package Information
5

6
- **Package Name**: walkdir
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install walkdir`
10

11
## Core Imports
12

13
```javascript
14
const walkdir = require('walkdir');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const walkdir = require('walkdir');
21

22
// Async with callback
23
walkdir('./my-directory', function(path, stat) {
24
  console.log('Found:', path);
25
});
26

27
// Sync usage
28
const paths = walkdir.sync('./my-directory');
29
console.log('All paths:', paths);
30

31
// Promise-based
32
const result = await walkdir.async('./my-directory', {return_object: true});
33
// result is {[path]: stat} object
34

35
// Event emitter pattern
36
const emitter = walkdir('./my-directory');
37
emitter.on('file', (path, stat) => {
38
  console.log('File found:', path);
39
});
40
emitter.on('directory', (path, stat) => {
41
  console.log('Directory found:', path);
42
});
43
emitter.on('end', () => {
44
  console.log('Walk completed');
45
});
46
```
47

48
## Architecture
49

50
Walkdir provides multiple interfaces for the same core functionality:
51

52
- **Callback Pattern**: Traditional Node.js callback interface for path iteration
53
- **Event Emitter**: EventEmitter-based interface for fine-grained control and event handling
54
- **Synchronous**: Blocking operations that return results immediately  
55
- **Promise-based**: Modern async/await compatible interface
56
- **Flexible Returns**: Choose between path arrays or {path: stat} objects
57
- **Stream Control**: Pause, resume, and early termination capabilities
58

59
The library handles symlinks, implements inode tracking to prevent loops, supports custom filtering, and provides comprehensive error handling for robust file system traversal.
60

61
## Capabilities
62

63
### Core Walking Interface
64

65
Main directory traversal function with multiple calling patterns and return types based on options.
66

67
```javascript { .api }
68
/**
69
 * Walk a directory tree, emitting events or returning results based on options
70
 * @param {string} path - Directory path to walk
71
 * @param {WalkOptions|WalkEventListener} [options] - Walk options or event listener
72
 * @param {WalkEventListener} [eventListener] - Optional event listener
73
 * @returns {WalkEmitter|string[]|Object<string,fs.Stats>} - Emitter, array, or object based on sync/return_object options
74
 */
75
function walkdir(path, options, eventListener);
76
```
77

78
[Core Walking Interface](./core-walking.md)
79

80
### Synchronous Operations
81

82
Blocking directory traversal that returns all results immediately.
83

84
```javascript { .api }
85
/**
86
 * Synchronously walk directory tree and return all paths
87
 * @param {string} path - Directory path to walk
88
 * @param {WalkOptions} [options] - Walk options
89
 * @param {WalkEventListener} [eventListener] - Optional event listener
90
 * @returns {string[]|Object<string,fs.Stats>} - Array of paths or object based on return_object option
91
 */
92
function walkdir.sync(path, options, eventListener);
93
```
94

95
[Synchronous Operations](./sync-operations.md)
96

97
### Promise-based Operations
98

99
Modern async/await compatible interface returning promises.
100

101
```javascript { .api }
102
/**
103
 * Walk directory tree and return promise of results
104
 * @param {string} path - Directory path to walk  
105
 * @param {WalkOptions} [options] - Walk options
106
 * @param {WalkEventListener} [eventListener] - Optional event listener
107
 * @returns {Promise<string[]|Object<string,fs.Stats>>} - Promise resolving to paths array or object
108
 */
109
function walkdir.async(path, options, eventListener);
110
```
111

112
[Promise-based Operations](./async-operations.md)
113

114
### Event System & Control
115

116
Event emitter interface with comprehensive file system events and flow control methods.
117

118
```javascript { .api }
119
interface WalkEmitter extends EventEmitter {
120
  /** Stop the walk immediately */
121
  end(): void;
122
  /** Pause event emission */
123
  pause(): void;
124
  /** Resume event emission */
125
  resume(): void;
126
  /** Ignore specific paths during traversal */
127
  ignore(paths: string | string[]): void;
128
}
129
```
130

131
[Event System & Control](./events-control.md)
132

133
### Configuration Options
134

135
Comprehensive options for controlling traversal behavior, performance, and output format.
136

137
```javascript { .api }
138
interface WalkOptions {
139
  /** Follow symbolic links (default: false) */
140
  follow_symlinks?: boolean;
141
  /** Only traverse one level deep */
142
  no_recurse?: boolean;
143
  /** Maximum traversal depth */
144
  max_depth?: number;
145
  /** Track inodes to prevent loops (default: true) */
146
  track_inodes?: boolean;
147
  /** Return {path: stat} object instead of path array */
148
  return_object?: boolean;
149
  /** Don't build internal result collection (memory optimization) */
150
  no_return?: boolean;
151
  /** Filter function for file/directory names */
152
  filter?: (directory: string, files: string[]) => string[] | Promise<string[]>;
153
  /** Custom fs implementation (e.g., graceful-fs) */
154
  fs?: any;
155
  /** Use lstat vs stat for link detection (default: true) */
156
  find_links?: boolean;
157
}
158
```
159

160
[Configuration Options](./options-configuration.md)
161

162
## Types
163

164
```javascript { .api }
165
/**
166
 * Event listener function called for each path found
167
 * Bound to WalkEmitter context (this) providing access to control methods:
168
 * - this.ignore(paths) - Skip specified paths
169
 * - this.pause() - Pause traversal
170
 * - this.resume() - Resume traversal  
171
 * - this.end() - Stop traversal
172
 * - this.stop() - Stop traversal (alias for end)
173
 * @param {string} path - Found file system path
174
 * @param {fs.Stats} stat - File system stats object  
175
 * @param {number} depth - Current depth in directory tree
176
 */
177
type WalkEventListener = (this: WalkEmitter, path: string, stat: fs.Stats, depth: number) => void;
178

179
/**
180
 * Walk emitter events - all include (path, stat, depth) parameters:
181
 * - 'path': Any file system object found
182
 * - 'file': Regular file found  
183
 * - 'directory': Directory found
184
 * - 'link': Symbolic link found
185
 * - 'socket': Socket found
186
 * - 'fifo': FIFO/named pipe found
187
 * - 'blockdevice': Block device found
188
 * - 'characterdevice': Character device found
189
 * - 'targetdirectory': Initial target directory (if directory)
190
 * - 'empty': Empty directory found
191
 * - 'end': Walk completed
192
 * - 'error': Fatal error on target path
193
 * - 'fail': Non-fatal error on nested path
194
 * - 'maxdepth': Maximum depth reached
195
 */
196
```