react-native-fast-json 0.1.0

package/FastJson.podspec

@@ -0,0 +1,41 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "FastJson"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  # Align with Swift CxxStdlib / Nitro toolchains (iOS 16+).
+  s.platforms    = { :ios => '16.0' }
+  s.source       = { :git => "https://github.com/ifeoluwak/react-native-fast-json.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    # .h: simdjson amalgamation header in cpp/third_party
+    "cpp/**/*.{h,hpp,cpp}",
+  ]
+
+
+  # Force O3 optimization specifically for C++ files
+  s.compiler_flags = '-O3 -DNDEBUG'
+
+  s.pod_target_xcconfig = {
+    'GCC_OPTIMIZATION_LEVEL' => '3',
+    'OTHER_CPLUSPLUSFLAGS' => '-O3 -DNDEBUG',
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/cpp\" \"$(PODS_TARGET_SRCROOT)/cpp/third_party\" $(inherited)",
+  }
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+
+  load 'nitrogen/generated/ios/FastJson+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 ifeoluwa
+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,162 @@
+# react-native-fast-json
+
+**`JSON.parse`** turns the whole file into nested JavaScript objects in the same memory as your app code. That is fine for small JSON; for **very large files** (on the order of **tens to hundreds of MB**), it often means:
+
+- CPU stays pegged high while parsing finishes  
+- The screen **freezes or stutters**  
+- Memory use jumps; in bad cases the app is **killed for using too much memory**  
+
+**This library** parses in **native** code with [simdjson](https://github.com/simdjson/simdjson) and exposes a **`JsonView`** through [Nitro Modules](https://nitro.margelo.com/)—you read the document **lazily** from native memory instead of inflating everything into one giant JavaScript tree up front.
+
+**Rough illustration** for a **~250 MB** file (device and JSON shape will change this):
+
+| | `JSON.parse` | `parseFile` + root `JsonView` |
+| --- | --- | --- |
+| **Parse / load** | Often **many seconds** on a phone (every object is allocated in JS) | Native read + parse often **~100 ms** for the same **~250 MB**—**near-instant** at UI scale; exact time depends on disk and CPU |
+| **CPU** | Long spikes (often **>100%** in system monitors) | **Calmer** during native load/parse |
+| **Memory (ballpark)** | **~1.2 GB** in a heavy case | **~400 MB** (the file still has to live somewhere) |
+
+These numbers are **illustrative only**—measure your own file on real hardware before you budget.
+
+## When to use it
+
+- Large JSON (for example **~100–200 MB+**: catalogs, offline bundles, big dumps) where **`JSON.parse`** feels too slow, freezes the UI, or uses too much memory.
+- Mostly **read-only**, **targeted** access: a few keys, paths, or scalars.
+
+Prefer normal **`JSON.parse`** for small responses and whenever you need the full tree as plain JS objects anyway.
+
+## Requirements
+
+- React Native with the setup expected by Nitro (see [Nitro docs](https://nitro.margelo.com/)).
+- **`react-native-nitro-modules`** as a dependency (peer).
+
+## Installation
+
+```sh
+yarn add react-native-fast-json react-native-nitro-modules
+# or
+npm install react-native-fast-json react-native-nitro-modules
+```
+
+Then install iOS pods from your app root:
+
+```sh
+cd ios && pod install
+```
+
+Rebuild the native app after adding the dependency.
+
+## Usage
+
+```ts
+import { fastJson, type JsonView } from 'react-native-fast-json';
+
+// From a JSON string (loads into native memory; not cached by path)
+const root = await fastJson.parseString(jsonString);
+if (!root) return;
+
+//Preferred - From a file path (native reads the file; result is cached per path)
+const fromFile = await fastJson.parseFile('/path/to/data.json');
+
+// Drop cached parse for that path when you are done (see Memory below)
+fastJson.release('/path/to/data.json');
+```
+
+### `JsonView`
+
+Navigate and read values without building a full JS tree up front:
+
+| Method / property | Purpose |
+|-------------------|--------|
+| `getValue(key)` | Single object key (not a path). Returns `JsonView \| null`. |
+| `keys()` | Keys for objects / arrays (as applicable). |
+| `at(index)` | Array element by index. |
+| `atPath('$.a.b.c')` | Simple dotted path from `$` (no `[index]` in path). |
+| `atPathWithWildcard('$.items[*].id')` | Wildcard / index segments; returns `string[] \| null`. |
+| `type`, `length` | Value kind and length (objects/arrays). |
+| `asString()`, `asNumber()`, `asBoolean()` | Scalar coercion. |
+| `asObject()` | Materialize object/array into an `AnyMap` (expensive for large values). |
+| `rawJson()` | Raw JSON slice as string (can be expensive for large values). |
+
+Example:
+
+```ts
+const meta = root.getValue('metadata');
+const version = meta?.getValue('version')?.asString();
+```
+
+## Memory and caching
+
+### How big is “big”?
+
+Native memory for a parse is dominated by the **root buffer**, which is roughly **the JSON byte size plus simdjson padding** (think **on the order of the file size**, not “a few MB overhead”).
+
+| Rough file size | What to expect |
+|-----------------|------------------|
+| **Under ~10 MB** | Usually fine to keep a root around for a screen session if you need repeated lazy access. |
+| **~10–50 MB** | Still workable; treat the root as a **large native allocation** and avoid keeping multiple overlapping parses. |
+| **~50–200 MB** | High impact on device RAM and OOM risk if you stack parses or retain roots in global state. Plan **`release(path)`** and avoid `rawJson` / `asObject` on the whole document. |
+| **200 MB+** | Same as above, but stricter: **short-lived root**, extract what you need, then drop handles immediately (see below). |
+
+These are ballparks—actual pressure depends on device, OS, and what else your app keeps in JavaScript memory versus native (C++) memory.
+
+### Prefer a short-lived root: read what you need, then discard
+
+**Do not** keep the root `JsonView` in React state, context, or a singleton for the whole app lifetime unless you truly need random access to that document for a long time.
+
+A safer pattern for large files:
+
+1. **`parseFile`** (or `parseString`) once when you need the data.
+2. In the **same synchronous stretch** (or one small async function), walk the tree and **copy** primitives, small objects, or IDs into **plain JavaScript** values you actually store in state.
+3. **Clear** your `JsonView` references and call **`release(path)`** for file parses so the native cache and buffer can go away.
+
+```ts
+async function loadConfig(path: string) {
+  const root = await fastJson.parseFile(path);
+  try {
+    const version = root?.getValue('metadata')?.getValue('version')?.asString();
+    const batchSize = root
+      ?.atPath('$.metadata.configuration.export_settings.batch_size')
+      ?.asNumber();
+    return { version, batchSize }; // plain JS — safe to keep
+  } finally {
+    fastJson.release(path);
+  }
+}
+```
+
+That way you pay the large native buffer only while you extract fields—not for the entire time the user has the app open.
+
+If you **do** need the root for a while (e.g. a deep drill-down UI over the same file), keep **one** root per path, avoid overlapping second parses of the same huge file, and still **`release`** when the user leaves the flow.
+
+### Other rules of thumb
+
+- **Root `JsonView`** holds the **full parsed buffer** in native memory (file size + padding for `parseFile`, string size for `parseString`).
+- **`parseFile(path)`** caches the native view **by path string**. Repeated `parseFile` with the same path returns the same cached root until **`release(path)`** removes it.
+- **`parseString`** does **not** use that path cache; each call allocates a new native view for that string (until the JS side drops the `JsonView`).
+- **`getValue` / `at` / paths** may create **child** views that copy JSON slices into their own buffers. Holding many large subtrees can add up.
+- **`rawJson()`** and **`asObject()`** on very large values can allocate **large** extra memory (strings / maps). Use sparingly on big documents.
+
+If you only need a subtree in JavaScript, you can still hold just that subtree—but while **`parseFile`** keeps the root in the path cache, the **full file buffer** stays in native memory until you **`release`** that path (and nothing else retains the view).
+
+## API summary
+
+| Method | Description |
+|--------|-------------|
+| `parseString(str)` | Parse JSON from a string. |
+| `parseFile(path)` | Load and parse JSON from a filesystem path; cached by `path`. |
+| `release(path)` | Remove cached parse for `path` (file cache only). |
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/android/CMakeLists.txt

@@ -0,0 +1,37 @@
+project(fastjson)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME fastjson)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(
+        ${PACKAGE_NAME}
+        SHARED
+        src/main/cpp/cpp-adapter.cpp
+        ../cpp/third_party/simdjson.cpp
+        ../cpp/HybridJsonView.cpp
+        ../cpp/HybridFastJson.cpp
+)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/fastjson+autolinking.cmake)
+
+# simdjson amalgamation + project C++
+target_include_directories(
+        ${PACKAGE_NAME}
+        PRIVATE
+        src/main/cpp
+        ../cpp
+        ../cpp/third_party
+)
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,119 @@
+buildscript {
+  ext.FastJson = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return FastJson[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/fastjson+autolinking.gradle'
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.margelo.nitro.fastjson"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        // Match iOS FastJson.podspec: fast simdjson in Debug app builds too (consumers debug JS, not this native code).
+        buildTypes {
+          debug {
+            cppFlags "-O3 -DNDEBUG"
+          }
+          release {
+            cppFlags "-O3 -DNDEBUG"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":react-native-nitro-modules")
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,11 @@
+#include <jni.h>
+#include "fastjsonOnLoad.hpp"
+
+#include <fbjni/fbjni.h>
+
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::fastjson::registerAllNatives();
+  });
+}

package/android/src/main/java/com/margelo/nitro/fastjson/FastJsonPackage.kt

@@ -0,0 +1,22 @@
+package com.margelo.nitro.fastjson
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class FastJsonPackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider { HashMap() }
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("fastjson")
+        }
+    }
+}

