Tipificación de respuestas de API

Q: ¿Cuál es el beneficio de un wrapper fetch genérico como fetchJson?

Centraliza el manejo de errores (verificar response.ok, capturar errores de red). Cada sitio de llamada especifica la forma de respuesta esperada mediante el parámetro de tipo. Reduce el código repetitivo de fetch en componentes.

Q: ¿Cómo proporciona Zod seguridad de tipo tanto en tiempo de compilación como de ejecución?

z.infer deriva el tipo de TypeScript del esquema. schema.parse(json) lanza un ZodError si los datos no coinciden en tiempo de ejecución.

Q: Trampa: ¿Proporciona la conversión as T alguna protección en tiempo de ejecución?

No. as T es una aseveración solo en tiempo de compilación con cero seguridad en tiempo de ejecución. Si la API cambia su formato de respuesta, tu código fallará silenciosamente hasta que un acceso a propiedad falle. Para límites críticos de API, usa Zod o una guarda de tipo personalizada en su lugar.

Q: ¿Por qué fetch no lanza errores en respuestas 4xx o 5xx?

fetch solo rechaza en fallos de red (errores de DNS, sin conexión). Los códigos de estado de error HTTP (400, 404, 500) se consideran solicitudes de red exitosas. Debes verificar response.ok o response.status manualmente.

Q: ¿Cómo tipificas una unión discriminada para resultados de API (éxito versus error)?

El campo success actúa como el discriminante. TypeScript reduce el acceso a data y error en función de la comprobación de success.

Q: Trampa: ¿Qué sucede si olvidas manejar los estados de carga y error?

Acceder a .data en un estado null causa un error en tiempo de ejecución. Siempre modela tres estados: carga, error y éxito. Usa una unión discriminada o variables de estado separadas para cada uno.

Q: ¿Cuál es la ventaja de usar unknown en lugar de any para datos sin validar?

unknown te obliga a reducir o validar antes de acceder a propiedades. any permite silenciosamente todo acceso a propiedades sin comprobaciones. Usa const data: unknown = await response.json() como punto de partida para validación.

Receta

Tipifica tus respuestas de API de extremo a extremo, desde llamadas fetch hasta la renderización de componentes. Usa guardas de tipo y validación en tiempo de ejecución para cerrar la brecha entre datos de red sin tipificar y tus tipos de TypeScript.

Ejemplo de funcionamiento

// Define tus tipos de API
type ApiUser = {
  id: number;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
};
 
type ApiResponse<T> = {
  data: T;
  meta: {
    page: number;
    totalPages: number;
    totalCount: number;
  };
};
 
// Wrapper fetch type-safe
async function fetchJson<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  return response.json() as Promise<T>;
}
 
// Uso en un componente
function UserList() {
  const [result, setResult] = useState<ApiResponse<ApiUser[]> | null>(null);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    fetchJson<ApiResponse<ApiUser[]>>("/api/users")
      .then(setResult)
      .catch((err) => setError(err.message));
  }, []);
 
  if (error) return <p>Error: {error}</p>;
  if (!result) return <p>Loading...</p>;
 
  return (
    <ul>
      {result.data.map((user) => (
        <li key={user.id}>{user.name} ({user.role})</li>
      ))}
    </ul>
  );
}

Análisis profundo

Cómo funciona

fetch devuelve Response, y response.json() devuelve Promise<any>. La conversión as Promise<T> le dice a TypeScript qué forma esperar, pero no valida los datos en tiempo de ejecución.
Un wrapper fetch genérico (fetchJson<T>) centraliza el manejo de errores y la tipificación. Cada sitio de llamada especifica la forma de respuesta esperada.
Para una verdadera seguridad en tiempo de ejecución, empareja tus tipos con una biblioteca de validación como Zod. Esto asegura que la API devolvió realmente la forma que esperas.
Separa tus tipos de API (lo que envía el servidor) de tus tipos de dominio (lo que usa tu aplicación). Mapéalos entre sí en una capa de servicio.

