Skip to content

API consistency in React Native #4971

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#contentAsyncStorage.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#contentNetInfo.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#contentCameralRoll.saveImageWithTag(tag,successCallback,errorCallback);CameralRoll.getPhotos(params,callback,errorCallback);// https://facebook.github.io/react-native/docs/nativemethodsmixin.html#contentNativeMethodsMixin.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#contentActionSheetIOS.showShareActionSheetWithOptions(options: Object,failureCallback: Function,successCallback: Function)

5. Callbacks with no error

// https://facebook.github.io/react-native/docs/actionsheetios.html#contentActionSheetIOS.showActionSheetWithOptions(options: Object,callback: Function)// https://facebook.github.io/react-native/docs/alertios.html#promptAlert.prompt(title: string,value?: string,buttons?: Array<{text?: string;onPress?: ?Function;style?: AlertButtonStyle;}>,callback?: Function)// Clipboard: not documented yetClipboard.getString(callback: Function)// https://facebook.github.io/react-native/docs/intentandroid.html#contentIntentAndroid.canOpenURL(url: string,callback: Function)IntentAndroid.getInitialURL(callback: Function)// https://facebook.github.io/react-native/docs/linkingios.html#contentLinkingIOS.canOpenURL(url: string,callback: Function)// https://facebook.github.io/react-native/docs/nativemethodsmixin.html#contentNativeMethodsMixin.measure(callback: MeasureOnSuccessCallback)// https://facebook.github.io/react-native/docs/pushnotificationios.html#contentPushNotificationIOS.getApplicationIconBadgeNumber(callback: Function)PushNotificationIOS.checkPermissions(callback: Function)

6. Promise based APIs

// https://facebook.github.io/react-native/docs/asyncstorage.html#contentAsyncStorage// all AsyncStorage methods// https://facebook.github.io/react-native/docs/netinfo.html#contentNetInfo.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