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

package/react-native.config.js

@@ -0,0 +1,20 @@
+// https://github.com/react-native-community/cli/blob/main/docs/dependencies.md
+
+module.exports = {
+  dependency: {
+    platforms: {
+      /**
+       * @type {import('@react-native-community/cli-types').IOSDependencyParams}
+       */
+      ios: {},
+      /**
+       * @type {import('@react-native-community/cli-types').AndroidDependencyParams}
+       */
+      android: {
+        cxxModuleCMakeListsModuleName: 'react-native-mmkv',
+        cxxModuleCMakeListsPath: `${__dirname}/android/CMakeLists.txt`,
+        cxxModuleHeaderName: 'NativeMmkvModule',
+      },
+    },
+  },
+};

package/src/LazyTurboModule.ts

@@ -0,0 +1,98 @@
+import { NativeModules, Platform, TurboModule } from 'react-native';
+
+declare global {
+  // A react-native internal from TurboModuleRegistry.js
+  var __turboModuleProxy: unknown | undefined;
+}
+
+interface ModuleHolder<T> {
+  module: T | null;
+}
+
+const BULLET_POINT = '\n* ';
+
+/**
+ * Lazily get a TurboModule by wrapping it in a Proxy.
+ */
+export function getLazyTurboModule<T extends TurboModule>(
+  initializeTurboModule: () => T | null
+): T {
+  const proxy = new Proxy<ModuleHolder<T>>(
+    {
+      module: null,
+    },
+    {
+      get: (target, property) => {
+        if (target.module == null) {
+          // Target is null, let's initialize it!
+          target.module = initializeTurboModule();
+
+          if (target.module == null) {
+            // TurboModule not found, something went wrong!
+            if (global.__turboModuleProxy == null) {
+              // TurboModules are not available/new arch is not enabled.
+              // react-native-mmkv 3.x.x requires new arch (react-native >0.74)
+              // react-native-mmkv 2.x.x works on old arch (react-native <0.74)
+              throw new Error(
+                'Failed to create a new MMKV instance: react-native-mmkv 3.x.x requires TurboModules, but the new architecture is not enabled!' +
+                  BULLET_POINT +
+                  'Downgrade to react-native-mmkv 2.x.x if you want to stay on the old architecture.' +
+                  BULLET_POINT +
+                  'Enable the new architecture in your app to use react-native-mmkv 3.x.x. (See https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md)'
+              );
+            }
+
+            const message =
+              'Failed to create a new MMKV instance: The native MMKV Module could not be found.';
+            const suggestions: string[] = [];
+            suggestions.push(
+              'Make sure react-native-mmkv is correctly autolinked (run `npx react-native config` to verify)'
+            );
+            suggestions.push(
+              'Make sure you enabled the new architecture (TurboModules) and CodeGen properly generated the react-native-mmkv specs. See https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md'
+            );
+            suggestions.push(
+              'Make sure you are using react-native 0.74.0 or higher, because react-native-mmkv is a C++ TurboModule.'
+            );
+            suggestions.push('Make sure you rebuilt the app.');
+            switch (Platform.OS) {
+              case 'ios':
+              case 'macos':
+                suggestions.push(
+                  'Make sure you ran `pod install` in the ios/ directory.'
+                );
+                break;
+              case 'android':
+                suggestions.push('Make sure gradle is synced.');
+                break;
+              default:
+                throw new Error(`MMKV is not supported on ${Platform.OS}!`);
+            }
+            // 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
+                suggestions.push('Make sure you ran `expo prebuild`.');
+              }
+            }
+
+            const error =
+              message + BULLET_POINT + suggestions.join(BULLET_POINT);
+            throw new Error(error);
+          }
+        }
+
+        return target.module[property as keyof T];
+      },
+    }
+  );
+  return proxy as unknown as T;
+}

package/src/MMKV.ts

@@ -1,100 +1,11 @@
 import { AppState } from 'react-native';
 import { createMMKV } from './createMMKV';
 import { createMockMMKV } from './createMMKV.mock';
-import { isJest } from './PlatformChecker';
+import { isTest } from './PlatformChecker';
 import { Configuration } from './NativeMmkv';
+import { Listener, MMKVInterface, NativeMMKV } from './Types';
 export { Configuration, Mode } from './NativeMmkv';
 
