fix(nitrogen): look up Kotlin callbacks with a boxed return type

[giaBaoJS]

What breaks

packages/nitrogen/src/syntax/kotlin/KotlinFunction.ts:142 builds the JNI signature of the generated JFunc_X::invoke() from the plain JNI type of the callback's return type. For Sync<() => number> that is double():

double invoke() const {
  static const auto method = javaClassStatic()->getMethod<double()>("invoke");
  auto __result = method(self());
  return __result;
}

The Kotlin half of the same callback is a fun interface that extends the Kotlin function type:

fun interface Func_double: () -> Double {
  override fun invoke(): Double
}

invoke overrides Function0<R>.invoke, and kotlinc cannot specialize a generic return type to a JVM primitive, so it keeps the boxed type. Parameters are specialized (kotlinc adds a (Ljava/lang/Object;)Ljava/lang/Object; bridge for them), return types are not.

fbjni resolves methods by exact descriptor, so the Android build does not catch this. GetMethodID finds nothing and the call throws NoSuchMethodError.

Ground truth

kotlinc 2.4.10 + javap -p -s, on the exact fun interface shape nitrogen generates:

Kotlin declaration	what kotlinc emits	what nitrogen looked up
fun interface F: () -> Double	invoke ()Ljava/lang/Double;	()D
fun interface F: () -> Boolean	invoke ()Ljava/lang/Boolean;	()Z
fun interface F: () -> Long	invoke ()Ljava/lang/Long;	()J
fun interface F: () -> Unit	invoke ()V	()V (already correct)
fun interface F: (Double) -> Unit	invoke (D)V	(D)V (already correct)
fun interface F: () -> String	invoke ()Ljava/lang/String;	same (already correct)

Unit is the exception: it maps to void, so a void callback was fine. Every other primitive return was broken.

When it fires

Only when the callback was implemented in Kotlin. A callback that came from JS is a Func_X_cxx, and KotlinCxxBridgedType unwraps that via getFunction() without ever touching JNI. Anything else falls into JNICallable<JFunc_X, R(Args...)>, which calls JFunc_X::invoke().

That is why CI never hit it: react-native-nitro-test used Func_double only as a parameter (callbackSync), never as a value handed from Kotlin to C++.

iOS is unaffected, Swift closures do not go through this path.

Fix

KotlinFunction.ts now boxes the return type of the invoke lookup for the primitive kinds, and unboxes __result with the existing parseFromKotlinToCpp(.., isBoxed) machinery:

double invoke() const {
  static const auto method = javaClassStatic()->getMethod<jni::local_ref<jni::JDouble>()>("invoke");
  auto __result = method(self());
  return __result->value();
}

std::optional<double> returns already emitted jni::local_ref<jni::JDouble>, so they were correct before and are untouched.

Test

One method on SharedTestObjectProps, in the "Sync funcs" block next to the existing callbackSync:

getSyncNumberCallback(): Sync<() => number>

plus one assertion in example/src/getTests.ts, so the Harness workflows cover it on both platforms. It reuses the Func_double specialization that callbackSync already generates, this time in the return direction, which is the direction that was broken.

How I proved it

I compiled the generated Kotlin (nitrogen/generated/android/kotlin, minus the ViewManagers, which need React Native on the classpath) with kotlinc, then checked every getField / getMethod lookup in nitrogen/generated/android/c++ against javap -p -s on the resulting class files.

Before the fix, one lookup did not exist:

('JFunc_double.hpp', 'com.margelo.nitro.test.Func_double', 'invoke', 'Method', '()D', ['()Ljava/lang/Double;', '()Ljava/lang/Object;'])
1 signature problems

Resolving that descriptor the way GetMethodID does:

MISSING  com.margelo.nitro.test.Func_double.invoke()D
FOUND    com.margelo.nitro.test.Func_double.invoke()Ljava/lang/Double;

After the fix, all 339 JNI names and descriptors emitted for react-native-nitro-test match the compiler, with no exceptions:

0 signature problems

I also checked the fix is not vacuous by mutating it in the other direction (boxing to jni::JLong instead of jni::JDouble), which the same check catches as ()Ljava/lang/Long; vs ()Ljava/lang/Double;.

Not covered

UInt64 callbacks are broken in a different way and are out of scope here: ULong is a value class, so kotlinc mangles the whole method name (invoke-s-VKNKU for a ULong return, invoke-VKZWuLQ for a ULong parameter). Boxing does not help there, so I left that path exactly as it was. Happy to open a separate issue for it.

