chore: comment

Author: krizzu

packages/async-storage/src/AsyncStorage.ts

@@ -7,6 +7,7 @@ export interface AsyncStorage {
    * @param key - The key identifying the stored value.
    * @returns A Promise resolving to the stored string value,
    *          or `null` if the key does not exist.
+   * @throws {@link AsyncStorageError}
    */
   getItem(key: string): Promise<string | null>;
 
@@ -15,13 +16,15 @@ export interface AsyncStorage {
    * @param key - The key under which the value will be stored.
    * @param value - The string value to store.
    * @returns A Promise that resolves once the value has been written.
+   * @throws {@link AsyncStorageError} if writing fails.
    */
   setItem(key: string, value: string): Promise<void>;
 
   /**
    * Removes an item from storage.
    * @param key - The key of the item to remove.
    * @returns A Promise that resolves once the key has been removed.
+   * @throws {@link AsyncStorageError} if removal fails.
    */
   removeItem(key: string): Promise<void>;
 
@@ -30,32 +33,37 @@ export interface AsyncStorage {
    * @param keys - An array of keys to retrieve.
    * @returns A Promise resolving to an object mapping each key to its stored value,
    *          or `null` for keys that do not exist.
+   * @throws {@link AsyncStorageError} if retrieval fails.
    */
   getMany(keys: string[]): Promise<Record<string, string | null>>;
 
   /**
    * Stores multiple items in storage.
    * @param entries - An object containing key-value pairs to store.
    * @returns A Promise that resolves once all items have been written.
+   * @throws {@link AsyncStorageError} if writing fails.
    */
   setMany(entries: Record<string, string>): Promise<void>;
 
   /**
    * Removes multiple items from storage.
    * @param keys - An array of keys to remove.
    * @returns A Promise that resolves once all keys have been removed.
+   * @throws {@link AsyncStorageError} if removal fails.
    */
   removeMany(keys: string[]): Promise<void>;
 
   /**
    * Retrieves all keys currently stored.
    * @returns A Promise resolving to an array of keys.
+   * @throws {@link AsyncStorageError} if retrieval fails.
    */
   getAllKeys(): Promise<string[]>;
 
   /**
    * Clears all data from the storage.
    * @returns A Promise that resolves once the storage has been cleared.
+   * @throws {@link AsyncStorageError} if clearing fails.
    */
   clear(): Promise<void>;
 }

packages/async-storage/src/createAsyncStorage.native.ts

@@ -4,10 +4,18 @@ import NativeAsyncStorage, {
 } from "./native-module/NativeAsyncStorage";
 import { AsyncStorageError } from "./AsyncStorageError";
 
+/**
+ * Creates a new AsyncStorage instance bound to a given database name.
+ * @param databaseName - The name of the database to open or create.
+ */
 export function createAsyncStorage(databaseName: string): AsyncStorage {
   return new AsyncStorageImpl(databaseName);
 }
 
+/**
+ * AsyncStorage implementation backed by the shared-storage module.
+ * Each instance operates on a separate database identified by `dbName`.
+ */
 class AsyncStorageImpl implements AsyncStorage {
   constructor(private readonly dbName: string) {}
 
@@ -98,13 +106,18 @@ class AsyncStorageImpl implements AsyncStorage {
 }
 
 /**
- * This is a proxy to old storage implementation, to help with migration to v3.
- * Usage is highly discouraged and should be used only as a measure to transition v3.
+ * Returns a singleton instance of the legacy (v2) AsyncStorage implementation.
+ *
+ * ⚠️ Usage is discouraged. This is provided only as a migration path to v3.
  */
 export function getLegacyStorage(): AsyncStorage {
   return LegacyAsyncStorageImpl.instance;
 }
 
+/**
+ * Legacy AsyncStorage implementation, backed by the old native module API.
+ * Singleton to ensure consistent state across calls.
+ */
 class LegacyAsyncStorageImpl implements AsyncStorage {
   private constructor() {}
 

packages/async-storage/src/createAsyncStorage.ts

@@ -2,6 +2,18 @@ import type { AsyncStorage } from "./AsyncStorage";
 import { AsyncStorageError } from "./AsyncStorageError";
 import IndexedDBStorage from "./web-module/IndexedDBStorage";
 
+/**
+ * Creates a new AsyncStorage instance bound to a given database name.
+ * @param databaseName - The name of the database to open or create.
+ */
+export function createAsyncStorage(databaseName: string): AsyncStorage {
+  return new AsyncStorageWebImpl(databaseName);
+}
+
+/**
+ * AsyncStorage implementation for web using IndexedDB.
+ * Each instance operates on its own IndexedDB database.
+ */
 class AsyncStorageWebImpl implements AsyncStorage {
   private db: IndexedDBStorage;
 
@@ -93,14 +105,20 @@ class AsyncStorageWebImpl implements AsyncStorage {
   }
 }
 
-export function createAsyncStorage(databaseName: string): AsyncStorage {
-  return new AsyncStorageWebImpl(databaseName);
-}
 
+/**
+ * Returns a singleton instance of the legacy (v2) web AsyncStorage implementation.
+ *
+ * ⚠️ Usage is discouraged. This is provided only as a migration path to v3.
+ */
 export function getLegacyStorage(): AsyncStorage {
   return LegacyAsyncStorageWebImpl.instance;
 }
 
+/**
+ * Legacy AsyncStorage implementation, backed by LocalStorage Web API.
+ * Singleton to ensure consistent state across calls.
+ */
 class LegacyAsyncStorageWebImpl implements AsyncStorage {
   private constructor() {}
   static instance = new LegacyAsyncStorageWebImpl();

packages/async-storage/src/createAsyncStorage.windows.ts

@@ -3,13 +3,27 @@ import { AsyncStorageError } from "./AsyncStorageError";
 import { TurboModuleRegistry, type TurboModule } from "react-native";
 
 /**
- * Because of missing support for Windows native target by Room KMP,
- * Windows target uses v2 implementation of AsyncStorage.
+ * Due to Windows native target not being supported by Room KMP,
+ * custom storages are not available. Instead, this module falls back
+ * to the legacy v2 AsyncStorage implementation.
+ */
+let warned = false;
+
+/**
+ * Creates an AsyncStorage instance.
+ * On Windows, always falls back to legacy storage.
  */
 export function createAsyncStorage(_: string): AsyncStorage {
+  if (!warned && __DEV__) {
+    warned = true;
+    console.warn(
+      "[AsyncStorage] Warning: Creating custom storages is not supported on Windows. Falling back to the legacy implementation."
+    );
+  }
   return getLegacyStorage();
 }
 
+/** Returns a singleton instance of the legacy (v2) AsyncStorage implementation. */
 export function getLegacyStorage(): AsyncStorage {
   return LegacyAsyncStorageImpl.instance;
 }
@@ -231,10 +245,10 @@ class LegacyAsyncStorageImpl implements AsyncStorage {
 }
 
 /**
- *
- * This is a backward compatibility layer, to support Windows target in v3.
- * Room KMP does not support Windows native target currently, so shared-storage cannot be used.
- * https://issuetracker.google.com/issues/363195546
+ * Backward compatibility layer to support the Windows target in v3.
+ * Room KMP does not currently support the Windows native target,
+ * so shared-storage cannot be used on Windows.
+ * See: https://issuetracker.google.com/issues/363195546
  */
 const RNCAsyncStorage =
   TurboModuleRegistry.get<NativeAsyncStorageSpec>("RNCAsyncStorage");