@eversurf/dengine-rn-jsi/README.md

Dengine React Native JSI

<h1>Dengine for React Native JSI</h1>

JSI-based implementation of a bridge to mobile React Native platform including static libraries for iOS and Android.

# Installation

```sh
yarn add @eversurf/dengine-rn-jsi
```

## iOS

Requirements: Xcode 12.5

```
cd ios && pod install && cd ..
```

On iOS, the library is installed automatically. However, currently it is not possible to autoinstall more than one JSI library. In order to use lib-react-native-jsi and [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) simultaneously, you need to enable `DONT_AUTOINSTALL_*` flags in Podfile and register JSI bindings in `jsExecutorFactoryForBridge` method:

`Podfile`

```rb
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['OTHER_CPLUSPLUSFLAGS'] = '-DDONT_AUTOINSTALL_REANIMATED -DDONT_AUTOINSTALL_TONCLIENTJSI'
    end
  end
end
```

> **Note:** Don't forget to run `pod install` after doing that.

Then, rename `AppDelegate.m` to `AppDelegate.mm` in order to compile this file as Objective-C++.

> **Note:** It's important to do it with Xcode, so that the project references are updated accordingly.

`AppDelegate.mm`

## Android

Requirements: Android NDK 26.0.10792818

`android/build.gradle`

# Setup

# Blob support

In React Native app, you can load any resource as JS Blob (binary large object) using `fetch` function and `blob` method:

```js
const url = '...'; // path to a local file or a remote resource
const response = await fetch(url);
const blob = await response.blob();
```

Then you can create an object URL for the provided blob:

```js
const objectURL = URL.createObjectURL(blob);
```

> **Note:** On Android, it is necessary to register `BlobProvider` as a ContentProvider in order to create object URLs for blobs ([see details](https://github.com/facebook/react-native/blob/33ef82ce6dfd31e1f990d438c925a0e52723e16b/Libraries/Blob/URL.js#L27-L50)). On iOS, there is no additional configuration required.

Finally, you can pass the object URL directly as source prop of React Native `<Image />` component:

```jsx
<Image source={{ uri: objectURL }} />
```

> **Note:** There is a problem with accessing blobs greater than 64 KB on Android (see [this issue](https://github.com/facebook/react-native/issues/31774)) on React Native 0.64.2 and earlier. Please use React Native 0.65.0+ or alternatively build older version of React Native from sources with the fix from [this pull request](https://github.com/facebook/react-native/pull/31789).

It is also possible to pass blob object URL directly as source prop of `<Pdf />` component from [react-native-pdf](https://github.com/wonday/react-native-pdf):

```jsx
<Pdf source={{ uri: objectURL }} />
```

> **Note**: The above requires [this pull request](https://github.com/wonday/react-native-pdf/pull/581) which has not been merged yet.

> **Note**: It is advisable to keep the reference to the Blob object as long as its object URL is used with other components. Otherwise, the JavaScript garbage collector may collect the JS Blob object and consequently deallocate the memory associated with this blob (both on [Android](https://github.com/facebook/react-native/blob/4fcf46813152f5555a79ecb0ab06fe5d84e21624/ReactAndroid/src/main/java/com/facebook/react/modules/blob/jni/BlobCollector.cpp#L27-L34) and [iOS](https://github.com/facebook/react-native/blob/1465c8f3874cdee8c325ab4a4916fda0b3e43bdb/Libraries/Blob/RCTBlobCollector.mm#L19-L25)). This will lead to a crash due to bad memory access when the component tries to access blob data again, for example during UI interaction or re-render.

After you're done with the object URL, don't forget to revoke it:

```js
URL.revokeObjectURL(objectURL);
```

> **Note:** Currently, the React Native implementation [does nothing](https://github.com/facebook/react-native/blob/4fcf46813152f5555a79ecb0ab06fe5d84e21624/Libraries/Blob/URL.js#L123-L125), but this function is still a part of [URL API](https://developer.mozilla.org/en-US/docs/Web/API/URL_API).

This library provides two ways of transferring large binary payloads between React Native and TON SDK:

- as base64-encoded JS strings
- as raw binary JS Blobs

You can pass each request param individually either as a string or a blob to `lib.sendRequestParams` method and consequently to any of TON Client JS bindings. All JS Blobs in the request params will be resolved and converted to base64-encoded strings and then JSON-serialized on a worker thread to avoid UI freezes before calling `tc_request_ptr` function from TON SDK.

By default, if there is any JS Blob in the request params, then all strings in the response params will also be converted to JS Blobs. Otherwise, all strings will be returned as regular JS strings.

You can override this behaviour by passing additional parameter `response_binary_type` in the request params with either of following values:

- `base64` &ndash; all string response params will be returned as original strings returned from TON SDK

- `blob` &ndash; all string response params will decoded from base64 and returned as raw binary JS Blobs

# Development

First, install the dependencies in `lib-react-native-jsi` directory:

```sh
cd packages/lib-react-native-jsi
yarn install
```

The library comes with example apps for different versions of React Native. Before running each example app, it is necessary to install its dependencies using `yarn install` as well as its CocoaPods dependencies using `pod install` in `ios` directory.

```sh
cd example63
yarn install
cd ios
pod install
cd ..
```

Then you can build and run the example app on Android or iOS with the following commands:

```sh
yarn react-native start
yarn react-native run-android
yarn react-native run-ios
```

Please remember to set appropriate version of React Native in `lib-react-native-jsi` when developing `example63`, `example64` and `example65` apps using the following commands:

```sh
cd lib-react-native-jsi
yarn add react-native@0.63.4
yarn add react-native@0.64.0
yarn add react-native@0.65.1
```

# Testing

For testing purposes, use `tests-lib-react-native-jsi` tests runner.

First pack the dependent libraries into `*.tgz` archives:

```sh
cd packages/core
npm i
npx tsc
npm pack

cd ../tests
npm i
npx tsc
npm pack

cd ../lib-react-native-jsi
yarn install
npm pack
```

Then, install the dependencies from `*.tgz` archives:

```sh
cd ../tests-react-native-jsi
npm add file:../core/dengine-js-1.30.1.tgz
npm add file:../tests/dengine-tests-1.30.1.tgz
npm add file:../lib-react-native-jsi/dengine-rn-jsi-1.30.1.tgz
npm i
cd ios
pod install
cd ..
```

> **Note:** Please update the version in the filenames appropriately.

Finally, you can launch the tests runner with the following commands:

```sh
node run ios
node run android
```