@tpzdsp/next-toolkit 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "A reusable React component library for Next.js applications",
   "packageManager": "pnpm@11.5.3",
   "engines": {
@@ -122,11 +122,12 @@
     "dev:push": "yalc push",
     "tsc:check": "tsc -b --noEmit",
     "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
     "release": "semantic-release",
     "postinstall": "if [ \"$CI\" != \"true\" ]; then ./postinstall.sh; fi"
   },
   "devDependencies": {
-    "@better-fetch/fetch": "^1.1.21",
+    "@better-fetch/fetch": "^1.3.1",
     "@commitlint/cli": "^21.1.0",
     "@commitlint/config-conventional": "^21.1.0",
     "@commitlint/types": "^21.1.0",

package/src/http/fetch.test.ts

@@ -0,0 +1,100 @@
+import z from 'zod/v4';
+
+import { apiFetch } from './fetch';
+import { ApiError, ApiErrorSchema } from '../errors';
+
+const UserSchema = z.object({ id: z.number(), name: z.string() });
+
+const USERS_URL = 'https://api.test/users/1';
+const CREATE_USER_URL = 'https://api.test/create-user';
+const INVALID_NAME_ERROR = { message: 'Invalid name', details: 'name is required' };
+
+const stubFetchResponse = (status: number, body: unknown) => {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(
+      async () =>
+        new Response(JSON.stringify(body), {
+          status,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+    ),
+  );
+};
+
+describe('apiFetch', () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // `ApiError` logs to `console.error` on construction - not relevant to what these tests assert on.
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+    vi.unstubAllGlobals();
+  });
+
+  it('returns a `{ data, error }` tuple on success by default', async () => {
+    stubFetchResponse(200, { id: 1, name: 'Alice' });
+
+    const result = await apiFetch<{ id: number; name: string }>(USERS_URL, {
+      errorSchema: ApiErrorSchema,
+      output: UserSchema,
+    });
+
+    expect(result).toEqual({ data: { id: 1, name: 'Alice' }, error: null });
+  });
+
+  it('resolves directly with the data when `throw: true`', async () => {
+    stubFetchResponse(200, { id: 1, name: 'Alice' });
+
+    const data = await apiFetch<{ id: number; name: string }>(USERS_URL, {
+      errorSchema: ApiErrorSchema,
+      output: UserSchema,
+      throw: true,
+    });
+
+    expect(data).toEqual({ id: 1, name: 'Alice' });
+  });
+
+  it('returns the raw, unparsed error in the tuple when the request fails and `throw` is not set', async () => {
+    stubFetchResponse(404, { message: 'Not Found' });
+
+    const result = await apiFetch('https://api.test/users/999', { errorSchema: ApiErrorSchema });
+
+    expect(result.data).toBeNull();
+    expect(result.error).toMatchObject({ message: 'Not Found', status: 404 });
+  });
+
+  it('throws a normalized `ApiError` when the request fails and `throw: true`', async () => {
+    stubFetchResponse(400, INVALID_NAME_ERROR);
+
+    await expect(
+      apiFetch(CREATE_USER_URL, { errorSchema: ApiErrorSchema, throw: true }),
+    ).rejects.toThrow(ApiError);
+
+    stubFetchResponse(400, INVALID_NAME_ERROR);
+
+    const error = await apiFetch<never>(CREATE_USER_URL, {
+      errorSchema: ApiErrorSchema,
+      throw: true,
+    }).catch((caught: unknown) => caught as ApiError);
+
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error.message).toBe(INVALID_NAME_ERROR.message);
+    expect(error.details).toBe(INVALID_NAME_ERROR.details);
+    expect(error.status).toBe(400);
+  });
+
+  it('normalizes a network-level failure into an `ApiError`, regardless of `throw`', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        throw new TypeError('fetch failed');
+      }),
+    );
+
+    await expect(apiFetch(USERS_URL, { errorSchema: ApiErrorSchema })).rejects.toThrow(ApiError);
+  });
+});

package/src/http/fetch.ts

@@ -4,12 +4,14 @@ import z from 'zod/v4';
 import {
   createSchema as betterFetchCreateSchema,
   createFetch as betterFetchCreateFetch,
+  betterFetch,
   type CreateFetchOption as BetterFetchCreateFetchOption,
   type Schema,
   type FetchSchema,
   ValidationError,
   BetterFetchError,
   type BetterFetch,
+  type BetterFetchResponse,
   type StandardSchemaV1,
   type BetterFetchPlugin,
 } from '@better-fetch/fetch';
