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

package/lib/createMMKV/createMMKV.web.js

@@ -0,0 +1,117 @@
+import { createTextEncoder } from '../web/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();
+export function createMMKV(config) {
+    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) => inMemoryStorage.get(key) ?? null,
+                setItem: (key, value) => inMemoryStorage.set(key, value),
+                removeItem: (key) => inMemoryStorage.delete(key),
+                clear: () => inMemoryStorage.clear(),
+                length: inMemoryStorage.size,
+                key: (index) => Object.keys(inMemoryStorage).at(index) ?? null,
+            };
+        }
+        const domStorage = global?.localStorage ?? window?.localStorage ?? localStorage;
+        if (domStorage == null) {
+            throw new Error(`Could not find 'localStorage' instance!`);
+        }
+        return domStorage;
+    };
+    const textEncoder = createTextEncoder();
+    const listeners = new Set();
+    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) => {
+        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);
+                }
+            }
+        },
+        remove: (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
+        },
+        dispose: () => { },
+        equals: () => false,
+        name: 'MMKV',
+        addOnValueChangedListener: (listener) => {
+            listeners.add(listener);
+            return {
+                remove: () => {
+                    listeners.delete(listener);
+                },
+            };
+        },
+    };
+}

package/lib/createMMKV/getDefaultMMKVInstance.d.ts

@@ -0,0 +1,2 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+export declare function getDefaultMMKVInstance(): MMKV;

package/lib/createMMKV/getDefaultMMKVInstance.js

@@ -0,0 +1,8 @@
+import { createMMKV } from './createMMKV';
+let defaultInstance = null;
+export function getDefaultMMKVInstance() {
+    if (defaultInstance == null) {
+        defaultInstance = createMMKV();
+    }
+    return defaultInstance;
+}

package/lib/hooks/createMMKVHook.d.ts

@@ -0,0 +1,2 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+export declare 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): (key: string, instance?: MMKV) => [value: T, setValue: (value: TSetAction) => void];

package/lib/hooks/createMMKVHook.js

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { getDefaultMMKVInstance } from '../createMMKV/getDefaultMMKVInstance';
+export function createMMKVHook(getter) {
+    return (key, instance) => {
+        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) => {
+            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/lib/hooks/useMMKV.d.ts

@@ -0,0 +1,11 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+import type { Configuration } from '../specs/MMKVFactory.nitro';
+/**
+ * Use the default, shared MMKV instance.
+ */
+export declare 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 declare function useMMKV(configuration: Configuration): MMKV;

package/lib/hooks/useMMKV.js

@@ -0,0 +1,23 @@
+import { useRef } from 'react';
+import { getDefaultMMKVInstance } from '../createMMKV/getDefaultMMKVInstance';
+import { createMMKV } from '../createMMKV/createMMKV';
+function isConfigurationEqual(left, right) {
+    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);
+}
+export function useMMKV(configuration) {
+    const instance = useRef(undefined);
+    const lastConfiguration = useRef(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/lib/hooks/useMMKVBoolean.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare const useMMKVBoolean: (key: string, instance?: import("..").MMKV) => [value: boolean | undefined, setValue: (value: boolean | ((current: boolean | undefined) => boolean | undefined) | undefined) => void];

package/lib/hooks/useMMKVBoolean.js

@@ -0,0 +1,12 @@
+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/lib/hooks/useMMKVBuffer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare const useMMKVBuffer: (key: string, instance?: import("..").MMKV) => [value: ArrayBuffer | undefined, setValue: (value: ArrayBuffer | ((current: ArrayBuffer | undefined) => ArrayBuffer | undefined) | undefined) => void];

package/lib/hooks/useMMKVBuffer.js

@@ -0,0 +1,12 @@
+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/lib/hooks/useMMKVKeys.d.ts

@@ -0,0 +1,12 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+/**
+ * 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 declare function useMMKVKeys(instance?: MMKV): string[];

package/lib/hooks/useMMKVKeys.js

@@ -0,0 +1,33 @@
+import { useState } from 'react';
+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) {
+    const mmkv = instance ?? getDefaultMMKVInstance();
+    const [allKeys, setKeys] = useState(() => 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/lib/hooks/useMMKVListener.d.ts

@@ -0,0 +1,15 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+/**
+ * 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 declare function useMMKVListener(valueChangedListener: (key: string) => void, instance?: MMKV): void;

package/lib/hooks/useMMKVListener.js

@@ -0,0 +1,26 @@
+import { useEffect, useRef } from 'react';
+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, instance) {
+    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/lib/hooks/useMMKVNumber.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare const useMMKVNumber: (key: string, instance?: import("..").MMKV) => [value: number | undefined, setValue: (value: number | ((current: number | undefined) => number | undefined) | undefined) => void];

package/lib/hooks/useMMKVNumber.js

@@ -0,0 +1,12 @@
+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/lib/hooks/useMMKVObject.d.ts

@@ -0,0 +1,17 @@
+import type { MMKV } from '../specs/MMKV.nitro';
+/**
+ * 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 declare function useMMKVObject<T>(key: string, instance?: MMKV): [
+    value: T | undefined,
+    setValue: (value: T | undefined | ((prevValue: T | undefined) => T | undefined)) => void
+];

package/lib/hooks/useMMKVObject.js

@@ -0,0 +1,38 @@
+import { useCallback, useMemo } from 'react';
+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(key, instance) {
+    const [json, setJson] = useMMKVString(key, instance);
+    const value = useMemo(() => {
+        if (json == null)
+            return undefined;
+        return JSON.parse(json);
+    }, [json]);
+    const setValue = useCallback((v) => {
+        if (v instanceof Function) {
+            setJson((currentJson) => {
+                const currentValue = currentJson != null ? JSON.parse(currentJson) : 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/lib/hooks/useMMKVString.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare const useMMKVString: (key: string, instance?: import("..").MMKV) => [value: string | undefined, setValue: (value: string | ((current: string | undefined) => string | undefined) | undefined) => void];

package/lib/hooks/useMMKVString.js

@@ -0,0 +1,12 @@
+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/lib/index.d.ts

@@ -0,0 +1,11 @@
+export type { MMKV } from './specs/MMKV.nitro';
+export type { Configuration, Mode } from './specs/MMKVFactory.nitro';
+export { createMMKV } from './createMMKV/createMMKV';
+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/lib/index.js

@@ -0,0 +1,11 @@
+// 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/lib/isTest.d.ts

@@ -0,0 +1 @@
+export declare function isTest(): boolean;

package/lib/isTest.js

@@ -0,0 +1,7 @@
+export function isTest() {
+    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/lib/specs/MMKV.nitro.d.ts

@@ -0,0 +1,93 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+export interface Listener {
+    remove: () => void;
+}
+export interface MMKV extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    /**
+     * 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): ArrayBuffer | undefined;
+    /**
+     * Checks whether the given `key` is being stored in this MMKV instance.
+     */
+    contains(key: string): boolean;
+    /**
+     * Removes the given `key`.
+     */
+    remove(key: string): void;
+    /**
+     * Get all keys.
+     *
+     * @default []
+     */
+    getAllKeys(): string[];
+    /**
+     * Clears all keys/values.
+     */
+    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;
+    /**
+     * 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/lib/specs/MMKV.nitro.js

@@ -0,0 +1 @@
+export {};