Skip to content

Refactor Executorch bindings #379

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
msluszniak wants to merge 4 commits into from
Closed

Refactor Executorch bindings #379

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7961256
Refactor Executorch bindings
Jun 7, 2025
93c4df7
Update example in docs
Jun 7, 2025
d001a76
Update docs/docs/typescript-api/ExecutorchModule.md
msluszniak Jun 7, 2025
e04e015
Fix types
Jun 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions docs/docs/executorch-bindings/useExecutorchModule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,26 +30,30 @@ The `modelSource` parameter expects a location string pointing to the model bina

### Returns

| Field | Type | Description |
| :----------------: | :--------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `error` | <code>string &#124; null</code> | Contains the error message if the model failed to load. |
| `isGenerating` | `boolean` | Indicates whether the model is currently processing an inference. |
| `isReady` | `boolean` | Indicates whether the model has successfully loaded and is ready for inference. |
| `loadMethod` | `(methodName: string) => Promise<void>` | Loads resources specific to `methodName` into memory before execution. |
| `loadForward` | `() => Promise<void>` | Loads resources specific to `forward` method into memory before execution. Uses `loadMethod` under the hood. |
| `forward` | `(input: ETInput, shape: number[]) => Promise<number[][]>` | Executes the model's forward pass, where `input` is a Javascript typed array and `shape` is an array of integers representing input Tensor shape. The output is a Tensor - raw result of inference. |
| `downloadProgress` | `number` | Represents the download progress as a value between 0 and 1. |
| Field | Type | Description |
| :----------------: | :----------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `error` | <code>string &#124; null</code> | Contains the error message if the model failed to load. |
| `isGenerating` | `boolean` | Indicates whether the model is currently processing an inference. |
| `isReady` | `boolean` | Indicates whether the model has successfully loaded and is ready for inference. |
| `loadMethod` | `(methodName: string) => Promise<void>` | Loads resources specific to `methodName` into memory before execution. |
| `loadForward` | `() => Promise<void>` | Loads resources specific to `forward` method into memory before execution. Uses `loadMethod` under the hood. |
| `forward` | `(input: Tensor[] \| Tensor): Promise<number[]>` | Executes the model's forward pass, where `input` is a `Tensor` or array of tensors `Tensor[]`. Tensor is a compound type consisting of two elements: data and shape. Data is a JavaScript typed array, and shape is an array of integers representing the input tensor shape. |
| `downloadProgress` | `number` | Represents the download progress as a value between 0 and 1. |

## ETInput

The `ETInput` type defines the typed arrays that can be used as inputs in the `forward` method:
The `ETInput` type defines the typed arrays that can be used as data in `Tensor`:

- Int8Array
- Int32Array
- BigInt64Array
- Float32Array
- Float64Array

## Tensor

The `Tensor` is a complex type that aggregates both data and shape of the tensor passed to the `forward` method.

## Errors

