Skip to content

Commit ebe682b

Browse files
chmjkbchmjkb
committed
docs: add /legacy import note to docs, add new errror
1 parent f652d1a commit ebe682b

7 files changed

Lines changed: 38 additions & 13 deletions

File tree

‎docs/docs/01-fundamentals/01-getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ Before using any other API, you must call `initExecutorch` with a resource fetch
127127

128128
```js
129129
import { initExecutorch } from 'react-native-executorch';
130-
import { ExpoResourceFetcher } from 'react-native-executorch-expo-resource-fetcher';
130+
import { ExpoResourceFetcher } from 'react-native-executorch-expo-resource-fetcher'; // Use /legacy import if you're using Expo SDK < 54
131131
// or BareResourceFetcher for bare react-native projects
132132

133133
initExecutorch({ resourceFetcher: ExpoResourceFetcher });

‎docs/docs/01-fundamentals/02-loading-models.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ and then add the following code in your React Native app:
4141

4242
```typescript
4343
import { initExecutorch } from 'react-native-executorch';
44-
import { ExpoResourceFetcher } from 'react-native-executorch-expo-resource-fetcher';
44+
import { ExpoResourceFetcher } from 'react-native-executorch-expo-resource-fetcher'; // Use /legacy import if you're using Expo SDK < 54
4545

