react-native-nitro-storage 0.4.5 → 0.5.1

package/lib/module/index.web.js

@@ -4,6 +4,7 @@ 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";
+import { StorageEventRegistry } from "./storage-events";
 export { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 export { migrateFromMMKV } from "./migration";
 export { getStorageErrorCode } from "./storage-runtime";
@@ -38,7 +39,9 @@ const BIOMETRIC_WEB_PREFIX = "__bio_";
 let hasWarnedAboutWebBiometricFallback = false;
 let hasWindowStorageEventSubscription = false;
 let metricsObserver;
+let eventObserver;
 const metricsCounters = new Map();
+const storageEvents = new StorageEventRegistry();
 function recordMetric(operation, scope, durationMs, keysCount = 1) {
   const existing = metricsCounters.get(operation);
   if (!existing) {
@@ -89,6 +92,9 @@ 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");
@@ -160,6 +166,7 @@ function applyExternalChangeEvent(scope, key, newValue) {
   }
   if (scope === StorageScope.Secure && key.startsWith(SECURE_WEB_PREFIX)) {
     const plainKey = fromSecureStorageKey(key);
+    const oldValue = readCachedRawValue(StorageScope.Secure, plainKey);
     if (newValue === null) {
       ensureWebScopeKeyIndex(StorageScope.Secure).delete(plainKey);
       cacheRawValue(StorageScope.Secure, plainKey, undefined);
@@ -168,10 +175,12 @@ function applyExternalChangeEvent(scope, key, newValue) {
       cacheRawValue(StorageScope.Secure, plainKey, newValue);
     }
     notifyKeyListeners(getScopedListeners(StorageScope.Secure), plainKey);
+    emitKeyChange(StorageScope.Secure, plainKey, oldValue, newValue ?? undefined, "external", "external");
     return;
   }
   if (scope === StorageScope.Secure && key.startsWith(BIOMETRIC_WEB_PREFIX)) {
     const plainKey = fromBiometricStorageKey(key);
+    const oldValue = readCachedRawValue(StorageScope.Secure, plainKey);
     if (newValue === null) {
       if (withWebBackendOperation(StorageScope.Secure, "external-sync:getItem", backend => backend.getItem(toSecureStorageKey(plainKey))) === null) {
         ensureWebScopeKeyIndex(StorageScope.Secure).delete(plainKey);
@@ -182,8 +191,10 @@ function applyExternalChangeEvent(scope, key, newValue) {
       cacheRawValue(StorageScope.Secure, plainKey, newValue);
     }
     notifyKeyListeners(getScopedListeners(StorageScope.Secure), plainKey);
+    emitKeyChange(StorageScope.Secure, plainKey, oldValue, newValue ?? undefined, "external", "external");
     return;
   }
+  const oldValue = readCachedRawValue(scope, key);
   if (newValue === null) {
     ensureWebScopeKeyIndex(scope).delete(key);
     cacheRawValue(scope, key, undefined);
@@ -192,6 +203,7 @@ function applyExternalChangeEvent(scope, key, newValue) {
     cacheRawValue(scope, key, newValue);
   }
   notifyKeyListeners(getScopedListeners(scope), key);
+  emitKeyChange(scope, key, oldValue, newValue ?? undefined, "external", "external");
 }
 function handleWebStorageEvent(event) {
   const key = event.key;
@@ -282,6 +294,46 @@ function addKeyListener(registry, key, listener) {
     }
   };
 }
+function getEventRawValue(scope, key) {
+  if (scope === StorageScope.Memory) {
+    const value = memoryStore.get(key);
+    return typeof value === "string" ? value : undefined;
+  }
+  return getRawValue(key, scope);
+}
+function createKeyChange(scope, key, oldValue, newValue, operation, source) {
+  return {
+    type: "key",
+    scope,
+    key,
+    oldValue,
+    newValue,
+    operation,
+    source
+  };
+}
+function hasStorageChangeObservers(scope) {
+  return storageEvents.hasListeners(scope) || eventObserver !== undefined;
+}
+function emitKeyChange(scope, key, oldValue, newValue, operation, source) {
+  const event = createKeyChange(scope, key, oldValue, newValue, operation, source);
+  storageEvents.emitKey(event);
+  eventObserver?.(event);
+}
+function emitBatchChange(scope, operation, source, changes) {
+  if (changes.length === 0) {
+    return;
+  }
+  const event = {
+    type: "batch",
+    scope,
+    operation,
+    source,
+    changes
+  };
+  storageEvents.emitBatch(event);
+  eventObserver?.(event);
+}
 function readPendingSecureWrite(key) {
   return pendingSecureWrites.get(key)?.value;
 }
@@ -531,13 +583,10 @@ const WebStorage = {
     return () => {};
   },
   has: (key, scope) => {
-    if (scope === StorageScope.Secure) {
-      return withWebBackendOperation(scope, "has", backend => backend.getItem(toSecureStorageKey(key))) !== null || withWebBackendOperation(scope, "has", backend => backend.getItem(toBiometricStorageKey(key))) !== null;
-    }
-    if (scope !== StorageScope.Disk) {
-      return false;
+    if (scope === StorageScope.Disk || scope === StorageScope.Secure) {
+      return ensureWebScopeKeyIndex(scope).has(key);
     }
-    return withWebBackendOperation(scope, "has", backend => backend.getItem(key)) !== null;
+    return false;
   },
   getAllKeys: scope => {
     if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
@@ -628,15 +677,18 @@ function getRawValue(key, scope) {
 }
 function setRawValue(key, value, scope) {
   assertValidScope(scope);
+  const oldValue = scope === StorageScope.Memory ? getEventRawValue(scope, key) : undefined;
   if (scope === StorageScope.Memory) {
     memoryStore.set(key, value);
     notifyKeyListeners(memoryListeners, key);
+    emitKeyChange(scope, key, oldValue, value, "set", "memory");
     return;
   }
   if (scope === StorageScope.Disk) {
     cacheRawValue(scope, key, value);
     if (diskWritesAsync) {
       scheduleDiskWrite(key, value);
+      emitKeyChange(scope, key, oldValue, value, "set", "web");
       return;
     }
     flushDiskWrites();
@@ -648,18 +700,22 @@ function setRawValue(key, value, scope) {
   }
   WebStorage.set(key, value, scope);
   cacheRawValue(scope, key, value);
+  emitKeyChange(scope, key, oldValue, value, "set", "web");
 }
 function removeRawValue(key, scope) {
   assertValidScope(scope);
+  const oldValue = getEventRawValue(scope, key);
   if (scope === StorageScope.Memory) {
     memoryStore.delete(key);
     notifyKeyListeners(memoryListeners, key);
+    emitKeyChange(scope, key, oldValue, undefined, "remove", "memory");
     return;
   }
   if (scope === StorageScope.Disk) {
     cacheRawValue(scope, key, undefined);
     if (diskWritesAsync) {
       scheduleDiskWrite(key, undefined);
+      emitKeyChange(scope, key, oldValue, undefined, "remove", "web");
       return;
     }
     flushDiskWrites();
@@ -671,6 +727,7 @@ function removeRawValue(key, scope) {
   }
   WebStorage.remove(key, scope);
   cacheRawValue(scope, key, undefined);
+  emitKeyChange(scope, key, oldValue, undefined, "remove", "web");
 }
 function readMigrationVersion(scope) {
   const raw = getRawValue(MIGRATION_VERSION_KEY, scope);
@@ -684,11 +741,43 @@ function writeMigrationVersion(scope, version) {
   setRawValue(MIGRATION_VERSION_KEY, String(version), scope);
 }
 export const storage = {
+  subscribe: (scope, listener) => {
+    assertValidScope(scope);
+    if (scope !== StorageScope.Memory) {
+      ensureExternalSyncSubscriptions();
+    }
+    return storageEvents.subscribe(scope, listener);
+  },
+  subscribeKey: (scope, key, listener) => {
+    assertValidScope(scope);
+    if (scope !== StorageScope.Memory) {
+      ensureExternalSyncSubscriptions();
+    }
+    return storageEvents.subscribeKey(scope, key, listener);
+  },
+  subscribePrefix: (scope, prefix, listener) => {
+    assertValidScope(scope);
+    if (scope !== StorageScope.Memory) {
+      ensureExternalSyncSubscriptions();
+    }
+    return storageEvents.subscribePrefix(scope, prefix, listener);
+  },
+  subscribeNamespace: (namespace, scope, listener) => {
+    return storage.subscribePrefix(scope, prefixKey(namespace, ""), listener);
+  },
+  setEventObserver: observer => {
+    eventObserver = observer;
+    if (observer) {
+      ensureExternalSyncSubscriptions();
+    }
+  },
   clear: scope => {
     measureOperation("storage:clear", scope, () => {
+      const previousValues = hasStorageChangeObservers(scope) ? storage.getAll(scope) : {};
       if (scope === StorageScope.Memory) {
         memoryStore.clear();
         notifyAllListeners(memoryListeners);
+        emitBatchChange(scope, "clear", "memory", Object.keys(previousValues).map(key => createKeyChange(scope, key, previousValues[key], undefined, "clear", "memory")));
         return;
       }
       if (scope === StorageScope.Disk) {
@@ -701,6 +790,7 @@ export const storage = {
       }
       clearScopeRawCache(scope);
       WebStorage.clear(scope);
+      emitBatchChange(scope, "clear", "web", Object.keys(previousValues).map(key => createKeyChange(scope, key, previousValues[key], undefined, "clear", "web")));
     });
   },
   clearAll: () => {
@@ -714,15 +804,26 @@ export const storage = {
     measureOperation("storage:clearNamespace", scope, () => {
       assertValidScope(scope);
       if (scope === StorageScope.Memory) {
-        for (const key of memoryStore.keys()) {
-          if (isNamespaced(key, namespace)) {
-            memoryStore.delete(key);
-          }
+        const affectedKeys = Array.from(memoryStore.keys()).filter(key => isNamespaced(key, namespace));
+        const previousValues = affectedKeys.map(key => ({
+          key,
+          value: getEventRawValue(scope, key)
+        }));
+        if (affectedKeys.length === 0) {
+          return;
         }
-        notifyAllListeners(memoryListeners);
+        affectedKeys.forEach(key => {
+          memoryStore.delete(key);
+        });
+        affectedKeys.forEach(key => notifyKeyListeners(memoryListeners, key));
+        emitBatchChange(scope, "clearNamespace", "memory", previousValues.map(({
+          key,
+          value
+        }) => createKeyChange(scope, key, value, undefined, "clearNamespace", "memory")));
         return;
       }
       const keyPrefix = prefixKey(namespace, "");
+      const previousValues = hasStorageChangeObservers(scope) ? storage.getByPrefix(keyPrefix, scope) : {};
       if (scope === StorageScope.Disk) {
         flushDiskWrites();
       }
@@ -736,6 +837,7 @@ export const storage = {
         }
       }
       WebStorage.removeByPrefix(keyPrefix, scope);
+      emitBatchChange(scope, "clearNamespace", "web", Object.keys(previousValues).map(key => createKeyChange(scope, key, previousValues[key], undefined, "clearNamespace", "web")));
     });
   },
   clearBiometric: () => {
@@ -844,6 +946,9 @@ export const storage = {
       return result;
     });
   },
+  export: scope => {
+    return measureOperation("storage:export", scope, () => storage.getAll(scope));
+  },
   size: scope => {
     return measureOperation("storage:size", scope, () => {
       assertValidScope(scope);
@@ -915,6 +1020,57 @@ export const storage = {
     },
     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);
@@ -936,11 +1092,13 @@ export const storage = {
       assertValidScope(scope);
       if (keys.length === 0) return;
       const values = keys.map(k => data[k]);
+      const changes = keys.map((key, index) => createKeyChange(scope, key, getEventRawValue(scope, key), values[index], "import", scope === StorageScope.Memory ? "memory" : "web"));
       if (scope === StorageScope.Memory) {
         keys.forEach((key, index) => {
           memoryStore.set(key, values[index]);
         });
         keys.forEach(key => notifyKeyListeners(memoryListeners, key));
+        emitBatchChange(scope, "import", "memory", changes);
         return;
       }
       if (scope === StorageScope.Secure) {
@@ -952,6 +1110,7 @@ export const storage = {
       }
       WebStorage.setBatch(keys, values, scope);
       keys.forEach((key, index) => cacheRawValue(scope, key, values[index]));
+      emitBatchChange(scope, "import", "web", changes);
     }, keys.length);
   }
 };
@@ -1093,56 +1252,68 @@ export function createStorageItem(config) {
     return raw;
   };
   const writeStoredRaw = rawValue => {
+    const oldValue = config.scope === StorageScope.Memory ? getEventRawValue(config.scope, storageKey) : undefined;
     if (isBiometric) {
       WebStorage.setSecureBiometricWithLevel(storageKey, rawValue, resolvedBiometricLevel);
+      emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "web");
       return;
     }
     cacheRawValue(nonMemoryScope, storageKey, rawValue);
     if (nonMemoryScope === StorageScope.Disk) {
       if (coalesceDiskWrites || diskWritesAsync) {
         scheduleDiskWrite(storageKey, rawValue);
+        emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "web");
         return;
       }
       clearPendingDiskWrite(storageKey);
     }
     if (coalesceSecureWrites) {
       scheduleSecureWrite(storageKey, rawValue, secureAccessControl ?? secureDefaultAccessControl);
+      emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "web");
       return;
     }
     if (nonMemoryScope === StorageScope.Secure) {
       clearPendingSecureWrite(storageKey);
     }
     WebStorage.set(storageKey, rawValue, config.scope);
+    emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "web");
   };
   const removeStoredRaw = () => {
+    const oldValue = getEventRawValue(config.scope, storageKey);
     if (isBiometric) {
       WebStorage.deleteSecureBiometric(storageKey);
+      emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "web");
       return;
     }
     cacheRawValue(nonMemoryScope, storageKey, undefined);
     if (nonMemoryScope === StorageScope.Disk) {
       if (coalesceDiskWrites || diskWritesAsync) {
         scheduleDiskWrite(storageKey, undefined);
+        emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "web");
         return;
       }
       clearPendingDiskWrite(storageKey);
     }
     if (coalesceSecureWrites) {
       scheduleSecureWrite(storageKey, undefined, secureAccessControl ?? secureDefaultAccessControl);
+      emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "web");
       return;
     }
     if (nonMemoryScope === StorageScope.Secure) {
       clearPendingSecureWrite(storageKey);
     }
     WebStorage.remove(storageKey, config.scope);
+    emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "web");
   };
   const writeValueWithoutValidation = value => {
     if (isMemory) {
+      const oldValue = getEventRawValue(config.scope, storageKey);
       if (memoryExpiration) {
         memoryExpiration.set(storageKey, Date.now() + (expirationTtlMs ?? 0));
       }
       memoryStore.set(storageKey, value);
       notifyKeyListeners(memoryListeners, storageKey);
+      emitKeyChange(config.scope, storageKey, oldValue, typeof value === "string" ? value : undefined, "set", "memory");
       return;
     }
     const serialized = serialize(value);
@@ -1274,11 +1445,13 @@ export function createStorageItem(config) {
     measureOperation("item:delete", config.scope, () => {
       invalidateParsedCache();
       if (isMemory) {
+        const oldValue = getEventRawValue(config.scope, storageKey);
         if (memoryExpiration) {
           memoryExpiration.delete(storageKey);
         }
         memoryStore.delete(storageKey);
         notifyKeyListeners(memoryListeners, storageKey);
+        emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "memory");
         return;
       }
       removeStoredRaw();
@@ -1312,6 +1485,22 @@ export function createStorageItem(config) {
       }
     };
   };
+  const subscribeSelector = (selector, listener, options = {}) => {
+    const isEqual = options.isEqual ?? Object.is;
+    let currentValue = selector(getInternal());
+    if (options.fireImmediately === true) {
+      listener(currentValue, currentValue);
+    }
+    return subscribe(() => {
+      const nextValue = selector(getInternal());
+      if (isEqual(currentValue, nextValue)) {
+        return;
+      }
+      const previousValue = currentValue;
+      currentValue = nextValue;
+      listener(nextValue, previousValue);
+    });
+  };
   const storageItem = {
     get,
     getWithVersion,
@@ -1320,6 +1509,7 @@ export function createStorageItem(config) {
     delete: deleteItem,
     has: hasItem,
     subscribe,
+    subscribeSelector,
     serialize,
     deserialize,
     _triggerListeners: () => {
@@ -1422,6 +1612,10 @@ export function setBatch(items, scope) {
         }) => item.set(value));
         return;
       }
+      const changes = items.map(({
+        item,
+        value
+      }) => createKeyChange(scope, item.key, getEventRawValue(scope, item.key), typeof value === "string" ? value : undefined, "setBatch", "memory"));
 
       // Atomic write: update all values in memoryStore, invalidate caches, then batch-notify
       items.forEach(({
@@ -1434,6 +1628,7 @@ export function setBatch(items, scope) {
       items.forEach(({
         item
       }) => notifyKeyListeners(memoryListeners, item.key));
+      emitBatchChange(scope, "setBatch", "memory", changes);
       return;
     }
     if (scope === StorageScope.Secure) {
@@ -1456,6 +1651,10 @@ export function setBatch(items, scope) {
         return;
       }
       flushSecureWrites();
+      const keys = secureEntries.map(({
+        item
+      }) => item.key);
+      const oldValues = hasStorageChangeObservers(scope) ? WebStorage.getBatch(keys, scope) : [];
       const groupedByAccessControl = new Map();
       secureEntries.forEach(({
         item,
@@ -1479,6 +1678,10 @@ export function setBatch(items, scope) {
         WebStorage.setBatch(group.keys, group.values, scope);
         group.keys.forEach((key, index) => cacheRawValue(scope, key, group.values[index]));
       });
+      emitBatchChange(scope, "setBatch", "web", secureEntries.map(({
+        item,
+        value
+      }, index) => createKeyChange(scope, item.key, oldValues[index], item.serialize(value), "setBatch", "web")));
       return;
     }
     flushDiskWrites();
@@ -1494,15 +1697,19 @@ export function setBatch(items, scope) {
     }
     const keys = items.map(entry => entry.item.key);
     const values = items.map(entry => entry.item.serialize(entry.value));
+    const oldValues = hasStorageChangeObservers(scope) ? WebStorage.getBatch(keys, scope) : [];
     WebStorage.setBatch(keys, values, scope);
     keys.forEach((key, index) => cacheRawValue(scope, key, values[index]));
+    emitBatchChange(scope, "setBatch", "web", keys.map((key, index) => createKeyChange(scope, key, oldValues[index], values[index], "setBatch", "web")));
   }, items.length);
 }
 export function removeBatch(items, scope) {
   measureOperation("batch:remove", scope, () => {
     assertBatchScope(items, scope);
     if (scope === StorageScope.Memory) {
+      const changes = items.map(item => createKeyChange(scope, item.key, getEventRawValue(scope, item.key), undefined, "removeBatch", "memory"));
       items.forEach(item => item.delete());
+      emitBatchChange(scope, "removeBatch", "memory", changes);
       return;
     }
     const keys = items.map(item => item.key);
@@ -1512,8 +1719,10 @@ export function removeBatch(items, scope) {
     if (scope === StorageScope.Secure) {
       flushSecureWrites();
     }
+    const oldValues = hasStorageChangeObservers(scope) ? WebStorage.getBatch(keys, scope) : [];
     WebStorage.removeBatch(keys, scope);
     keys.forEach(key => cacheRawValue(scope, key, undefined));
+    emitBatchChange(scope, "removeBatch", "web", keys.map((key, index) => createKeyChange(scope, key, oldValues[index], undefined, "removeBatch", "web")));
   }, items.length);
 }
 export function registerMigration(version, migration) {