`@orveth/errors`

Typed errors with stable code strings, optional structured details, and JSON-friendly normalization for logs and HTTP responses. The server runtime maps these errors to outgoing payloads through @orveth/http helpers.

Core concepts

Every OrvethError exposes toNormalized() for a serializable snapshot.
HttpError extends the base class with an explicit numeric statusCode.
isNormalizedError performs a structural type guard when handling unknown objects.

Error classes

Class	When to use	Notable fields
`OrvethError`	Base type for domain failures that should surface in logs or APIs.	`code`, `message`, optional `details`, optional `cause`
`HttpError`	Failures that map directly to HTTP responses.	`statusCode` plus inherited `code` / `message`
`ValidationError`	Input validation problems (stable code `ORVETH_VALIDATION_FAILED`).	Human-readable message plus optional structured details.
`ConfigError`	Configuration parsing or coercion failures.	Thrown by parsers in `@orveth/config`.

`NormalizedError` shape

Field	Purpose
`code`	Stable machine-readable identifier (for example `ORVETH_HTTP_NOT_FOUND`).
`message`	Human-readable explanation safe for logs and many API responses.
`statusCode?`	Present when the error originated as an `HttpError`.
`details?`	Optional JSON-serializable diagnostic payload.
`cause?`	Optional nested normalized error when another `OrvethError` was chained.

Usage patterns

Throwing structured HTTP errors

routes/item.ts

import { HttpError } from "@orveth/errors";

export async function readItem(id: string) {
  if (!id) {
    throw new HttpError(400, "ORVETH_ITEM_ID_REQUIRED", "Item id is required");
  }
  if (id === "missing") {
    throw new HttpError(404, "ORVETH_ITEM_NOT_FOUND", "Item not found", {
      details: { id },
    });
  }
  return { id, name: "Example" };
}

Normalization for logs

logging.ts

import { OrvethError } from "@orveth/errors";

try {
  throw new OrvethError("ORVETH_EXAMPLE", "Something failed", {
    details: { requestId: "abc" },
  });
} catch (error) {
  if (error instanceof OrvethError) {
    console.error(JSON.stringify(error.toNormalized(), null, 2));
  }
}