UNPKG

3.63 kBMarkdownView Raw
1node-walk
2====
3
4node.js walk implementation.
5
6This is somewhat of a port python's `os.walk`, but using Node.JS conventions.
7
8 * EventEmitter
9 * Asynchronous
10 * Chronological (optionally)
11 * Built-in flow-control
12
13As few file descriptors are opened at a time as possible.
14This is particularly well suited for single hard disks which are not flash or solid state.
15
16Installation
17----
18
19 npm install walk
20
21Usage
22====
23
24 var walk = require('walk').walk,
25 options,
26 walker;
27
28 options = {
29 followLinks: false,
30 };
31
32 walker = walk("path/to/dir", options);
33
34 walker.on("names", function (root, nodeNamesArray) {
35 nodeNames.sort(function (a, b) {
36 if (a > b) return 1;
37 if (a < b) return -1;
38 return 0;
39 });
40 });
41
42 walker.on("directories", function (root, dirStatsArray, next) {
43 // dirStatsArray is an array of `stat` objects with the additional attributes
44 // * type
45 // * error
46 // * name
47
48 next();
49 });
50
51 walker.on("file", function (root, fileStats, next) {
52 fs.readFile(file, function () {
53 // doStuff
54 next();
55 });
56 });
57
58 walker.on("errors", function (root, nodeStatsArray, next) {
59 next();
60 });
61
62 walker.on("end", function () {
63 console.log("all done");
64 });
65
66API
67====
68
69Emitted Values
70
71 * `on('XYZ', function(root, stats, next) {})`
72
73 * `root` - the containing the files to be inspected
74 * *stats[Array]* - a single `stats` object or an array with some added attributes
75 * type - 'file', 'directory', etc
76 * error
77 * name - the name of the file, dir, etc
78 * next - no more files will be read until this is called
79
80Single Events - fired immediately
81
82 * `end` - No files, dirs, etc left to inspect
83
84 * `directoryError` - Error when `fstat` succeeded, but reading path failed (Probably due to permissions).
85 * `nodeError` - Error `fstat` did not succeeded.
86 * `node` - a `stats` object for a node of any type
87 * `file` - includes links when `followLinks` is `true`
88 * Note: This feature is broken in the current version, but works in the previous `walk-recursive` version
89 * `directory`
90 * `symbolicLink` - always empty when `followLinks` is `true`
91 * `blockDevice`
92 * `characterDevice`
93 * `FIFO`
94 * `socket`
95
96Events with Array Arguments - fired after all files in the dir have been `stat`ed
97
98 * `names` - before any `stat` takes place. Useful for sorting and filtering.
99 * Note: the array is an array of `string`s, not `stat` objects
100 * Note: the `next` argument is a `noop`
101
102 * `errors` - errors encountered by `fs.stat` when reading ndes in a directory
103 * `nodes` - an array of `stats` of any type
104 * `files`
105 * `directories` - modification of this array - sorting, removing, etc - affects traversal
106 * `symbolicLinks`
107 * `blockDevices`
108 * `characterDevices`
109 * `FIFOs`
110 * `sockets`
111
112**Warning** beware of infinite loops when `followLinks` is true (using `walk-recurse` varient).
113
114Comparisons
115====
116
117Tested on my `/System` containing 59,490 (+ self) directories (and lots of files).
118The size of the text output was 6mb.
119
120`find`:
121 time bash -c "find /System -type d | wc"
122 59491 97935 6262916
123
124 real 2m27.114s
125 user 0m1.193s
126 sys 0m14.859s
127
128`find.js`:
129
130Note that `find.js` omits the start directory
131
132 time bash -c "node examples/find.js /System -type d | wc"
133 59490 97934 6262908
134
135 # Test 1
136 real 2m52.273s
137 user 0m20.374s
138 sys 0m27.800s
139
140 # Test 2
141 real 2m23.725s
142 user 0m18.019s
143 sys 0m23.202s
144
145 # Test 3
146 real 2m50.077s
147 user 0m17.661s
148 sys 0m24.008s
149