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

package/src/__tests__/hooks.test.tsx

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

package/src/addMemoryWarningListener/addMemoryWarningListener.mock.ts

@@ -0,0 +1,5 @@
+import type { MMKV } from '../specs/MMKV.nitro'
+
+export function addMemoryWarningListener(_mmkv: MMKV): void {
+  // This is no-op in a mocked environment.
+}

package/src/{MemoryWarningListener.ts → addMemoryWarningListener/addMemoryWarningListener.ts}

@@ -1,29 +1,29 @@
-import { AppState } from 'react-native';
-import type { NativeEventSubscription } from 'react-native';
-import { MMKVInterface } from './Types';
+import { AppState } from 'react-native'
+import type { NativeEventSubscription } from 'react-native'
+import type { MMKV } from '../specs/MMKV.nitro'
 
-export function addMemoryWarningListener(mmkv: MMKVInterface): void {
+export function addMemoryWarningListener(mmkv: MMKV): void {
   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 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();
-    });
+      weakMmkv.deref()?.trim()
+    })
     // 2. Add a listener to when the MMKV instance is deleted
     const finalization = new FinalizationRegistry(
       (l: NativeEventSubscription) => {
         // 3. When MMKV is deleted, this listener will be called with the memoryWarning listener.
-        l.remove();
+        l.remove()
       }
-    );
+    )
     // 2.1. Bind the listener to the actual MMKV instance.
-    finalization.register(mmkv, listener);
+    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();
-    });
+      mmkv.trim()
+    })
   }
 }

package/src/addMemoryWarningListener/addMemoryWarningListener.web.ts

@@ -0,0 +1,5 @@
+import type { MMKV } from '../specs/MMKV.nitro'
+
+export const addMemoryWarningListener = (_mmkv: MMKV): void => {
+  //no-op function, there is not a web equivalent to memory warning
+}

package/src/createMMKV/createMMKV.mock.ts

