Skip to content

Commit d41ed1e

Browse files
committed
Update README.md with promise support info
1 parent 03b2080 commit d41ed1e

File tree

1 file changed

+16
-25
lines changed

1 file changed

+16
-25
lines changed

README.md

+16-25
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Node.js: fs-extra
22
=================
33

4-
`fs-extra` adds file system methods that aren't included in the native `fs` module. It is a drop in replacement for `fs`.
4+
`fs-extra` adds file system methods that aren't included in the native `fs` module and adds promise support to the `fs` methods. It should be a drop in replacement for `fs`.
55

66
[![npm Package](https://img.shields.io/npm/v/fs-extra.svg?style=flat-square)](https://www.npmjs.org/package/fs-extra)
77
[![build status](https://api.travis-ci.org/jprichardson/node-fs-extra.svg)](http://travis-ci.org/jprichardson/node-fs-extra)
@@ -30,7 +30,7 @@ Installation
3030
Usage
3131
-----
3232

33-
`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are unmodified and attached to `fs-extra`.
33+
`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are attached to `fs-extra`. All `fs` methods return promises if the callback isn't passed.
3434

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

@@ -60,7 +60,7 @@ const fse = require('fs-extra')
6060

6161
Sync vs Async
6262
-------------
63-
Most methods are async by default (they take a callback with an `Error` as first argument).
63+
Most methods are async by default. All async methods will return a promise if the callback isn't passed.
6464

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

@@ -69,14 +69,23 @@ Example:
6969
```js
7070
const fs = require('fs-extra')
7171

72+
// Async with promises:
73+
fs.copy('/tmp/myfile', '/tmp/mynewfile')
74+
.then(() => console.log('success!'))
75+
.catch(err => {
76+
// Handle error
77+
})
78+
79+
// Async with callbacks:
7280
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
7381
if (err) return console.error(err)
74-
console.log("success!")
75-
});
82+
console.log('success!')
83+
})
7684

85+
// Sync:
7786
try {
7887
fs.copySync('/tmp/myfile', '/tmp/mynewfile')
79-
console.log("success!")
88+
console.log('success!')
8089
} catch (err) {
8190
console.error(err)
8291
}
@@ -119,7 +128,7 @@ Methods
119128
- [writeJsonSync](docs/writeJson-sync.md)
120129

121130

122-
**NOTE:** You can still use the native Node.js methods. They are copied over to `fs-extra`.
131+
**NOTE:** You can still use the native Node.js methods. They are promisified and copied over to `fs-extra`.
123132

124133
### What happened to `walk()` and `walkSync()`?
125134

@@ -129,24 +138,6 @@ They were removed from `fs-extra` in v2.0.0. If you need the functionality, `wal
129138
Third Party
130139
-----------
131140

132-
### Promises
133-
134-
Use [Bluebird](https://github.com/petkaantonov/bluebird). See https://github.com/petkaantonov/bluebird/blob/master/API.md#promisification. `fs-extra` is
135-
explicitly listed as supported.
136-
137-
```js
138-
const Promise = require('bluebird')
139-
const fs = Promise.promisifyAll(require('fs-extra'))
140-
```
141-
142-
Or you can use a dedicated package:
143-
144-
- [`fs-extra-promise`](https://github.com/overlookmotel/fs-extra-promise) uses Bluebird.
145-
- [`fs-promise`](https://github.com/kevinbeaty/fs-promise) uses
146-
[Any Promise](https://github.com/kevinbeaty/any-promise) and also covers
147-
[`mz/fs`](https://github.com/normalize/mz/blob/master/fs.js).
148-
- [`fs-p`](https://github.com/grammarly/fs-p) - TypeScript-friendly promises implementation
149-
150141

151142
### TypeScript
152143

0 commit comments

Comments
 (0)