React-native: 👻 Flow Typing NativeModules

Created on 16 May 2019 · 66Comments · Source: facebook/react-native

Flow Typing NativeModules

The TurboModule system is nearly feature-complete on both Android and iOS. Before we rollout the system, we'd like to migrate all our OSS NativeModules to use it. As a prerequisite for this migration, all the the NativeModules must have spec files. There are currently 41 NativeModules in total, so there is a bunch of work to do. We'd love to use this as an opportunity to help get more people involved by contributing to React Native.

Instructions

Pick an unclaimed module and comment that you're working on it.
Create a Spec file called NativeXYZ.js, where XYZ is the name of the NativeModule.
Define flow types based on the NativeModule's native methods.
Change call-sites from NativeModules.XYZ to NativeXYZ
Make sure flow passes
Do one module per PR

What is a Spec file?

A Spec file looks like this:

NativeAnalytics.js

/**
 * Copyright 2004-present Facebook. All Rights Reserved.
 *
 * @flow strict-local
 * @format
 */

'use strict';

import type {TurboModule} from 'RCTExport';
import * as TurboModuleRegistry from 'TurboModuleRegistry';

export interface Spec extends TurboModule {
  +getConstants: () => {|
    constant1: string,
    constant2: boolean,
  |};
  +logCounter: (key: string, value: number) => void;
  +logEvent: (eventName: string, data: Object, analyticsModule: ?string) => void;
  +logRealtimeEvent: (
    eventName: string,
    data: Object,
    analyticsModule: ?string,
  ) => void;
}

export default TurboModuleRegistry.getEnforcing<Spec>(
  'Analytics',
);

Observations

We use TurboModuleRegistry.getEnforcing<Spec>('Analytics') as opposed to NativeModules.Analytics to require the NativeModule. TurboModuleRegistry.getEnforcing is an indirection that allows us to require both NativeModules and TurboModules. It throws if the NativeModule isn't there. In the case that a NativeModule is platform-specific, please use Platform.OS and conditionally call TurboModuleRegistry.getEnforcing.
Each Spec file exports an interface called Spec that extends TurboModule. This interface contains typings for methods exposed by the NativeModule/TurboModule.
NativeModule constants are declared in the return type of the getConstants() method. The old way of accessing constants as properties on NativeModule objects is deprecated and unsupported by the TurboModule system. On iOS, these constants map to the return type of constantsToExport in iOS and getConstants in Android.
Each Spec file is named Native*.js. The filename matters because our codegen uses it to name the generated Java interfaces, ObjC protocols, and C++ TurboModule subclasses. NativeAnalytics.js, for instance, will generate a Java interface and ObjC protocol called NativeAnalyticsSpec, and a C++ TurboModule class called NativeAnalyticsSpecJSI. After these Spec files are typed, we'll generate and check in the codegen output into this repository. Then, after we open source our codegen, we'll delete the generated interfaces, protocols, and C++ classes from this repository.
- Note that the naming convention used here is not finalized, but stable enough for the time being.
This isn't a ViewManager. We're currently not focusing on ViewManagers. Therefore, there's no need to write spec files for them.
We're not using imported types. Our codegen doesn't support imported types. So, for the time being, all types used by the spec must be declared in the same file.

Supported Types

Methods with simple args:
- string
- boolean
- number
- Object
- Array<*>*
Function and typed function:
- Methods with nullable args
- ?string
- ?Object
- ?Array<*>*
- ?Function and nullable typed function
- number and boolean are not supported
Methods with inline complex Object typed args
- e.g. (x: {|foo: string, ... |}) => void
Methods that return a Promise<*>*
Synchronous methods that return simple non-nullable types
- string
- number
- boolean
- Object
- Array<*>*
Optional methods with all variants above
Typed exported constants
Note: Flow unions aren't supported

How do you type NativeModules?

You have to deduce the types by looking at the NativeModule implementations on iOS and Android. Some NativeModules already have JS wrappers, so you could also look at those for writing the Spec files.

Guidelines

How do you know which methods are exported to JS?
- On Android: Look for NativeModule non-inherited class methods annotated with @ReactMethod.
- On iOS: Look for NativeModule non-inherited and inherited class methods wrapped in RCT_EXPORT_*_METHOD macros .
How do you know when a method should have a Promise return type?
- On Android: The last argument of the method is the Promise object.
- On iOS: The last two arguments are a RCTPromiseResolveBlock and RCTPromiseRejectBlock
What should the JS method name be?
- On Android: It's the name of the Java method.
- On iOS: It's the part of the selector before the first argument/color.
NSDictionary on iOS, and ReadableMap and WritableMap on Android translate to object literals in JS.
RCTResponseSenderBlock and RCTResponseErrorBlock on iOS, and Callback on Android translate to function literals in JS.
Try to avoid using Function and Object whenever possible.
In the case that a method or constant is unavailable on one platform, make it optional.
In the case that a NativeModule is unavailable on one platform, make it optional.
Where do you put the Spec file?
- Most NativeModules belong to a Library (see the JS section of the table below), so you could write the Spec in the library. For the other NativeModules, write the spec inside react-native-github/Libraries/NativeModules/specs.