package/cpp/HybridFastJson.cpp

@@ -0,0 +1,61 @@
+#include "HybridFastJson.hpp"
+
+#include <NitroModules/Promise.hpp>
+#include "HybridJsonView.hpp"
+
+#include <simdjson.h>
+
+namespace margelo::nitro::fastjson
+{
+
+  std::unordered_map<std::string, std::shared_ptr<HybridJsonViewSpec>> jsonStrings;
+
+  HybridFastJson::HybridFastJson() : HybridObject(TAG) {}
+
+  /**
+   * Parses a JSON string and returns a Promise that resolves to a JsonViewSpec.
+   * Not ideal, prefer parseFile or use simple JSON.parse if possible.
+   * @param str The JSON string.
+   * @returns A Promise that resolves to a JsonViewSpec or null. Not cached (unlike parseFile).
+   */
+  std::shared_ptr<Promise<ParseResult>> HybridFastJson::parseString(const std::string &str)
+  {
+    std::shared_ptr<HybridJsonView> view = std::make_shared<HybridJsonView>();
+    view->pstr = str;
+
+    std::shared_ptr<HybridJsonViewSpec> asSpec = view;
+
+    return Promise<ParseResult>::resolved(ParseResult{std::move(asSpec)});
+  }
+
+
+  /**
+   * Parses a JSON file and returns a Promise that resolves to a JsonViewSpec.
+   * No check is done if invalid path is provided. Error handling is left to the caller.
+   * @param path The path to the JSON file.
+   * @returns A Promise that resolves to a JsonViewSpec or null. Response is cached for future calls.
+   */
+  std::shared_ptr<Promise<ParseResult>> HybridFastJson::parseFile(const std::string& path)
+  {
+    if (jsonStrings.find(path) != jsonStrings.end())
+    {
+      return Promise<ParseResult>::resolved(ParseResult{jsonStrings[path]});
+    }
+
+    std::shared_ptr<HybridJsonView> view = std::make_shared<HybridJsonView>();
+    view->pstr = simdjson::padded_string::load(path);
+
+    std::shared_ptr<HybridJsonViewSpec> asSpec = view;
+
+    jsonStrings[path] = asSpec;
+
+    return Promise<ParseResult>::resolved(ParseResult{asSpec});
+  }
+
+
+  void HybridFastJson::release(const std::string &source)
+  {
+    jsonStrings.erase(source);
+  }
+
+} // namespace margelo::nitro::fastjson

package/cpp/HybridFastJson.hpp

@@ -0,0 +1,19 @@
+#pragma once
+
+#include "HybridFastJsonSpec.hpp"
+#include "HybridJsonViewSpec.hpp"
+
+namespace margelo::nitro::fastjson {
+
+using ParseResult = std::variant<nitro::NullType, std::shared_ptr<HybridJsonViewSpec>>;
+
+class HybridFastJson : public HybridFastJsonSpec {
+public:
+  HybridFastJson();
+
+  std::shared_ptr<Promise<std::variant<nitro::NullType, std::shared_ptr<HybridJsonViewSpec>>>> parseString(const std::string& str) override;
+  std::shared_ptr<Promise<std::variant<nitro::NullType, std::shared_ptr<HybridJsonViewSpec>>>> parseFile(const std::string& path) override;
+  void release(const std::string& source) override;
+};
+
+} // namespace margelo::nitro::fastjson