docs: API clarification (#354)

Author: mdjastrzebski

README.md

@@ -20,22 +20,19 @@ $ yarn add @react-native-community/async-storage
 
 - **React Native 0.60+**
 
-
 [CLI autolink feature](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md) links the module while building the app. 
 
-
-- **React Native <= 0.59**
-
+Run `pod install` in iOS project in order to add RNAsyncStorage cocoapod:
 
 ```bash
-$ react-native link @react-native-community/async-storage
+$ cd ios && pod install
 ```
 
+- **React Native <= 0.59**
 
-*Note* For `iOS` using `cocoapods`, run:
 
 ```bash
-$ cd ios/ && pod install
+$ react-native link @react-native-community/async-storage
 ```
 
 See docs for [manual linking guide](docs/Linking.md)
@@ -54,26 +51,48 @@ $ react-native unlink @react-native-community/async-storage
 
 ## Usage
 
-### Import
+AsyncStorage can only store `string` data, so in order to store object data you need to serialize it first. 
+For data that can be serialized to JSON you can use `JSON.stringify()` when saving the data and `JSON.parse()` when loading the data.
+
+
+### Importing
 
 ```js
 import AsyncStorage from '@react-native-community/async-storage';
 ```
 
-### Store data
-```jsx
+### Storing data
+
+`setItem()` is used both to add new data item (when no data for given key exists), and to modify exiting item (when previous data for given key exists).
 
-storeData = async () => {
+#### Storing string value
+```jsx
+const storeData = async (value) => {
   try {
-    await AsyncStorage.setItem('@storage_Key', 'stored value')
+    await AsyncStorage.setItem('@storage_Key', value)
   } catch (e) {
     // saving error
   }
 }
+```
 
+#### Storing object value
+```jsx
+const storeData = async (value) => {
+  try {
+    const jsonValue = JSON.stringify(value)
+    await AsyncStorage.setItem('@storage_Key', jsonValue)
+  } catch (e) {
+    // saving error
+  }
+}
 ```
 
-### Read data
+### Reading data
+
+`getItem` returns a promise that either resolves to stored value when data is found for given key, or returns `null` otherwise.  
+
+#### Reading string value
 ```jsx
 
 getData = async () => {
@@ -88,8 +107,23 @@ getData = async () => {
 }
 
 ```
-### Advanced
-See docs for [api and more examples](docs/API.md) or [advanced usages](docs/advanced).
+#### Reading object value 
+
+```jsx
+
+getData = async () => {
+  try {
+    const jsonValue = await AsyncStorage.getItem('@storage_Key')
+    return jsonValue != null ? JSON.parse(jsonValue) : null;
+  } catch(e) {
+    // error reading value
+  }
+}
+
+```
+
+## Advanced usage
+See docs for [API and more examples](docs/API.md) or [advanced usages](docs/advanced).
 
 ## Writing tests
 

docs/API.md

@@ -22,7 +22,11 @@
 
 ## `getItem`
 
-Fetches a data for a given `key`, invokes (optional) callback once completed.
+Gets a string value for given `key`. This function can either return a string value for existing `key` or return `null` otherwise.
+
+In order to store object value, you need to deserialize it, e.g. using `JSON.parse()`.
+
+*Note (legacy)*: you can use optional callback as an alternative for returned promise.
 
 **Signature**:
 
@@ -32,15 +36,32 @@ static getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => voi
 
 **Returns**:
 
-`Promise` with data, if exists, `null` otherwise.
+`Promise` resolving with a string value, if entry exists for given `key`, or `null` otherwise.
+
+`Promise` can be also rejects in case of underlying storage error.
 
 **Example**:
 
 ```js
 
-getMyValue = async () => {
+getMyStringValue = async () => {
+  try {
+    return await AsyncStorage.getItem('@key')
+  } catch(e) {
+    // read error
+  }
+
+  console.log('Done.')
+
+}
+```
+
+```js
+
+getMyObject = async () => {
   try {
-    const value = await AsyncStorage.getItem('@MyApp_key')
+    const jsonValue = await AsyncStorage.getItem('@key')
+    return jsonValue != null ? JSON.parse(jsonValue) : null
   } catch(e) {
     // read error
   }
@@ -58,7 +79,11 @@ getMyValue = async () => {
 
 ## `setItem`
 
-Stores a `value` for the `key`, invokes (optional) `callback` once completed.
+Sets a string `value` for given `key`. This operation can either modify an existing entry, if it did exist for given `key`, or add new one otherwise. 
+
+In order to store object value, you need to serialize it, e.g. using `JSON.stringify()`.
+
+*Note (legacy)*: you can use optional callback as an alternative for returned promise.
 
 **Signature**:
 
@@ -68,15 +93,31 @@ static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void)
 
 **Returns**:
 
-`Promise` object.
+`Promise` resolving when the set operation is completed.
+
+`Promise` can be also rejects in case of underlying storage error.
 
 **Example**:
 
 ```js
 
-setValue = async () => {
+setStringValue = async (value) => {
+  try {
+    await AsyncStorage.setItem('key', value)
+  } catch(e) {
+    // save error
+  }
+
+  console.log('Done.')
+}
+```
+
+```js
+
+setObjectValue = async (value) => {
   try {
-    await AsyncStorage.setItem('@MyApp_key', 'my secret value')
+    const jsonValue = JSON.stringify(value)
+    await AsyncStorage.setItem('key', jsonValue)
   } catch(e) {
     // save error
   }