Variaciones

Validación de Zod en tiempo de ejecución:

import { z } from "zod";
 
const ApiUserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(["admin", "editor", "viewer"]),
});
 
type ApiUser = z.infer<typeof ApiUserSchema>;
 
const ApiResponseSchema = <T extends z.ZodType>(dataSchema: T) =>
  z.object({
    data: dataSchema,
    meta: z.object({
      page: z.number(),
      totalPages: z.number(),
      totalCount: z.number(),
    }),
  });
 
async function fetchValidated<T>(url: string, schema: z.ZodType<T>): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const json = await response.json();
  return schema.parse(json); // Lanza ZodError si la validación falla
}
 
// Uso
const result = await fetchValidated(
  "/api/users",
  ApiResponseSchema(z.array(ApiUserSchema))
);

Guarda de tipo personalizada:

function isApiUser(value: unknown): value is ApiUser {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value &&
    "email" in value &&
    "role" in value &&
    typeof (value as ApiUser).id === "number" &&
    typeof (value as ApiUser).name === "string"
  );
}
 
// Uso
const data: unknown = await response.json();
if (isApiUser(data)) {
  console.log(data.name); // TypeScript sabe que data es ApiUser
}

Tipificación de respuesta de error:

type ApiError = {
  message: string;
  code: string;
  details?: Record<string, string[]>;
};
 
type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };
 
async function fetchApi<T>(url: string): Promise<ApiResult<T>> {
  try {
    const response = await fetch(url);
    const json = await response.json();
    if (!response.ok) {
      return { success: false, error: json as ApiError };
    }
    return { success: true, data: json as T };
  } catch {
    return { success: false, error: { message: "Network error", code: "NETWORK" } };
  }
}

Notas de TypeScript

response.json() devuelve Promise<any>. La conversión as Promise<T> es un compromiso necesario ya que el análisis de JSON es inherentemente sin tipificar.
z.infer<typeof Schema> deriva el tipo de TypeScript de un esquema de Zod, dándote una única fuente de verdad.
Usa unknown en lugar de any para datos sin validar. Te obliga a reducir o validar antes de acceder a propiedades.

Trampas

La conversión con as T proporciona cero seguridad en tiempo de ejecución. Si la API cambia su formato de respuesta, tu código fallará silenciosamente hasta que un acceso a propiedad falle.
fetch no lanza errores en respuestas 4xx o 5xx. Debes verificar response.ok o response.status manualmente.
Los tipos de API pueden no coincidir con tus tipos de dominio frontend (por ejemplo, las fechas vienen como strings, no objetos Date). Transfórmalos en una capa de mapeo.
Olvidar manejar los estados de carga y error conduce a acceder a .data en null, causando errores en tiempo de ejecución.

Alternativas

Enfoque	Pros	Contras
Conversión `as T`	Simple, cero dependencias	Sin validación en tiempo de ejecución
Validación de Zod	Seguridad en tiempo de compilación y ejecución, única fuente de verdad	Dependencia agregada, costo de análisis
Guardas de tipo (funciones `is`)	Sin dependencias, reducción explícita	Tedioso para tipos complejos, fácil de errar
tRPC	Seguridad de tipo de extremo a extremo, sin tipificación manual	Requiere configuración de servidor y cliente
GraphQL codegen	Tipos generados a partir del esquema	Paso de compilación, ecosistema de GraphQL requerido

Preguntas frecuentes

¿Por qué response.json() devuelve Promise y qué debes hacer al respecto?

El análisis de JSON es inherentemente sin tipificar - TypeScript no puede saber qué forma tendrán los datos.
Usa as Promise<T> para convertir, o valida con schema.parse(json) de Zod para seguridad en tiempo de ejecución.
La conversión proporciona cero seguridad en tiempo de ejecución - la API podría devolver cualquier cosa.

¿Cuál es el beneficio de un wrapper fetch genérico como `fetchJson<T>`?

