react-native-mmkv 3.0.2 → 3.1.0

package/MMKV/Core/MemoryFile.h

@@ -47,6 +47,7 @@ enum class OpenFlag : uint32_t {
     Excel = 1 << 3, // fail if Create is set but the file already exist
     Truncate = 1 << 4,
 };
+constexpr uint32_t OpenFlagRWMask = 0x3; // mask for Read Write mode
 
 static inline OpenFlag operator | (OpenFlag left, OpenFlag right) {
     return static_cast<OpenFlag>(static_cast<uint32_t>(left) | static_cast<uint32_t>(right));
@@ -56,6 +57,10 @@ static inline bool operator & (OpenFlag left, OpenFlag right) {
     return ((static_cast<uint32_t>(left) & static_cast<uint32_t>(right)) != 0);
 }
 
+static inline OpenFlag operator & (OpenFlag left, uint32_t right) {
+    return static_cast<OpenFlag>(static_cast<uint32_t>(left) & right);
+}
+
 template <typename T>
 T roundUp(T numToRound, T multiple) {
     return ((numToRound + multiple - 1) / multiple) * multiple;
@@ -109,6 +114,7 @@ class MemoryFile {
 #endif
     void *m_ptr;
     size_t m_size;
+    const bool m_readOnly;
 
     bool mmap();
 
@@ -116,9 +122,9 @@ class MemoryFile {
 
 public:
 #ifndef MMKV_ANDROID
-    explicit MemoryFile(MMKVPath_t path, size_t expectedCapacity = 0);
+    explicit MemoryFile(MMKVPath_t path, size_t expectedCapacity = 0, bool readOnly = false);
 #else
-    MemoryFile(MMKVPath_t path, size_t size, FileType fileType, size_t expectedCapacity = 0);
+    MemoryFile(MMKVPath_t path, size_t size, FileType fileType, size_t expectedCapacity = 0, bool readOnly = false);
     explicit MemoryFile(MMKVFileHandle_t ashmemFD);
 
     const FileType m_fileType;

package/MMKV/Core/MemoryFile_Android.cpp

@@ -70,8 +70,9 @@ File::File(MMKVFileHandle_t ashmemFD)
     }
 }
 
-MemoryFile::MemoryFile(string path, size_t size, FileType fileType, size_t expectedCapacity)
-    : m_diskFile(std::move(path), OpenFlag::ReadWrite | OpenFlag::Create, size, fileType), m_ptr(nullptr), m_size(0), m_fileType(fileType) {
+MemoryFile::MemoryFile(string path, size_t size, FileType fileType, size_t expectedCapacity, bool isReadOnly)
+    : m_diskFile(std::move(path), isReadOnly ? OpenFlag::ReadOnly : (OpenFlag::ReadWrite | OpenFlag::Create), size, fileType),
+    m_ptr(nullptr), m_size(0), m_fileType(fileType), m_readOnly(isReadOnly) {
     if (m_fileType == MMFILE_TYPE_FILE) {
         reloadFromFile(expectedCapacity);
     } else {
@@ -86,7 +87,7 @@ MemoryFile::MemoryFile(string path, size_t size, FileType fileType, size_t expec
 }
 
 MemoryFile::MemoryFile(int ashmemFD)
-    : m_diskFile(ashmemFD), m_ptr(nullptr), m_size(0), m_fileType(MMFILE_TYPE_ASHMEM) {
+    : m_diskFile(ashmemFD), m_ptr(nullptr), m_size(0), m_fileType(MMFILE_TYPE_ASHMEM), m_readOnly(false) {
     if (!m_diskFile.isFileValid()) {
         MMKVError("fd %d invalid", ashmemFD);
     } else {

package/MMKV/Core/MemoryFile_Win32.cpp

@@ -43,7 +43,7 @@ File::File(MMKVPath_t path, OpenFlag flag) : m_path(std::move(path)), m_fd(INVAL
 
 static pair<int, int> OpenFlag2NativeFlag(OpenFlag flag) {
     int access = 0, create = OPEN_EXISTING;
-    if (flag & OpenFlag::ReadWrite) {
+    if ((flag & OpenFlagRWMask) == OpenFlag::ReadWrite) {
         access = (GENERIC_READ | GENERIC_WRITE);
     } else if (flag & OpenFlag::ReadOnly) {
         access |= GENERIC_READ;
@@ -70,10 +70,10 @@ bool File::open() {
     m_fd = CreateFile(m_path.c_str(), pair.first, FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE, nullptr,
                       pair.second, FILE_ATTRIBUTE_NORMAL, nullptr);
     if (!isFileValid()) {
-        MMKVError("fail to open:[%ls], %d", m_path.c_str(), GetLastError());
+        MMKVError("fail to open:[%ls], flag %x, error %d", m_path.c_str(), m_flag, GetLastError());
         return false;
     }
-    MMKVInfo("open fd[%p], %ls", m_fd, m_path.c_str());
+    MMKVInfo("open fd[%p], flag %x, %ls", m_fd, m_flag, m_path.c_str());
     return true;
 }
 
@@ -94,11 +94,12 @@ size_t File::getActualFileSize() const {
     return size;
 }
 
-MemoryFile::MemoryFile(MMKVPath_t path, size_t expectedCapacity)
-    : m_diskFile(std::move(path), OpenFlag::ReadWrite | OpenFlag::Create)
+MemoryFile::MemoryFile(MMKVPath_t path, size_t expectedCapacity, bool readOnly)
+    : m_diskFile(std::move(path), readOnly ? OpenFlag::ReadOnly : (OpenFlag::ReadWrite | OpenFlag::Create))
     , m_fileMapping(nullptr)
     , m_ptr(nullptr)
-    , m_size(0) {
+    , m_size(0)
+    , m_readOnly(readOnly) {
     reloadFromFile(expectedCapacity);
 }
 
@@ -109,6 +110,10 @@ bool MemoryFile::truncate(size_t size) {
     if (size == m_size) {
         return true;
     }
+    if (m_readOnly) {
+        // truncate readonly file not allow
+        return false;
+    }
 
     auto oldSize = m_size;
     m_size = size;
@@ -151,6 +156,10 @@ bool MemoryFile::truncate(size_t size) {
 }
 
 bool MemoryFile::msync(SyncFlag syncFlag) {
+    if (m_readOnly) {
+        // there's no point in msync() readonly memory
+        return true;
+    }
     if (m_ptr) {
         if (FlushViewOfFile(m_ptr, m_size)) {
             if (syncFlag == MMKV_SYNC) {
@@ -168,14 +177,16 @@ bool MemoryFile::msync(SyncFlag syncFlag) {
 }
 
 bool MemoryFile::mmap() {
-    m_fileMapping = CreateFileMapping(m_diskFile.getFd(), nullptr, PAGE_READWRITE, 0, 0, nullptr);
+    auto mode = m_readOnly ? PAGE_READONLY : PAGE_READWRITE;
+    m_fileMapping = CreateFileMapping(m_diskFile.getFd(), nullptr, mode, 0, 0, nullptr);
     if (!m_fileMapping) {
-        MMKVError("fail to CreateFileMapping [%ls], %d", m_diskFile.m_path.c_str(), GetLastError());
+        MMKVError("fail to CreateFileMapping [%ls], mode %x, %d", m_diskFile.m_path.c_str(), mode, GetLastError());
         return false;
     } else {
-        m_ptr = (char *) MapViewOfFile(m_fileMapping, FILE_MAP_ALL_ACCESS, 0, 0, 0);
+        auto viewMode = m_readOnly ? FILE_MAP_READ : FILE_MAP_ALL_ACCESS;
+        m_ptr = (char *) MapViewOfFile(m_fileMapping, viewMode, 0, 0, 0);
         if (!m_ptr) {
-            MMKVError("fail to mmap [%ls], %d", m_diskFile.m_path.c_str(), GetLastError());
+            MMKVError("fail to mmap [%ls], mode %x, %d", m_diskFile.m_path.c_str(), viewMode, GetLastError());
             return false;
         }
         MMKVInfo("mmap to address [%p], [%ls]", m_ptr, m_diskFile.m_path.c_str());
@@ -199,7 +210,7 @@ void MemoryFile::reloadFromFile(size_t expectedCapacity) {
         mmkv::getFileSize(m_diskFile.getFd(), m_size);
         size_t expectedSize = std::max<size_t>(DEFAULT_MMAP_SIZE, roundUp<size_t>(expectedCapacity, DEFAULT_MMAP_SIZE));
         // round up to (n * pagesize)
-        if (m_size < expectedSize || (m_size % DEFAULT_MMAP_SIZE != 0)) {
+        if (!m_readOnly && (m_size < expectedSize || (m_size % DEFAULT_MMAP_SIZE != 0))) {
             size_t roundSize = ((m_size / DEFAULT_MMAP_SIZE) + 1) * DEFAULT_MMAP_SIZE;;
             roundSize = std::max<size_t>(expectedSize, roundSize);
             truncate(roundSize);

package/MMKV/Core/aes/AESCrypt.cpp

@@ -24,13 +24,28 @@
 #include <cstdlib>
 #include <cstring>
 #include <ctime>
+#include "../MMKVLog.h"
+#include "../MemoryFile.h"
+
+namespace mmkv {
+
+// assuming size in [1, 5]
+uint32_t AESCrypt::randomItemSizeHolder(uint32_t size) {
+    constexpr uint32_t ItemSizeHolders[] = {0, 0x80, 0x4000, 0x200000, 0x10000000, 0};
+    auto ItemSizeHolderMin = ItemSizeHolders[size - 1];
+    auto ItemSizeHolderMax = ItemSizeHolders[size] - 1;
+
+    srand((unsigned) time(nullptr));
+    auto result = static_cast<uint32_t>(rand());
+    result = result % (ItemSizeHolderMax - ItemSizeHolderMin + 1);
+    result += ItemSizeHolderMin;
+    return result;
+}
 
 #ifndef MMKV_DISABLE_CRYPT
 
 using namespace openssl;
 
-namespace mmkv {
-
 AESCrypt::AESCrypt(const void *key, size_t keyLength, const void *iv, size_t ivLength) {
     if (key && keyLength > 0) {
         memcpy(m_key, key, (keyLength > AES_KEY_LEN) ? AES_KEY_LEN : keyLength);
@@ -102,19 +117,6 @@ void AESCrypt::fillRandomIV(void *vector) {
     }
 }
 
-// assuming size in [1, 5]
-uint32_t AESCrypt::randomItemSizeHolder(uint32_t size) {
-    constexpr uint32_t ItemSizeHolders[] = {0, 0x80, 0x4000, 0x200000, 0x10000000, 0};
-    auto ItemSizeHolderMin = ItemSizeHolders[size - 1];
-    auto ItemSizeHolderMax = ItemSizeHolders[size] - 1;
-
-    srand((unsigned) time(nullptr));
-    auto result = static_cast<uint32_t>(rand());
-    result = result % (ItemSizeHolderMax - ItemSizeHolderMin + 1);
-    result += ItemSizeHolderMin;
-    return result;
-}
-
 static inline void
 Rollback_cfb_decrypt(const uint8_t *input, const uint8_t *output, size_t len, AES_KEY *key, AESCryptStatus &status) {
     auto ivec = status.m_vector;
@@ -174,15 +176,8 @@ AESCrypt AESCrypt::cloneWithStatus(const AESCryptStatus &status) const {
     return AESCrypt(*this, status);
 }
 
-} // namespace mmkv
-
 #    ifdef MMKV_DEBUG
 
-#        include "../MMKVLog.h"
-#        include "../MemoryFile.h"
-
-namespace mmkv {
-
 void testRandomPlaceHolder() {
     for (uint32_t size = 1; size < 6; size++) {
         auto holder = AESCrypt::randomItemSizeHolder(size);
@@ -272,7 +267,7 @@ void AESCrypt::testAESCrypt() {
     delete[] decryptText;
 }
 
-} // namespace mmkv
-
 #    endif // MMKV_DEBUG
 #endif     // MMKV_DISABLE_CRYPT
+
+} // namespace mmkv

package/MMKV/Core/aes/AESCrypt.h

@@ -29,7 +29,10 @@
 #ifdef MMKV_DISABLE_CRYPT
 
 namespace mmkv {
-class AESCrypt;
+class AESCrypt {
+public:
+    static uint32_t randomItemSizeHolder(uint32_t size);
+};
 }
 
 #else

package/MMKV/README.md

@@ -0,0 +1,354 @@
+[![license](https://img.shields.io/badge/license-BSD_3-brightgreen.svg?style=flat)](https://github.com/Tencent/MMKV/blob/master/LICENSE.TXT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Tencent/MMKV/pulls)
+[![Release Version](https://img.shields.io/badge/release-2.0.0-brightgreen.svg)](https://github.com/Tencent/MMKV/releases)
+[![Platform](https://img.shields.io/badge/Platform-%20Android%20%7C%20iOS%2FmacOS%20%7C%20Windows%20%7C%20POSIX%20%7C%20HarmonyOS%20NEXT-brightgreen.svg)](https://github.com/Tencent/MMKV/wiki/home)
+
+中文版本请参看[这里](./README_CN.md)
+
+MMKV is an **efficient**, **small**, **easy-to-use** mobile key-value storage framework used in the WeChat application. It's currently available on **Android**, **iOS/macOS**, **Windows**, **POSIX** and **HarmonyOS NEXT**.
+
+# MMKV for Android
+
+## Features
+
+* **Efficient**. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of Android to achieve the best performance.
+  * **Multi-Process concurrency**: MMKV supports concurrent read-read and read-write access between processes.
+
+* **Easy-to-use**. You can use MMKV as you go. All changes are saved immediately, no `sync`, no `apply` calls needed.
+
+* **Small**.
+  * **A handful of files**: MMKV contains process locks, encode/decode helpers and mmap logics, and nothing more. It's really tidy.
+  * **About 50K in binary size**: MMKV adds about 50K per architecture on App size, and much less when zipped (APK).
+
+
+## Getting Started
+
+### Installation Via Maven
+Add the following lines to `build.gradle` on your app module:
+
+```gradle
+dependencies {
+    implementation 'com.tencent:mmkv:2.0.0'
+    // replace "2.0.0" with any available version
+}
+```
+
+For other installation options, see [Android Setup](https://github.com/Tencent/MMKV/wiki/android_setup).
+
+### Quick Tutorial
+You can use MMKV as you go. All changes are saved immediately, no `sync`, no `apply` calls needed.  
+Setup MMKV on App startup, say your `Application` class, add these lines:
+
+```Java
+public void onCreate() {
+    super.onCreate();
+
+    String rootDir = MMKV.initialize(this);
+    System.out.println("mmkv root: " + rootDir);
+    //……
+}
+```
+
+MMKV has a global instance, that can be used directly:
+
+```Java
+import com.tencent.mmkv.MMKV;
+    
+MMKV kv = MMKV.defaultMMKV();
+
+kv.encode("bool", true);
+boolean bValue = kv.decodeBool("bool");
+
+kv.encode("int", Integer.MIN_VALUE);
+int iValue = kv.decodeInt("int");
+
+kv.encode("string", "Hello from mmkv");
+String str = kv.decodeString("string");
+```
+
+MMKV also supports **Multi-Process Access**. Full tutorials can be found here [Android Tutorial](https://github.com/Tencent/MMKV/wiki/android_tutorial).
+
+## Performance
+Writing random `int` for 1000 times, we get this chart:  
+![](https://github.com/Tencent/MMKV/wiki/assets/profile_android_mini.png)  
+For more benchmark data, please refer to [our benchmark](https://github.com/Tencent/MMKV/wiki/android_benchmark).
+
+# MMKV for iOS/macOS
+
+## Features
+
+* **Efficient**. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of iOS/macOS to achieve the best performance.
+ 
+* **Easy-to-use**. You can use MMKV as you go, no configurations are needed. All changes are saved immediately, no `synchronize` calls are needed.
+
+* **Small**.
+  * **A handful of files**: MMKV contains encode/decode helpers and mmap logics and nothing more. It's really tidy.
+  * **Less than 30K in binary size**: MMKV adds less than 30K per architecture on App size, and much less when zipped (IPA).
+
+## Getting Started
+
+### Installation Via CocoaPods:
+  1. Install [CocoaPods](https://guides.CocoaPods.org/using/getting-started.html);
+  2. Open the terminal, `cd` to your project directory, run `pod repo update` to make CocoaPods aware of the latest available MMKV versions;
+  3. Edit your Podfile, add `pod 'MMKV'` to your app target;
+  4. Run `pod install`;
+  5. Open the `.xcworkspace` file generated by CocoaPods;
+  6. Add `#import <MMKV/MMKV.h>` to your source file and we are done.
+
+For other installation options, see [iOS/macOS Setup](https://github.com/Tencent/MMKV/wiki/iOS_setup).
+
+### Quick Tutorial
+You can use MMKV as you go, no configurations are needed. All changes are saved immediately, no `synchronize` calls are needed.
+Setup MMKV on App startup, in your `-[MyApp application: didFinishLaunchingWithOptions:]`, add these lines:
+
+```objective-c
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+    // init MMKV in the main thread
+    [MMKV initializeMMKV:nil];
+
+    //...
+    return YES;
+}
+```
+
+MMKV has a global instance, that can be used directly:
+
+```objective-c
+MMKV *mmkv = [MMKV defaultMMKV];
+    
+[mmkv setBool:YES forKey:@"bool"];
+BOOL bValue = [mmkv getBoolForKey:@"bool"];
+    
+[mmkv setInt32:-1024 forKey:@"int32"];
+int32_t iValue = [mmkv getInt32ForKey:@"int32"];
+    
+[mmkv setString:@"hello, mmkv" forKey:@"string"];
+NSString *str = [mmkv getStringForKey:@"string"];
+```
+
+MMKV also supports **Multi-Process Access**. Full tutorials can be found [here](https://github.com/Tencent/MMKV/wiki/iOS_tutorial).
+
+## Performance
+Writing random `int` for 10000 times, we get this chart:  
+![](https://github.com/Tencent/MMKV/wiki/assets/profile_mini.png)  
+For more benchmark data, please refer to [our benchmark](https://github.com/Tencent/MMKV/wiki/iOS_benchmark).
+
+
+# MMKV for Windows
+
+## Features
+
+* **Efficient**. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of Windows to achieve the best performance.
+  * **Multi-Process concurrency**: MMKV supports concurrent read-read and read-write access between processes.
+
+* **Easy-to-use**. You can use MMKV as you go. All changes are saved immediately, no `save`, no `sync` calls are needed.
+
+* **Small**.
+  * **A handful of files**: MMKV contains process locks, encode/decode helpers and mmap logics, and nothing more. It's really tidy.
+  * **About 10K in binary size**: MMKV adds about 10K on application size, and much less when zipped.
+
+
+## Getting Started
+
+### Installation Via Source
+1. Getting source code from git repository:
+  
+   ```
+   git clone https://github.com/Tencent/MMKV.git
+   ```
+  
+2. Add `Core/core.vcxproj` to your solution;
+3. Add `MMKV` project to your project's dependencies;
+4. Add `$(OutDir)include` to your project's `C/C++` -> `General` -> `Additional Include Directories`;
+5. Add `$(OutDir)` to your project's `Linker` -> `General` -> `Additional Library Directories`;
+6. Add `mmkv.lib` to your project's `Linker` -> `Input` -> `Additional Dependencies`;
+7. Add `#include <MMKV/MMKV.h>` to your source file and we are done.
+
+
+note:  
+
+1. MMKV is compiled with `MT/MTd` runtime by default. If your project uses `MD/MDd`, you should change MMKV's setting to match your project's (`C/C++` -> `Code Generation` -> `Runtime Library`), or vice versa.
+2. MMKV is developed with Visual Studio 2017, change the `Platform Toolset` if you use a different version of Visual Studio.
+
+For other installation options, see [Windows Setup](https://github.com/Tencent/MMKV/wiki/windows_setup).
+
+### Quick Tutorial
+You can use MMKV as you go. All changes are saved immediately, no `sync`, no `save` calls needed.  
+Setup MMKV on App startup, say in your `main()`, add these lines:
+
+```C++
+#include <MMKV/MMKV.h>
+
+int main() {
+    std::wstring rootDir = getYourAppDocumentDir();
+    MMKV::initializeMMKV(rootDir);
+    //...
+}
+```
+
+MMKV has a global instance, that can be used directly:
+
+```C++
+auto mmkv = MMKV::defaultMMKV();
+
+mmkv->set(true, "bool");
+std::cout << "bool = " << mmkv->getBool("bool") << std::endl;
+
+mmkv->set(1024, "int32");
+std::cout << "int32 = " << mmkv->getInt32("int32") << std::endl;
+
+mmkv->set("Hello, MMKV for Windows", "string");
+std::string result;
+mmkv->getString("string", result);
+std::cout << "string = " << result << std::endl;
+```
+
+MMKV also supports **Multi-Process Access**. Full tutorials can be found here [Windows Tutorial](https://github.com/Tencent/MMKV/wiki/windows_tutorial).
+
+# MMKV for POSIX
+
+## Features
+
+* **Efficient**. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of POSIX to achieve the best performance.
+  * **Multi-Process concurrency**: MMKV supports concurrent read-read and read-write access between processes.
+
+* **Easy-to-use**. You can use MMKV as you go. All changes are saved immediately, no `save`, no `sync` calls are needed.
+
+* **Small**.
+  * **A handful of files**: MMKV contains process locks, encode/decode helpers and mmap logics, and nothing more. It's really tidy.
+  * **About 7K in binary size**: MMKV adds about 7K on application size, and much less when zipped.
+
+
+## Getting Started
+
+### Installation Via CMake
+1. Getting source code from the git repository:
+  
+   ```
+   git clone https://github.com/Tencent/MMKV.git
+   ```
+2. Edit your `CMakeLists.txt`, add those lines:
+
+    ```cmake
+    add_subdirectory(mmkv/POSIX/src mmkv)
+    target_link_libraries(MyApp
+        mmkv)
+    ```
+3. Add `#include "MMKV.h"` to your source file and we are done.
+
+For other installation options, see [POSIX Setup](https://github.com/Tencent/MMKV/wiki/posix_setup).
+
+### Quick Tutorial
+You can use MMKV as you go. All changes are saved immediately, no `sync`, no `save` calls needed.  
+Setup MMKV on App startup, say in your `main()`, add these lines:
+
+```C++
+#include "MMKV.h"
+
+int main() {
+    std::string rootDir = getYourAppDocumentDir();
+    MMKV::initializeMMKV(rootDir);
+    //...
+}
+```
+
+MMKV has a global instance, that can be used directly:
+
+```C++
+auto mmkv = MMKV::defaultMMKV();
+
+mmkv->set(true, "bool");
+std::cout << "bool = " << mmkv->getBool("bool") << std::endl;
+
+mmkv->set(1024, "int32");
+std::cout << "int32 = " << mmkv->getInt32("int32") << std::endl;
+
+mmkv->set("Hello, MMKV for Windows", "string");
+std::string result;
+mmkv->getString("string", result);
+std::cout << "string = " << result << std::endl;
+```
+
+MMKV also supports **Multi-Process Access**. Full tutorials can be found here [POSIX Tutorial](https://github.com/Tencent/MMKV/wiki/posix_tutorial).
+
+# MMKV for HarmonyOS NEXT
+
+## Features
+
+* **Efficient**. MMKV uses mmap to keep memory synced with file, and protobuf to encode/decode values, making the most of native platform to achieve best performance.
+  * **Multi-Process concurrency**: MMKV supports concurrent read-read and read-write access between processes.
+
+* **Easy-to-use**. You can use MMKV as you go. All changes are saved immediately, no `sync`, no `flush` calls needed.
+
+* **Small**.
+  * **A handful of files**: MMKV contains process locks, encode/decode helpers and mmap logics and nothing more. It's really tidy.
+  * **About 600K in binary size**: MMKV adds about 600K per architecture on App size, and much less when zipped (HAR/HAP).
+
+
+## Getting Started
+### Installation via OHPM:
+
+```bash
+ohpm install @tencent/mmkv
+```
+### Quick Tutorial
+You can use MMKV as you go. All changes are saved immediately, no `sync`, no `apply` calls needed.  
+Setup MMKV on App startup, say your `EntryAbility.onCreate()` function, add these lines:
+
+```js
+import { MMKV } from '@tencent/mmkv';
+
+export default class EntryAbility extends UIAbility {
+  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
+    let appCtx = this.context.getApplicationContext();
+    let mmkvRootDir = MMKV.initialize(appCtx);
+    console.info('mmkv rootDir: ', mmkvRootDir);
+    ……
+  }
+```
+
+MMKV has a global instance, that can be used directly:
+
+```js
+import { MMKV } from '@tencent/mmkv';
+    
+let mmkv = MMKV.defaultMMKV();
+mmkv.encodeBool('bool', true);
+console.info('bool = ', mmkv.decodeBool('bool'));
+    
+mmkv.encodeInt32('int32', Math.pow(2, 31) - 1);
+console.info('max int32 = ', mmkv.decodeInt32('int32'));
+    
+mmkv.encodeInt64('int', BigInt(2**63) - BigInt(1));
+console.info('max int64 = ', mmkv.decodeInt64('int'));
+    
+let str: string = 'Hello OpenHarmony from MMKV';
+mmkv.encodeString('string', str);
+console.info('string = ', mmkv.decodeString('string'));
+
+let arrayBuffer: ArrayBuffer = StringToArrayBuffer('Hello OpenHarmony from MMKV with bytes');
+mmkv.encodeBytes('bytes', arrayBuffer);
+let bytes = mmkv.decodeBytes('bytes');
+console.info('bytes = ', ArrayBufferToString(bytes));
+```
+
+As you can see, MMKV is quite easy to use.
+For the full documentation, see [HarmonyOS NEXT Tutorial](https://github.com/Tencent/MMKV/wiki/ohos_setup).
+
+## License
+MMKV is published under the BSD 3-Clause license. For details check out the [LICENSE.TXT](./LICENSE.TXT).
+
+## Change Log
+Check out the [CHANGELOG.md](./CHANGELOG.md) for details of change history.
+
+## Contributing
+
+If you are interested in contributing, check out the [CONTRIBUTING.md](./CONTRIBUTING.md), also join our [Tencent OpenSource Plan](https://opensource.tencent.com/contribution).
+
+To give clarity of what is expected of our members, MMKV has adopted the code of conduct defined by the Contributor Covenant, which is widely used. And we think it articulates our values well. For more, check out the [Code of Conduct](./CODE_OF_CONDUCT.md).
+
+## FAQ & Feedback
+Check out the [FAQ](https://github.com/Tencent/MMKV/wiki/FAQ) first. Should there be any questions, don't hesitate to create [issues](https://github.com/Tencent/MMKV/issues).
+
+## Personal Information Protection Rules
+User privacy is taken very seriously: MMKV does not obtain, collect or upload any personal information. Please refer to the [MMKV SDK Personal Information Protection Rules](https://support.weixin.qq.com/cgi-bin/mmsupportacctnodeweb-bin/pages/aY5BAtRiO1BpoHxo) for details.

package/README.md

@@ -0,0 +1,5 @@
+# react-native-mmkv
+
+The fastest key/value storage for React Native. ~30x faster than AsyncStorage!
+
+See [README.md](https://github.com/mrousavy/react-native-mmkv) for more information.

package/cpp/MmkvHostObject.cpp

@@ -26,6 +26,10 @@ MmkvHostObject::MmkvHostObject(const facebook::react::MMKVConfig& config) {
   std::string* pathPtr = path.size() > 0 ? &path : nullptr;
   std::string* encryptionKeyPtr = encryptionKey.size() > 0 ? &encryptionKey : nullptr;
   MMKVMode mode = getMMKVMode(config);
+  if (config.readOnly.has_value() && config.readOnly.value()) {
+    MmkvLogger::log("RNMMKV", "Instance is read-only!");
+    mode = mode | MMKVMode::MMKV_READ_ONLY;
+  }
 
 #ifdef __APPLE__
   instance = MMKV::mmkvWithID(config.id, mode, encryptionKeyPtr, pathPtr);
@@ -62,7 +66,7 @@ MmkvHostObject::~MmkvHostObject() {
 std::vector<jsi::PropNameID> MmkvHostObject::getPropertyNames(jsi::Runtime& rt) {
   return jsi::PropNameID::names(rt, "set", "getBoolean", "getBuffer", "getString", "getNumber",
                                 "contains", "delete", "getAllKeys", "deleteAll", "recrypt", "trim",
-                                "size");
+                                "size", "isReadOnly");
 }
 
 MMKVMode MmkvHostObject::getMMKVMode(const facebook::react::MMKVConfig& config) {
@@ -130,7 +134,12 @@ jsi::Value MmkvHostObject::get(jsi::Runtime& runtime, const jsi::PropNameID& pro
           }
 
           if (!successful) [[unlikely]] {
-            throw std::runtime_error("Failed to set " + keyName + "!");
+            if (instance->isReadOnly()) {
+              throw jsi::JSError(runtime,
+                                 "Failed to set " + keyName + "! This instance is read-only!");
+            } else {
+              throw jsi::JSError(runtime, "Failed to set " + keyName + "!");
+            }
           }
 
           return jsi::Value::undefined();
@@ -310,7 +319,7 @@ jsi::Value MmkvHostObject::get(jsi::Runtime& runtime, const jsi::PropNameID& pro
           }
 
           if (!successful) [[unlikely]] {
-            throw std::runtime_error("Failed to recrypt MMKV instance!");
+            throw jsi::JSError(runtime, "Failed to recrypt MMKV instance!");
           }
 
           return jsi::Value::undefined();
@@ -336,5 +345,11 @@ jsi::Value MmkvHostObject::get(jsi::Runtime& runtime, const jsi::PropNameID& pro
     return jsi::Value(static_cast<int>(size));
   }
 
+  if (propName == "isReadOnly") {
+    // MMKV.isReadOnly
+    bool isReadOnly = instance->isReadOnly();
+    return jsi::Value(isReadOnly);
+  }
+
   return jsi::Value::undefined();
 }

package/cpp/NativeMmkvModule.h

@@ -22,7 +22,7 @@ namespace facebook::react {
 // The MMKVConfiguration type from JS
 using MMKVConfig =
     NativeMmkvConfiguration<std::string, std::optional<std::string>, std::optional<std::string>,
-                            std::optional<NativeMmkvMode>>;
+                            std::optional<NativeMmkvMode>, std::optional<bool>>;
 template <> struct Bridging<MMKVConfig> : NativeMmkvConfigurationBridging<MMKVConfig> {};
 
 // The TurboModule itself