react-native-ultra-base64 0.1.5

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Alex Shumihin
+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,378 @@
+# ⚡ react-native-ultra-base64
+
+**The fastest base64 encoding/decoding library for React Native**
+
+Ultra-fast base64 operations powered by optimized C++ with JSI bindings. Built for performance-critical applications that need blazing-fast base64 encoding and decoding.
+
+[![npm version](https://img.shields.io/npm/v/react-native-ultra-base64.svg)](https://www.npmjs.com/package/react-native-ultra-base64)
+[![license](https://img.shields.io/npm/l/react-native-ultra-base64.svg)](https://github.com/pioner92/react-native-ultra-base64/blob/main/LICENSE)
+[![platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android-lightgrey.svg)](https://github.com/pioner92/react-native-ultra-base64)
+
+---
+
+## 🚀 Why Choose This Library?
+
+- **🏎️ Blazing Fast** - Up to **2x faster** than react-native-quick-base64 v3
+- **⚡ Zero Bridge Overhead** - Direct JSI bindings eliminate React Native bridge bottleneck
+- **🌐 URL-Safe Support** - Native support for URL-safe base64 encoding/decoding
+- **📦 Small Bundle** - Minimal JavaScript footprint, heavy lifting done in native code
+- **🔒 Type Safe** - Full TypeScript support with comprehensive type definitions
+- **✅ Battle Tested** - Extensive test suite covering edge cases and compatibility
+
+---
+
+## 📊 Performance
+
+Benchmark against **react-native-quick-base64 v3**
+
+| iPhone | Android |
+| ------ | ------- |
+| <img src="./assets/iphone.png" height="600"> | <img src="./assets/android.png" height="600"> |
+
+
+> 💡 **Performance scales with data size** - the larger your data, the more dramatic the improvement!
+
+---
+
+## 📦 Installation
+
+```sh
+npm install react-native-ultra-base64
+```
+
+or
+
+```sh
+yarn add react-native-ultra-base64
+```
+
+### iOS Setup
+
+```sh
+cd ios && pod install
+```
+
+### Android Setup
+
+No additional steps required! The library will automatically link.
+
+---
+
+## 🎯 Quick Start
+
+```typescript
+import {
+  fromByteArray,
+  toByteArray,
+  byteLength,
+  trimBase64Padding
+} from 'react-native-ultra-base64';
+
+// 🔵 Encode to base64
+const data = new Uint8Array([72, 101, 108, 108, 111]);
+const encoded = fromByteArray(data);
+console.log(encoded); // "SGVsbG8="
+
+// 🔵 Decode from base64
+const decoded = toByteArray('SGVsbG8=');
+console.log(decoded); // Uint8Array [72, 101, 108, 108, 111]
+
+// 🔵 Get byte length without decoding
+const length = byteLength('SGVsbG8=');
+console.log(length); // 5
+
+// 🔵 URL-safe base64
+const urlSafeEncoded = fromByteArray(data, true);
+console.log(urlSafeEncoded); // Uses '-' and '_' instead of '+' and '/'
+```
+
+---
+
+## 📖 API Reference
+
+### `fromByteArray(uint8: Uint8Array, urlSafe?: boolean): string`
+
+Encodes a `Uint8Array` to a base64 string.
+
+**Parameters:**
+- `uint8` - The byte array to encode
+- `urlSafe` (optional) - Use URL-safe encoding (replaces `+/` with `-_` and omits padding)
+
+**Returns:** Base64 encoded string
+
+**Example:**
+```typescript
+const bytes = new Uint8Array([255, 254, 253]);
+const standard = fromByteArray(bytes); // "//79"
+const urlSafe = fromByteArray(bytes, true); // "__79"
+```
+
+---
+
+### `toByteArray(input: string, removeLinebreaks?: boolean): Uint8Array`
+
+Decodes a base64 string to a `Uint8Array`.
+
+**Parameters:**
+- `input` - The base64 string to decode
+- `removeLinebreaks` (optional) - Remove `\n` and `\r` before decoding
+
+**Returns:** Decoded byte array
+
+**Example:**
+```typescript
+const decoded = toByteArray('SGVsbG8=');
+console.log(decoded); // Uint8Array [72, 101, 108, 108, 111]
+
+// Handle base64 with linebreaks
+const withLinebreaks = 'SGVs\nbG8=';
+const cleaned = toByteArray(withLinebreaks, true);
+```
+
+**Throws:** `Error` if input is not valid base64
+
+---
+
+### `byteLength(b64: string): number`
+
+Calculates the byte length of a base64 string **without decoding**.
+
+**Parameters:**
+- `b64` - The base64 string
+
+**Returns:** Number of bytes the decoded data would be
+
+**Example:**
+```typescript
+const length = byteLength('SGVsbG8=');
+console.log(length); // 5 (much faster than decoding)
+```
+
+---
+
+### `trimBase64Padding(str: string): string`
+
+Removes trailing padding characters (`=`) from a base64 string.
+
+**Parameters:**
+- `str` - The base64 string
+
+**Returns:** String without padding
+
+**Example:**
+```typescript
+const padded = 'SGVsbG8=';
+const trimmed = trimBase64Padding(padded);
+console.log(trimmed); // "SGVsbG8"
+```
+
+## 🎨 Advanced Examples
+
+### Working with Images
+
+```typescript
+import { toByteArray, fromByteArray } from 'react-native-ultra-base64';
+import RNFS from 'react-native-fs';
+
+// Load and decode base64 image
+async function loadImage(base64Data: string) {
+  const imageBytes = toByteArray(base64Data);
+  const path = `${RNFS.CachesDirectoryPath}/image.jpg`;
+  await RNFS.writeFile(path, imageBytes, 'base64');
+  return path;
+}
+
+// Encode image to base64
+async function encodeImage(filePath: string) {
+  const fileData = await RNFS.readFile(filePath, 'base64');
+  const bytes = toByteArray(fileData);
+  return fromByteArray(bytes);
+}
+```
+
+### Processing Large Files
+
+```typescript
+import { toByteArray, fromByteArray } from 'react-native-ultra-base64';
+
+// Efficiently process large base64 data
+function processLargeFile(base64String: string) {
+  // Decode (fast!)
+  const bytes = toByteArray(base64String);
+
+  // Process bytes...
+  const processed = bytes.map(byte => byte ^ 0xFF); // Example: invert bits
+
+  // Encode back (still fast!)
+  return fromByteArray(new Uint8Array(processed));
+}
+```
+
+### API Requests with Base64 Bodies
+
+```typescript
+import { fromByteArray, toByteArray } from 'react-native-ultra-base64';
+
+// Send binary data as base64
+async function uploadBinaryData(data: Uint8Array) {
+  const base64 = fromByteArray(data);
+
+  const response = await fetch('https://api.example.com/upload', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ data: base64 })
+  });
+
+  return response.json();
+}
+
+// Receive binary data as base64
+async function downloadBinaryData() {
+  const response = await fetch('https://api.example.com/download');
+  const { data } = await response.json();
+
+  return toByteArray(data); // Returns Uint8Array
+}
+```
+
+### Crypto Integration
+
+```typescript
+import { toByteArray, fromByteArray } from 'react-native-ultra-base64';
+import * as Crypto from 'expo-crypto';
+
+async function encryptAndEncode(plaintext: string) {
+  // Encrypt
+  const encrypted = await Crypto.digestStringAsync(
+    Crypto.CryptoDigestAlgorithm.SHA256,
+    plaintext,
+    { encoding: Crypto.CryptoEncoding.HEX }
+  );
+
+  // Convert hex to bytes
+  const bytes = new Uint8Array(
+    encrypted.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16))
+  );
+
+  // Encode to base64 for transmission
+  return fromByteArray(bytes);
+}
+```
+
+---
+
+## 🔥 Features
+
+- ✅ **Standard & URL-safe base64** - Full RFC 4648 compliance
+- ✅ **Linebreak handling** - Automatically remove `\n` and `\r` during decode
+- ✅ **Padding tolerance** - Handles missing or misplaced padding gracefully
+- ✅ **TypeScript first** - Complete type definitions included
+- ✅ **Zero dependencies** - No runtime dependencies except React Native
+- ✅ **JSI direct bindings** - Bypass the bridge entirely
+- ✅ **Memory efficient** - Optimized memory usage for large data
+- ✅ **Works with Expo** - Compatible with Expo dev builds
+
+---
+
+## 🆚 Comparison with react-native-quick-base64
+
+| Feature | react-native-ultra-base64 | react-native-quick-base64 |
+|---------|--------------------------|---------------------------|
+| **Speed** | ⚡⚡⚡⚡⚡ ~2x faster | ⚡⚡⚡ Fast |
+| **JSI Bindings** | ✅ | ✅ |
+| **URL-safe Support** | ✅ | ✅ |
+| **TypeScript** | ✅ | ✅ |
+| **Bundle Size** | 🟢 Small | 🟢 Small |
+| **Native Code** | C++ (highly optimized) | C++ |
+
+---
+
+## 🏗️ How It Works
+
+This library uses several optimization techniques:
+
+1. **JSI Direct Bindings** - Functions are installed directly on the JavaScript global object, eliminating bridge serialization overhead
+2. **Cache-Aligned Tables** - Lookup tables are aligned to 64-byte boundaries for L1 cache efficiency
+3. **Branch Prediction Hints** - Uses `[[likely]]`/`[[unlikely]]` attributes for optimal branch prediction
+4. **Zero-Copy Operations** - Direct memory access to ArrayBuffers without copying when possible
+5. **Optimized Hot Paths** - Fast path for common cases (99.9%), slow path only for edge cases
+
+---
+
+## 🐛 Troubleshooting
+
+### "encodeBase64FromArrayBuffer is not a function"
+
+Make sure the native module is properly installed and linked:
+
+```sh
+# iOS
+cd ios && pod install
+
+# Clean build
+cd .. && yarn example ios --simulator="iPhone 15"
+```
+
+### TypeScript errors
+
+Ensure you have the latest version installed and TypeScript can find the types:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "moduleResolution": "node"
+  }
+}
+```
+
+### Performance not as expected?
+
+- Ensure you're running a **release build** (debug builds have overhead)
+- Check you're testing with realistic data sizes (>1KB)
+- Verify no other libraries are intercepting base64 operations
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```sh
+# Clone the repo
+git clone https://github.com/pioner92/react-native-ultra-base64.git
+cd react-native-ultra-base64
+
+# Install dependencies
+yarn
+
+# Run example app
+yarn example ios
+# or
+yarn example android
+```
+
+---
+
+## 📄 License
+
+MIT © [Alex Shumihin](https://github.com/pioner92)
+
+---
+
+## 🙏 Acknowledgments
+
+- Inspired by [base64-js](https://github.com/beatgammit/base64-js) and [react-native-quick-base64](https://github.com/craftzdog/react-native-quick-base64)
+- Built with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
+
+---
+
+## ⭐ Show Your Support
+
+If this library helps your project, please give it a ⭐ on [GitHub](https://github.com/pioner92/react-native-ultra-base64)!
+
+---
+
+**Made with ❤️ for the React Native community**

package/android/CMakeLists.txt

@@ -0,0 +1,34 @@
+cmake_minimum_required(VERSION 3.4.1)
+project(react-native-ultra-base64)
+
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 17)
+
+
+add_library(react-native-ultra-base64 SHARED
+        ../cpp/react-native-ultra-base64.cpp
+        ../cpp/simdutf.cpp
+        ../cpp/simdutf.h
+        cpp-adapter.cpp
+)
+
+include_directories(
+            ../cpp
+)
+
+find_package(ReactAndroid REQUIRED CONFIG)
+
+
+if (ReactAndroid_VERSION_MINOR GREATER_EQUAL 76)
+    target_link_libraries(
+            react-native-ultra-base64
+            ReactAndroid::jsi
+            ReactAndroid::reactnative
+    )
+else()
+    target_link_libraries(
+            react-native-ultra-base64
+            ReactAndroid::jsi
+            ReactAndroid::reactnativejni
+)
+endif()

package/android/build.gradle

@@ -0,0 +1,107 @@
+buildscript {
+  def kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : project.properties["RNUltraBase64_kotlinVersion"]
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:7.2.1"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+  }
+}
+
+
+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"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["RNUlid_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["RNUlid_" + name]).toInteger()
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+android {
+  namespace "com.ultrabase64"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-O3 -Wall -ffunction-sections -fdata-sections -fstack-protector-strong"
+        abiFilters (*reactNativeArchitectures())
+        arguments "-DANDROID_STL=c++_shared",
+                  "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  packagingOptions {
+      excludes = [
+            "**/libc++_shared.so",
+            "**/libjsi.so",
+             "**/libreactnativejni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libturbomodulejsijni.so",
+            "**/libc++_shared.so",
+            "**/libfbjni.so",
+            "**/libreactnative.so",
+    ]
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-native:+"
+   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+}

package/android/cpp-adapter.cpp

@@ -0,0 +1,12 @@
+#include <jni.h>
+#include "jsi/jsi.h"
+#include "react-native-ultra-base64.h"
+
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_ultrabase64_UltraBase64Module_nativeInstall (JNIEnv* /*env*/, jobject /*thiz*/, jlong runtimePtr) {
+  auto* rt = reinterpret_cast<facebook::jsi::Runtime*>(runtimePtr);
+  if (!rt) return;
+  rnub_base64::install(rt);
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+RNTurboBase64_kotlinVersion=1.7.0
+RNTurboBase64_minSdkVersion=21
+RNTurboBase64_targetSdkVersion=31
+RNTurboBase64_compileSdkVersion=31
+RNTurboBase64_ndkversion=21.4.7075529

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/java/com/ultrabase64/UltraBase64Module.kt

@@ -0,0 +1,38 @@
+package com.ultrabase64
+
+import android.util.Log
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.common.annotations.FrameworkAPI
+
+class UltraBase64Module(private val reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String {
+        return NAME
+    }
+
+    companion object {
+        const val NAME = "RNUltraBase64"
+        init {
+            System.loadLibrary("react-native-ultra-base64")
+        }
+
+        @OptIn(FrameworkAPI::class)
+        @JvmStatic
+        private external fun nativeInstall(jsiRuntimePtr: Long)
+    }
+
+    @OptIn(FrameworkAPI::class)
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun install(): Boolean {
+        Log.d("react-native-ultra-base64", "install() called")
+        nativeInstall(
+            reactContext.javaScriptContextHolder!!.get(),
+        )
+        return true
+    }
+
+
+}

package/android/src/main/java/com/ultrabase64/UltraBase64Package.kt

@@ -0,0 +1,16 @@
+package com.ultrabase64
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class UltraBase64Package : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+    return listOf(UltraBase64Module(reactContext))
+    }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return emptyList()
+  }
+}