Type-Safe Practices for Using Fetch API in TypeScript

Introduction

In modern web development, Fetch API has become the standard approach for making HTTP requests. However, in TypeScript environments, many developers face challenges with type conversion when using fetch. This article aims to provide a comprehensive exploration of correctly using Fetch API in TypeScript, ensuring type safety and code quality.

Problem Analysis

Many developers encounter difficulties when attempting to convert fetch responses to custom types. The common approach of using intermediate any variables for forced type conversion violates TypeScript's type safety principles. For example:

fetch(`http://swapi.co/api/people/1/`)
  .then(res => res.json())
  .then(res => {
    let a:any = res; 
    let b:Actor = <Actor>a;
  })

While this approach compiles successfully, it loses the advantages of TypeScript's type checking.

Type-Safe Fetch Implementation

To achieve type-safe fetch calls, we can create a generic function to encapsulate fetch operations:

function api<T>(url: string): Promise<T> {
  return fetch(url)
    .then(response => {
      if (!response.ok) {
        throw new Error(response.statusText)
      }
      return response.json() as Promise<T>
    })
}

This implementation ensures the returned Promise has the correct generic type while including basic error handling.

Data Transformation and Unwrapping

In practical applications, API responses often contain wrapped data structures. We can extend the generic function to handle this scenario:

function api<T>(url: string): Promise<T> {
  return fetch(url)
    .then(response => {
      if (!response.ok) {
        throw new Error(response.statusText)
      }
      return response.json() as Promise<{ data: T }>
    })
    .then(data => {
      return data.data
    })
}

This implementation automatically unwraps data, allowing consumers to directly access the required data structure.

Error Handling Strategy

While errors can be handled directly within the fetch wrapper function, a better approach is to let errors bubble up to the caller:

function api<T>(url: string): Promise<T> {
  return fetch(url)
    .then(response => {
      if (!response.ok) {
        throw new Error(response.statusText)
      }
      return response.json() as Promise<{ data: T }>
    })
    .then(data => {
      return data.data
    })
    .catch((error: Error) => {
      externalErrorLogging.error(error)
      throw error
    })
}

This design allows callers to handle errors according to specific business requirements while maintaining logging functionality.

Practical Application Example

Let's demonstrate a complete type-safe implementation through a concrete Pokemon API example:

type PokemonData = {
  id: string
  number: string
  name: string
  image: string
  fetchedAt: string
  attacks: {
    special: Array<{
      name: string
      type: string
      damage: number
    }>
  }
}

async function fetchPokemon(name: string): Promise<PokemonData> {
  const response = await fetch('https://graphql-pokemon2.vercel.app/', {
    method: 'POST',
    headers: {
      'content-type': 'application/json;charset=UTF-8',
    },
    body: JSON.stringify({
      query: `query { pokemon(name: "${name}") { id number name image attacks { special { name type damage } } } }`
    }),
  })

  type JSONResponse = {
    data?: {
      pokemon: Omit<PokemonData, 'fetchedAt'>
    }
    errors?: Array<{ message: string }>
  }

  const { data, errors }: JSONResponse = await response.json()

  if (response.ok) {
    const pokemon = data?.pokemon
    if (pokemon) {
      return Object.assign(pokemon, { fetchedAt: new Date().toISOString() })
    } else {
      throw new Error(`No pokemon with the name "${name}"`)
    }
  } else {
    const errorMessage = errors?.map(e => e.message).join('\n') ?? 'unknown'
    throw new Error(errorMessage)
  }
}

Importance of Type Annotations

When using fetch in TypeScript, proper use of type annotations is crucial. The response.json() method returns Promise<any> by default, meaning TypeScript cannot infer the structure of response data. Through explicit type annotations, we can provide necessary information to the compiler:

const response = await fetch(url)
const data: MyType = await response.json()

Or using type assertions:

const data = await response.json() as MyType

Limitations of Promise Rejection Values

It's important to note that TypeScript's Promise generic only supports type definitions for resolved values, not rejected values. This means we cannot write:

// This is not allowed
function api<T, E>(url: string): Promise<T, E> { ... }

This is because in JavaScript, errors can originate from various unpredictable sources, and TypeScript cannot guarantee the specific type of errors.

Best Practices Summary

1. Always use generic functions to encapsulate fetch calls, ensuring type safety

2. Avoid using any type for forced conversions

3. Add type annotations and type assertions at appropriate locations

4. Implement complete error handling mechanisms

5. Define detailed interface types for complex API responses

6. Use Object.assign or other safe methods for object property extension

Conclusion

By correctly using TypeScript's type system and Fetch API, we can build type-safe, maintainable network request code. The methods introduced in this article not only solve basic type conversion problems but also provide complete solutions for handling complex scenarios. Following these best practices, developers can fully leverage TypeScript's static type checking advantages to build more reliable web applications.