Checks

• bun specs run, generated files committed. Apart from the new method, the only generated change is JFunc_double.hpp and some include reordering.
• bun run build, bun typecheck, bun lint, bun lint-cpp, bun lint-swift, bun lint-kotlin: all clean, no files changed by the formatters.
• I could not run the Harness suite here (no Android device), so the new runtime assertion is verified by CI, not locally. The compiler evidence above is what I verified locally.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
nitro-docs	Skipped		Sep 7, 2026 6:58pm UTC

[mrousavy]

We should avoid boxing for performance reasons. Maybe we can add a (private?) method called invokeDirect(..), and invoke(): Double would call invokeDirect if it is a primitive. I'll think about this

[mrousavy]

Probably this PR is fine to be merged at first, and then a follow-up PR to make it faster (with the invokeDirect(..)) - that splits it up nicely and atomically. Can you do that?

[mrousavy]

I am also not sure if that even makes things faster, I think that needs to actually be benchmarked. Not sure what the JVM does under the hood in this case.

[giaBaoJS]

Yes, I can do that. This PR stays as the correctness fix, and I will open a separate PR for invokeDirect once this one is in.

On your third point, I did not want to assume boxing is expensive, so I measured what the JVM does with it. Method: OpenJDK 17 on arm64 macOS, an interface returning Double against one returning double, 20M calls after warmup, allocation from ThreadMXBean.getThreadAllocatedBytes, time as best of 7 reps.

                       alloc       time
primitive double       0 B/op      0.494 ns/op
boxed, non-escaping    0 B/op      0.512 ns/op
boxed, escaping       24 B/op      1.595 ns/op

Two things come out of that:

• Double has no valueOf cache, unlike Integer, so a boxed return is always a fresh allocation.
• Escape analysis removes that allocation entirely when the box does not escape. It only costs anything when it does, which is our case: the box is handed to C++ as a jobject, so it cannot be scalar replaced.

So the ceiling for invokeDirect looks like roughly 1 ns and 24 bytes per call. That is HotSpot on a desktop with no JNI in the loop. I have not measured the path that actually matters, which is ART on device plus the JNI crossing and a local ref for the returned object, so I would not carry these numbers over. The follow-up will lead with a benchmark there rather than with an assumption.

One thing I ran into while looking at it: fun interface Func_X: () -> R can only have one abstract member, so invokeDirect cannot just be added next to invoke. And Func_X_java wraps a () -> Double, which is a Function0<Double> and boxes on its own before the JNI call happens at all. Avoiding the box end to end may mean the generated interface stops extending FunctionN, not just gaining a method. I will work that out in the follow-up.

Rebased on main, this is mergeable again.

[mrousavy]

• It only costs anything when it does, which is our case: the box is handed to C++ as a jobject

But thats literally what I'm saying, that C++ does not accept jobject but instead double directly. A fast path for primitive.s

[mrousavy]

code is bad, pls fix

[mrousavy]

What? This does not make sense and looks like AI slop. .asJniReference('local') gives you jni::local_ref<...>, so this ternary here adds exactly what the method already does, just more complex code. Was this generated by GPT-1 on ultra-low?

[giaBaoJS]

Simplified. The boxing decision moved into KotlinCxxBridgedType, so the call site is now a single asJniReferenceType('local', isReturnBoxed) and the hand-built jni::local_ref<...> string is gone. Generated output is byte-identical.

On the redundancy: asJniReferenceType returns a bare primitive for exactly the kinds this PR is about.

case 'void':
case 'number':
case 'boolean':
case 'int64':
  // primitives are not references
  return this.getTypeCode('c++')

So () => number produced getMethod<double()>("invoke"), i.e. ()D. The compiled fun interface Func_double: () -> Double only has:

invoke  ->  ()Ljava/lang/Double;
invoke  ->  ()Ljava/lang/Object;

Parameters do specialize, (Double) -> Double compiles to (D)Ljava/lang/Double;. Only the return stays generic.

Separate finding while measuring: UInt64 returns are broken too, but boxing does not fix them. () -> ULong compiles to invoke-s-VKNKU -> ()J plus the ()Ljava/lang/Object; bridge, so there is no method named invoke to resolve at all. Kept out of this PR. Happy to add a nitrogen error for it if you want.

[mrousavy]

~

[mrousavy]

~

[mrousavy]

But yea invokeDirect will probably not work.

[github-actions]

Performance Report

⚠️ Advisory: Results do not fail this PR while the baseline is being calibrated.

iOS

