www.aleph1.co.uk Git - yaffs-website/blob - node_modules/klaw/README.md

   1 Node.js - klaw
   2 ==============
   3
   4 A Node.js file system walker extracted from [fs-extra](https://github.com/jprichardson/node-fs-extra).
   5
   6 [![npm Package](https://img.shields.io/npm/v/klaw.svg?style=flat-square)](https://www.npmjs.org/package/klaw)
   7 [![build status](https://api.travis-ci.org/jprichardson/node-klaw.svg)](http://travis-ci.org/jprichardson/node-klaw)
   8 [![windows build status](https://ci.appveyor.com/api/projects/status/github/jprichardson/node-klaw?branch=master&svg=true)](https://ci.appveyor.com/project/jprichardson/node-klaw/branch/master)
   9
  10 <!-- [![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard) -->
  11 <a href="http://standardjs.com"><img src="https://cdn.rawgit.com/feross/standard/master/sticker.svg" alt="Standard" width="100"></a>
  12
  13 Install
  14 -------
  15
  16     npm i --save klaw
  17
  18
  19 Name
  20 ----
  21
  22 `klaw` is `walk` backwards :p
  23
  24
  25 Usage
  26 -----
  27
  28 ### klaw(directory, [options])
  29
  30 Returns a [Readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable) that iterates
  31 through every file and directory starting with `dir` as the root. Every `read()` or `data` event
  32 returns an object with two properties: `path` and `stats`. `path` is the full path of the file and
  33 `stats` is an instance of [fs.Stats](https://nodejs.org/api/fs.html#fs_class_fs_stats).
  34
  35 - `directory`: The directory to recursively walk. Type `string`.
  36 - `options`: [Readable stream options](https://nodejs.org/api/stream.html#stream_new_stream_readable_options) and
  37 the following:
  38   - `queueMethod` (`string`, default: `'shift'`): Either `'shift'` or `'pop'`. On `readdir()` array, call either `shift()` or `pop()`.
  39   - `pathSorter` (`function`, default: `undefined`): Sorting [function for Arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).
  40   - `fs` (`object`, default: `require('fs')`): Use this to hook into the `fs` methods or to use [`mock-fs`](https://github.com/tschaub/mock-fs)
  41   - `filter` (`function`, default: `undefined`): Filtering [function for Arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter)
  42
  43 **Streams 1 (push) example:**
  44
  45 ```js
  46 var klaw = require('klaw')
  47
  48 var items = [] // files, directories, symlinks, etc
  49 klaw('/some/dir')
  50   .on('data', function (item) {
  51     items.push(item.path)
  52   })
  53   .on('end', function () {
  54     console.dir(items) // => [ ... array of files]
  55   })
  56 ```
  57
  58 **Streams 2 & 3 (pull) example:**
  59
  60 ```js
  61 var klaw = require('klaw')
  62
  63 var items = [] // files, directories, symlinks, etc
  64 klaw('/some/dir')
  65   .on('readable', function () {
  66     var item
  67     while ((item = this.read())) {
  68       items.push(item.path)
  69     }
  70   })
  71   .on('end', function () {
  72     console.dir(items) // => [ ... array of files]
  73   })
  74 ```
  75
  76 If you're not sure of the differences on Node.js streams 1, 2, 3 then I'd
  77 recommend this resource as a good starting point: https://strongloop.com/strongblog/whats-new-io-js-beta-streams3/.
  78
  79
  80 ### Error Handling
  81
  82 Listen for the `error` event.
  83
  84 Example:
  85
  86 ```js
  87 var klaw = require('klaw')
  88 klaw('/some/dir')
  89   .on('readable', function () {
  90     var item
  91     while ((item = this.read())) {
  92       // do something with the file
  93     }
  94   })
  95   .on('error', function (err, item) {
  96     console.log(err.message)
  97     console.log(item.path) // the file the error occurred on
  98   })
  99   .on('end', function () {
 100     console.dir(items) // => [ ... array of files]
 101   })
 102
 103 ```
 104
 105
 106 ### Aggregation / Filtering / Executing Actions (Through Streams)
 107
 108 On many occasions you may want to filter files based upon size, extension, etc.
 109 Or you may want to aggregate stats on certain file types. Or maybe you want to
 110 perform an action on certain file types.
 111
 112 You should use the module [`through2`](https://www.npmjs.com/package/through2) to easily
 113 accomplish this.
 114
 115 Install `through2`:
 116
 117     npm i --save through2
 118
 119
 120 **Example (skipping directories):**
 121
 122 ```js
 123 var klaw = require('klaw')
 124 var through2 = require('through2')
 125
 126 var excludeDirFilter = through2.obj(function (item, enc, next) {
 127   if (!item.stats.isDirectory()) this.push(item)
 128   next()
 129 })
 130
 131 var items = [] // files, directories, symlinks, etc
 132 klaw('/some/dir')
 133   .pipe(excludeDirFilter)
 134   .on('data', function (item) {
 135     items.push(item.path)
 136   })
 137   .on('end', function () {
 138     console.dir(items) // => [ ... array of files without directories]
 139   })
 140
 141 ```
 142 **Example (ignore hidden directories):**
 143 ```js
 144 var klaw = require('klaw')
 145 var path = require('path')
 146
 147 var filterFunc = function(item){
 148   var basename = path.basename(item)
 149   return basename === '.' || basename[0] !== '.'
 150 }
 151
 152 klaw('/some/dir', { filter : filterFunc  })
 153   .on('data', function(item){
 154     // only items of none hidden folders will reach here
 155   })
 156
 157 ```
 158
 159 **Example (totaling size of PNG files):**
 160
 161 ```js
 162 var klaw = require('klaw')
 163 var path = require('path')
 164 var through2 = require('through2')
 165
 166 var totalPngsInBytes = 0
 167 var aggregatePngSize = through2.obj(function (item, enc, next) {
 168   if (path.extname(item.path) === '.png') {
 169     totalPngsInBytes += item.stats.size
 170   }
 171   this.push(item)
 172   next()
 173 })
 174
 175 klaw('/some/dir')
 176   .pipe(aggregatePngSize)
 177   .on('data', function (item) {
 178     items.push(item.path)
 179   })
 180   .on('end', function () {
 181     console.dir(totalPngsInBytes) // => total of all pngs (bytes)
 182   })
 183 ```
 184
 185
 186 **Example (deleting all .tmp files):**
 187
 188 ```js
 189 var fs = require('fs')
 190 var klaw = require('klaw')
 191 var through2 = require('through2')
 192
 193 var deleteAction = through2.obj(function (item, enc, next) {
 194   this.push(item)
 195
 196   if (path.extname(item.path) === '.tmp') {
 197     item.deleted = true
 198     fs.unklink(item.path, next)
 199   } else {
 200     item.deleted = false
 201     next()
 202   }
 203 })
 204
 205 var deletedFiles = []
 206 klaw('/some/dir')
 207   .pipe(deleteAction)
 208   .on('data', function (item) {
 209     if (!item.deleted) return
 210     deletedFiles.push(item.path)
 211   })
 212   .on('end', function () {
 213     console.dir(deletedFiles) // => all deleted files
 214   })
 215 ```
 216
 217 You can even chain a bunch of these filters and aggregators together. By using
 218 multiple pipes.
 219
 220 **Example (using multiple filters / aggregators):**
 221
 222 ```js
 223 klaw('/some/dir')
 224   .pipe(filterCertainFiles)
 225   .pipe(deleteSomeOtherFiles)
 226   .on('end', function () {
 227     console.log('all done!')
 228   })
 229 ```
 230
 231 **Example passing (piping) through errors:**
 232
 233 Node.js does not `pipe()` errors. This means that the error on one stream, like
 234 `klaw` will not pipe through to the next. If you want to do this, do the following:
 235
 236 ```js
 237 var klaw = require('klaw')
 238 var through2 = require('through2')
 239
 240 var excludeDirFilter = through2.obj(function (item, enc, next) {
 241   if (!item.stats.isDirectory()) this.push(item)
 242   next()
 243 })
 244
 245 var items = [] // files, directories, symlinks, etc
 246 klaw('/some/dir')
 247   .on('error', function (err) { excludeDirFilter.emit('error', err) }) // forward the error on
 248   .pipe(excludeDirFilter)
 249   .on('data', function (item) {
 250     items.push(item.path)
 251   })
 252   .on('end', function () {
 253     console.dir(items) // => [ ... array of files without directories]
 254   })
 255 ```
 256
 257
 258 ### Searching Strategy
 259
 260 Pass in options for `queueMethod` and `pathSorter` to affect how the file system
 261 is recursively iterated. See the code for more details, it's less than 50 lines :)
 262
 263
 264
 265 License
 266 -------
 267
 268 MIT
 269
 270 Copyright (c) 2015 [JP Richardson](https://github.com/jprichardson)