-interface Listener {
-  remove: () => void;
-}
-
-/**
- * Represents a single MMKV instance.
- */
-export interface NativeMMKV {
-  /**
-   * Set a value for the given `key`.
-   */
-  set: (key: string, value: boolean | string | number | ArrayBuffer) => void;
-  /**
-   * Get the boolean value for the given `key`, or `undefined` if it does not exist.
-   *
-   * @default undefined
-   */
-  getBoolean: (key: string) => boolean | undefined;
-  /**
-   * Get the string value for the given `key`, or `undefined` if it does not exist.
-   *
-   * @default undefined
-   */
-  getString: (key: string) => string | undefined;
-  /**
-   * Get the number value for the given `key`, or `undefined` if it does not exist.
-   *
-   * @default undefined
-   */
-  getNumber: (key: string) => number | undefined;
-  /**
-   * Get a raw buffer of unsigned 8-bit (0-255) data.
-   *
-   * @default undefined
-   */
-  getBuffer: (key: string) => ArrayBuffer | undefined;
-  /**
-   * Checks whether the given `key` is being stored in this MMKV instance.
-   */
-  contains: (key: string) => boolean;
-  /**
-   * Delete the given `key`.
-   */
-  delete: (key: string) => void;
-  /**
-   * Get all keys.
-   *
-   * @default []
-   */
-  getAllKeys: () => string[];
-  /**
-   * Delete all keys.
-   */
-  clearAll: () => void;
-  /**
-   * Sets (or updates) the encryption-key to encrypt all data in this MMKV instance with.
-   *
-   * To remove encryption, pass `undefined` as a key.
-   *
-   * Encryption keys can have a maximum length of 16 bytes.
-   */
-  recrypt: (key: string | undefined) => void;
-  /**
-   * Trims the storage space and clears memory cache.
-   *
-   * Since MMKV does not resize itself after deleting keys, you can call `trim()`
-   * after deleting a bunch of keys to manually trim the memory- and
-   * disk-file to reduce storage and memory usage.
-   *
-   * In most applications, this is not needed at all.
-   */
-  trim(): void;
-  /**
-   * Get the current total size of the storage, in bytes.
-   */
-  readonly size: number;
-}
-
-interface MMKVInterface extends NativeMMKV {
-  /**
-   * Adds a value changed listener. The Listener will be called whenever any value
-   * in this storage instance changes (set or delete).
-   *
-   * To unsubscribe from value changes, call `remove()` on the Listener.
-   */
-  addOnValueChangedListener: (
-    onValueChanged: (key: string) => void
-  ) => Listener;
-}
-
 const onValueChangedListeners = new Map<string, ((key: string) => void)[]>();
 
 /**
@@ -111,17 +22,15 @@ export class MMKV implements MMKVInterface {
    */
   constructor(configuration: Configuration = { id: 'mmkv.default' }) {
     this.id = configuration.id;
-    this.nativeInstance = isJest()
+    this.nativeInstance = isTest()
       ? createMockMMKV()
       : createMMKV(configuration);
     this.functionCache = {};
 
-    if ('WeakRef' in global) {
-      const weakSelf = new WeakRef(this);
-      AppState.addEventListener('memoryWarning', () => {
-        weakSelf.deref()?.trim();
-      });
-    }
+    AppState.addEventListener('memoryWarning', () => {
+      // when we have a memory warning, delete unused keys by trimming MMKV
+      this.trim();
+    });
   }
 
   private get onValueChangedListeners() {

package/src/NativeMmkv.ts

@@ -1,6 +1,7 @@
-import { NativeModules, Platform, TurboModule } from 'react-native';
+import { TurboModule } from 'react-native';
 import { TurboModuleRegistry } from 'react-native';
 import { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+import { getLazyTurboModule } from './LazyTurboModule';
 import { PlatformContext } from './NativeMmkvPlatformContext';
 
 /**
@@ -72,61 +73,33 @@ export interface Configuration {
 }
 
 export interface Spec extends TurboModule {
+  /**
+   * Initialize MMKV with the given base storage directory.
+   * This should be the documents directory by default.
+   */
   initialize(basePath: string): boolean;
+  /**
+   * Create a new instance of MMKV.
+   * The returned {@linkcode UnsafeObject} is a `jsi::HostObject`.
+   */
   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);
-    }
+function getNativeModule(): Spec | null {
+  if (basePath == null) {
+    // use default base path from the Platform (iOS/Android)
+    basePath = PlatformContext.getBaseDirectory();
+  }
 
-    if (basePath == null) {
-      // Get base path from platform specific context
-      basePath = PlatformContext.getBaseDirectory();
-    }
+  const module = TurboModuleRegistry.get<Spec>('MmkvCxx');
 
-    // Initialize MMKV
+  if (module != null) {
+    // initialize MMKV
     module.initialize(basePath);
   }
 
   return module;
 }
+export const MMKVTurboModule = getLazyTurboModule(getNativeModule);

package/src/NativeMmkvPlatformContext.ts

@@ -1,4 +1,5 @@
 import { TurboModule, TurboModuleRegistry } from 'react-native';