Benchmark	Before	After	Difference
C++ small array (16)	1.19 µs	1.60 µs	🔴 +35.12% slower
C++ nested Car struct	3.45 µs	4.39 µs	🔴 +27.3% slower

All Benchmarks

Benchmark	Before	After	Difference
JavaScript addNumbers()	44.3 ns	48.4 ns	🟡 +9.17% slower (noisy)
C++ bounce(1 MiB)	604.3 ns	526.7 ns	🟡 -12.85% faster (noisy)
C++ bounce(4 KiB)	524.1 ns	592.7 ns	🟡 +13.1% slower (noisy)
C++ copy(1 MiB)	118.67 µs	117.85 µs	🟡 -0.69% faster (noisy)
C++ copy(4 KiB)	2.12 µs	1.96 µs	🟡 -7.27% faster (noisy)
C++ large array (1,024)	71.26 µs	77.88 µs	🟡 +9.28% slower (noisy)
C++ synchronousCallback()	456.7 ns	415.9 ns	🟡 -8.92% faster (noisy)
C++ create()	883.7 ns	852.7 ns	🟡 -3.51% faster (noisy)
C++ returnExisting()	394.4 ns	362.5 ns	🟡 -8.1% faster (noisy)
C++ typed map (8 entries)	2.95 µs	3.24 µs	🟡 +9.83% slower (noisy)
C++ optional trailing string	258.5 ns	319.3 ns	🟡 +23.5% slower (noisy)
C++ addNumbers()	162.3 ns	168.4 ns	🟡 +3.76% slower (noisy)
C++ simpleFunc()	129.5 ns	157.9 ns	🟡 +21.95% slower (noisy)
C++ immediatePromise()	1.68 µs	1.71 µs	ℹ️ +1.71% slower (advisory)
C++ number property get/set	250.7 ns	259.3 ns	🟡 +3.46% slower (noisy)
C++ short ASCII string	231.2 ns	258.6 ns	🟡 +11.86% slower (noisy)
C++ Unicode string	487.5 ns	560.8 ns	🟡 +15.04% slower (noisy)
C++ number | string variant	266.5 ns	277.9 ns	🟡 +4.26% slower (noisy)
Swift bounce(1 MiB)	605.0 ns	562.1 ns	🟡 -7.08% faster (noisy)
Swift bounce(4 KiB)	578.3 ns	553.8 ns	🟡 -4.24% faster (noisy)
Swift copy(1 MiB)	115.57 µs	110.62 µs	🟡 -4.28% faster (noisy)
Swift copy(4 KiB)	2.12 µs	2.13 µs	🟡 +0.28% slower (noisy)
Swift large array (1,024)	74.90 µs	85.47 µs	🟡 +14.11% slower (noisy)
Swift small array (16)	1.79 µs	1.77 µs	🟡 -1.49% faster (noisy)
Swift synchronousCallback()	512.7 ns	513.9 ns	🟡 +0.25% slower (noisy)
Swift create()	43.81 µs	50.59 µs	🟡 +15.48% slower (noisy)
Swift returnExisting()	494.6 ns	455.6 ns	🟡 -7.89% faster (noisy)
Swift typed map (8 entries)	5.15 µs	4.59 µs	🟡 -10.83% faster (noisy)
Swift optional trailing string	313.6 ns	286.9 ns	🟡 -8.52% faster (noisy)
Swift addNumbers()	159.2 ns	156.2 ns	🟡 -1.88% faster (noisy)
Swift simpleFunc()	134.0 ns	137.1 ns	🟡 +2.33% slower (noisy)
Swift immediatePromise()	2.79 µs	2.71 µs	ℹ️ -3.04% faster (advisory)
Swift number property get/set	288.1 ns	294.9 ns	🟡 +2.38% slower (noisy)
Swift short ASCII string	340.5 ns	334.2 ns	🟡 -1.85% faster (noisy)
Swift Unicode string	747.7 ns	756.8 ns	🟡 +1.21% slower (noisy)
Swift nested Car struct	3.91 µs	4.56 µs	🟡 +16.58% slower (noisy)
Swift number | string variant	404.7 ns	404.9 ns	🟡 +0.06% slower (noisy)
TurboModule addNumbers()	1.72 µs	2.06 µs	🟡 +19.31% slower (noisy)

Android

Benchmark	Before	After	Difference
C++ synchronousCallback()	506.4 ns	480.3 ns	🟢 -5.15% faster
C++ simpleFunc()	132.6 ns	141.3 ns	🔴 +6.57% slower

