@hubspot/ui-extensions 0.12.4 → 0.13.1

package/dist/__tests__/experimental/hooks/utils/fetchCrmSearch.spec.js

@@ -0,0 +1,217 @@
+import { vi } from 'vitest';
+import { fetchCrmSearch } from "../../../../experimental/hooks/utils/fetchCrmSearch.js";
+const mockFetchCrmSearch = vi.fn();
+// Mock the global self object to match the hsWorkerAPI shape
+Object.defineProperty(global, 'self', {
+    value: {
+        __HUBSPOT_EXTENSION_WORKER__: true,
+        hsWorkerAPI: {
+            fetchCrmSearch: mockFetchCrmSearch,
+        },
+    },
+    writable: true,
+});
+describe('fetchCrmSearch', () => {
+    const createMockResponse = (data, overrides = {}) => ({
+        ok: true,
+        json: vi.fn().mockResolvedValue({ data, cleanup: vi.fn() }),
+        ...overrides,
+    });
+    const createBasicRequest = (overrides = {}) => ({
+        objectType: '0-1',
+        properties: ['firstname', 'lastname'],
+        ...overrides,
+    });
+    const createValidResponseData = (overrides = {}) => ({
+        results: [
+            {
+                objectId: 1001,
+                properties: { firstname: 'John', lastname: 'Doe' },
+            },
+        ],
+        total: 1,
+        hasMore: false,
+        ...overrides,
+    });
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('basic functionality', () => {
+        it('should successfully fetch CRM search results', async () => {
+            const data = createValidResponseData();
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse(data));
+            const request = createBasicRequest();
+            const result = await fetchCrmSearch(request);
+            expect(result).toHaveProperty('data');
+            expect(result).toHaveProperty('cleanup');
+            expect(typeof result.cleanup).toBe('function');
+            expect(result.data).toEqual(data);
+        });
+        it('should return a Promise', () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse(createValidResponseData()));
+            const result = fetchCrmSearch(createBasicRequest());
+            expect(result).toBeInstanceOf(Promise);
+        });
+        it('should support all request fields (query, filterGroups, sorts, pageSize, after)', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse(createValidResponseData({ hasMore: true, after: 'cursor-2' })));
+            const request = {
+                objectType: '0-1',
+                properties: ['firstname'],
+                query: 'john',
+                filterGroups: [
+                    {
+                        filters: [
+                            { propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' },
+                        ],
+                    },
+                ],
+                sorts: [
+                    { propertyName: 'createdate', direction: 'DESCENDING' },
+                ],
+                pageSize: 25,
+                after: 'cursor-1',
+            };
+            await fetchCrmSearch(request);
+            expect(mockFetchCrmSearch).toHaveBeenCalledWith(request, undefined);
+        });
+    });
+    describe('error handling', () => {
+        it('should throw an error when fetch fails', async () => {
+            mockFetchCrmSearch.mockRejectedValueOnce(new Error('Network error'));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Network error');
+        });
+        it('should handle unknown errors with a default message', async () => {
+            mockFetchCrmSearch.mockRejectedValueOnce('Unknown error');
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Failed to fetch CRM search results: Unknown error');
+        });
+        it('should throw when server returns an error field', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce({
+                ok: true,
+                json: vi.fn().mockResolvedValue({
+                    error: 'Permission denied',
+                    cleanup: vi.fn(),
+                }),
+            });
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Permission denied');
+        });
+    });
+    describe('response validation', () => {
+        it('should throw error when results field is missing', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse({ total: 0, hasMore: false }) // missing results
+            );
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+        it('should throw error when results is not an array', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse({
+                results: 'not an array',
+                total: 0,
+                hasMore: false,
+            }));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+        it('should throw error when total is not a number', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse({ results: [], total: 'zero', hasMore: false }));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+        it('should throw error when hasMore is not a boolean', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse({ results: [], total: 0, hasMore: 'yes' }));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+        it('should throw error when data is null', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse(null));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+        it('should throw error when a result is missing objectId', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse({
+                results: [{ properties: {} }],
+                total: 1,
+                hasMore: false,
+            }));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+        it('should throw error when a result objectId is not a number', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse({
+                results: [{ objectId: '1001', properties: {} }],
+                total: 1,
+                hasMore: false,
+            }));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+        it('should throw error when a result properties field is not an object', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse({
+                results: [{ objectId: 1, properties: null }],
+                total: 1,
+                hasMore: false,
+            }));
+            await expect(fetchCrmSearch(createBasicRequest())).rejects.toThrow('Invalid response format');
+        });
+    });
+    describe('API integration', () => {
+        it('should call hsWorkerAPI.fetchCrmSearch with correct parameters and no options', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse(createValidResponseData()));
+            const request = createBasicRequest({ pageSize: 50 });
+            await fetchCrmSearch(request);
+            expect(mockFetchCrmSearch).toHaveBeenCalledWith(request, undefined);
+        });
+        it('should return the cleanup function provided by the API response', async () => {
+            const mockCleanup = vi.fn();
+            mockFetchCrmSearch.mockResolvedValueOnce({
+                ok: true,
+                json: vi.fn().mockResolvedValue({
+                    data: createValidResponseData(),
+                    cleanup: mockCleanup,
+                }),
+            });
+            const result = await fetchCrmSearch(createBasicRequest());
+            expect(result.cleanup).toBe(mockCleanup);
+            result.cleanup();
+            expect(mockCleanup).toHaveBeenCalledTimes(1);
+        });
+        it('should provide a default cleanup function when none is provided', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce({
+                ok: true,
+                json: vi.fn().mockResolvedValue({ data: createValidResponseData() }),
+            });
+            const result = await fetchCrmSearch(createBasicRequest());
+            expect(typeof result.cleanup).toBe('function');
+            expect(() => result.cleanup()).not.toThrow();
+        });
+    });
+    describe('options handling', () => {
+        it('should pass formatting options to the underlying fetch function', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse(createValidResponseData()));
+            const options = {
+                propertiesToFormat: ['firstname'],
+                formattingOptions: {
+                    date: { format: 'MM/dd/yyyy' },
+                    currency: { addSymbol: true },
+                },
+            };
+            await fetchCrmSearch(createBasicRequest(), options);
+            expect(mockFetchCrmSearch).toHaveBeenCalledWith(createBasicRequest(), options);
+        });
+        it('should handle propertiesToFormat set to "all"', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse(createValidResponseData()));
+            const options = {
+                propertiesToFormat: 'all',
+                formattingOptions: { dateTime: { relative: true } },
+            };
+            await fetchCrmSearch(createBasicRequest(), options);
+            expect(mockFetchCrmSearch).toHaveBeenCalledWith(createBasicRequest(), options);
+        });
+        it('should preserve error handling with formatting options', async () => {
+            mockFetchCrmSearch.mockRejectedValueOnce(new Error('Network error'));
+            const options = {
+                propertiesToFormat: ['firstname'],
+                formattingOptions: { date: { format: 'MM/dd/yyyy' } },
+            };
+            await expect(fetchCrmSearch(createBasicRequest(), options)).rejects.toThrow('Network error');
+            expect(mockFetchCrmSearch).toHaveBeenCalledWith(createBasicRequest(), options);
+        });
+        it('should preserve response validation with formatting options', async () => {
+            mockFetchCrmSearch.mockResolvedValueOnce(createMockResponse('Invalid response') // data should be an object
+            );
+            await expect(fetchCrmSearch(createBasicRequest(), { propertiesToFormat: 'all' })).rejects.toThrow('Invalid response format');
+        });
+    });
+});