@@ -263,3 +265,41 @@ export const createFetch = <
     }
   }) as typeof instance;
 };
+
+/**
+ * Performs a single, one-off `better-fetch` request without needing a fetch schema or a
+ * `createFetch` instance - useful for requests that don't belong to any particular API/schema.
+ *
+ * Applies the same defaults as {@link createFetch} (basic auth from environment variables, the
+ * toolkit plugin) and normalizes any thrown error into an {@link ApiError}.
+ *
+ * As with plain `better-fetch`, pass `throw: true` in `options` to have a failed request throw
+ * (normalized to an {@link ApiError}) instead of resolving to a `{ data, error }` tuple - the
+ * `error` side of that tuple is whatever the server responded with, unparsed, same as plain
+ * `better-fetch` (only the *thrown* error path is normalized/validated against `errorSchema`).
+ */
+type ApiFetch = {
+  // `throw: true` - resolves directly with the data, or throws a normalized `ApiError`.
+  <TRes = unknown, Option extends CreateFetchOption = CreateFetchOption>(
+    url: string,
+    options: Option & { throw: true },
+  ): Promise<TRes>;
+
+  // Default (`throw` unset/`false`) - resolves with a `{ data, error }` tuple.
+  <TRes = unknown, Option extends CreateFetchOption = CreateFetchOption>(
+    url: string,
+    options: Option,
+  ): Promise<BetterFetchResponse<TRes, unknown, false>>;
+};
+
+export const apiFetch: ApiFetch = async (url: string, options: CreateFetchOption) => {
+  try {
+    return await betterFetch(url, {
+      auth: getAuth(),
+      ...options,
+      plugins: [...(options.plugins ?? []), TOOLKIT_PLUGIN],
+    });
+  } catch (error) {
+    throw await normalizeError(error, options);
+  }
+};

package/src/http/query.test.tsx

