Error

import { KoyoError } from "koyojs/Error";

throw new KoyoError("Config file could not be read", {
  code: "CONFIG_UNREADABLE",
  module: "Config",
  details: { path: "/etc/app.toml" },
});

// Branch on the code, not the message text
try {
  loadConfig();
} catch (err) {
  if (err instanceof KoyoError && err.code === "CONFIG_UNREADABLE") {
    useDefaults();
  } else {
    throw err;
  }
}

// Structured logging — details stay a separate field
try {
  loadConfig();
} catch (err) {
  if (err instanceof KoyoError) {
    logger.error(err.toJSON());
    // { name, code, module, message, details }
  }
}

// Wrapping a lower-level failure without losing it
try {
  await db.connect();
} catch (cause) {
  throw new KoyoError("Database unavailable", {
    code: "DB_DOWN",
    module: "Storage",
    cause,
  });
}

import { KoyoTypeError } from "koyojs/Error";

function parsePort(value: unknown): number {
  if (typeof value !== "number") {
    throw new KoyoTypeError("port must be a number", {
      code: "BAD_PORT",
      details: { received: typeof value },
    });
  }
  return value;
}

import { KoyoRangeError } from "koyojs/Error";

function setVolume(level: number) {
  if (level < 0 || level > 100) {
    throw new KoyoRangeError("volume must be between 0 and 100", {
      code: "VOLUME_OUT_OF_RANGE",
      details: { level },
    });
  }
}

import { KoyoStateError } from "koyojs/Error";
import { useState, onCleanup } from "koyojs/State";

// Thrown by the library when the rules of hooks are broken
useState(0);      // outside component() → KoyoStateError
onCleanup(() => {});  // outside a reactive scope → KoyoStateError

// Also thrown when an effect writes a signal it reads,
// after 1000 flush passes: "Maximum update depth exceeded"

try {
  renderApp();
} catch (err) {
  if (err instanceof KoyoStateError) {
    console.error("Reactive bug:", err.toJSON());
  }
}

import { KoyoDOMError } from "koyojs/Error";
import { $ } from "koyojs/DOM";

// Running $ where there is no document (SSR, worker) throws
try {
  $(".card").addClass("active");
} catch (err) {
  if (err instanceof KoyoDOMError) {
    // Skip DOM work on the server rather than crashing the render
    return;
  }
  throw err;
}

import { createError, isKoyoError } from "koyojs/Error";

const PaymentError = createError("PaymentError", {
  code: "PAYMENT",
  module: "Billing",
});

throw new PaymentError("Card declined", {
  details: { last4: "4242" },
});
// name: "PaymentError", code: "PAYMENT", module: "Billing"

// Per-throw options win over the baked-in defaults
throw new PaymentError("Gateway timed out", { code: "PAYMENT_TIMEOUT" });
// code: "PAYMENT_TIMEOUT"

// Still part of the hierarchy
try {
  charge();
} catch (err) {
  isKoyoError(err);            // true
  err instanceof PaymentError; // true
}

// One class per failure domain keeps catch blocks readable
const AuthError  = createError("AuthError",  { code: "AUTH",  module: "Auth" });
const QuotaError = createError("QuotaError", { code: "QUOTA", module: "Limits" });

import { isKoyoError } from "koyojs/Error";

try {
  await doWork();
} catch (err) {
  if (isKoyoError(err)) {
    // Narrowed — code, module, details, toJSON() all available
    logger.error({ code: err.code, module: err.module, ...err.details });
  } else {
    logger.error({ message: String(err) });
  }
}

// Correct across realms, where instanceof is not
const iframeError = getErrorFromIframe();
iframeError instanceof KoyoError;  // false — different realm, different class
isKoyoError(iframeError);          // true

// Same story with two copies of koyojs in one dependency tree
isKoyoError(errorFromNestedCopy);  // true

import { assert, KoyoRangeError, KoyoTypeError } from "koyojs/Error";

function head<T>(items: T[]): T {
  assert(items.length > 0, "items must not be empty", {
    error: KoyoRangeError,
  });
  return items[0];  // no non-null assertion needed
}

// Narrowing removes the need for a manual type guard
function greet(name: string | null) {
  assert(name !== null, "name is required", { error: KoyoTypeError });
  return name.toUpperCase();  // name is string here
}

// Carries the same structured context as a hand-thrown error
assert(user.role === "admin", "admin required", {
  code: "FORBIDDEN",
  module: "Auth",
  details: { role: user.role },
});