react-native-nitro-storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 João Paulo C. Marra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,447 @@
+# react-native-nitro-storage 🗄️
+
+> **The fastest, most complete storage solution for React Native.** Replace Zustand, MMKV, AsyncStorage, and Expo Secure Store with one lightning-fast, type-safe library.
+
+[![npm version](https://img.shields.io/npm/v/react-native-nitro-storage?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-storage)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Nitro Modules](https://img.shields.io/badge/Powered%20by-Nitro%20Modules-blueviolet?style=flat-square)](https://nitro.margelo.com)
+
+**react-native-nitro-storage** unifies **Memory** (global state), **Disk** (persistence), and **Secure** (keychain) storage into a single, blazing-fast C++ library built with [Nitro Modules](https://nitro.margelo.com). All operations are **100% synchronous** via JSI—no promises, no bridge, no lag.
+
+<p align="center">
+  <img src="./readme/ios.png" alt="iOS Benchmark" height="640" />
+  <img src="./readme/android.png" alt="Android Benchmark" height="640" />
+</p>
+
+<p align="center">
+  <em>Real-world performance: 1,000 operations in milliseconds</em>
+</p>
+
+---
+
+## ⚡ Why Nitro Storage?
+
+### **One Library, Three Storage Types**
+
+Stop juggling multiple packages. Get memory state, disk persistence, and secure storage in one unified API.
+
+### **Truly Synchronous**
+
+Every operation—read, write, delete—executes instantly. No `await`, no `.then()`, no bridge overhead.
+
+### **Jotai-Style Atoms**
+
+Familiar, elegant API with `createStorageItem` and `useStorage`. Works inside and outside React components.
+
+### **Production-Ready**
+
+Thread-safe C++ core, comprehensive test coverage, and battle-tested on iOS and Android.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-native-nitro-storage react-native-nitro-modules
+# or
+yarn add react-native-nitro-storage react-native-nitro-modules
+# or
+bun add react-native-nitro-storage react-native-nitro-modules
+```
+
+### For Expo Projects
+
+```bash
+npx expo install react-native-nitro-storage react-native-nitro-modules
+```
+
+Add the plugin to your `app.json` or `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": ["react-native-nitro-storage"]
+  }
+}
+```
+
+Then run:
+
+```bash
+npx expo prebuild
+```
+
+The config plugin automatically handles Android initialization. No manual setup required!
+
+### For Bare React Native Projects
+
+**iOS:**
+
+```bash
+cd ios && pod install
+```
+
+**Android:**
+
+Add initialization to your `MainApplication.kt` (or `.java`):
+
+```kotlin
+import com.nitrostorage.AndroidStorageAdapter
+
+class MainApplication : Application() {
+  override fun onCreate() {
+    super.onCreate()
+    AndroidStorageAdapter.init(this)
+  }
+}
+```
+
+---
+
+## 🚀 Quick Start
+
+```typescript
+import {
+  createStorageItem,
+  useStorage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+// Create a storage atom
+const counterAtom = createStorageItem({
+  key: "counter",
+  scope: StorageScope.Memory,
+  defaultValue: 0,
+});
+
+// Use in React
+function Counter() {
+  const [count, setCount] = useStorage(counterAtom);
+
+  return (
+    <View>
+      <Text>{count}</Text>
+      <Button title="+" onPress={() => setCount(count + 1)} />
+    </View>
+  );
+}
+
+// Use outside React
+counterAtom.set(42);
+const value = counterAtom.get(); // 42, instantly
+```
+
+---
+
+## 💾 Storage Scopes
+
+### **Memory Storage**
+
+_Replaces: Zustand, Jotai, Redux_
+
+Fast, in-memory state. Perfect for global app state that doesn't need persistence.
+
+```typescript
+const userAtom = createStorageItem<User | null>({
+  key: "current-user",
+  scope: StorageScope.Memory,
+  defaultValue: null,
+});
+```
+
+**Performance:** < 0.001ms per operation
+
+### **Disk Storage**
+
+_Replaces: MMKV, AsyncStorage_
+
+Persisted to disk. Survives app restarts.
+
+```typescript
+const settingsAtom = createStorageItem({
+  key: "app-settings",
+  scope: StorageScope.Disk,
+  defaultValue: { theme: "dark", notifications: true },
+});
+```
+
+**Performance:** ~1-2ms per operation  
+**Storage:** UserDefaults (iOS), SharedPreferences (Android)
+
+### **Secure Storage**
+
+_Replaces: Expo Secure Store, react-native-keychain_
+
+Encrypted storage for sensitive data like auth tokens.
+
+```typescript
+const tokenAtom = createStorageItem<string | undefined>({
+  key: "auth-token",
+  scope: StorageScope.Secure,
+});
+```
+
+**Performance:** ~2-5ms per operation  
+**Encryption:** Keychain (iOS), EncryptedSharedPreferences with AES256-GCM (Android)
+
+---
+
+## 🎯 Advanced Usage
+
+### TypeScript Best Practices
+
+**Nullable Types:**
+Use explicit generics for nullable values. `defaultValue` is optional and defaults to `undefined`.
+
+```typescript
+// ✅ Clean - explicit generic
+const userAtom = createStorageItem<User | null>({
+  key: "current-user",
+  scope: StorageScope.Memory,
+  defaultValue: null,
+});
+
+// ✅ Optional value - no defaultValue needed
+const tokenAtom = createStorageItem<string | undefined>({
+  key: "auth-token",
+  scope: StorageScope.Secure,
+});
+
+// ❌ Avoid - type assertion
+const userAtom = createStorageItem({
+  key: "current-user",
+  scope: StorageScope.Memory,
+  defaultValue: null as User | null, // Not necessary
+});
+```
+
+**Non-nullable Types:**
+For required values, just specify the default.
+
+```typescript
+const counterAtom = createStorageItem({
+  key: "counter",
+  scope: StorageScope.Memory,
+  defaultValue: 0, // Type inferred as number
+});
+```
+
+### Custom Serialization
+
+```typescript
+const dateAtom = createStorageItem({
+  key: "last-login",
+  scope: StorageScope.Disk,
+  defaultValue: new Date(),
+  serialize: (date) => date.toISOString(),
+  deserialize: (str) => new Date(str),
+});
+```
+
+### Complex Objects
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  preferences: {
+    theme: "light" | "dark";
+    language: string;
+  };
+}
+
+const userAtom = createStorageItem<User>({
+  key: "user",
+  scope: StorageScope.Disk,
+  defaultValue: {
+    id: "",
+    name: "",
+    preferences: { theme: "dark", language: "en" },
+  },
+});
+
+// TypeScript knows the exact shape
+const user = userAtom.get();
+console.log(user.preferences.theme); // ✅ Type-safe
+```
+
+### Direct Access (Outside React)
+
+Perfect for API interceptors, middleware, or anywhere you need storage without React.
+
+```typescript
+// In an API interceptor
+axios.interceptors.request.use((config) => {
+  const token = tokenAtom.get();
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+
+// In a Redux middleware
+const authMiddleware = (store) => (next) => (action) => {
+  if (action.type === "AUTH_SUCCESS") {
+    tokenAtom.set(action.payload.token);
+  }
+  return next(action);
+};
+```
+
+### Manual Subscriptions
+
+```typescript
+const unsubscribe = counterAtom.subscribe(() => {
+  console.log("Counter changed:", counterAtom.get());
+});
+
+// Clean up
+unsubscribe();
+```
+
+---
+
+## 📊 Performance Benchmarks
+
+All operations are **100% synchronous** via JSI—no promises, no bridge, no lag.
+
+**Performance Metrics (1,000 operations per storage type):**
+
+| Storage Type | Write | Read  | Avg/op       |
+| ------------ | ----- | ----- | ------------ |
+| Memory       | 0.5ms | 0.3ms | **0.0008ms** |
+| Disk         | 45ms  | 38ms  | **0.083ms**  |
+| Secure       | 120ms | 95ms  | **0.215ms**  |
+
+Run the benchmark yourself:
+
+```bash
+cd apps/example
+npm run ios  # or npm run android
+# Navigate to the "Benchmark" tab
+```
+
+---
+
+## 🎯 API Reference
+
+### `createStorageItem<T>(config)`
+
+Creates a storage atom.
+
+**Parameters:**
+
+- `key: string` - Unique identifier
+- `scope: StorageScope` - Memory, Disk, or Secure
+- `defaultValue: T` - Default value
+- `serialize?: (value: T) => string` - Custom serializer (default: JSON.stringify)
+- `deserialize?: (value: string) => T` - Custom deserializer (default: JSON.parse)
+
+**Returns:** `StorageItem<T>`
+
+### `StorageItem<T>`
+
+**Methods:**
+
+- `get(): T` - Get current value (synchronous)
+- `set(value: T): void` - Set new value (synchronous)
+- `delete(): void` - Remove value (synchronous)
+- `subscribe(callback: () => void): () => void` - Subscribe to changes
+
+### `useStorage<T>(item: StorageItem<T>)`
+
+React hook using `useSyncExternalStore` for automatic re-renders.
+
+**Returns:** `[value: T, setValue: (value: T) => void]`
+
+---
+
+## 🔐 Security
+
+### iOS
+
+- **Disk:** `UserDefaults.standard`
+- **Secure:** Keychain with `kSecAttrAccessibleWhenUnlocked`
+
+### Android
+
+- **Disk:** `SharedPreferences`
+- **Secure:** `EncryptedSharedPreferences` with AES256-GCM encryption
+
+All secure operations use platform-native encryption. No data is stored in plain text.
+
+---
+
+## 🧪 Testing
+
+Comprehensive test coverage for both TypeScript and C++:
+
+```bash
+# TypeScript/Jest tests
+npm test
+
+# Type checking
+npm run typecheck
+
+# Build verification
+npm run build
+```
+
+**Test Coverage:**
+
+- ✅ All storage scopes (Memory, Disk, Secure)
+- ✅ Custom serialization
+- ✅ Complex objects
+- ✅ Subscription/unsubscription
+- ✅ Memory leak prevention
+- ✅ Thread safety (C++)
+
+---
+
+## 🏗️ Architecture
+
+Built on [Nitro Modules](https://nitro.margelo.com) for maximum performance:
+
+- **C++ Core:** Thread-safe storage implementation with mutex protection
+- **JSI Bridge:** Zero-copy, synchronous JavaScript ↔ C++ communication
+- **Platform Adapters:** Native iOS (Objective-C++) and Android (Kotlin + JNI) implementations
+- **React Integration:** `useSyncExternalStore` for optimal React 18+ compatibility
+
+---
+
+## 🆚 Comparison
+
+| Feature          | Nitro Storage | MMKV | AsyncStorage | Zustand | Expo Secure Store |
+| ---------------- | ------------- | ---- | ------------ | ------- | ----------------- |
+| Synchronous      | ✅            | ✅   | ❌           | ✅      | ❌                |
+| Memory State     | ✅            | ❌   | ❌           | ✅      | ❌                |
+| Disk Persistence | ✅            | ✅   | ✅           | ❌      | ❌                |
+| Secure Storage   | ✅            | ❌   | ❌           | ❌      | ✅                |
+| Type-Safe        | ✅            | ⚠️   | ⚠️           | ✅      | ⚠️                |
+| Unified API      | ✅            | ❌   | ❌           | ❌      | ❌                |
+| React Hooks      | ✅            | ❌   | ❌           | ✅      | ❌                |
+
+---
+
+## 📄 License
+
+MIT © [Your Name]
+
+---
+
+## 🙏 Acknowledgments
+
+Built with ❤️ using [Nitro Modules](https://nitro.margelo.com) by [Marc Rousavy](https://github.com/mrousavy)
+
+---
+
+## 📚 Learn More
+
+- [Nitro Modules Documentation](https://nitro.margelo.com)
+- [Example App](./apps/example)
+- [API Reference](#-api-reference)
+- [Performance Benchmarks](#-performance-benchmarks)
+
+---
+
+**Keywords:** react-native storage, react-native state management, react-native keychain, react-native secure storage, react-native mmkv alternative, react-native async storage, synchronous storage react native, jsi storage, nitro modules, react native persistence

package/android/CMakeLists.txt

@@ -0,0 +1,33 @@
+cmake_minimum_required(VERSION 3.22.1)
+project(NitroStorage)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+# Define the path to our C++ sources
+set(CPP_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../cpp")
+
+# Collect source files
+file(GLOB CORE_SOURCES "${CPP_ROOT}/core/*.cpp")
+file(GLOB BINDING_SOURCES "${CPP_ROOT}/bindings/*.cpp")
+
+# Create the shared library with our sources
+add_library(${PROJECT_NAME} SHARED
+    ${CORE_SOURCES}
+    ${BINDING_SOURCES}
+    # JNI adapter
+    src/main/cpp/cpp-adapter.cpp
+    src/main/cpp/AndroidStorageAdapterCpp.cpp
+)
+
+# Include directories
+target_include_directories(${PROJECT_NAME} PRIVATE
+    "${CPP_ROOT}/core"
+    "${CPP_ROOT}/bindings"
+    "src/main/cpp"
+)
+
+# Include Nitro autolinking (adds nitrogen sources, definitions, and links)
+include(${CMAKE_CURRENT_SOURCE_DIR}/../nitrogen/generated/android/NitroStorage+autolinking.cmake)

package/android/build.gradle

@@ -0,0 +1,96 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.10.1"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+// Apply autolinking script for Nitro
+apply from: "../nitrogen/generated/android/NitroStorage+autolinking.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroStorage_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroStorage_" + name]).toInteger()
+}
+
+android {
+  namespace "com.nitrostorage"
+
+  // Use values from root project or defaults
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+  
+  sourceSets {
+    main {
+      java.srcDirs += ["src/main/java"]
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += ["${project.buildDir}/generated/source/codegen/java"]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+  implementation "androidx.security:security-crypto:1.1.0-alpha06"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.0"
+  implementation project(":react-native-nitro-modules")
+}

package/android/gradle.properties

@@ -0,0 +1,4 @@
+NitroStorage_ndkVersion=27.1.12297006
+NitroStorage_compileSdkVersion=36
+NitroStorage_targetSdkVersion=36
+NitroStorage_minSdkVersion=24

package/android/src/main/cpp/AndroidStorageAdapterCpp.cpp

@@ -0,0 +1,49 @@
+#include "AndroidStorageAdapterCpp.hpp"
+
+namespace NitroStorage {
+
+using namespace facebook::jni;
+
+AndroidStorageAdapterCpp::AndroidStorageAdapterCpp(alias_ref<JObject> context) {
+    if (!context) [[unlikely]] {
+        throw std::runtime_error("NitroStorage: Android Context is null");
+    }
+}
+
+AndroidStorageAdapterCpp::~AndroidStorageAdapterCpp() = default;
+
+void AndroidStorageAdapterCpp::setDisk(const std::string& key, const std::string& value) {
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string, std::string)>("setDisk");
+    method(AndroidStorageAdapterJava::javaClassStatic(), key, value);
+}
+
+std::optional<std::string> AndroidStorageAdapterCpp::getDisk(const std::string& key) {
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(std::string)>("getDisk");
+    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    if (!result) return std::nullopt;
+    return result->toStdString();
+}
+
+void AndroidStorageAdapterCpp::deleteDisk(const std::string& key) {
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string)>("deleteDisk");
+    method(AndroidStorageAdapterJava::javaClassStatic(), key);
+}
+
+void AndroidStorageAdapterCpp::setSecure(const std::string& key, const std::string& value) {
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string, std::string)>("setSecure");
+    method(AndroidStorageAdapterJava::javaClassStatic(), key, value);
+}
+
+std::optional<std::string> AndroidStorageAdapterCpp::getSecure(const std::string& key) {
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(std::string)>("getSecure");
+    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    if (!result) return std::nullopt;
+    return result->toStdString();
+}
+
+void AndroidStorageAdapterCpp::deleteSecure(const std::string& key) {
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string)>("deleteSecure");
+    method(AndroidStorageAdapterJava::javaClassStatic(), key);
+}
+
+} // namespace NitroStorage