feat: Add `Priority` to Dispatcher `runAsync` and `runSync` methods

[mrousavy]

What

Adds a priority argument to Dispatcher::runAsync(F&&).

This internally uses the CallInvoker's counterpart:

• CallInvoker::invokeAsync(SchedulerPriority, F&&)

The priority can have 5 values:

enum class SchedulerPriority : int {
  ImmediatePriority = 1,
  UserBlockingPriority = 2,
  NormalPriority = 3,
  LowPriority = 4,
  IdlePriority = 5,
};

Promises Change

Also, this PR already makes use of this by using a high priority (ImmediatePriority) for Promise.then and Promise.catch calls, while using a normal (NormalPriority) for anything else (callbacks). So Promises in Nitro would now follow microtask "rules".

Test Plan / Example app

I can tell that this actually works because this test failed:

If we take a look at the JS code for the test, it looks like this:

let value: string | undefined
await testObject.getValueFromJsCallback(
  () => 'hello',
  (val) => {
    value = val
  }
)
return value

Now after quickly reading the JS Spec on Microtasks/Event Queues, I think this is expected. The Promise.resolve function has a higher priority (it's a microtask) so it runs before the asynchronous callback (a macrotask) - so this is expected. I updated the test to reflect this.

Problem: Priority is not really used in react-native

The only problem with this change is that react-native itself often doesn't use invokeAsync(Priority, F&&) - instead they just use invokeAsync(F&&) - which by default just uses SchedulerPriority::ImmediatePriority. In other words, many React Native asynchronous calls would take precedence over Nitro's asynchronous calls, since only Nitro would "properly" use the prioritizations while react-native just uses highest priority always. I created a discussion for this here; https://github.com/facebook/react-native/pull/54141#issuecomment-3398486829

[vercel[bot]]

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

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
nitro-docs	Skipped			Oct 13, 2025 5:26pm