Type a generic fetch hook that returns a known payload

A fetch hook is only useful if the value it returns is trustworthy. This one is generic over the payload type and requires the caller to bring a type predicate, so the hook can state in its signature that success data has passed a runtime check rather than a cast.

// src/use-fetch.ts
import { useEffect, useState } from "react";

export type FetchState<TPayload> =
  | { readonly status: "idle" }
  | { readonly status: "loading" }
  | { readonly status: "success"; readonly data: TPayload }
  | { readonly status: "error"; readonly error: Error };

export type UseFetchResult<TPayload> = {
  readonly state: FetchState<TPayload>;
  readonly reload: () => void;
};

export function useFetch<TPayload>(
  url: string,
  narrowResponse: (value: unknown) => value is TPayload,
): UseFetchResult<TPayload> {
  const [state, setState] = useState<FetchState<TPayload>>({ status: "idle" });
  const [revision, setRevision] = useState(0);

  useEffect(() => {
    const controller = new AbortController();
    setState({ status: "loading" });

    void (async (): Promise<void> => {
      try {
        const response = await fetch(url, { signal: controller.signal });

        if (!response.ok) {
          throw new Error(`Request failed with status ${response.status}`);
        }

        const payload: unknown = await response.json();

        if (!narrowResponse(payload)) {
          throw new Error("Response body did not match the expected shape");
        }

        setState({ status: "success", data: payload });
      } catch (error) {
        if (controller.signal.aborted) {
          return;
        }

        setState({
          status: "error",
          error: error instanceof Error ? error : new Error(String(error)),
        });
      }
    })();

    return () => {
      controller.abort();
    };
  }, [url, narrowResponse, revision]);

  return {
    state,
    reload: () => setRevision((current) => current + 1),
  };
}

The consuming component never writes a type assertion. It picks a payload type, hands over the matching predicate, and reads state.data only in the branch the discriminated union leaves available.

// src/release-banner.tsx
import { useFetch } from "./use-fetch";

const releasesUrl = "https://api.example.com/releases";

function isVersionList(value: unknown): value is readonly string[] {
  return Array.isArray(value) && value.every((entry: unknown) => typeof entry === "string");
}

export function ReleaseBanner() {
  const { state, reload } = useFetch(releasesUrl, isVersionList);

  if (state.status === "idle" || state.status === "loading") {
    return <p>Loading release notes…</p>;
  }

  if (state.status === "error") {
    return (
      <p>
        {state.error.message}
        <button type="button" onClick={reload}>
          Try again
        </button>
      </p>
    );
  }

  return (
    <ul>
      {state.data.map((version) => (
        <li key={version}>{version}</li>
      ))}
    </ul>
  );
}

Explanation

The hook keeps the payload type as a parameter rather than hard-coding a response shape, and FetchState is a discriminated union: every variant carries a literal status, so a check on that property is enough for the compiler to decide which other properties exist. useState is annotated with the same union, which means a later setState call cannot mix variants — { status: "success" } without data is rejected at compile time. The generic then flows back out through UseFetchResult, so a component that asks for readonly string[] gets state.data typed as readonly string[] and cannot accidentally treat it as something else.

The interesting part is where that type comes from. response.json() is declared to return a promise of an unchecked value, so assigning it to a TPayload variable would be a guess. This hook instead takes (value: unknown) => value is TPayload and calls it before building the success variant. The predicate is what makes the assignment honest: inside the type system a type predicate is the one construct that says “a runtime check happened here”, and because the parsed body is a const in the same block, the compiler narrows it after the guard, so the data property receives a value already known to be TPayload. TypeScript erases generics when it emits JavaScript, so nothing about the type parameter survives into the bundle; if you delete the predicate argument and cast the body instead, the code still compiles and only the runtime data tells you whether the shape was real.

Two boundary conditions are worth testing against your own endpoints. First, the effect lists narrowResponse in its dependencies, which is correct because the effect calls it — pass a module-level function or a useCallback result, otherwise identity changes each render, the effect re-runs, and the request repeats. Second, the response.ok check runs before the body is parsed, so a 500 with a JSON error object surfaces as an HTTP failure rather than as a narrowing failure; only a 2xx response reaches the predicate. Aborted requests are swallowed by the controller.signal.aborted guard in the catch block, which is what stops a cancelled navigation from being reported as an error to the reader.