feat: Add prevent load to all hooks (#323)

pweglik · web-flow · commit b013e43c63cb · 2025-05-22T15:12:48.000+02:00
### Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update (improves or adds clarity to existing documentation) ### Tested on - [x] iOS (CV) - [ ] Android ### Related issues #303 ### Checklist - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [x] I have updated the documentation accordingly - [x] My changes generate no new warnings
diff --git a/docs/docs/computer-vision/useClassification.md b/docs/docs/computer-vision/useClassification.md
@@ -35,6 +35,8 @@ try {
 **`modelSource`**
 A string that specifies the location of the model binary. For more information, take a look at [loading models](../fundamentals/loading-models.md) page.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 | Field              | Type                                                         | Description                                                                                              |
diff --git a/docs/docs/computer-vision/useImageSegmentation.md b/docs/docs/computer-vision/useImageSegmentation.md
@@ -34,6 +34,8 @@ try {
 **`modelSource`**
 A string that specifies the location of the model binary. For more information, take a look at [loading models](../fundamentals/loading-models.md) page.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 | Field              | Type                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
diff --git a/docs/docs/computer-vision/useOCR.md b/docs/docs/computer-vision/useOCR.md
@@ -144,6 +144,8 @@ For more information, take a look at [loading models](../fundamentals/loading-mo
 
 **`language`** - A parameter that specifies the language of the text to be recognized by the OCR.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 The hook returns an object with the following properties:
diff --git a/docs/docs/computer-vision/useObjectDetection.md b/docs/docs/computer-vision/useObjectDetection.md
@@ -51,11 +51,11 @@ interface Detection {
 
 ### Arguments
 
-`modelSource`
-
-A string that specifies the path to the model file. You can download the model from our [HuggingFace repository](https://huggingface.co/software-mansion/react-native-executorch-ssdlite320-mobilenet-v3-large/tree/main).
+**`modelSource`** - A string that specifies the path to the model file. You can download the model from our [HuggingFace repository](https://huggingface.co/software-mansion/react-native-executorch-ssdlite320-mobilenet-v3-large/tree/main).
 For more information on that topic, you can check out the [Loading models](https://docs.swmansion.com/react-native-executorch/fundamentals/loading-models) page.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 The hook returns an object with the following properties:
diff --git a/docs/docs/computer-vision/useStyleTransfer.md b/docs/docs/computer-vision/useStyleTransfer.md
@@ -34,6 +34,8 @@ try {
 **`modelSource`**
 A string that specifies the location of the model binary. For more information, take a look at [loading models](../fundamentals/loading-models.md) page.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 | Field              | Type                                 | Description                                                                                              |
diff --git a/docs/docs/computer-vision/useVerticalOCR.md b/docs/docs/computer-vision/useVerticalOCR.md
@@ -161,6 +161,8 @@ For more information, take a look at [loading models](../fundamentals/loading-mo
 
 **`independentCharacters`** – A boolean parameter that indicates whether the text in the image consists of a random sequence of characters. If set to true, the algorithm will scan each character individually instead of reading them as continuous text.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 The hook returns an object with the following properties:
diff --git a/docs/docs/executorch-bindings/useExecutorchModule.md b/docs/docs/executorch-bindings/useExecutorchModule.md
@@ -26,6 +26,8 @@ The `modelSource` parameter expects a location string pointing to the model bina
 
 **`modelSource`** - A string that specifies the location of the model binary.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 |       Field        |                            Type                            |                                                                                             Description                                                                                             |
diff --git a/docs/docs/natural-language-processing/useSpeechToText.md b/docs/docs/natural-language-processing/useSpeechToText.md
@@ -89,6 +89,8 @@ Specifies the size of each audio chunk (expressed in seconds). Overrides `stream
 **`streamingConfig?`**
 Specifies config for both `overlapSeconds` and `windowSize` values. Three options are available: `fast`, `balanced` and `quality`. We discourage using `fast` config with `Whisper` model which while has the lowest latency to first token has the slowest overall speed.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 | Field                 | Type                                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
diff --git a/docs/docs/natural-language-processing/useTextEmbeddings.md b/docs/docs/natural-language-processing/useTextEmbeddings.md
@@ -50,6 +50,8 @@ A string that specifies the location of the model binary. For more information,
 **`tokenizerSource`**
 A string that specifies the location of the tokenizer JSON file.
 
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
+
 ### Returns
 
 | Field              | Type                                   | Description                                                                       |
diff --git a/docs/docs/natural-language-processing/useTokenizer.md b/docs/docs/natural-language-processing/useTokenizer.md
@@ -51,7 +51,9 @@ try {
 
 ## Arguments
 
-A string that specifies the path or URI of the tokenizer JSON file.
+**`tokenizerSource`** - A string that specifies the path or URI of the tokenizer JSON file.
+
+**`preventLoad?`** - Boolean that can prevent automatic model loading (and downloading the data if you load it for the first time) after running the hook.
 
 ### Returns
 
diff --git a/examples/computer-vision/package.json b/examples/computer-vision/package.json
@@ -17,7 +17,7 @@
     "metro-config": "^0.81.0",
     "react": "19.0.0",
     "react-native": "0.79.2",
-    "react-native-executorch": "^0.3.2",
+    "react-native-executorch": "^0.4.0",
     "react-native-image-picker": "^7.2.2",
     "react-native-loading-spinner-overlay": "^3.0.1",
     "react-native-reanimated": "~3.17.4",
diff --git a/examples/llm/package.json b/examples/llm/package.json
@@ -19,7 +19,7 @@
     "react": "19.0.0",
     "react-native": "^0.79.2",
     "react-native-audio-api": "0.5.7",
-    "react-native-executorch": "^0.3.2",
+    "react-native-executorch": "^0.4.0",
     "react-native-live-audio-stream": "^1.1.1",
     "react-native-loading-spinner-overlay": "^3.0.1",
     "react-native-markdown-display": "^7.0.2",
diff --git a/examples/speech-to-text/package.json b/examples/speech-to-text/package.json
@@ -19,7 +19,7 @@
     "react-native": "0.79.2",
     "react-native-audio-api": "0.5.7",
     "react-native-device-info": "^14.0.4",
-    "react-native-executorch": "^0.3.2",
+    "react-native-executorch": "^0.4.0",
     "react-native-image-picker": "^7.2.2",
     "react-native-live-audio-stream": "^1.1.1",
     "react-native-loading-spinner-overlay": "^3.0.1",
diff --git a/examples/text-embeddings/package.json b/examples/text-embeddings/package.json
@@ -13,7 +13,7 @@
     "expo-status-bar": "~2.2.3",
     "react": "19.0.0",
     "react-native": "0.79.2",
-    "react-native-executorch": "^0.3.2"
+    "react-native-executorch": "^0.4.0"
   },
   "devDependencies": {
     "@babel/core": "^7.25.2",
diff --git a/src/hooks/computer_vision/useClassification.ts b/src/hooks/computer_vision/useClassification.ts
@@ -4,6 +4,13 @@ import { useModule } from '../useModule';
 
 export const useClassification = ({
   modelSource,
+  preventLoad = false,
 }: {
   modelSource: ResourceSource;
-}) => useModule({ module: ClassificationModule, loadArgs: [modelSource] });
+  preventLoad?: boolean;
+}) =>
+  useModule({
+    module: ClassificationModule,
+    loadArgs: [modelSource],
+    preventLoad,
+  });
diff --git a/src/hooks/computer_vision/useImageSegmentation.ts b/src/hooks/computer_vision/useImageSegmentation.ts
@@ -1,9 +1,18 @@
 import { useModule } from '../useModule';
 import { ImageSegmentationModule } from '../../modules/computer_vision/ImageSegmentationModule';
+import { ResourceSource } from '../../types/common';
 
 interface Props {
-  modelSource: string | number;
+  modelSource: ResourceSource;
+  preventLoad?: boolean;
 }
 
-export const useImageSegmentation = ({ modelSource }: Props) =>
-  useModule({ module: ImageSegmentationModule, loadArgs: [modelSource] });
+export const useImageSegmentation = ({
+  modelSource,
+  preventLoad = false,
+}: Props) =>
+  useModule({
+    module: ImageSegmentationModule,
+    loadArgs: [modelSource],
+    preventLoad,
+  });
diff --git a/src/hooks/computer_vision/useOCR.ts b/src/hooks/computer_vision/useOCR.ts
@@ -15,6 +15,7 @@ export const useOCR = ({
   detectorSource,
   recognizerSources,
   language = 'en',
+  preventLoad = false,
 }: {
   detectorSource: ResourceSource;
   recognizerSources: {
@@ -23,6 +24,7 @@ export const useOCR = ({
     recognizerSmall: ResourceSource;
   };
   language?: OCRLanguage;
+  preventLoad?: boolean;
 }): OCRModule => {
   const [error, setError] = useState<string | null>(null);
   const [isReady, setIsReady] = useState(false);
@@ -45,9 +47,18 @@ export const useOCR = ({
       await model.loadModel(detectorSource, recognizerSources, language);
     };
 
-    loadModel();
+    if (!preventLoad) {
+      loadModel();
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [model, detectorSource, language, JSON.stringify(recognizerSources)]);
+  }, [
+    model,
+    detectorSource,
+    language,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    JSON.stringify(recognizerSources),
+    preventLoad,
+  ]);
 
   return {
     error,
diff --git a/src/hooks/computer_vision/useObjectDetection.ts b/src/hooks/computer_vision/useObjectDetection.ts
@@ -4,7 +4,15 @@ import { ObjectDetectionModule } from '../../modules/computer_vision/ObjectDetec
 
 interface Props {
   modelSource: ResourceSource;
+  preventLoad?: boolean;
 }
 
-export const useObjectDetection = ({ modelSource }: Props) =>
-  useModule({ module: ObjectDetectionModule, loadArgs: [modelSource] });
+export const useObjectDetection = ({
+  modelSource,
+  preventLoad = false,
+}: Props) =>
+  useModule({
+    module: ObjectDetectionModule,
+    loadArgs: [modelSource],
+    preventLoad,
+  });
diff --git a/src/hooks/computer_vision/useStyleTransfer.ts b/src/hooks/computer_vision/useStyleTransfer.ts
@@ -4,7 +4,12 @@ import { StyleTransferModule } from '../../modules/computer_vision/StyleTransfer
 
 interface Props {
   modelSource: ResourceSource;
+  preventLoad?: boolean;
 }
 
-export const useStyleTransfer = ({ modelSource }: Props) =>
-  useModule({ module: StyleTransferModule, loadArgs: [modelSource] });
+export const useStyleTransfer = ({ modelSource, preventLoad = false }: Props) =>
+  useModule({
+    module: StyleTransferModule,
+    loadArgs: [modelSource],
+    preventLoad,
+  });
diff --git a/src/hooks/computer_vision/useVerticalOCR.ts b/src/hooks/computer_vision/useVerticalOCR.ts
@@ -16,6 +16,7 @@ export const useVerticalOCR = ({
   recognizerSources,
   language = 'en',
   independentCharacters = false,
+  preventLoad = false,
 }: {
   detectorSources: {
     detectorLarge: ResourceSource;
@@ -27,6 +28,7 @@ export const useVerticalOCR = ({
   };
   language?: OCRLanguage;
   independentCharacters?: boolean;
+  preventLoad?: boolean;
 }): OCRModule => {
   const [error, setError] = useState<string | null>(null);
   const [isReady, setIsReady] = useState(false);
@@ -54,7 +56,9 @@ export const useVerticalOCR = ({
       );
     };
 
-    loadModel();
+    if (!preventLoad) {
+      loadModel();
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     model,
@@ -64,6 +68,7 @@ export const useVerticalOCR = ({
     independentCharacters,
     // eslint-disable-next-line react-hooks/exhaustive-deps
     JSON.stringify(recognizerSources),
+    preventLoad,
   ]);
 
   return {
diff --git a/src/hooks/general/useExecutorchModule.ts b/src/hooks/general/useExecutorchModule.ts
@@ -1,9 +1,18 @@
 import { ExecutorchModule } from '../../modules/general/ExecutorchModule';
+import { ResourceSource } from '../../types/common';
 import { useModule } from '../useModule';
 
 interface Props {
-  modelSource: string | number;
+  modelSource: ResourceSource;
+  preventLoad?: boolean;
 }
 
-export const useExecutorchModule = ({ modelSource }: Props) =>
-  useModule({ module: ExecutorchModule, loadArgs: [modelSource] });
+export const useExecutorchModule = ({
+  modelSource,
+  preventLoad = false,
+}: Props) =>
+  useModule({
+    module: ExecutorchModule,
+    loadArgs: [modelSource],
+    preventLoad,
+  });
diff --git a/src/hooks/natural_language_processing/useSpeechToText.ts b/src/hooks/natural_language_processing/useSpeechToText.ts
@@ -30,6 +30,7 @@ export const useSpeechToText = ({
   overlapSeconds,
   windowSize,
   streamingConfig,
+  preventLoad = false,
 }: {
   modelName: AvailableModels;
   encoderSource?: ResourceSource;
@@ -44,6 +45,7 @@ export const useSpeechToText = ({
   streamingConfig?: ConstructorParameters<
     typeof SpeechToTextController
   >['0']['streamingConfig'];
+  preventLoad?: boolean;
 }): SpeechToTextModule => {
   const [sequence, setSequence] = useState<string>('');
   const [isReady, setIsReady] = useState(false);
@@ -76,8 +78,17 @@ export const useSpeechToText = ({
         tokenizerSource
       );
     };
-    loadModel();
-  }, [model, modelName, encoderSource, decoderSource, tokenizerSource]);
+    if (!preventLoad) {
+      loadModel();
+    }
+  }, [
+    model,
+    modelName,
+    encoderSource,
+    decoderSource,
+    tokenizerSource,
+    preventLoad,
+  ]);
 
   return {
     isReady,
diff --git a/src/hooks/natural_language_processing/useTextEmbeddings.ts b/src/hooks/natural_language_processing/useTextEmbeddings.ts
@@ -5,11 +5,14 @@ import { useModule } from '../useModule';
 export const useTextEmbeddings = ({
   modelSource,
   tokenizerSource,
+  preventLoad = false,
 }: {
   modelSource: ResourceSource;
   tokenizerSource: ResourceSource;
+  preventLoad?: boolean;
 }) =>
   useModule({
     module: TextEmbeddingsModule,
     loadArgs: [modelSource, tokenizerSource],
+    preventLoad,
   });
diff --git a/src/hooks/natural_language_processing/useTokenizer.ts b/src/hooks/natural_language_processing/useTokenizer.ts
@@ -5,8 +5,10 @@ import { ETError, getError } from '../../Error';
 
 export const useTokenizer = ({
   tokenizerSource,
+  preventLoad = false,
 }: {
   tokenizerSource: ResourceSource;
+  preventLoad?: boolean;
 }) => {
   const [error, setError] = useState<null | string>(null);
   const [isReady, setIsReady] = useState(false);
@@ -24,8 +26,10 @@ export const useTokenizer = ({
         setError((err as Error).message);
       }
     };
-    loadModule();
-  }, [tokenizerSource]);
+    if (!preventLoad) {
+      loadModule();
+    }
+  }, [tokenizerSource, preventLoad]);
 
   const stateWrapper = <T extends (...args: any[]) => Promise<any>>(fn: T) => {
     const boundFn = fn.bind(TokenizerModule);
diff --git a/src/hooks/useModule.ts b/src/hooks/useModule.ts
@@ -15,9 +15,11 @@ export const useModule = <
 >({
   module,
   loadArgs,
+  preventLoad = false,
 }: {
   module: M;
   loadArgs: LoadArgs;
+  preventLoad?: boolean;
 }) => {
   const [error, setError] = useState<null | string>(null);
   const [isReady, setIsReady] = useState(false);
@@ -35,9 +37,11 @@ export const useModule = <
         setError((err as Error).message);
       }
     };
-    loadModule();
+    if (!preventLoad) {
+      loadModule();
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [...loadArgs]);
+  }, [...loadArgs, preventLoad]);
 
   const forward = async (...input: ForwardArgs): Promise<ForwardReturn> => {
     if (!isReady) throw new Error(getError(ETError.ModuleNotLoaded));
diff --git a/src/index.tsx b/src/index.tsx
diff --git a/src/modules/computer_vision/ImageSegmentationModule.ts b/src/modules/computer_vision/ImageSegmentationModule.ts
diff --git a/src/native/NativeObjectDetection.ts b/src/native/NativeObjectDetection.ts
diff --git a/src/types/imageSegmentation.ts b/src/types/imageSegmentation.ts
diff --git a/src/types/objectDetection.ts b/src/types/objectDetection.ts
