error-codes

(no submodules)

Purpose

error-codes exports the canonical stable error-code registry used by every other module in @suaveplan/test-vite. The registry is built with @suaveplan/error's defineCodes so each code value becomes a namespaced string of the form TEST_VITE.<REASON>. This namespace survives module boundaries, structured cloning, RPC boundaries, and JSON serialisation, so callers can discriminate on error.code rather than relying on prototype chains. The companion TestViteError class extends SuaveplanError<TestViteCode> so static analysis narrows err.code to the literal union of registered codes.

Features

8-code namespaced registry: INVALID_OPTIONS, MISSING_ENTRY, TREE_SHAKE_VIOLATION, SIZE_BUDGET_EXCEEDED, SNAPSHOT_MISSING, PORT_EXHAUSTED, PORT_NOT_HELD, HMR_TIMEOUT.
TestViteError class extending SuaveplanError<TestViteCode> with a public constructor.
Structured details payload propagated as the SuaveplanError context field.
Cause-chain support via the standard Error.cause constructor option.
No marketing language — each code names a concrete, reachable failure mode.

Usage: Basic

import { TEST_VITE_CODES, TestViteError } from "@suaveplan/test-vite/error-codes";

try {
  doSomething();
} catch (err) {
  if (err instanceof TestViteError && err.code === TEST_VITE_CODES.INVALID_OPTIONS) {
    console.error("bad options", err.details);
  }
}

Usage: Advanced

Discriminate on the namespaced code value directly so the handler survives RPC and serialisation:

import { TEST_VITE_CODES } from "@suaveplan/test-vite/error-codes";

function isTestViteError(err: unknown): err is { code: string; details: Record<string, unknown> } {
  return typeof err === "object" && err !== null && typeof (err as { code?: unknown }).code === "string";
}

function classify(err: unknown): "retry" | "abort" {
  if (!isTestViteError(err)) return "abort";
  switch (err.code) {
    case TEST_VITE_CODES.PORT_EXHAUSTED:
    case TEST_VITE_CODES.HMR_TIMEOUT:
      return "retry";
    default:
      return "abort";
  }
}

API Reference

TEST_VITE_CODES — Readonly<Record<string, TestViteCode>> built via defineCodes("TEST_VITE", [...]).
TestViteCode — string literal union of every registered code.
TestViteError extends SuaveplanError<TestViteCode> — new TestViteError(code, message, { cause?, details? }). Exposes code: TestViteCode, message: string, details: Record<string, unknown>, and inherits timestamp, name, cause from SuaveplanError / Error.

Implementation Notes

The constructor passes the details payload to SuaveplanError as context so the OTel span-event adapter picks it up automatically. We mirror the payload on a public details field for ergonomic access from non-TypeScript consumers. cause is forwarded only when supplied so the standard Error.prototype.cause behaviour stays clean.

3.0 KiB Raw Blame History