react-native-nitro-storage 0.4.0 → 0.4.3

package/src/index.web.ts

@@ -163,10 +163,12 @@ const webScopeKeyIndex = new Map<NonMemoryScope, Set<string>>([
 const hydratedWebScopeKeyIndex = new Set<NonMemoryScope>();
 const pendingSecureWrites = new Map<string, PendingSecureWrite>();
 let secureFlushScheduled = false;
+let secureDefaultAccessControl: AccessControl = AccessControl.WhenUnlocked;
 const SECURE_WEB_PREFIX = "__secure_";
 const BIOMETRIC_WEB_PREFIX = "__bio_";
 let hasWarnedAboutWebBiometricFallback = false;
 let hasWebStorageEventSubscription = false;
+let webStorageSubscriberCount = 0;
 let metricsObserver: StorageMetricsObserver | undefined;
 const metricsCounters = new Map<
   string,
@@ -200,6 +202,9 @@ function measureOperation<T>(
   fn: () => T,
   keysCount = 1,
 ): T {
+  if (!metricsObserver) {
+    return fn();
+  }
   const start = Date.now();
   try {
     return fn();
@@ -232,6 +237,9 @@ function createLocalStorageWebSecureBackend(): WebSecureStorageBackend {
 let webSecureStorageBackend: WebSecureStorageBackend | undefined =
   createLocalStorageWebSecureBackend();
 
+let cachedSecureBrowserStorage: BrowserStorageLike | undefined;
+let cachedSecureBackendRef: WebSecureStorageBackend | undefined;
+
 function getBrowserStorage(scope: number): BrowserStorageLike | undefined {
   if (scope === StorageScope.Disk) {
     return globalThis.localStorage;
@@ -240,16 +248,24 @@ function getBrowserStorage(scope: number): BrowserStorageLike | undefined {
     if (!webSecureStorageBackend) {
       return undefined;
     }
-    return {
-      setItem: (key, value) => webSecureStorageBackend?.setItem(key, value),
-      getItem: (key) => webSecureStorageBackend?.getItem(key) ?? null,
-      removeItem: (key) => webSecureStorageBackend?.removeItem(key),
-      clear: () => webSecureStorageBackend?.clear(),
-      key: (index) => webSecureStorageBackend?.getAllKeys()[index] ?? null,
+    if (
+      cachedSecureBackendRef === webSecureStorageBackend &&
+      cachedSecureBrowserStorage
+    ) {
+      return cachedSecureBrowserStorage;
+    }
+    cachedSecureBackendRef = webSecureStorageBackend;
+    cachedSecureBrowserStorage = {
+      setItem: (key, value) => webSecureStorageBackend!.setItem(key, value),
+      getItem: (key) => webSecureStorageBackend!.getItem(key) ?? null,
+      removeItem: (key) => webSecureStorageBackend!.removeItem(key),
+      clear: () => webSecureStorageBackend!.clear(),
+      key: (index) => webSecureStorageBackend!.getAllKeys()[index] ?? null,
       get length() {
-        return webSecureStorageBackend?.getAllKeys().length ?? 0;
+        return webSecureStorageBackend!.getAllKeys().length;
       },
     };
+    return cachedSecureBrowserStorage;
   }
   return undefined;
 }
@@ -370,17 +386,27 @@ function handleWebStorageEvent(event: StorageEvent): void {
 }
 
 function ensureWebStorageEventSubscription(): void {
-  if (hasWebStorageEventSubscription) {
-    return;
+  webStorageSubscriberCount += 1;
+  if (
+    webStorageSubscriberCount === 1 &&
+    typeof window !== "undefined" &&
+    typeof window.addEventListener === "function"
+  ) {
+    window.addEventListener("storage", handleWebStorageEvent);
+    hasWebStorageEventSubscription = true;
   }
+}
+
+function maybeCleanupWebStorageSubscription(): void {
+  webStorageSubscriberCount = Math.max(0, webStorageSubscriberCount - 1);
   if (
-    typeof window === "undefined" ||
-    typeof window.addEventListener !== "function"
+    webStorageSubscriberCount === 0 &&
+    hasWebStorageEventSubscription &&
+    typeof window !== "undefined"
   ) {
-    return;
+    window.removeEventListener("storage", handleWebStorageEvent);
+    hasWebStorageEventSubscription = false;
   }
-  window.addEventListener("storage", handleWebStorageEvent);
-  hasWebStorageEventSubscription = true;
 }
 
 function getScopedListeners(scope: NonMemoryScope): KeyListenerRegistry {
@@ -417,13 +443,20 @@ function clearScopeRawCache(scope: NonMemoryScope): void {
 }
 
 function notifyKeyListeners(registry: KeyListenerRegistry, key: string): void {
-  registry.get(key)?.forEach((listener) => listener());
+  const listeners = registry.get(key);
+  if (listeners) {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
 }
 
 function notifyAllListeners(registry: KeyListenerRegistry): void {
-  registry.forEach((listeners) => {
-    listeners.forEach((listener) => listener());
-  });
+  for (const listeners of registry.values()) {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
 }
 
 function addKeyListener(
@@ -482,7 +515,7 @@ function flushSecureWrites(): void {
     if (value === undefined) {
       keysToRemove.push(key);
     } else {
-      const resolvedAccessControl = accessControl ?? AccessControl.WhenUnlocked;
+      const resolvedAccessControl = accessControl ?? secureDefaultAccessControl;
       const existingGroup = groupedSetWrites.get(resolvedAccessControl);
       const group = existingGroup ?? { keys: [], values: [] };
       group.keys.push(key);
@@ -882,7 +915,12 @@ export const storage = {
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
-      clearScopeRawCache(scope);
+      const scopeCache = getScopeRawCache(scope);
+      for (const key of scopeCache.keys()) {
+        if (isNamespaced(key, namespace)) {
+          scopeCache.delete(key);
+        }
+      }
       WebStorage.removeByPrefix(keyPrefix, scope);
     });
   },
@@ -958,9 +996,13 @@ export const storage = {
         return result;
       }
       const keys = WebStorage.getAllKeys(scope);
-      keys.forEach((key) => {
-        const val = WebStorage.get(key, scope);
-        if (val !== undefined) result[key] = val;
+      if (keys.length === 0) return {};
+      const values = WebStorage.getBatch(keys, scope);
+      keys.forEach((key, index) => {
+        const val = values[index];
+        if (val !== undefined && val !== null) {
+          result[key] = val;
+        }
       });
       return result;
     });
@@ -972,7 +1014,8 @@ export const storage = {
       return WebStorage.size(scope);
     });
   },
-  setAccessControl: (_level: AccessControl) => {
+  setAccessControl: (level: AccessControl) => {
+    secureDefaultAccessControl = level;
     recordMetric("storage:setAccessControl", StorageScope.Secure, 0);
   },
   setSecureWritesAsync: (_enabled: boolean) => {
@@ -1005,12 +1048,58 @@ export const storage = {
   resetMetrics: () => {
     metricsCounters.clear();
   },
+  getString: (key: string, scope: StorageScope): string | undefined => {
+    return measureOperation("storage:getString", scope, () => {
+      return getRawValue(key, scope);
+    });
+  },
+  setString: (key: string, value: string, scope: StorageScope): void => {
+    measureOperation("storage:setString", scope, () => {
+      setRawValue(key, value, scope);
+    });
+  },
+  deleteString: (key: string, scope: StorageScope): void => {
+    measureOperation("storage:deleteString", scope, () => {
+      removeRawValue(key, scope);
+    });
+  },
+  import: (data: Record<string, string>, scope: StorageScope): void => {
+    const keys = Object.keys(data);
+    measureOperation(
+      "storage:import",
+      scope,
+      () => {
+        assertValidScope(scope);
+        if (keys.length === 0) return;
+        const values = keys.map((k) => data[k]!);
+
+        if (scope === StorageScope.Memory) {
+          keys.forEach((key, index) => {
+            memoryStore.set(key, values[index]);
+          });
+          keys.forEach((key) => notifyKeyListeners(memoryListeners, key));
+          return;
+        }
+
+        if (scope === StorageScope.Secure) {
+          flushSecureWrites();
+          WebStorage.setSecureAccessControl(secureDefaultAccessControl);
+        }
+
+        WebStorage.setBatch(keys, values, scope);
+        keys.forEach((key, index) => cacheRawValue(scope, key, values[index]));
+      },
+      keys.length,
+    );
+  },
 };
 
 export function setWebSecureStorageBackend(
   backend?: WebSecureStorageBackend,
 ): void {
   webSecureStorageBackend = backend ?? createLocalStorageWebSecureBackend();
+  cachedSecureBrowserStorage = undefined;
+  cachedSecureBackendRef = undefined;
   hydratedWebScopeKeyIndex.delete(StorageScope.Secure);
   clearScopeRawCache(StorageScope.Secure);
 }
@@ -1058,6 +1147,7 @@ export interface StorageItem<T> {
 
 type StorageItemInternal<T> = StorageItem<T> & {
   _triggerListeners: () => void;
+  _invalidateParsedCacheOnly: () => void;
   _hasValidation: boolean;
   _hasExpiration: boolean;
   _readCacheEnabled: boolean;
@@ -1183,17 +1273,18 @@ export function createStorageItem<T = undefined>(
       return memoryStore.get(storageKey);
     }
 
-    if (
-      nonMemoryScope === StorageScope.Secure &&
-      !isBiometric &&
-      hasPendingSecureWrite(storageKey)
-    ) {
-      return readPendingSecureWrite(storageKey);
+    if (nonMemoryScope === StorageScope.Secure && !isBiometric) {
+      const pending = pendingSecureWrites.get(storageKey);
+      if (pending !== undefined) {
+        return pending.value;
+      }
     }
 
     if (readCache) {
-      if (hasCachedRawValue(nonMemoryScope!, storageKey)) {
-        return readCachedRawValue(nonMemoryScope!, storageKey);
+      const cache = getScopeRawCache(nonMemoryScope!);
+      const cached = cache.get(storageKey);
+      if (cached !== undefined || cache.has(storageKey)) {
+        return cached;
       }
     }
 
@@ -1222,7 +1313,7 @@ export function createStorageItem<T = undefined>(
       scheduleSecureWrite(
         storageKey,
         rawValue,
-        secureAccessControl ?? AccessControl.WhenUnlocked,
+        secureAccessControl ?? secureDefaultAccessControl,
       );
       return;
     }
@@ -1246,7 +1337,7 @@ export function createStorageItem<T = undefined>(
       scheduleSecureWrite(
         storageKey,
         undefined,
-        secureAccessControl ?? AccessControl.WhenUnlocked,
+        secureAccessControl ?? secureDefaultAccessControl,
       );
       return;
     }
@@ -1326,6 +1417,7 @@ export function createStorageItem<T = undefined>(
         onExpired?.(storageKey);
         lastValue = ensureValidatedValue(defaultValue, false);
         hasLastValue = true;
+        listeners.forEach((cb) => cb());
         return lastValue;
       }
     }
@@ -1367,6 +1459,7 @@ export function createStorageItem<T = undefined>(
             onExpired?.(storageKey);
             lastValue = ensureValidatedValue(defaultValue, false);
             hasLastValue = true;
+            listeners.forEach((cb) => cb());
             return lastValue;
           }
 
@@ -1405,14 +1498,13 @@ export function createStorageItem<T = undefined>(
         ? valueOrFn(getInternal())
         : valueOrFn;
 
-      invalidateParsedCache();
-
       if (validate && !validate(newValue)) {
         throw new Error(
           `Validation failed for key "${storageKey}" in scope "${StorageScope[config.scope]}".`,
         );
       }
 
+      invalidateParsedCache();
       writeValueWithoutValidation(newValue);
     });
   };
@@ -1462,6 +1554,9 @@ export function createStorageItem<T = undefined>(
       if (listeners.size === 0 && unsubscribe) {
         unsubscribe();
         unsubscribe = null;
+        if (!isMemory) {
+          maybeCleanupWebStorageSubscription();
+        }
       }
     };
   };
@@ -1480,6 +1575,9 @@ export function createStorageItem<T = undefined>(
       invalidateParsedCache();
       listeners.forEach((listener) => listener());
     },
+    _invalidateParsedCacheOnly: () => {
+      invalidateParsedCache();
+    },
     _hasValidation: validate !== undefined,
     _hasExpiration: expiration !== undefined,
     _readCacheEnabled: readCache,
@@ -1496,6 +1594,7 @@ export function createStorageItem<T = undefined>(
 }
 
 export { useStorage, useStorageSelector, useSetStorage } from "./storage-hooks";
+export { createIndexedDBBackend } from "./indexeddb-backend";
 
 type BatchReadItem<T> = Pick<
   StorageItem<T>,
@@ -1544,15 +1643,18 @@ export function getBatch(
 
       items.forEach((item, index) => {
         if (scope === StorageScope.Secure) {
-          if (hasPendingSecureWrite(item.key)) {
-            rawValues[index] = readPendingSecureWrite(item.key);
+          const pending = pendingSecureWrites.get(item.key);
+          if (pending !== undefined) {
+            rawValues[index] = pending.value;
             return;
           }
         }
 
         if (item._readCacheEnabled === true) {
-          if (hasCachedRawValue(scope, item.key)) {
-            rawValues[index] = readCachedRawValue(scope, item.key);
+          const cache = getScopeRawCache(scope);
+          const cached = cache.get(item.key);
+          if (cached !== undefined || cache.has(item.key)) {
+            rawValues[index] = cached;
             return;
           }
         }
@@ -1600,7 +1702,25 @@ export function setBatch<T>(
       );
 
       if (scope === StorageScope.Memory) {
-        items.forEach(({ item, value }) => item.set(value));
+        // Determine if any item needs per-item handling (validation or TTL)
+        const needsIndividualSets = items.some(({ item }) => {
+          const internal = asInternal(item as StorageItem<unknown>);
+          return internal._hasValidation || internal._hasExpiration;
+        });
+
+        if (needsIndividualSets) {
+          items.forEach(({ item, value }) => item.set(value));
+          return;
+        }
+
+        // Atomic write: update all values in memoryStore, invalidate caches, then batch-notify
+        items.forEach(({ item, value }) => {
+          memoryStore.set(item.key, value);
+          asInternal(item as StorageItem<unknown>)._invalidateParsedCacheOnly();
+        });
+        items.forEach(({ item }) =>
+          notifyKeyListeners(memoryListeners, item.key),
+        );
         return;
       }
 
@@ -1626,7 +1746,7 @@ export function setBatch<T>(
 
         secureEntries.forEach(({ item, value, internal }) => {
           const accessControl =
-            internal._secureAccessControl ?? AccessControl.WhenUnlocked;
+            internal._secureAccessControl ?? secureDefaultAccessControl;
           const existingGroup = groupedByAccessControl.get(accessControl);
           const group = existingGroup ?? { keys: [], values: [] };
           group.keys.push(item.key);
@@ -1725,10 +1845,13 @@ export function migrateToLatest(
         return;
       }
       migration(context);
-      writeMigrationVersion(scope, version);
       appliedVersion = version;
     });
 
+    if (appliedVersion !== currentVersion) {
+      writeMigrationVersion(scope, appliedVersion);
+    }
+
     return appliedVersion;
   });
 }
@@ -1743,13 +1866,18 @@ export function runTransaction<T>(
       flushSecureWrites();
     }
 
-    const rollback = new Map<string, string | undefined>();
+    const NOT_SET = Symbol();
+    const rollback = new Map<string, unknown>();
 
     const rememberRollback = (key: string) => {
       if (rollback.has(key)) {
         return;
       }
-      rollback.set(key, getRawValue(key, scope));
+      if (scope === StorageScope.Memory) {
+        rollback.set(key, memoryStore.has(key) ? memoryStore.get(key) : NOT_SET);
+      } else {
+        rollback.set(key, getRawValue(key, scope));
+      }
     };
 
     const tx: TransactionContext = {
@@ -1785,11 +1913,12 @@ export function runTransaction<T>(
       const rollbackEntries = Array.from(rollback.entries()).reverse();
       if (scope === StorageScope.Memory) {
         rollbackEntries.forEach(([key, previousValue]) => {
-          if (previousValue === undefined) {
-            removeRawValue(key, scope);
+          if (previousValue === NOT_SET) {
+            memoryStore.delete(key);
           } else {
-            setRawValue(key, previousValue, scope);
+            memoryStore.set(key, previousValue);
           }
+          notifyKeyListeners(memoryListeners, key);
         });
       } else {
         const keysToSet: string[] = [];
@@ -1801,7 +1930,7 @@ export function runTransaction<T>(
             keysToRemove.push(key);
           } else {
             keysToSet.push(key);
-            valuesToSet.push(previousValue);
+            valuesToSet.push(previousValue as string);
           }
         });
 
@@ -1867,3 +1996,7 @@ export function createSecureAuthStorage<K extends string>(
 
   return result as Record<K, StorageItem<string>>;
 }
+
+export function isKeychainLockedError(_err: unknown): boolean {
+  return false;
+}

package/src/indexeddb-backend.ts

@@ -0,0 +1,143 @@
+import type { WebSecureStorageBackend } from "./index.web";
+
+const DEFAULT_DB_NAME = "nitro-storage-secure";
+const DEFAULT_STORE_NAME = "keyvalue";
+const DB_VERSION = 1;
+
+/**
+ * Opens (or creates) an IndexedDB database and returns the underlying IDBDatabase.
+ * Rejects if IndexedDB is unavailable in the current environment.
+ */
+function openDB(dbName: string, storeName: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (typeof indexedDB === "undefined") {
+      reject(new Error("IndexedDB is not available in this environment."));
+      return;
+    }
+
+    const request = indexedDB.open(dbName, DB_VERSION);
+
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(storeName)) {
+        db.createObjectStore(storeName);
+      }
+    };
+
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () =>
+      reject(request.error ?? new Error("Failed to open IndexedDB database."));
+  });
+}
+
+/**
+ * Creates a `WebSecureStorageBackend` backed by IndexedDB.
+ *
+ * IndexedDB is async, but `WebSecureStorageBackend` requires a synchronous
+ * interface. This implementation bridges the gap with a write-through in-memory
+ * cache:
+ *
+ * - **Reads** are always served from the in-memory cache (synchronous, O(1)).
+ * - **Writes** update the cache synchronously, then persist to IndexedDB
+ *   asynchronously in the background.
+ * - **Initialisation**: the returned backend pre-loads all persisted entries
+ *   from IndexedDB into memory before resolving, so the first synchronous read
+ *   after `await createIndexedDBBackend()` already returns the correct value.
+ *
+ * @param dbName    Name of the IndexedDB database. Defaults to `"nitro-storage-secure"`.
+ * @param storeName Name of the object store inside the database. Defaults to `"keyvalue"`.
+ *
+ * @example
+ * ```ts
+ * import { setWebSecureStorageBackend } from "react-native-nitro-storage";
+ * import { createIndexedDBBackend } from "react-native-nitro-storage/indexeddb-backend";
+ *
+ * const backend = await createIndexedDBBackend();
+ * setWebSecureStorageBackend(backend);
+ * ```
+ */
+export async function createIndexedDBBackend(
+  dbName = DEFAULT_DB_NAME,
+  storeName = DEFAULT_STORE_NAME,
+): Promise<WebSecureStorageBackend> {
+  const db = await openDB(dbName, storeName);
+  const cache = new Map<string, string>();
+
+  // Hydrate the in-memory cache from IndexedDB.
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(storeName, "readonly");
+    const store = tx.objectStore(storeName);
+    const request = store.openCursor();
+
+    request.onsuccess = () => {
+      const cursor = request.result;
+      if (cursor) {
+        const value = cursor.value as unknown;
+        if (typeof value === "string") {
+          cache.set(String(cursor.key), value);
+        }
+        cursor.continue();
+      }
+    };
+
+    tx.oncomplete = () => resolve();
+    tx.onerror = () =>
+      reject(tx.error ?? new Error("Failed to load IndexedDB entries."));
+  });
+
+  /** Fire-and-forget IndexedDB write. Errors are silently ignored to avoid
+   *  breaking the synchronous caller — the in-memory cache is always authoritative. */
+  function persistSet(key: string, value: string): void {
+    try {
+      const tx = db.transaction(storeName, "readwrite");
+      tx.objectStore(storeName).put(value, key);
+    } catch {
+      // Best-effort; cache is the source of truth.
+    }
+  }
+
+  function persistDelete(key: string): void {
+    try {
+      const tx = db.transaction(storeName, "readwrite");
+      tx.objectStore(storeName).delete(key);
+    } catch {
+      // Best-effort.
+    }
+  }
+
+  function persistClear(): void {
+    try {
+      const tx = db.transaction(storeName, "readwrite");
+      tx.objectStore(storeName).clear();
+    } catch {
+      // Best-effort.
+    }
+  }
+
+  const backend: WebSecureStorageBackend = {
+    getItem(key: string): string | null {
+      return cache.get(key) ?? null;
+    },
+
+    setItem(key: string, value: string): void {
+      cache.set(key, value);
+      persistSet(key, value);
+    },
+
+    removeItem(key: string): void {
+      cache.delete(key);
+      persistDelete(key);
+    },
+
+    clear(): void {
+      cache.clear();
+      persistClear();
+    },
+
+    getAllKeys(): string[] {
+      return Array.from(cache.keys());
+    },
+  };
+
+  return backend;
+}