Centraliza el manejo de errores (verificar response.ok, capturar errores de red).
Cada sitio de llamada especifica la forma de respuesta esperada mediante el parámetro de tipo.
Reduce el código repetitivo de fetch en componentes.

¿Cómo proporciona Zod seguridad de tipo tanto en tiempo de compilación como de ejecución?

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});
type User = z.infer<typeof UserSchema>; // tipo derivado
 
const data = UserSchema.parse(json); // validación en tiempo de ejecución

z.infer<typeof Schema> deriva el tipo de TypeScript del esquema.
schema.parse(json) lanza un ZodError si los datos no coinciden en tiempo de ejecución.

Trampa: ¿Proporciona la conversión `as T` alguna protección en tiempo de ejecución?

No. as T es una aseveración solo en tiempo de compilación con cero seguridad en tiempo de ejecución.
Si la API cambia su formato de respuesta, tu código fallará silenciosamente hasta que un acceso a propiedad falle.
Para límites críticos de API, usa Zod o una guarda de tipo personalizada en su lugar.

¿Por qué fetch no lanza errores en respuestas 4xx o 5xx?

fetch solo rechaza en fallos de red (errores de DNS, sin conexión).
Los códigos de estado de error HTTP (400, 404, 500) se consideran solicitudes de red exitosas.
Debes verificar response.ok o response.status manualmente.

¿Cuándo debes usar una guarda de tipo personalizada versus validación de Zod?

Las guardas de tipo personalizado no tienen dependencias pero son tediosas y propensas a errores para tipos complejos.
Zod proporciona una única fuente de verdad (esquema = tipo + validación) pero agrega una dependencia.
Usa Zod para límites de API; usa guardas de tipo para comprobaciones simples y únicas.

¿Por qué deberían los tipos de API separarse de los tipos de dominio?

Las APIs pueden enviar fechas como strings, usar snake_case, o incluir campos que tu aplicación no necesita.
Una capa de mapeo convierte tipos de API a tipos de dominio (por ejemplo, analizando strings de fecha a objetos Date).
Esto desvincula tu frontend de cambios de esquema de backend.

¿Cómo tipificas una unión discriminada para resultados de API (éxito versus error)?

type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };

El campo success actúa como el discriminante.
TypeScript reduce el acceso a data y error en función de la comprobación de success.

Trampa: ¿Qué sucede si olvidas manejar los estados de carga y error?

Acceder a .data en un estado null causa un error en tiempo de ejecución.
Siempre modela tres estados: carga, error y éxito.
Usa una unión discriminada o variables de estado separadas para cada uno.

¿Cuál es la ventaja de usar `unknown` en lugar de `any` para datos sin validar?

unknown te obliga a reducir o validar antes de acceder a propiedades.
any permite silenciosamente todo acceso a propiedades sin comprobaciones.
Usa const data: unknown = await response.json() como punto de partida para validación.

// Define tus tipos de API
type ApiUser = {
  id: number;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
};
 
type ApiResponse<T> = {
  data: T;
  meta: {
    page: number;
    totalPages: number;
    totalCount: number;
  };
};
 
// Wrapper fetch type-safe
async function fetchJson<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  return response.json() as Promise<T>;
}
 
// Uso en un componente
function UserList() {
  const [result, setResult] = useState<ApiResponse<ApiUser[]> | null>(null);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    fetchJson<ApiResponse<ApiUser[]>>("/api/users")
      .then(setResult)
      .catch((err) => setError(err.message));
  }, []);
 
  if (error) return <p>Error: {error}</p>;
  if (!result) return <p>Loading...</p>;
 
  return (
    <ul>
      {result.data.map((user) => (
        <li key={user.id}>{user.name} ({user.role})</li>
      ))}
    </ul>
  );
}

Análisis profundo

Cómo funciona

