docs: improvements

Author: krizzu

docs/api/brownfield.md

@@ -1,15 +1,17 @@
 !!! info
 
-    Brownfield integration is supported on **Android**, **iOS** and **macOS**.
+    Brownfield integration is supported on **Android**, **iOS**, and **macOS**.
 
-`AsyncStorage` is built on a shared storage layer (`SharedStorage`) that can also be accessed directly from native code.
-This is useful in brownfield scenarios, where your app combines React Native and native code, and you want both layers to read/write from the same storage consistently.
+`AsyncStorage` is built on a shared storage layer (`SharedStorage`) that can also be accessed directly from native
+code.  
+This is especially useful in brownfield scenarios, where your app combines React Native and native code, allowing both
+layers to read from and write to the same storage consistently.
 
 All platforms provide a thread-safe singleton registry called `StorageRegistry` to manage storage instances.
 
 ### Android
 
-On Android, `StorageRegistry` is public singleton, which is used to share `SharedStorage` instances with Native module.
+On Android, `StorageRegistry` is a public singleton, which is used to share `SharedStorage` instances with the native module.
 Multiple calls with the same name return the same singleton instance, ensuring consistent access.
 
 ```kotlin
@@ -30,7 +32,7 @@ runBlocking {
 
 ### iOS / macOS
 
-On iOS/macOS, the `StorageRegistry` singleton provides the same functionality in Swift/Objc.
+On iOS and macOS, the `StorageRegistry` singleton provides the same functionality in Swift and Objective-C.
 
 ```swift
 import SharedAsyncStorage

docs/api/db-naming.md

@@ -1,13 +1,14 @@
 ## How `databaseName` is used
 
-When creating a new storage instance with `createAsyncStorage(databaseName)`, the provided `databaseName` determines where and how the underlying database file is stored on each platform.
-This ensures that storages are scoped by name and do not leak data between one another.
+When creating a new storage instance with `createAsyncStorage(databaseName)`, the provided `databaseName` determines the
+location and structure of the underlying database file on each platform.  
+This ensures that each storage instance is scoped by name and prevents data from leaking between instances.
 
 ### iOS & macOS
 
-On Apple platforms, the storage is located under the app’s `Application Support` directory.
-The `databaseName` is normalized into a file path with the `.sqlite` extension.
-Each `databaseName` creates its own subdirectory inside `async-storage/databases`.
+On Apple platforms, storage is located in the app’s `Application Support` directory.  
+The `databaseName` is normalized into a file path with the `.sqlite` extension, and each `databaseName` creates its own
+subdirectory inside `async-storage/databases`.
 
 Directory:
 
@@ -33,9 +34,9 @@ createAsyncStorage(`user-${userId}`);
 
 ### Android
 
-On Android, databases are stored inside the app’s internal files directory.
-The `databaseName` is normalized into a file path with the `.sqlite` extension.
-Each `databaseName` creates its own subdirectory inside `async-storage/databases`.
+On Android, databases are stored in the app’s internal files directory.  
+The `databaseName` is normalized into a file path with the `.sqlite` extension, and each `databaseName` creates its own
+subdirectory inside `async-storage/databases`.
 
 Directory:
 
@@ -61,8 +62,8 @@ createAsyncStorage(`user-${userId}`);
 
 ### Web
 
-On Web, `databaseName` corresponds directly to the name of the IndexedDB database.
-The `async-storage` grouping is abstracted away, but the uniqueness of the name is still guaranteed.
+On the Web, `databaseName` corresponds directly to the name of the IndexedDB database.  
+Although the `async-storage` grouping is abstracted away, the name remains unique across instances.
 
 Example:
 
@@ -77,5 +78,5 @@ Creates database named `user-1234`:
 
 ### Windows
 
-On Windows, scoped storages are not supported.
-The API always falls back to the legacy v2 storage implementation, which ignores `databaseName`.
+On the Web, `databaseName` corresponds directly to the name of the IndexedDB database.  
+Although the `async-storage` grouping is abstracted away, the name remains unique across instances.

docs/api/errors.md

@@ -1,30 +1,31 @@
 # Error handling
 
-All `AsyncStorage` methods throw a specialized error type, `AsyncStorageError`.
-This class extends the standard `Error` class, by adding a `type` property to help identify the issue.
+All `AsyncStorage` methods throw a specialized error type called `AsyncStorageError`.  
+This class extends the standard `Error` class and adds a `type` property to make it easier to identify the specific
+issue.
 
 ## Error types
 
-The error type is an enum `AsyncStorageError.Type` with the following possible values:
+Errors are categorized using the `AsyncStorageError.Type` enum, which includes the following values:
 
 ### NativeModuleError
 
-Raised when the RN native module itself fails — for example,
-the module is null at app startup, or not initialized correctly.
+Occurs when the React Native native module fails - for example, if the module is null at app startup or not initialized
+correctly.
 
 ### WebStorageError
 
