Async Callbacks, Promises, and Events from Native

Why Native Methods Must Be Async

Callbacks: The Original Pattern

// Kotlin
@ReactMethod
fun readFile(
    path: String,
    successCallback: Callback,
    errorCallback: Callback
) {
    try {
        val content = java.io.File(path).readText()
        successCallback.invoke(content)
    } catch (e: Exception) {
        errorCallback.invoke(e.message)
    }
}

// JavaScript
NativeModules.FileModule.readFile(
  '/data/test.txt',
  (content) => console.log(content),
  (error) => console.error(error)
);

Promises: The Modern Approach

// Kotlin
@ReactMethod
fun fetchUserData(userId: String, promise: Promise) {
    Thread {
        try {
            val data = apiClient.getUser(userId)
            val map = Arguments.createMap()
            map.putString('name', data.name)
            map.putString('email', data.email)
            promise.resolve(map)
        } catch (e: Exception) {
            promise.reject('FETCH_ERROR', e.message, e)
        }
    }.start()
}

// JavaScript
try {
  const user = await NativeModules.UserModule.fetchUserData('123');
  console.log(user.name);
} catch (err) {
  console.error('Failed:', err.message);
}

Promise Rejection Codes and Messages

// Kotlin — structured rejection
@ReactMethod
fun openCamera(promise: Promise) {
    val permission = ContextCompat.checkSelfPermission(
        reactApplicationContext,
        Manifest.permission.CAMERA
    )
    if (permission != PackageManager.PERMISSION_GRANTED) {
        promise.reject(
            'PERMISSION_DENIED',
            'Camera permission is not granted. Please enable it in settings.',
            null
        )
        return
    }
    // proceed...
    promise.resolve(true)
}

// JavaScript
try {
  await NativeModules.CameraModule.openCamera();
} catch (err) {
  if (err.code === 'PERMISSION_DENIED') showSettingsPrompt();
}

Events: Push Data from Native to JS

// Kotlin — emit an event
private fun sendEvent(name: String, data: WritableMap) {
    reactApplicationContext
        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
        .emit(name, data)
}

// Call this from a background task:
val map = Arguments.createMap()
map.putDouble('progress', 0.75)
map.putString('fileName', 'video.mp4')
sendEvent('downloadProgress', map)

Listening to Events in JavaScript

import React, { useEffect, useState } from 'react';
import { NativeModules, NativeEventEmitter } from 'react-native';

const emitter = new NativeEventEmitter(NativeModules.DownloadModule);

export function DownloadScreen() {
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const sub = emitter.addListener('downloadProgress', (event) => {
      setProgress(event.progress);
    });
    return () => sub.remove(); // cleanup
  }, []);

  return <ProgressBar value={progress} />;
}

addListener and removeListeners on iOS

// Swift
@objc(DownloadModule)
class DownloadModule: RCTEventEmitter {

  override func supportedEvents() -> [String]! {
    return ['downloadProgress', 'downloadComplete', 'downloadError']
  }

  // Required boilerplate
  override func addListener(_ eventName: String!) { }
  override func removeListeners(_ count: Double) { }

  func reportProgress(_ pct: Double, file: String) {
    sendEvent(
      withName: 'downloadProgress',
      body: ['progress': pct, 'fileName': file]
    )
  }
}

WritableArray for List Results

// Kotlin
@ReactMethod
fun listBluetoothDevices(promise: Promise) {
    val array = Arguments.createArray()
    val devices = bluetoothAdapter?.bondedDevices ?: emptySet()
    for (device in devices) {
        val map = Arguments.createMap()
        map.putString('name', device.name)
        map.putString('address', device.address)
        array.pushMap(map)
    }
    promise.resolve(array)
}

// JavaScript
const devices = await NativeModules.BleModule.listBluetoothDevices();
devices.forEach(d => console.log(d.name, d.address));

Choosing Between Callbacks, Promises, and Events

// Decision chart as comments
// One result, awaitable? → Promise
const photo = await NativeModules.Camera.takePhoto();

// Multiple results over time? → Event emitter
const sub = emitter.addListener('locationUpdate', handleLocation);
NativeModules.LocationModule.startWatching();

// Legacy API you must support? → Callback
NativeModules.OldModule.doThing(onSuccess, onError);

Thread Safety for Event Emission

// Kotlin — safe event emit with listener guard
private var listenerCount = 0

@ReactMethod
fun addListener(eventName: String) {
    listenerCount++
}

@ReactMethod
fun removeListeners(count: Int) {
    listenerCount -= count
}

private fun safeSendEvent(name: String, data: WritableMap) {
    if (listenerCount > 0) {
        reactApplicationContext
            .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
            .emit(name, data)
    }
}

Testing Native Module Callbacks in Jest

// __mocks__/NativeModules.js
jest.mock('react-native', () => ({
  ...jest.requireActual('react-native'),
  NativeModules: {
    CameraModule: {
      takePhoto: jest.fn(() => Promise.resolve('/path/to/photo.jpg')),
      openCamera: jest.fn(() => Promise.resolve(true)),
    },
    DownloadModule: {},
  },
}));

// In your test
it('captures a photo and sets image URI', async () => {
  const { getByTestId } = render(<CameraScreen />);
  fireEvent.press(getByTestId('shutter-btn'));
  await waitFor(() =>
    expect(getByTestId('preview').props.source).toEqual(
      { uri: '/path/to/photo.jpg' }
    )
  );
});

Quick Check

Lesson Recap