vf-error-handling

Veryfront Error Handling

Overview

Veryfront uses a centralized error registry with slug-based identification. All errors extend VeryfrontError and are created via defineError().

Core principle: Never throw raw Error. Use the registry. Never identify errors by class name. Use slugs.

Error Registry Pattern

Defining New Errors

// In src/errors/error-registry.ts
import { defineError } from "./types.ts";

export const MY_NEW_ERROR = defineError({
  slug: "my-new-error",           // kebab-case, unique
  category: "RUNTIME",            // CONFIG | BUILD | RUNTIME | ROUTE | MODULE | SERVER | BOUNDARY | DEV | DEPLOY | AGENT | GENERAL
  status: 500,                    // default HTTP status
  title: "Something went wrong",  // human-readable
  suggestion: "Try doing X instead", // actionable fix
});

Throwing Errors

import { MY_NEW_ERROR } from "#veryfront/errors";

throw MY_NEW_ERROR.create({
  detail: "Specific description of what happened",
  context: { key: "value", relevantData: data },
  cause: originalError,  // optional: chain the original error
});

Catching Errors

import { VeryfrontError } from "#veryfront/errors";

try {
  riskyOperation();
} catch (error) {
  if (error instanceof VeryfrontError && error.slug === "my-new-error") {
    // Handle specific error
    console.log(error.context.relevantData);
  }
  throw error; // Re-throw unknown errors
}

Migrating Class-Based Errors to Registry

When replacing class FooError extends Error:

Step 1: Define in Registry

// src/errors/error-registry.ts
export const FOO_ERROR = defineError({
  slug: "foo-error",
  category: "RUNTIME",
  status: 500,
  title: "Foo operation failed",
  suggestion: "Check the foo configuration",
});

Step 2: Update Usage Sites

// Before
throw new FooError("something failed", { details: data });

// After
throw FOO_ERROR.create({
  detail: "something failed",
  context: { details: data },
});