Promises (Promise<T>)

A function can be made asynchronous by returning a Promise to JS. This allows your native code to perform heavy-, long-running tasks in parallel, while the JS thread can continue rendering and performing other business logic.

TypeScript

In TypeScript, a Promise<T> is represented using the built-in Promise<T> type, which can be awaited:

import { type HybridObject, iOS } from 'nitro-core'

@iOS(...)
export declare class Math extends HybridObject {
  fibonacci(n: number): Promise<number>
}

const math = // ...
await math.fibonacci(13)

note

The Promise<T> type is built-in in JavaScript.

Swift

In Swift, a Promise<T> can be created via Nitro's Promise<T> type - for example, to use Swift's new async/await syntax:

func fibonacci(n: Double) -> any Promise<Double> {
  return .async {
    // This runs in a Swift Task and can await asynchronous work.
    return try await calculateFibonacciSequence(n)
  }
}

note

Import Promise from Nitro: import NitroModules

Kotlin

In Kotlin, a Promise<T> can be created via Nitro's Promise<T> type - for example, to use Kotlin's coroutine syntax:

fun fibonacci(n: Double): Promise<Double> {
  return Promise.async {
    // This runs on a separate Thread, and can use suspending coroutine functions!
    return@async calculateFibonacciSequence(n)
  }
}

note

Import Promise from Nitro: import com.margelo.nitro.core.Promise

C++

In C++, a Promise<T> can be created via Nitro's Promise<T> type - for example, to use an asynchronous Thread pool:

Promise<double> fibonacci(double n) {
  return Promise<double>::async([=]() -> double {
    // This runs on a separate Thread!
    return calculateFibonacciSequence(n);
  });
}

note

Import Promise from Nitro: #include <NitroModules/Promise.hpp>

Additionally, Nitro statically enforces that Promises can never go stale, preventing you from accidentally "forgetting" to resolve or reject a Promise:

HybridMath.swift

func saveToFile(image: HybridImage) -> any Promise<Void> {
  guard let data = image.data else { return }
                                     ^ // Error: Cannot return void!
  return .async {
    try await data.writeToFile("file://tmp/img.png")
  }
}

In Swift, Promise<T> is a protocol. Use any Promise<T> in signatures and contextual factories such as .async { ... }, .parallel { ... }, .resolved(with: value), or .rejected(with: error). Nitrogen generates these factories for the promise types used by your specs.