BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / fs-extra / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 17.5 KiB Download Raw

Node.js: fs-extra =================

fs-extra adds file system methods that aren't included in the native fs module. It is a drop in replacement for fs.

npm Package build status windows Build status downloads per month Coverage Status

Standard JavaScript

NOTE (2016-11-01): Node v0.12 will be unsupported on 2016-12-31.

Why? ----

I got tired of including mkdirp, rimraf, and ncp in most of my projects.

Installation ------------

npm install --save fs-extra

Usage -----

fs-extra is a drop in replacement for native fs. All methods in fs are unmodified and attached to fs-extra.

You don't ever need to include the original fs module again:

var fs = require('fs') // this is no longer necessary

you can now do this:

var fs = require('fs-extra')

or if you prefer to make it clear that you're using fs-extra and not fs, you may want to name your fs variable fse like so:

var fse = require('fs-extra')

you can also keep both, but it's redundant:

var fs = require('fs')
var fse = require('fs-extra')

Sync vs Async ------------- Most methods are async by default (they take a callback with an Error as first argument).

Sync methods on the other hand will throw if an error occurs.

Example:

var fs = require('fs-extra')

fs.copy('/tmp/myfile', '/tmp/mynewfile', function (err) {
  if (err) return console.error(err)
  console.log("success!")
});

try {
  fs.copySync('/tmp/myfile', '/tmp/mynewfile')
  console.log("success!")
} catch (err) {
  console.error(err)
}

Methods -------

NOTE: You can still use the native Node.js methods. They are copied over to fs-extra.

copy()

copy(src, dest, [options], callback)

Copy a file or directory. The directory can have contents. Like cp -r.

