1 | node-walk
|
2 | ====
|
3 |
|
4 | node.js walk implementation.
|
5 |
|
6 | This 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 |
|
13 | As few file descriptors are opened at a time as possible.
|
14 | This is particularly well suited for single hard disks which are not flash or solid state.
|
15 |
|
16 | Installation
|
17 | ----
|
18 |
|
19 | npm install walk
|
20 |
|
21 | Usage
|
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 |
|
66 | API
|
67 | ====
|
68 |
|
69 | Emitted 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 |
|
80 | Single 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 |
|
96 | Events 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 |
|
114 | Comparisons
|
115 | ====
|
116 |
|
117 | Tested on my `/System` containing 59,490 (+ self) directories (and lots of files).
|
118 | The 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 |
|
130 | Note 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 |
|