From b0223ac13a029c283955f50912eef16ed55d1eae Mon Sep 17 00:00:00 2001
From: RyanZim <opensrc@ryanzim.com>
Date: Sat, 8 Apr 2017 13:38:11 -0400
Subject: [PATCH 1/4] Universalify native fs methods

---
 lib/{ => fs}/__tests__/fs-integration.test.js |  2 +-
 lib/fs/__tests__/mz.test.js                   | 50 +++++++++++++++
 lib/fs/index.js                               | 64 +++++++++++++++++++
 lib/index.js                                  | 13 ++--
 package.json                                  |  3 +-
 5 files changed, 121 insertions(+), 11 deletions(-)
 rename lib/{ => fs}/__tests__/fs-integration.test.js (96%)
 create mode 100644 lib/fs/__tests__/mz.test.js
 create mode 100644 lib/fs/index.js

diff --git a/lib/__tests__/fs-integration.test.js b/lib/fs/__tests__/fs-integration.test.js
similarity index 96%
rename from lib/__tests__/fs-integration.test.js
rename to lib/fs/__tests__/fs-integration.test.js
index 4ff52c59..ea19c1f0 100644
--- a/lib/__tests__/fs-integration.test.js
+++ b/lib/fs/__tests__/fs-integration.test.js
@@ -2,7 +2,7 @@
 
 const os = require('os')
 const fs = require('fs')
-const fse = require('../')
+const fse = require('../..')
 const path = require('path')
 const assert = require('assert')
 
diff --git a/lib/fs/__tests__/mz.test.js b/lib/fs/__tests__/mz.test.js
new file mode 100644
index 00000000..5c61f339
--- /dev/null
+++ b/lib/fs/__tests__/mz.test.js
@@ -0,0 +1,50 @@
+// This is adapted from https://github.com/normalize/mz
+// Copyright (c) 2014-2016 Jonathan Ong me@jongleberry.com and Contributors
+
+/* eslint-env mocha */
+const assert = require('assert')
+const fs = require('../..')
+
+describe('fs', () => {
+  it('.stat()', done => {
+    fs.stat(__filename).then(function (stats) {
+      assert.equal(typeof stats.size, 'number')
+      done()
+    }).catch(done)
+  })
+
+  it('.statSync()', () => {
+    const stats = fs.statSync(__filename)
+    assert.equal(typeof stats.size, 'number')
+  })
+
+  it('.exists()', done => {
+    fs.exists(__filename).then(function (exists) {
+      assert(exists)
+      done()
+    }).catch(done)
+  })
+
+  it('.existsSync()', () => {
+    const exists = fs.existsSync(__filename)
+    assert(exists)
+  })
+
+  describe('callback support', () => {
+    it('.stat()', done => {
+      fs.stat(__filename, function (err, stats) {
+        assert(!err)
+        assert.equal(typeof stats.size, 'number')
+        done()
+      })
+    })
+
+    // This test is different from mz/fs, since we are a drop-in replacement for native fs
+    it('.exists()', done => {
+      fs.exists(__filename, function (exists) {
+        assert(exists)
+        done()
+      })
+    })
+  })
+})
diff --git a/lib/fs/index.js b/lib/fs/index.js
new file mode 100644
index 00000000..85d96a82
--- /dev/null
+++ b/lib/fs/index.js
@@ -0,0 +1,64 @@
+// This is adapted from https://github.com/normalize/mz
+// Copyright (c) 2014-2016 Jonathan Ong me@jongleberry.com and Contributors
+const u = require('universalify').fromCallback
+const fs = require('graceful-fs')
+
+const api = [
+  'rename',
+  'ftruncate',
+  'chown',
+  'fchown',
+  'lchown',
+  'chmod',
+  'fchmod',
+  'stat',
+  'lstat',
+  'fstat',
+  'link',
+  'symlink',
+  'readlink',
+  'realpath',
+  'unlink',
+  'rmdir',
+  'mkdir',
+  'readdir',
+  'close',
+  'open',
+  'utimes',
+  'futimes',
+  'fsync',
+  'fdatasync',
+  'write',
+  'read',
+  'readFile',
+  'writeFile',
+  'appendFile',
+  'truncate'
+]
+// fs.mkdtemp() was added in Node.js v5.10.0, so check if it exists
+typeof fs.mkdtemp === 'function' && api.push('mkdtemp')
+
+// Export all keys:
+Object.keys(fs).forEach(key => {
+  exports[key] = fs[key]
+})
+
+// Universalify async methods:
+api.forEach(method => {
+  exports[method] = u(fs[method])
+})
+
+// We differ from mz/fs in that we still ship the old, broken, fs.exists()
+// since we are a drop-in replacement for the native module
+exports.exists = function (filename, callback) {
+  if (typeof callback === 'function') {
+    return fs.exists(filename, function (exists) {
+      callback(exists)
+    })
+  }
+  return new Promise(function (resolve) {
+    return fs.exists(filename, function (exists) {
+      resolve(exists)
+    })
+  })
+}
diff --git a/lib/index.js b/lib/index.js
index 88ad4642..dd9fe2b2 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -2,16 +2,11 @@
 
 const assign = require('./util/assign')
 
