@cogs/fetch-error-handler

Cross-runtime fetch guard that turns ambiguous upstream failures into structured @cogs/errors. Ship the same handler to Node.js (Next.js / workers) and browsers, drain unread response bodies, and remove bespoke boilerplate wherever you call fetch.

Features

• One API, two runtimes – conditional exports surface the Node implementation by default (create-handler.node.ts) and the browser implementation to bundlers via the browser field. Both share the same logic, differing only in how response bodies are drained.
• Structured error mapping – HTTP 4xx/5xx, DNS lookup issues, socket hangups, aborted or timed-out requests, and invalid JSON payloads are promoted to HttpError, OperationalError, or UpstreamServiceError with normalized codes and relatesToSystems.
• Response body insight without leaks – the handler clones responses, truncates large payloads (2 KB cap), and records raw text/JSON in the thrown error. The original Response body is drained via environment hooks so Node streams and browser readers do not linger.
• Promise-aware wrapper – accept either a Response or a Promise<Response>; any rejection is re-thrown as a richer error and successful responses must pass .ok / .status checks before returning.
• Tiny surface area – createFetchErrorHandler(options?) returns a handleFetchErrors(responseOrPromise) helper. A ready-to-use singleton (handleFetchErrors) is exported for quick integration.

Installation

pnpm add @cogs/fetch-error-handler

Usage

JavaScript

import { handleFetchErrors } from "@cogs/fetch-error-handler"

export async function loadFeatureFlags() {
  const response = await handleFetchErrors(
    fetch("https://example.internal/api/flags", { method: "GET" }),
  )

  return response.json()
}

TypeScript (custom handler per upstream)

import { createFetchErrorHandler } from "@cogs/fetch-error-handler"

const handleUpstreamErrors = createFetchErrorHandler({
  upstreamSystemCode: "UPSTREAM_API",
})

export async function callUpstream<T>(input: RequestInfo, init?: RequestInit): Promise<T> {
  const response = await handleUpstreamErrors(fetch(input, init))
  return response.json() as Promise<T>
}

Wiring into other clients

Wrap the underlying fetch Promise from any XHR-like abstraction:

import { handleFetchErrors } from "@cogs/fetch-error-handler"

const safeFetch = (input: RequestInfo, init?: RequestInit) =>
  handleFetchErrors(fetch(input, init))

// inside a client
const response = await safeFetch(url, {
  method: "POST",
  body: JSON.stringify(payload),
})

Options

• upstreamSystemCode?: string – when provided, the resulting errors will include relatesToSystems: [upstreamSystemCode], helping log aggregation and alerting pipelines bucket failures.

Error Mapping Summary

• HTTP 4xx → HttpError with code: "FETCH_CLIENT_ERROR" (status coerced to 500 for consistent downstream handling).
• HTTP 5xx → UpstreamServiceError with code: "FETCH_SERVER_ERROR".
• Unexpected status (non-304, non-ok) → HttpError code: "FETCH_UNKNOWN_ERROR".
• Invalid JSON in OK response → UpstreamServiceError code: "FETCH_INVALID_JSON_ERROR".
• DNS / ENOTFOUND → OperationalError code: "FETCH_DNS_LOOKUP_ERROR".
• Abort / timeout → OperationalError code: "FETCH_ABORT_ERROR" or FETCH_TIMEOUT_ERROR.
• Socket hangup / ECONNRESET → UpstreamServiceError code: "FETCH_SOCKET_HANGUP_ERROR".
• Any other thrown Error passes through untouched so higher layers can decide whether to crash or recover.

Scripts

• pnpm build – compile ESM output and declarations via tsc.
• pnpm typecheck – type-check without emitting.
• pnpm lint – run Biome.
• pnpm test – run the Vitest suite (unit + end-to-end fixtures).