1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
[](http://travis-ci.org/soldair/node-walkdir)
## walkdir
Find files. Walks a directory tree emitting events based on what it finds. Presents a familliar callback/emitter/sync interface. Walk a tree of any depth. This is a performant option any pull requests to make it more so will be taken into consderation..
## Example
```js
var walk = require('walkdir');
//async with path callback
walk('../',function(path,stat){
console.log('found: ',path);
});
//use async emitter to capture more events
var emitter = walk('../');
emitter.on('file',function(filename,stat){
console.log('file from emitter: ', filename);
});
//sync with callback
walk.sync('../',function(path,stat){
console.log('found sync:',path);
});
//sync just need paths
var paths = walk.sync('../');
console.log('found paths sync: ',paths);
```
## install
npm install walkdir
## arguments
walkdir(path, [options], [callback])
walkdir.sync(path, [options], [callback]);
- path
- the starting point of your directory walk
- options. supported options are
- general
```js
{
"follow_symlinks":false, // default is off
"no_recurse":false, // only recurse one level deep
"max_depth":undefined // only recurse down to max_depth. if you need more than no_recurse
}
```
- sync only
```js
{
"return_object":false, // if true the sync return will be in {path:stat} format instead of [path,path,...]
"no_return":false, // if true null will be returned and no array or object will be created with found paths. useful for large listings
}
```
- callback
- this is bound to the path event of the emitter. its optional in all cases.
```js
callback(path,stat)
```
## events
non error type events are emitted with (path,stat). stat is an instanceof fs.Stats
###path
fired for everything
###file
fired only for regular files
###directory
fired only for directories
###link
fired when a symbolic link is found
###end
fired when the entire tree has been read and emitted.
###socket
fired when a socket descriptor is found
###fifo
fired when a fifo is found
###characterdevice
fired when a character device is found
###blockdevice
fired when a block device is found
###targetdirectory
fired for the stat of the path you provided as the first argument. is is only fired if it is a directory.
###empty
fired for empty directory
## error events
error type events are emitted with (path,error). error being the error object returned from an fs call or other opperation.
###error
if the target path cannot be read an error event is emitted. this is the only failure case.
###fail
when stat or read fails on a path somewhere in the walk and it is not your target path you get a fail event instead of error.
This is handy if you want to find places you dont have access too.
## notes
the async emitter returned supports 3 methods
###end
stop a walk in progress
###pause
pause the walk. no more events will be emitted until resume
###resume
resume the walk
### ignore(path or array of paths)
will not traverse these directories. may be called in the path event handler to ignore dynamically.
```js
var walk = require('walkdir');
var p = require('path');
walk('/',function(path,stat){
// ignore all .git directories.
if(p.basename(path) === '.git') {
this.ignore(path)
}
})
```
### cancel a walk in progress
```js
//cancel a walk in progress within callback.
var walk = require('walkdir');
walk('../',function(path,stat){
this.end();
});
//cancel a walk in progress with emitter handle
var walk = require('walkdir');
var emitter = walk('../');
doSomethingAsync(function(){
emitter.end();
})
```
## thanks
thanks to substack. the interface for this module is based off of node-findit
## contributing
see `CONTRIBUTING.md` for guidelines. this is an open opensource project.
|