@@ -0,0 +1,366 @@
+import type { ReactNode } from 'react';
+import { Suspense } from 'react';
+
+import { ErrorBoundary } from 'react-error-boundary';
+import z from 'zod/v4';
+
+import { type BetterFetch, type CreateFetchOption } from '@better-fetch/fetch';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+import { HttpMethod } from './constants';
+import { createSchema } from './fetch';
+import { reactQueryBetterFetch } from './query';
+import { ApiError } from '../errors';
+import { render, renderHook, screen, userEvent, waitFor } from '../test/renderers';
+
+const Route = {
+  USERS: '/users',
+  USER_BY_ID: '/users/:id',
+  RAW_USERS: '/raw-users',
+  CREATE_USER: '/create-user',
+} as const;
+
+const UserSchema = z.object({ id: z.number(), name: z.string() });
+const CreateUserInputSchema = z.object({ name: z.string() });
+
+// A schema with a mix of routes to exercise every branch of the hook overloads:
+// - a route with a schema-defined `output` (`RoutesWithOutput`)
+// - a route with a schema-defined `output` AND a `params` schema (`RoutesWithInput`)
+// - a route with no `output` at all (`RoutesWithoutOutput`, requires a manual generic)
+// - a route with a schema-defined `input` (`RoutesWithInput`, used for mutations)
+const testSchema = createSchema({
+  [Route.USERS]: {
+    method: HttpMethod.Get,
+    output: z.array(UserSchema),
+  },
+  [Route.USER_BY_ID]: {
+    method: HttpMethod.Get,
+    output: UserSchema,
+    params: z.object({ id: z.string() }),
+  },
+  [Route.RAW_USERS]: {
+    method: HttpMethod.Get,
+  },
+  [Route.CREATE_USER]: {
+    method: HttpMethod.Post,
+    input: CreateUserInputSchema,
+    output: UserSchema,
+  },
+});
+
+type TestOption = CreateFetchOption & { schema: typeof testSchema };
+
+// `reactQueryBetterFetch` only cares about `instance` as a callable matching `BetterFetch<Option>` -
+// the actual fetching is entirely mocked here, so we don't need a real network layer to test the
+// hooks' schema-driven typing, query/mutation key building, and React Query wiring.
+const createTestInstance = () => {
+  const fetchMock = vi.fn();
+  const instance = fetchMock as unknown as BetterFetch<TestOption>;
+
+  return { fetchMock, instance };
+};
+
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+
+const createQueryWrapper = (client: QueryClient) => {
+  const Wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={client}>{children}</QueryClientProvider>
+  );
+
+  return Wrapper;
+};
+
+// Renders the fetched user's name - shared between the suspense tests below, which only differ in
+// how the fetch mock resolves/rejects and what's wrapped around this component.
+const createUserNameComponent = (
+  useBetterSuspenseQuery: ReturnType<
+    typeof reactQueryBetterFetch<TestOption>
+  >['useBetterSuspenseQuery'],
+) => {
+  const UserName = () => {
+    const { data } = useBetterSuspenseQuery(Route.USER_BY_ID, { params: { id: '1' } });
+
+    return <p>{data.name}</p>;
+  };
+
+  return UserName;
+};
+
+describe('reactQueryBetterFetch', () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // `ApiError` logs to `console.error` on construction, and React logs errors caught by an
+    // `ErrorBoundary` - neither is relevant to what these tests assert on.
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('builds a strict, schema-validated route map for the test fixture', () => {
+    expect(Object.keys(testSchema.schema)).toEqual(Object.values(Route));
+    expect(testSchema.config).toEqual({ strict: true });
+  });
+
+  describe('useBetterQuerySafe', () => {
+    it('fetches data for a route with a schema-defined output', async () => {
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockResolvedValue([{ id: 1, name: 'Alice' }]);
+
+      const { useBetterQuerySafe } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result } = renderHook(() => useBetterQuerySafe(Route.USERS), {
+        wrapper: createQueryWrapper(queryClient),
+      });
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+      expect(result.current.data).toEqual([{ id: 1, name: 'Alice' }]);
+      expect(fetchMock).toHaveBeenCalledWith(Route.USERS, undefined);
+    });
+
+    it('supports a manually specified output type for routes without a schema output', async () => {
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockResolvedValue([{ id: 9, extra: true }]);
+
+      const { useBetterQuerySafe } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result } = renderHook(
+        () => useBetterQuerySafe<{ id: number; extra: boolean }[]>(Route.RAW_USERS),
+        { wrapper: createQueryWrapper(queryClient) },
+      );
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+      expect(result.current.data).toEqual([{ id: 9, extra: true }]);
+    });
+
+    it('builds the query key from the route and fetch options, refetching when they change', async () => {
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockImplementation(async (_route: string, options: { params: { id: string } }) => ({
+        id: Number(options.params.id),
+        name: `User ${options.params.id}`,
+      }));
+
+      const { useBetterQuerySafe } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result, rerender } = renderHook(
+        ({ id }: { id: string }) => useBetterQuerySafe(Route.USER_BY_ID, { params: { id } }),
+        { wrapper: createQueryWrapper(queryClient), initialProps: { id: '1' } },
+      );
+
+      await waitFor(() => expect(result.current.data).toEqual({ id: 1, name: 'User 1' }));
+
+      rerender({ id: '2' });
+
+      await waitFor(() => expect(result.current.data).toEqual({ id: 2, name: 'User 2' }));
+
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('applies a `select` transform, exposing the transformed shape as `data`', async () => {
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockResolvedValue({ id: 1, name: 'Alice' });
+
+      const { useBetterQuerySafe } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result } = renderHook(
+        () =>
+          useBetterQuerySafe(
+            Route.USER_BY_ID,
+            { params: { id: '1' } },
+            { select: (user) => user.name },
+          ),
+        { wrapper: createQueryWrapper(queryClient) },
+      );
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+      expect(result.current.data).toBe('Alice');
+    });
+
+    it('returns the error instead of throwing when the request fails', async () => {
+      const apiError = ApiError.notFound('user not found');
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockRejectedValue(apiError);
+
+      const { useBetterQuerySafe } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result } = renderHook(
+        () => useBetterQuerySafe(Route.USER_BY_ID, { params: { id: '1' } }),
+        { wrapper: createQueryWrapper(queryClient) },
+      );
+
+      await waitFor(() => expect(result.current.isError).toBe(true));
+
+      expect(result.current.error).toBe(apiError);
+    });
+  });
+
+  describe('useBetterSuspenseQuery', () => {
+    it('suspends while loading and resolves with the schema-derived data', async () => {
+      const { fetchMock, instance } = createTestInstance();
+
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      let resolveFetch: (value: unknown) => void = () => {};
+
+      fetchMock.mockReturnValue(
+        new Promise((resolve) => {
+          resolveFetch = resolve;
+        }),
+      );
+
+      const { useBetterSuspenseQuery } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+      const UserName = createUserNameComponent(useBetterSuspenseQuery);
+
+      render(
+        <QueryClientProvider client={queryClient}>
+          <Suspense fallback={<p>loading...</p>}>
+            <UserName />
+          </Suspense>
+        </QueryClientProvider>,
+      );
+
+      expect(screen.getByText('loading...')).toBeInTheDocument();
+
+      resolveFetch({ id: 1, name: 'Alice' });
+
+      expect(await screen.findByText('Alice')).toBeInTheDocument();
+    });
+
+    it('throws to the nearest error boundary when the request fails', async () => {
+      const apiError = ApiError.internalServerError('boom');
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockRejectedValue(apiError);
+
+      const { useBetterSuspenseQuery } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+      const onError = vi.fn();
+      const UserName = createUserNameComponent(useBetterSuspenseQuery);
+
+      render(
+        <QueryClientProvider client={queryClient}>
+          <ErrorBoundary fallback={<p>failed</p>} onError={onError}>
+            <Suspense fallback={<p>loading...</p>}>
+              <UserName />
+            </Suspense>
+          </ErrorBoundary>
+        </QueryClientProvider>,
+      );
+
+      expect(await screen.findByText('failed')).toBeInTheDocument();
+      expect(onError).toHaveBeenCalledWith(apiError, expect.anything());
+    });
+
+    it('supports a manually specified output type for routes without a schema output', async () => {
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockResolvedValue({ id: 9, extra: true });
+
+      const { useBetterSuspenseQuery } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result } = renderHook(
+        () => useBetterSuspenseQuery<{ id: number; extra: boolean }>(Route.RAW_USERS),
+        { wrapper: createQueryWrapper(queryClient) },
+      );
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+      expect(result.current.data).toEqual({ id: 9, extra: true });
+    });
+  });
+
+  describe('useBetterMutation', () => {
+    it('sends the merged fetch and mutation input and returns the schema output', async () => {
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockResolvedValue({ id: 5, name: 'Bob' });
+
+      const { useBetterMutation } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result } = renderHook(() => useBetterMutation(Route.CREATE_USER), {
+        wrapper: createQueryWrapper(queryClient),
+      });
+
+      const data = await result.current.mutateAsync({ body: { name: 'Bob' } });
+
+      expect(data).toEqual({ id: 5, name: 'Bob' });
+      expect(fetchMock).toHaveBeenCalledWith(Route.CREATE_USER, { body: { name: 'Bob' } });
+    });
+
+    it('throws the error during render so the nearest error boundary catches it', async () => {
+      const user = userEvent.setup();
+      const apiError = ApiError.badRequest('invalid name');
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockRejectedValue(apiError);
+
+      const { useBetterMutation } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+      const onError = vi.fn();
+
+      const CreateUserButton = () => {
+        const { mutate } = useBetterMutation(Route.CREATE_USER);
+
+        return <button onClick={() => mutate({ body: { name: '' } })}>create</button>;
+      };
+
+      render(
+        <QueryClientProvider client={queryClient}>
+          <ErrorBoundary fallback={<p>failed</p>} onError={onError}>
+            <CreateUserButton />
+          </ErrorBoundary>
+        </QueryClientProvider>,
+      );
+
+      await user.click(screen.getByRole('button', { name: 'create' }));
+
+      expect(await screen.findByText('failed')).toBeInTheDocument();
+      expect(onError).toHaveBeenCalledWith(apiError, expect.anything());
+    });
+  });
+
+  describe('useBetterMutationSafe', () => {
+    it('does not throw on error, exposing it via the mutation result instead', async () => {
+      const apiError = ApiError.badRequest('invalid name');
+      const { fetchMock, instance } = createTestInstance();
+
+      fetchMock.mockRejectedValue(apiError);
+
+      const { useBetterMutationSafe } = reactQueryBetterFetch<TestOption>(instance);
+      const queryClient = createTestQueryClient();
+
+      const { result } = renderHook(() => useBetterMutationSafe(Route.CREATE_USER), {
+        wrapper: createQueryWrapper(queryClient),
+      });
+
+      result.current.mutate({ body: { name: '' } });
+
+      await waitFor(() => expect(result.current.isError).toBe(true));
+
+      expect(result.current.error).toBe(apiError);
+    });
+  });
+});

