react-native-nitro-storage 0.4.5 → 0.5.1

package/src/index.ts

@@ -21,18 +21,39 @@ import type {
 import {
   getStorageErrorCode,
   isLockedStorageErrorCode,
+  type SecureStorageMetadata,
+  type SecurityCapabilities,
   type StorageCapabilities,
   type StorageErrorCode,
 } from "./storage-runtime";
+import {
+  StorageEventRegistry,
+  type StorageBatchChangeEvent,
+  type StorageChangeEvent,
+  type StorageChangeOperation,
+  type StorageChangeSource,
+  type StorageEventListener,
+  type StorageKeyChangeEvent,
+} from "./storage-events";
 
 export { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 export type { Storage } from "./Storage.nitro";
 export { migrateFromMMKV } from "./migration";
 export {
   getStorageErrorCode,
+  type SecureStorageMetadata,
+  type SecurityCapabilities,
   type StorageCapabilities,
   type StorageErrorCode,
 } from "./storage-runtime";
+export type {
+  StorageBatchChangeEvent,
+  StorageChangeEvent,
+  StorageChangeOperation,
+  StorageChangeSource,
+  StorageEventListener,
+  StorageKeyChangeEvent,
+} from "./storage-events";
 export type {
   WebStorageBackend,
   WebStorageChangeEvent,
@@ -61,6 +82,14 @@ export type StorageMetricSummary = {
   avgDurationMs: number;
   maxDurationMs: number;
 };
+export type StorageSelectorListener<TSelected> = (
+  value: TSelected,
+  previousValue: TSelected,
+) => void;
+export type StorageSelectorSubscribeOptions<TSelected> = {
+  isEqual?: (previousValue: TSelected, nextValue: TSelected) => boolean;
+  fireImmediately?: boolean;
+};
 export type MigrationContext = {
   scope: StorageScope;
   getRaw: (key: string) => string | undefined;
@@ -157,11 +186,18 @@ let diskWritesAsync = false;
 const pendingSecureWrites = new Map<string, PendingSecureWrite>();
 let secureFlushScheduled = false;
 let secureDefaultAccessControl: AccessControl = AccessControl.WhenUnlocked;
+const suppressedNativeEvents = new Map<NonMemoryScope, Map<string, number>>([
+  [StorageScope.Disk, new Map()],
+  [StorageScope.Secure, new Map()],
+]);
 let metricsObserver: StorageMetricsObserver | undefined;
+let eventObserver: StorageEventListener | undefined;
 const metricsCounters = new Map<
   string,
   { count: number; totalDurationMs: number; maxDurationMs: number }
 >();
+const storageEvents = new StorageEventRegistry();
+const nativeSecureBackend = "platform-secure-storage";
 
 function recordMetric(
   operation: string,
@@ -240,6 +276,28 @@ function clearScopeRawCache(scope: NonMemoryScope): void {
   getScopeRawCache(scope).clear();
 }
 
+function suppressNativeEvent(scope: NonMemoryScope, key: string): void {
+  const suppressedEvents = suppressedNativeEvents.get(scope)!;
+  suppressedEvents.set(key, (suppressedEvents.get(key) ?? 0) + 1);
+}
+
+function consumeSuppressedNativeEvent(
+  scope: NonMemoryScope,
+  key: string,
+): boolean {
+  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: KeyListenerRegistry, key: string): void {
   const listeners = registry.get(key);
   if (listeners) {
@@ -281,6 +339,99 @@ function addKeyListener(
   };
 }
 
+function getEventRawValue(
+  scope: StorageScope,
+  key: string,
+): string | undefined {
+  if (scope === StorageScope.Memory) {
+    const value = memoryStore.get(key);
+    return typeof value === "string" ? value : undefined;
+  }
+
+  return getRawValue(key, scope);
+}
+
+function createKeyChange(
+  scope: StorageScope,
+  key: string,
+  oldValue: string | undefined,
+  newValue: string | undefined,
+  operation: StorageChangeOperation,
+  source: StorageChangeSource,
+): StorageKeyChangeEvent {
+  return {
+    type: "key",
+    scope,
+    key,
+    oldValue,
+    newValue,
+    operation,
+    source,
+  };
+}
+
+function hasStorageChangeObservers(scope: StorageScope): boolean {
+  return storageEvents.hasListeners(scope) || eventObserver !== undefined;
+}
+
+function emitKeyChange(
+  scope: StorageScope,
+  key: string,
+  oldValue: string | undefined,
+  newValue: string | undefined,
+  operation: StorageChangeOperation,
+  source: StorageChangeSource,
+): void {
+  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: StorageScope,
+  operation: StorageChangeOperation,
+  source: StorageChangeSource,
+  changes: StorageKeyChangeEvent[],
+): void {
+  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: StorageBatchChangeEvent = {
+    type: "batch",
+    scope,
+    operation,
+    source,
+    changes,
+  };
+  storageEvents.emitBatch(event);
+  eventObserver?.(event);
+}
+
 function readPendingSecureWrite(key: string): string | undefined {
   return pendingSecureWrites.get(key)?.value;
 }
@@ -433,15 +584,27 @@ function ensureNativeScopeSubscription(scope: NonMemoryScope): void {
       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: NonMemoryScope): void {
   const listeners = getScopedListeners(scope);
-  if (listeners.size > 0) {
+  if (
+    listeners.size > 0 ||
+    storageEvents.hasListeners(scope) ||
+    eventObserver !== undefined
+  ) {
     return;
   }
 
@@ -474,9 +637,12 @@ function getRawValue(key: string, scope: StorageScope): string | undefined {
 
 function setRawValue(key: string, value: string, scope: StorageScope): void {
   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;
   }
 
@@ -484,6 +650,7 @@ function setRawValue(key: string, value: string, scope: StorageScope): void {
     cacheRawValue(scope, key, value);
     if (diskWritesAsync) {
       scheduleDiskWrite(key, value);
+      emitKeyChange(scope, key, oldValue, value, "set", "native");
       return;
     }
 
@@ -499,13 +666,16 @@ function setRawValue(key: string, value: string, scope: StorageScope): void {
 
   getStorageModule().set(key, value, scope);
   cacheRawValue(scope, key, value);
+  emitKeyChange(scope, key, oldValue, value, "set", "native");
 }
 
 function removeRawValue(key: string, scope: StorageScope): void {
   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;
   }
 
@@ -513,6 +683,7 @@ function removeRawValue(key: string, scope: StorageScope): void {
     cacheRawValue(scope, key, undefined);
     if (diskWritesAsync) {
       scheduleDiskWrite(key, undefined);
+      emitKeyChange(scope, key, oldValue, undefined, "remove", "native");
       return;
     }
 
@@ -527,6 +698,7 @@ function removeRawValue(key: string, scope: StorageScope): void {
 
   getStorageModule().remove(key, scope);
   cacheRawValue(scope, key, undefined);
+  emitKeyChange(scope, key, oldValue, undefined, "remove", "native");
 }
 
 function readMigrationVersion(scope: StorageScope): number {
@@ -544,11 +716,97 @@ function writeMigrationVersion(scope: StorageScope, version: number): void {
 }
 
 export const storage = {
+  subscribe: (
+    scope: StorageScope,
+    listener: StorageEventListener,
+  ): (() => void) => {
+    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: StorageScope,
+    key: string,
+    listener: StorageEventListener,
+  ): (() => void) => {
+    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: StorageScope,
+    prefix: string,
+    listener: StorageEventListener,
+  ): (() => void) => {
+    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: string,
+    scope: StorageScope,
+    listener: StorageEventListener,
+  ): (() => void) => {
+    return storage.subscribePrefix(scope, prefixKey(namespace, ""), listener);
+  },
+  setEventObserver: (observer?: StorageEventListener) => {
+    eventObserver = observer;
+    if (observer) {
+      ensureNativeScopeSubscription(StorageScope.Disk);
+      ensureNativeScopeSubscription(StorageScope.Secure);
+      return;
+    }
+    maybeCleanupNativeScopeSubscription(StorageScope.Disk);
+    maybeCleanupNativeScopeSubscription(StorageScope.Secure);
+  },
   clear: (scope: StorageScope) => {
     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;
       }
 
@@ -564,6 +822,21 @@ 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: () => {
@@ -582,16 +855,44 @@ 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();
       }
@@ -606,6 +907,21 @@ 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: () => {
@@ -657,7 +973,7 @@ export const storage = {
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
-      return getStorageModule().getKeysByPrefix(prefix, scope);
+      return getStorageModule().getKeysByPrefix(prefix, scope) ?? [];
     });
   },
   getByPrefix: (
@@ -687,7 +1003,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) {
@@ -702,9 +1018,10 @@ export const storage = {
       assertValidScope(scope);
       const result: Record<string, string> = {};
       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) {
@@ -713,9 +1030,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;
@@ -723,6 +1040,11 @@ export const storage = {
       return result;
     });
   },
+  export: (scope: StorageScope): Record<string, string> => {
+    return measureOperation("storage:export", scope, () =>
+      storage.getAll(scope),
+    );
+  },
   size: (scope: StorageScope): number => {
     return measureOperation("storage:size", scope, () => {
       assertValidScope(scope);
@@ -803,7 +1125,7 @@ export const storage = {
     platform: "native",
     backend: {
       disk: "platform-preferences",
-      secure: "platform-secure-storage",
+      secure: nativeSecureBackend,
     },
     writeBuffering: {
       disk: true,
@@ -811,6 +1133,67 @@ export const storage = {
     },
     errorClassification: true,
   }),
+  getSecurityCapabilities: (): SecurityCapabilities => ({
+    platform: "native",
+    secureStorage: {
+      backend: nativeSecureBackend,
+      encrypted: "available",
+      accessControl: "unknown",
+      keychainAccessGroup: "unknown",
+      hardwareBacked: "unknown",
+    },
+    biometric: {
+      storage: "unknown",
+      prompt: "unknown",
+      biometryOnly: "unknown",
+      biometryOrPasscode: "unknown",
+    },
+    metadata: {
+      perKey: true,
+      listsWithoutValues: true,
+      persistsTimestamps: false,
+    },
+  }),
+  getSecureMetadata: (key: string): SecureStorageMetadata => {
+    return measureOperation(
+      "storage:getSecureMetadata",
+      StorageScope.Secure,
+      () => {
+        flushSecureWrites();
+        const storageModule = getStorageModule();
+        const biometricProtected = storageModule.hasSecureBiometric(key);
+        const exists =
+          biometricProtected || storageModule.has(key, StorageScope.Secure);
+        let kind: SecureStorageMetadata["kind"] = "missing";
+        if (exists) {
+          kind = biometricProtected ? "biometric" : "secure";
+        }
+
+        return {
+          key,
+          exists,
+          kind,
+          backend: nativeSecureBackend,
+          encrypted: "available",
+          hardwareBacked: "unknown",
+          biometricProtected,
+          valueExposed: false,
+        };
+      },
+    );
+  },
+  getAllSecureMetadata: (): SecureStorageMetadata[] => {
+    return measureOperation(
+      "storage:getAllSecureMetadata",
+      StorageScope.Secure,
+      () => {
+        flushSecureWrites();
+        return getStorageModule()
+          .getAllKeys(StorageScope.Secure)
+          .map((key) => storage.getSecureMetadata(key));
+      },
+    );
+  },
   getString: (key: string, scope: StorageScope): string | undefined => {
     return measureOperation("storage:getString", scope, () => {
       return getRawValue(key, scope);
@@ -835,12 +1218,23 @@ 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;
         }
 
@@ -851,6 +1245,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,
     );
@@ -913,6 +1308,11 @@ export interface StorageItem<T> {
   delete: () => void;
   has: () => boolean;
   subscribe: (callback: () => void) => () => void;
+  subscribeSelector: <TSelected>(
+    selector: (value: T) => TSelected,
+    listener: StorageSelectorListener<TSelected>,
+    options?: StorageSelectorSubscribeOptions<TSelected>,
+  ) => () => void;
   serialize: (value: T) => string;
   deserialize: (value: string) => T;
   scope: StorageScope;
@@ -1081,12 +1481,21 @@ export function createStorageItem<T = undefined>(
   };
 
   const writeStoredRaw = (rawValue: string): void => {
+    const oldValue = undefined;
     if (isBiometric) {
       getStorageModule().setSecureBiometricWithLevel(
         storageKey,
         rawValue,
         resolvedBiometricLevel,
       );
+      emitKeyChange(
+        config.scope,
+        storageKey,
+        oldValue,
+        rawValue,
+        "set",
+        "native",
+      );
       return;
     }
 
@@ -1095,6 +1504,14 @@ export function createStorageItem<T = undefined>(
     if (nonMemoryScope === StorageScope.Disk) {
       if (coalesceDiskWrites || diskWritesAsync) {
         scheduleDiskWrite(storageKey, rawValue);
+        emitKeyChange(
+          config.scope,
+          storageKey,
+          oldValue,
+          rawValue,
+          "set",
+          "native",
+        );
         return;
       }
 
@@ -1107,6 +1524,14 @@ export function createStorageItem<T = undefined>(
         rawValue,
         secureAccessControl ?? secureDefaultAccessControl,
       );
+      emitKeyChange(
+        config.scope,
+        storageKey,
+        oldValue,
+        rawValue,
+        "set",
+        "native",
+      );
       return;
     }
 
@@ -1118,11 +1543,28 @@ export function createStorageItem<T = undefined>(
     }
 
     getStorageModule().set(storageKey, rawValue, config.scope);
+    emitKeyChange(
+      config.scope,
+      storageKey,
+      oldValue,
+      rawValue,
+      "set",
+      "native",
+    );
   };
 
   const removeStoredRaw = (): void => {
+    const oldValue = getEventRawValue(config.scope, storageKey);
     if (isBiometric) {
       getStorageModule().deleteSecureBiometric(storageKey);
+      emitKeyChange(
+        config.scope,
+        storageKey,
+        oldValue,
+        undefined,
+        "remove",
+        "native",
+      );
       return;
     }
 
@@ -1131,6 +1573,14 @@ export function createStorageItem<T = undefined>(
     if (nonMemoryScope === StorageScope.Disk) {
       if (coalesceDiskWrites || diskWritesAsync) {
         scheduleDiskWrite(storageKey, undefined);
+        emitKeyChange(
+          config.scope,
+          storageKey,
+          oldValue,
+          undefined,
+          "remove",
+          "native",
+        );
         return;
       }
 
@@ -1143,6 +1593,14 @@ export function createStorageItem<T = undefined>(
         undefined,
         secureAccessControl ?? secureDefaultAccessControl,
       );
+      emitKeyChange(
+        config.scope,
+        storageKey,
+        oldValue,
+        undefined,
+        "remove",
+        "native",
+      );
       return;
     }
 
@@ -1151,15 +1609,32 @@ export function createStorageItem<T = undefined>(
     }
 
     getStorageModule().remove(storageKey, config.scope);
+    emitKeyChange(
+      config.scope,
+      storageKey,
+      oldValue,
+      undefined,
+      "remove",
+      "native",
+    );
   };
 
   const writeValueWithoutValidation = (value: T): void => {
     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;
     }
 
@@ -1331,11 +1806,20 @@ export function createStorageItem<T = undefined>(
       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;
       }
 
@@ -1377,6 +1861,30 @@ export function createStorageItem<T = undefined>(
     };
   };
 
+  const subscribeSelector = <TSelected>(
+    selector: (value: T) => TSelected,
+    listener: StorageSelectorListener<TSelected>,
+    options: StorageSelectorSubscribeOptions<TSelected> = {},
+  ): (() => void) => {
+    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: StorageItemInternal<T> = {
     get,
     getWithVersion,
@@ -1385,6 +1893,7 @@ export function createStorageItem<T = undefined>(
     delete: deleteItem,
     has: hasItem,
     subscribe,
+    subscribeSelector,
     serialize,
     deserialize,
     _triggerListeners: () => {
@@ -1541,6 +2050,17 @@ export function setBatch<T>(
           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(({ item, value }) => {
           memoryStore.set(item.key, value);
@@ -1549,6 +2069,7 @@ export function setBatch<T>(
         items.forEach(({ item }) =>
           notifyKeyListeners(memoryListeners, item.key),
         );
+        emitBatchChange(scope, "setBatch", "memory", changes);
         return;
       }
 
@@ -1568,6 +2089,10 @@ export function setBatch<T>(
 
         flushSecureWrites();
         const storageModule = getStorageModule();
+        const keys = secureEntries.map(({ item }) => item.key);
+        const oldValues = hasStorageChangeObservers(scope)
+          ? (storageModule.getBatch(keys, scope) ?? [])
+          : [];
         const groupedByAccessControl = new Map<
           number,
           { keys: string[]; values: string[] }
@@ -1592,6 +2117,21 @@ export function setBatch<T>(
             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;
       }
 
@@ -1607,9 +2147,27 @@ export function setBatch<T>(
 
       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,
   );
@@ -1626,7 +2184,18 @@ export function removeBatch(
       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;
       }
 
@@ -1637,8 +2206,26 @@ export function removeBatch(
       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,
   );