@buoy-gg/storage 3.0.2 → 4.0.1

package/lib/commonjs/storage/utils/AsyncStorageListener.js

@@ -4,10 +4,11 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.stopListening = exports.startListening = exports.resumeCapture = exports.removeAllListeners = exports.pauseCapture = exports.isPaused = exports.isListening = exports.getListenerCount = exports.default = exports.addListener = void 0;
-var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _asyncStorageCompat = require("./asyncStorageCompat");
 // AsyncStorage method signatures - matching the actual AsyncStorage API
 
+// v3-only batch methods (replace multiSet/multiRemove)
+
 // Event types for AsyncStorage operations
 
 /**
@@ -18,6 +19,12 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  * and emits events to registered listeners. It maintains the original functionality
  * while providing observability for debugging and development tools.
  *
+ * Supports both async-storage v2 (multiGet/multiSet/multiRemove/mergeItem) and
+ * v3 (getMany/setMany/removeMany, no merge). On v3 the renamed batch methods are
+ * swizzled and normalized back to the same v2-shaped events, so the rest of the
+ * tool — event store, time-travel, desktop sync — is version-agnostic. v3 dropped
+ * the merge API entirely, so no merge events can occur there.
+ *
  * @example
  * ```typescript
  * // Start listening to all AsyncStorage operations
@@ -58,9 +65,13 @@ class AsyncStorageListener {
   originalRemoveItem = null;
   originalMergeItem = null;
   originalClear = null;
+  // v2 batch originals
   originalMultiSet = null;
   originalMultiRemove = null;
   originalMultiMerge = null;
+  // v3 batch originals
+  originalSetMany = null;
+  originalRemoveMany = null;
 
   /**
    * Determines if a storage key should be ignored to prevent infinite loops
@@ -99,19 +110,27 @@ class AsyncStorageListener {
     }
 
     // Check if methods are already swizzled by checking the function name
-    if (_asyncStorage.default.setItem.name === "swizzled_setItem") {
+    if (_asyncStorageCompat.asyncStorage.setItem.name === "swizzled_setItem") {
       // Don't store swizzled methods as originals
       return false;
     }
 
-    // Store original methods (these should be the real AsyncStorage methods)
-    this.originalSetItem = _asyncStorage.default.setItem.bind(_asyncStorage.default);
-    this.originalRemoveItem = _asyncStorage.default.removeItem.bind(_asyncStorage.default);
-    this.originalMergeItem = _asyncStorage.default.mergeItem.bind(_asyncStorage.default);
-    this.originalClear = _asyncStorage.default.clear.bind(_asyncStorage.default);
-    this.originalMultiSet = _asyncStorage.default.multiSet.bind(_asyncStorage.default);
-    this.originalMultiRemove = _asyncStorage.default.multiRemove.bind(_asyncStorage.default);
-    this.originalMultiMerge = _asyncStorage.default.multiMerge ? _asyncStorage.default.multiMerge.bind(_asyncStorage.default) : null;
+    // Store original methods (these should be the real AsyncStorage methods).
+    // Single-item + clear are identical across v2/v3.
+    this.originalSetItem = _asyncStorageCompat.asyncStorage.setItem.bind(_asyncStorageCompat.asyncStorage);
+    this.originalRemoveItem = _asyncStorageCompat.asyncStorage.removeItem.bind(_asyncStorageCompat.asyncStorage);
+    this.originalClear = _asyncStorageCompat.asyncStorage.clear.bind(_asyncStorageCompat.asyncStorage);
+    if (_asyncStorageCompat.asyncStorageCaps.hasLegacyMultiApi) {
+      // v2: multiSet/multiRemove + merge API
+      this.originalMultiSet = _asyncStorageCompat.asyncStorage.multiSet.bind(_asyncStorageCompat.asyncStorage);
+      this.originalMultiRemove = _asyncStorageCompat.asyncStorage.multiRemove.bind(_asyncStorageCompat.asyncStorage);
+      this.originalMergeItem = _asyncStorageCompat.asyncStorage.mergeItem.bind(_asyncStorageCompat.asyncStorage);
+      this.originalMultiMerge = _asyncStorageCompat.asyncStorage.multiMerge ? _asyncStorageCompat.asyncStorage.multiMerge.bind(_asyncStorageCompat.asyncStorage) : null;
+    } else {
+      // v3: setMany/removeMany; merge API was removed (nothing to capture)
+      this.originalSetMany = _asyncStorageCompat.asyncStorage.setMany.bind(_asyncStorageCompat.asyncStorage);
+      this.originalRemoveMany = _asyncStorageCompat.asyncStorage.removeMany.bind(_asyncStorageCompat.asyncStorage);
+    }
 
     // Original methods stored successfully
     this.isInitialized = true;
@@ -125,27 +144,35 @@ class AsyncStorageListener {
    * AsyncStorage methods that were saved during initialization.
    */
   restoreOriginalMethods() {
-    if (!_asyncStorage.default || !this.originalSetItem) {
+    if (!_asyncStorageCompat.asyncStorage || !this.originalSetItem) {
       return;
     }
-    _asyncStorage.default.setItem = this.originalSetItem;
+    _asyncStorageCompat.asyncStorage.setItem = this.originalSetItem;
     if (this.originalRemoveItem) {
-      _asyncStorage.default.removeItem = this.originalRemoveItem;
-    }
-    if (this.originalMergeItem) {
-      _asyncStorage.default.mergeItem = this.originalMergeItem;
+      _asyncStorageCompat.asyncStorage.removeItem = this.originalRemoveItem;
     }
     if (this.originalClear) {
-      _asyncStorage.default.clear = this.originalClear;
+      _asyncStorageCompat.asyncStorage.clear = this.originalClear;
+    }
+    // v2 batch + merge
+    if (this.originalMergeItem) {
+      _asyncStorageCompat.asyncStorage.mergeItem = this.originalMergeItem;
     }
     if (this.originalMultiSet) {
-      _asyncStorage.default.multiSet = this.originalMultiSet;
+      _asyncStorageCompat.asyncStorage.multiSet = this.originalMultiSet;
     }
     if (this.originalMultiRemove) {
-      _asyncStorage.default.multiRemove = this.originalMultiRemove;
+      _asyncStorageCompat.asyncStorage.multiRemove = this.originalMultiRemove;
     }
     if (this.originalMultiMerge) {
-      _asyncStorage.default.multiMerge = this.originalMultiMerge;
+      _asyncStorageCompat.asyncStorage.multiMerge = this.originalMultiMerge;
+    }
+    // v3 batch
+    if (this.originalSetMany) {
+      _asyncStorageCompat.asyncStorage.setMany = this.originalSetMany;
+    }
+    if (this.originalRemoveMany) {
+      _asyncStorageCompat.asyncStorage.removeMany = this.originalRemoveMany;
     }
   }
 
@@ -175,6 +202,77 @@ class AsyncStorageListener {
     });
   }
 
