react-native-mmkv 4.0.0-beta.0 → 4.0.0-beta.10

package/cpp/{MmkvTypes.h → MMKVTypes.hpp}

@@ -1,5 +1,5 @@
 //
-//  MmkvTypes.h
+//  MMKVTypes.h
 //  react-native-mmkv
 //
 //  Created by Brad Anderson on 10.08.2025.

package/cpp/MMKVValueChangedListenerRegistry.cpp

@@ -0,0 +1,58 @@
+//
+//  MMKVValueChangedListenerRegistry.cpp
+//  react-native-mmkv
+//
+//  Created by Marc Rousavy on 21.08.2025.
+//
+
+#include "MMKVValueChangedListenerRegistry.hpp"
+
+namespace margelo::nitro::mmkv {
+
+// static members
+std::atomic<ListenerID> MMKVValueChangedListenerRegistry::_listenersCounter = 0;
+std::unordered_map<MMKVID, std::vector<ListenerSubscription>> MMKVValueChangedListenerRegistry::_listeners;
+
+ListenerID MMKVValueChangedListenerRegistry::addListener(const std::string& mmkvID,
+                                                         const std::function<void(const std::string& /* key */)>& callback) {
+  // 1. Get (or create) the listeners array for these MMKV instances
+  auto& listeners = _listeners[mmkvID];
+  // 2. Get (and increment) the listener ID counter
+  auto id = _listenersCounter.fetch_add(1);
+  // 3. Add the listener to our array
+  listeners.push_back(ListenerSubscription{
+      .id = id,
+      .callback = callback,
+  });
+  // 4. Return the ID used to unsubscribe later on
+  return id;
+}
+
+void MMKVValueChangedListenerRegistry::removeListener(const std::string& mmkvID, ListenerID id) {
+  // 1. Get the listeners array for these MMKV instances
+  auto entry = _listeners.find(mmkvID);
+  if (entry == _listeners.end()) {
+    // There's no more listeners for this instance anyways.
+    return;
+  }
+  // 2. Remove all listeners where the ID matches. Should only be one.
+  auto& listeners = entry->second;
+  listeners.erase(std::remove_if(listeners.begin(), listeners.end(), [id](const ListenerSubscription& e) { return e.id == id; }),
+                  listeners.end());
+}
+
+void MMKVValueChangedListenerRegistry::notifyOnValueChanged(const std::string& mmkvID, const std::string& key) {
+  // 1. Get all listeners for the specific MMKV ID
+  auto entry = _listeners.find(mmkvID);
+  if (entry == _listeners.end()) {
+    // There are no listeners. Return
+    return;
+  }
+  // 2. Call each listener.
+  auto& listeners = entry->second;
+  for (const auto& listener : listeners) {
+    listener.callback(key);
+  }
+}
+
+} // namespace margelo::nitro::mmkv

package/cpp/MMKVValueChangedListenerRegistry.hpp

@@ -0,0 +1,43 @@
+//
+//  MMKVValueChangedListenerRegistry.hpp
+//  react-native-mmkv
+//
+//  Created by Marc Rousavy on 21.08.2025.
+//
+
+#include "MMKVTypes.hpp"
+#include <atomic>
+#include <unordered_map>
+
+namespace margelo::nitro::mmkv {
+
+using ListenerID = size_t;
+using MMKVID = std::string;
+
+struct ListenerSubscription {
+  ListenerID id;
+  std::function<void(const std::string& /* key */)> callback;
+};
+
+/**
+ * Listeners are tracked across instances - so we need an extra static class for
+ * the registry.
+ */
+class MMKVValueChangedListenerRegistry final {
+public:
+  MMKVValueChangedListenerRegistry() = delete;
+  ~MMKVValueChangedListenerRegistry() = delete;
+
+public:
+  static ListenerID addListener(const std::string& mmkvID, const std::function<void(const std::string& /* key */)>& callback);
+  static void removeListener(const std::string& mmkvID, ListenerID id);
+
+public:
+  static void notifyOnValueChanged(const std::string& mmkvID, const std::string& key);
+
+private:
+  static std::atomic<ListenerID> _listenersCounter;
+  static std::unordered_map<MMKVID, std::vector<ListenerSubscription>> _listeners;
+};
+
+} // namespace margelo::nitro::mmkv

