legacy-libs/walkdir/readme.md

   1 [![Build Status](https://secure.travis-ci.org/soldair/node-walkdir.png)](http://travis-ci.org/soldair/node-walkdir)
   2
   3 ## walkdir
   4
   5 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..
   6
   7 ## Example
   8
   9 ```js
  10
  11 var walk = require('walkdir');
  12
  13 //async with path callback
  14
  15 walk('../', function(path, stat) {
  16   console.log('found: ', path);
  17 });
  18
  19 //use async emitter to capture more events
  20
  21 var emitter = walk('../');
  22
  23 emitter.on('file', function(filename, stat) {
  24   console.log('file from emitter: ', filename);
  25 });
  26
  27
  28 //sync with callback
  29
  30 walk.sync('../', function(path, stat) {
  31   console.log('found sync:', path);
  32 });
  33
  34 //sync just need paths
  35
  36 var paths = walk.sync('../');
  37 console.log('found paths sync: ', paths);
  38
  39 // async await/promise!
  40 let result = await walk.async('../',{return_object:true})
  41 //result['path'] = {statObject}
  42
  43 ```
  44
  45 ## install
  46
  47         npm install walkdir
  48
  49 ## arguments
  50
  51 walkdir(path, [options], [callback])
  52 walkdir.sync(path, [options], [callback]);
  53
  54 - path
  55   - the starting point of your directory walk
  56
  57 - options. supported options are
  58   - general
  59
  60 ```js
  61 {
  62   /**
  63   * follow symlinks. default FALSE
  64   */
  65   "follow_symlinks"?: boolean,
  66   /**
  67     * only go one level deep. convenience param.
  68     */
  69   "no_recurse"?: boolean,
  70   /**
  71     * only travel to max depth. emits an error if hit.
  72     */
  73   "max_depth"?: number,
  74   /**
  75     * on filesystems where inodes are not unique like windows (or perhaps hardlinks) some files may not be emitted due to inode collision.
  76     * turning off this behavior may be required but at the same time may lead to hitting max_depth via link loop.
  77     */
  78   "track_inodes"?: boolean;
  79   /**
  80     * make this syncronous. the same as calling walkdir.sync
  81     */
  82   "sync"?:boolean,
  83   /**
  84     * return an object of {path:stat} instead of just the resolved path names
  85     */
  86   "return_object"?: boolean,
  87   /**
  88     * dont build up an internal list or object of all of the paths. this can be an important optimization for listing HUGE trees.
  89     */
  90   "no_return"?: boolean,
  91   /**
  92     * filter. filter an array of paths from readdir
  93     */
  94   "filter"?:(directory:string,files:string[])=>string[]|Promise<string[]>,
  95   /**
  96     *  pass in a custom fs object like gracfeful-fs
  97     *  needs stat, lstat, readdir, readlink and sync verisons if you use sync:true
  98     */
  99   "fs"?:any,
 100   /***
 101    * default True. if false this will use stat insteqad of lstat and not find links at all.
 102    */
 103   "find_links?":boolean,
 104 }
 105 ```
 106
 107   - walkdir.sync/walkdir.async only
 108
 109         ```js
 110         {
 111           "return_object": false, // if true the sync return will be in {path:stat} format instead of [path,path,...]
 112           "no_return": false, // if true null will be returned and no array or object will be created with found paths. useful for large listings
 113         }
 114         ```
 115
 116 - callback
 117   - this is bound to the path event of the emitter. its optional in all cases.
 118
 119         ```js
 120         callback(path, stat)
 121         ```
 122
 123 ## events
 124
 125 non error type events are emitted with (path,stat). stat is an instanceof fs.Stats
 126
 127 ### path
 128 fired for everything
 129
 130 ### file
 131 fired only for regular files
 132
 133 ### directory
 134 fired only for directories
 135
 136 ### link
 137 fired when a symbolic link is found
 138
 139 ### end
 140 fired when the entire tree has been read and emitted.
 141
 142 ### socket
 143 fired when a socket descriptor is found
 144
 145 ### fifo
 146 fired when a fifo is found
 147
 148 ### characterdevice
 149 fired when a character device is found
 150
 151 ### blockdevice
 152 fired when a block device is found
 153
 154 ### targetdirectory
 155 fired for the stat of the path you provided as the first argument. is is only fired if it is a directory.
 156
 157 ### empty
 158 fired for empty directory
 159
 160 ## error events
 161 error type events are emitted with (path,error). error being the error object returned from an fs call or other opperation.
 162
 163 ### error
 164 if the target path cannot be read an error event is emitted. this is the only failure case.
 165
 166 ### fail
 167 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.
 168 This is handy if you want to find places you dont have access too.
 169
 170 ## notes
 171 the async emitter returned supports 3 methods
 172
 173 ###end
 174   stop a walk in progress
 175
 176 ###pause
 177   pause the walk. no more events will be emitted until resume
 178
 179 ###resume
 180   resume the walk
 181
 182 ### ignore(path or array of paths)
 183   will not traverse these directories. may be called in the path event handler to ignore dynamically.
 184   ```js
 185   var walk = require('walkdir');
 186   var p = require('path');
 187   walk('/', function(path, stat) {
 188     // ignore all .git directories.
 189     if (p.basename(path) === '.git') {
 190       this.ignore(path)
 191     }
 192   })
 193   ```
 194
 195 ### cancel a walk in progress
 196   ```js
 197   //cancel a walk in progress within callback.
 198
 199   var walk = require('walkdir');
 200   walk('../', function(path, stat) {
 201     this.end();
 202   });
 203
 204   //cancel a walk in progress with emitter handle
 205   var walk = require('walkdir');
 206   var emitter = walk('../');
 207
 208   doSomethingAsync(function() {
 209     emitter.end();
 210   })
 211   ```
 212
 213 ## thanks
 214 thanks to substack. the interface for this module is based off of node-findit
 215
 216 ## contributing
 217 see `CONTRIBUTING.md` for guidelines. this is an open opensource project.
 218