[Feature]: Error handling system

[nehu3n]

Summary

Add a type-safe error handling system using a builder pattern for defining custom errors, with support for error handlers at multiple specificity levels.

Motivation

Currently Kito doesn't have a structured way to handle errors. Developers need a clean, type-safe approach to:

• Define custom errors with specific status codes and context data
• Handle errors at different levels (specific error, by code, catch-all)
• Get full TypeScript inference when throwing and handling errors
• Access error context in handlers

This is essential for building production apps where proper error handling and logging are critical.

Proposed Solution

Defining errors

Use a builder pattern to create type-safe error definitions:

import { error } from "kitojs";

const UserNotFound = error("USER_NOT_FOUND")
  .status(404)
  .message("User not found")
  .data<{ userId: string }>()
  .build();

const ValidationError = error("VALIDATION_ERROR")
  .status(400)
  .message((data: { fields: string[] }) => `Validation failed: ${data.fields.join(", ")}`)
  .data()
  .build();

Throwing errors

app.get("/users/:id", ({ req, res }) => {
  const user = db.find(req.params.id);
  
  if (!user) {
    throw UserNotFound({ userId: req.params.id });
  }
  
  res.json(user);
});

Handling errors

Support multiple handler levels:

// Specific error handler
app.onError(UserNotFound, async ({ error, res }) => {
  await logger.warn(`User ${error.data.userId} not found`);
  res.status(error.status).json({ error: error.code });
});

// By error code
app.onError("VALIDATION_ERROR", ({ error, res }) => {
  res.status(400).json({ fields: error.data.fields });
});

// Multiple specific errors
app.onError([UserNotFound, OtherError], ({ error, res }) => {});

Observing errors

For logging, metrics, or other side-effects that should always run regardless of handling:

app.observeError(({ error, ctx }) => {});

Fallback for unhandled errors

Executes only if no other handler consumed the error:

app.onUnhandledError(({ error, res }) => {
  res.status(500).json({ error: "internal_error" });
});

Built-in errors

Export common framework errors:

import { KitoErrors } from "kitojs";

throw KitoErrors.RouteNotFound();
throw KitoErrors.MethodNotAllowed({ allowed: ["GET", "POST"] });
throw KitoErrors.PayloadTooLarge({ limit: "10mb" });

Future considerations

• Error recovery/retry logic
• Error transformation chains
• Error context propagation

Checklist

• I've searched for related issues
• I've read the documentation

[mindplay-dk]

This looks very cool! Almost like the catch (ErrorType e) we can't have in JS... interesting! I think I like it.

app.onError("*", ({ error, res }) => {
  res.status(500).json({ error: "internal_error" });
});

The catch-all is useful for things like logging, right? And this would trigger regardless of a specific error-handler also handling the error?

Can we have a fallback error-handler as well? For handling errors that weren't handled by an error-handler? This could be very useful - like the final catch clause in languages where you have multiple, type-hinted error-handlers.

[nehu3n]

Hi @mindplay-dk !

Thanks for the feedback, glad you like the idea 🙂

I agree that using "*" introduces an implicit convention, which can be confusing. A cleaner approach would be to remove it entirely and keep app.onError() strictly for handling specific errors:

app.onError(UserNotFound, ({ error, res }) => {});
app.onError("USER_NOT_FOUND", ({ error, res }) => {});
app.onError([UserNotFound, OtherError], ({ error, res }) => {});

For use cases that should always run — such as logging, metrics, or tracing — we could introduce a separate observer API:

app.observeError(({ error, ctx }) => {});

This would always run, regardless of whether the error is eventually handled or not, and would not affect control flow.

Regarding your question about a fallback handler for unhandled errors: I completely agree, this is very useful and maps nicely to the “final catch” concept from languages with multiple, type-aware catch clauses.

One possible API could be:

app.onUnhandledError(({ error, res }) => {
  res.status(500).json({ error: "internal_error" });
});

This keeps the semantics explicit and avoids ambiguity around execution order or propagation.

Thanks again for the suggestions!

[mindplay-dk]

Separate methods, yes, good call! Always better to have methods with clear names, rather than trying to make one method do it all. This should be a relief - error handling is one of the all time worst features in express. 😄