Options:

  • clobber (boolean): overwrite existing file or directory, default is true.
  • dereference (boolean): dereference symlinks, default is false.
  • preserveTimestamps (boolean): will set last modification and access times to the ones of the original source files, default is false.
  • filter: Function to filter copied files. Return true to include, false to exclude. This can also be a RegExp, however this is deprecated (See issue #239 for background). _Warning: copySync currently applies the filter only to files (see #180). This will be fixed in a future release._

Sync: copySync()

Example:

var fs = require('fs-extra')

fs.copy('/tmp/myfile', '/tmp/mynewfile', function (err) {
  if (err) return console.error(err)
  console.log("success!")
}) // copies file

fs.copy('/tmp/mydir', '/tmp/mynewdir', function (err) {
  if (err) return console.error(err)
  console.log('success!')
}) // copies directory, even if it has subdirectories or files

emptyDir(dir, [callback])

Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.

Alias: emptydir()

Sync: emptyDirSync(), emptydirSync()

Example:

var fs = require('fs-extra')

// assume this directory has a lot of files and folders
fs.emptyDir('/tmp/some/dir', function (err) {
  if (!err) console.log('success!')
})

ensureFile(file, callback)

Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOT MODIFIED.

Alias: createFile()

Sync: createFileSync(),ensureFileSync()

Example:

var fs = require('fs-extra')

var file = '/tmp/this/path/does/not/exist/file.txt'
fs.ensureFile(file, function (err) {
  console.log(err) // => null
  // file has now been created, including the directory it is to be placed in
})

ensureDir(dir, callback)

Ensures that the directory exists. If the directory structure does not exist, it is created.

Sync: ensureDirSync()

Example:

var fs = require('fs-extra')

var dir = '/tmp/this/path/does/not/exist'
fs.ensureDir(dir, function (err) {
  console.log(err) // => null
  // dir has now been created, including the directory it is to be placed in
})

ensureLink(srcpath, dstpath, callback)

Ensures that the link exists. If the directory structure does not exist, it is created.

Sync: ensureLinkSync()

Example:

var fs = require('fs-extra')

var srcpath = '/tmp/file.txt'
var dstpath = '/tmp/this/path/does/not/exist/file.txt'
fs.ensureLink(srcpath, dstpath, function (err) {
  console.log(err) // => null
  // link has now been created, including the directory it is to be placed in
})

ensureSymlink(srcpath, dstpath, [type], callback)

Ensures that the symlink exists. If the directory structure does not exist, it is created.

Sync: ensureSymlinkSync()

Example:

var fs = require('fs-extra')

var srcpath = '/tmp/file.txt'
var dstpath = '/tmp/this/path/does/not/exist/file.txt'
fs.ensureSymlink(srcpath, dstpath, function (err) {
  console.log(err) // => null
  // symlink has now been created, including the directory it is to be placed in
})

mkdirs(dir, callback)

Creates a directory. If the parent hierarchy doesn't exist, it's created. Like mkdir -p.

Alias: mkdirp()

Sync: mkdirsSync() / mkdirpSync()

Examples:

var fs = require('fs-extra')

fs.mkdirs('/tmp/some/long/path/that/prob/doesnt/exist', function (err) {
  if (err) return console.error(err)
  console.log("success!")
})

fs.mkdirsSync('/tmp/another/path')

move(src, dest, [options], callback)

Moves a file or directory, even across devices.

Options:

  • clobber (boolean): overwrite existing file or directory
  • limit (number): number of concurrent moves, see ncp for more information

Example:

var fs = require('fs-extra')

fs.move('/tmp/somefile', '/tmp/does/not/exist/yet/somefile', function (err) {
  if (err) return console.error(err)
  console.log("success!")
})

outputFile(file, data, [options], callback)

Almost the same as writeFile (i.e. it overwrites), except that if the parent directory does not exist, it's created. options are what you'd pass to fs.writeFile().

Sync: outputFileSync()

Example:

var fs = require('fs-extra')
var file = '/tmp/this/path/does/not/exist/file.txt'

fs.outputFile(file, 'hello!', function (err) {
  console.log(err) // => null

  fs.readFile(file, 'utf8', function (err, data) {
    console.log(data) // => hello!
  })
})

outputJson(file, data, [options], callback)

Almost the same as writeJson, except that if the directory does not exist, it's created. options are what you'd pass to jsonFile.writeFile().

Alias: outputJSON()

Sync: outputJsonSync(), outputJSONSync()

Example:

var fs = require('fs-extra')
var file = '/tmp/this/path/does/not/exist/file.txt'

fs.outputJson(file, {name: 'JP'}, function (err) {
  console.log(err) // => null

  fs.readJson(file, function(err, data) {
    console.log(data.name) // => JP
  })
})

readJson(file, [options], callback)

Reads a JSON file and then parses it into an object. options are the same that you'd pass to jsonFile.readFile.

Alias: readJSON()

Sync: readJsonSync(), readJSONSync()

Example:

var fs = require('fs-extra')

fs.readJson('./package.json', function (err, packageObj) {
  console.log(packageObj.version) // => 0.1.3
})

readJsonSync() can take a throws option set to false and it won't throw if the JSON is invalid. Example:

var fs = require('fs-extra')
var file = path.join('/tmp/some-invalid.json')
var data = '{not valid JSON'
fs.writeFileSync(file, data)

var obj = fs.readJsonSync(file, {throws: false})
console.log(obj) // => null

remove(dir, callback)

Removes a file or directory. The directory can have contents. Like rm -rf.

Sync: removeSync()

Examples:

var fs = require('fs-extra')

fs.remove('/tmp/myfile', function (err) {
  if (err) return console.error(err)

  console.log('success!')
})

fs.removeSync('/home/jprichardson') //I just deleted my entire HOME directory.

walk()

walk(dir, [streamOptions])

The function walk() from the module klaw.

Returns a Readable stream that iterates through every file and directory starting with dir as the root. Every read() or data event returns an object with two properties: path and stats. path is the full path of the file and stats is an instance of fs.Stats.

Streams 1 (push) example:

var fs = require('fs-extra')
var items = [] // files, directories, symlinks, etc
fs.walk(TEST_DIR)
  .on('data', function (item) {
    items.push(item.path)
  })
  .on('end', function () {
    console.dir(items) // => [ ... array of files]
  })

Streams 2 & 3 (pull) example:

var items = [] // files, directories, symlinks, etc
var fs = require('fs-extra')
fs.walk(TEST_DIR)
  .on('readable', function () {
    var item
    while ((item = this.read())) {
      items.push(item.path)
    }
  })
  .on('end', function () {
    console.dir(items) // => [ ... array of files]
  })

If you're not sure of the differences on Node.js streams 1, 2, 3 then I'd recommend this resource as a good starting point: https://strongloop.com/strongblog/whats-new-io-js-beta-streams3/.

See klaw documentation for more detailed usage.

walkSync(dir)

Lists all files inside a directory recursively

Examples:

var fs = require('fs-extra')

var files = fs.walkSync('/home/jprichardson')
// files = ['/home/jprichardson/file1', '/home/jprichardson/dir1/file2']

writeJson(file, object, [options], callback)

Writes an object to a JSON file. options are the same that you'd pass to jsonFile.writeFile().

Alias: writeJSON()

Sync: writeJsonSync(), writeJSONSync()

Example:

var fs = require('fs-extra')
fs.writeJson('./package.json', {name: 'fs-extra'}, function (err) {
  console.log(err)
})

Third Party -----------

Promises

Use Bluebird. See https://github.com/petkaantonov/bluebird/blob/master/API.md#promisification. fs-extra is explicitly listed as supported.

var Promise = require('bluebird')
var fs = Promise.promisifyAll(require('fs-extra'))

Or you can use the package fs-extra-promise that marries the two together.

TypeScript

If you like TypeScript, you can use fs-extra with it: https://github.com/borisyankov/DefinitelyTyped/tree/master/fs-extra

File / Directory Watching

If you want to watch for changes to files or directories, then you should use chokidar.

Misc.

  • mfs - Monitor your fs-extra calls.

Hacking on fs-extra -------------------

Wanna hack on fs-extra? Great! Your help is needed! fs-extra is one of the most depended upon Node.js packages. This project uses JavaScript Standard Style - if the name or style choices bother you, you're gonna have to get over it :) If standard is good enough for npm, it's good enough for fs-extra.

js-standard-style

What's needed?

  • First, take a look at existing issues. Those are probably going to be where the priority lies.
  • More tests for edge cases. Specifically on different platforms. There can never be enough tests.
  • Improve test coverage. See coveralls output for more info.
  • After the directory walker is integrated, any function that needs to traverse directories like

copy, remove, or mkdirs should be built on top of it.

Note: If you make any big changes, you should definitely file an issue for discussion first.

Running the Test Suite

fs-extra contains hundreds of tests.

  • npm run lint: runs the linter (standard)
  • npm run unit: runs the unit tests
  • npm test: runs both the linter and the tests

Windows

If you run the tests on the Windows and receive a lot of symbolic link EPERM permission errors, it's because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7 However, I didn't have much luck doing this.

Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows. I open the Node.js command prompt and run as Administrator. I then map the network drive running the following command:

net use z: "\\vmware-host\Shared Folders"

I can then navigate to my fs-extra directory and run the tests.

Naming ------

I put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:

  • https://github.com/jprichardson/node-fs-extra/issues/2
  • https://github.com/flatiron/utile/issues/11
  • https://github.com/ryanmcgrath/wrench-js/issues/29
  • https://github.com/substack/node-mkdirp/issues/17

First, I believe that in as many cases as possible, the Node.js naming schemes should be chosen. However, there are problems with the Node.js own naming schemes.

For example, fs.readFile() and fs.readdir(): the F is capitalized in File and the d is not capitalized in dir. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: fs.mkdir(), fs.rmdir(), fs.chown(), etc.

We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: cp, cp -r, mkdir -p, and rm -rf?

My perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too.

So, if you want to remove a file or a directory regardless of whether it has contents, just call fs.remove(path). If you want to copy a file or a directory whether it has contents, just call fs.copy(source, destination). If you want to create a directory regardless of whether its parent directories exist, just call fs.mkdirs(path) or fs.mkdirp(path).

Credit ------

fs-extra wouldn't be possible without using the modules from the following authors:

License -------

Licensed under MIT

Copyright (c) 2011-2016 JP Richardson

[1]: http://nodejs.org/docs/latest/api/fs.html

[jsonfile]: https://github.com/jprichardson/node-jsonfile

Source
1Node.js: fs-extra
2=================
3
4`fs-extra` adds file system methods that aren't included in the native `fs` module. It is a drop in replacement for `fs`.
5
6[![npm Package](https://img.shields.io/npm/v/fs-extra.svg?style=flat-square)](https://www.npmjs.org/package/fs-extra)
7[![build status](https://api.travis-ci.org/jprichardson/node-fs-extra.svg)](http://travis-ci.org/jprichardson/node-fs-extra)
8[![windows Build status](https://img.shields.io/appveyor/ci/jprichardson/node-fs-extra/master.svg?label=windows%20build)](https://ci.appveyor.com/project/jprichardson/node-fs-extra/branch/master)
9[![downloads per month](http://img.shields.io/npm/dm/fs-extra.svg)](https://www.npmjs.org/package/fs-extra)
10[![Coverage Status](https://img.shields.io/coveralls/jprichardson/node-fs-extra.svg)](https://coveralls.io/r/jprichardson/node-fs-extra)
11
12<a href="https://github.com/feross/standard"><img src="https://cdn.rawgit.com/feross/standard/master/sticker.svg" alt="Standard JavaScript" width="100"></a>
13
14**NOTE (2016-11-01):** Node v0.12 will be unsupported on 2016-12-31.
15
16
17Why?
18----
19
20I got tired of including `mkdirp`, `rimraf`, and `ncp` in most of my projects.
21
22
23
24
25Installation
26------------
27
28 npm install --save fs-extra
29
30
31
32Usage
33-----
34
35`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are unmodified and attached to `fs-extra`.
36
37You don't ever need to include the original `fs` module again:
38
39```js
40var fs = require('fs') // this is no longer necessary
41```
42
43you can now do this:
44
45```js
46var fs = require('fs-extra')
47```
48
49or if you prefer to make it clear that you're using `fs-extra` and not `fs`, you may want
50to name your `fs` variable `fse` like so:
51
52```js
53var fse = require('fs-extra')
54```
55
56you can also keep both, but it's redundant:
57
58```js
59var fs = require('fs')
60var fse = require('fs-extra')
61```
62
63Sync vs Async
64-------------
65Most methods are async by default (they take a callback with an `Error` as first argument).
66
67Sync methods on the other hand will throw if an error occurs.
68
69Example:
70
71```js
72var fs = require('fs-extra')
73
74fs.copy('/tmp/myfile', '/tmp/mynewfile', function (err) {
75 if (err) return console.error(err)
76 console.log("success!")
77});
78
79try {
80 fs.copySync('/tmp/myfile', '/tmp/mynewfile')
81 console.log("success!")
82} catch (err) {
83 console.error(err)
84}
85```
86
87
88Methods
89-------
90- [copy](#copy)
91- [copySync](#copy)
92- [emptyDir](#emptydirdir-callback)
93- [emptyDirSync](#emptydirdir-callback)
94- [ensureFile](#ensurefilefile-callback)
95- [ensureFileSync](#ensurefilefile-callback)
96- [ensureDir](#ensuredirdir-callback)
97- [ensureDirSync](#ensuredirdir-callback)
98- [ensureLink](#ensurelinksrcpath-dstpath-callback)
99- [ensureLinkSync](#ensurelinksrcpath-dstpath-callback)
100- [ensureSymlink](#ensuresymlinksrcpath-dstpath-type-callback)
101- [ensureSymlinkSync](#ensuresymlinksrcpath-dstpath-type-callback)
102- [mkdirs](#mkdirsdir-callback)
103- [mkdirsSync](#mkdirsdir-callback)
104- [move](#movesrc-dest-options-callback)
105- [outputFile](#outputfilefile-data-options-callback)
106- [outputFileSync](#outputfilefile-data-options-callback)
107- [outputJson](#outputjsonfile-data-options-callback)
108- [outputJsonSync](#outputjsonfile-data-options-callback)
109- [readJson](#readjsonfile-options-callback)
110- [readJsonSync](#readjsonfile-options-callback)
111- [remove](#removedir-callback)
112- [removeSync](#removedir-callback)
113- [walk](#walk)
114- [walkSync](#walkSyncDir)
115- [writeJson](#writejsonfile-object-options-callback)
116- [writeJsonSync](#writejsonfile-object-options-callback)
117
118
119**NOTE:** You can still use the native Node.js methods. They are copied over to `fs-extra`.
120
121
122### copy()
123
124**copy(src, dest, [options], callback)**
125
126
127Copy a file or directory. The directory can have contents. Like `cp -r`.
128
129Options:
130- clobber (boolean): overwrite existing file or directory, default is `true`.
131- dereference (boolean): dereference symlinks, default is `false`.
132- preserveTimestamps (boolean): will set last modification and access times to the ones of the original source files, default is `false`.
133- filter: Function to filter copied files. Return `true` to include, `false` to exclude. This can also be a RegExp, however this is deprecated (See [issue #239](https://github.com/jprichardson/node-fs-extra/issues/239) for background). _Warning: `copySync` currently applies the filter only to files (see [#180](https://github.com/jprichardson/node-fs-extra/issues/180)). This will be fixed in a future release._
134
135Sync: `copySync()`
136
137Example:
138
139```js
140var fs = require('fs-extra')
141
142fs.copy('/tmp/myfile', '/tmp/mynewfile', function (err) {
143 if (err) return console.error(err)
144 console.log("success!")
145}) // copies file
146
147fs.copy('/tmp/mydir', '/tmp/mynewdir', function (err) {
148 if (err) return console.error(err)
149 console.log('success!')
150}) // copies directory, even if it has subdirectories or files
151```
152
153
154### emptyDir(dir, [callback])
155
156Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.
157
158Alias: `emptydir()`
159
160Sync: `emptyDirSync()`, `emptydirSync()`
161
162Example:
163
164```js
165var fs = require('fs-extra')
166
167// assume this directory has a lot of files and folders
168fs.emptyDir('/tmp/some/dir', function (err) {
169 if (!err) console.log('success!')
170})
171```
172
173
174### ensureFile(file, callback)
175
176Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is **NOT MODIFIED**.
177
178Alias: `createFile()`
179
180Sync: `createFileSync()`,`ensureFileSync()`
181
182
183Example:
184
185```js
186var fs = require('fs-extra')
187
188var file = '/tmp/this/path/does/not/exist/file.txt'
189fs.ensureFile(file, function (err) {
190 console.log(err) // => null
191 // file has now been created, including the directory it is to be placed in
192})
193```
194
195
196### ensureDir(dir, callback)
197
198Ensures that the directory exists. If the directory structure does not exist, it is created.
199
200Sync: `ensureDirSync()`
201
202
203Example:
204
205```js
206var fs = require('fs-extra')
207
208var dir = '/tmp/this/path/does/not/exist'
209fs.ensureDir(dir, function (err) {
210 console.log(err) // => null
211 // dir has now been created, including the directory it is to be placed in
212})
213```
214
215
216### ensureLink(srcpath, dstpath, callback)
217
218Ensures that the link exists. If the directory structure does not exist, it is created.
219
220Sync: `ensureLinkSync()`
221
222
223Example:
224
225```js
226var fs = require('fs-extra')
227
228var srcpath = '/tmp/file.txt'
229var dstpath = '/tmp/this/path/does/not/exist/file.txt'
230fs.ensureLink(srcpath, dstpath, function (err) {
231 console.log(err) // => null
232 // link has now been created, including the directory it is to be placed in
233})
234```
235
236
237### ensureSymlink(srcpath, dstpath, [type], callback)
238
239Ensures that the symlink exists. If the directory structure does not exist, it is created.
240
241Sync: `ensureSymlinkSync()`
242
243
244Example:
245
246```js
247var fs = require('fs-extra')
248
249var srcpath = '/tmp/file.txt'
250var dstpath = '/tmp/this/path/does/not/exist/file.txt'
251fs.ensureSymlink(srcpath, dstpath, function (err) {
252 console.log(err) // => null
253 // symlink has now been created, including the directory it is to be placed in
254})
255```
256
257
258### mkdirs(dir, callback)
259
260Creates a directory. If the parent hierarchy doesn't exist, it's created. Like `mkdir -p`.
261
262Alias: `mkdirp()`
263
264Sync: `mkdirsSync()` / `mkdirpSync()`
265
266
267Examples:
268
269```js
270var fs = require('fs-extra')
271
272fs.mkdirs('/tmp/some/long/path/that/prob/doesnt/exist', function (err) {
273 if (err) return console.error(err)
274 console.log("success!")
275})
276
277fs.mkdirsSync('/tmp/another/path')
278```
279
280
281### move(src, dest, [options], callback)
282
283Moves a file or directory, even across devices.
284
285Options:
286- clobber (boolean): overwrite existing file or directory
287- limit (number): number of concurrent moves, see ncp for more information
288
289Example:
290
291```js
292var fs = require('fs-extra')
293
294fs.move('/tmp/somefile', '/tmp/does/not/exist/yet/somefile', function (err) {
295 if (err) return console.error(err)
296 console.log("success!")
297})
298```
299
300
301### outputFile(file, data, [options], callback)
302
303Almost the same as `writeFile` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `options` are what you'd pass to [`fs.writeFile()`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback).
304
305Sync: `outputFileSync()`
306
307
308Example:
309
310```js
311var fs = require('fs-extra')
312var file = '/tmp/this/path/does/not/exist/file.txt'
313
314fs.outputFile(file, 'hello!', function (err) {
315 console.log(err) // => null
316
317 fs.readFile(file, 'utf8', function (err, data) {
318 console.log(data) // => hello!
319 })
320})
321```
322
323
324
325### outputJson(file, data, [options], callback)
326
327Almost the same as `writeJson`, except that if the directory does not exist, it's created.
328`options` are what you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback).
329
330Alias: `outputJSON()`
331
332Sync: `outputJsonSync()`, `outputJSONSync()`
333
334
335Example:
336
337```js
338var fs = require('fs-extra')
339var file = '/tmp/this/path/does/not/exist/file.txt'
340
341fs.outputJson(file, {name: 'JP'}, function (err) {
342 console.log(err) // => null
343
344 fs.readJson(file, function(err, data) {
345 console.log(data.name) // => JP
346 })
347})
348```
349
350
351
352### readJson(file, [options], callback)
353
354Reads a JSON file and then parses it into an object. `options` are the same
355that you'd pass to [`jsonFile.readFile`](https://github.com/jprichardson/node-jsonfile#readfilefilename-options-callback).
356
357Alias: `readJSON()`
358
359Sync: `readJsonSync()`, `readJSONSync()`
360
361
362Example:
363
364```js
365var fs = require('fs-extra')
366
367fs.readJson('./package.json', function (err, packageObj) {
368 console.log(packageObj.version) // => 0.1.3
369})
370```
371
372`readJsonSync()` can take a `throws` option set to `false` and it won't throw if the JSON is invalid. Example:
373
374```js
375var fs = require('fs-extra')
376var file = path.join('/tmp/some-invalid.json')
377var data = '{not valid JSON'
378fs.writeFileSync(file, data)
379
380var obj = fs.readJsonSync(file, {throws: false})
381console.log(obj) // => null
382```
383
384
385### remove(dir, callback)
386
387Removes a file or directory. The directory can have contents. Like `rm -rf`.
388
389Sync: `removeSync()`
390
391
392Examples:
393
394```js
395var fs = require('fs-extra')
396
397fs.remove('/tmp/myfile', function (err) {
398 if (err) return console.error(err)
399
400 console.log('success!')
401})
402
403fs.removeSync('/home/jprichardson') //I just deleted my entire HOME directory.
404```
405
406### walk()
407
408**walk(dir, [streamOptions])**
409
410The function `walk()` from the module [`klaw`](https://github.com/jprichardson/node-klaw).
411
412Returns a [Readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable) that iterates
413through every file and directory starting with `dir` as the root. Every `read()` or `data` event
414returns an object with two properties: `path` and `stats`. `path` is the full path of the file and
415`stats` is an instance of [fs.Stats](https://nodejs.org/api/fs.html#fs_class_fs_stats).
416
417Streams 1 (push) example:
418
419```js
420var fs = require('fs-extra')
421var items = [] // files, directories, symlinks, etc
422fs.walk(TEST_DIR)
423 .on('data', function (item) {
424 items.push(item.path)
425 })
426 .on('end', function () {
427 console.dir(items) // => [ ... array of files]
428 })
429```
430
431Streams 2 & 3 (pull) example:
432
433```js
434var items = [] // files, directories, symlinks, etc
435var fs = require('fs-extra')
436fs.walk(TEST_DIR)
437 .on('readable', function () {
438 var item
439 while ((item = this.read())) {
440 items.push(item.path)
441 }
442 })
443 .on('end', function () {
444 console.dir(items) // => [ ... array of files]
445 })
446```
447
448If you're not sure of the differences on Node.js streams 1, 2, 3 then I'd
449recommend this resource as a good starting point: https://strongloop.com/strongblog/whats-new-io-js-beta-streams3/.
450
451**See [`klaw` documentation](https://github.com/jprichardson/node-klaw) for more detailed usage.**
452
453### walkSync(dir)
454
455Lists all files inside a directory recursively
456
457Examples:
458
459```js
460var fs = require('fs-extra')
461
462var files = fs.walkSync('/home/jprichardson')
463// files = ['/home/jprichardson/file1', '/home/jprichardson/dir1/file2']
464```
465
466### writeJson(file, object, [options], callback)
467
468Writes an object to a JSON file. `options` are the same that
469you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback).
470
471Alias: `writeJSON()`
472
473Sync: `writeJsonSync()`, `writeJSONSync()`
474
475Example:
476
477```js
478var fs = require('fs-extra')
479fs.writeJson('./package.json', {name: 'fs-extra'}, function (err) {
480 console.log(err)
481})
482```
483
484
485Third Party
486-----------
487
488### Promises
489
490Use [Bluebird](https://github.com/petkaantonov/bluebird). See https://github.com/petkaantonov/bluebird/blob/master/API.md#promisification. `fs-extra` is
491explicitly listed as supported.
492
493```js
494var Promise = require('bluebird')
495var fs = Promise.promisifyAll(require('fs-extra'))
496```
497
498Or you can use the package [`fs-extra-promise`](https://github.com/overlookmotel/fs-extra-promise) that marries the two together.
499
500
501### TypeScript
502
503If you like TypeScript, you can use `fs-extra` with it: https://github.com/borisyankov/DefinitelyTyped/tree/master/fs-extra
504
505
506### File / Directory Watching
507
508If you want to watch for changes to files or directories, then you should use [chokidar](https://github.com/paulmillr/chokidar).
509
510
511### Misc.
512
513- [mfs](https://github.com/cadorn/mfs) - Monitor your fs-extra calls.
514
515
516
517Hacking on fs-extra
518-------------------
519
520Wanna hack on `fs-extra`? Great! Your help is needed! [fs-extra is one of the most depended upon Node.js packages](http://nodei.co/npm/fs-extra.png?downloads=true&downloadRank=true&stars=true). This project
521uses [JavaScript Standard Style](https://github.com/feross/standard) - if the name or style choices bother you,
522you're gonna have to get over it :) If `standard` is good enough for `npm`, it's good enough for `fs-extra`.
523
524[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)
525
526What's needed?
527- First, take a look at existing issues. Those are probably going to be where the priority lies.
528- More tests for edge cases. Specifically on different platforms. There can never be enough tests.
529- Improve test coverage. See coveralls output for more info.
530- After the directory walker is integrated, any function that needs to traverse directories like
531`copy`, `remove`, or `mkdirs` should be built on top of it.
532
533Note: If you make any big changes, **you should definitely file an issue for discussion first.**
534
535### Running the Test Suite
536
537fs-extra contains hundreds of tests.
538
539- `npm run lint`: runs the linter ([standard](http://standardjs.com/))
540- `npm run unit`: runs the unit tests
541- `npm test`: runs both the linter and the tests
542
543
544### Windows
545
546If you run the tests on the Windows and receive a lot of symbolic link `EPERM` permission errors, it's
547because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's
548account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7
549However, I didn't have much luck doing this.
550
551Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows.
552I open the `Node.js command prompt` and run as `Administrator`. I then map the network drive running the following command:
553
554 net use z: "\\vmware-host\Shared Folders"
555
556I can then navigate to my `fs-extra` directory and run the tests.
557
558
559Naming
560------
561
562I put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:
563
564* https://github.com/jprichardson/node-fs-extra/issues/2
565* https://github.com/flatiron/utile/issues/11
566* https://github.com/ryanmcgrath/wrench-js/issues/29
567* https://github.com/substack/node-mkdirp/issues/17
568
569First, I believe that in as many cases as possible, the [Node.js naming schemes](http://nodejs.org/api/fs.html) should be chosen. However, there are problems with the Node.js own naming schemes.
570
571For example, `fs.readFile()` and `fs.readdir()`: the **F** is capitalized in *File* and the **d** is not capitalized in *dir*. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: `fs.mkdir()`, `fs.rmdir()`, `fs.chown()`, etc.
572
573We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: `cp`, `cp -r`, `mkdir -p`, and `rm -rf`?
574
575My perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too.
576
577So, if you want to remove a file or a directory regardless of whether it has contents, just call `fs.remove(path)`. If you want to copy a file or a directory whether it has contents, just call `fs.copy(source, destination)`. If you want to create a directory regardless of whether its parent directories exist, just call `fs.mkdirs(path)` or `fs.mkdirp(path)`.
578
579
580Credit
581------
582
583`fs-extra` wouldn't be possible without using the modules from the following authors:
584
585- [Isaac Shlueter](https://github.com/isaacs)
586- [Charlie McConnel](https://github.com/avianflu)
587- [James Halliday](https://github.com/substack)
588- [Andrew Kelley](https://github.com/andrewrk)
589
590
591
592
593License
594-------
595
596Licensed under MIT
597
598Copyright (c) 2011-2016 [JP Richardson](https://github.com/jprichardson)
599
600[1]: http://nodejs.org/docs/latest/api/fs.html
601
602
603[jsonfile]: https://github.com/jprichardson/node-jsonfile