update v0.5.0 README

README.md

@@ -1,14 +1,16 @@
 # react-native-fetch-blob [![npm version](https://badge.fury.io/js/react-native-fetch-blob.svg)](https://badge.fury.io/js/react-native-fetch-blob) ![](https://img.shields.io/badge/PR-Welcome-brightgreen.svg)
 
-A react-native module for fetch file/image with custom headers, supports blob response data, and upload/download progress.
+## v0.5.0 Work In Progress README.md
 
-If you're dealing with image or file server that requires an `Authorization` token in the header, or you're having problem with `fetch` API when receiving blob data, you might try this module (this is also the reason why I made this).
+A react-native module for upload, and download file with custom headers. Supports blob response data, upload/download progress, and file reader API that enables you process file content in js context (such as display image data, string or image process).
 
-See [[fetch] Does fetch with blob() marshal data across the bridge?](https://github.com/facebook/react-native/issues/854).
+If you're dealing with image or file server that requires special field in the header, or you're having problem with `fetch` API when receiving blob data, you might try this module.
 
-This module enables you upload/download binary data in js, see [Examples](#user-content-usage) bellow.
+See [[fetch] Does fetch with blob() marshal data across the bridge?](https://github.com/facebook/react-native/issues/854) for the reason why we made this module.
 
-The source code is very simple, just an implementation of native HTTP request, supports both Android (uses awesome native library  [AsyncHttpClient](https://github.com/AsyncHttpClient/async-http-client])) and IOS.
+In latest version (v0.5.0), you can upload/download files directly with file path. We've also introduced `file stream` API for reading **large files** from storage, see [Examples](#user-content-usage) bellow.
+
+This module implements native HTTP request, supports both Android (uses awesome native library  [AsyncHttpClient](https://github.com/AsyncHttpClient/async-http-client])) and IOS.
 
 ## Usage
 
@@ -18,6 +20,8 @@ The source code is very simple, just an implementation of native HTTP request, s
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
  * [Upload/Download progress](#user-content-uploaaddownload-progress)
+ * [Deal with files in storage](#user-content-deal-with-files-in-storage)
+ * [Release cache files](#user-content-release-cache-files)
 * [API](#user-content-api)
 
 ## Installation
@@ -63,6 +67,66 @@ RNFetchBlob.fetch('GET', 'http://www.example.com/images/img1.png', {
   })
 ```
 
+#### Download to storage directly
+
+If you want to save the response data directly into file storage rather than convert response data into base64 for some reason.
+
+Put a `config` before calling `fetch`. There're three options which are `path`, `fileCache`, and `appendExt` that let you decide how and where to save the file.
+
+The simplest way is give a `fileCach` option to config, and set it to `true`. This will let the incoming response data stored in a temporary path **wihout** any file extension.
+
+```js
+RNFetchBlob
+  .config({
+    fileCache : true,
+  })
+  .fetch('GET', 'http://www.example.com/file/example.zip', {
+    some headers ..
+  })
+  .then((res) => {
+    // the temp file path
+    console.log('The file saved to ', res.path())
+  })
+```
+
+But in some cases, you might need a file extension even the file is temporary cached. For instance, when use the file path as source of `Image` element the path should end with something like .png or .jpg, you can do this by put one more option in to `config`.
+
+```js
+RNFetchBlob
+  .config({
+    fileCache : true,
+    appendExt : 'png'
+  })
+  .fetch('GET', 'http://www.example.com/file/example.zip', {
+    some headers ..
+  })
+  .then((res) => {
+    // the temp file path with file extension `png`
+    console.log('The file saved to ', res.path())
+    // Beware that when using a file path as Image source on Android,
+    // you must prepend "file://"" before the file path
+    imageView = <Image source={{ uri : Platform.OS === 'android' ? 'file://' : '' + res.path() }}/>
+  })
+```
+
+What's more, if you prefer a specific path, rather a random generated path, you can use `path` option. We've added a [getSystemDirs](#user-content-getsysdirs) API in v0.5.0 that lists several common used directories.
+
+```js
+RNFetchBlob.getSystemDirs().then((dirs) => {
+  RNFetchBlob
+    .config({
+      path : dirs.DocumentDir + 'path-to-file.anything'
+    })
+    .fetch('GET', 'http://www.example.com/file/example.zip', {
+      some headers ..
+    })
+    .then((res) => {
+      // the path should be dirs.DocumentDir + 'path-to-file.anything'
+      console.log('The file saved to ', res.path())
+    })
+})
+```
+
 ####  Upload example : Dropbox [files-upload](https://www.dropbox.com/developers/documentation/http/documentation#files-upload) API
 
 `react-native-fetch-blob` will convert the base64 string in `body` to binary format using native API, this process will be  done in a new thread, so it's async.
@@ -87,6 +151,29 @@ RNFetchBlob.fetch('POST', 'https://content.dropboxapi.com/2/files/upload', {
   })
 ```
 
+#### Upload a file from storage
+
+If you're going to use a `file` in file system as request body, just push the path with prefix `RNFetchBlob-file://`.
+
+```js
+RNFetchBlob.fetch('POST', 'https://content.dropboxapi.com/2/files/upload', {
+    Authorization : "Bearer access-token...",
+    'Dropbox-API-Arg': JSON.stringify({
+      path : '/img-from-react-native.png',
+      mode : 'add',
+      autorename : true,
+      mute : false
+    }),
+    'Content-Type' : 'application/octet-stream',
+  }, 'RNFetchBlob-file://' + PATH_TO_THE_FILE)
+  .then((res) => {
+    console.log(res.text())
+  })
+  .catch((err) => {
+    // error handling ..
+  })
+```
+
 #### Multipart/form-data example : Post form data with file and data
 
 In `version >= 0.3.0` you can also post files with form data,  just put an array in `body`, with object elements with property `name`, `data`, and `filename`(optional).
@@ -115,6 +202,30 @@ Elements have property `filename` will be transformed into binary format, otherw
   })
 ```
 
+What if some fields contains a file in file storage ? Just like [upload a file from storage](#user-content-upload-a-file-from-storage) example, change the `data` to path of the file with a prefix `RNFetchBlob-file://`
+
+```js
+
+  RNFetchBlob.fetch('POST', 'http://www.example.com/upload-form', {
+    Authorization : "Bearer access-token",
+    otherHeader : "foo",
+    'Content-Type' : 'multipart/form-data',
+  }, [
+    // append field data from file path
+    { name : 'avatar', filename : 'avatar.png', data: 'RNFetchBlob-file://' + PATH_TO_THE_FILE},
+    // elements without property `filename` will be sent as plain text
+    { name : 'name', data : 'user'},
+    { name : 'info', data : JSON.stringify({
+      mail : 'example@example.com',
+      tel : '12345678'
+    })},
+  ]).then((resp) => {
+    // ...
+  }).catch((err) => {
+    // ...
+  })
+```
+
 #### Upload/Download progress
 
 In `version >= 0.4.2` it is possible to know the upload/download progress.
@@ -184,10 +295,11 @@ When `fetch` success, it resolve a `FetchBlobResponse` object as first argument.
 
 | Version | |
 |---|---|
-| 0.3 | Upload/Download octet-stream and form-data |
-| 0.4 | Add base-64 encode/decode library and API |
+| ~0.3.0 | Upload/Download octet-stream and form-data |
+| 0.4.0 | Add base-64 encode/decode library and API |
 | 0.4.1 | Fixe upload form-data missing file extension problem on Android |
 | 0.4.2 | Supports upload/download progress |
+| 0.5.0 | Upload/download with direct access to file storage, and also supports read file with file stream |
 
 ### Upcoming Features
 
@@ -199,5 +311,5 @@ We are now working on v0.5.0, there will be some new features.
 
 ### Development
 
-If you're insterested in hacking this module, check our [development guide](https://github.com/wkh237/react-native-fetch-blob/wiki/Development-Guide), there might be something helpful. 
+If you're insterested in hacking this module, check our [development guide](https://github.com/wkh237/react-native-fetch-blob/wiki/Development-Guide), there might be something helpful.
 Please feel free to make a PR or file an issue.