Platform-specific NativeModules

For platform-specific NativeModules, use Platform.OS to conditionally call TurboModuleRegistry.getEnforcing<Spec>. When changing the call-sites of these NativeModules, you may have to guard them with null checks to please flow.

Call-site Before

const NativeModules = require('NativeModules');
const IntentAndroid = NativeModules.IntentAndroid;

function foo() {
  if (Platform.OS === 'android') {
    IntentAndroid.method();
  }
}

Call-site After

const NativeIntentAndroid = require('NativeIntentAndroid');
const {Platform} = require('react-native');

function foo() {
  if (Platform.OS === 'android') {
    if (NativeIntentAndroid != null) {
      NativeIntentAndroid.method();
    }
  }
}

NativeModule List

Please claim a NativeModule from the list below.

⬜️ - Unclaimed
🚧 - Claimed / PR in progress
✅ - PR Merged

Flow Good first issue Help Wanted Native Module Locked Discussion

Source

RSNara

👍30 🚀7 ❤7 🎉7

Most helpful comment

As of https://github.com/facebook/react-native/commit/18fededae085b53b01e54a7ed27e32c2318e7cae, all 42 PRs have now been merged! Thank you for all the contributions to this effort!

I'll close this issue for now.

fkgozali on 1 Jun 2019

🎉11 🚀7

All 66 comments

@RSNara any examples on how to handle event emitter classes?

ericlewis on 16 May 2019

any examples on how to handle event emitter classes?

export interface Spec extends TurboModule {
  +getConstants: () => {|
    // any constants it exports
  |};

  // add any exported methods

  // Then add these 2 methods:

  // Events
  +addListener: (eventName: string) => void;
  +removeListeners: (count: number) => void;
}

eric: I changed the comment for listeners to be generic

fkgozali on 16 May 2019

👍4

Also worth noting: there are some places in the code base that directly access constants in JS, they need to be changed to be grabbed from getConstants.

Example:

const DeviceInfo = require('./DeviceInfo');
dims = DeviceInfo.Dimensions;

becomes:

const DeviceInfo = require('./DeviceInfo');
dims = DeviceInfo.getConstants().Dimensions;

luckily, flow will complain about these if you do your typing right! So, just update the callsites.

ericlewis on 16 May 2019

👍2

Hey! I'd like to help with Linking module.

michalchudziak on 16 May 2019

Hi, I would like to help with DeviceInfo

gedeagas on 16 May 2019

@michalchudziak, @gedeagas both were done by &ericlewis’ PRs

fkgozali on 16 May 2019

PermissionAndroid/TimePickerAndroid are still open I think

fkgozali on 16 May 2019

I'll go with PermissionsAndroid then

Krizzu on 16 May 2019

Sure, no problem! Is it possible to work on AccessibilityManager & AccessibilityInfo?

Edit: I'm working on it :)

michalchudziak on 16 May 2019

I work on ToastAndroid

wojteg1337 on 16 May 2019

Taking Networking

thymikee on 16 May 2019

🎉1

Working on Timing

jeanregisser on 16 May 2019

🎉1

Working on WebSocketModule

jeanregisser on 16 May 2019

~Taking ToastAndroid~ someone already taken

chakrihacker on 16 May 2019

Working on HeapCapture

wojteg1337 on 16 May 2019

Working on IntentAndroid

chakrihacker on 16 May 2019

Working on ModalManager

abhiin1947 on 16 May 2019

@RSNara what about the case where the native method definition differs on iOS and Android?

This is what I did sofar for the close method of WebSocketModule:

// Native close method definition on Android
declare function close(code: number, reason: string, socketID: number): void;
// Native close method definition on iOS
declare function close(socketID: number): void;

export interface Spec extends TurboModule {
  +connect: (
    url: string,
    protocols: ?Array<string>,
    options: ?{headers?: {origin?: string}},
    socketID: number,
  ) => void;
  +send: (message: string, socketID: number) => void;
  +sendBinary: (base64String: string, socketID: number) => void;
  +ping: (socketID: number) => void;
  +close: typeof close;

  // RCTEventEmitter
  +addListener: (eventName: string) => void;
  +removeListeners: (count: number) => void;
}

jeanregisser on 16 May 2019

@jeanregisser I had similar issue with Networking module: https://github.com/facebook/react-native/pull/24892 and after consulting ideas with @rickhanlonii we decided to create two native modules for now: NativeNetworkingIOS and NativeNetworkingAndroid as even when using Platform.OS check, Flow mixed 2 definitions resulting in errors of wrong signature being used.

thymikee on 16 May 2019

Working on TimePickerAndroid

jeanregisser on 16 May 2019

Working on TVNavigationEventEmitter

jeanregisser on 16 May 2019

❤1

Working on SourceCode

jeanregisser on 16 May 2019

❤1 👍1

~Working on NativeAnimatedModule~ Already taken by @thymikee

uqmessias on 16 May 2019

~~Taking ExceptionsManager~~ Taken by @thymikee .