fetch devuelve Response, y response.json() devuelve Promise<any>. La conversión as Promise<T> le dice a TypeScript qué forma esperar, pero no valida los datos en tiempo de ejecución.
Un wrapper fetch genérico (fetchJson<T>) centraliza el manejo de errores y la tipificación. Cada sitio de llamada especifica la forma de respuesta esperada.
Para una verdadera seguridad en tiempo de ejecución, empareja tus tipos con una biblioteca de validación como Zod. Esto asegura que la API devolvió realmente la forma que esperas.
Separa tus tipos de API (lo que envía el servidor) de tus tipos de dominio (lo que usa tu aplicación). Mapéalos entre sí en una capa de servicio.

Variaciones

Validación de Zod en tiempo de ejecución:

import { z } from "zod";
 
const ApiUserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(["admin", "editor", "viewer"]),
});
 
type ApiUser = z.infer<typeof ApiUserSchema>;
 
const ApiResponseSchema = <T extends z.ZodType>(dataSchema: T) =>
  z.object({
    data: dataSchema,
    meta: z.object({
      page: z.number(),
      totalPages: z.number(),
      totalCount: z.number(),
    }),
  });
 
async function fetchValidated<T>(url: string, schema: z.ZodType<T>): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const json = await response.json();
  return schema.parse(json); // Lanza ZodError si la validación falla
}
 
// Uso
const result = await fetchValidated(
  "/api/users",
  ApiResponseSchema(z.array(ApiUserSchema))
);

Guarda de tipo personalizada:

function isApiUser(value: unknown): value is ApiUser {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value &&
    "email" in value &&
    "role" in value &&
    typeof (value as ApiUser).id === "number" &&
    typeof (value as ApiUser).name === "string"
  );
}
 
// Uso
const data: unknown = await response.json();
if (isApiUser(data)) {
  console.log(data.name); // TypeScript sabe que data es ApiUser
}

Tipificación de respuesta de error:

type ApiError = {
  message: string;
  code: string;
  details?: Record<string, string[]>;
};
 
type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };
 
async function fetchApi<T>(url: string): Promise<ApiResult<T>> {
  try {
    const response = await fetch(url);
    const json = await response.json();
    if (!response.ok) {
      return { success: false, error: json as ApiError };
    }
    return { success: true, data: json as T };
  } catch {
    return { success: false, error: { message: "Network error", code: "NETWORK" } };
  }
}

Notas de TypeScript

response.json() devuelve Promise<any>. La conversión as Promise<T> es un compromiso necesario ya que el análisis de JSON es inherentemente sin tipificar.
z.infer<typeof Schema> deriva el tipo de TypeScript de un esquema de Zod, dándote una única fuente de verdad.
Usa unknown en lugar de any para datos sin validar. Te obliga a reducir o validar antes de acceder a propiedades.

Trampas

La conversión con as T proporciona cero seguridad en tiempo de ejecución. Si la API cambia su formato de respuesta, tu código fallará silenciosamente hasta que un acceso a propiedad falle.
fetch no lanza errores en respuestas 4xx o 5xx. Debes verificar response.ok o response.status manualmente.
Los tipos de API pueden no coincidir con tus tipos de dominio frontend (por ejemplo, las fechas vienen como strings, no objetos Date). Transfórmalos en una capa de mapeo.
Olvidar manejar los estados de carga y error conduce a acceder a .data en null, causando errores en tiempo de ejecución.

Alternativas

Enfoque	Pros	Contras
Conversión `as T`	Simple, cero dependencias	Sin validación en tiempo de ejecución
Validación de Zod	Seguridad en tiempo de compilación y ejecución, única fuente de verdad	Dependencia agregada, costo de análisis
Guardas de tipo (funciones `is`)	Sin dependencias, reducción explícita	Tedioso para tipos complejos, fácil de errar
tRPC	Seguridad de tipo de extremo a extremo, sin tipificación manual	Requiere configuración de servidor y cliente
GraphQL codegen	Tipos generados a partir del esquema	Paso de compilación, ecosistema de GraphQL requerido

Preguntas frecuentes

