Error Handling

Error normalization to ResultError and customizable rules

ResultError

The library normalizes unknown values to a ResultError with:

• code: stable identifier
• message: error description
• status?: optional numeric status
• meta?: additional payload
• cause?: original value

Default normalizer

If no custom rules are provided, tryo automatically applies the following rules:

• abort: Detects AbortError and returns code: "ABORTED".
• timeout: Detects TimeoutError and returns code: "TIMEOUT".
• httpStatus: Detects errors with numeric status or statusCode. Returns code: "HTTP" and preserves the status.
• aggregate: Handles AggregateError by saving internal errors in meta.errors.
• string: If a string is thrown, it is used as the message.
• message: Extracts the message property from objects.

Example using default rules:

import tryo from "tryo";

const runner = tryo(); // Uses default rules

const result = await runner.run(async () => {
  throw new DOMException("Time out", "TimeoutError");
});

if (!result.ok && result.error.code === "TIMEOUT") {
  console.log("Request timed out");
}

Custom rules

Use errorRule to define specific mappings and tryo to apply them.

import tryo, { errorRule } from "tryo";

class HttpError extends Error {
  constructor(
    public status: number,
    public url: string,
    public body?: unknown
  ) {
    super("HTTP error");
  }
}

const runner = tryo({
  rules: [
    errorRule.instance(HttpError).toError((e) => ({
      code: "HTTP",
      message: `Request failed (${e.status})`,
      status: e.status,
      meta: { url: e.url, body: e.body },
      cause: e,
    })),
  ],
});

Transformation with mapError

Allows adjusting the already normalized error to enrich or standardize it.

const r = await run(() => fetch("/api"), {
  mapError: (e) => ({ ...e, message: `[api] ${e.message}` }),
});

Cancellation and Timeout

• signal and timeout affect how long we wait for the task to complete.
• If your function does not consume the provided AbortSignal, the library cannot cancel underlying I/O automatically.
• We race the task and return ABORTED/TIMEOUT promptly, but the inner request only stops if it cooperates with signal.

const controller = new AbortController();
const r = await run(() => fetch("/api"), { signal: controller.signal, timeout: 2000 });

Circuit Breaker (Runner-level)

• Circuit breaker is configured at the Runner level: tryo({ circuitBreaker }).
• Per-call circuit breaker is intentionally not exposed in RunOptions to keep the API lean.