package/dist/__tests__/hooks/useDebounce.spec.js

@@ -0,0 +1,123 @@
+import { renderHook } from '@testing-library/react';
+import { act } from 'react';
+import { vi } from 'vitest';
+import { useDebounce } from "../../hooks/useDebounce.js";
+describe('useDebounce', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('should return the initial value immediately', () => {
+        const { result } = renderHook(() => useDebounce('hello', 300));
+        expect(result.current).toBe('hello');
+    });
+    it('should not update the value before the delay has elapsed', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(299);
+        });
+        expect(result.current).toBe('initial');
+    });
+    it('should update the value after the delay has elapsed', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        expect(result.current).toBe('updated');
+    });
+    it('should only propagate the last value when changed rapidly', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'a', delay: 300 } });
+        rerender({ value: 'ab', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        rerender({ value: 'abc', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        expect(result.current).toBe('abc');
+    });
+    it('should reset the timer when the delay changes', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Change the delay — timer should restart
+        rerender({ value: 'updated', delay: 500 });
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        // 200 + 300 = 500ms total, but timer restarted at 200ms so only 300ms of 500ms elapsed
+        expect(result.current).toBe('initial');
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        expect(result.current).toBe('updated');
+    });
+    it('should clean up the timeout on unmount', () => {
+        const { result, rerender, unmount } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        unmount();
+        // Advancing timers after unmount should not cause errors
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        expect(result.current).toBe('initial');
+    });
+    it('should work with numeric values', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 0, delay: 200 } });
+        rerender({ value: 42, delay: 200 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        expect(result.current).toBe(42);
+    });
+    it('should not reset the timer when an object value is deeply equal', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: { query: 'a' }, delay: 300 } });
+        // Change the value
+        rerender({ value: { query: 'ab' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Pass a new reference with the same content — should NOT reset the timer
+        rerender({ value: { query: 'ab' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        // 200 + 100 = 300ms total — should have fired because the new reference didn't reset
+        expect(result.current).toEqual({ query: 'ab' });
+    });
+    it('should debounce when object content actually changes', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: { query: 'a' }, delay: 300 } });
+        rerender({ value: { query: 'ab' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Actual content change — should reset the timer
+        rerender({ value: { query: 'abc' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Only 200ms since the real change — should still be the initial value
+        expect(result.current).toEqual({ query: 'a' });
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        expect(result.current).toEqual({ query: 'abc' });
+    });
+    it('should still defer by one render cycle when delayMs is 0', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 0 } });
+        rerender({ value: 'updated', delay: 0 });
+        // useEffect is async, so even with delay 0 the value is stale for one cycle
+        expect(result.current).toBe('initial');
+        act(() => {
+            vi.advanceTimersByTime(0);
+        });
+        expect(result.current).toBe('updated');
+    });
+});