+  /**
+   * Shared core for batch writes (v2 multiSet/multiMerge, v3 setMany).
+   *
+   * Captures previous values for the affected keys, runs the original native
+   * operation, and emits a normalized event. `action` distinguishes a plain set
+   * from a merge so time-travel can replay them differently.
+   */
+  async handleBatchSet(pairs, runOriginal, action = "multiSet") {
+    // Filter out ignored keys
+    const filteredPairs = pairs.filter(([key]) => !this.shouldIgnoreKey(key));
+    if (filteredPairs.length === 0) {
+      return runOriginal();
+    }
+
+    // Capture previous values for all keys being written
+    const keysToSet = filteredPairs.map(([key]) => key);
+    let prevPairs = [];
+    try {
+      prevPairs = await (0, _asyncStorageCompat.readMany)(keysToSet);
+    } catch {
+      // Failed to capture previous values
+    }
+
+    // Execute the operation
+    const result = await runOriginal();
+
+    // Emit event with previous values
+    this.emit({
+      action,
+      timestamp: new Date(),
+      data: {
+        pairs: filteredPairs,
+        prevPairs
+      }
+    });
+    return result;
+  }
+
+  /**
+   * Shared core for batch removals (v2 multiRemove, v3 removeMany).
+   */
+  async handleBatchRemove(keys, runOriginal) {
+    // Filter out ignored keys
+    const filteredKeys = keys.filter(key => !this.shouldIgnoreKey(key));
+    if (filteredKeys.length === 0) {
+      return runOriginal();
+    }
+
+    // Capture previous values for all keys being removed
+    let prevPairs = [];
+    try {
+      prevPairs = await (0, _asyncStorageCompat.readMany)(filteredKeys);
+    } catch {
+      // Failed to capture previous values
+    }
+
+    // Execute the operation
+    const result = await runOriginal();
+
+    // Emit event with previous values
+    this.emit({
+      action: "multiRemove",
+      timestamp: new Date(),
+      data: {
+        keys: filteredKeys,
+        prevPairs
+      }
+    });
+    return result;
+  }
+
   /**
    * Start intercepting AsyncStorage operations by swizzling methods
    *
@@ -196,7 +294,7 @@ class AsyncStorageListener {
     }
 
     // Check if methods are already swizzled (this can happen if initialize was called twice somehow)
-    if (_asyncStorage.default && _asyncStorage.default.setItem.name === "swizzled_setItem") {
+    if (_asyncStorageCompat.asyncStorage && _asyncStorageCompat.asyncStorage.setItem.name === "swizzled_setItem") {
       this.restoreOriginalMethods();
     }
 
@@ -207,7 +305,7 @@ class AsyncStorageListener {
       // Only capture and emit if key is not ignored
       if (!this.shouldIgnoreKey(key)) {
         // Capture previous value before the operation
-        const prevValue = this.originalSetItem ? await _asyncStorage.default.getItem(key) : null;
+        const prevValue = this.originalSetItem ? await _asyncStorageCompat.asyncStorage.getItem(key) : null;
 
         // Execute the operation
         const result = this.originalSetItem ? await this.originalSetItem(key, value) : undefined;
@@ -229,17 +327,17 @@ class AsyncStorageListener {
     Object.defineProperty(swizzled_setItem, "name", {
       value: "swizzled_setItem"
     });
-    if (_asyncStorage.default) {
-      _asyncStorage.default.setItem = swizzled_setItem;
+    if (_asyncStorageCompat.asyncStorage) {
+      _asyncStorageCompat.asyncStorage.setItem = swizzled_setItem;
     }
 
     // Swizzle removeItem
-    if (_asyncStorage.default) {
-      _asyncStorage.default.removeItem = async key => {
+    if (_asyncStorageCompat.asyncStorage) {
+      _asyncStorageCompat.asyncStorage.removeItem = async key => {
         // Only capture and emit if key is not ignored
         if (!this.shouldIgnoreKey(key)) {
           // Capture previous value before the operation
-          const prevValue = this.originalRemoveItem ? await _asyncStorage.default.getItem(key) : null;
+          const prevValue = this.originalRemoveItem ? await _asyncStorageCompat.asyncStorage.getItem(key) : null;
 
           // Execute the operation
           const result = this.originalRemoveItem ? await this.originalRemoveItem(key) : undefined;
@@ -259,13 +357,13 @@ class AsyncStorageListener {
       };
     }
 
-    // Swizzle mergeItem
-    if (_asyncStorage.default) {
-      _asyncStorage.default.mergeItem = async (key, value) => {
+    // Swizzle mergeItem (v2 only — v3 removed the merge API)
+    if (_asyncStorageCompat.asyncStorageCaps.hasMergeApi && _asyncStorageCompat.asyncStorage) {
+      _asyncStorageCompat.asyncStorage.mergeItem = async (key, value) => {
         // Only capture and emit if key is not ignored
         if (!this.shouldIgnoreKey(key)) {
           // Capture previous value before the operation
-          const prevValue = this.originalMergeItem ? await _asyncStorage.default.getItem(key) : null;
+          const prevValue = this.originalMergeItem ? await _asyncStorageCompat.asyncStorage.getItem(key) : null;
 
           // Execute the operation
           const result = this.originalMergeItem ? await this.originalMergeItem(key, value) : undefined;
@@ -287,17 +385,16 @@ class AsyncStorageListener {
     }
 
     // Swizzle clear
-    if (_asyncStorage.default) {
-      _asyncStorage.default.clear = async () => {
+    if (_asyncStorageCompat.asyncStorage) {
+      _asyncStorageCompat.asyncStorage.clear = async () => {
         // Capture all key-value pairs before clearing
         let prevPairs = [];
         try {
-          const allKeys = await _asyncStorage.default.getAllKeys();
+          const allKeys = await _asyncStorageCompat.asyncStorage.getAllKeys();
           // Filter out ignored keys
           const keysToCapture = allKeys.filter(key => !this.shouldIgnoreKey(key));
           if (keysToCapture.length > 0) {
-            const keyValuePairs = await _asyncStorage.default.multiGet(keysToCapture);
-            prevPairs = keyValuePairs;
+            prevPairs = await (0, _asyncStorageCompat.readMany)(keysToCapture);
           }
         } catch {
           // Failed to capture previous state
@@ -318,105 +415,18 @@ class AsyncStorageListener {
       };
     }
 
-    // Swizzle multiSet
-    if (_asyncStorage.default) {
-      _asyncStorage.default.multiSet = async keyValuePairs => {
-        // Filter out ignored keys
-        const filteredPairs = keyValuePairs.filter(([key]) => !this.shouldIgnoreKey(key));
-        if (filteredPairs.length > 0) {
-          // Capture previous values for all keys being set
-          const keysToSet = filteredPairs.map(([key]) => key);
-          let prevPairs = [];
-          try {
-            const existingValues = await _asyncStorage.default.multiGet(keysToSet);
-            prevPairs = existingValues;
-          } catch {
-            // Failed to capture previous values
-          }
-
-          // Execute the operation
-          const result = this.originalMultiSet ? await this.originalMultiSet(keyValuePairs) : undefined;
-
-          // Emit event with previous values
-          this.emit({
-            action: "multiSet",
-            timestamp: new Date(),
-            data: {
-              pairs: filteredPairs,
-              prevPairs
-            }
-          });
-          return result;
-        }
-        return this.originalMultiSet ? this.originalMultiSet(keyValuePairs) : Promise.resolve();
-      };
-    }
-
-    // Swizzle multiRemove
-    if (_asyncStorage.default) {
-      _asyncStorage.default.multiRemove = async keys => {
-        // Filter out ignored keys
-        const filteredKeys = keys.filter(key => !this.shouldIgnoreKey(key));
-        if (filteredKeys.length > 0) {
-          // Capture previous values for all keys being removed
-          let prevPairs = [];
-          try {
-            const existingValues = await _asyncStorage.default.multiGet(filteredKeys);
-            prevPairs = existingValues;
-          } catch {
-            // Failed to capture previous values
-          }
-
-          // Execute the operation
-          const result = this.originalMultiRemove ? await this.originalMultiRemove(keys) : undefined;
-
-          // Emit event with previous values
-          this.emit({
-            action: "multiRemove",
-            timestamp: new Date(),
-            data: {
-              keys: filteredKeys,
-              prevPairs
-            }
-          });
-          return result;
-        }
-        return this.originalMultiRemove ? this.originalMultiRemove(keys) : Promise.resolve();
-      };
-    }
-
-    // Swizzle multiMerge if available
-    if (this.originalMultiMerge && _asyncStorage.default) {
-      _asyncStorage.default.multiMerge = async keyValuePairs => {
-        // Filter out ignored keys
-        const filteredPairs = keyValuePairs.filter(([key]) => !this.shouldIgnoreKey(key));
-        if (filteredPairs.length > 0) {
-          // Capture previous values for all keys being merged
-          const keysToMerge = filteredPairs.map(([key]) => key);
-          let prevPairs = [];
-          try {
-            const existingValues = await _asyncStorage.default.multiGet(keysToMerge);
-            prevPairs = existingValues;
-          } catch {
-            // Failed to capture previous values
-          }
-
-          // Execute the operation
-          const result = this.originalMultiMerge ? await this.originalMultiMerge(keyValuePairs) : undefined;
-
-          // Emit event with previous values
-          this.emit({
-            action: "multiMerge",
-            timestamp: new Date(),
-            data: {
-              pairs: filteredPairs,
-              prevPairs
-            }
-          });
-          return result;
-        }
-        return this.originalMultiMerge ? this.originalMultiMerge(keyValuePairs) : Promise.resolve();
-      };
+    // Swizzle the batch methods for whichever API the installed version exposes.
+    if (_asyncStorageCompat.asyncStorageCaps.hasLegacyMultiApi && _asyncStorageCompat.asyncStorage) {
+      // ── v2: multiSet / multiRemove / multiMerge ──
+      _asyncStorageCompat.asyncStorage.multiSet = keyValuePairs => this.handleBatchSet(keyValuePairs, () => this.originalMultiSet ? this.originalMultiSet(keyValuePairs) : Promise.resolve());
+      _asyncStorageCompat.asyncStorage.multiRemove = keys => this.handleBatchRemove(keys, () => this.originalMultiRemove ? this.originalMultiRemove(keys) : Promise.resolve());
+      if (this.originalMultiMerge) {
+        _asyncStorageCompat.asyncStorage.multiMerge = keyValuePairs => this.handleBatchSet(keyValuePairs, () => this.originalMultiMerge ? this.originalMultiMerge(keyValuePairs) : Promise.resolve(), "multiMerge");
+      }
+    } else if (_asyncStorageCompat.asyncStorage) {
+      // ── v3: setMany / removeMany (normalized back to multiSet/multiRemove events) ──
+      _asyncStorageCompat.asyncStorage.setMany = entries => this.handleBatchSet(Object.entries(entries), () => this.originalSetMany ? this.originalSetMany(entries) : Promise.resolve());
+      _asyncStorageCompat.asyncStorage.removeMany = keys => this.handleBatchRemove(keys, () => this.originalRemoveMany ? this.originalRemoveMany(keys) : Promise.resolve());
     }
     this.isListening = true;
     // Started listening successfully
@@ -432,34 +442,12 @@ class AsyncStorageListener {
     if (!this.isListening) {
       return;
     }
-    if (!_asyncStorage.default) {
+    if (!_asyncStorageCompat.asyncStorage) {
       return;
     }
 
     // Stopping listener and restoring original methods
-
-    // Restore original methods
-    if (this.originalSetItem) {
-      _asyncStorage.default.setItem = this.originalSetItem;
-    }
-    if (this.originalRemoveItem) {
-      _asyncStorage.default.removeItem = this.originalRemoveItem;
-    }
-    if (this.originalMergeItem) {
-      _asyncStorage.default.mergeItem = this.originalMergeItem;
-    }
-    if (this.originalClear) {
-      _asyncStorage.default.clear = this.originalClear;
-    }
-    if (this.originalMultiSet) {
-      _asyncStorage.default.multiSet = this.originalMultiSet;
-    }
-    if (this.originalMultiRemove) {
-      _asyncStorage.default.multiRemove = this.originalMultiRemove;
-    }
-    if (this.originalMultiMerge) {
-      _asyncStorage.default.multiMerge = this.originalMultiMerge;
-    }
+    this.restoreOriginalMethods();
     this.isListening = false;
     // Stopped listening successfully
   }

package/lib/commonjs/storage/utils/asyncStorageCompat.js

@@ -0,0 +1,89 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.asyncStorageCaps = exports.asyncStorage = void 0;
+exports.readMany = readMany;
+exports.removeMany = removeMany;
+exports.writeMany = writeMany;
+var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * AsyncStorage compatibility adapter (v2 + v3)
+ *
+ * `@react-native-async-storage/async-storage` 3.x reshaped the default-export
+ * API. The single-item methods kept their v2 signatures, but the batch + merge
+ * methods changed:
+ *
+ *   v2 (what this package was written against)   v3
+ *   ------------------------------------------   --------------------------------
+ *   multiGet(keys): [key, value|null][]          getMany(keys): Record<key, value|null>
+ *   multiSet([[k, v]]): void                     setMany({ k: v }): void
+ *   multiRemove(keys): void                      removeMany(keys): void
+ *   mergeItem / multiMerge                       removed entirely
+ *
+ * This module is the single seam between the storage tool and whichever
+ * async-storage version the host app installed. The rest of the package always
+ * speaks the v2 tuple-shaped API; we translate to v3 here when needed.
+ *
+ * Reads (`readMany`) are routed through the *unswizzled* native methods, so the
+ * event listener can safely call them while capturing previous values without
+ * re-triggering itself.
+ */
+
+// Loosely typed because the surface differs across major versions; callers go
+// through the helpers below rather than touching this directly.
+
+/** The live default-export object (methods may be swizzled by the listener). */
+const asyncStorage = exports.asyncStorage = _asyncStorage.default;
+
+/**
+ * Capability flags describing which API surface the installed version exposes.
+ * `multiGet` only exists on v2; `mergeItem` was removed in v3.
+ */
+const asyncStorageCaps = exports.asyncStorageCaps = {
+  /** v2 exposes multiGet/multiSet/multiRemove; v3 renamed these to *Many. */
+  hasLegacyMultiApi: typeof asyncStorage?.multiGet === "function",
+  /** v3 removed mergeItem/multiMerge with no replacement. */
+  hasMergeApi: typeof asyncStorage?.mergeItem === "function"
+};
+
+/**
+ * Batch-read keys, normalized to the v2 `[key, value|null][]` tuple shape and
+ * preserving the requested key order regardless of installed version.
+ */
+async function readMany(keys) {
+  if (typeof asyncStorage.multiGet === "function") {
+    return await asyncStorage.multiGet(keys);
+  }
+  // v3: getMany returns a Record; rebuild ordered tuples ("what you request is
+  // what you get" — missing keys come back as null).
+  const record = await asyncStorage.getMany(keys);
+  return keys.map(key => [key, record[key] ?? null]);
+}
+
+/**
+ * Batch-write key/value pairs. Calls the live method (which may be swizzled by
+ * the listener on v2's `multiSet` / v3's `setMany`) so writes still emit events.
+ */
+async function writeMany(pairs) {
+  if (typeof asyncStorage.multiSet === "function") {
+    return asyncStorage.multiSet(pairs);
+  }
+  const record = {};
+  for (const [key, value] of pairs) record[key] = value;
+  return asyncStorage.setMany(record);
+}
+
+/**
+ * Batch-remove keys via the live method (swizzled on v2's `multiRemove` /
+ * v3's `removeMany`).
+ */
+async function removeMany(keys) {
+  if (typeof asyncStorage.multiRemove === "function") {
+    return asyncStorage.multiRemove(keys);
+  }
+  return asyncStorage.removeMany(keys);
+}
+var _default = exports.default = asyncStorage;