package/src/http/query.ts

@@ -130,30 +130,32 @@ type ReactQueryBetterFetch = <
   useBetterQuerySafe<
     Error = ApiError,
     Route extends RoutesWithOutput<Routes> = RoutesWithOutput<Routes>,
+    Output = SchemaRouteOutput<Routes, Route>,
+    // The type actually returned as `data`. Defaults to `Output` (i.e. `select` is the identity
+    // function), but can be inferred as something else when a transforming `select` is passed.
+    Data = Output,
   >(
     route: Route,
     // If the route requires an input, then expect options that provide that input, otherwise just expect options without inputs.
     fetchOptions?: Route extends RoutesWithInput<Routes>
       ? OptionsWithInput<Routes, Route>
       : OptionsNoInputOutput,
-    queryOptions?: Omit<
-      UseQueryOptions<unknown, Error, SchemaRouteOutput<Routes, Route>, QueryKey>,
-      OmitReactQueryKeys
-    >,
-  ): UseQueryResult<SchemaRouteOutput<Routes, Route>, Error>;
+    queryOptions?: Omit<UseQueryOptions<Output, Error, Data, QueryKey>, OmitReactQueryKeys>,
+  ): UseQueryResult<Data, Error>;
 
   // Overload that allows manual output type instead of schema (`RoutesWithoutOutput`)
   useBetterQuerySafe<
     Output,
     Error = ApiError,
     Route extends RoutesWithoutOutput<Routes> = RoutesWithoutOutput<Routes>,
