fix: improve readme regarding type safety

Also add local implementation fo described helper and migrate to it where applicable.

Author: xobotyi

README.md

@@ -94,24 +94,22 @@ regarding the testing environment configuration. Since you're using this library
 testing environment, making this error redundant.
 
 ```ts filename="useState.test.ts"
-import {expect, test} from 'vitest';
 import {act, renderHook} from '@ver0/react-hooks-testing';
+import {useState} from 'react';
+import {expect, test} from 'vitest';
+import {expectResultValue} from './test-helpers.test.js';
 
 test('should use setState value', async () => {
 	const {result} = await renderHook(() => useState('foo'));
 
-	expect(result.value).toBe('foo');
-	expect(result.error).toBe(undefined);
-
-	if (result.value === undefined) {
-		return;
-	}
+	const value = expectResultValue(result);
+	expect(value[0]).toBe('foo');
 
 	await act(async () => {
-		result.value[1]('bar');
+		value[1]('bar');
 	});
 
-	expect(result.value[0]).toBe('bar');
+	expect(expectResultValue(result)[0]).toBe('bar');
 });
 ```
 
@@ -150,13 +148,44 @@ each render.
 Another notable difference is the `error` property. This property captures any error thrown during the hook’s rendering,
 thanks to an Error Boundary component wrapped around the hook’s harness component.
 
-Each result object is immutable and contains either a `value` or an `error` property—but never both. The hook’s result
-object follows the same principle. Although the `value` and `error` properties are implemented as getters and always
-exist, the values they return correspond to the most recent render result from the `all` array.
+Each result object is immutable and has either a `value` or an `error` property set. The hook's result object follows
+the same principle. Although the `value` and `error` properties are implemented as getters and always exist, the values
+they return correspond to the most recent render result from the `all` array.
+
+> Though it is possible for both values to become `undefined` simultaneously, when a hook returns `undefined` as a valid
+> value, it is developer's responsibility to check error prior to using the value. The other theoretical possibility is
+> `undefined` being thrown, but that is considered a bad practice and thus not handled specifically.
 
 Otherwise, the API is similar to `@testing-library/react`. Note that the `waitForNextUpdate` function is not provided,
 as modern testing frameworks include their own `waitFor` function, which serves the same purpose.
 
+**Type-Safety Helper**
+
+While the discriminated union type provides strong type safety, manually checking for errors in every test can be
+annoyingly verbose. To ease usage while ensuring both type-safety and test coverage, you can introduce a helper
+function:
+
+```ts filename="test-helpers.test.ts"
+import type {ResultValue} from '@ver0/react-hooks-testing';
+import {expect} from 'vitest';
+
+/**
+ * Helper to assert that a hook result is successful and extract its value in a type-safe way.
+ */
+export function expectResultValue<T>(result: ResultValue<T>) {
+	expect(result.error).toBeUndefined();
+
+	if (result.error) {
+		throw new Error('result has unexpected error');
+	}
+
+	return result.value;
+}
+```
+
+This helper both asserts that no error occurred and narrows the TypeScript type, allowing you to work with
+`result.value` directly, as demonstrated in the example above.
+
 #### Testing server-side hooks
 
 The primary purpose of this package is to provide out-of-the-box SSR (Server-Side Rendering) support through the

src/create-hook-renderer.ts

@@ -58,7 +58,7 @@ function newResults<T>() {
 			results.push(Object.freeze({value, error: undefined}));
 		},
 		setError(error: Error) {
-			results.push(Object.freeze({value: undefined, error}));
+			results.push(Object.freeze({error, value: undefined}));
 		},
 	};
 }

src/tests/result-history.ssr.test.ts

@@ -1,5 +1,6 @@
 import {describe, expect, test} from 'vitest';
 import {renderHookServer} from '../index.js';