All Benchmarks

Benchmark	Before	After	Difference
JavaScript addNumbers()	43.6 ns	43.8 ns	⚪ ~0.58% unchanged
C++ bounce(1 MiB)	623.8 ns	609.5 ns	🟡 -2.29% faster (noisy)
C++ bounce(4 KiB)	635.7 ns	616.9 ns	🟡 -2.95% faster (noisy)
C++ copy(1 MiB)	33.11 µs	32.91 µs	⚪ ~0.6% unchanged
C++ copy(4 KiB)	1.45 µs	1.45 µs	🟡 -0.25% faster (noisy)
C++ large array (1,024)	83.09 µs	83.13 µs	⚪ ~0.05% unchanged
C++ small array (16)	1.69 µs	1.70 µs	⚪ ~0.46% unchanged
C++ create()	1.05 µs	1.01 µs	🟡 -3.24% faster (noisy)
C++ returnExisting()	377.2 ns	386.3 ns	⚪ ~2.42% unchanged
C++ typed map (8 entries)	3.36 µs	3.30 µs	⚪ ~1.7% unchanged
C++ optional trailing string	273.5 ns	280.2 ns	⚪ ~2.44% unchanged
C++ addNumbers()	168.2 ns	171.0 ns	⚪ ~1.67% unchanged
C++ immediatePromise()	1.72 µs	1.74 µs	ℹ️ +1.52% slower (advisory)
C++ number property get/set	269.8 ns	282.1 ns	⚪ ~4.57% unchanged
C++ short ASCII string	241.6 ns	245.1 ns	⚪ ~1.47% unchanged
C++ Unicode string	533.7 ns	533.6 ns	⚪ ~0.02% unchanged
C++ nested Car struct	4.43 µs	4.46 µs	⚪ ~0.67% unchanged
C++ number | string variant	257.8 ns	251.2 ns	⚪ ~2.56% unchanged
Kotlin bounce(1 MiB)	1.78 µs	1.80 µs	⚪ ~1.15% unchanged
Kotlin bounce(4 KiB)	1.80 µs	1.78 µs	⚪ ~0.79% unchanged
Kotlin copy(1 MiB)	447.04 µs	441.21 µs	⚪ ~1.3% unchanged
Kotlin copy(4 KiB)	8.76 µs	8.63 µs	🟡 -1.43% faster (noisy)
Kotlin large array (1,024)	92.18 µs	91.54 µs	⚪ ~0.7% unchanged
Kotlin small array (16)	2.30 µs	2.26 µs	⚪ ~1.55% unchanged
Kotlin synchronousCallback()	1.72 µs	1.71 µs	⚪ ~0.21% unchanged
Kotlin create()	3.02 µs	3.05 µs	🟡 +1.14% slower (noisy)
Kotlin returnExisting()	1.22 µs	1.27 µs	🟡 +4.21% slower (noisy)
Kotlin typed map (8 entries)	13.22 µs	13.23 µs	⚪ ~0.06% unchanged
Kotlin optional trailing string	687.9 ns	700.1 ns	⚪ ~1.77% unchanged
Kotlin addNumbers()	263.3 ns	267.9 ns	⚪ ~1.75% unchanged
Kotlin simpleFunc()	207.1 ns	213.6 ns	⚪ ~3.16% unchanged
Kotlin immediatePromise()	4.60 µs	4.58 µs	ℹ️ -0.33% faster (advisory)
Kotlin number property get/set	546.4 ns	553.6 ns	🟡 +1.31% slower (noisy)
Kotlin short ASCII string	928.8 ns	935.0 ns	⚪ ~0.68% unchanged
Kotlin Unicode string	1.49 µs	1.50 µs	⚪ ~0.49% unchanged
Kotlin nested Car struct	9.65 µs	9.61 µs	⚪ ~0.38% unchanged
Kotlin number | string variant	871.9 ns	859.0 ns	⚪ ~1.48% unchanged
TurboModule addNumbers()	550.7 ns	529.5 ns	⚪ ~3.85% unchanged

Benchmarking Code Diff fe50d8fc...30bff400 (view raw output)

[mrousavy]

I wonder if we even need this information. Can't we just always pass true to asJniReferenceType(..., true)?

I guess if it's void it shouldn't generate jni::local_ref<void>, but that logic could be handled inside asJniReferenceType(...) too right? Like returning void for 'void' in the switch...

[vercel]

@mrousavy is attempting to deploy a commit to the Margelo Team on Vercel.

A member of the Team first needs to authorize it.