package/lib/commonjs/storage/utils/clearAllStorage.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.clearAllAppStorage = clearAllAppStorage;
 exports.clearAllStorageIncludingDevTools = clearAllStorageIncludingDevTools;
 var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
+var _asyncStorageCompat = require("./asyncStorageCompat");
 var _sharedUi = require("@buoy-gg/shared-ui");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /**
@@ -30,7 +31,7 @@ async function clearAllAppStorage() {
   // Clearing ${keysToRemove.length} app storage keys
 
   // Remove all non-dev-tool keys
-  await _asyncStorage.default.multiRemove(keysToRemove);
+  await (0, _asyncStorageCompat.removeMany)(keysToRemove);
 
   // Successfully cleared app storage
 }

package/lib/commonjs/storage/utils/mmkvTypeDetection.js

@@ -42,16 +42,25 @@ exports.isTypeMatch = isTypeMatch;
  * ```
  */
 function detectMMKVType(instance, key) {
-  // Try string (most common)
+  // MMKV stores no type metadata, so the native getters can cross-read: in
+  // particular `getString` returns "" (an empty string, NOT undefined) for many
+  // non-string values like numbers and `false`. Trying getString first and
+  // trusting its result therefore mis-detects those as empty strings — e.g.
+  // a key set to 42 or false would render as "". Probe the getters and only let
+  // getString win when it returns a NON-empty string; treat an empty result as
+  // ambiguous and prefer the number/boolean getters.
   const stringValue = instance.getString(key);
-  if (stringValue !== undefined) {
+
+  // A non-empty string is unambiguously a string.
+  if (stringValue !== undefined && stringValue !== '') {
     return {
       value: stringValue,
       type: 'string'
     };
   }
 
-  // Try number
+  // Empty getString result is ambiguous (genuine "" vs a number/boolean the
+  // native layer decoded to ""). Prefer typed getters when they have a value.
   const numberValue = instance.getNumber(key);
   if (numberValue !== undefined) {
     return {
@@ -59,8 +68,6 @@ function detectMMKVType(instance, key) {
       type: 'number'
     };
   }
-
-  // Try boolean
   const booleanValue = instance.getBoolean(key);
   if (booleanValue !== undefined) {
     return {
@@ -69,6 +76,14 @@ function detectMMKVType(instance, key) {
     };
   }
 
+  // getString returned "" and nothing else matched -> a genuine empty string.
+  if (stringValue === '') {
+    return {
+      value: '',
+      type: 'string'
+    };
+  }
+
   // Try buffer (least common)
   const bufferValue = instance.getBuffer(key);
   if (bufferValue !== undefined) {

package/lib/commonjs/storage/utils/storageTimeTravelUtils.js

@@ -7,6 +7,7 @@ exports.canUndo = canUndo;
 exports.jumpToState = jumpToState;
 exports.undoOperation = undoOperation;
 var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
+var _asyncStorageCompat = require("./asyncStorageCompat");
 var _AsyncStorageListener = require("./AsyncStorageListener");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /**
@@ -79,7 +80,7 @@ async function undoOperation(event) {
           // Restore all cleared key-value pairs
           const pairsToRestore = data.prevPairs.filter(([, value]) => value !== null);
           if (pairsToRestore.length > 0) {
-            await _asyncStorage.default.multiSet(pairsToRestore);
+            await (0, _asyncStorageCompat.writeMany)(pairsToRestore);
           }
         }
         break;
@@ -131,7 +132,7 @@ async function jumpToState(events, targetEventIndex) {
       }
     }
     if (pairsToSet.length > 0) {
-      await _asyncStorage.default.multiSet(pairsToSet);
+      await (0, _asyncStorageCompat.writeMany)(pairsToSet);
     }
   } finally {
     // Always resume capture

package/lib/commonjs/storage/utils/valueType.js

@@ -3,7 +3,9 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.getValuePreview = getValuePreview;
 exports.getValueTypeLabel = getValueTypeLabel;
+exports.getValueTypeWithPreview = getValueTypeWithPreview;
 /** Return a concise string describing the JavaScript type of the provided value. */
 function getValueTypeLabel(value) {
   if (value === null) return "null";
@@ -15,4 +17,43 @@ function getValueTypeLabel(value) {
   if (type === "number") return "number";
   if (type === "string") return "string";
   return "unknown";
+}
+
+/** Longest value preview rendered inline next to the type label. */
+const MAX_INLINE_PREVIEW = 40;
+
+/**
+ * Short, human-readable preview of a value for inline display next to the type
+ * label, or `null` when the value is too large/complex to preview (long
+ * strings, objects, arrays). Lets the user read simple values without opening
+ * the card.
+ */
+function getValuePreview(value) {
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      return Number.isFinite(value) ? String(value) : null;
+    case "string":
+      {
+        if (value.length === 0) return '""';
+        if (value.length > MAX_INLINE_PREVIEW) return null;
+        // Collapse whitespace so multi-line/tabbed values stay on one line.
+        return `"${value.replace(/\s+/g, " ")}"`;
+      }
+    default:
+      return null;
+    // objects, arrays, null, undefined
+  }
+}
+
+/**
+ * Type label optionally followed by a short value preview — e.g. `boolean · true`,
+ * `number · 42`, `string · "hello"`. Falls back to just the type label when the
+ * value is too large to preview.
+ */
+function getValueTypeWithPreview(value) {
+  const label = getValueTypeLabel(value);
+  const preview = getValuePreview(value);
+  return preview ? `${label} · ${preview}` : label;
 }