feat: requested changes

Author: NorbertKlockiewicz

packages/react-native-executorch/src/controllers/BaseOCRController.ts

@@ -89,8 +89,11 @@ export abstract class BaseOCRController {
   };
 
   get runOnFrame(): ((frame: Frame) => OCRDetection[]) | null {
-    if (!this.nativeModule?.generateFromFrame) {
-      return null;
+    if (!this.isReady) {
+      throw new RnExecutorchError(
+        RnExecutorchErrorCode.ModuleNotLoaded,
+        'The model is currently not loaded. Please load the model before calling runOnFrame().'
+      );
     }
 
     const nativeGenerateFromFrame = this.nativeModule.generateFromFrame;

packages/react-native-executorch/src/modules/computer_vision/ClassificationModule.ts

@@ -14,6 +14,10 @@ import { VisionModule } from './VisionModule';
 export class ClassificationModule extends VisionModule<{
   [category: string]: number;
 }> {
+  private constructor(nativeModule: unknown) {
+    super();
+    this.nativeModule = nativeModule;
+  }
   /**
    * Creates a classification instance for a built-in model.
    *
@@ -41,9 +45,9 @@ export class ClassificationModule extends VisionModule<{
         );
       }
 
-      const instance = new ClassificationModule();
-      instance.nativeModule = await global.loadClassification(paths[0]);
-      return instance;
+      return new ClassificationModule(
+        await global.loadClassification(paths[0])
+      );
     } catch (error) {
       Logger.error('Load failed:', error);
       throw parseUnknownError(error);

packages/react-native-executorch/src/modules/computer_vision/ImageEmbeddingsModule.ts

@@ -12,6 +12,10 @@ import { VisionModule } from './VisionModule';
  * @category Typescript API
  */
 export class ImageEmbeddingsModule extends VisionModule<Float32Array> {
+  private constructor(nativeModule: unknown) {
+    super();
+    this.nativeModule = nativeModule;
+  }
   /**
    * Creates an image embeddings instance for a built-in model.
    *
@@ -39,9 +43,9 @@ export class ImageEmbeddingsModule extends VisionModule<Float32Array> {
         );
       }
 
-      const instance = new ImageEmbeddingsModule();
-      instance.nativeModule = await global.loadImageEmbeddings(paths[0]);
-      return instance;
+      return new ImageEmbeddingsModule(
+        await global.loadImageEmbeddings(paths[0])
+      );
     } catch (error) {
       Logger.error('Load failed:', error);
       throw parseUnknownError(error);

packages/react-native-executorch/src/modules/computer_vision/StyleTransferModule.ts

@@ -12,6 +12,10 @@ import { VisionModule } from './VisionModule';
  * @category Typescript API
  */
 export class StyleTransferModule extends VisionModule<PixelData | string> {
+  private constructor(nativeModule: unknown) {
+    super();
+    this.nativeModule = nativeModule;
+  }
   /**
    * Creates a style transfer instance for a built-in model.
    *
@@ -39,9 +43,7 @@ export class StyleTransferModule extends VisionModule<PixelData | string> {
         );
       }
 
-      const instance = new StyleTransferModule();
-      instance.nativeModule = await global.loadStyleTransfer(paths[0]);
-      return instance;
+      return new StyleTransferModule(await global.loadStyleTransfer(paths[0]));
     } catch (error) {
       Logger.error('Load failed:', error);
       throw parseUnknownError(error);

packages/react-native-executorch/src/modules/computer_vision/VisionLabeledModule.ts

@@ -4,6 +4,8 @@ import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 import { VisionModule } from './VisionModule';
 
+export { ResolveLabels } from '../../types/computerVision';
+
 /**
  * Fetches a model binary and returns its local path, throwing if the download
  * was interrupted (paused or cancelled).
@@ -24,22 +26,6 @@ export async function fetchModelPath(
   return paths[0];
 }
 
-/**
- * Given a model configs record (mapping model names to `{ labelMap }`) and a
- * type `T` (either a model name key or a raw {@link LabelEnum}), resolves to
- * the label map for that model or `T` itself.
- *
- * @internal
- */
-export type ResolveLabels<
-  T,
-  Configs extends Record<string, { labelMap: LabelEnum }>,
-> = T extends keyof Configs
-  ? Configs[T]['labelMap']
-  : T extends LabelEnum
-    ? T
-    : never;
-
 /**
  * Base class for computer vision modules that carry a type-safe label map
  * and support the full VisionModule API (string/PixelData forward + runOnFrame).

packages/react-native-executorch/src/modules/computer_vision/VisionModule.ts

@@ -59,8 +59,11 @@ export abstract class VisionModule<TOutput> extends BaseModule {
    * ```
    */
   get runOnFrame(): ((frame: Frame, ...args: any[]) => TOutput) | null {
-    if (!this.nativeModule?.generateFromFrame) {
-      return null;
+    if (!this.nativeModule) {
+      throw new RnExecutorchError(
+        RnExecutorchErrorCode.ModuleNotLoaded,
+        'The model is currently not loaded. Please load the model before calling runOnFrame().'
+      );
     }
 
     // Extract pure JSI function reference (runs on JS thread)
@@ -73,9 +76,7 @@ export abstract class VisionModule<TOutput> extends BaseModule {
       let nativeBuffer: any = null;
       try {
         nativeBuffer = frame.getNativeBuffer();
-        const frameData = {
-          nativeBuffer: nativeBuffer.pointer,
-        };
+        const frameData = { nativeBuffer: nativeBuffer.pointer };
         return nativeGenerateFromFrame(frameData, ...args);
       } finally {
         if (nativeBuffer?.release) {

packages/react-native-executorch/src/types/classification.ts

@@ -77,20 +77,6 @@ export interface ClassificationType {
    *
    * Available after model is loaded (`isReady: true`).
    *
-   * @example
-   * ```typescript
-   * const { runOnFrame, isReady } = useClassification({ model: MODEL });
-   *
-   * const frameOutput = useFrameOutput({
-   *   onFrame(frame) {
-   *     'worklet';
-   *     if (!runOnFrame) return;
-   *     const result = runOnFrame(frame);
-   *     frame.dispose();
-   *   }
-   * });
-   * ```
-   *
    * @param frame - VisionCamera Frame object
    * @returns Object mapping class labels to confidence scores.
    */

packages/react-native-executorch/src/types/computerVision.ts

@@ -0,0 +1,17 @@
+import { LabelEnum } from './common';
+
+/**
+ * Given a model configs record (mapping model names to `{ labelMap }`) and a
+ * type `T` (either a model name key or a raw {@link LabelEnum}), resolves to
+ * the label map for that model or `T` itself.
+ *
+ * @internal
+ */
+export type ResolveLabels<
+  T,
+  Configs extends Record<string, { labelMap: LabelEnum }>,
+> = T extends keyof Configs
+  ? Configs[T]['labelMap']
+  : T extends LabelEnum
+    ? T
+    : never;

packages/react-native-executorch/src/types/imageEmbeddings.ts

@@ -60,7 +60,7 @@ export interface ImageEmbeddingsType {
    *
    * **Note**: For VisionCamera frame processing, use `runOnFrame` instead.
    *
-   * @param input - Image source (string or PixelData object)
+   * @param input - Image source (string or {@link PixelData} object)
    * @returns A Promise that resolves to a `Float32Array` containing the generated embedding vector.
    * @throws {RnExecutorchError} If the model is not loaded or is currently processing another image.
    */