package/cpp/{ManagedMMBuffer.h → ManagedMMBuffer.hpp}

@@ -7,18 +7,24 @@
 
 #pragma once
 
-#include "MmkvTypes.h" // IWYU pragma: keep
-#include <jsi/jsi.h>
+#include "MMKVTypes.hpp"
+#include <NitroModules/ArrayBuffer.hpp>
 
-using namespace facebook;
+namespace margelo::nitro::mmkv {
 
 /**
- A jsi::MutableBuffer that manages MMBuffer memory (by ownership).
+ An ArrayBuffer subclass that manages MMBuffer memory (by ownership).
  */
-class ManagedMMBuffer : public jsi::MutableBuffer {
+class ManagedMMBuffer : public ArrayBuffer {
 public:
   explicit ManagedMMBuffer(MMBuffer&& buffer) : _buffer(std::move(buffer)) {}
 
+public:
+  bool isOwner() const noexcept override {
+    return true;
+  }
+
+public:
   uint8_t* data() override {
     return static_cast<uint8_t*>(_buffer.getPtr());
   }
@@ -30,3 +36,5 @@ public:
 private:
   MMBuffer _buffer;
 };
+
+} // namespace margelo::nitro::mmkv

package/ios/HybridMMKVPlatformContext.swift

@@ -0,0 +1,43 @@
+//
+//  HybridMMKVPlatformContext.h
+//  react-native-mmkv
+//
+//  Created by Marc Rousavy on 25.03.24.
+//
+
+import Foundation
+import NitroModules
+
+class HybridMMKVPlatformContext: HybridMMKVPlatformContextSpec {
+  static var directory: FileManager.SearchPathDirectory {
+#if os(tvOS)
+    return .cachesDirectory
+#else
+    return .documentDirectory
+#endif
+  }
+  
+  func getBaseDirectory() throws -> String {
+    // Get user documents directory
+    let paths = FileManager.default.urls(for: Self.directory, in: .userDomainMask)
+    guard let documentsPath = paths.first else {
+      throw RuntimeError.error(withMessage: "Cannot find base-path to store MMKV files!")
+    }
+    
+    // append /mmkv to it
+    let basePath = documentsPath.appendingPathComponent("mmkv", conformingTo: .directory)
+    return basePath.path
+  }
+  
+  func getAppGroupDirectory() throws -> String? {
+    // Read `AppGroupIdentifier` from `Info.plist`
+    guard let appGroupID = Bundle.main.object(forInfoDictionaryKey: "AppGroupIdentifier") as? String else {
+      return nil
+    }
+    // Get the URL for the AppGroup
+    guard let url = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: appGroupID) else {
+      throw RuntimeError.error(withMessage: "Container for AppGroup \"\(appGroupID)\" not accessible")
+    }
+    return url.path
+  }
+}

package/lib/__tests__/hooks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/hooks.test.js