¿Por qué response.json() devuelve Promise y qué debes hacer al respecto?

El análisis de JSON es inherentemente sin tipificar - TypeScript no puede saber qué forma tendrán los datos.
Usa as Promise<T> para convertir, o valida con schema.parse(json) de Zod para seguridad en tiempo de ejecución.
La conversión proporciona cero seguridad en tiempo de ejecución - la API podría devolver cualquier cosa.

¿Cuál es el beneficio de un wrapper fetch genérico como `fetchJson<T>`?

Centraliza el manejo de errores (verificar response.ok, capturar errores de red).
Cada sitio de llamada especifica la forma de respuesta esperada mediante el parámetro de tipo.
Reduce el código repetitivo de fetch en componentes.

¿Cómo proporciona Zod seguridad de tipo tanto en tiempo de compilación como de ejecución?

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});
type User = z.infer<typeof UserSchema>; // tipo derivado
 
const data = UserSchema.parse(json); // validación en tiempo de ejecución

z.infer<typeof Schema> deriva el tipo de TypeScript del esquema.
schema.parse(json) lanza un ZodError si los datos no coinciden en tiempo de ejecución.

Trampa: ¿Proporciona la conversión `as T` alguna protección en tiempo de ejecución?

No. as T es una aseveración solo en tiempo de compilación con cero seguridad en tiempo de ejecución.
Si la API cambia su formato de respuesta, tu código fallará silenciosamente hasta que un acceso a propiedad falle.
Para límites críticos de API, usa Zod o una guarda de tipo personalizada en su lugar.

¿Por qué fetch no lanza errores en respuestas 4xx o 5xx?

fetch solo rechaza en fallos de red (errores de DNS, sin conexión).
Los códigos de estado de error HTTP (400, 404, 500) se consideran solicitudes de red exitosas.
Debes verificar response.ok o response.status manualmente.

¿Cuándo debes usar una guarda de tipo personalizada versus validación de Zod?

Las guardas de tipo personalizado no tienen dependencias pero son tediosas y propensas a errores para tipos complejos.
Zod proporciona una única fuente de verdad (esquema = tipo + validación) pero agrega una dependencia.
Usa Zod para límites de API; usa guardas de tipo para comprobaciones simples y únicas.

¿Por qué deberían los tipos de API separarse de los tipos de dominio?

Las APIs pueden enviar fechas como strings, usar snake_case, o incluir campos que tu aplicación no necesita.
Una capa de mapeo convierte tipos de API a tipos de dominio (por ejemplo, analizando strings de fecha a objetos Date).
Esto desvincula tu frontend de cambios de esquema de backend.

¿Cómo tipificas una unión discriminada para resultados de API (éxito versus error)?

type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };

El campo success actúa como el discriminante.
TypeScript reduce el acceso a data y error en función de la comprobación de success.

Trampa: ¿Qué sucede si olvidas manejar los estados de carga y error?

Acceder a .data en un estado null causa un error en tiempo de ejecución.
Siempre modela tres estados: carga, error y éxito.
Usa una unión discriminada o variables de estado separadas para cada uno.

¿Cuál es la ventaja de usar `unknown` en lugar de `any` para datos sin validar?

unknown te obliga a reducir o validar antes de acceder a propiedades.
any permite silenciosamente todo acceso a propiedades sin comprobaciones.
Usa const data: unknown = await response.json() como punto de partida para validación.

Tipificación de respuestas de API

Receta

Ejemplo de funcionamiento

Análisis profundo

Cómo funciona

Variaciones

Notas de TypeScript

Trampas

Alternativas

Preguntas frecuentes

Relacionado

Tipificación de respuestas de API

Receta

Ejemplo de funcionamiento

Análisis profundo

Cómo funciona

Variaciones

Notas de TypeScript

Trampas

Alternativas

Preguntas frecuentes

Relacionado

Tipificación de respuestas de API

Buscar en la documentación

Tipificación de respuestas de API