react-native-mmkv 2.12.2 → 3.0.0-beta.1

package/src/NativeMmkv.ts

@@ -0,0 +1,132 @@
+import { NativeModules, Platform, TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+import { PlatformContext } from './NativeMmkvPlatformContext';
+
+/**
+ * Configures the mode of the MMKV instance.
+ */
+export enum Mode {
+  /**
+   * The MMKV instance is only used from a single process (this app).
+   */
+  SINGLE_PROCESS,
+  /**
+   * The MMKV instance may be used from multiple processes, such as app clips, share extensions or background services.
+   */
+  MULTI_PROCESS,
+}
+
+/**
+ * Used for configuration of a single MMKV instance.
+ */
+export interface Configuration {
+  /**
+   * The MMKV instance's ID. If you want to use multiple instances, make sure to use different IDs!
+   *
+   * @example
+   * ```ts
+   * const userStorage = new MMKV({ id: `user-${userId}-storage` })
+   * const globalStorage = new MMKV({ id: 'global-app-storage' })
+   * ```
+   *
+   * @default 'mmkv.default'
+   */
+  id: string;
+  /**
+   * The MMKV instance's root path. By default, MMKV stores file inside `$(Documents)/mmkv/`. You can customize MMKV's root directory on MMKV initialization:
+
+   * @example
+   * ```ts
+   * const temporaryStorage = new MMKV({ path: '/tmp/' })
+   * ```
+   *
+   * _Notice_: On iOS you can set the AppGroup bundle property to share the same storage between your app and its extensions.
+   * In this case `path` property will be ignored.
+   * See more on MMKV configuration [here](https://github.com/Tencent/MMKV/wiki/iOS_tutorial#configuration).
+   *
+   * @default undefined
+   */
+  path?: string;
+  /**
+   * The MMKV instance's encryption/decryption key. By default, MMKV stores all key-values in plain text on file, relying on iOS's sandbox to make sure the file is encrypted. Should you worry about information leaking, you can choose to encrypt MMKV.
+   *
+   * Encryption keys can have a maximum length of 16 bytes.
+   *
+   * @example
+   * ```ts
+   * const secureStorage = new MMKV({ encryptionKey: 'my-encryption-key!' })
+   * ```
+   *
+   * @default undefined
+   */
+  encryptionKey?: string;
+  /**
+   * Configure the processing mode for MMKV.
+   * - `SINGLE_PROCESS`: The MMKV instance is only used from a single process (this app).
+   * - `MULTI_PROCESS`: The MMKV instance may be used from multiple processes, such as app clips, share extensions or background services.
+   *
+   * @default SINGLE_PROCESS
+   */
+  mode?: Mode;
+}
+
+export interface Spec extends TurboModule {
+  initialize(basePath: string): boolean;
+  createMMKV(configuration: Configuration): UnsafeObject;
+}
+
+let module: Spec | null = null;
+let basePath: string | null = null;
+
+/**
+ * Get the MMKV TurboModule, and initialize it if this is the first time calling.
+ * This will throw an error if the module cannot be found.
+ */
+export function getMMKVTurboModule(): Spec {
+  if (module == null) {
+    // try to find the turbomodule
+    module = TurboModuleRegistry.get<Spec>('MmkvCxx');
+
+    if (module == null) {
+      // if it still is null, something went wrong!
+      let message =
+        'Failed to create a new MMKV instance: The native MMKV Module could not be found.';
+      message +=
+        '\n* Make sure react-native-mmkv is correctly autolinked (run `npx react-native config` to verify)';
+      if (Platform.OS === 'ios' || Platform.OS === 'macos') {
+        message += '\n* Make sure you ran `pod install` in the ios/ directory.';
+      }
+      if (Platform.OS === 'android') {
+        message += '\n* Make sure gradle is synced.';
+      }
+      // check if Expo
+      const ExpoConstants =
+        NativeModules.NativeUnimoduleProxy?.modulesConstants?.ExponentConstants;
+      if (ExpoConstants != null) {
+        if (ExpoConstants.appOwnership === 'expo') {
+          // We're running Expo Go
+          throw new Error(
+            'react-native-mmkv is not supported in Expo Go! Use EAS (`expo prebuild`) or eject to a bare workflow instead.'
+          );
+        } else {
+          // We're running Expo bare / standalone
+          message += '\n* Make sure you ran `expo prebuild`.';
+        }
+      }
+
+      message += '\n* Make sure you rebuilt the app.';
+      throw new Error(message);
+    }
+
+    if (basePath == null) {
+      // Get base path from platform specific context
+      basePath = PlatformContext.getBaseDirectory();
+    }
+
+    // Initialize MMKV
+    module.initialize(basePath);
+  }
+
+  return module;
+}

package/src/NativeMmkvPlatformContext.ts

@@ -0,0 +1,12 @@
+import { TurboModule, TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  /**
+   * Gets the base directory of the documents storage
+   */
+  getBaseDirectory(): string;
+}
+
+export const PlatformContext = TurboModuleRegistry.getEnforcing<Spec>(
+  'MmkvPlatformContext'
+);

package/src/__tests__/hooks.test.tsx

@@ -0,0 +1,88 @@
+import React from 'react';
+import { Button, Text } from 'react-native';
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+} from '@testing-library/react-native';
+import { MMKV, useMMKVNumber, useMMKVString } from '..';
+
+const mmkv = new MMKV();
+
+beforeEach(() => {
+  mmkv.clearAll();
+});
+
+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: React.FC = () => {
+    const [state, setState] = React.useState(0);
+    const [value, setValue] = useMMKVNumber('number-key', mmkv);
+
+    return (
+      <>
+        <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);
+          }}
+        />
+        <Text testID="state-value">State: {state.toString()}</Text>
+        <Text testID="mmkv-value">MMKV: {(value ?? 0).toString()}</Text>
+      </>
+    );
+  };
+
+  render(<Component />);
+
+  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/src/createMMKV.mock.ts

