Add BigInt Support to Java Turbo Module (#56018)

Summary:
Pull Request resolved: #56018

This diff adds a getBigInt method to the Java/Kotlin sample Turbo Module,
demonstrating how to use JavaScript BigInt with BigInt bridging on Android.

Changes:
- Updated NativeSampleTurboModule.js with getBigInt method declaration
- Added getBigInt Java method in NativeSampleTurboModuleSpec.java
- Implemented getBigInt in SampleTurboModule.kt using Kotlin's Long type
- Added getBigInt test case in SampleTurboModuleExample.js

On the C++ side, `facebook::react::BigInt` is used as the bridging type.
The Java/JNI layer maps this to Java's `long` type (64-bit signed integer).
JavaScript BigInt values are automatically bridged to/from Java long via the
BigIntKind return type in the JNI bindings.

## Conversion Table
| Type | Bits | Signed | Min | Max |
| --- | --- | --- | --- | --- |
| Java  long | 64 | ✅ | -9.2 × 10¹⁸ | 9.2 × 10¹⁸ |
| C++  int64_t | 64 | ✅ | -9.2 × 10¹⁸ | 9.2 × 10¹⁸ |
| C++  uint64_t | 64 | ❌ | 0 | 1.8 × 10¹⁹ |
| Java  BigInteger | Arbitrary | ✅ | Unbounded | Unbounded |

RESULT -> Any uint64_t value greater than 9,223,372,036,854,775,807 (2⁶³ - 1) cannot be correctly represented in a Java long

## Example:
```java
// Java spec (hand-written, codegen not yet supported for BigInt)
DoNotStrip
public BigInteger getBigInt(BigInteger arg) { return 0; }
```

```kotlin
// Kotlin implementation
override fun getBigInt(arg: BigInteger): BigInteger = arg
```

Reviewed By: sammy-SC

Differential Revision: D95232272

Author: christophpurrer

packages/react-native-codegen/src/generators/modules/GenerateModuleJavaSpec.js

@@ -271,11 +271,8 @@ function translateFunctionParamToJavaType(
       imports.add('com.facebook.react.bridge.Callback');
       return wrapOptional('Callback', isRequired);
     case 'BigIntTypeAnnotation':
-      throw new Error(
-        createErrorMessage(
-          `${realTypeAnnotation.type} is not supported in Java TurboModules yet`,
-        ),
-      );
+      imports.add('java.math.BigInteger');
+      return wrapOptional('BigInteger', isRequired);
     default:
       realTypeAnnotation.type as 'MixedTypeAnnotation';
       throw new Error(createErrorMessage(realTypeAnnotation.type));
@@ -371,11 +368,8 @@ function translateFunctionReturnTypeToJavaType(
       imports.add('com.facebook.react.bridge.WritableArray');
       return wrapOptional('WritableArray', isRequired);
     case 'BigIntTypeAnnotation':
-      throw new Error(
-        createErrorMessage(
-          `${realTypeAnnotation.type} is not supported in Java TurboModules yet`,
-        ),
-      );
+      imports.add('java.math.BigInteger');
+      return wrapOptional('BigInteger', isRequired);
     default:
       realTypeAnnotation.type as 'MixedTypeAnnotation';
       throw new Error(createErrorMessage(realTypeAnnotation.type));
@@ -459,7 +453,7 @@ function getFalsyReturnStatementFromReturnType(
     case 'ArrayTypeAnnotation':
       return 'return null;';
     case 'BigIntTypeAnnotation':
-      throw new Error(createErrorMessage(realTypeAnnotation.type));
+      return nullable ? 'return null;' : 'return BigInteger.ZERO;';
     default:
       realTypeAnnotation.type as 'MixedTypeAnnotation';
       throw new Error(createErrorMessage(realTypeAnnotation.type));

packages/react-native-codegen/src/generators/modules/GenerateModuleJniCpp.js

@@ -299,9 +299,7 @@ function translateParamTypeToJniType(
     case 'Int32TypeAnnotation':
       return !isRequired ? 'Ljava/lang/Double;' : 'D';
     case 'BigIntTypeAnnotation':
-      throw new Error(
-        `${realTypeAnnotation.type} is not supported in Java TurboModules yet`,
-      );
+      return 'Ljava/math/BigInteger;';
     case 'GenericObjectTypeAnnotation':
       return 'Lcom/facebook/react/bridge/ReadableMap;';
     case 'ObjectTypeAnnotation':
@@ -387,9 +385,7 @@ function translateReturnTypeToJniType(
     case 'Int32TypeAnnotation':
       return nullable ? 'Ljava/lang/Double;' : 'D';
     case 'BigIntTypeAnnotation':
-      throw new Error(
-        `${realTypeAnnotation.type} is not supported in Java TurboModules yet`,
-      );
+      return 'Ljava/math/BigInteger;';
     case 'PromiseTypeAnnotation':
       return 'Lcom/facebook/react/bridge/Promise;';
     case 'GenericObjectTypeAnnotation':

packages/react-native/ReactCommon/react/nativemodule/core/platform/android/ReactCommon/JavaTurboModule.cpp

@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <array>
+#include <cstdint>
+#include <limits>
 #include <memory>
 #include <string>
 
@@ -169,6 +172,53 @@ struct JPromiseImpl : public jni::JavaClass<JPromiseImpl> {
   }
 };
 
+struct JBigInteger : public jni::JavaClass<JBigInteger> {
+  constexpr static auto kJavaDescriptor = "Ljava/math/BigInteger;";
+
+  static jni::local_ref<javaobject> valueOf(jlong val) {
+    static const auto cls = javaClassStatic();
+    static const auto method =
+        cls->getStaticMethod<javaobject(jlong)>("valueOf");
+    return method(cls, val);
+  }
+
+  static jni::local_ref<javaobject> fromUint64(uint64_t val) {
+    // For values that fit in int64, use the fast path.
+    if (val <= static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+      return valueOf(static_cast<jlong>(val));
+    }
+    // For values with the high bit set, construct from a big-endian byte
+    // array with a leading zero byte to ensure a positive signum.
+    std::array<jbyte, 9> bytes{};
+    bytes[0] = 0; // sign byte: ensures BigInteger treats this as positive
+    for (int i = 8; i >= 1; --i) {
+      bytes[i] = static_cast<jbyte>(val & 0xFF);
+      val >>= 8;
+    }
+    auto env = jni::Environment::current();
+    auto byteArray = env->NewByteArray(9);
+    env->SetByteArrayRegion(byteArray, 0, 9, bytes.data());
+    return newInstance(byteArray);
+  }
+
+  jlong longValue() const {
+    static const auto method =
+        javaClassStatic()->getMethod<jlong()>("longValue");
+    return method(self());
+  }
+
+  jint bitLength() const {
+    static const auto method =
+        javaClassStatic()->getMethod<jint()>("bitLength");
+    return method(self());
+  }
+
+  jint signum() const {
+    static const auto method = javaClassStatic()->getMethod<jint()>("signum");
+    return method(self());
+  }
+};
+
 // This is used for generating short exception strings.
 std::string stringifyJSIValue(const jsi::Value& v, jsi::Runtime* rt = nullptr) {
   if (v.isUndefined()) {
@@ -322,7 +372,7 @@ JNIArgs convertJSIArgsToJNIArgs(
     return obj;
   };
 
-  for (unsigned int argIndex = 0; argIndex < count; argIndex += 1) {
+  for (int argIndex = 0; argIndex < static_cast<int>(count); argIndex += 1) {
     const std::string& type = methodArgTypes.at(argIndex);
 
     const jsi::Value* arg = &args[argIndex];
@@ -397,6 +447,23 @@ JNIArgs convertJSIArgsToJNIArgs(
       jarg->l = makeGlobalIfNecessary(
           jni::JBoolean::valueOf(static_cast<unsigned char>(arg->getBool()))
               .release());
+    } else if (type == "Ljava/math/BigInteger;") {
+      if (!arg->isBigInt()) {
+        throw JavaTurboModuleArgumentConversionException(
+            "bigint", argIndex, methodName, arg, &rt);
+      }
+      auto bigint = arg->getBigInt(rt);
+      jni::local_ref<JBigInteger::javaobject> javaBigInt;
+      if (bigint.isInt64(rt)) {
+        javaBigInt = JBigInteger::valueOf(bigint.getInt64(rt));
+      } else if (bigint.isUint64(rt)) {
+        javaBigInt = JBigInteger::fromUint64(bigint.getUint64(rt));
+      } else {
+        throw jsi::JSError(
+            rt,
+            "BigInt value cannot be losslessly represented as int64_t or uint64_t");
+      }
+      jarg->l = makeGlobalIfNecessary(javaBigInt.release());
     } else if (type == "Ljava/lang/String;") {
       if (!arg->isString()) {
         throw JavaTurboModuleArgumentConversionException(
@@ -963,6 +1030,42 @@ jsi::Value JavaTurboModule::invokeJavaMethod(
       TMPL::asyncMethodCallEnd(moduleName, methodName);
       return jsPromise;
     }
+    case BigIntKind: {
+      auto returnObject =
+          env->CallObjectMethodA(instance, methodID, jargs.data());
+      checkJNIErrorForMethodCall();
+
+      TMPL::syncMethodCallExecutionEnd(moduleName, methodName);
+      TMPL::syncMethodCallReturnConversionStart(moduleName, methodName);
+
+      auto returnValue = jsi::Value::null();
+      if (returnObject != nullptr) {
+        auto bigIntObj = jni::adopt_local(
+            static_cast<JBigInteger::javaobject>(returnObject));
+
+        // bitLength() returns bits excluding sign bit.
+        // A value fits in int64_t when bitLength() <= 63.
+        // A positive value fits in uint64_t when bitLength() <= 64.
+        auto bits = bigIntObj->bitLength();
+        if (bits <= 63) {
+          returnValue = jsi::BigInt::fromInt64(
+              runtime, static_cast<int64_t>(bigIntObj->longValue()));
+        } else if (bits <= 64 && bigIntObj->signum() >= 0) {
+          // Unsigned 64-bit value: extract low 64 bits via longValue()
+          // and reinterpret as uint64_t.
+          returnValue = jsi::BigInt::fromUint64(
+              runtime, static_cast<uint64_t>(bigIntObj->longValue()));
+        } else {
+          throw jsi::JSError(
+              runtime,
+              "BigInt value cannot be losslessly represented as int64_t or uint64_t");
+        }
+      }
+
+      TMPL::syncMethodCallReturnConversionEnd(moduleName, methodName);
+      TMPL::syncMethodCallEnd(moduleName, methodName);
+      return returnValue;
+    }
     default:
       throw std::runtime_error(
           "Unable to find method module: " + methodNameStr + "(" +

packages/react-native/ReactCommon/react/nativemodule/samples/platform/android/SampleTurboModule.kt

@@ -27,6 +27,7 @@ import com.facebook.react.bridge.WritableNativeMap
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.turbomodule.core.interfaces.BindingsInstallerHolder
 import com.facebook.react.turbomodule.core.interfaces.TurboModuleWithJSIBindings
+import java.math.BigInteger
 import java.util.UUID
 
 @DoNotStrip
@@ -225,6 +226,12 @@ public class SampleTurboModule(private val context: ReactApplicationContext) :
     assert(false) { "Intentional assert from JVM promiseAssert" }
   }
 
+  @DoNotStrip
+  override fun getBigInt(arg: BigInteger): BigInteger {
+    log("getBigInt", arg, arg)
+    return arg
+  }
+
   @DoNotStrip
   @Suppress("unused")
   override fun getImageUrl(promise: Promise) {

packages/react-native/ReactCommon/react/nativemodule/samples/platform/ios/ReactCommon/RCTSampleTurboModule.mm

@@ -210,6 +210,11 @@ - (void)installJSIBindingsWithRuntime:(facebook::jsi::Runtime &)runtime
   RCTAssert(false, @"Intentional assert from ObjC promiseAssert");
 }
 
+RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD(NSNumber *, getBigInt : (NSNumber *)arg)
+{
+  return arg;
+}
+
 @end
 
 Class _Nonnull RCTSampleTurboModuleCls(void)

packages/react-native/src/private/specs_DEPRECATED/modules/NativeSampleTurboModule.js

@@ -43,8 +43,9 @@ export interface Spec extends TurboModule {
   };
   +voidFunc: () => void;
   +getBool: (arg: boolean) => boolean;
-  +getEnum?: (arg: EnumInt) => EnumInt;
+  +getEnum: (arg: EnumInt) => EnumInt;
   +getNumber: (arg: number) => number;
+  +getBigInt: (arg: bigint) => bigint;
   +getString: (arg: string) => string;
   +getArray: (arg: Array<any>) => Array<any>;
   +getObject: (arg: Object) => Object;

packages/rn-tester/js/examples/TurboModule/SampleTurboModuleExample.js

@@ -41,6 +41,7 @@ type Examples =
   | 'getStrEnum'
   | 'getMap'
   | 'getNumber'
+  | 'getBigInt'
   | 'getObject'
   | 'getSet'
   | 'getString'
@@ -94,6 +95,8 @@ class SampleTurboModuleExample extends React.Component<{}, State> {
         ? NativeSampleTurboModule.getEnum(EnumInt.A)
         : null,
     getNumber: () => NativeSampleTurboModule.getNumber(99.95),
+    getBigInt: () =>
+      NativeSampleTurboModule?.getBigInt(BigInt('9223372036854775807')),
     getString: () => NativeSampleTurboModule.getString('Hello'),
     getArray: () =>
       NativeSampleTurboModule.getArray([
@@ -195,7 +198,9 @@ class SampleTurboModuleExample extends React.Component<{}, State> {
     return (
       <View style={styles.result}>
         <RNTesterText style={[styles.value]}>
-          {JSON.stringify(result.value)}
+          {typeof result.value === 'bigint'
+            ? result.value.toString()
+            : JSON.stringify(result.value)}
         </RNTesterText>
         <RNTesterText style={[styles.type]}>{result.type}</RNTesterText>
       </View>

scripts/cxx-api/api-snapshots/ReactAppleDebugCxx.api

@@ -2854,6 +2854,7 @@ protocol NativeSampleTurboModuleSpec : public NSObjectRCTBridgeModule, public RC
   public virtual NSDictionary* getObjectThrows:(NSDictionary* arg);
   public virtual NSDictionary* getUnsafeObject:(NSDictionary* arg);
   public virtual NSDictionary* getValue:y:z:(double x, NSString* y, NSDictionary* z);
+  public virtual NSNumber* getBigInt:(NSNumber* arg);
   public virtual NSNumber* getBool:(BOOL arg);
   public virtual NSNumber* getEnum:(double arg);
   public virtual NSNumber* getNumber:(double arg);

scripts/cxx-api/api-snapshots/ReactAppleReleaseCxx.api

@@ -2854,6 +2854,7 @@ protocol NativeSampleTurboModuleSpec : public NSObjectRCTBridgeModule, public RC
   public virtual NSDictionary* getObjectThrows:(NSDictionary* arg);
   public virtual NSDictionary* getUnsafeObject:(NSDictionary* arg);
   public virtual NSDictionary* getValue:y:z:(double x, NSString* y, NSDictionary* z);
+  public virtual NSNumber* getBigInt:(NSNumber* arg);
   public virtual NSNumber* getBool:(BOOL arg);
   public virtual NSNumber* getEnum:(double arg);
   public virtual NSNumber* getNumber:(double arg);