@@ -0,0 +1,69 @@
+import React from 'react';
+import { Button, Text } from 'react-native';
+import { act, fireEvent, render, renderHook, screen, cleanup, } from '@testing-library/react-native';
+import { createMMKV, useMMKVNumber, useMMKVString } from '..';
+const mmkv = createMMKV();
+beforeEach(() => {
+    mmkv.clearAll();
+    mmkv.trim();
+});
+afterEach(() => {
+    cleanup();
+});
+test('hooks update when the value is changed directly through the instance', () => {
+    const { result } = renderHook(() => useMMKVString('string-key', mmkv));
+    expect(result.current[0]).toBeUndefined();
+    // First, make a "normal" change
+    act(() => {
+        result.current[1]('value 1');
+    });
+    expect(result.current[0]).toStrictEqual('value 1');
+    // Now, make the change directly through the instance.
+    act(() => {
+        mmkv.set('string-key', 'value 2');
+    });
+    expect(result.current[0]).toStrictEqual('value 2');
+});
+test('functional updates to hooks', () => {
+    const Component = () => {
+        const [state, setState] = React.useState(0);
+        const [value, setValue] = useMMKVNumber('number-key', mmkv);
+        return (React.createElement(React.Fragment, null,
+            React.createElement(Button, { testID: "button", title: "Double Increment Me", onPress: () => {
+                    // Increment the state value twice, using the function form of useState.
+                    setState((current) => current + 1);
+                    setState((current) => current + 1);
+                    // Increment the MMKV value twice, using the same function form.
+                    setValue((current) => (current ?? 0) + 1);
+                    setValue((current) => (current ?? 0) + 1);
+                } }),
+            React.createElement(Text, { testID: "state-value" },
+                "State: ",
+                state.toString()),
+            React.createElement(Text, { testID: "mmkv-value" },
+                "MMKV: ",
+                (value ?? 0).toString())));
+    };
+    render(React.createElement(Component, null));
+    const button = screen.getByTestId('button');
+    // Why these assertions:
+    // https://github.com/mrousavy/react-native-mmkv/issues/599
+    fireEvent.press(button);
+    expect(screen.getByTestId('state-value').children).toStrictEqual([
+        'State: ',
+        '2',
+    ]);
+    expect(screen.getByTestId('mmkv-value').children).toStrictEqual([
+        'MMKV: ',
+        '2',
+    ]);
+    fireEvent.press(button);
+    expect(screen.getByTestId('state-value').children).toStrictEqual([
+        'State: ',
+        '4',
+    ]);
+    expect(screen.getByTestId('mmkv-value').children).toStrictEqual([
+        'MMKV: ',
+        '4',
+    ]);
+});

package/lib/addMemoryWarningListener/addMemoryWarningListener.d.ts

@@ -0,0 +1,2 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+export declare function addMemoryWarningListener(mmkv: MMKV): void;

package/lib/addMemoryWarningListener/addMemoryWarningListener.js

@@ -0,0 +1,25 @@
+import { AppState } from 'react-native';
+export function addMemoryWarningListener(mmkv) {
+    if (global.WeakRef != null && global.FinalizationRegistry != null) {
+        // 1. Weakify MMKV so we can safely use it inside the memoryWarning event listener
+        const weakMmkv = new WeakRef(mmkv);
+        const listener = AppState.addEventListener('memoryWarning', () => {
+            // 0. Everytime we receive a memoryWarning, we try to trim the MMKV instance (if it is still valid)
+            weakMmkv.deref()?.trim();
+        });
+        // 2. Add a listener to when the MMKV instance is deleted
+        const finalization = new FinalizationRegistry((l) => {
+            // 3. When MMKV is deleted, this listener will be called with the memoryWarning listener.
+            l.remove();
+        });
+        // 2.1. Bind the listener to the actual MMKV instance.
+        finalization.register(mmkv, listener);
+    }
+    else {
+        // WeakRef/FinalizationRegistry is not implemented in this engine.
+        // Just add the listener, even if it retains MMKV strong forever.
+        AppState.addEventListener('memoryWarning', () => {
+            mmkv.trim();
+        });
+    }
+}

package/lib/addMemoryWarningListener/addMemoryWarningListener.mock.d.ts

@@ -0,0 +1,2 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+export declare function addMemoryWarningListener(_mmkv: MMKV): void;

package/lib/addMemoryWarningListener/addMemoryWarningListener.mock.js

@@ -0,0 +1,3 @@
+export function addMemoryWarningListener(_mmkv) {
+    // This is no-op in a mocked environment.
+}

package/lib/addMemoryWarningListener/addMemoryWarningListener.web.d.ts

