Update docs for promise support

jprichardson · Apr 26, 2017 · 1613f20 · 1613f20
1 parent d41ed1e
commit 1613f20
Show file tree

Hide file tree

Showing 12 changed files with 130 additions and 12 deletions.
diff --git a/docs/copy.md b/docs/copy.md
@@ -1,4 +1,4 @@
-# copy(src, dest, [options], callback)
+# copy(src, dest, [options, callback])
 
 Copy a file or directory. The directory can have contents. Like `cp -r`.
 
@@ -28,6 +28,15 @@ fs.copy('/tmp/mydir', '/tmp/mynewdir', err => {
 
   console.log('success!')
 }) // copies directory, even if it has subdirectories or files
+
+// Promise usage:
+fs.copy('/tmp/myfile', '/tmp/mynewfile')
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
 
 **Using filter function**

diff --git a/docs/emptyDir.md b/docs/emptyDir.md
@@ -18,4 +18,13 @@ fs.emptyDir('/tmp/some/dir', err => {
 
   console.log('success!')
 })
+
+// With promises
+fs.emptyDir('/tmp/some/dir')
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/ensureDir.md b/docs/ensureDir.md
@@ -1,4 +1,4 @@
-# ensureDir(dir, callback)
+# ensureDir(dir, [callback])
 
 Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`.
 
@@ -17,4 +17,13 @@ fs.ensureDir(dir, err => {
   console.log(err) // => null
   // dir has now been created, including the directory it is to be placed in
 })
+
+// With Promises:
+fs.ensureDir(dir)
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/ensureFile.md b/docs/ensureFile.md
@@ -1,4 +1,4 @@
-# ensureFile(file, callback)
+# 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**.
 
@@ -17,4 +17,13 @@ fs.ensureFile(file, err => {
   console.log(err) // => null
   // file has now been created, including the directory it is to be placed in
 })
+
+// With Promises:
+fs.ensureFile(file)
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/ensureLink.md b/docs/ensureLink.md
@@ -1,4 +1,4 @@
-# ensureLink(srcpath, dstpath, callback)
+# ensureLink(srcpath, dstpath, [callback])
 
 Ensures that the link exists. If the directory structure does not exist, it is created.
 
@@ -17,4 +17,13 @@ fs.ensureLink(srcpath, dstpath, err => {
   console.log(err) // => null
   // link has now been created, including the directory it is to be placed in
 })
+
+// With Promises:
+fs.ensureLink(srcpath, dstpath)
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/ensureSymlink.md b/docs/ensureSymlink.md
@@ -1,4 +1,4 @@
-# ensureSymlink(srcpath, dstpath, [type], callback)
+# ensureSymlink(srcpath, dstpath, [type, callback])
 
 Ensures that the symlink exists. If the directory structure does not exist, it is created.
 
@@ -18,4 +18,13 @@ fs.ensureSymlink(srcpath, dstpath, err => {
   console.log(err) // => null
   // symlink has now been created, including the directory it is to be placed in
 })
+
+// With Promises:
+fs.ensureSymlink(srcpath, dstpath)
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/move.md b/docs/move.md
@@ -1,4 +1,4 @@
-# move(src, dest, [options], callback)
+# move(src, dest, [options, callback])
 
 Moves a file or directory, even across devices.
 
@@ -18,6 +18,14 @@ fs.move('/tmp/somefile', '/tmp/does/not/exist/yet/somefile', err => {
 
   console.log('success!')
 })
+
+fs.move('/tmp/somefile', '/tmp/does/not/exist/yet/somefile')
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
 
 **Using `overwrite` option**

diff --git a/docs/outputFile.md b/docs/outputFile.md
@@ -1,4 +1,4 @@
-# outputFile(file, data, [options], callback)
+# outputFile(file, data, [options, callback])
 
 Almost 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. `file` must be a file path (a buffer or a file descriptor is not allowed). `options` are what you'd pass to [`fs.writeFile()`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback).
 
@@ -20,4 +20,14 @@ fs.outputFile(file, 'hello!', err => {
     console.log(data) // => hello!
   })
 })
+
+// With Promises:
+fs.outputFile(file, 'hello!')
+.then(() => fs.readFile(file, 'utf8'))
+.then(data => {
+  console.log(data) // => hello!
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/outputJson.md b/docs/outputJson.md
@@ -1,4 +1,4 @@
-# outputJson(file, object, [options], callback)
+# outputJson(file, object, [options, callback])
 
 Almost the same as [`writeJson`](writeJson.md), except that if the directory does not exist, it's created.
 `options` are what you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback).
@@ -23,4 +23,14 @@ fs.outputJson(file, {name: 'JP'}, err => {
     console.log(data.name) // => JP
   })
 })
+
+// With Promises:
+fs.outputJson(file, {name: 'JP'})
+.then(() => fs.readJson(file))
+.then(data => {
+  console.log(data.name) // => JP
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/readJson.md b/docs/readJson.md
@@ -1,4 +1,4 @@
-# readJson(file, [options], callback)
+# 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`](https://github.com/jprichardson/node-jsonfile#readfilefilename-options-callback).
@@ -16,9 +16,18 @@ const fs = require('fs-extra')
 
 fs.readJson('./package.json', (err, packageObj) => {
   if (err) console.error(err)
-  
+
   console.log(packageObj.version) // => 0.1.3
 })
+
+// Promise Usage
+fs.readJson('./package.json')
+.then(packageObj => {
+  console.log(packageObj.version) // => 0.1.3
+})
+.catch(err => {
+  // handle error
+})
 ```
 
 ---
@@ -37,4 +46,13 @@ fs.readJson(file, { throws: false }, (err, obj) => {
 
   console.log(obj) // => null
 })
+
+// Promise Usage
+fs.readJson(file, { throws: false })
+.then(obj => {
+  console.log(obj) // => null
+})
+.catch(err => {
+  // Not called
+})
 ```
diff --git a/docs/remove.md b/docs/remove.md
@@ -1,4 +1,4 @@
-# remove(path, callback)
+# remove(path, [callback])
 
 Removes a file or directory. The directory can have contents. Like `rm -rf`.
 
@@ -22,4 +22,13 @@ fs.remove('/home/jprichardson', err => {
 
   console.log('success!') // I just deleted my entire HOME directory.
 })
+
+// Promise Usage
+fs.remove('/tmp/myfile')
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
diff --git a/docs/writeJson.md b/docs/writeJson.md
@@ -1,4 +1,4 @@
-# writeJson(file, object, [options], callback)
+# writeJson(file, object, [options, callback])
 
 Writes an object to a JSON file. `options` are the same that
 you'd pass to [`jsonFile.writeFile()`](https://github.com/jprichardson/node-jsonfile#writefilefilename-options-callback).
@@ -20,6 +20,15 @@ fs.writeJson('./package.json', {name: 'fs-extra'}, err => {
 
   console.log('success!')
 })
+
+// With Promises
+fs.writeJson('./package.json', {name: 'fs-extra'})
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  // handle error
+})
 ```
 
 ---