4646
initExecutorch({
4747
resourceFetcher: ExpoResourceFetcher,

‎docs/docs/05-utilities/04-error-handling.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -108,17 +108,18 @@ These errors occur during file read/write operations.
108108

109109
These errors occur during model download and resource management.
110110

111-
| Error Code | Description | When It Occurs | How to Handle |
112-
| -------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
113-
| `DownloadInterrupted` | Download was interrupted | Not all files were downloaded successfully | Retry the download |
114-
| `ResourceFetcherDownloadFailed` | Resource download failed | Network error, invalid URL, or server error | Check network connection and URL validity, retry with exponential backoff |
115-
| `ResourceFetcherDownloadInProgress` | Download already in progress | Calling `fetch()` for same resource while downloading | Wait for current download to complete |
116-
| `ResourceFetcherAlreadyPaused` | Download already paused | Calling `pauseFetching()` on already paused download | Check download state before pausing |
117-
| `ResourceFetcherAlreadyOngoing` | Download already ongoing | Calling `resumeFetching()` on active download | No action needed, download is already running |
118-
| `ResourceFetcherNotActive` | No active download found | Calling pause/resume/cancel on non-existent download | Verify download was started before trying to control it |
119-
| `ResourceFetcherMissingUri` | Required URI information missing | Internal state error during download operations | Restart the download from beginning |
120-
| `ResourceFetcherAdapterNotInitialized` | Resource fetcher not initialized | Trying to load resources without calling `initExecutorch()` first | Call `initExecutorch({ resourceFetcher: ... })` before loading models |
121-
| `ResourceFetcherPlatformNotSupported` | Platform not supported by resource fetcher | Using a resource fetcher feature unavailable on the current platform | Use a platform-appropriate fetcher or avoid the unsupported operation |
111+
| Error Code | Description | When It Occurs | How to Handle |
112+
| ----------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
113+
| `DownloadInterrupted` | Download was interrupted | Not all files were downloaded successfully | Retry the download |
114+
| `ResourceFetcherDownloadFailed` | Resource download failed | Network error, invalid URL, or server error | Check network connection and URL validity, retry with exponential backoff |
115+
| `ResourceFetcherDownloadInProgress` | Download already in progress | Calling `fetch()` for same resource while downloading | Wait for current download to complete |
116+
| `ResourceFetcherAlreadyPaused` | Download already paused | Calling `pauseFetching()` on already paused download | Check download state before pausing |
117+
| `ResourceFetcherAlreadyOngoing` | Download already ongoing | Calling `resumeFetching()` on active download | No action needed, download is already running |
118+
| `ResourceFetcherNotActive` | No active download found | Calling pause/resume/cancel on non-existent download | Verify download was started before trying to control it |
119+
| `ResourceFetcherMissingUri` | Required URI information missing | Internal state error during download operations | Restart the download from beginning |
120+
| `ResourceFetcherAdapterNotInitialized` | Resource fetcher not initialized | Trying to load resources without calling `initExecutorch()` first | Call `initExecutorch({ resourceFetcher: ... })` before loading models |
121+
| `ResourceFetcherPlatformNotSupported` | Platform not supported by resource fetcher | Using a resource fetcher feature unavailable on the current platform | Use a platform-appropriate fetcher or avoid the unsupported operation |
122+
| `ResourceFetcherFileSystemApiUnavailable` | Expo FileSystem API is unavailable (occurs for ExpoResourceFetcher) | When importing a non-existing Expo FS module | If you're using Expo 54 and below, make sure to use `/legacy` import for ExpoResourceFetcher. |
122123

123124
### Speech-to-Text Streaming Errors
124125

‎packages/expo-resource-fetcher/src/ResourceFetcher.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,15 @@ import {
3131
RnExecutorchError,
3232
BaseResourceFetcherClass,
3333
} from 'react-native-executorch';
34+
35+
if (typeof Directory !== 'function' || typeof File !== 'function') {
36+
throw new RnExecutorchError(
37+
RnExecutorchErrorCode.ResourceFetcherFileSystemApiUnavailable,
38+
"react-native-executorch-expo-resource-fetcher: the new 'expo-file-system' API " +
39+
"(Directory/File) is unavailable — you're likely on Expo SDK <54. Import from " +
40+
"'react-native-executorch-expo-resource-fetcher/legacy' instead."
41+
);
42+
}
3443
import { ResourceFetcherUtils, DownloadStatus } from './ResourceFetcherUtils';
3544
import {
3645
type ActiveDownload,

‎packages/react-native-executorch/common/rnexecutorch/ErrorCodes.h‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,13 @@ enum class RnExecutorchErrorCode : int32_t {
120120
* Thrown when the platform does not support the resource fetching feature, which is required for downloading models and other resources in React Native ExecuTorch.
121121
*/
122122
ResourceFetcherPlatformNotSupported = 187,
123+
/**
124+
* Thrown when the Expo resource fetcher entry point is incompatible with the
125+
* installed expo-file-system version. The default entry point requires the
126+
* new Directory/File API (Expo SDK 54+); use the `/legacy` entry point on
127+
* older SDKs.
128+
*/
129+
ResourceFetcherFileSystemApiUnavailable = 188,
123130
};
124131

125132
} // namespace rnexecutorch

‎packages/react-native-executorch/src/errors/ErrorCodes.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,10 @@ export enum RnExecutorchErrorCode {
114114
* Thrown when the platform does not support the resource fetching feature, which is required for downloading models and other resources in React Native ExecuTorch.
115115
*/
116116
ResourceFetcherPlatformNotSupported = 187,
117+
/**
118+
* Thrown when the Expo resource fetcher entry point is incompatible with the installed expo-file-system version. The default entry point requires the new Directory/File API (Expo SDK 54+); use the `/legacy` entry point on older SDKs.
119+
*/
120+
ResourceFetcherFileSystemApiUnavailable = 188,
117121
/**
118122
* Status indicating a successful operation.
119123
*/

‎scripts/errors.config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,10 @@ export const errorDefinitions = {
125125
* Thrown when the platform does not support the resource fetching feature, which is required for downloading models and other resources in React Native ExecuTorch.
126126
*/
127127
ResourceFetcherPlatformNotSupported: 0xbb,
128+
/**
129+
* Thrown when the Expo resource fetcher entry point is incompatible with the installed expo-file-system version. The default entry point requires the new Directory/File API (Expo SDK 54+); use the `/legacy` entry point on older SDKs.
130+
*/
131+
ResourceFetcherFileSystemApiUnavailable: 0xbc,
128132

129133
// =========================================================================
130134
// ExecuTorch mapped errors (0x00–0x3f)

0 commit comments

Comments
 (0)