fix!: use discriminated union with Error type for useViewModelInstance result

Author: mfazekas

example/src/demos/DataBindingArtboardsExample.tsx

@@ -78,7 +78,7 @@ function ArtboardSwapper({
   mainFile: RiveFile;
   assetsFile: RiveFile;
 }) {
-  const instance = useViewModelInstance(mainFile);
+  const { instance } = useViewModelInstance(mainFile);
   const [currentArtboard, setCurrentArtboard] = useState<string>('Dragon');
   const initializedRef = useRef(false);
 

example/src/exercisers/FontFallbackExample.tsx

@@ -258,7 +258,7 @@ function MountedView({ text }: { text: string }) {
     // https://rive.app/marketplace/26480-49641-simple-test-text-property/
     require('../../assets/rive/font_fallback.riv')
   );
-  const instance = useViewModelInstance(riveFile ?? null);
+  const { instance } = useViewModelInstance(riveFile ?? null);
 
   const { setValue: setRiveText, error: textError } = useRiveString(
     TEXT_PROPERTY,

example/src/exercisers/NestedViewModelExample.tsx

@@ -38,7 +38,7 @@ export default function NestedViewModelExample() {
 }
 
 function WithViewModelSetup({ file }: { file: RiveFile }) {
-  const instance = useViewModelInstance(file);
+  const { instance } = useViewModelInstance(file);
 
   if (!instance) {
     return <ActivityIndicator size="large" color="#0000ff" />;

example/src/exercisers/RiveDataBindingExample.tsx

@@ -35,7 +35,7 @@ export default function WithRiveFile() {
 }
 
 function WithViewModelSetup({ file }: { file: RiveFile }) {
-  const instance = useViewModelInstance(file);
+  const { instance } = useViewModelInstance(file);
 
   if (!instance) {
     return <ActivityIndicator size="large" color="#0000ff" />;

src/hooks/__tests__/useViewModelInstance.test.ts

@@ -107,7 +107,7 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
     expect(result.current.error).toBeNull();
   });
 
-  it('should return null when instance name not found and required is false', () => {
+  it('should return error when instance name not found and required is false', () => {
     const defaultViewModel = createMockViewModel({
       namedInstances: {},
     });
@@ -119,7 +119,8 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
     );
 
     expect(result.current.instance).toBeNull();
-    expect(result.current.error).toContain('not found');
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain('NonExistent');
   });
 
   it('should throw when instance name not found and required is true', () => {
@@ -139,7 +140,7 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
     ).toThrow("ViewModel instance 'NonExistent' not found");
   });
 
-  it('should return null when artboardName not found and required is false', () => {
+  it('should return error when artboardName not found and required is false', () => {
     const mockRiveFile = createMockRiveFile({
       artboardViewModels: {},
     });
@@ -149,7 +150,8 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
     );
 
     expect(result.current.instance).toBeNull();
-    expect(result.current.error).toContain('not found');
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain('MissingArtboard');
   });
 
   it('should throw when artboardName not found and required is true', () => {
@@ -262,7 +264,7 @@ describe('useViewModelInstance - RiveFile with viewModelName parameter', () => {
     expect(result.current.error).toBeNull();
   });
 
-  it('should return null when viewModelName not found and required is false', () => {
+  it('should return error when viewModelName not found and required is false', () => {
     const mockRiveFile = createMockRiveFile({
       namedViewModels: {},
     });
@@ -272,7 +274,8 @@ describe('useViewModelInstance - RiveFile with viewModelName parameter', () => {
     );
 
     expect(result.current.instance).toBeNull();
-    expect(result.current.error).toContain('not found');
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain('NonExistent');
   });
 
   it('should throw when viewModelName not found and required is true', () => {

src/hooks/useViewModelInstance.ts

@@ -176,17 +176,17 @@ function createInstance(
   return { instance: vmi ?? null, needsDispose: true };
 }
 
-export type UseViewModelInstanceResult = {
-  instance: ViewModelInstance | null;
-  error: string | null;
-};
+export type UseViewModelInstanceResult =
+  | { instance: ViewModelInstance; error: null }
+  | { instance: null; error: Error }
+  | { instance: null; error: null };
 
 /**
  * Hook for getting a ViewModelInstance from a RiveFile, ViewModel, or RiveViewRef.
  *
  * @param source - The RiveFile, ViewModel, or RiveViewRef to get an instance from
  * @param params - Configuration for which instance to retrieve
- * @returns An object with `instance` (the ViewModelInstance or null) and `error` (string or null)
+ * @returns An object with `instance` and `error` (discriminated union)
  *
  * @example
  * ```tsx
@@ -234,7 +234,7 @@ export type UseViewModelInstanceResult = {
  * ```tsx
  * // Create a new blank instance from ViewModel
  * const viewModel = file.viewModelByName('TodoItem');
- * const { instance: newInstance } = useViewModelInstance(viewModel, { useNew: true });
+ * const { instance } = useViewModelInstance(viewModel, { useNew: true });
  * ```
  *
  * @example
@@ -253,7 +253,13 @@ export type UseViewModelInstanceResult = {
  *     vmi.stringProperty('name').set(userName);
  *   }
  * });
- * // Values are already set here
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Error handling
+ * const { instance, error } = useViewModelInstance(riveFile, { viewModelName: 'Missing' });
+ * if (error) console.error(error.message);
  * ```
  */
 // RiveFile overloads
@@ -352,6 +358,8 @@ export function useViewModelInstance(
     };
   }, []);
 
+  const error = result.error ? new Error(result.error) : null;
+
   if (required && result.instance === null) {
     throw new Error(
       result.error
@@ -361,5 +369,8 @@ export function useViewModelInstance(
     );
   }
 
-  return { instance: result.instance, error: result.error ?? null };
+  if (result.instance) {
+    return { instance: result.instance, error: null };
+  }
+  return { instance: null, error };
 }