@x-titan/koa-error-handler

🧩 A minimal, composable error handler middleware for Koa, designed for pure REST APIs.

It provides a small, flexible structure for handling errors — without hiding logic from developers.
You control how errors are prepared and formatted, while the middleware handles the basic flow.

✨ Features

• ⚙️ Minimal: no dependencies beyond Koa
• 🧽 Flexible: developer controls how errors are formatted
• 🔒 Safe: prevents double responses
• 🤓 Developer-friendly with optional debug logging
• 🌐 REST-only (JSON output)

📦 Installation

npm install @x-titan/koa-error-handler

🚀 Usage

import Koa from "koa"
import createHttpError, { type HttpError } from "http-errors"
import error, { ErrorEvent } from "@x-titan/koa-error-handler"

const app = new Koa()

app.use(error({
  prepare(error) {
    // Normalize to HttpError
    return createHttpError(
      error.status || 500,
      error.message || "Internal Server Error"
    )
  },

  onerror(event: ErrorEvent<HttpError>) {
    const err = event.error as HttpError

    // Format final JSON response
    event.body = {
      success: false,
      message: err.expose ? err.message : "Internal Server Error",
      status: err.status,
      timestamp: new Date().toISOString(),
    }

    event.status = err.status
  }
}))

app.use(async ctx => {
  ctx.throw(400, "Invalid input")
})

app.listen(3000, () => console.log("Server running on http://localhost:3000"))

⚙️ API

error(options?: ErrorHandlerOptions | ErrorEventListener)

Creates a Koa middleware for centralized error handling.

Options

| Option | Type | Description | |--------|------|-------------| | prepare | (error: any) => any | Optional. Normalize or wrap any thrown error before handling error event. | | onerror | (event: ErrorEvent) => void | Required. Define how the final JSON response should look. | | finalize | (event: ErrorEvent) => void | Optional. Mutate the response before sending (e.g., for logging). | | debug | boolean | Optional. Logs caught errors to console when true. Defaults to process.env.NODE_ENV === "development". |

ErrorEvent

Each onerror receives an ErrorEvent object:

type ErrorEvent<Err = any> = {
  error: Err
  status: number
  body: any
  type: string
  meta: {
    accepts: string[] | string | false
    method: string
    path: string
  }
}

💡 Design Philosophy

• This package does not automatically normalize errors.
  → Developers decide how to shape their own responses.
• No magic defaults, no HTML responses, no stack traces unless you add them.

🧠 Example: Production vs Development

import error from "@x-titan/koa-error-handler"
import createHttpError from "http-errors"

app.use(error({
  prepare(error) {
    return createHttpError(error.status || 500, error.message)
  },
  onerror(event) {
    const err = event.error
    const isDev = process.env.NODE_ENV === "development"

    event.body = {
      success: false,
      message: err.expose ? err.message : "Internal Server Error",
      ...(isDev && { stack: err.stack }),
    }

    event.status = err.status
  }
}))

🧺 Default Behavior

If no onerror is provided:

{
  "error": "Internal Server Error"
}

📝 License

MIT © 2025 Aset Telmanov