+import {expectResultValue} from './test-helpers.test.js';
 
 describe('result history SSR', () => {
 	function useValue(value: number) {
@@ -13,7 +14,7 @@ describe('result history SSR', () => {
 	test('should capture all renders states of hook with hydration', async () => {
 		const {result} = await renderHookServer((value) => useValue(value), {initialProps: 0});
 
-		expect(result.value).toEqual(0);
+		expect(expectResultValue(result)).toEqual(0);
 		expect(result.all).toEqual([{value: 0}]);
 	});
 });

src/tests/test-helpers.test.ts

@@ -0,0 +1,15 @@
+import {expect} from 'vitest';
+import type {ResultValue} from '../index.js';
+
+/**
+ * Helper to assert that a hook result is successful and extract its value in a type-safe way.
+ */
+export function expectResultValue<T>(result: ResultValue<T>) {
+	expect(result.error).toBeUndefined();
+
+	if (result.error) {
+		throw new Error('result has unexpected error');
+	}
+
+	return result.value;
+}

src/tests/use-state.dom.test.ts

@@ -1,6 +1,7 @@
 import {useState} from 'react';
 import {describe, expect, it} from 'vitest';
 import {act, renderHook, renderHookServer} from '../index.js';
+import {expectResultValue} from './test-helpers.test.js';
 
 describe('useState on the client', () => {
 	it('should use setState value', async () => {
@@ -10,14 +11,7 @@ describe('useState on the client', () => {
 			return {state, setState};
 		});
 
-		expect(result.value).not.toBe(undefined);
-		expect(result.error).toBe(undefined);
-
-		if (result.value === undefined) {
-			return;
-		}
-
-		expect(result.value.state).toBe('foo');
+		expect(expectResultValue(result).state).toBe('foo');
 	});
 
 	it('should update state', async () => {
@@ -27,18 +21,11 @@ describe('useState on the client', () => {
 			return {state, setState};
 		});
 
-		expect(result.value).not.toBe(undefined);
-		expect(result.error).toBe(undefined);
-
-		if (result.value === undefined) {
-			return;
-		}
-
 		await act(async () => {
-			result.value.setState('bar');
+			expectResultValue(result).setState('bar');
 		});
 
-		expect(result.value.state).toBe('bar');
+		expect(expectResultValue(result).state).toBe('bar');
 	});
 });
 
@@ -50,25 +37,18 @@ describe('useState SSR hydrated', () => {
 			return {state, setState};
 		});
 
-		expect(result.value).not.toBe(undefined);
-		expect(result.error).toBe(undefined);
-
-		if (result.value === undefined) {
-			return;
-		}
-
 		await act(async () => {
-			result.value.setState('bar');
+			expectResultValue(result).setState('bar');
 		});
 
 		expect(result.all.length).toBe(1);
 
 		await hydrate();
 
 		await act(async () => {
-			result.value.setState('bar');
+			expectResultValue(result).setState('bar');
 		});
 
-		expect(result.value.state).toBe('bar');
+		expect(expectResultValue(result).state).toBe('bar');
 	});
 });

src/tests/use-state.ssr.test.ts

@@ -1,6 +1,7 @@
 import {useState} from 'react';
 import {describe, expect, it} from 'vitest';
 import {act, renderHookServer} from '../index.js';
+import {expectResultValue} from './test-helpers.test.js';
 
 describe('useState SSR, non-hydrated', () => {
 	it('should use setState value', async () => {
@@ -10,14 +11,7 @@ describe('useState SSR, non-hydrated', () => {
 			return {state, setState};
 		});
 
-		expect(result.value).not.toBe(undefined);
-		expect(result.error).toBe(undefined);
-
-		if (result.value === undefined) {
-			return;
-		}
-
-		expect(result.value.state).toBe('foo');
+		expect(expectResultValue(result).state).toBe('foo');
 	});
 
 	it('should not update state without hydration', async () => {
@@ -27,15 +21,8 @@ describe('useState SSR, non-hydrated', () => {
 			return {state, setState};
 		});
 
-		expect(result.value).not.toBe(undefined);
-		expect(result.error).toBe(undefined);
-
-		if (result.value === undefined) {
-			return;
-		}
-
 		await act(async () => {
-			result.value.setState('bar');
+			expectResultValue(result).setState('bar');
 		});
 
 		expect(result.all.length).toBe(1);