@@ -0,0 +1,2 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+export declare const addMemoryWarningListener: (_mmkv: MMKV) => void;

package/lib/addMemoryWarningListener/addMemoryWarningListener.web.js

@@ -0,0 +1,3 @@
+export const addMemoryWarningListener = (_mmkv) => {
+    //no-op function, there is not a web equivalent to memory warning
+};

package/lib/createMMKV/createMMKV.d.ts

@@ -0,0 +1,3 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+import type { Configuration } from '../specs/MMKVFactory.nitro';
+export declare function createMMKV(configuration?: Configuration): MMKV;

package/lib/createMMKV/createMMKV.js

@@ -0,0 +1,40 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import { Platform } from 'react-native';
+import { addMemoryWarningListener } from '../addMemoryWarningListener/addMemoryWarningListener';
+import { isTest } from '../isTest';
+import { createMockMMKV } from './createMockMMKV';
+let factory;
+let platformContext;
+export function createMMKV(configuration) {
+    if (isTest()) {
+        // In a test environment, we mock the MMKV instance.
+        return createMockMMKV();
+    }
+    if (platformContext == null) {
+        // Lazy-init the platform-context HybridObject
+        platformContext = NitroModules.createHybridObject('MMKVPlatformContext');
+    }
+    if (factory == null) {
+        // Lazy-init the factory HybridObject
+        factory = NitroModules.createHybridObject('MMKVFactory');
+        const baseDirectory = platformContext.getBaseDirectory();
+        factory.initializeMMKV(baseDirectory);
+    }
+    // Pre-parse the config
+    let config = configuration ?? { id: factory.defaultMMKVInstanceId };
+    if (Platform.OS === 'ios') {
+        if (config.path == null) {
+            // If the user set an App Group directory in Info.plist, let's use
+            // the App Group as a MMKV path:
+            const appGroupDirectory = platformContext.getAppGroupDirectory();
+            if (appGroupDirectory != null) {
+                config.path = appGroupDirectory;
+            }
+        }
+    }
+    // Creates the C++ MMKV HybridObject
+    const mmkv = factory.createMMKV(config);
+    // Add a hook that trims the storage when we get a memory warning
+    addMemoryWarningListener(mmkv);
+    return mmkv;
+}

package/lib/createMMKV/createMMKV.mock.d.ts

@@ -0,0 +1,5 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+/**
+ * Mock MMKV instance when used in a Jest/Test environment.
+ */
+export declare function createMockMMKV(): MMKV;

package/lib/createMMKV/createMMKV.mock.js

@@ -0,0 +1,74 @@
+/**
+ * Mock MMKV instance when used in a Jest/Test environment.
+ */
+export function createMockMMKV() {
+    const storage = new Map();
+    const listeners = new Set();
+    const notifyListeners = (key) => {
+        listeners.forEach((listener) => {
+            listener(key);
+        });
+    };
+    return {
+        clearAll: () => {
+            const keysBefore = storage.keys();
+            storage.clear();
+            // Notify all listeners for all keys that were cleared
+            for (const key of keysBefore) {
+                notifyListeners(key);
+            }
+        },
+        remove: (key) => {
+            const deleted = storage.delete(key);
+            if (deleted) {
+                notifyListeners(key);
+            }
+            return deleted;
+        },
+        set: (key, value) => {
+            storage.set(key, value);
+            notifyListeners(key);
+        },
+        getString: (key) => {
+            const result = storage.get(key);
+            return typeof result === 'string' ? result : undefined;
+        },
+        getNumber: (key) => {
+            const result = storage.get(key);
+            return typeof result === 'number' ? result : undefined;
+        },
+        getBoolean: (key) => {
+            const result = storage.get(key);
+            return typeof result === 'boolean' ? result : undefined;
+        },
+        getBuffer: (key) => {
+            const result = storage.get(key);
+            return result instanceof ArrayBuffer ? result : undefined;
+        },
+        getAllKeys: () => Array.from(storage.keys()),
+        contains: (key) => storage.has(key),
+        recrypt: () => {
+            console.warn('Encryption is not supported in mocked MMKV instances!');
+        },
+        get size() {
+            return storage.size;
+        },
+        isReadOnly: false,
+        trim: () => {
+            // no-op
+        },
+        name: 'MMKV',
+        dispose: () => { },
+        equals: () => {
+            return false;
+        },
+        addOnValueChangedListener: (listener) => {
+            listeners.add(listener);
+            return {
+                remove: () => {
+                    listeners.delete(listener);
+                },
+            };
+        },
+    };
+}

