Skip to content

API consistency in React Native #4971

@satya164

Description

@satya164

Currently React Native has lots of incosnistencies in its APIs. This is an attempt to settle on a standard way for API methods and change the current APIs to the standard format by discussing a migration path.

Currently available modules and their callbacks

The available APIs can be categorized into the following categories,

1. Node-style error-first callbacks

// https://facebook.github.io/react-native/docs/asyncstorage.html#content
AsyncStorage.getItem(key: string, callback?: ?(error: ?Error, result: ?string) => void) // all AsyncStorage methods

2. Value first callbacks

// https://facebook.github.io/react-native/docs/netinfo.html#content
NetInfo.isConnectionExpensive(callback: (metered: ?boolean, error?: string) => void)

3. Separate callbacks for success and error, success-first

// https://facebook.github.io/react-native/docs/cameraroll.html#content
CameralRoll.saveImageWithTag(tag, successCallback, errorCallback);
CameralRoll.getPhotos(params, callback, errorCallback);

// https://facebook.github.io/react-native/docs/nativemethodsmixin.html#content
NativeMethodsMixin.measureLayout(relativeToNativeNode: number, onSuccess: MeasureLayoutOnSuccessCallback, onFail: () => void)

4. Separate callbacks for success and error, error-first

// https://facebook.github.io/react-native/docs/actionsheetios.html#content
ActionSheetIOS.showShareActionSheetWithOptions(options: Object, failureCallback: Function, successCallback: Function)

5. Callbacks with no error

// https://facebook.github.io/react-native/docs/actionsheetios.html#content
ActionSheetIOS.showActionSheetWithOptions(options: Object, callback: Function)

// https://facebook.github.io/react-native/docs/alertios.html#prompt
Alert.prompt(title: string, value?: string, buttons?: Array<{ text?: string; onPress?: ?Function; style?: AlertButtonStyle; }>, callback?: Function)

// Clipboard: not documented yet
Clipboard.getString(callback: Function)

// https://facebook.github.io/react-native/docs/intentandroid.html#content
IntentAndroid.canOpenURL(url: string, callback: Function)
IntentAndroid.getInitialURL(callback: Function)

// https://facebook.github.io/react-native/docs/linkingios.html#content
LinkingIOS.canOpenURL(url: string, callback: Function)

// https://facebook.github.io/react-native/docs/nativemethodsmixin.html#content
NativeMethodsMixin.measure(callback: MeasureOnSuccessCallback)

// https://facebook.github.io/react-native/docs/pushnotificationios.html#content
PushNotificationIOS.getApplicationIconBadgeNumber(callback: Function)
PushNotificationIOS.checkPermissions(callback: Function)

6. Promise based APIs

// https://facebook.github.io/react-native/docs/asyncstorage.html#content
AsyncStorage // all AsyncStorage methods

// https://facebook.github.io/react-native/docs/netinfo.html#content
NetInfo.fetch().done(callback: Function)

Candidates for the standardized callbacks

The callbacks should encourage error handling IMO. Keeping that in mind, I think the following should be good candidates.

  1. Node-style error-first callbacks (enforces error handling)
  2. Separate callbacks for success and error, success-first (only by enforcing it in the module manually)
  3. Separate callbacks for success and error, error-first (enforces error handling)
  4. Promise based APIs (when error logging is implemented and errors show redbox - Add basic rejection tracking then/promise#116)

Problems to discuss

  1. Discuss on the advantages and disadvantages for all of the above types of callbacks and settle on one
  2. Think of a good migration path, for example when someone is using the incorrect API, show a redbox saying that API is different

If I missed any, please edit the post and add them. Thanks :D

cc @vjeux @mkonicek @nicklockwood @ide @brentvatne @skevy

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions