docs: migration, usage

Author: krizzu

docs/api/errors.md

@@ -0,0 +1,4 @@
+# Error handling
+
+
+todo

docs/api/usage.md

@@ -0,0 +1,116 @@
+---
+title: Usage
+---
+
+# Using Async Storage
+
+The [`AsyncStorage`](https://github.com/react-native-async-storage/async-storage/blob/main/packages/async-storage/src/AsyncStorage.ts) interface provides an asynchronous, promise-based API for persistent key-value storage.
+Each method is modeled after the Web Storage API, with extensions for batch operations.
+
+Similar to Web, AsyncStorage deals with data that should be already serialized (strings). If you need to store objects, arrays, or other non-string values, you must serialize them first (for example, using `JSON.stringify`) and deserialize them when retrieving (for example, using `JSON.parse`).
+
+## Creating a storage
+
+To create a new storage, call `createAsyncStorage` with your database name:
+
+```typescript
+import { createAsyncStorage } from "@react-native-async-storage/async-storage";
+
+// any name is fine, you can even add an extension!
+const userStorage = createAsyncStorage("john.db");
+```
+
+This returns an instance of `AsyncStorage` and each instance is uniquely identified by the name you provide.
+The data in one storage instance is scoped to its name: using different names ensures that data does not leak between storages.
+
+!!! note "Web platform"
+
+    On Web, AsyncStorage is backed by [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API), which also support scoped storages.
+
+!!! warning "Windows platform"
+
+    As of AsyncStorage v3.0, Windows platform does not support scoped storages. It fallsback to previous implementation - single storage per application.
+
+## Using a storage
+
+Once you have created a storage instance, you can start managing data.
+
+### Single item operations
+
+You can store, retrieve, and remove individual keys using `setItem`, `getItem`, and `removeItem`.
+
+Note that:
+
+- Calling `setItem` with an existing key will overwrite the current value
+- Calling `removeItem` on a key that does not exist has no effect and does not throw an error
+
+```typescript
+await userStorage.setItem("username", "doe_john");
+// previously stored value is overriden
+await userStorage.setItem("username", "john_doe");
+
+// read current value
+let username = await userStorage.getItem("username");
+console.log(username); // "john_doe"
+
+await userStorage.removeItem("username");
+// does nothing, item is already removed
+await userStorage.removeItem("username");
+
+username = await userStorage.getItem("username");
+console.log(username); // null
+```
+
+### Batch operations
+
+Use convenient batch methods to handle multiple keys at once. Behind the scene, transaction performed to store all of them, or none in case of an error.
+
+```typescript
+// store values
+await userStorage.setMany({
+  email: "[email protected]",
+  age: "30",
+});
+
+// read multiple items
+const data = await userStorage.getMany(["email", "age", "username"]);
+console.log(data);
+// {
+//   email: "[email protected]",
+//   age: "30",
+//   username: null, // key doesn't exist
+// }
+
+// remove multiple items
+// non-existing keys are ignored
+await userStorage.removeMany(["email", "age", "not-here"]);
+```
+
+### Reading stored keys
+
+To retrieve all keys currently stored in a storage instance, use `getAllKeys`:
+
+```typescript
+await userStorage.setMany({
+  email: "[email protected]",
+  age: "30",
+});
+
+const keys = await userStorage.getAllKeys();
+console.log(keys); // ["email", "age"]
+```
+
+### Clearing storage
+
+To remove all data from a storage instance, use `clear`:
+
+```typescript
+await userStorage.setMany({
+  email: "[email protected]",
+  age: "30",
+});
+
+await userStorage.clear();
+const keys = await userStorage.getAllKeys();
+console.log(keys); // []
+```

docs/index.md

@@ -1,3 +1,7 @@
+---
+title: Overview
+---
+
 # Async Storage
 
 Async Storage is asynchronous, unencrypted, persistent, key-value storage for your React Native application.  
@@ -34,12 +38,10 @@ pod install
 
 ## Usage
 
-### Basic
-
 ```typescript
 import { createAsyncStorage } from "@react-native-async-storage/async-storage";
 
-// Create a storage instance
+// create a storage instance
 const storage = createAsyncStorage("appDB");
 
 async function demo() {
@@ -48,30 +50,11 @@ async function demo() {
 
   // read value stored at "userToken" key
   const token = await storage.getItem("userToken");
-  console.log("Stored token:", token);
+  console.log("Stored token:", token); // abc123
 
   // remove value from storage
   await storage.removeItem("userToken");
 }
 ```
 
-### Multi-item operations
-
-Async Storage supports batch operations for efficiency:
-
-```typescript
-async function demo() {
-  // save multiple values at once
-  await storage.setMany({
-    theme: "dark",
-    language: "en",
-  });
-
-  // Retrieve multiple values
-  const values = await storage.getMany(["theme", "language", "different"]);
-  console.log(values); // { theme: "dark", language: "en", different: null }
-
-  // Remove multiple values
-  await storage.removeMany(["theme", "language"]);
-}
-```
+Head over to [Usage page](api/usage.md) to learn more.

docs/migration-to-3.md

@@ -0,0 +1,74 @@
+# Migration to v3
+
+AsyncStorage v3 introduces some breaking changes to simplify the API and make it more consistent.
+
+## AsyncStorage instance needs to be created now
+
+AsyncStorage v3 introduced scoped storages, which needs to be created before use. Head to [Usage page](api/usage.md#creating-a-storage) to learn more.
+
+## Default export points to v2 storage
+
+To make transition easier, the default export still points to the v2 storage implementation, ensuring that no existing data is lost.
+
+## Removed callback arguments
+
+All methods now return Promises, and callbacks have been removed from all methods.
+
+## Removed merge functionality
+
+AsyncStorage's "merge" behavior has historically been inconsistent across platforms. Rather than enforcing a platform-specific merging strategy, the merge API has been removed to avoid ambiguity.
+
+## Method signature changes
+
+The core methods
+
+- `getItem`
+- `setItem`
+- `removeItem`
+- `getAllKeys`
+- `clear`
+
+retain their signatures from v2, ensuring backward compatibility.
+
+### multiGet
+
+Renamed to `getMany` and returns a `Record<string, string | null>`, following a "what you request is what you get" rule: every key you pass in the request appears in the returned object, with `null` for keys that don’t exist in storage.
+
+```diff
+-  multiGet: (
+-    keys: readonly string[],
+-    callback?: MultiGetCallback
+-  ) => Promise<readonly KeyValuePair[]>;
+
++ getMany(keys: string[]): Promise<Record<string, string | null>>;
+```
+
+### multiSet
+
+Renamed to `setMany`, accepts a `Record<string, string>` of key-value entries.
+
+```diff
+-  multiSet: (
+-    keyValuePairs: ReadonlyArray<readonly [string, string]>,
+-    callback?: MultiCallback
+-  ) => Promise<void>;
+
++ setMany(entries: Record<string, string>): Promise<void>;
+```
+
+### multiRemove
+
+Renamed to `removeMany`, accepts list of keys.
+
+```diff
+-  multiRemove: (
+-    keys: readonly string[],
+-    callback?: MultiCallback
+-  ) => Promise<void>;
+
++ removeMany(keys: string[]): Promise<void>;
+```
+
+## Errors are more predictable now
+
+All errors now thrown from `AsyncStorage` are instances of `AsyncStorageError` containing `type` of the error it represents. Head over to [Errors page](api/errors.md) to learn more.

mkdocs.yml

@@ -4,6 +4,10 @@ site_url: https://react-native-async-storage.github.io/
 
 nav:
   - Overview: index.md
+  - API:
+      - Usage: api/usage.md
+      - 'Error handling': api/errors.md
+  - 'Migration to v3': migration-to-3.md
   - Changelog: changelog.md