From 5a8d5681c55daf1b09d852c112f44baa408341c0 Mon Sep 17 00:00:00 2001
From: RyanZim <opensrc@ryanzim.com>
Date: Mon, 26 Jun 2017 15:45:42 -0400
Subject: [PATCH] Add docs for using promises with fs.read() & fs.write()

---
 README.md             |  2 +-
 docs/fs-read-write.md | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 docs/fs-read-write.md

diff --git a/README.md b/README.md
index 61c79c86..7dbb9f7e 100644
--- a/README.md
+++ b/README.md
@@ -128,7 +128,7 @@ Methods
 - [writeJsonSync](docs/writeJson-sync.md)
 
 
-**NOTE:** You can still use the native Node.js methods. They are promisified and copied over to `fs-extra`.
+**NOTE:** You can still use the native Node.js methods. They are promisified and copied over to `fs-extra`. See [notes on `fs.read()` & `fs.write()`](docs/fs-read-write.md)
 
 ### What happened to `walk()` and `walkSync()`?
 
diff --git a/docs/fs-read-write.md b/docs/fs-read-write.md
new file mode 100644
index 00000000..ea9cf170
--- /dev/null
+++ b/docs/fs-read-write.md
@@ -0,0 +1,39 @@
+# About `fs.read()` & `fs.write()`
+
+[`fs.read()`](https://nodejs.org/api/fs.html#fs_fs_read_fd_buffer_offset_length_position_callback) & [`fs.write()`](https://nodejs.org/api/fs.html#fs_fs_write_fd_buffer_offset_length_position_callback) are different from other `fs` methods in that their callbacks are called with 3 arguments instead of the usual 2 arguments.
+
+If you're using them with callbacks, they will behave as usual. However, their promise usage is a little different. `fs-extra` promisifies these methods like [`util.promisify()`](https://nodejs.org/api/util.html#util_util_promisify_original) (only availible in Node 8+) does.
+
+Here's the example promise usage:
+
+## `fs.read()`
+
+```js
+// Basic promises
+fs.read(fd, buffer, offset, length, position)
+  .then(results => {
+    console.log(results)
+    // { bytesRead: 20, buffer: <Buffer 0f 34 5d ...> }
+  })
+
+// Async/await usage:
+async function example () {
+  const { bytesRead, buffer } = await fs.read(fd, buffer, offset, length, position)
+}
+```
+
+## `fs.write()`
+
+```js
+// Basic promises
+fs.write(fd, buffer, offset, length, position)
+  .then(results => {
+    console.log(results)
+    // { bytesWritten: 20, buffer: <Buffer 0f 34 5d ...> }
+  })
+
+// Async/await usage:
+async function example () {
+  const { bytesWritten, buffer } = await fs.write(fd, buffer, offset, length, position)
+}
+```