-Web only, when an IndexedDB operation fails.
-[See IndexedDB error codes](https://developer.mozilla.org/en-US/docs/Web/API/IDBRequest/error.
+Occurs on the Web when an IndexedDB operation fails.
+[See IndexedDB error codes](https://developer.mozilla.org/en-US/docs/Web/API/IDBRequest/errori)
 
 ### SqliteStorageError
 
-Raised when SQLite itself fails on iOS, macOS, or Android.
-[See SQLite error codes](https://www.sqlite.org/rescode.html).
+Occurs when SQLite itself fails on iOS, macOS, or Android.
+[See SQLite error codes](https://www.sqlite.org/rescode.html)
 
 ### OtherStorageError
 
-Raised for other storage-related failures that don’t fit into the categories above.
+Used for storage-related failures that don’t fall into the other categories.  
 Examples include:
 
 - Storage not initialized correctly
@@ -35,7 +36,7 @@ Examples include:
 
 ### UnknownError
 
-A catch-all for cases where the system cannot classify the error.
+A catch-all for errors that cannot be classified into any of the defined categories.
 
 ## Example of error handling
 

docs/api/usage.md

@@ -4,48 +4,51 @@ 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.
+The [
+`AsyncStorage`](https://github.com/react-native-async-storage/async-storage/blob/main/packages/async-storage/src/AsyncStorage.ts)
+interface provides a promise-based API for persistent key-value storage.
+It mirrors the Web Storage API, with additional support 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`).
+**Note:** AsyncStorage only stores strings. To save objects, arrays, or other non-string values, serialize them with
+`JSON.stringify` before storing, and use `JSON.parse` when reading them back.
 
 ## Creating a storage
 
-To create a new storage, call `createAsyncStorage` with your database name:
+Create a new storage instance by calling `createAsyncStorage` with a unique database name:
 
-!!! note "About naming"
+!!! note "Naming"
 
-    It's best to avoid adding an extensions to the name. Read more at [Database naming](db-naming.md) section.
+    Avoid including file extensions in the database name (like "user.db"). See [Database naming](db-naming.md) for details.
 
 ```typescript
 import { createAsyncStorage } from "@react-native-async-storage/async-storage";
 
 const userStorage = createAsyncStorage("john");
 ```
 
-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.
+Each instance is uniquely identified by its name.
+Data in one storage instance is isolated, ensuring that different names do not share data.
 
-!!! note "Web platform"
+!!! note "Web"
 
-    On Web, AsyncStorage is backed by [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API), which also support scoped storages.
+    On the Web, AsyncStorage uses [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API), which supports scoped storages.
 
-!!! warning "Windows platform"
+!!! warning "Windows"
 
-    As of AsyncStorage v3.0, Windows platform does not support scoped storages. It falls back to previous implementation - single storage per application.
+    Windows does not support scoped storages. It falls back to the previous v2 implementation, which provides a single storage per application.
 
 ## Using a storage
 
-Once you have created a storage instance, you can start managing data.
+After creating a storage instance, the storage is ready to use.
 
 ### 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
+- `setItem` overwrites the current value if the key already exists.
+- `removeItem` does nothing if the key does not exist; it does not throw an error.
 
 ```typescript
 await userStorage.setItem("username", "doe_john");
@@ -66,7 +69,12 @@ 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.
+Use batch methods to handle multiple keys at once. These operations are performed atomically: either all changes are
+applied, or none if an error occurs.
+
+- `setMany` stores multiple key-value pairs.
+- `getMany` retrieves multiple keys at once, returning `null` for any keys that don’t exist.
+- `removeMany` deletes multiple keys; non-existing keys are ignored without errors.
 
 ```typescript
 // store values
@@ -89,9 +97,9 @@ console.log(data);
 await userStorage.removeMany(["email", "age", "not-here"]);
 ```
 
-### Reading stored keys
+### Read all keys
 
-To retrieve all keys currently stored in a storage instance, use `getAllKeys`:
+To retrieve all keys currently used in the storage instance, use `getAllKeys`:
 
 ```typescript
 await userStorage.setMany({

docs/index.md

@@ -4,28 +4,28 @@ title: Overview
 
 # Async Storage
 
-Async Storage is asynchronous, unencrypted, persistent, key-value storage for your React Native application.  
-It provides a simple API compatible with the [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API), with a few extensions for batch operations and multi-database support.
+Async Storage is an asynchronous, unencrypted, persistent key-value storage solution for your React Native application.
+It provides a simple API compatible with the [Web Storage API]((https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)), with additional extensions for batch operations and multi-database support.
 
 ---
 
-## Supported platforms
+## Supported Platforms
 
 - **Android** (SQLite backend via Room KMP)
 - **iOS** (SQLite backend via Room KMP)
 - **Web** (IndexedDB backend)
 - **macOS** (SQLite backend via Room KMP)
-- **Windows** (legacy fallback, single database only)
+- **Windows** (legacy fallback, single-database only)
 
 ---
 
 ## Installation
 
 ```shell
-# using npm
+# Using npm
 npm install @react-native-async-storage/async-storage
 
-# using yarn
+# Using yarn
 yarn add @react-native-async-storage/async-storage
 ```
 
@@ -36,7 +36,7 @@ Inside your `android/build.gradle(.kts)` file, add link to local maven repo:
 ```groovy
 allprojects {
     repositories {
-        // ... others like google(), mavenCenterl()
+        // ... others like google(), mavenCentral()
 
         maven {
             // or uri("path/to/node_modules/@react-native-async-storage/async-storage/android/local_repo")

docs/migration-to-3.md

@@ -1,21 +1,20 @@
 # Migration to v3
 
-AsyncStorage v3 introduces some breaking changes to simplify the API and make it more consistent.
+AsyncStorage v3 introduces a few breaking changes to simplify the API and make it more consistent.
 
 ## Key changes:
 
 ### Installation changes
 
-Android requires local maven repo to be added in your `build.gradle(.kts)` file. Head over to [Installation step for Android](index.md#android) to learn more.
-
+Android requires a local Maven repository to be added to your `build.gradle(.kts)` file. Head over to the [Installation step for Android](index.md#android) to learn more.
 
 ### `AsyncStorage` is now instance-based
 
 In v3, AsyncStorage is no longer a singleton.  
-Each instance represents an **isolated storage area**, providing separation between data sets. Head over to [Usage page](api/usage.md#creating-a-storage) to learn more.
+Each instance represents an **isolated storage area**, providing separation between data sets. Head over to the [Usage page](api/usage.md#creating-a-storage) to learn more.
 
 ```typescript
-// create seperate storages
+// create separate storages
 const userStorage = createAsyncStorage('user');
 const cacheStorage = createAsyncStorage('cache');
 ```
@@ -25,43 +24,63 @@ const cacheStorage = createAsyncStorage('cache');
 To make upgrading smoother, the default export continues to reference the v2 implementation.
 This ensures that:
 
-- Your app continues to access previously stored data.
+- Your app can continue to access previously stored data.
 - You can migrate incrementally to v3 instances.
 
 ```typescript
-// Still works (uses v2 backend)
+// Still works (uses the v2 backend)
 import AsyncStorage from '@react-native-async-storage/async-storage';
 await AsyncStorage.setItem('foo', 'bar');
 ```
 
-### Callbacks removed — Promises only
+### Callbacks removed - Promises only
 
-All methods are now Promise-based.
+All methods are now promise-based.
 The old callback arguments have been removed to make the API simpler and more consistent.
 
 ### 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.
+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.
+
+### Removed `useAsyncStorage` hook
+
+The `useAsyncStorage` hook has been removed due to implementation issues.  
+It will be reintroduced in a future release with an improved design.
+
+If you need it, here's the old version:
+
+```typescript
+export function useAsyncStorage(key: string): AsyncStorageHook {
+  return {
+    getItem: (...args) => AsyncStorage.getItem(key, ...args),
+    setItem: (...args) => AsyncStorage.setItem(key, ...args),
+    mergeItem: (...args) => AsyncStorage.mergeItem(key, ...args),
+    removeItem: (...args) => AsyncStorage.removeItem(key, ...args),
+  };
+}
+```
 
 ### 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.
+All errors thrown by `AsyncStorage` are now instances of `AsyncStorageError`, each containing a `type` property that indicates the kind of error.
+For more details, head over to the [Errors page](api/errors.md).
 
 ### Method signature changes
 
-The core methods
+The core methods:
 
 - `getItem`
 - `setItem`
 - `removeItem`
 - `getAllKeys`
 - `clear`
 
-retain their signatures from v2, ensuring backward compatibility.
+retain their signatures as in 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.
+Renamed to `getMany`, this method returns a `Record<string, string | null>` and follows a "what you request is what you get" rule: every key provided in the request appears in the returned object, with `null` for keys that don’t exist, or have `null` value, in storage.
 
 ```diff
 -  multiGet: (
@@ -74,7 +93,7 @@ Renamed to `getMany` and returns a `Record<string, string | null>`, following a
 
 #### multiSet
 
-Renamed to `setMany`, accepts a `Record<string, string>` of key-value entries.
+Renamed to `setMany`, this method accepts a `Record<string, string>` containing key-value pairs.
 
 ```diff
 -  multiSet: (
@@ -87,7 +106,7 @@ Renamed to `setMany`, accepts a `Record<string, string>` of key-value entries.
 
 #### multiRemove
 
-Renamed to `removeMany`, accepts list of keys.
+Renamed to `removeMany`, this method accepts a list of keys to remove.
 
 ```diff
 -  multiRemove: (