zhongwuzw on 16 May 2019

👍1

Taking UIManager

ericlewis on 16 May 2019

👍1

Working on AlertManager

sasurau4 on 16 May 2019

👍2

Taking ImageLoader

yjose on 16 May 2019

👍3

can I take DevSettings?

raphaeleidus on 16 May 2019

👍4

I'll take PlatformConstants Platform.android.js

sattaman on 16 May 2019

👍2

I will take JSCSamplingProfiler

ericlewis on 16 May 2019

👍2

Will take FileReaderModule

ericlewis on 16 May 2019

👍1

i'll take DevLoadingView

glenna on 16 May 2019

👍1

I will take JSDevSupport

ericlewis on 16 May 2019

👍1

Taking NativeAnimatedModule

thymikee on 16 May 2019

👍1

Thank you all for doing the work! We're halfway there :)

fkgozali on 16 May 2019

🚀3

Taking HeadlessJsTaskSupport

ericlewis on 16 May 2019

👍2

Will take I18nManagerModule

ericlewis on 16 May 2019

👍2

taking BlobModule

ericlewis on 16 May 2019

👍3

Working on DialogManagerAndroid

uqmessias on 16 May 2019

👍2

taking DatePickerAndroid

pedpess on 16 May 2019

👍2

Taking DeviceEventManager

uqmessias on 16 May 2019

👍2

Taking ImageViewManager

uqmessias on 16 May 2019

taking AnimationDebugModule

ericlewis on 16 May 2019

@uqmessias:

Actually viewmanagers shouldn’t be typed, re: ImageViewManager

fkgozali on 16 May 2019

👍2

@fkgozali
I was almost finishing, but I'll stop it and keep the current code in a separated branch.

uqmessias on 16 May 2019

RedBox remaining.

ericlewis on 16 May 2019

👍1

@fkgozali can you check the ImageLoader mapping ios and android files in the table: RCTImageEditingManager.m and ImageLoaderModule.java look like something wrong?

yjose on 16 May 2019

@yjose,
I was working on something related to this one

uqmessias on 16 May 2019

@uqmessias hmm ok

Actually` viewmanagers shouldn’t be typed, re: ImageViewManager

in this case, I think they mean ImageEditor which have the correct ios and android files RCTImageEditingManager.m and ImageEditingManager.java?
cc @RSNara @fkgozali

yjose on 16 May 2019

👍2

@yjose i think you are correct

ericlewis on 16 May 2019

working on ImageEditor

yjose on 16 May 2019

👍1

We got 'em all i think

ericlewis on 17 May 2019

👍4 🎉2

Taking Platform.ios.js

jarvisluong on 17 May 2019

I would like to help with AppState . Let's get started right away.

mitulsavani on 17 May 2019

@mitulsavani AppState is already done and merged. Please have a look at "NativeModule List" section of the original post. Looks like the only one left is "TimePickerAndroid.ios.js" – feel free to grab it while it's free! (and please check https://github.com/facebook/react-native/pull/24897/files because it may overlap, so it may be better to cooperate with the author, @jeanregisser, on this one)

thymikee on 17 May 2019

I would certainly like to claim that. Although i have no clue how and what needs to change/add, but I want to at least give a shot! @thymikee

mitulsavani on 17 May 2019

@mitulsavani @thymikee indeed https://github.com/facebook/react-native/pull/24897 addresses TimePickerAndroid.ios.js as well.

jeanregisser on 17 May 2019

👍3

@thymikee anything left that I work on ?

mitulsavani on 17 May 2019

Thanks all for the PRs, we're going through them one by one to ensure nothing else breaks in FB internal infra. Stay tuned!

fkgozali on 17 May 2019

👍5

It looks like ImageStore got left out. For anyone interested, feel free to claim it.

fkgozali on 30 May 2019

I hereby claim for it.

mitulsavani on 30 May 2019

👍2

DevSettings was also left out, feel free to claim.

fkgozali on 30 May 2019

I will claim the ‘DevSetting’

jarvisluong on 30 May 2019

👍3

As of https://github.com/facebook/react-native/commit/18fededae085b53b01e54a7ed27e32c2318e7cae, all 42 PRs have now been merged! Thank you for all the contributions to this effort!

I'll close this issue for now.

fkgozali on 1 Jun 2019

🎉11 🚀7

In order to get a sense of how the codegen output looks like, https://github.com/facebook/react-native/commit/b1bf133d69cf06629fb1beeeaf23ccd418bec242 checked them in, based on all the Flow types you all have added. This is not used yet, and we're working on migrating each module to use it gradually.

fkgozali on 26 Jun 2019

❤2

Hi,

In the instructions, we can read:

Create a Spec file called NativeXYZ.js, where XYZ is the name of the NativeModule.

How strict is this rule?

There's no NativePlatformConstants.js anywhere, rather there I see both NativePlatformConstantsIOS.js and NativePlatformConstantsAndroid.js. Is that going to through a wrench in the cogs?

https://github.com/react-native-community/discussions-and-proposals/issues/40#issuecomment-537056284