react-native-mmkv 4.0.0-beta.1 → 4.0.0-beta.11

package/src/{createMMKV.web.ts → createMMKV/createMMKV.web.ts}

@@ -1,44 +1,46 @@
-/* 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 = { id: 'mmkv.default' }
+): 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 +52,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)) ?? false,
     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/createMockMMKV.ts

@@ -0,0 +1,78 @@
+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>()
+
+  const notifyListeners = (key: string) => {
+    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(): 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/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
+}

package/src/hooks/useMMKVListener.ts

@@ -0,0 +1,33 @@
+import { useEffect, useRef } from 'react'
+import type { MMKV } from '../specs/MMKV.nitro'
+import { getDefaultMMKVInstance } from '../createMMKV/getDefaultMMKVInstance'
+
+/**
+ * Listen for changes in the given MMKV storage instance.
+ * If no instance is passed, the default instance will be used.
+ * @param valueChangedListener The function to call whenever a value inside the storage instance changes
+ * @param instance The instance to listen to changes to (or the default instance)
+ *
+ * @example
+ * ```ts
+ * useMMKVListener((key) => {
+ *   console.log(`Value for "${key}" changed!`)
+ * })
+ * ```
+ */
+export function useMMKVListener(
+  valueChangedListener: (key: string) => void,
+  instance?: MMKV
+): void {
+  const ref = useRef(valueChangedListener)
+  ref.current = valueChangedListener
+
+  const mmkv = instance ?? getDefaultMMKVInstance()
+
+  useEffect(() => {
+    const listener = mmkv.addOnValueChangedListener((changedKey) => {
+      ref.current(changedKey)
+    })
+    return () => listener.remove()
+  }, [mmkv])
+}

package/src/hooks/useMMKVNumber.ts

@@ -0,0 +1,15 @@
+import { createMMKVHook } from './createMMKVHook'
+
+/**
+ * Use the number 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 [age, setAge] = useMMKVNumber("user.age")
+ * ```
+ */
+export const useMMKVNumber = createMMKVHook((instance, key) =>
+  instance.getNumber(key)
+)

package/src/hooks/useMMKVObject.ts

@@ -0,0 +1,53 @@
+import { useCallback, useMemo } from 'react'
+import type { MMKV } from '../specs/MMKV.nitro'
+import { useMMKVString } from './useMMKVString'
+
+/**
+ * Use an object value of the given `key` from the given MMKV storage instance.
+ *
+ * If no instance is provided, a shared default instance will be used.
+ *
+ * The object will be serialized using `JSON`.
+ *
+ * @example
+ * ```ts
+ * const [user, setUser] = useMMKVObject<User>("user")
+ * ```
+ */
+export function useMMKVObject<T>(
+  key: string,
+  instance?: MMKV
+): [
+  value: T | undefined,
+  setValue: (
+    value: T | undefined | ((prevValue: T | undefined) => T | undefined)
+  ) => void,
+] {
+  const [json, setJson] = useMMKVString(key, instance)
+
+  const value = useMemo(() => {
+    if (json == null) return undefined
+    return JSON.parse(json) as T
+  }, [json])
+
+  const setValue = useCallback(
+    (v: (T | undefined) | ((prev: T | undefined) => T | undefined)) => {
+      if (v instanceof Function) {
+        setJson((currentJson) => {
+          const currentValue =
+            currentJson != null ? (JSON.parse(currentJson) as T) : undefined
+          const newValue = v(currentValue)
+          // Store the Object as a serialized Value or clear the value
+          return newValue != null ? JSON.stringify(newValue) : undefined
+        })
+      } else {
+        // Store the Object as a serialized Value or clear the value
+        const newValue = v != null ? JSON.stringify(v) : undefined
+        setJson(newValue)
+      }
+    },
+    [setJson]
+  )
+
+  return [value, setValue]
+}

package/src/hooks/useMMKVString.ts

@@ -0,0 +1,15 @@
+import { createMMKVHook } from './createMMKVHook'
+
+/**
+ * Use the string 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 [username, setUsername] = useMMKVString("user.name")
+ * ```
+ */
+export const useMMKVString = createMMKVHook((instance, key) =>
+  instance.getString(key)
+)

package/src/index.ts

@@ -1,4 +1,16 @@
-export * from './MMKV';
-export * from './hooks';
+// All types
+export type { MMKV } from './specs/MMKV.nitro'
+export type { Configuration, Mode } from './specs/MMKVFactory.nitro'
 
-export { Mode, type Configuration } from './Types';
+// The create function
+export { createMMKV } from './createMMKV/createMMKV'
+
+// All the hooks
+export { useMMKV } from './hooks/useMMKV'
+export { useMMKVBoolean } from './hooks/useMMKVBoolean'
+export { useMMKVBuffer } from './hooks/useMMKVBuffer'
+export { useMMKVNumber } from './hooks/useMMKVNumber'
+export { useMMKVObject } from './hooks/useMMKVObject'
+export { useMMKVString } from './hooks/useMMKVString'
+export { useMMKVListener } from './hooks/useMMKVListener'
+export { useMMKVKeys } from './hooks/useMMKVKeys'

package/src/{PlatformChecker.ts → isTest.ts}

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