+import { getLazyTurboModule } from './LazyTurboModule';
 
 export interface Spec extends TurboModule {
   /**
@@ -7,6 +8,7 @@ export interface Spec extends TurboModule {
   getBaseDirectory(): string;
 }
 
-export const PlatformContext = TurboModuleRegistry.getEnforcing<Spec>(
-  'MmkvPlatformContext'
-);
+function getModule(): Spec | null {
+  return TurboModuleRegistry.get<Spec>('MmkvPlatformContext');
+}
+export const PlatformContext = getLazyTurboModule(getModule);

package/src/PlatformChecker.ts

@@ -1,7 +1,9 @@
-export function isJest(): boolean {
+export function isTest(): boolean {
   if (global.process == null) {
     // In a WebBrowser/Electron the `process` variable does not exist
     return false;
   }
-  return process.env.JEST_WORKER_ID != null;
+  return (
+    process.env.JEST_WORKER_ID != null || process.env.VITEST_WORKER_ID != null
+  );
 }

package/src/Types.ts

@@ -0,0 +1,89 @@
+/**
+ * Represents a single MMKV instance.
+ */
+export interface NativeMMKV {
+  /**
+   * Set a value for the given `key`.
+   */
+  set: (key: string, value: boolean | string | number | ArrayBuffer) => void;
+  /**
+   * Get the boolean value for the given `key`, or `undefined` if it does not exist.
+   *
+   * @default undefined
+   */
+  getBoolean: (key: string) => boolean | undefined;
+  /**
+   * Get the string value for the given `key`, or `undefined` if it does not exist.
+   *
+   * @default undefined
+   */
+  getString: (key: string) => string | undefined;
+  /**
+   * Get the number value for the given `key`, or `undefined` if it does not exist.
+   *
+   * @default undefined
+   */
+  getNumber: (key: string) => number | undefined;
+  /**
+   * Get a raw buffer of unsigned 8-bit (0-255) data.
+   *
+   * @default undefined
+   */
+  getBuffer: (key: string) => ArrayBuffer | undefined;
+  /**
+   * Checks whether the given `key` is being stored in this MMKV instance.
+   */
+  contains: (key: string) => boolean;
+  /**
+   * Delete the given `key`.
+   */
+  delete: (key: string) => void;
+  /**
+   * Get all keys.
+   *
+   * @default []
+   */
+  getAllKeys: () => string[];
+  /**
+   * Delete all keys.
+   */
+  clearAll: () => void;
+  /**
+   * Sets (or updates) the encryption-key to encrypt all data in this MMKV instance with.
+   *
+   * To remove encryption, pass `undefined` as a key.
+   *
+   * Encryption keys can have a maximum length of 16 bytes.
+   */
+  recrypt: (key: string | undefined) => void;
+  /**
+   * Trims the storage space and clears memory cache.
+   *
+   * Since MMKV does not resize itself after deleting keys, you can call `trim()`
+   * after deleting a bunch of keys to manually trim the memory- and
+   * disk-file to reduce storage and memory usage.
+   *
+   * In most applications, this is not needed at all.
+   */
+  trim(): void;
+  /**
+   * Get the current total size of the storage, in bytes.
+   */
+  readonly size: number;
+}
+
+export interface Listener {
+  remove: () => void;
+}
+
+export interface MMKVInterface extends NativeMMKV {
+  /**
+   * Adds a value changed listener. The Listener will be called whenever any value
+   * in this storage instance changes (set or delete).
+   *
+   * To unsubscribe from value changes, call `remove()` on the Listener.
+   */
+  addOnValueChangedListener: (
+    onValueChanged: (key: string) => void
+  ) => Listener;
+}

package/src/__tests__/hooks.test.tsx

@@ -13,6 +13,7 @@ const mmkv = new MMKV();
 
 beforeEach(() => {
   mmkv.clearAll();
+  mmkv.trim();
 });
 
 test('hooks update when the value is changed directly through the instance', () => {

package/src/createMMKV.mock.ts

@@ -1,4 +1,4 @@
-import type { NativeMMKV } from './MMKV';
+import type { NativeMMKV } from './Types';
 
 /* Mock MMKV instance for use in tests */
 export const createMockMMKV = (): NativeMMKV => {

package/src/createMMKV.ts

@@ -1,10 +1,9 @@
-import type { Configuration, NativeMMKV } from './MMKV';
-import { getMMKVTurboModule } from './NativeMmkv';
-
-const module = getMMKVTurboModule();
+import type { Configuration } from './MMKV';
+import { MMKVTurboModule } from './NativeMmkv';
+import type { NativeMMKV } from './Types';
 
 export const createMMKV = (config: Configuration): NativeMMKV => {
-  const instance = module.createMMKV(config);
+  const instance = MMKVTurboModule.createMMKV(config);
   if (__DEV__) {
     if (typeof instance !== 'object' || instance == null) {
       throw new Error(

package/src/createMMKV.web.ts

@@ -1,5 +1,6 @@
 /* global localStorage */
-import type { Configuration, NativeMMKV } from './MMKV';
+import type { Configuration } from './MMKV';
+import type { NativeMMKV } from './Types';
 import { createTextEncoder } from './createTextEncoder';
 
 const canUseDOM =

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './MMKV';
+export * from './hooks';
+
+export { Mode, Configuration } from './NativeMmkv';

package/src/index.tsx

@@ -1,2 +0,0 @@
-export * from './MMKV';
-export * from './hooks';