react-native-nitro-storage 0.5.0 → 0.5.2

package/lib/module/index.js

@@ -4,6 +4,7 @@ import { NitroModules } from "react-native-nitro-modules";
 import { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 import { MIGRATION_VERSION_KEY, isStoredEnvelope, assertBatchScope, assertValidScope, decodeNativeBatchValue, serializeWithPrimitiveFastPath, deserializeWithPrimitiveFastPath, toVersionToken, prefixKey, isNamespaced } from "./internal";
 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";
@@ -39,8 +40,11 @@ let diskWritesAsync = false;
 const pendingSecureWrites = new Map();
 let secureFlushScheduled = false;
 let secureDefaultAccessControl = AccessControl.WhenUnlocked;
+const suppressedNativeEvents = new Map([[StorageScope.Disk, new Map()], [StorageScope.Secure, new Map()]]);
 let metricsObserver;
+let eventObserver;
 const metricsCounters = new Map();
+const storageEvents = new StorageEventRegistry();
 const nativeSecureBackend = "platform-secure-storage";
 function recordMetric(operation, scope, durationMs, keysCount = 1) {
   const existing = metricsCounters.get(operation);
@@ -91,6 +95,23 @@ function hasCachedRawValue(scope, key) {
 function clearScopeRawCache(scope) {
   getScopeRawCache(scope).clear();
 }
+function suppressNativeEvent(scope, key) {
+  const suppressedEvents = suppressedNativeEvents.get(scope);
+  suppressedEvents.set(key, (suppressedEvents.get(key) ?? 0) + 1);
+}
+function consumeSuppressedNativeEvent(scope, key) {
+  const suppressedEvents = suppressedNativeEvents.get(scope);
+  const count = suppressedEvents.get(key);
+  if (count === undefined) {
+    return false;
+  }
+  if (count <= 1) {
+    suppressedEvents.delete(key);
+  } else {
+    suppressedEvents.set(key, count - 1);
+  }
+  return true;
+}
 function notifyKeyListeners(registry, key) {
   const listeners = registry.get(key);
   if (listeners) {
@@ -124,6 +145,52 @@ 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) {
+  if (source === "native" && operation !== "external" && scope !== StorageScope.Memory && scopedUnsubscribers.has(scope)) {
+    suppressNativeEvent(scope, key);
+  }
+  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;
+  }
+  if (source === "native" && operation !== "external" && scope !== StorageScope.Memory && scopedUnsubscribers.has(scope)) {
+    changes.forEach(change => suppressNativeEvent(scope, change.key));
+  }
+  const event = {
+    type: "batch",
+    scope,
+    operation,
+    source,
+    changes
+  };
+  storageEvents.emitBatch(event);
+  eventObserver?.(event);
+}
 function readPendingSecureWrite(key) {
   return pendingSecureWrites.get(key)?.value;
 }
@@ -260,14 +327,19 @@ function ensureNativeScopeSubscription(scope) {
       notifyAllListeners(getScopedListeners(scope));
       return;
     }
+    const oldValue = readCachedRawValue(scope, key);
     cacheRawValue(scope, key, value);
     notifyKeyListeners(getScopedListeners(scope), key);
+    if (consumeSuppressedNativeEvent(scope, key)) {
+      return;
+    }
+    emitKeyChange(scope, key, oldValue, value, "external", "native");
   });
-  scopedUnsubscribers.set(scope, unsubscribe);
+  scopedUnsubscribers.set(scope, typeof unsubscribe === "function" ? unsubscribe : () => {});
 }
 function maybeCleanupNativeScopeSubscription(scope) {
   const listeners = getScopedListeners(scope);
-  if (listeners.size > 0) {
+  if (listeners.size > 0 || storageEvents.hasListeners(scope) || eventObserver !== undefined) {
     return;
   }
   const unsubscribe = scopedUnsubscribers.get(scope);
@@ -293,15 +365,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", "native");
       return;
     }
     flushDiskWrites();
@@ -314,18 +389,22 @@ function setRawValue(key, value, scope) {
   }
   getStorageModule().set(key, value, scope);
   cacheRawValue(scope, key, value);
+  emitKeyChange(scope, key, oldValue, value, "set", "native");
 }
 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", "native");
       return;
     }
     flushDiskWrites();
@@ -337,6 +416,7 @@ function removeRawValue(key, scope) {
   }
   getStorageModule().remove(key, scope);
   cacheRawValue(scope, key, undefined);
