API Reference

Complete reference for every function, type, and option exported by StatusForge.

normalizeError

Core function

Accepts any value — an Error instance, an HTTP response, a plain object, or even a string — and returns a NormalizedError. Adapters are tried in order; the first whose canHandle returns true produces the output.

Signature

function normalizeError(
  input: unknown,
  options?: NormalizeErrorOptions
): NormalizedError

Parameters

inputunknownrequired

The value to normalize. Can be an Error, a Response, a plain object, a string, or anything else.

optionsNormalizeErrorOptionsoptional

Configuration object. Currently supports a single field: adapters.

Options

NormalizeErrorOptions

interface NormalizeErrorOptions {
  adapters?: ErrorAdapter[];
}

adaptersErrorAdapter[]optional

Custom list of adapters to use instead of the defaults. Order matters — adapters are tried left to right until one handles the input. If omitted, the default chain is used: axios, ky, fetch, apollo, node-http, generic.

NormalizedError

Return type

The object returned by normalizeError. Always contains all five fields, never undefined.

Type definition

interface NormalizedError {
  code: string;
  message: string;
  status: number | null;
  retryable: boolean;
  details: Record<string, unknown> | null;
}

Field	Type	Description
code	string	Uppercase identifier such as HTTP_503, ECONNRESET, or UNKNOWN_ERROR. Suitable for switch statements and error tracking.
message	string	Human-readable explanation extracted from the error source. Safe to render in UI.
status	number \| null	HTTP status in the 100-599 range when available. null for transport errors and non-HTTP failures.
retryable	boolean	true when the error is transient (e.g. 429, 503, ECONNRESET). Inferred from status codes, error codes, and message patterns.
details	Record<string, unknown> \| null	Original error payload minus redundant fields. Preserved for logging, Sentry, or debugging.

ErrorAdapter

Interface

The contract every adapter must satisfy. Implement this interface to add support for custom error shapes.

Type definition

interface ErrorAdapter {
  name: string;
  canHandle(input: unknown): boolean;
  normalize(input: unknown): Partial<NormalizedError>;
}

namestring

Identifier for the adapter. Used for debugging and logging.

canHandle(input: unknown) => boolean

Returns true if this adapter knows how to normalize the given input. Should be fast — avoid async operations or heavy computation.

normalize(input: unknown) => Partial<NormalizedError>

Extracts fields from the input. Return a partial — StatusForge fills in defaults for any missing fields.

Custom adapters

Pass a custom adapter array via options to handle domain-specific error shapes. Your adapters run first; include genericAdapter at the end as a fallback.

Example: Stripe error adapter

import {
  normalizeError,
  axiosAdapter,
  genericAdapter,
  type ErrorAdapter
} from "@npmforge/statusforge";

const stripeAdapter: ErrorAdapter = {
  name: "stripe",
  canHandle(input) {
    return (
      typeof input === "object" &&
      input !== null &&
      "type" in input &&
      (input as Record<string, unknown>).type === "StripeCardError"
    );
  },
  normalize(input) {
    const err = input as {
      type: string;
      code?: string;
      message?: string;
      decline_code?: string;
    };
    return {
      code: err.code ?? err.type,
      message: err.message ?? "Payment failed",
      status: 402,
      retryable: err.decline_code === "insufficient_funds",
      details: { decline_code: err.decline_code }
    };
  }
};

const normalized = normalizeError(error, {
  adapters: [stripeAdapter, axiosAdapter, genericAdapter]
});

Adapter order matters

Adapters are tried left to right. Place more specific adapters before generic ones. If no adapter matches and genericAdapter is not in the list, the fallback returns code UNKNOWN_ERROR.

Retryable inference

The retryable field is automatically derived from status codes, error codes, and message patterns. No configuration needed.

Category	Values
HTTP status codes	408, 425, 429, 500, 502, 503, 504
Network error codes	ECONNRESET, ECONNABORTED, ETIMEDOUT, EAI_AGAIN, ENOTFOUND, ECONNREFUSED, EHOSTUNREACH, EPIPE, UND_ERR_*
Message patterns	"timeout", "network error", "fetch failed", "temporar"
Non-retryable override	Messages containing "abort"

Exported adapters

All six built-in adapters are exported individually so you can compose custom chains. See the Adapters reference for detection rules and output examples.

axiosAdapterkyAdapterfetchAdapterapolloAdapternodeHttpAdaptergenericAdapter