typedFetch

Wrapper type-safe sobre a API fetch nativa que retorna erros como valores em vez de lancar excecoes.

Assinatura

function typedFetch<
  JsonReturnType,
  ErrorType extends ClientErrors = ClientErrors,
>(
  url: Parameters<typeof fetch>[0],
  options?: Parameters<typeof fetch>[1] & {
    headers?: TypedHeaders;
    method?: HttpMethods;
  },
): Promise<
  | { response: TypedResponse<JsonReturnType>; error: null }
  | { response: null; error: ErrorType | ServerErrors | NetworkError }
>

Parametros de Tipo

Parametro	Descricao
JsonReturnType	Tipo esperado do corpo da resposta em caso de sucesso
ErrorType	Tipos de erro de cliente especificos esperados (padrao: todos os 4xx). Erros de servidor (5xx) e NetworkError sao sempre incluidos.

Parametros

Parametro	Tipo	Descricao
url	string | URL | Request	A URL do recurso, igual ao fetch()
options	RequestInit	Opcoes da requisicao com headers e method tipados (opcional, padrao {})

Tipo de Retorno

Uma discriminated union — verifique error para restringir:

const { response, error } = await typedFetch<User>('/api/users/1');

if (error) {
  // response e null, error e ErrorType | ServerErrors | NetworkError
} else {
  // error e null, response e TypedResponse<User>
  const user = await response.json(); // Type: User
}

Compatibilidade com a API Fetch

typedFetch tem a mesma API do fetch nativo:

• Todas as opcoes do fetch funcionam: method, headers, body, credentials, cache, etc.
• Suporte completo ao AbortController via signal
• Timeout de requisicao usando AbortSignal.timeout()
• Mesmos tipos de parametros do fetch nativo
• Substituicao direta para chamadas fetch existentes

isHttpError

function isHttpError(error: unknown): error is BaseHttpError

Type guard que verifica se um valor e um erro HTTP (qualquer subclasse de BaseHttpError). Prefira isso ao instanceof quando o erro pode cruzar limites de pacotes.

import { isHttpError } from '@pbpeterson/typed-fetch';

if (isHttpError(error)) {
  console.log(error.status, error.statusText, error.name);
}

isNetworkError

function isNetworkError(error: unknown): error is NetworkError

Type guard que verifica se um valor e um NetworkError.

import { isNetworkError } from '@pbpeterson/typed-fetch';

if (isNetworkError(error)) {
  console.log('Connection failed:', error.message);
}

statusCodeErrorMap

const statusCodeErrorMap: Map<number, HttpErrors>

Mapeia codigos de status HTTP (400-511) para seus construtores de classes de erro correspondentes.

import { statusCodeErrorMap } from '@pbpeterson/typed-fetch';

const ErrorClass = statusCodeErrorMap.get(404); // NotFoundError

httpErrors

const httpErrors: readonly [BadGatewayError, BadRequestError, ...]

Array com todos os 40 construtores de classes de erro HTTP. Util para iteracao e registros personalizados.

import { httpErrors } from '@pbpeterson/typed-fetch';

for (const ErrorClass of httpErrors) {
  console.log(`${ErrorClass.status}: ${ErrorClass.statusText}`);
}

Exemplos

Cancelamento de Requisicao

const controller = new AbortController();

const { response, error } = await typedFetch<User[]>('/api/users', {
  signal: controller.signal,
});

controller.abort();

Timeout de Requisicao

const { response, error } = await typedFetch<User[]>('/api/users', {
  signal: AbortSignal.timeout(5000),
});

POST com Typed Headers

const { response, error } = await typedFetch<User>('/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token',
  },
  body: JSON.stringify(userData),
  credentials: 'include',
});