+  emitKeyChange(scope, key, oldValue, undefined, "remove", "native");
 }
 function readMigrationVersion(scope) {
   const raw = getRawValue(MIGRATION_VERSION_KEY, scope);
@@ -350,11 +430,62 @@ function writeMigrationVersion(scope, version) {
   setRawValue(MIGRATION_VERSION_KEY, String(version), scope);
 }
 export const storage = {
+  subscribe: (scope, listener) => {
+    assertValidScope(scope);
+    if (scope !== StorageScope.Memory) {
+      ensureNativeScopeSubscription(scope);
+      const unsubscribe = storageEvents.subscribe(scope, listener);
+      return () => {
+        unsubscribe();
+        maybeCleanupNativeScopeSubscription(scope);
+      };
+    }
+    return storageEvents.subscribe(scope, listener);
+  },
+  subscribeKey: (scope, key, listener) => {
+    assertValidScope(scope);
+    if (scope !== StorageScope.Memory) {
+      ensureNativeScopeSubscription(scope);
+      const unsubscribe = storageEvents.subscribeKey(scope, key, listener);
+      return () => {
+        unsubscribe();
+        maybeCleanupNativeScopeSubscription(scope);
+      };
+    }
+    return storageEvents.subscribeKey(scope, key, listener);
+  },
+  subscribePrefix: (scope, prefix, listener) => {
+    assertValidScope(scope);
+    if (scope !== StorageScope.Memory) {
+      ensureNativeScopeSubscription(scope);
+      const unsubscribe = storageEvents.subscribePrefix(scope, prefix, listener);
+      return () => {
+        unsubscribe();
+        maybeCleanupNativeScopeSubscription(scope);
+      };
+    }
+    return storageEvents.subscribePrefix(scope, prefix, listener);
+  },
+  subscribeNamespace: (namespace, scope, listener) => {
+    return storage.subscribePrefix(scope, prefixKey(namespace, ""), listener);
+  },
+  setEventObserver: observer => {
+    eventObserver = observer;
+    if (observer) {
+      ensureNativeScopeSubscription(StorageScope.Disk);
+      ensureNativeScopeSubscription(StorageScope.Secure);
+      return;
+    }
+    maybeCleanupNativeScopeSubscription(StorageScope.Disk);
+    maybeCleanupNativeScopeSubscription(StorageScope.Secure);
+  },
   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) {
@@ -367,6 +498,7 @@ export const storage = {
       }
       clearScopeRawCache(scope);
       getStorageModule().clear(scope);
+      emitBatchChange(scope, "clear", "native", Object.keys(previousValues).map(key => createKeyChange(scope, key, previousValues[key], undefined, "clear", "native")));
     });
   },
   clearAll: () => {
@@ -380,15 +512,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();
       }
@@ -402,6 +545,7 @@ export const storage = {
         }
       }
       getStorageModule().removeByPrefix(keyPrefix, scope);
+      emitBatchChange(scope, "clearNamespace", "native", Object.keys(previousValues).map(key => createKeyChange(scope, key, previousValues[key], undefined, "clearNamespace", "native")));
     });
   },
   clearBiometric: () => {
@@ -451,7 +595,7 @@ export const storage = {
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
-      return getStorageModule().getKeysByPrefix(prefix, scope);
+      return getStorageModule().getKeysByPrefix(prefix, scope) ?? [];
     });
   },
   getByPrefix: (prefix, scope) => {
@@ -476,7 +620,7 @@ export const storage = {
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
-      const values = getStorageModule().getBatch(keys, scope);
+      const values = getStorageModule().getBatch(keys, scope) ?? [];
       keys.forEach((key, idx) => {
         const value = decodeNativeBatchValue(values[idx]);
         if (value !== undefined) {
@@ -491,9 +635,10 @@ export const storage = {
       assertValidScope(scope);
       const result = {};
       if (scope === StorageScope.Memory) {
-        memoryStore.forEach((value, key) => {
+        for (const key of memoryStore.keys()) {
+          const value = memoryStore.get(key);
           if (typeof value === "string") result[key] = value;
-        });
+        }
         return result;
       }
       if (scope === StorageScope.Disk) {
@@ -502,9 +647,9 @@ export const storage = {
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
-      const keys = getStorageModule().getAllKeys(scope);
+      const keys = getStorageModule().getAllKeys(scope) ?? [];
       if (keys.length === 0) return result;
-      const values = getStorageModule().getBatch(keys, scope);
+      const values = getStorageModule().getBatch(keys, scope) ?? [];
       keys.forEach((key, idx) => {
         const val = decodeNativeBatchValue(values[idx]);
         if (val !== undefined) result[key] = val;
@@ -512,6 +657,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);
@@ -661,11 +809,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" : "native"));
       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) {
@@ -674,6 +824,7 @@ export const storage = {
       }
       getStorageModule().setBatch(keys, values, scope);
       keys.forEach((key, index) => cacheRawValue(scope, key, values[index]));
+      emitBatchChange(scope, "import", "native", changes);
     }, keys.length);
   }
 };
@@ -794,20 +945,24 @@ export function createStorageItem(config) {
     return raw;
   };
   const writeStoredRaw = rawValue => {
+    const oldValue = undefined;
     if (isBiometric) {
       getStorageModule().setSecureBiometricWithLevel(storageKey, rawValue, resolvedBiometricLevel);
+      emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "native");
       return;
     }
     cacheRawValue(nonMemoryScope, storageKey, rawValue);
     if (nonMemoryScope === StorageScope.Disk) {
       if (coalesceDiskWrites || diskWritesAsync) {
         scheduleDiskWrite(storageKey, rawValue);
+        emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "native");
         return;
       }
       clearPendingDiskWrite(storageKey);
     }
     if (coalesceSecureWrites) {
       scheduleSecureWrite(storageKey, rawValue, secureAccessControl ?? secureDefaultAccessControl);
+      emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "native");
       return;
     }
     if (nonMemoryScope === StorageScope.Secure) {
@@ -815,36 +970,44 @@ export function createStorageItem(config) {
       getStorageModule().setSecureAccessControl(secureAccessControl ?? secureDefaultAccessControl);
     }
     getStorageModule().set(storageKey, rawValue, config.scope);
+    emitKeyChange(config.scope, storageKey, oldValue, rawValue, "set", "native");
   };
   const removeStoredRaw = () => {
+    const oldValue = getEventRawValue(config.scope, storageKey);
     if (isBiometric) {
       getStorageModule().deleteSecureBiometric(storageKey);
+      emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "native");
       return;
     }
     cacheRawValue(nonMemoryScope, storageKey, undefined);
     if (nonMemoryScope === StorageScope.Disk) {
       if (coalesceDiskWrites || diskWritesAsync) {
         scheduleDiskWrite(storageKey, undefined);
+        emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "native");
         return;
       }
       clearPendingDiskWrite(storageKey);
     }
     if (coalesceSecureWrites) {
       scheduleSecureWrite(storageKey, undefined, secureAccessControl ?? secureDefaultAccessControl);
+      emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "native");
       return;
     }
     if (nonMemoryScope === StorageScope.Secure) {
       clearPendingSecureWrite(storageKey);
     }
     getStorageModule().remove(storageKey, config.scope);
+    emitKeyChange(config.scope, storageKey, oldValue, undefined, "remove", "native");
   };
   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);