package/dist/__tests__/hooks/utils/useFetchLifecycle.spec.js

@@ -0,0 +1,324 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { vi } from 'vitest';
+import { useFetchLifecycle, } from "../../../hooks/utils/useFetchLifecycle.js";
+function createMockCallbacks() {
+    return {
+        onStart: vi.fn(),
+        onSuccess: vi.fn(),
+        onError: vi.fn(),
+    };
+}
+describe('useFetchLifecycle', () => {
+    let originalError;
+    beforeAll(() => {
+        // Suppress React act() warnings coming from @testing-library/react
+        originalError = console.error;
+        console.error = (...args) => {
+            if (typeof args[0] === 'string' &&
+                (args[0].includes('ReactDOMTestUtils.act') ||
+                    args[0].includes('was not wrapped in act')))
+                return;
+            originalError.call(console, ...args);
+        };
+    });
+    afterAll(() => {
+        console.error = originalError;
+    });
+    describe('initial fetch', () => {
+        it('should call onStart then onSuccess on successful fetch', async () => {
+            const callbacks = createMockCallbacks();
+            const mockData = { name: 'test' };
+            const mockFetchFn = vi.fn().mockResolvedValue({
+                data: mockData,
+                cleanup: vi.fn(),
+            });
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onStart).toHaveBeenCalledWith({ isRefetch: false });
+                expect(callbacks.onSuccess).toHaveBeenCalledWith(mockData, {
+                    isRefetch: false,
+                });
+                expect(callbacks.onError).not.toHaveBeenCalled();
+            });
+        });
+        it('should call onError when fetch rejects with an Error', async () => {
+            const callbacks = createMockCallbacks();
+            const error = new Error('Network failure');
+            const mockFetchFn = vi.fn().mockRejectedValue(error);
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onError).toHaveBeenCalledWith(error, {
+                    isRefetch: false,
+                });
+                expect(callbacks.onSuccess).not.toHaveBeenCalled();
+            });
+        });
+        it('should use defaultErrorMessage for non-Error rejections', async () => {
+            const callbacks = createMockCallbacks();
+            const mockFetchFn = vi.fn().mockRejectedValue('string error');
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+                defaultErrorMessage: 'Custom error message',
+            }));
+            await waitFor(() => {
+                expect(callbacks.onError).toHaveBeenCalledTimes(1);
+                const [error] = callbacks.onError.mock.calls[0];
+                expect(error).toBeInstanceOf(Error);
+                expect(error.message).toBe('Custom error message');
+            });
+        });
+        it('should pass signal with isRefetch=false to fetchFn during initial fetch', async () => {
+            const callbacks = createMockCallbacks();
+            let capturedSignal;
+            const mockFetchFn = vi.fn().mockImplementation((signal) => {
+                capturedSignal = signal;
+                return Promise.resolve({ data: 'test' });
+            });
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(capturedSignal).toBeDefined();
+                expect(capturedSignal?.isRefetch).toBe(false);
+                expect(capturedSignal?.cancelled).toBe(false);
+            });
+        });
+    });
+    describe('cleanup', () => {
+        it('should call cleanup function when component unmounts', async () => {
+            const callbacks = createMockCallbacks();
+            const mockCleanup = vi.fn();
+            const mockFetchFn = vi.fn().mockResolvedValue({
+                data: 'test',
+                cleanup: mockCleanup,
+            });
+            const { unmount } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            unmount();
+            expect(mockCleanup).toHaveBeenCalledTimes(1);
+        });
+        it('should call cleanup when deps change and start new fetch', async () => {
+            const callbacks = createMockCallbacks();
+            const mockCleanup1 = vi.fn();
+            const mockCleanup2 = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'first', cleanup: mockCleanup1 })
+                .mockResolvedValueOnce({ data: 'second', cleanup: mockCleanup2 });
+            const { rerender } = renderHook(({ dep }) => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [dep],
+            }), { initialProps: { dep: 'a' } });
+            await waitFor(() => {
+                expect(mockFetchFn).toHaveBeenCalledTimes(1);
+            });
+            rerender({ dep: 'b' });
+            await waitFor(() => {
+                expect(mockFetchFn).toHaveBeenCalledTimes(2);
+                expect(mockCleanup1).toHaveBeenCalledTimes(1);
+            });
+        });
+        it('should not call onFetchSuccess when fetch resolves after cancellation', async () => {
+            const callbacks = createMockCallbacks();
+            let resolveFirst = () => { };
+            const firstFetchPromise = new Promise((resolve) => {
+                resolveFirst = resolve;
+            });
+            const mockFetchFn = vi
+                .fn()
+                .mockImplementationOnce(() => firstFetchPromise)
+                .mockResolvedValueOnce({ data: 'second' });
+            const { rerender } = renderHook(({ dep }) => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [dep],
+            }), { initialProps: { dep: 'a' } });
+            // Change deps before first fetch resolves
+            rerender({ dep: 'b' });
+            // Now resolve the first fetch
+            resolveFirst({ data: 'first', cleanup: vi.fn() });
+            await waitFor(() => {
+                expect(mockFetchFn).toHaveBeenCalledTimes(2);
+            });
+            // onSuccess should have been called with 'second' (from the second fetch), not 'first'
+            // onStart is called twice (once per fetch)
+            expect(callbacks.onStart).toHaveBeenCalledTimes(2);
+            expect(callbacks.onSuccess).toHaveBeenCalledWith('second', {
+                isRefetch: false,
+            });
+            // It should NOT have been called with 'first' (cancelled)
+            expect(callbacks.onSuccess).not.toHaveBeenCalledWith('first', expect.anything());
+        });
+    });
+    describe('refetch', () => {
+        it('should call onStart and onSuccess with isRefetch=true on successful refetch', async () => {
+            const callbacks = createMockCallbacks();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({ data: 'refetched', cleanup: vi.fn() });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            // onStart called twice: once for fetch, once for refetch
+            expect(callbacks.onStart).toHaveBeenCalledTimes(2);
+            expect(callbacks.onStart).toHaveBeenLastCalledWith({ isRefetch: true });
+            expect(callbacks.onSuccess).toHaveBeenCalledWith('refetched', {
+                isRefetch: true,
+            });
+        });
+        it('should call onError with isRefetch=true when refetch fails', async () => {
+            const callbacks = createMockCallbacks();
+            const error = new Error('Refetch failed');
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockRejectedValueOnce(error);
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            expect(callbacks.onError).toHaveBeenCalledWith(error, {
+                isRefetch: true,
+            });
+        });
+        it('should pass signal with isRefetch=true to fetchFn during refetch', async () => {
+            const callbacks = createMockCallbacks();
+            const capturedSignals = [];
+            const mockFetchFn = vi.fn().mockImplementation((signal) => {
+                capturedSignals.push({ ...signal });
+                return Promise.resolve({ data: 'test', cleanup: vi.fn() });
+            });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            expect(capturedSignals).toHaveLength(2);
+            expect(capturedSignals[0].isRefetch).toBe(false); // initial fetch
+            expect(capturedSignals[1].isRefetch).toBe(true); // refetch
+        });
+        it('should cancel in-flight refetch when called again', async () => {
+            const callbacks = createMockCallbacks();
+            const firstRefetchCleanup = vi.fn();
+            const secondRefetchCleanup = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({
+                data: 'first-refetch',
+                cleanup: firstRefetchCleanup,
+            })
+                .mockResolvedValueOnce({
+                data: 'second-refetch',
+                cleanup: secondRefetchCleanup,
+            });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            // Call refetch twice rapidly
+            const first = result.current.refetch();
+            const second = result.current.refetch();
+            await Promise.all([first, second]);
+            // Second refetch should win
+            expect(callbacks.onSuccess).toHaveBeenCalledWith('second-refetch', {
+                isRefetch: true,
+            });
+            // First refetch's cleanup should have been called (cancelled)
+            expect(firstRefetchCleanup).toHaveBeenCalledTimes(1);
+            // Second refetch's cleanup should NOT be called yet
+            expect(secondRefetchCleanup).not.toHaveBeenCalled();
+        });
+        it('should clean up previous refetch subscription when starting new refetch', async () => {
+            const callbacks = createMockCallbacks();
+            const firstRefetchCleanup = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({
+                data: 'first-refetch',
+                cleanup: firstRefetchCleanup,
+            })
+                .mockResolvedValueOnce({
+                data: 'second-refetch',
+                cleanup: vi.fn(),
+            });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            // First refetch completes normally
+            await result.current.refetch();
+            expect(firstRefetchCleanup).not.toHaveBeenCalled();
+            // Second refetch should clean up first refetch's subscription
+            await result.current.refetch();
+            expect(firstRefetchCleanup).toHaveBeenCalledTimes(1);
+        });
+        it('should clean up refetch subscription on unmount', async () => {
+            const callbacks = createMockCallbacks();
+            const refetchCleanup = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({
+                data: 'refetched',
+                cleanup: refetchCleanup,
+            });
+            const { result, unmount } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            expect(refetchCleanup).not.toHaveBeenCalled();
+            unmount();
+            expect(refetchCleanup).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/dist/__tests__/internal/hook-utils.spec.js

@@ -0,0 +1,17 @@
+import { renderHook } from '@testing-library/react';
+import { useStableValue } from "../../internal/hook-utils.js";
+describe('useStableValue', () => {
+    it('should preserve reference for deeply equal objects', () => {
+        const { result, rerender } = renderHook(({ value }) => useStableValue(value), { initialProps: { value: { a: 1, b: [2, 3] } } });
+        const firstRef = result.current;
+        rerender({ value: { a: 1, b: [2, 3] } });
+        expect(result.current).toBe(firstRef);
+    });
+    it('should return a new reference when content changes', () => {
+        const { result, rerender } = renderHook(({ value }) => useStableValue(value), { initialProps: { value: { a: 1 } } });
+        const firstRef = result.current;
+        rerender({ value: { a: 2 } });
+        expect(result.current).not.toBe(firstRef);
+        expect(result.current).toEqual({ a: 2 });
+    });
+});