react-native-nitro-storage 0.4.4 → 0.5.0

package/lib/module/index.web.js

@@ -2,8 +2,11 @@
 
 import { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 import { MIGRATION_VERSION_KEY, isStoredEnvelope, assertBatchScope, assertValidScope, serializeWithPrimitiveFastPath, deserializeWithPrimitiveFastPath, toVersionToken, prefixKey, isNamespaced } from "./internal";
+import { createLocalStorageWebBackend } from "./web-storage-backend";
+import { getStorageErrorCode, isLockedStorageErrorCode } from "./storage-runtime";
 export { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 export { migrateFromMMKV } from "./migration";
+export { getStorageErrorCode } from "./storage-runtime";
 function asInternal(item) {
   return item;
 }
@@ -17,20 +20,23 @@ const registeredMigrations = new Map();
 const runMicrotask = typeof queueMicrotask === "function" ? queueMicrotask : task => {
   Promise.resolve().then(task);
 };
+const now = typeof performance !== "undefined" && typeof performance.now === "function" ? () => performance.now() : () => Date.now();
 const memoryStore = new Map();
 const memoryListeners = new Map();
 const webScopeListeners = new Map([[StorageScope.Disk, new Map()], [StorageScope.Secure, new Map()]]);
 const scopedRawCache = new Map([[StorageScope.Disk, new Map()], [StorageScope.Secure, new Map()]]);
 const webScopeKeyIndex = new Map([[StorageScope.Disk, new Set()], [StorageScope.Secure, new Set()]]);
 const hydratedWebScopeKeyIndex = new Set();
+const pendingDiskWrites = new Map();
+let diskFlushScheduled = false;
+let diskWritesAsync = false;
 const pendingSecureWrites = new Map();
 let secureFlushScheduled = false;
 let secureDefaultAccessControl = AccessControl.WhenUnlocked;
 const SECURE_WEB_PREFIX = "__secure_";
 const BIOMETRIC_WEB_PREFIX = "__bio_";
 let hasWarnedAboutWebBiometricFallback = false;
-let hasWebStorageEventSubscription = false;
-let webStorageSubscriberCount = 0;
+let hasWindowStorageEventSubscription = false;
 let metricsObserver;
 const metricsCounters = new Map();
 function recordMetric(operation, scope, durationMs, keysCount = 1) {
@@ -57,61 +63,54 @@ function measureOperation(operation, scope, fn, keysCount = 1) {
   if (!metricsObserver) {
     return fn();
   }
-  const start = Date.now();
+  const start = now();
   try {
     return fn();
   } finally {
-    recordMetric(operation, scope, Date.now() - start, keysCount);
+    recordMetric(operation, scope, now() - start, keysCount);
   }
 }
-function createLocalStorageWebSecureBackend() {
-  return {
-    getItem: key => globalThis.localStorage?.getItem(key) ?? null,
-    setItem: (key, value) => globalThis.localStorage?.setItem(key, value),
-    removeItem: key => globalThis.localStorage?.removeItem(key),
-    clear: () => globalThis.localStorage?.clear(),
-    getAllKeys: () => {
-      const storage = globalThis.localStorage;
-      if (!storage) return [];
-      const keys = [];
-      for (let index = 0; index < storage.length; index += 1) {
-        const key = storage.key(index);
-        if (key) {
-          keys.push(key);
-        }
-      }
-      return keys;
-    }
-  };
+function createDefaultDiskBackend() {
+  return createLocalStorageWebBackend({
+    name: "localStorage:disk",
+    includeKey: key => !key.startsWith(SECURE_WEB_PREFIX) && !key.startsWith(BIOMETRIC_WEB_PREFIX)
+  });
 }
-let webSecureStorageBackend = createLocalStorageWebSecureBackend();
-let cachedSecureBrowserStorage;
-let cachedSecureBackendRef;
-function getBrowserStorage(scope) {
-  if (scope === StorageScope.Disk) {
-    return globalThis.localStorage;
+function createDefaultSecureBackend() {
+  return createLocalStorageWebBackend({
+    name: "localStorage:secure",
+    includeKey: key => key.startsWith(SECURE_WEB_PREFIX) || key.startsWith(BIOMETRIC_WEB_PREFIX)
+  });
+}
+let webDiskStorageBackend = createDefaultDiskBackend();
+let webSecureStorageBackend = createDefaultSecureBackend();
+const externalSyncUnsubscribers = new Map();
+function getBackendName(scope, backend) {
+  const scopeName = scope === StorageScope.Disk ? "disk" : "secure";
+  return backend?.name ?? `web:${scopeName}`;
+}
+function getWebSecureEncryptionStatus(backend) {
+  return backend?.name === "localStorage:secure" ? "unavailable" : "unknown";
+}
+function createWebStorageError(scope, operation, error, backend) {
+  const backendName = getBackendName(scope, backend);
+  const message = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return new Error(`NitroStorage(web): ${operation} failed for ${backendName}: ${message}`);
+}
+function withWebBackendOperation(scope, operation, fn) {
+  const backend = scope === StorageScope.Disk ? webDiskStorageBackend : webSecureStorageBackend;
+  if (!backend) {
+    throw new Error(`NitroStorage(web): ${operation} failed because no ${scope === StorageScope.Disk ? "disk" : "secure"} backend is configured.`);
   }
-  if (scope === StorageScope.Secure) {
-    if (!webSecureStorageBackend) {
-      return undefined;
-    }
-    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;
-      }
-    };
-    return cachedSecureBrowserStorage;
+  try {
+    ensureExternalSyncSubscriptions();
+    return fn(backend);
+  } catch (error) {
+    throw createWebStorageError(scope, operation, error, backend);
   }
-  return undefined;
+}
+function getWebBackend(scope) {
+  return scope === StorageScope.Disk ? webDiskStorageBackend : webSecureStorageBackend;
 }
 function toSecureStorageKey(key) {
   return `${SECURE_WEB_PREFIX}${key}`;
@@ -132,28 +131,21 @@ function hydrateWebScopeKeyIndex(scope) {
   if (hydratedWebScopeKeyIndex.has(scope)) {
     return;
   }
-  const storage = getBrowserStorage(scope);
+  const backend = getWebBackend(scope);
   const keyIndex = getWebScopeKeyIndex(scope);
   keyIndex.clear();
-  if (storage) {
-    for (let index = 0; index < storage.length; index += 1) {
-      const key = storage.key(index);
-      if (!key) {
-        continue;
-      }
-      if (scope === StorageScope.Disk) {
-        if (!key.startsWith(SECURE_WEB_PREFIX) && !key.startsWith(BIOMETRIC_WEB_PREFIX)) {
-          keyIndex.add(key);
-        }
-        continue;
-      }
-      if (key.startsWith(SECURE_WEB_PREFIX)) {
-        keyIndex.add(fromSecureStorageKey(key));
-        continue;
-      }
-      if (key.startsWith(BIOMETRIC_WEB_PREFIX)) {
-        keyIndex.add(fromBiometricStorageKey(key));
-      }
+  const keys = backend?.getAllKeys() ?? [];
+  for (const key of keys) {
+    if (scope === StorageScope.Disk) {
+      keyIndex.add(key);
+      continue;
+    }
+    if (key.startsWith(SECURE_WEB_PREFIX)) {
+      keyIndex.add(fromSecureStorageKey(key));
+      continue;
+    }
+    if (key.startsWith(BIOMETRIC_WEB_PREFIX)) {
+      keyIndex.add(fromBiometricStorageKey(key));
     }
   }
   hydratedWebScopeKeyIndex.add(scope);
@@ -162,65 +154,85 @@ function ensureWebScopeKeyIndex(scope) {
   hydrateWebScopeKeyIndex(scope);
   return getWebScopeKeyIndex(scope);
 }
-function handleWebStorageEvent(event) {
-  const key = event.key;
+function applyExternalChangeEvent(scope, key, newValue) {
   if (key === null) {
-    clearScopeRawCache(StorageScope.Disk);
-    clearScopeRawCache(StorageScope.Secure);
-    ensureWebScopeKeyIndex(StorageScope.Disk).clear();
-    ensureWebScopeKeyIndex(StorageScope.Secure).clear();
-    notifyAllListeners(getScopedListeners(StorageScope.Disk));
-    notifyAllListeners(getScopedListeners(StorageScope.Secure));
+    clearScopeRawCache(scope);
+    ensureWebScopeKeyIndex(scope).clear();
+    notifyAllListeners(getScopedListeners(scope));
     return;
   }
-  if (key.startsWith(SECURE_WEB_PREFIX)) {
+  if (scope === StorageScope.Secure && key.startsWith(SECURE_WEB_PREFIX)) {
     const plainKey = fromSecureStorageKey(key);
-    if (event.newValue === null) {
+    if (newValue === null) {
       ensureWebScopeKeyIndex(StorageScope.Secure).delete(plainKey);
       cacheRawValue(StorageScope.Secure, plainKey, undefined);
     } else {
       ensureWebScopeKeyIndex(StorageScope.Secure).add(plainKey);
-      cacheRawValue(StorageScope.Secure, plainKey, event.newValue);
+      cacheRawValue(StorageScope.Secure, plainKey, newValue);
     }
     notifyKeyListeners(getScopedListeners(StorageScope.Secure), plainKey);
     return;
   }
-  if (key.startsWith(BIOMETRIC_WEB_PREFIX)) {
+  if (scope === StorageScope.Secure && key.startsWith(BIOMETRIC_WEB_PREFIX)) {
     const plainKey = fromBiometricStorageKey(key);
-    if (event.newValue === null) {
-      if (getBrowserStorage(StorageScope.Secure)?.getItem(toSecureStorageKey(plainKey)) === null) {
+    if (newValue === null) {
+      if (withWebBackendOperation(StorageScope.Secure, "external-sync:getItem", backend => backend.getItem(toSecureStorageKey(plainKey))) === null) {
         ensureWebScopeKeyIndex(StorageScope.Secure).delete(plainKey);
       }
       cacheRawValue(StorageScope.Secure, plainKey, undefined);
     } else {
       ensureWebScopeKeyIndex(StorageScope.Secure).add(plainKey);
-      cacheRawValue(StorageScope.Secure, plainKey, event.newValue);
+      cacheRawValue(StorageScope.Secure, plainKey, newValue);
     }
     notifyKeyListeners(getScopedListeners(StorageScope.Secure), plainKey);
     return;
   }
-  if (event.newValue === null) {
-    ensureWebScopeKeyIndex(StorageScope.Disk).delete(key);
-    cacheRawValue(StorageScope.Disk, key, undefined);
+  if (newValue === null) {
+    ensureWebScopeKeyIndex(scope).delete(key);
+    cacheRawValue(scope, key, undefined);
   } else {
-    ensureWebScopeKeyIndex(StorageScope.Disk).add(key);
-    cacheRawValue(StorageScope.Disk, key, event.newValue);
+    ensureWebScopeKeyIndex(scope).add(key);
+    cacheRawValue(scope, key, newValue);
   }
-  notifyKeyListeners(getScopedListeners(StorageScope.Disk), key);
+  notifyKeyListeners(getScopedListeners(scope), key);
 }
-function ensureWebStorageEventSubscription() {
-  webStorageSubscriberCount += 1;
-  if (webStorageSubscriberCount === 1 && typeof window !== "undefined" && typeof window.addEventListener === "function") {
-    window.addEventListener("storage", handleWebStorageEvent);
-    hasWebStorageEventSubscription = true;
+function handleWebStorageEvent(event) {
+  const key = event.key;
+  if (key === null) {
+    applyExternalChangeEvent(StorageScope.Disk, null, null);
+    applyExternalChangeEvent(StorageScope.Secure, null, null);
+    return;
+  }
+  if (key.startsWith(SECURE_WEB_PREFIX) || key.startsWith(BIOMETRIC_WEB_PREFIX)) {
+    applyExternalChangeEvent(StorageScope.Secure, key, event.newValue);
+    return;
   }
+  applyExternalChangeEvent(StorageScope.Disk, key, event.newValue);
+}
+function subscribeToBackendChanges(scope) {
+  if (externalSyncUnsubscribers.has(scope)) {
+    return;
+  }
+  const backend = getWebBackend(scope);
+  if (!backend?.subscribe) {
+    return;
+  }
+  const unsubscribe = backend.subscribe(event => {
+    applyExternalChangeEvent(scope, event.key, event.newValue);
+  });
+  externalSyncUnsubscribers.set(scope, unsubscribe);
+}
+function resetBackendChangeSubscription(scope) {
+  externalSyncUnsubscribers.get(scope)?.();
+  externalSyncUnsubscribers.delete(scope);
 }
-function maybeCleanupWebStorageSubscription() {
-  webStorageSubscriberCount = Math.max(0, webStorageSubscriberCount - 1);
-  if (webStorageSubscriberCount === 0 && hasWebStorageEventSubscription && typeof window !== "undefined") {
-    window.removeEventListener("storage", handleWebStorageEvent);
-    hasWebStorageEventSubscription = false;
+function ensureExternalSyncSubscriptions() {
+  if (!hasWindowStorageEventSubscription && typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    window.addEventListener("storage", handleWebStorageEvent);
+    hasWindowStorageEventSubscription = true;
   }
+  subscribeToBackendChanges(StorageScope.Disk);
+  subscribeToBackendChanges(StorageScope.Secure);
 }
 function getScopedListeners(scope) {
   return webScopeListeners.get(scope);
@@ -276,12 +288,49 @@ function addKeyListener(registry, key, listener) {
 function readPendingSecureWrite(key) {
   return pendingSecureWrites.get(key)?.value;
 }
+function readPendingDiskWrite(key) {
+  return pendingDiskWrites.get(key)?.value;
+}
+function hasPendingDiskWrite(key) {
+  return pendingDiskWrites.has(key);
+}
 function hasPendingSecureWrite(key) {
   return pendingSecureWrites.has(key);
 }
+function clearPendingDiskWrite(key) {
+  pendingDiskWrites.delete(key);
+}
 function clearPendingSecureWrite(key) {
   pendingSecureWrites.delete(key);
 }
+function flushDiskWrites() {
+  diskFlushScheduled = false;
+  if (pendingDiskWrites.size === 0) {
+    return;
+  }
+  const writes = Array.from(pendingDiskWrites.values());
+  pendingDiskWrites.clear();
+  const keysToSet = [];
+  const valuesToSet = [];
+  const keysToRemove = [];
+  writes.forEach(({
+    key,
+    value
+  }) => {
+    if (value === undefined) {
+      keysToRemove.push(key);
+      return;
+    }
+    keysToSet.push(key);
+    valuesToSet.push(value);
+  });
+  if (keysToSet.length > 0) {
+    WebStorage.setBatch(keysToSet, valuesToSet, StorageScope.Disk);
+  }
+  if (keysToRemove.length > 0) {
+    WebStorage.removeBatch(keysToRemove, StorageScope.Disk);
+  }
+}
 function flushSecureWrites() {
   secureFlushScheduled = false;
   if (pendingSecureWrites.size === 0) {
@@ -320,6 +369,17 @@ function flushSecureWrites() {
     WebStorage.removeBatch(keysToRemove, StorageScope.Secure);
   }
 }
+function scheduleDiskWrite(key, value) {
+  pendingDiskWrites.set(key, {
+    key,
+    value
+  });
+  if (diskFlushScheduled) {
+    return;
+  }
+  diskFlushScheduled = true;
+  runMicrotask(flushDiskWrites);
+}
 function scheduleSecureWrite(key, value, accessControl) {
   const pendingWrite = {
     key,
@@ -340,117 +400,124 @@ const WebStorage = {
   equals: other => other === WebStorage,
   dispose: () => {},
   set: (key, value, scope) => {
-    const storage = getBrowserStorage(scope);
-    if (!storage) {
+    if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
       return;
     }
     const storageKey = scope === StorageScope.Secure ? toSecureStorageKey(key) : key;
-    storage.setItem(storageKey, value);
-    if (scope === StorageScope.Disk || scope === StorageScope.Secure) {
-      ensureWebScopeKeyIndex(scope).add(key);
-      notifyKeyListeners(getScopedListeners(scope), key);
-    }
+    withWebBackendOperation(scope, "set", backend => {
+      backend.setItem(storageKey, value);
+    });
+    ensureWebScopeKeyIndex(scope).add(key);
+    notifyKeyListeners(getScopedListeners(scope), key);
   },
   get: (key, scope) => {
-    const storage = getBrowserStorage(scope);
+    if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
+      return undefined;
+    }
     const storageKey = scope === StorageScope.Secure ? toSecureStorageKey(key) : key;
-    return storage?.getItem(storageKey) ?? undefined;
+    const value = withWebBackendOperation(scope, "get", backend => backend.getItem(storageKey));
+    return value ?? undefined;
   },
   remove: (key, scope) => {
-    const storage = getBrowserStorage(scope);
-    if (!storage) {
+    if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
       return;
     }
     if (scope === StorageScope.Secure) {
-      storage.removeItem(toSecureStorageKey(key));
-      storage.removeItem(toBiometricStorageKey(key));
+      withWebBackendOperation(scope, "remove", backend => {
+        if (backend.removeMany) {
+          backend.removeMany([toSecureStorageKey(key), toBiometricStorageKey(key)]);
+          return;
+        }
+        backend.removeItem(toSecureStorageKey(key));
+        backend.removeItem(toBiometricStorageKey(key));
+      });
     } else {
-      storage.removeItem(key);
-    }
-    if (scope === StorageScope.Disk || scope === StorageScope.Secure) {
-      ensureWebScopeKeyIndex(scope).delete(key);
-      notifyKeyListeners(getScopedListeners(scope), key);
+      withWebBackendOperation(scope, "remove", backend => {
+        backend.removeItem(key);
+      });
     }
+    ensureWebScopeKeyIndex(scope).delete(key);
+    notifyKeyListeners(getScopedListeners(scope), key);
   },
   clear: scope => {
-    const storage = getBrowserStorage(scope);
-    if (!storage) {
+    if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
       return;
     }
-    if (scope === StorageScope.Secure) {
-      const keysToRemove = [];
-      for (let i = 0; i < storage.length; i++) {
-        const key = storage.key(i);
-        if (key?.startsWith(SECURE_WEB_PREFIX) || key?.startsWith(BIOMETRIC_WEB_PREFIX)) {
-          keysToRemove.push(key);
-        }
-      }
-      keysToRemove.forEach(key => storage.removeItem(key));
-    } else if (scope === StorageScope.Disk) {
-      const keysToRemove = [];
-      for (let i = 0; i < storage.length; i++) {
-        const key = storage.key(i);
-        if (key && !key.startsWith(SECURE_WEB_PREFIX) && !key.startsWith(BIOMETRIC_WEB_PREFIX)) {
-          keysToRemove.push(key);
-        }
-      }
-      keysToRemove.forEach(key => storage.removeItem(key));
-    } else {
-      storage.clear();
-    }
-    if (scope === StorageScope.Disk || scope === StorageScope.Secure) {
-      ensureWebScopeKeyIndex(scope).clear();
-      notifyAllListeners(getScopedListeners(scope));
-    }
+    withWebBackendOperation(scope, "clear", backend => {
+      backend.clear();
+    });
+    ensureWebScopeKeyIndex(scope).clear();
+    notifyAllListeners(getScopedListeners(scope));
   },
   setBatch: (keys, values, scope) => {
-    const storage = getBrowserStorage(scope);
-    if (!storage) {
+    if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
       return;
     }
+    const entries = [];
     keys.forEach((key, index) => {
       const value = values[index];
       if (value === undefined) {
         return;
       }
-      const storageKey = scope === StorageScope.Secure ? toSecureStorageKey(key) : key;
-      storage.setItem(storageKey, value);
+      entries.push([scope === StorageScope.Secure ? toSecureStorageKey(key) : key, value]);
     });
-    if (scope === StorageScope.Disk || scope === StorageScope.Secure) {
-      const keyIndex = ensureWebScopeKeyIndex(scope);
-      keys.forEach(key => keyIndex.add(key));
-      const listeners = getScopedListeners(scope);
-      keys.forEach(key => notifyKeyListeners(listeners, key));
-    }
+    withWebBackendOperation(scope, "setBatch", backend => {
+      if (backend.setMany) {
+        backend.setMany(entries);
+        return;
+      }
+      entries.forEach(([storageKey, value]) => {
+        backend.setItem(storageKey, value);
+      });
+    });
+    const keyIndex = ensureWebScopeKeyIndex(scope);
+    keys.forEach(key => keyIndex.add(key));
+    const listeners = getScopedListeners(scope);
+    keys.forEach(key => notifyKeyListeners(listeners, key));
   },
   getBatch: (keys, scope) => {
-    const storage = getBrowserStorage(scope);
-    return keys.map(key => {
-      const storageKey = scope === StorageScope.Secure ? toSecureStorageKey(key) : key;
-      return storage?.getItem(storageKey) ?? undefined;
+    if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
+      return keys.map(() => undefined);
+    }
+    const storageKeys = keys.map(key => scope === StorageScope.Secure ? toSecureStorageKey(key) : key);
+    const values = withWebBackendOperation(scope, "getBatch", backend => {
+      if (backend.getMany) {
+        return backend.getMany(storageKeys);
+      }
+      return storageKeys.map(storageKey => backend.getItem(storageKey));
     });
+    return values.map(value => value ?? undefined);
   },
   removeBatch: (keys, scope) => {
-    const storage = getBrowserStorage(scope);
-    if (!storage) {
+    if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
       return;
     }
     if (scope === StorageScope.Secure) {
-      keys.forEach(key => {
-        storage.removeItem(toSecureStorageKey(key));
-        storage.removeItem(toBiometricStorageKey(key));
+      const storageKeys = keys.flatMap(key => [toSecureStorageKey(key), toBiometricStorageKey(key)]);
+      withWebBackendOperation(scope, "removeBatch", backend => {
+        if (backend.removeMany) {
+          backend.removeMany(storageKeys);
+          return;
+        }
+        storageKeys.forEach(storageKey => {
+          backend.removeItem(storageKey);
+        });
       });
     } else {
-      keys.forEach(key => {
-        storage.removeItem(key);
+      withWebBackendOperation(scope, "removeBatch", backend => {
+        if (backend.removeMany) {
+          backend.removeMany(keys);
+          return;
+        }
+        keys.forEach(key => {
+          backend.removeItem(key);
+        });
       });
     }
-    if (scope === StorageScope.Disk || scope === StorageScope.Secure) {
-      const keyIndex = ensureWebScopeKeyIndex(scope);
-      keys.forEach(key => keyIndex.delete(key));
-      const listeners = getScopedListeners(scope);
-      keys.forEach(key => notifyKeyListeners(listeners, key));
-    }
+    const keyIndex = ensureWebScopeKeyIndex(scope);
+    keys.forEach(key => keyIndex.delete(key));
+    const listeners = getScopedListeners(scope);
+    keys.forEach(key => notifyKeyListeners(listeners, key));
   },
   removeByPrefix: (prefix, scope) => {
     if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
@@ -467,11 +534,13 @@ const WebStorage = {
     return () => {};
   },
   has: (key, scope) => {
-    const storage = getBrowserStorage(scope);
     if (scope === StorageScope.Secure) {
-      return storage?.getItem(toSecureStorageKey(key)) !== null || storage?.getItem(toBiometricStorageKey(key)) !== null;
+      return withWebBackendOperation(scope, "has", backend => backend.getItem(toSecureStorageKey(key))) !== null || withWebBackendOperation(scope, "has", backend => backend.getItem(toBiometricStorageKey(key))) !== null;
     }
-    return storage?.getItem(key) !== null;
+    if (scope !== StorageScope.Disk) {
+      return false;
+    }
+    return withWebBackendOperation(scope, "has", backend => backend.getItem(key)) !== null;
   },
   getAllKeys: scope => {
     if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
@@ -502,40 +571,43 @@ const WebStorage = {
       hasWarnedAboutWebBiometricFallback = true;
       console.warn("[NitroStorage] Biometric storage is not supported on web. Using localStorage.");
     }
-    getBrowserStorage(StorageScope.Secure)?.setItem(toBiometricStorageKey(key), value);
+    withWebBackendOperation(StorageScope.Secure, "setSecureBiometric", backend => backend.setItem(toBiometricStorageKey(key), value));
     ensureWebScopeKeyIndex(StorageScope.Secure).add(key);
     notifyKeyListeners(getScopedListeners(StorageScope.Secure), key);
   },
   getSecureBiometric: key => {
-    return getBrowserStorage(StorageScope.Secure)?.getItem(toBiometricStorageKey(key)) ?? undefined;
+    const value = withWebBackendOperation(StorageScope.Secure, "getSecureBiometric", backend => backend.getItem(toBiometricStorageKey(key)));
+    return value ?? undefined;
   },
   deleteSecureBiometric: key => {
-    const storage = getBrowserStorage(StorageScope.Secure);
-    storage?.removeItem(toBiometricStorageKey(key));
-    if (storage?.getItem(toSecureStorageKey(key)) === null) {
+    withWebBackendOperation(StorageScope.Secure, "deleteSecureBiometric", backend => backend.removeItem(toBiometricStorageKey(key)));
+    if (withWebBackendOperation(StorageScope.Secure, "deleteSecureBiometric:getItem", backend => backend.getItem(toSecureStorageKey(key))) === null) {
       ensureWebScopeKeyIndex(StorageScope.Secure).delete(key);
     }
     notifyKeyListeners(getScopedListeners(StorageScope.Secure), key);
   },
   hasSecureBiometric: key => {
-    return getBrowserStorage(StorageScope.Secure)?.getItem(toBiometricStorageKey(key)) !== null;
+    return withWebBackendOperation(StorageScope.Secure, "hasSecureBiometric", backend => backend.getItem(toBiometricStorageKey(key))) !== null;
   },
   clearSecureBiometric: () => {
-    const storage = getBrowserStorage(StorageScope.Secure);
-    if (!storage) return;
-    const keysToNotify = [];
-    const toRemove = [];
-    for (let i = 0; i < storage.length; i++) {
-      const k = storage.key(i);
-      if (k?.startsWith(BIOMETRIC_WEB_PREFIX)) {
-        toRemove.push(k);
-        keysToNotify.push(fromBiometricStorageKey(k));
-      }
+    const storageKeys = withWebBackendOperation(StorageScope.Secure, "clearSecureBiometric:getAllKeys", backend => backend.getAllKeys());
+    const keysToNotify = storageKeys.filter(key => key.startsWith(BIOMETRIC_WEB_PREFIX)).map(key => fromBiometricStorageKey(key));
+    if (keysToNotify.length === 0) {
+      return;
     }
-    toRemove.forEach(k => storage.removeItem(k));
+    withWebBackendOperation(StorageScope.Secure, "clearSecureBiometric", backend => {
+      const biometricKeys = keysToNotify.map(key => toBiometricStorageKey(key));
+      if (backend.removeMany) {
+        backend.removeMany(biometricKeys);
+        return;
+      }
+      biometricKeys.forEach(storageKey => {
+        backend.removeItem(storageKey);
+      });
+    });
     const keyIndex = ensureWebScopeKeyIndex(StorageScope.Secure);
     keysToNotify.forEach(key => {
-      if (storage.getItem(toSecureStorageKey(key)) === null) {
+      if (withWebBackendOperation(StorageScope.Secure, "clearSecureBiometric:getItem", backend => backend.getItem(toSecureStorageKey(key))) === null) {
         keyIndex.delete(key);
       }
     });
@@ -549,6 +621,9 @@ function getRawValue(key, scope) {
     const value = memoryStore.get(key);
     return typeof value === "string" ? value : undefined;
   }
+  if (scope === StorageScope.Disk && hasPendingDiskWrite(key)) {
+    return readPendingDiskWrite(key);
+  }
   if (scope === StorageScope.Secure && hasPendingSecureWrite(key)) {
     return readPendingSecureWrite(key);
   }
@@ -561,6 +636,15 @@ function setRawValue(key, value, scope) {
     notifyKeyListeners(memoryListeners, key);
     return;
   }
+  if (scope === StorageScope.Disk) {
+    cacheRawValue(scope, key, value);
+    if (diskWritesAsync) {
+      scheduleDiskWrite(key, value);
+      return;
+    }
+    flushDiskWrites();
+    clearPendingDiskWrite(key);
+  }
   if (scope === StorageScope.Secure) {
     flushSecureWrites();
     clearPendingSecureWrite(key);
@@ -575,6 +659,15 @@ function removeRawValue(key, scope) {
     notifyKeyListeners(memoryListeners, key);
     return;
   }
+  if (scope === StorageScope.Disk) {
+    cacheRawValue(scope, key, undefined);
+    if (diskWritesAsync) {
+      scheduleDiskWrite(key, undefined);
+      return;
+    }
+    flushDiskWrites();
+    clearPendingDiskWrite(key);
+  }
   if (scope === StorageScope.Secure) {
     flushSecureWrites();
     clearPendingSecureWrite(key);
@@ -601,6 +694,10 @@ export const storage = {
         notifyAllListeners(memoryListeners);
         return;
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+        pendingDiskWrites.clear();
+      }
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
         pendingSecureWrites.clear();
@@ -629,6 +726,9 @@ export const storage = {
         return;
       }
       const keyPrefix = prefixKey(namespace, "");
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
@@ -650,6 +750,12 @@ export const storage = {
     return measureOperation("storage:has", scope, () => {
       assertValidScope(scope);
       if (scope === StorageScope.Memory) return memoryStore.has(key);
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return WebStorage.has(key, scope);
     });
   },
@@ -657,6 +763,12 @@ export const storage = {
     return measureOperation("storage:getAllKeys", scope, () => {
       assertValidScope(scope);
       if (scope === StorageScope.Memory) return Array.from(memoryStore.keys());
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return WebStorage.getAllKeys(scope);
     });
   },
@@ -666,6 +778,12 @@ export const storage = {
       if (scope === StorageScope.Memory) {
         return Array.from(memoryStore.keys()).filter(key => key.startsWith(prefix));
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return WebStorage.getKeysByPrefix(prefix, scope);
     });
   },
@@ -685,6 +803,12 @@ export const storage = {
         });
         return result;
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       const values = WebStorage.getBatch(keys, scope);
       keys.forEach((key, index) => {
         const value = values[index];
@@ -705,6 +829,12 @@ export const storage = {
         });
         return result;
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       const keys = WebStorage.getAllKeys(scope);
       if (keys.length === 0) return {};
       const values = WebStorage.getBatch(keys, scope);
@@ -721,6 +851,12 @@ export const storage = {
     return measureOperation("storage:size", scope, () => {
       assertValidScope(scope);
       if (scope === StorageScope.Memory) return memoryStore.size;
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return WebStorage.size(scope);
     });
   },
@@ -731,6 +867,19 @@ export const storage = {
   setSecureWritesAsync: _enabled => {
     recordMetric("storage:setSecureWritesAsync", StorageScope.Secure, 0);
   },
+  setDiskWritesAsync: enabled => {
+    measureOperation("storage:setDiskWritesAsync", StorageScope.Disk, () => {
+      diskWritesAsync = enabled;
+      if (!enabled) {
+        flushDiskWrites();
+      }
+    });
+  },
+  flushDiskWrites: () => {
+    measureOperation("storage:flushDiskWrites", StorageScope.Disk, () => {
+      flushDiskWrites();
+    });
+  },
   flushSecureWrites: () => {
     measureOperation("storage:flushSecureWrites", StorageScope.Secure, () => {
       flushSecureWrites();
@@ -757,6 +906,69 @@ export const storage = {
   resetMetrics: () => {
     metricsCounters.clear();
   },
+  getCapabilities: () => ({
+    platform: "web",
+    backend: {
+      disk: getBackendName(StorageScope.Disk, webDiskStorageBackend),
+      secure: getBackendName(StorageScope.Secure, webSecureStorageBackend)
+    },
+    writeBuffering: {
+      disk: true,
+      secure: true
+    },
+    errorClassification: true
+  }),
+  getSecurityCapabilities: () => {
+    const secureBackend = getBackendName(StorageScope.Secure, webSecureStorageBackend);
+    return {
+      platform: "web",
+      secureStorage: {
+        backend: secureBackend,
+        encrypted: getWebSecureEncryptionStatus(webSecureStorageBackend),
+        accessControl: "unavailable",
+        keychainAccessGroup: "unavailable",
+        hardwareBacked: "unavailable"
+      },
+      biometric: {
+        storage: "unavailable",
+        prompt: "unavailable",
+        biometryOnly: "unavailable",
+        biometryOrPasscode: "unavailable"
+      },
+      metadata: {
+        perKey: true,
+        listsWithoutValues: true,
+        persistsTimestamps: false
+      }
+    };
+  },
+  getSecureMetadata: key => {
+    return measureOperation("storage:getSecureMetadata", StorageScope.Secure, () => {
+      flushSecureWrites();
+      const biometricProtected = WebStorage.hasSecureBiometric(key);
+      const exists = biometricProtected || WebStorage.has(key, StorageScope.Secure);
+      let kind = "missing";
+      if (exists) {
+        kind = biometricProtected ? "biometric" : "secure";
+      }
+      return {
+        key,
+        exists,
+        kind,
+        backend: getBackendName(StorageScope.Secure, webSecureStorageBackend),
+        encrypted: getWebSecureEncryptionStatus(webSecureStorageBackend),
+        hardwareBacked: "unavailable",
+        biometricProtected,
+        valueExposed: false
+      };
+    });
+  },
+  getAllSecureMetadata: () => {
+    return measureOperation("storage:getAllSecureMetadata", StorageScope.Secure, () => {
+      flushSecureWrites();
+      return WebStorage.getAllKeys(StorageScope.Secure).map(key => storage.getSecureMetadata(key));
+    });
+  },
   getString: (key, scope) => {
     return measureOperation("storage:getString", scope, () => {
       return getRawValue(key, scope);
@@ -789,21 +1001,50 @@ export const storage = {
         flushSecureWrites();
         WebStorage.setSecureAccessControl(secureDefaultAccessControl);
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
       WebStorage.setBatch(keys, values, scope);
       keys.forEach((key, index) => cacheRawValue(scope, key, values[index]));
     }, keys.length);
   }
 };
 export function setWebSecureStorageBackend(backend) {
-  webSecureStorageBackend = backend ?? createLocalStorageWebSecureBackend();
-  cachedSecureBrowserStorage = undefined;
-  cachedSecureBackendRef = undefined;
+  pendingSecureWrites.clear();
+  webSecureStorageBackend = backend ?? createDefaultSecureBackend();
+  resetBackendChangeSubscription(StorageScope.Secure);
   hydratedWebScopeKeyIndex.delete(StorageScope.Secure);
   clearScopeRawCache(StorageScope.Secure);
+  ensureExternalSyncSubscriptions();
 }
 export function getWebSecureStorageBackend() {
   return webSecureStorageBackend;
 }
+export function setWebDiskStorageBackend(backend) {
+  pendingDiskWrites.clear();
+  webDiskStorageBackend = backend ?? createDefaultDiskBackend();
+  resetBackendChangeSubscription(StorageScope.Disk);
+  hydratedWebScopeKeyIndex.delete(StorageScope.Disk);
+  clearScopeRawCache(StorageScope.Disk);
+  ensureExternalSyncSubscriptions();
+}
+export function getWebDiskStorageBackend() {
+  return webDiskStorageBackend;
+}
+export async function flushWebStorageBackends() {
+  flushDiskWrites();
+  flushSecureWrites();
+  const flushes = [];
+  const diskFlush = webDiskStorageBackend?.flush;
+  const secureFlush = webSecureStorageBackend?.flush;
+  if (diskFlush) {
+    flushes.push(diskFlush());
+  }
+  if (secureFlush) {
+    flushes.push(secureFlush());
+  }
+  await Promise.all(flushes);
+}
 function canUseRawBatchPath(item) {
   return item._hasExpiration === false && item._hasValidation === false && item._isBiometric !== true && item._secureAccessControl === undefined;
 }
@@ -831,6 +1072,7 @@ export function createStorageItem(config) {
   const expirationTtlMs = expiration?.ttlMs;
   const memoryExpiration = expiration && isMemory ? new Map() : null;
   const readCache = !isMemory && config.readCache === true;
+  const coalesceDiskWrites = config.scope === StorageScope.Disk && config.coalesceDiskWrites === true;
   const coalesceSecureWrites = config.scope === StorageScope.Secure && config.coalesceSecureWrites === true && !isBiometric;
   const defaultValue = config.defaultValue;
   const nonMemoryScope = config.scope === StorageScope.Disk ? StorageScope.Disk : config.scope === StorageScope.Secure ? StorageScope.Secure : null;
@@ -861,7 +1103,7 @@ export function createStorageItem(config) {
       unsubscribe = addKeyListener(memoryListeners, storageKey, listener);
       return;
     }
-    ensureWebStorageEventSubscription();
+    ensureExternalSyncSubscriptions();
     unsubscribe = addKeyListener(getScopedListeners(nonMemoryScope), storageKey, listener);
   };
   const readStoredRaw = () => {
@@ -878,6 +1120,12 @@ export function createStorageItem(config) {
       }
       return memoryStore.get(storageKey);
     }
+    if (nonMemoryScope === StorageScope.Disk) {
+      const pending = pendingDiskWrites.get(storageKey);
+      if (pending !== undefined) {
+        return pending.value;
+      }
+    }
     if (nonMemoryScope === StorageScope.Secure && !isBiometric) {
       const pending = pendingSecureWrites.get(storageKey);
       if (pending !== undefined) {
@@ -904,6 +1152,13 @@ export function createStorageItem(config) {
       return;
     }
     cacheRawValue(nonMemoryScope, storageKey, rawValue);
+    if (nonMemoryScope === StorageScope.Disk) {
+      if (coalesceDiskWrites || diskWritesAsync) {
+        scheduleDiskWrite(storageKey, rawValue);
+        return;
+      }
+      clearPendingDiskWrite(storageKey);
+    }
     if (coalesceSecureWrites) {
       scheduleSecureWrite(storageKey, rawValue, secureAccessControl ?? secureDefaultAccessControl);
       return;
@@ -919,6 +1174,13 @@ export function createStorageItem(config) {
       return;
     }
     cacheRawValue(nonMemoryScope, storageKey, undefined);
+    if (nonMemoryScope === StorageScope.Disk) {
+      if (coalesceDiskWrites || diskWritesAsync) {
+        scheduleDiskWrite(storageKey, undefined);
+        return;
+      }
+      clearPendingDiskWrite(storageKey);
+    }
     if (coalesceSecureWrites) {
       scheduleSecureWrite(storageKey, undefined, secureAccessControl ?? secureDefaultAccessControl);
       return;
@@ -1079,6 +1341,18 @@ export function createStorageItem(config) {
   const hasItem = () => measureOperation("item:has", config.scope, () => {
     if (isMemory) return memoryStore.has(storageKey);
     if (isBiometric) return WebStorage.hasSecureBiometric(storageKey);
+    if (nonMemoryScope === StorageScope.Disk) {
+      const pending = pendingDiskWrites.get(storageKey);
+      if (pending !== undefined) {
+        return pending.value !== undefined;
+      }
+    }
+    if (nonMemoryScope === StorageScope.Secure) {
+      const pending = pendingSecureWrites.get(storageKey);
+      if (pending !== undefined) {
+        return pending.value !== undefined;
+      }
+    }
     return WebStorage.has(storageKey, config.scope);
   });
   const subscribe = callback => {
@@ -1089,9 +1363,6 @@ export function createStorageItem(config) {
       if (listeners.size === 0 && unsubscribe) {
         unsubscribe();
         unsubscribe = null;
-        if (!isMemory) {
-          maybeCleanupWebStorageSubscription();
-        }
       }
     };
   };
@@ -1141,6 +1412,13 @@ export function getBatch(items, scope) {
     const keysToFetch = [];
     const keyIndexes = [];
     items.forEach((item, index) => {
+      if (scope === StorageScope.Disk) {
+        const pending = pendingDiskWrites.get(item.key);
+        if (pending !== undefined) {
+          rawValues[index] = pending.value;
+          return;
+        }
+      }
       if (scope === StorageScope.Secure) {
         const pending = pendingSecureWrites.get(item.key);
         if (pending !== undefined) {
@@ -1257,6 +1535,7 @@ export function setBatch(items, scope) {
       });
       return;
     }
+    flushDiskWrites();
     const useRawBatchPath = items.every(({
       item
     }) => canUseRawBatchPath(asInternal(item)));
@@ -1281,6 +1560,9 @@ export function removeBatch(items, scope) {
       return;
     }
     const keys = items.map(item => item.key);
+    if (scope === StorageScope.Disk) {
+      flushDiskWrites();
+    }
     if (scope === StorageScope.Secure) {
       flushSecureWrites();
     }
@@ -1326,6 +1608,9 @@ export function migrateToLatest(scope = StorageScope.Disk) {
 export function runTransaction(scope, transaction) {
   return measureOperation("transaction:run", scope, () => {
     assertValidScope(scope);
+    if (scope === StorageScope.Disk) {
+      flushDiskWrites();
+    }
     if (scope === StorageScope.Secure) {
       flushSecureWrites();
     }
@@ -1392,6 +1677,9 @@ export function runTransaction(scope, transaction) {
             valuesToSet.push(previousValue);
           }
         });
+        if (scope === StorageScope.Disk) {
+          flushDiskWrites();
+        }
         if (scope === StorageScope.Secure) {
           flushSecureWrites();
         }
@@ -1437,7 +1725,7 @@ export function createSecureAuthStorage(config, options) {
   }
   return result;
 }
-export function isKeychainLockedError(_err) {
-  return false;
+export function isKeychainLockedError(err) {
+  return isLockedStorageErrorCode(getStorageErrorCode(err));
 }
 //# sourceMappingURL=index.web.js.map