@@ -976,11 +1139,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();
@@ -1017,6 +1182,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,
@@ -1025,6 +1206,7 @@ export function createStorageItem(config) {
     delete: deleteItem,
     has: hasItem,
     subscribe,
+    subscribeSelector,
     serialize,
     deserialize,
     _triggerListeners: () => {
@@ -1128,6 +1310,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(({
@@ -1140,6 +1326,7 @@ export function setBatch(items, scope) {
       items.forEach(({
         item
       }) => notifyKeyListeners(memoryListeners, item.key));
+      emitBatchChange(scope, "setBatch", "memory", changes);
       return;
     }
     if (scope === StorageScope.Secure) {
@@ -1163,6 +1350,10 @@ export function setBatch(items, scope) {
       }
       flushSecureWrites();
       const storageModule = getStorageModule();
+      const keys = secureEntries.map(({
+        item
+      }) => item.key);
+      const oldValues = hasStorageChangeObservers(scope) ? storageModule.getBatch(keys, scope) ?? [] : [];
       const groupedByAccessControl = new Map();
       secureEntries.forEach(({
         item,
@@ -1186,6 +1377,10 @@ export function setBatch(items, scope) {
         storageModule.setBatch(group.keys, group.values, scope);
         group.keys.forEach((key, index) => cacheRawValue(scope, key, group.values[index]));
       });
+      emitBatchChange(scope, "setBatch", "native", secureEntries.map(({
+        item,
+        value
+      }, index) => createKeyChange(scope, item.key, oldValues[index], item.serialize(value), "setBatch", "native")));
       return;
     }
     flushDiskWrites();
@@ -1201,15 +1396,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) ? getStorageModule().getBatch(keys, scope) ?? [] : [];
     getStorageModule().setBatch(keys, values, scope);
     keys.forEach((key, index) => cacheRawValue(scope, key, values[index]));
+    emitBatchChange(scope, "setBatch", "native", keys.map((key, index) => createKeyChange(scope, key, oldValues[index], values[index], "setBatch", "native")));
   }, 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);
@@ -1219,8 +1418,10 @@ export function removeBatch(items, scope) {
     if (scope === StorageScope.Secure) {
       flushSecureWrites();
     }
+    const oldValues = hasStorageChangeObservers(scope) ? getStorageModule().getBatch(keys, scope) ?? [] : [];
     getStorageModule().removeBatch(keys, scope);
     keys.forEach(key => cacheRawValue(scope, key, undefined));
+    emitBatchChange(scope, "removeBatch", "native", keys.map((key, index) => createKeyChange(scope, key, oldValues[index], undefined, "removeBatch", "native")));
   }, items.length);
 }
 export function registerMigration(version, migration) {