+    Data = Output,
   >(
     route: Route,
     fetchOptions?: Route extends RoutesWithInput<Routes>
       ? OptionsWithInput<Routes, Route>
       : OptionsNoInputOutput,
-    queryOptions?: Omit<UseQueryOptions<unknown, Error, Output, QueryKey>, OmitReactQueryKeys>,
-  ): UseQueryResult<Output, Error>;
+    queryOptions?: Omit<UseQueryOptions<Output, Error, Data, QueryKey>, OmitReactQueryKeys>,
+  ): UseQueryResult<Data, Error>;
 
   // Suspense query (error thrown)
 
@@ -161,31 +163,27 @@ type ReactQueryBetterFetch = <
   useBetterSuspenseQuery<
     Route extends RoutesWithOutput<Routes>,
     Output = SchemaRouteOutput<Routes, Route>,
+    Data = Output,
   >(
     route: Route,
     fetchOptions?: Route extends RoutesWithInput<Routes>
       ? OptionsWithInput<Routes, Route>
       : OptionsNoInputOutput,
-    queryOptions?: Omit<
-      UseSuspenseQueryOptions<unknown, never, Output, QueryKey>,
-      OmitReactQueryKeys
-    >,
-  ): UseSuspenseQueryResult<Output>;
+    queryOptions?: Omit<UseSuspenseQueryOptions<Output, never, Data, QueryKey>, OmitReactQueryKeys>,
+  ): UseSuspenseQueryResult<Data>;
 
   // Overload that allows manual output type instead of schema (`RoutesWithoutOutput`)
   useBetterSuspenseQuery<
     Output,
     Route extends RoutesWithoutOutput<Routes> = RoutesWithoutOutput<Routes>,
+    Data = Output,
   >(
     route: Route,
     fetchOptions?: Route extends RoutesWithInput<Routes>
       ? OptionsWithInput<Routes, Route>
       : OptionsNoInputOutput,
-    queryOptions?: Omit<
-      UseSuspenseQueryOptions<unknown, never, Output, QueryKey>,
-      OmitReactQueryKeys
-    >,
-  ): UseSuspenseQueryResult<Output>;
+    queryOptions?: Omit<UseSuspenseQueryOptions<Output, never, Data, QueryKey>, OmitReactQueryKeys>,
+  ): UseSuspenseQueryResult<Data>;
 
   // Mutation query (error thrown)