-const fse = {}
-const gfs = require('graceful-fs')
-
-// attach fs methods to fse
-Object.keys(gfs).forEach(key => {
-  fse[key] = gfs[key]
-})
-
-const fs = fse
+const fs = {}
 
+// Export graceful-fs:
+assign(fs, require('./fs'))
+// Export extra methods:
 assign(fs, require('./copy'))
 assign(fs, require('./copy-sync'))
 assign(fs, require('./mkdirs'))
diff --git a/package.json b/package.json
index d4894948..7bd3071b 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,8 @@
   "license": "MIT",
   "dependencies": {
     "graceful-fs": "^4.1.2",
-    "jsonfile": "^2.1.0"
+    "jsonfile": "^2.1.0",
+    "universalify": "^0.1.0"
   },
   "devDependencies": {
     "coveralls": "^2.11.2",

From 4e47caa413b5064481df47778976b54b01f8b3ba Mon Sep 17 00:00:00 2001
From: RyanZim <opensrc@ryanzim.com>
Date: Sat, 8 Apr 2017 14:28:22 -0400
Subject: [PATCH 2/4] Universalify fs-extra methods

---
 lib/__tests__/promise.test.js          | 29 ++++++++++++++
 lib/copy/index.js                      |  3 +-
 lib/empty/index.js                     |  5 ++-
 lib/ensure/file.js                     |  8 ++--
 lib/ensure/link.js                     |  8 ++--
 lib/ensure/symlink.js                  |  8 ++--
 lib/fs/index.js                        | 53 ++++++++++++--------------
 lib/json/__tests__/output-json.test.js |  8 ++++
 lib/json/index.js                      | 11 ++++--
 lib/json/jsonfile.js                   | 11 ++----
 lib/mkdirs/index.js                    | 17 ++++++---
 lib/move/index.js                      |  3 +-
 lib/output/__tests__/output.test.js    |  5 +++
 lib/output/index.js                    |  3 +-
 lib/remove/index.js                    | 14 ++-----
 15 files changed, 111 insertions(+), 75 deletions(-)
 create mode 100644 lib/__tests__/promise.test.js

diff --git a/lib/__tests__/promise.test.js b/lib/__tests__/promise.test.js
new file mode 100644
index 00000000..9b3806d7
--- /dev/null
+++ b/lib/__tests__/promise.test.js
@@ -0,0 +1,29 @@
+'use strict'
+
+/* eslint-env mocha */
+
+const fse = require('..')
+
+const methods = [
+  'copy',
+  'emptyDir',
+  'ensureFile',
+  'ensureDir',
+  'ensureLink',
+  'ensureSymlink',
+  'mkdirs',
+  'move',
+  'readJson',
+  'readJSON',
+  'remove',
+  'writeJson',
+  'writeJSON'
+]
+
+describe('promise support', () => {
+  methods.forEach(method => {
+    it(method, done => {
+      fse[method]().catch(() => done())
+    })
+  })
+})
diff --git a/lib/copy/index.js b/lib/copy/index.js
index 3e090161..a6a51da6 100644
--- a/lib/copy/index.js
+++ b/lib/copy/index.js
@@ -1,3 +1,4 @@
+const u = require('universalify').fromCallback
 module.exports = {
-  copy: require('./copy')
+  copy: u(require('./copy'))
 }
diff --git a/lib/empty/index.js b/lib/empty/index.js
index 180c3f79..db05c171 100644
--- a/lib/empty/index.js
+++ b/lib/empty/index.js
@@ -1,11 +1,12 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const fs = require('fs')
 const path = require('path')
 const mkdir = require('../mkdirs')
 const remove = require('../remove')
 
-function emptyDir (dir, callback) {
+const emptyDir = u(function emptyDir (dir, callback) {
   callback = callback || function () {}
   fs.readdir(dir, (err, items) => {
     if (err) return mkdir.mkdirs(dir, callback)
@@ -23,7 +24,7 @@ function emptyDir (dir, callback) {
       })
     }
   })
-}
+})
 
 function emptyDirSync (dir) {
   let items
diff --git a/lib/ensure/file.js b/lib/ensure/file.js
index 031d1303..c562bc86 100644
--- a/lib/ensure/file.js
+++ b/lib/ensure/file.js
@@ -1,5 +1,6 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const path = require('path')
 const fs = require('graceful-fs')
 const mkdir = require('../mkdirs')
@@ -37,9 +38,6 @@ function createFileSync (file) {
 }
 
 module.exports = {
-  createFile,
-  createFileSync,
-  // alias
-  ensureFile: createFile,
-  ensureFileSync: createFileSync
+  createFile: u(createFile),
+  createFileSync
 }
diff --git a/lib/ensure/link.js b/lib/ensure/link.js
index 8284fae3..12796383 100644
--- a/lib/ensure/link.js
+++ b/lib/ensure/link.js
@@ -1,5 +1,6 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const path = require('path')
 const fs = require('graceful-fs')
 const mkdir = require('../mkdirs')
@@ -52,9 +53,6 @@ function createLinkSync (srcpath, dstpath, callback) {
 }
 
 module.exports = {
-  createLink,
-  createLinkSync,
-  // alias
-  ensureLink: createLink,
-  ensureLinkSync: createLinkSync
+  createLink: u(createLink),
+  createLinkSync
 }
diff --git a/lib/ensure/symlink.js b/lib/ensure/symlink.js
index 2ea9e062..d879f514 100644
--- a/lib/ensure/symlink.js
+++ b/lib/ensure/symlink.js
@@ -1,5 +1,6 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const path = require('path')
 const fs = require('graceful-fs')
 const _mkdirs = require('../mkdirs')
@@ -56,9 +57,6 @@ function createSymlinkSync (srcpath, dstpath, type, callback) {
 }
 
 module.exports = {
-  createSymlink,
-  createSymlinkSync,
-  // alias
-  ensureSymlink: createSymlink,
-  ensureSymlinkSync: createSymlinkSync
+  createSymlink: u(createSymlink),
+  createSymlinkSync
 }
diff --git a/lib/fs/index.js b/lib/fs/index.js
index 85d96a82..e20ae762 100644
--- a/lib/fs/index.js
+++ b/lib/fs/index.js
@@ -4,36 +4,37 @@ const u = require('universalify').fromCallback
 const fs = require('graceful-fs')
 
 const api = [
-  'rename',
-  'ftruncate',
-  'chown',
-  'fchown',
-  'lchown',
+  'access',
+  'appendFile',
   'chmod',
+  'chown',
+  'close',
   'fchmod',
-  'stat',
-  'lstat',
+  'fchown',
+  'fdatasync',
   'fstat',
+  'fsync',
+  'ftruncate',
+  'futimes',
+  'lchown',
   'link',
-  'symlink',
+  'lstat',
+  'mkdir',
+  'open',
+  'read',
+  'readFile',
+  'readdir',
   'readlink',
   'realpath',
-  'unlink',
+  'rename',
   'rmdir',
-  'mkdir',
-  'readdir',
-  'close',
-  'open',
+  'stat',
+  'symlink',
+  'truncate',
+  'unlink',
   'utimes',
-  'futimes',
-  'fsync',
-  'fdatasync',
   'write',
-  'read',
-  'readFile',
-  'writeFile',
-  'appendFile',
-  'truncate'
+  'writeFile'
 ]
 // fs.mkdtemp() was added in Node.js v5.10.0, so check if it exists
 typeof fs.mkdtemp === 'function' && api.push('mkdtemp')
@@ -52,13 +53,9 @@ api.forEach(method => {
 // since we are a drop-in replacement for the native module
 exports.exists = function (filename, callback) {
   if (typeof callback === 'function') {
-    return fs.exists(filename, function (exists) {
-      callback(exists)
-    })
+    return fs.exists(filename, callback)
   }
-  return new Promise(function (resolve) {
-    return fs.exists(filename, function (exists) {
-      resolve(exists)
-    })
+  return new Promise(resolve => {
+    return fs.exists(filename, resolve)
   })
 }
diff --git a/lib/json/__tests__/output-json.test.js b/lib/json/__tests__/output-json.test.js
index 03b4714a..192084fe 100644
--- a/lib/json/__tests__/output-json.test.js
+++ b/lib/json/__tests__/output-json.test.js
@@ -34,6 +34,14 @@ describe('json', () => {
       })
     })
 
+    it('should support Promises', () => {
+      const file = path.join(TEST_DIR, 'this-dir', 'prob-does-not', 'exist', 'file.json')
+      assert(!fs.existsSync(file))
+
+      const data = {name: 'JP'}
+      return outputJson(file, data)
+    })
+
     describe('> when an option is passed, like JSON replacer', () => {
       it('should pass the option along to jsonfile module', done => {
         const file = path.join(TEST_DIR, 'this-dir', 'does-not', 'exist', 'really', 'file.json')
diff --git a/lib/json/index.js b/lib/json/index.js
index 42293113..717d48f4 100644
--- a/lib/json/index.js
+++ b/lib/json/index.js
@@ -1,11 +1,16 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const jsonFile = require('./jsonfile')
 
 jsonFile.outputJsonSync = require('./output-json-sync')
-jsonFile.outputJson = require('./output-json')
+jsonFile.outputJson = u(require('./output-json'))
 // aliases
-jsonFile.outputJSONSync = require('./output-json-sync')
-jsonFile.outputJSON = require('./output-json')
+jsonFile.outputJSONSync = jsonFile.outputJSONSync
+jsonFile.outputJSON = jsonFile.outputJson
+jsonFile.writeJSON = jsonFile.writeJson
+jsonFile.writeJSONSync = jsonFile.writeJsonSync
+jsonFile.readJSON = jsonFile.readJson
+jsonFile.readJSONSync = jsonFile.readJsonSync
 
 module.exports = jsonFile
diff --git a/lib/json/jsonfile.js b/lib/json/jsonfile.js
index ad235eba..59cdb3e4 100644
--- a/lib/json/jsonfile.js
+++ b/lib/json/jsonfile.js
@@ -1,15 +1,12 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const jsonFile = require('jsonfile')
 
 module.exports = {
   // jsonfile exports
-  readJson: jsonFile.readFile,
-  readJSON: jsonFile.readFile,
+  readJson: u(jsonFile.readFile),
   readJsonSync: jsonFile.readFileSync,
-  readJSONSync: jsonFile.readFileSync,
-  writeJson: jsonFile.writeFile,
-  writeJSON: jsonFile.writeFile,
-  writeJsonSync: jsonFile.writeFileSync,
-  writeJSONSync: jsonFile.writeFileSync
+  writeJson: u(jsonFile.writeFile),
+  writeJsonSync: jsonFile.writeFileSync
 }
diff --git a/lib/mkdirs/index.js b/lib/mkdirs/index.js
index 2611217c..29975c5b 100644
--- a/lib/mkdirs/index.js
+++ b/lib/mkdirs/index.js
@@ -1,9 +1,14 @@
+'use strict'
+const u = require('universalify').fromCallback
+const mkdirs = u(require('./mkdirs'))
+const mkdirsSync = require('./mkdirs-sync')
+
 module.exports = {
-  mkdirs: require('./mkdirs'),
-  mkdirsSync: require('./mkdirs-sync'),
+  mkdirs: mkdirs,
+  mkdirsSync: mkdirsSync,
   // alias
-  mkdirp: require('./mkdirs'),
-  mkdirpSync: require('./mkdirs-sync'),
-  ensureDir: require('./mkdirs'),
-  ensureDirSync: require('./mkdirs-sync')
+  mkdirp: mkdirs,
+  mkdirpSync: mkdirsSync,
+  ensureDir: mkdirs,
+  ensureDirSync: mkdirsSync
 }
diff --git a/lib/move/index.js b/lib/move/index.js
index 6bbdaf48..c44e66be 100644
--- a/lib/move/index.js
+++ b/lib/move/index.js
@@ -6,6 +6,7 @@
 
 // this needs a cleanup
 
+const u = require('universalify').fromCallback
 const fs = require('graceful-fs')
 const ncp = require('../copy/ncp')
 const path = require('path')
@@ -157,5 +158,5 @@ function moveDirAcrossDevice (source, dest, overwrite, callback) {
 }
 
 module.exports = {
-  move
+  move: u(move)
 }
diff --git a/lib/output/__tests__/output.test.js b/lib/output/__tests__/output.test.js
index 59ff05fe..103737c5 100644
--- a/lib/output/__tests__/output.test.js
+++ b/lib/output/__tests__/output.test.js
@@ -30,6 +30,11 @@ describe('output', () => {
           done()
         })
       })
+      it('should support promises', () => {
+        const file = path.join(TEST_DIR, Math.random() + 't-ne', Math.random() + '.txt')
+        assert(!fs.existsSync(file))
+        return fse.outputFile(file, 'hi jp')
+      })
     })
 
     describe('> when the file does exist', () => {
diff --git a/lib/output/index.js b/lib/output/index.js
index f4eb9bb6..14187478 100644
--- a/lib/output/index.js
+++ b/lib/output/index.js
@@ -1,5 +1,6 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const fs = require('graceful-fs')
 const path = require('path')
 const mkdir = require('../mkdirs')
@@ -32,6 +33,6 @@ function outputFileSync (file, data, encoding) {
 }
 
 module.exports = {
-  outputFile,
+  outputFile: u(outputFile),
   outputFileSync
 }
diff --git a/lib/remove/index.js b/lib/remove/index.js
index 0e3b5dd1..cee53400 100644
--- a/lib/remove/index.js
+++ b/lib/remove/index.js
@@ -1,17 +1,9 @@
 'use strict'
 
+const u = require('universalify').fromCallback
 const rimraf = require('./rimraf')
 
-function removeSync (dir) {
-  return rimraf.sync(dir, {disableGlob: true})
-}
-
-function remove (dir, callback) {
-  const options = {disableGlob: true}
-  return callback ? rimraf(dir, options, callback) : rimraf(dir, options, function () {})
-}
-
 module.exports = {
-  remove,
-  removeSync
+  remove: u(rimraf),
+  removeSync: rimraf.sync
 }

From 51d83a39fd4e95bbf7fa85b3e270b535a1848939 Mon Sep 17 00:00:00 2001
From: RyanZim <opensrc@ryanzim.com>
Date: Mon, 10 Apr 2017 13:06:20 -0400
Subject: [PATCH 3/4] Update README.md with promise support info

---
 README.md | 41 ++++++++++++++++-------------------------
 1 file changed, 16 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index cee43993..6a114e48 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 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`.
+`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`.
 
 [![npm Package](https://img.shields.io/npm/v/fs-extra.svg?style=flat-square)](https://www.npmjs.org/package/fs-extra)
 [![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
 Usage
 -----
 
-`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are unmodified and attached to `fs-extra`.
+`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.
 
 You don't ever need to include the original `fs` module again:
 
@@ -60,7 +60,7 @@ const fse = require('fs-extra')
 
 Sync vs Async
 -------------
-Most methods are async by default (they take a callback with an `Error` as first argument).
+Most methods are async by default. All async methods will return a promise if the callback isn't passed.
 
 Sync methods on the other hand will throw if an error occurs.
 
@@ -69,14 +69,23 @@ Example:
 ```js
 const fs = require('fs-extra')
 
+// Async with promises:
+fs.copy('/tmp/myfile', '/tmp/mynewfile')
+  .then(() => console.log('success!'))
+  .catch(err => {
+    // Handle error
+  })
+
+// Async with callbacks:
 fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
   if (err) return console.error(err)
-  console.log("success!")
-});
+  console.log('success!')
+})
 
+// Sync:
 try {
   fs.copySync('/tmp/myfile', '/tmp/mynewfile')
-  console.log("success!")
+  console.log('success!')
 } catch (err) {
   console.error(err)
 }
@@ -119,7 +128,7 @@ Methods
 - [writeJsonSync](docs/writeJson-sync.md)
 
 
-**NOTE:** You can still use the native Node.js methods. They are copied over to `fs-extra`.
+**NOTE:** You can still use the native Node.js methods. They are promisified and copied over to `fs-extra`.
 
 ### What happened to `walk()` and `walkSync()`?
 
@@ -129,24 +138,6 @@ They were removed from `fs-extra` in v2.0.0. If you need the functionality, `wal
 Third Party
 -----------
 
-### Promises
-
-Use [Bluebird](https://github.com/petkaantonov/bluebird). See https://github.com/petkaantonov/bluebird/blob/master/API.md#promisification. `fs-extra` is
-explicitly listed as supported.
-
-```js
-const Promise = require('bluebird')
-const fs = Promise.promisifyAll(require('fs-extra'))
-```
-
-Or you can use a dedicated package:
-
-- [`fs-extra-promise`](https://github.com/overlookmotel/fs-extra-promise) uses Bluebird.
-- [`fs-promise`](https://github.com/kevinbeaty/fs-promise) uses
-  [Any Promise](https://github.com/kevinbeaty/any-promise) and also covers
-  [`mz/fs`](https://github.com/normalize/mz/blob/master/fs.js).
-- [`fs-p`](https://github.com/grammarly/fs-p) - TypeScript-friendly promises implementation
-
 
 ### TypeScript
 

From e09efe1d313c125c70a159fac230c8fcd39a99aa Mon Sep 17 00:00:00 2001
From: RyanZim <opensrc@ryanzim.com>
Date: Thu, 13 Apr 2017 20:17:02 -0400
Subject: [PATCH 4/4] Update docs for promise support

---
 docs/copy.md          | 11 ++++++++++-
 docs/emptyDir.md      |  9 +++++++++
 docs/ensureDir.md     | 11 ++++++++++-
 docs/ensureFile.md    | 11 ++++++++++-
 docs/ensureLink.md    | 11 ++++++++++-
 docs/ensureSymlink.md | 11 ++++++++++-
 docs/move.md          | 10 +++++++++-
 docs/outputFile.md    | 12 +++++++++++-
 docs/outputJson.md    | 12 +++++++++++-
 docs/readJson.md      | 22 ++++++++++++++++++++--
 docs/remove.md        | 11 ++++++++++-
 docs/writeJson.md     | 11 ++++++++++-
 12 files changed, 130 insertions(+), 12 deletions(-)

diff --git a/docs/copy.md b/docs/copy.md
index a4f75e9d..94c71c0c 100644
--- 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
index 43292e3a..58268184 100644
--- 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
index 1f8acfb8..a342a219 100644
--- 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
index 1567e606..6e006454 100644
--- 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
index 3cf38c5f..736d73de 100644
--- 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
index b6c96954..eeb993b6 100644
--- 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
index 547af7c2..4ad8bc57 100644
--- 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
index 494cba34..22ae2b90 100644
--- 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
index 58917b8e..62787210 100644
--- 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
index acaf19c9..5913aa69 100644
--- 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
index 68f91621..5a1a566c 100644
--- 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
index 3f8f0420..b5a2e092 100644
--- 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
+})
 ```
 
 ---