package/lib/createMMKV/createMMKV.web.d.ts

@@ -0,0 +1,3 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+import type { Configuration } from '../specs/MMKVFactory.nitro';
+export declare function createMMKV(config?: Configuration): MMKV;

package/lib/createMMKV/createMMKV.web.js

@@ -0,0 +1,117 @@
+import { createTextEncoder } from '../web/createTextEncoder';
+const canUseDOM = typeof window !== 'undefined' && window.document?.createElement != null;
+const hasAccessToLocalStorage = () => {
+    try {
+        // throws ACCESS_DENIED error
+        window.localStorage;
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const KEY_WILDCARD = '\\';
+const inMemoryStorage = new Map();
+export function createMMKV(config = { id: 'mmkv.default' }) {
+    if (config.encryptionKey != null) {
+        throw new Error("MMKV: 'encryptionKey' is not supported on Web!");
+    }
+    if (config.path != null) {
+        throw new Error("MMKV: 'path' is not supported on Web!");
+    }
+    // canUseDOM check prevents spam in Node server environments, such as Next.js server side props.
+    if (!hasAccessToLocalStorage() && canUseDOM) {
+        console.warn('MMKV: LocalStorage has been disabled. Your experience will be limited to in-memory storage!');
+    }
+    const storage = () => {
+        if (!canUseDOM) {
+            throw new Error('Tried to access storage on the server. Did you forget to call this in useEffect?');
+        }
+        if (!hasAccessToLocalStorage()) {
+            return {
+                getItem: (key) => inMemoryStorage.get(key) ?? null,
+                setItem: (key, value) => inMemoryStorage.set(key, value),
+                removeItem: (key) => inMemoryStorage.delete(key),
+                clear: () => inMemoryStorage.clear(),
+                length: inMemoryStorage.size,
+                key: (index) => Object.keys(inMemoryStorage).at(index) ?? null,
+            };
+        }
+        const domStorage = global?.localStorage ?? window?.localStorage ?? localStorage;
+        if (domStorage == null) {
+            throw new Error(`Could not find 'localStorage' instance!`);
+        }
+        return domStorage;
+    };
+    const textEncoder = createTextEncoder();
+    const listeners = new Set();
+    if (config.id.includes(KEY_WILDCARD)) {
+        throw new Error('MMKV: `id` cannot contain the backslash character (`\\`)!');
+    }
+    const keyPrefix = `${config.id}${KEY_WILDCARD}`; // mmkv.default\\
+    const prefixedKey = (key) => {
+        if (key.includes('\\')) {
+            throw new Error('MMKV: `key` cannot contain the backslash character (`\\`)!');
+        }
+        return `${keyPrefix}${key}`;
+    };
+    return {
+        clearAll: () => {
+            const keys = Object.keys(storage());
+            for (const key of keys) {
+                if (key.startsWith(keyPrefix)) {
+                    storage().removeItem(key);
+                }
+            }
+        },
+        remove: (key) => storage().removeItem(prefixedKey(key)) ?? false,
+        set: (key, value) => {
+            storage().setItem(prefixedKey(key), value.toString());
+        },
+        getString: (key) => storage().getItem(prefixedKey(key)) ?? undefined,
+        getNumber: (key) => {
+            const value = storage().getItem(prefixedKey(key));
+            if (value == null)
+                return undefined;
+            return Number(value);
+        },
+        getBoolean: (key) => {
+            const value = storage().getItem(prefixedKey(key));
+            if (value == null)
+                return undefined;
+            return value === 'true';
+        },
+        getBuffer: (key) => {
+            const value = storage().getItem(prefixedKey(key));
+            if (value == null)
+                return undefined;
+            return textEncoder.encode(value).buffer;
+        },
+        getAllKeys: () => {
+            const keys = Object.keys(storage());
+            return keys
+                .filter((key) => key.startsWith(keyPrefix))
+                .map((key) => key.slice(keyPrefix.length));
+        },
+        contains: (key) => storage().getItem(prefixedKey(key)) != null,
+        recrypt: () => {
+            throw new Error('`recrypt(..)` is not supported on Web!');
+        },
+        size: 0,
+        isReadOnly: false,
+        trim: () => {
+            // no-op
+        },
+        dispose: () => { },
+        equals: () => false,
+        name: 'MMKV',
+        addOnValueChangedListener: (listener) => {
+            listeners.add(listener);
+            return {
+                remove: () => {
+                    listeners.delete(listener);
+                },
+            };
+        },
+    };
+}

package/lib/createMMKV/createMockMMKV.d.ts

@@ -0,0 +1,5 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+/**
+ * Mock MMKV instance when used in a Jest/Test environment.
+ */
+export declare function createMockMMKV(): MMKV;

package/lib/createMMKV/createMockMMKV.js

@@ -0,0 +1,74 @@
+/**
+ * Mock MMKV instance when used in a Jest/Test environment.
+ */
+export function createMockMMKV() {
+    const storage = new Map();
+    const listeners = new Set();
+    const notifyListeners = (key) => {
+        listeners.forEach((listener) => {
+            listener(key);
+        });
+    };
+    return {
+        clearAll: () => {
+            const keysBefore = storage.keys();
+            storage.clear();
+            // Notify all listeners for all keys that were cleared
+            for (const key of keysBefore) {
+                notifyListeners(key);
+            }
+        },
+        remove: (key) => {
+            const deleted = storage.delete(key);
+            if (deleted) {
+                notifyListeners(key);
+            }
+            return deleted;
+        },
+        set: (key, value) => {
+            storage.set(key, value);
+            notifyListeners(key);
+        },
+        getString: (key) => {
+            const result = storage.get(key);
+            return typeof result === 'string' ? result : undefined;
+        },
+        getNumber: (key) => {
+            const result = storage.get(key);
+            return typeof result === 'number' ? result : undefined;
+        },
+        getBoolean: (key) => {
+            const result = storage.get(key);
+            return typeof result === 'boolean' ? result : undefined;
+        },
+        getBuffer: (key) => {
+            const result = storage.get(key);
+            return result instanceof ArrayBuffer ? result : undefined;
+        },
+        getAllKeys: () => Array.from(storage.keys()),
+        contains: (key) => storage.has(key),
+        recrypt: () => {
+            console.warn('Encryption is not supported in mocked MMKV instances!');
+        },
+        get size() {
+            return storage.size;
+        },
+        isReadOnly: false,
+        trim: () => {
+            // no-op
+        },
+        name: 'MMKV',
+        dispose: () => { },
+        equals: () => {
+            return false;
+        },
+        addOnValueChangedListener: (listener) => {
+            listeners.add(listener);
+            return {
+                remove: () => {
+                    listeners.delete(listener);
+                },
+            };
+        },
+    };
+}

package/lib/createMMKV/getDefaultMMKVInstance.d.ts

@@ -0,0 +1,2 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+export declare function getDefaultMMKVInstance(): MMKV;

package/lib/createMMKV/getDefaultMMKVInstance.js

@@ -0,0 +1,8 @@
+import { createMMKV } from './createMMKV';
+let defaultInstance = null;
+export function getDefaultMMKVInstance() {
+    if (defaultInstance == null) {
+        defaultInstance = createMMKV();
+    }
+    return defaultInstance;
+}