@react-native-ohos/react-native-mmkv 3.3.1-1

package/src/NativeMmkv.ts

@@ -0,0 +1,118 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import type { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+import { ModuleNotFoundError } from './ModuleNotFoundError';
+import { getMMKVPlatformContextTurboModule } from './NativeMmkvPlatformContext';
+
+/**
+ * IMPORTANT: These types are also in the Types.ts file.
+ * Due to how react-native-codegen works these are required here as the spec types can not be separated from spec.
+ * We also need the types separate to allow bypassing importing turbo module registry in web
+ */
+/**
+ * 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/' })
+   * ```
+   *
+   * @note On iOS, if an `AppGroup` is set in `Info.plist` and `path` is `undefined`, MMKV will use the `AppGroup` directory.
+   * App Groups allow you to share MMKV storage between apps, widgets and extensions within the same AppGroup bundle.
+   * For more information, see [the `Configuration` section](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;
+  /**
+   * If `true`, the MMKV instance can only read from the storage, but not write to it.
+   */
+  readOnly?: boolean;
+}
+
+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 mmkvModule: Spec | null;
+
+export function getMMKVTurboModule(): Spec {
+  try {
+    if (mmkvModule == null) {
+      // 1. Load MMKV TurboModule
+      mmkvModule = TurboModuleRegistry.getEnforcing<Spec>('MmkvCxx');
+
+      // 2. Get the PlatformContext TurboModule as well
+      const platformContext = getMMKVPlatformContextTurboModule();
+
+      // 3. Initialize it with the documents directory from platform-specific context
+      const basePath = platformContext.getBaseDirectory();
+      mmkvModule.initialize(basePath);
+    }
+
+    return mmkvModule;
+  } catch (cause) {
+    // TurboModule could not be found!
+    throw new ModuleNotFoundError(cause);
+  }
+}

package/src/NativeMmkvPlatformContext.ts

@@ -0,0 +1,38 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import { ModuleNotFoundError } from './ModuleNotFoundError';
+
+export interface Spec extends TurboModule {
+  /**
+   * Gets the base directory of the documents storage
+   */
+  getBaseDirectory(): string;
+  /**
+   * Get the App Group directory if it exists, or `undefined` otherwise.
+   *
+   * The App Group directory will be used instead of a custom path to use the same
+   * MMKV instance between the iOS app, Widgets, and other companion apps.
+   *
+   * To set an App Group, add a `AppGroup` field to `Info.plist`
+   *
+   * @platform ios
+   */
+  getAppGroupDirectory(): string | undefined;
+}
+
+let mmkvPlatformModule: Spec | null;
+
+export function getMMKVPlatformContextTurboModule(): Spec {
+  try {
+    if (mmkvPlatformModule == null) {
+      // 1. Get the TurboModule
+      mmkvPlatformModule = TurboModuleRegistry.getEnforcing<Spec>(
+        'MmkvPlatformContext'
+      );
+    }
+    return mmkvPlatformModule;
+  } catch (e) {
+    // TurboModule could not be found!
+    throw new ModuleNotFoundError(e);
+  }
+}

package/src/PlatformChecker.ts

@@ -0,0 +1,9 @@
+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 || process.env.VITEST_WORKER_ID != null
+  );
+}

package/src/Types.ts

@@ -0,0 +1,178 @@
+/**
+ * IMPORTANT: Some of these types are also in the NativeMmkv.ts file.
+ * Due to how react-native-codegen works these are required here as the spec types can not be separated from spec.
+ * We also need the types separate to allow bypassing importing turbo module registry in web
+ */
+
+/**
+ * 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/' })
+   * ```
+   *
+   * @note On iOS, if an `AppGroup` is set in `Info.plist` and `path` is `undefined`, MMKV will use the `AppGroup` directory.
+   * App Groups allow you to share MMKV storage between apps, widgets and extensions within the same AppGroup bundle.
+   * For more information, see [the `Configuration` section](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;
+  /**
+   * If `true`, the MMKV instance can only read from the storage, but not write to it.
+   * This is more efficient if you do not need to write to it.
+   * @default false
+   */
+  readOnly?: boolean;
+}
+
+/**
+ * Represents a single MMKV instance.
+ */
+export interface NativeMMKV {
+  /**
+   * Set a value for the given `key`.
+   *
+   * @throws an Error if the value cannot be set.
+   */
+  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) => ArrayBufferLike | 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.
+   *
+   * @throws an Error if the instance cannot be recrypted.
+   */
+  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;
+  /**
+   * Returns whether this instance is in read-only mode or not.
+   * If this is `true`, you can only use "get"-functions.
+   */
+  readonly isReadOnly: boolean;
+}
+
+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