@@ -0,0 +1,56 @@
+import type { MMKV } from '../specs/MMKV.nitro'
+
+/**
+ * Mock MMKV instance when used in a Jest/Test environment.
+ */
+export function createMockMMKV(): MMKV {
+  const storage = new Map<string, string | boolean | number | ArrayBuffer>()
+  const listeners = new Set<(key: string) => void>()
+
+  return {
+    clearAll: () => storage.clear(),
+    remove: (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!')
+    },
+    get size(): number {
+      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/src/createMMKV/createMMKV.ts

@@ -0,0 +1,51 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { MMKV } from '../specs/MMKV.nitro'
+import type { Configuration, MMKVFactory } from '../specs/MMKVFactory.nitro'
+import type { MMKVPlatformContext } from '../specs/MMKVPlatformContext.nitro'
+import { Platform } from 'react-native'
+import { addMemoryWarningListener } from '../addMemoryWarningListener/addMemoryWarningListener'
+import { isTest } from '../isTest'
+import { createMockMMKV } from './createMMKV.mock'
+
+let factory: MMKVFactory | undefined
+let platformContext: MMKVPlatformContext | undefined
+
+export function createMMKV(configuration?: Configuration): MMKV {
+  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>(
+      'MMKVPlatformContext'
+    )
+  }
+  if (factory == null) {
+    // Lazy-init the factory HybridObject
+    factory = NitroModules.createHybridObject<MMKVFactory>('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/src/{createMMKV.web.ts → createMMKV/createMMKV.web.ts}

@@ -1,44 +1,44 @@
-/* global localStorage */
-import type { Configuration, NativeMMKV } from './Types';
-import { createTextEncoder } from './createTextEncoder';
+import type { MMKV } from '../specs/MMKV.nitro'
+import type { Configuration } from '../specs/MMKVFactory.nitro'
+import { createTextEncoder } from '../web/createTextEncoder'
 
 const canUseDOM =
-  typeof window !== 'undefined' && window.document?.createElement != null;
+  typeof window !== 'undefined' && window.document?.createElement != null
 
 const hasAccessToLocalStorage = () => {
   try {
     // throws ACCESS_DENIED error
-    window.localStorage;
+    window.localStorage
 
-    return true;
+    return true
   } catch {
-    return false;
+    return false
   }
-};
+}
 
-const KEY_WILDCARD = '\\';
-const inMemoryStorage = new Map<string, string>();
+const KEY_WILDCARD = '\\'
+const inMemoryStorage = new Map<string, string>()
 
-export const createMMKV = (config: Configuration): NativeMMKV => {
+export function createMMKV(config: Configuration): MMKV {
   if (config.encryptionKey != null) {
-    throw new Error("MMKV: 'encryptionKey' is not supported on Web!");
+    throw new Error("MMKV: 'encryptionKey' is not supported on Web!")
   }
   if (config.path != null) {
-    throw new Error("MMKV: 'path' is not supported on Web!");
+    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()) {
@@ -50,78 +50,88 @@ export const createMMKV = (config: Configuration): NativeMMKV => {
         clear: () => inMemoryStorage.clear(),
         length: inMemoryStorage.size,
         key: (index: number) => Object.keys(inMemoryStorage).at(index) ?? null,
-      } as Storage;
+      } as Storage
     }
 
     const domStorage =
-      global?.localStorage ?? window?.localStorage ?? localStorage;
+      global?.localStorage ?? window?.localStorage ?? localStorage
     if (domStorage == null) {
-      throw new Error(`Could not find 'localStorage' instance!`);
+      throw new Error(`Could not find 'localStorage' instance!`)
     }
-    return domStorage;
-  };
+    return domStorage
+  }
 
-  const textEncoder = createTextEncoder();
+  const textEncoder = createTextEncoder()
+  const listeners = new Set<(key: string) => void>()
 
   if (config.id.includes(KEY_WILDCARD)) {
-    throw new Error(
-      'MMKV: `id` cannot contain the backslash character (`\\`)!'
-    );
+    throw new Error('MMKV: `id` cannot contain the backslash character (`\\`)!')
   }
 
-  const keyPrefix = `${config.id}${KEY_WILDCARD}`; // mmkv.default\\
+  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 `${keyPrefix}${key}`
+  }
 
   return {
     clearAll: () => {
-      const keys = Object.keys(storage());
+      const keys = Object.keys(storage())
       for (const key of keys) {
         if (key.startsWith(keyPrefix)) {
-          storage().removeItem(key);
+          storage().removeItem(key)
         }
       }
     },
-    delete: (key) => storage().removeItem(prefixedKey(key)),
+    remove: (key) => storage().removeItem(prefixedKey(key)),
     set: (key, value) => {
-      storage().setItem(prefixedKey(key), value.toString());
+      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);
+      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';
+      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;
+      const value = storage().getItem(prefixedKey(key))
+      if (value == null) return undefined
+      return textEncoder.encode(value).buffer
     },
     getAllKeys: () => {
-      const keys = Object.keys(storage());
+      const keys = Object.keys(storage())
       return keys
         .filter((key) => key.startsWith(keyPrefix))
-        .map((key) => key.slice(keyPrefix.length));
+        .map((key) => key.slice(keyPrefix.length))
     },
     contains: (key) => storage().getItem(prefixedKey(key)) != null,
     recrypt: () => {
-      throw new Error('`recrypt(..)` is not supported on Web!');
+      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/src/createMMKV/getDefaultMMKVInstance.ts

@@ -0,0 +1,10 @@
+import type { MMKV } from '../specs/MMKV.nitro'
+import { createMMKV } from './createMMKV'
+
+let defaultInstance: MMKV | null = null
+export function getDefaultMMKVInstance(): MMKV {
+  if (defaultInstance == null) {
+    defaultInstance = createMMKV()
+  }
+  return defaultInstance
+}

package/src/hooks/createMMKVHook.ts

@@ -0,0 +1,66 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { getDefaultMMKVInstance } from '../createMMKV/getDefaultMMKVInstance'
+import type { MMKV } from '../specs/MMKV.nitro'
+
+export function createMMKVHook<
+  T extends (boolean | number | string | ArrayBufferLike) | undefined,
+  TSet extends T | undefined,
+  TSetAction extends TSet | ((current: T) => TSet),
+>(getter: (instance: MMKV, key: string) => T) {
+  return (
+    key: string,
+    instance?: MMKV
+  ): [value: T, setValue: (value: TSetAction) => void] => {
+    const mmkv = instance ?? getDefaultMMKVInstance()
+
+    const [bump, setBump] = useState(0)
+    const value = useMemo(() => {
+      // bump is here as an additional outside dependency, so this useMemo
+      // re-computes the value each time bump changes, effectively acting as a hint
+      // that the outside value (storage) has changed. setting bump refreshes this value.
+      bump
+      return getter(mmkv, key)
+    }, [mmkv, key, bump])
+
+    // update value by user set
+    const set = useCallback(
+      (v: TSetAction) => {
+        const newValue = typeof v === 'function' ? v(getter(mmkv, key)) : v
+        switch (typeof newValue) {
+          case 'number':
+          case 'string':
+          case 'boolean':
+            mmkv.set(key, newValue)
+            break
+          case 'undefined':
+            mmkv.remove(key)
+            break
+          case 'object':
+            if (newValue instanceof ArrayBuffer) {
+              mmkv.set(key, newValue)
+              break
+            } else {
+              throw new Error(
+                `MMKV: Type object (${newValue}) is not supported!`
+              )
+            }
+          default:
+            throw new Error(`MMKV: Type ${typeof newValue} is not supported!`)
+        }
+      },
+      [key, mmkv]
+    )
+
+    // update value if it changes somewhere else (second hook, same key)
+    useEffect(() => {
+      const listener = mmkv.addOnValueChangedListener((changedKey) => {
+        if (changedKey === key) {
+          setBump((b) => b + 1)
+        }
+      })
+      return () => listener.remove()
+    }, [key, mmkv])
+
+    return [value, set]
+  }
+}

package/src/hooks/useMMKV.ts

@@ -0,0 +1,45 @@
+import { useRef } from 'react'
+import type { MMKV } from '../specs/MMKV.nitro'
+import type { Configuration } from '../specs/MMKVFactory.nitro'
+import { getDefaultMMKVInstance } from '../createMMKV/getDefaultMMKVInstance'
+import { createMMKV } from '../createMMKV/createMMKV'
+
+function isConfigurationEqual(
+  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.mode === right.mode
+  )
+}
+
+/**
+ * Use the default, shared MMKV instance.
+ */
+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: Configuration): MMKV
+export function useMMKV(configuration?: Configuration): MMKV {
+  const instance = useRef<MMKV>(undefined)
+  const lastConfiguration = useRef<Configuration>(undefined)
+
+  if (configuration == null) return getDefaultMMKVInstance()
+
+  if (
+    instance.current == null ||
+    !isConfigurationEqual(lastConfiguration.current, configuration)
+  ) {
+    lastConfiguration.current = configuration
+    instance.current = createMMKV(configuration)
+  }
+
+  return instance.current
+}

package/src/hooks/useMMKVBoolean.ts

@@ -0,0 +1,15 @@
+import { createMMKVHook } from './createMMKVHook'
+
+/**
+ * Use the boolean value of the given `key` from the given MMKV storage instance.
+ *
+ * If no instance is provided, a shared default instance will be used.
+ *
+ * @example
+ * ```ts
+ * const [isPremiumAccount, setIsPremiumAccount] = useMMKVBoolean("user.isPremium")
+ * ```
+ */
+export const useMMKVBoolean = createMMKVHook((instance, key) =>
+  instance.getBoolean(key)
+)

package/src/hooks/useMMKVBuffer.ts

@@ -0,0 +1,15 @@
+import { createMMKVHook } from './createMMKVHook'
+
+/**
+ * Use the buffer value (unsigned 8-bit (0-255)) of the given `key` from the given MMKV storage instance.
+ *
+ * If no instance is provided, a shared default instance will be used.
+ *
+ * @example
+ * ```ts
+ * const [privateKey, setPrivateKey] = useMMKVBuffer("user.privateKey")
+ * ```
+ */
+export const useMMKVBuffer = createMMKVHook((instance, key) =>
+  instance.getBuffer(key)
+)

package/src/hooks/useMMKVKeys.ts

@@ -0,0 +1,36 @@
+import { useState } from 'react'
+import type { MMKV } from '../specs/MMKV.nitro'
+import { getDefaultMMKVInstance } from '../createMMKV/getDefaultMMKVInstance'
+import { useMMKVListener } from './useMMKVListener'
+
+/**
+ * Get a list of all keys that exist in the given MMKV {@linkcode instance}.
+ * The keys update when new keys are added or removed.
+ * @param instance The instance to listen to changes to (or the default instance)
+ *
+ * @example
+ * ```ts
+ * useMMKVKeys(instance)
+ * ```
+ */
+export function useMMKVKeys(instance?: MMKV): string[] {
+  const mmkv = instance ?? getDefaultMMKVInstance()
+  const [allKeys, setKeys] = useState<string[]>(() => mmkv.getAllKeys())
+
+  useMMKVListener((key) => {
+    // a key changed
+    setKeys((keys) => {
+      const currentlyHasKey = keys.includes(key)
+      const hasKey = mmkv.contains(key)
+      if (hasKey !== currentlyHasKey) {
+        // Re-fetch the keys from native
+        return mmkv.getAllKeys()
+      } else {
+        // We are up-to-date.
+        return keys
+      }
+    })
+  }, mmkv)
+
+  return allKeys
+}