docs: v2

Author: krizzu

docs/API.md

@@ -0,0 +1,55 @@
+---
+title: Installation
+---
+
+### Install
+
+With npm:
+
+```shell
+npm install @react-native-async-storage/async-storage
+```
+
+With Yarn:
+
+```shell
+yarn add @react-native-async-storage/async-storage
+```
+
+With Expo CLI:
+
+```shell
+npx expo install @react-native-async-storage/async-storage
+```
+
+### Link
+
+#### Android & iOS
+
+Requires **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.
+
+On iOS, use CocoaPods to add the native `RNAsyncStorage` to your project:
+
+```shell
+npx pod-install
+```
+
+#### Windows
+
+Requires **React Native Windows 0.63+**
+
+[CLI autolink feature](https://microsoft.github.io/react-native-windows/docs/native-modules-autolinking)
+links the module while building the app.
+
+#### macOS
+
+Requires **React Native macOS 0.63+**
+
+1. Set `platform :macos, '10.14'` in `macos/Podfile`
+2. Install the pods
+3. From now on
+   [CLI autolink feature](https://microsoft.github.io/react-native-windows/docs/native-modules-autolinking)
+   will link the module while building the app.

docs/Installation.md

@@ -0,0 +1,83 @@
+---
+id: usage
+title: Usage
+sidebar_label: Usage
+---
+
+**Async Storage** can only store `string` data. 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-async-storage/async-storage';
+```
+
+### Storing data
+
+`setItem()` is used both to add new data item (when no data for given key
+exists), and to modify existing item (when previous data for given key exists).
+
+#### Storing string value
+
+```jsx
+const storeData = async (value) => {
+  try {
+    await AsyncStorage.setItem('my-key', value);
+  } catch (e) {
+    // saving error
+  }
+};
+```
+
+#### Storing object value
+
+```jsx
+const storeData = async (value) => {
+  try {
+    const jsonValue = JSON.stringify(value);
+    await AsyncStorage.setItem('my-key', jsonValue);
+  } catch (e) {
+    // saving error
+  }
+};
+```
+
+### 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
+const getData = async () => {
+  try {
+    const value = await AsyncStorage.getItem('my-key');
+    if (value !== null) {
+      // value previously stored
+    }
+  } catch (e) {
+    // error reading value
+  }
+};
+```
+
+#### Reading object value
+
+```jsx
+const getData = async () => {
+  try {
+    const jsonValue = await AsyncStorage.getItem('my-key');
+    return jsonValue != null ? JSON.parse(jsonValue) : null;
+  } catch (e) {
+    // error reading value
+  }
+};
+```
+
+### More
+
+For more examples, [head over to API section.](API.md)

docs/Usage.md

@@ -0,0 +1,23 @@
+---
+title: Database backup exclusion
+---
+
+### Supported platforms:
+- **iOS**
+- **macOS**
+
+
+---
+
+Async Storage stores data in `Application Support` directory, which is backed up by iCloud by default.  
+This can lead to unintentional behavior where data is persisted even after an app re-installation.
+
+Async Storage disables that feature by default. 
+
+In order to enable iCloud backup, open your app's `info.plist` in Xcode and add **boolean** entry called **RCTAsyncStorageExcludeFromBackup** and set its value to **NO** (NO as no for exclusion).
+
+Alternatively, you can open `info.plist` in editor and add new entry: 
+```diff
++	<key>RCTAsyncStorageExcludeFromBackup</key>
++	<false/>
+```

docs/advanced/Backup.md

@@ -0,0 +1,224 @@
+---
+title: Brownfield integration
+---
+
+### Supported platforms:
+
+- **iOS**
+- **macOS**
+- **Android**
+
+---
+
+# iOS
+
+If you're embedding React Native into native application, you can also integrate
+Async Storage module, so that both worlds will use one storage solution.
+
+AsyncStorage can be controlled by the hosting app via the delegate on
+`RNCAsyncStorage`:
+
+```objc
+RNCAsyncStorage *asyncStorage = [bridge moduleForClass:[RNCAsyncStorage class]];
+asyncStorage.delegate = self;
+```
+
+## The protocol
+
+The delegate must conform to the `RNCAsyncStorageDelegate` protocol:
+
+### allKeys
+
+```objc
+- (void)allKeys:(RNCAsyncStorageResultCallback)block;
+```
+
+Returns all keys currently stored. If none, an empty array is returned.
+Called by `getAllKeys` in JS.
+
+### mergeValues
+
+```objc
+- (void)mergeValues:(NSArray<NSString *> *)values
+            forKeys:(NSArray<NSString *> *)keys
+         completion:(RNCAsyncStorageResultCallback)block;
+```
+
+Merges values with the corresponding values stored at specified keys.
+Called by `mergeItem` and `multiMerge` in JS.
+
+### removeAllValues
+
+```objc
+- (void)removeAllValues:(RNCAsyncStorageCompletion)block;
+```
+
+Removes all values from the store. Called by `clear` in JS.
+
+### removeValuesForKeys
+
+```objc
+- (void)removeValuesForKeys:(NSArray<NSString *> *)keys
+                 completion:(RNCAsyncStorageResultCallback)block;
+```
+
+Removes all values associated with specified keys.
+Called by `removeItem` and `multiRemove` in JS.
+
+### setValues
+
+```objc
+- (void)setValues:(NSArray<NSString *> *)values
+          forKeys:(NSArray<NSString *> *)keys
+       completion:(RNCAsyncStorageResultCallback)block;
+```
+
+Sets specified key-value pairs. Called by `setItem` and `multiSet` in JS.
+
+### valuesForKeys
+
+```objc
+- (void)valuesForKeys:(NSArray<NSString *> *)keys
+           completion:(RNCAsyncStorageResultCallback)block;
+```
+
+Returns values associated with specified keys.
+Called by `getItem` and `multiGet` in JS.
+
+### passthrough
+
+```objc
+@optional
+@property (nonatomic, readonly, getter=isPassthrough) BOOL passthrough;
+```
+
+**Optional:** Returns whether the delegate should be treated as a passthrough.
+This is useful for monitoring storage usage among other things. Returns `NO` by
+default.
+
+---
+
+# Android
+
+The recommended approach here is to use Kotlin language to leverage coroutines when accessing the storage.
+Java is also supported (through Kotlin interop), but the approach is more cumbersome.
+
+## Prerequisites
+
+1. [Next storage feature](Next.md) enabled.
+2. Add dependency on `coroutines-android` in your app's `build.gradle`
+
+```diff
+
+dependencies {
+  // other dependencies
+
+
+  // will work with coroutines 1.3.0 and up
++ implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.9"
+
+}
+```
+
+3. Your library of choice for parsing JSON storage values (since there are strings only)
+
+## Access storage
+
+### Kotlin (recommended)
+
+We use Coroutines to handle asynchronous code. Each method on storage is `suspend` method, so you need to
+call it from within a coroutine.
+
+#### Reading value
+
+```kotlin
+suspend fun readValue(ctx: Context, keys: List<String>) {
+    // get instance of the Storage by providing context object
+    val asyncStorage = StorageModule.getStorageInstance(ctx)
+
+    val entries: List<Entry> = asyncStorage.getValues(keys)
+    doSomethingWithValues(entries)
+}
+```
+
+#### Saving value
+
+```kotlin
+suspend fun saveValue(ctx: Context) {
+    val asyncStorage = StorageModule.getStorageInstance(ctx)
+
+    val entries = listOf(
+        Entry("myKey", "myValue")
+    )
+    asyncStorage.setValues(entries)
+}
+```
+
+### Java
+
+You can access AsyncStorage form Java, but you're still required to add Kotlin dependencies.
+There's no one way of accessing the data and there's more than one way to parse it.
+
+#### Reading from storage
+
+```java
+void readStorageValue(Context ctx, String key) {
+    AsyncStorageAccess asyncStorage = StorageModule.getStorageInstance(ctx);
+
+    BuildersKt.launch(GlobalScope.INSTANCE,
+                Dispatchers.getIO(),
+                CoroutineStart.DEFAULT,
+                (scope, continuation) -> {
+                    List<String> keys = new ArrayList<>();
+                    keys.add(key);
+
+                    Continuation<? super List<? extends Entry>> cont = new Continuation() {
+                        @NotNull
+                        @Override
+                        public CoroutineContext getContext() {
+                            return scope.getCoroutineContext();
+                        }
+
+                        @Override
+                        public void resumeWith(@NotNull Object o) {
+                            List<Entry> entries = (List<Entry>) o;
+                            doSomethingWithEntries(entries);
+                        }
+                    };
+
+                    asyncStorage.getValues(keys, cont);
+                    return Unit.INSTANCE;
+                });
+
+}
+```
+
+#### Saving to storage
+
+```java
+void saveStorageValue(Context ctx, String key, String value) {
+  AsyncStorageAccess asyncStorage = StorageModule.getStorageInstance(ctx);
+
+  BuildersKt.launch(GlobalScope.INSTANCE,
+                Dispatchers.getIO(),
+                CoroutineStart.DEFAULT,
+                (scope, continuation) -> {
+                    Continuation cont = new Continuation() {
+                        @NotNull
+                        @Override
+                        public CoroutineContext getContext() {
+                            return scope.getCoroutineContext();
+                        }
+
+                        @Override
+                        public void resumeWith(@NotNull Object o) {}
+                    };
+
+                    List<Entry> entries = new ArrayList<>();
+                    Entry entry = new Entry(key, value);
+                    entries.add(entry);
+                    asyncStorage.setValues(entries, cont);
+                    return Unit.INSTANCE;
+                });
+}
+```