@@ -1,8 +1,8 @@
-import type { NativeMMKV } from 'react-native-mmkv';
+import type { NativeMMKV } from './MMKV';
 
 /* Mock MMKV instance for use in tests */
 export const createMockMMKV = (): NativeMMKV => {
-  const storage = new Map<string, string | boolean | number | Uint8Array>();
+  const storage = new Map<string, string | boolean | number | ArrayBuffer>();
 
   return {
     clearAll: () => storage.clear(),
@@ -22,12 +22,16 @@ export const createMockMMKV = (): NativeMMKV => {
     },
     getBuffer: (key) => {
       const result = storage.get(key);
-      return result instanceof Uint8Array ? result : undefined;
+      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!');
     },
+    size: 0,
+    trim: () => {
+      // no-op
+    },
   };
 };

package/src/createMMKV.ts

@@ -1,70 +1,16 @@
-import { NativeModules, Platform } from 'react-native';
-import type { MMKVConfiguration, NativeMMKV } from 'react-native-mmkv';
+import type { Configuration, NativeMMKV } from './MMKV';
+import { getMMKVTurboModule } from './NativeMmkv';
 
-// global func declaration for JSI functions
-declare global {
-  function mmkvCreateNewInstance(configuration: MMKVConfiguration): NativeMMKV;
-  function nativeCallSyncHook(): unknown;
-}
+const module = getMMKVTurboModule();
 