@@ -0,0 +1,89 @@
+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();
+  mmkv.trim();
+});
+
+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

@@ -0,0 +1,38 @@
+import type { NativeMMKV } from './Types';
+
+/* Mock MMKV instance for use in tests */
+export const createMockMMKV = (): NativeMMKV => {
+  const storage = new Map<string, string | boolean | number | ArrayBuffer>();
+
+  return {
+    clearAll: () => storage.clear(),
+    delete: (key) => storage.delete(key),
+    set: (key, value) => storage.set(key, value),
+    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!');
+    },
+    size: 0,
+    isReadOnly: false,
+    trim: () => {
+      // no-op
+    },
+  };
+};

package/src/createMMKV.ts

@@ -0,0 +1,42 @@
+import { Platform } from 'react-native';
+import { getMMKVTurboModule } from './NativeMmkv';
+import { type Configuration, Mode, type NativeMMKV } from './Types';
+import { getMMKVPlatformContextTurboModule } from './NativeMmkvPlatformContext';
+
+export const createMMKV = (config: Configuration): NativeMMKV => {
+  const module = getMMKVTurboModule();
+
+  if (Platform.OS === 'ios') {
+    if (config.path == null) {
+      try {
+        // If no `path` was supplied, we check if an `AppGroup` was set in Info.plist
+        const appGroupDirectory =
+          getMMKVPlatformContextTurboModule().getAppGroupDirectory();
+        if (appGroupDirectory != null) {
+          // If we have an `AppGroup` in Info.plist, use that as a path.
+          config.path = appGroupDirectory;
+        }
+      } catch (e) {
+        // We cannot throw errors here because it is a sync C++ TurboModule func. idk why.
+        console.error(e);
+      }
+    }
+  }
+
+  if (typeof config.mode === 'number') {
+    // Code-gen expects enums to be strings. In TS, they might be numbers tho.
+    // This sucks, so we need a workaround.
+    // @ts-expect-error the native side actually expects a string.
+    config.mode = Mode[config.mode];
+  }
+
+  const instance = module.createMMKV(config);
+  if (__DEV__) {
+    if (typeof instance !== 'object' || instance == null) {
+      throw new Error(
+        'Failed to create MMKV instance - an unknown object was returned by createMMKV(..)!'
+      );
+    }
+  }
+  return instance as NativeMMKV;
+};

package/src/createMMKV.web.ts

@@ -0,0 +1,127 @@
+/* global localStorage */
+import type { Configuration, NativeMMKV } from './Types';
+import { createTextEncoder } from './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<string, string>();
+
+export const createMMKV = (config: Configuration): NativeMMKV => {
+  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: string) => inMemoryStorage.get(key) ?? null,
+        setItem: (key: string, value: string) =>
+          inMemoryStorage.set(key, value),
+        removeItem: (key: string) => inMemoryStorage.delete(key),
+        clear: () => inMemoryStorage.clear(),
+        length: inMemoryStorage.size,
+        key: (index: number) => Object.keys(inMemoryStorage).at(index) ?? null,
+      } as Storage;
+    }
+
+    const domStorage =
+      global?.localStorage ?? window?.localStorage ?? localStorage;
+    if (domStorage == null) {
+      throw new Error(`Could not find 'localStorage' instance!`);
+    }
+    return domStorage;
+  };
+
+  const textEncoder = createTextEncoder();
+
+  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: string) => {
+    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);
+        }
+      }
+    },
+    delete: (key) => storage().removeItem(prefixedKey(key)),
+    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
+    },
+  };
+};

package/src/createTextEncoder.ts

@@ -0,0 +1,16 @@
+/* global TextEncoder */
+export function createTextEncoder(): TextEncoder {
+  if (global.TextEncoder != null) {
+    return new global.TextEncoder();
+  } else {
+    return {
+      encode: () => {
+        throw new Error('TextEncoder is not supported in this environment!');
+      },
+      encodeInto: () => {
+        throw new Error('TextEncoder is not supported in this environment!');
+      },
+      encoding: 'utf-8',
+    };
+  }
+}