All functions provided by the `useExecutorchModule` hook are asynchronous and may throw an error. The `ETError` enum includes errors [defined by the ExecuTorch team](https://github.com/pytorch/executorch/blob/main/runtime/core/error.h) and additional errors specified by our library.
Expand Down
34 changes: 21 additions & 13 deletions docs/docs/typescript-api/ExecutorchModule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,38 +13,46 @@ import {
} from 'react-native-executorch';

// Creating the input array
const shape = [1, 3, 640, 640];
const input = new Float32Array(1 * 3 * 640 * 640);
const inputShape = [1, 3, 640, 640];
const inputData = new Float32Array(1 * 3 * 640 * 640);

// Loading the model
await ExecutorchModule.load(STYLE_TRANSFER_CANDY);

// Running the model
const output = await ExecutorchModule.forward(input, shape);
const output = await ExecutorchModule.forward({
data: inputData,
shape: inputShape,
});
```

### Methods

| Method | Type | Description |
| -------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `load` | `(modelSource: ResourceSource): Promise<void>` | Loads the model, where `modelSource` is a string that specifies the location of the model binary. |
| `forward` | `(input: ETInput, shape: number[]): Promise<number[]>` | Executes the model's forward pass, where `input` is a JavaScript typed array and `shape` is an array of integers representing input Tensor shape. The output is a Tensor - raw result of inference. |
| `loadMethod` | `(methodName: string): Promise<void>` | Loads resources specific to `methodName` into memory before execution. |
| `loadForward` | `(): Promise<void>` | Loads resources specific to `forward` method into memory before execution. Uses `loadMethod` under the hood. |
| `onDownloadProgress` | `(callback: (downloadProgress: number) => void): any` | Subscribe to the download progress event. |
| Method | Type | Description |
| -------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `load` | `(modelSource: ResourceSource): Promise<void>` | Loads the model, where `modelSource` is a string that specifies the location of the model binary. |
| `forward` | `(input: Tensor[] \| Tensor): Promise<number[]>` | Executes the model's forward pass, where `input` is a `Tensor` or array of tensors `Tensor[]`. Tensor is a compound type consisting of two elements: data and shape. Data is a JavaScript typed array, and shape is an array of integers representing the input tensor shape. |
| `loadMethod` | `(methodName: string): Promise<void>` | Loads resources specific to `methodName` into memory before execution. |
| `loadForward` | `(): Promise<void>` | Loads resources specific to `forward` method into memory before execution. Uses `loadMethod` under the hood. |
| `onDownloadProgress` | `(callback: (downloadProgress: number) => void): any` | Subscribe to the download progress event. |

<details>
<summary>Type definitions</summary>

```typescript
type ResourceSource = string | number | object;
export type ResourceSource = string | number | object;

export type ETInput =
type ETInput =
| Int8Array
| Int32Array
| BigInt64Array
| Float32Array
| Float64Array;

export interface Tensor {
data: ETInput;
shape: number[];
}
```

</details>
Expand All @@ -55,7 +63,7 @@ To load the model, use the `load` method. It accepts the `modelSource` which is

## Running the model

To run the model use the `forward` method. It accepts two arguments: `input` and `shape`. The `input` is a JavaScript typed array, and `shape` is an array of integers representing the input tensor shape. There's no need to explicitly define the input type, as it will automatically be inferred from the typed array you pass to forward method. Outputs from the model, such as classification probabilities, are returned in raw format.
To run the model use the `forward` method. It accepts one argument: `input`. The `input` is a `Tensor` or array of tensors `Tensor[]`. Tensor is a compound type consisting of two elements: data and shape. Data is a JavaScript typed array, and `shape` is an array of integers representing the input tensor shape. There's no need to explicitly define the input type, as it will automatically be inferred from the typed array you pass to forward method. Outputs from the model, such as classification probabilities, are returned in raw format.

## Loading methods

Expand Down
15 changes: 11 additions & 4 deletions packages/react-native-executorch/src/modules/general/ExecutorchModule.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { ETError, getError } from '../../Error';
import { ETModuleNativeModule } from '../../native/RnExecutorchModules';
import { ResourceSource } from '../../types/common';
import { ETInput } from '../../types/common';
import { Tensor } from '../../types/common';
import { getTypeIdentifier } from '../../types/common';
import { BaseModule } from '../BaseModule';

Expand All @@ -12,21 +12,28 @@ export class ExecutorchModule extends BaseModule {
return await super.load(modelSource);
}

static override async forward(input: ETInput[] | ETInput, shape: number[][]) {
static override async forward(input: Tensor[] | Tensor) {
if (!Array.isArray(input)) {
input = [input];
}

let inputTypeIdentifiers = [];
let shape = [];
let modelInputs = [];

for (let idx = 0; idx < input.length; idx++) {
let currentInputTypeIdentifier = getTypeIdentifier(input[idx] as ETInput);
const currentInput = input[idx];
if (!currentInput || !currentInput.data) {
throw new Error('Input tensor is undefined.');
}

let currentInputTypeIdentifier = getTypeIdentifier(currentInput.data);
if (currentInputTypeIdentifier === -1) {
throw new Error(getError(ETError.InvalidArgument));
}
shape.push(currentInput.shape);
inputTypeIdentifiers.push(currentInputTypeIdentifier);
modelInputs.push([...(input[idx] as unknown as number[])]);
modelInputs.push([...(currentInput as unknown as number[])]);
}

try {
Expand Down
5 changes: 5 additions & 0 deletions packages/react-native-executorch/src/types/common.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,8 @@ export type ETInput =
| BigInt64Array
| Float32Array
| Float64Array;

export interface Tensor {
data: ETInput;
shape: number[];
}
Loading