-// Root directory of all MMKV stores
-const ROOT_DIRECTORY: string | null = null;
-
-export const createMMKV = (config: MMKVConfiguration): NativeMMKV => {
-  // Check if the constructor exists. If not, try installing the JSI bindings.
-  if (global.mmkvCreateNewInstance == null) {
-    // Get the native MMKV ReactModule
-    const MMKVModule = NativeModules.MMKV;
-    if (MMKVModule == null) {
-      let message =
-        'Failed to create a new MMKV instance: The native MMKV Module could not be found.';
-      message +=
-        '\n* Make sure react-native-mmkv is correctly autolinked (run `npx react-native config` to verify)';
-      if (Platform.OS === 'ios' || Platform.OS === 'macos') {
-        message += '\n* Make sure you ran `pod install` in the ios/ directory.';
-      }
-      if (Platform.OS === 'android') {
-        message += '\n* Make sure gradle is synced.';
-      }
-      // check if Expo
-      const ExpoConstants =
-        NativeModules.NativeUnimoduleProxy?.modulesConstants?.ExponentConstants;
-      if (ExpoConstants != null) {
-        if (ExpoConstants.appOwnership === 'expo') {
-          // We're running Expo Go
-          throw new Error(
-            'react-native-mmkv is not supported in Expo Go! Use EAS (`expo prebuild`) or eject to a bare workflow instead.'
-          );
-        } else {
-          // We're running Expo bare / standalone
-          message += '\n* Make sure you ran `expo prebuild`.';
-        }
-      }
-
-      message += '\n* Make sure you rebuilt the app.';
-      throw new Error(message);
-    }
-
-    // Check if we are running on-device (JSI)
-    if (global.nativeCallSyncHook == null || MMKVModule.install == null) {
+export const createMMKV = (config: Configuration): NativeMMKV => {
+  const instance = module.createMMKV(config);
+  if (__DEV__) {
+    if (typeof instance !== 'object' || instance == null) {
       throw new Error(
-        'Failed to create a new MMKV instance: React Native is not running on-device. MMKV can only be used when synchronous method invocations (JSI) are possible. If you are using a remote debugger (e.g. Chrome), switch to an on-device debugger (e.g. Flipper) instead.'
+        'Failed to create MMKV instance - an unknown object was returned by createMMKV(..)!'
       );
     }
-
-    // Call the synchronous blocking install() function
-    const result = MMKVModule.install(ROOT_DIRECTORY);
-    if (result !== true)
-      throw new Error(
-        `Failed to create a new MMKV instance: The native MMKV Module could not be installed! Looks like something went wrong when installing JSI bindings: ${result}`
-      );
-
-    // Check again if the constructor now exists. If not, throw an error.
-    if (global.mmkvCreateNewInstance == null)
-      throw new Error(
-        'Failed to create a new MMKV instance, the native initializer function does not exist. Are you trying to use MMKV from different JS Runtimes?'
-      );
   }
-
-  return global.mmkvCreateNewInstance(config);
+  return instance as NativeMMKV;
 };

package/src/createMMKV.web.ts

@@ -1,5 +1,5 @@
 /* global localStorage */
-import type { MMKVConfiguration, NativeMMKV } from 'react-native-mmkv';
+import type { Configuration, NativeMMKV } from './MMKV';
 import { createTextEncoder } from './createTextEncoder';
 
 const canUseDOM =
@@ -19,7 +19,7 @@ const hasAccessToLocalStorage = () => {
 const KEY_WILDCARD = '\\';
 const inMemoryStorage = new Map<string, string>();
 
-export const createMMKV = (config: MMKVConfiguration): NativeMMKV => {
+export const createMMKV = (config: Configuration): NativeMMKV => {
   if (config.encryptionKey != null) {
     throw new Error("MMKV: 'encryptionKey' is not supported on Web!");
   }
@@ -118,5 +118,9 @@ export const createMMKV = (config: MMKVConfiguration): NativeMMKV => {
     recrypt: () => {
       throw new Error('`recrypt(..)` is not supported on Web!');
     },
+    size: 0,
+    trim: () => {
+      // no-op
+    },
   };
 };

package/src/hooks.ts

@@ -1,16 +1,17 @@
 import { useRef, useState, useMemo, useCallback, useEffect } from 'react';
-import { MMKV, MMKVConfiguration } from './MMKV';
+import { MMKV, Configuration } from './MMKV';
 
 function isConfigurationEqual(
-  left?: MMKVConfiguration,
-  right?: MMKVConfiguration
+  left?: Configuration,
+  right?: Configuration
 ): boolean {
   if (left == null || right == null) return left == null && right == null;
 
   return (
     left.encryptionKey === right.encryptionKey &&
     left.id === right.id &&
-    left.path === right.path
+    left.path === right.path &&
+    left.mode === right.mode
   );
 }
 
@@ -30,10 +31,10 @@ export function useMMKV(): MMKV;
  * Use a custom MMKV instance with the given configuration.
  * @param configuration The configuration to initialize the MMKV instance with. Does not have to be memoized.
  */
-export function useMMKV(configuration: MMKVConfiguration): MMKV;
-export function useMMKV(configuration?: MMKVConfiguration): MMKV {
+export function useMMKV(configuration: Configuration): MMKV;
+export function useMMKV(configuration?: Configuration): MMKV {
   const instance = useRef<MMKV>();
-  const lastConfiguration = useRef<MMKVConfiguration>();
+  const lastConfiguration = useRef<Configuration>();
 
   if (configuration == null) return getDefaultInstance();
 
@@ -49,9 +50,9 @@ export function useMMKV(configuration?: MMKVConfiguration): MMKV {
 }
 
 function createMMKVHook<
-  T extends (boolean | number | string | Uint8Array) | undefined,
+  T extends (boolean | number | string | ArrayBuffer) | undefined,
   TSet extends T | undefined,
-  TSetAction extends TSet | ((current: T) => TSet)
+  TSetAction extends TSet | ((current: T) => TSet),
 >(getter: (instance: MMKV, key: string) => T) {
   return (
     key: string,
@@ -82,7 +83,7 @@ function createMMKVHook<
             mmkv.delete(key);
             break;
           case 'object':
-            if (newValue instanceof Uint8Array) {
+            if (newValue instanceof ArrayBuffer) {
               mmkv.set(key, newValue);
               break;
             } else {
@@ -179,7 +180,12 @@ export const useMMKVBuffer = createMMKVHook((instance, key) =>
 export function useMMKVObject<T>(
   key: string,
   instance?: MMKV
-): [value: T | undefined, setValue: (value: T | undefined | ((prevValue: T | undefined) => T | undefined)) => void] {
+): [
+  value: T | undefined,
+  setValue: (
+    value: T | undefined | ((prevValue: T | undefined) => T | undefined)
+  ) => void,
+] {
   const [json, setJson] = useMMKVString(key, instance);
 
   const value = useMemo(() => {

package/android/src/main/java/com/reactnativemmkv/MmkvModule.java

@@ -1,49 +0,0 @@
-package com.reactnativemmkv;
-
-import android.util.Log;
-
-import androidx.annotation.NonNull;
-import androidx.annotation.Nullable;
-
-import com.facebook.react.bridge.JavaScriptContextHolder;
-import com.facebook.react.bridge.ReactContextBaseJavaModule;
-import com.facebook.react.bridge.ReactApplicationContext;
-import com.facebook.react.bridge.ReactMethod;
-import com.facebook.react.module.annotations.ReactModule;
-
-@ReactModule(name = MmkvModule.NAME)
-public class MmkvModule extends ReactContextBaseJavaModule {
-  public static final String NAME = "MMKV";
-
-  public MmkvModule(ReactApplicationContext reactContext) {
-    super(reactContext);
-  }
-
-  @NonNull
-  @Override
-  public String getName() {
-    return NAME;
-  }
-
-  @ReactMethod(isBlockingSynchronousMethod = true)
-  public boolean install(@Nullable String rootDirectory) {
-    try {
-      Log.i(NAME, "Loading C++ library...");
-      System.loadLibrary("reactnativemmkv");
-
-      JavaScriptContextHolder jsContext = getReactApplicationContext().getJavaScriptContextHolder();
-      if (rootDirectory == null) {
-        rootDirectory = getReactApplicationContext().getFilesDir().getAbsolutePath() + "/mmkv";
-      }
-      Log.i(NAME, "Installing MMKV JSI Bindings for MMKV root directory: " + rootDirectory);
-      nativeInstall(jsContext.get(), rootDirectory);
-      Log.i(NAME, "Successfully installed MMKV JSI Bindings!");
-      return true;
-    } catch (Exception exception) {
-      Log.e(NAME, "Failed to install MMKV JSI Bindings!", exception);
-      return false;
-    }
-  }
-
-  private static native void nativeInstall(long jsiPtr, String path);
-}

package/android/src/main/java/com/reactnativemmkv/MmkvPackage.java

@@ -1,26 +0,0 @@
-package com.reactnativemmkv;
-
-import androidx.annotation.NonNull;
-
-import com.facebook.react.ReactPackage;
-import com.facebook.react.bridge.NativeModule;
-import com.facebook.react.bridge.ReactApplicationContext;
-import com.facebook.react.uimanager.ViewManager;
-
-import java.util.Collections;
-import java.util.List;
-
-
-public class MmkvPackage implements ReactPackage {
-  @NonNull
-  @Override
-  public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactContext) {
-    return Collections.singletonList(new MmkvModule(reactContext));
-  }
-
-  @NonNull
-  @Override
-  public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
-    return Collections.emptyList();
-  }
-}