Error Handler

pnpm dlx blockend-cli add error-handler

/**
 * Base class for all expected, handled application errors.
 *
 * Use this for errors you anticipate — bad input, missing resources,
 * auth failures. The global error handler checks `instanceof AppError`
 * and returns a clean, predictable JSON shape for these.
 *
 * Anything that is NOT an AppError is treated as a bug, logged in full,
 * and never leaked to the client beyond a generic message.
 */
export class AppError extends Error {
  constructor(
    public readonly statusCode: number,
    message: string,
    /**
     * Operational errors are expected and safe to expose to the client.
     * Set to false for errors that are technically anticipated but
     * shouldn't reveal details (rare — defaults to true for normal use).
     */
    public readonly isOperational: boolean = true
  ) {
    super(message);
    this.name = "AppError";

    // Required when extending built-ins like Error in TypeScript —
    // without this, `instanceof AppError` can silently return false
    // depending on the consuming project's compile target.
    Object.setPrototypeOf(this, AppError.prototype);
  }
}

export const HTTP_STATUS = {
  OK: 200,
  CREATED: 201,
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  CONFLICT: 409,
  UNPROCESSABLE_ENTITY: 422,
  INTERNAL_SERVER_ERROR: 500,
  SERVICE_UNAVAILABLE: 503
} as const;

export type HttpStatus = (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS];

import { HTTP_STATUS } from "./http-status.js";

/**
 * Common error catalog. Use with `throwError(ERRORS.NOT_FOUND)` or
 * reference `.message` / `.status` directly when building your own AppError.
 *
 * This is a starting set, not an exhaustive one — add your own entries
 * as your domain needs them. It's your file now.
 */
export const ERRORS = {
  VALIDATION_FAILED: {
    message: "Validation failed",
    status: HTTP_STATUS.BAD_REQUEST
  },
  BAD_REQUEST: {
    message: "Bad request",
    status: HTTP_STATUS.BAD_REQUEST
  },
  INVALID_CREDENTIALS: {
    message: "Invalid credentials",
    status: HTTP_STATUS.UNAUTHORIZED
  },
  UNAUTHORIZED: {
    message: "Unauthorized access",
    status: HTTP_STATUS.UNAUTHORIZED
  },
  FORBIDDEN: {
    message: "You do not have permission to perform this action",
    status: HTTP_STATUS.FORBIDDEN
  },
  TOKEN_EXPIRED: {
    message: "Session expired. Please log in again.",
    status: HTTP_STATUS.UNAUTHORIZED
  },
  INVALID_TOKEN: {
    message: "Invalid token",
    status: HTTP_STATUS.UNAUTHORIZED
  },
  TOKEN_TYPE_MISMATCH: {
    message: "Token type mismatch",
    status: HTTP_STATUS.UNAUTHORIZED
  },
  TOKEN_REVOKED: {
    message: "Token has been revoked",
    status: HTTP_STATUS.UNAUTHORIZED
  },
  NOT_FOUND: {
    message: "Not found",
    status: HTTP_STATUS.NOT_FOUND
  },
  USER_ALREADY_EXISTS: {
    message: "User already exists",
    status: HTTP_STATUS.CONFLICT
  },
  DUPLICATE_RESOURCE: {
    message: "Resource already exists",
    status: HTTP_STATUS.CONFLICT
  },
  UNPROCESSABLE: {
    message: "Unable to process the request",
    status: HTTP_STATUS.UNPROCESSABLE_ENTITY
  },
  INTERNAL_SERVER_ERROR: {
    message: "Internal server error",
    status: HTTP_STATUS.INTERNAL_SERVER_ERROR
  },
  SERVICE_UNAVAILABLE: {
    message: "Service temporarily unavailable",
    status: HTTP_STATUS.SERVICE_UNAVAILABLE
  }
} as const;

export type ErrorKey = keyof typeof ERRORS;

import { AppError } from "./app-error.js";
import { ERRORS } from "./errors.js";

/**
 * Throws an AppError from a catalog entry in ERRORS.
 *
 * Usage: throwError(ERRORS.NOT_FOUND)
 * Equivalent to: throw new AppError(404, 'Not found')
 *
 * Use this for catalog errors. Use `new AppError(status, message)`
 * directly for one-off errors that don't belong in the shared catalog.
 */
export function throwError(error: { message: string; status: number }): never {
  throw new AppError(error.status, error.message);
}

export { ERRORS };

import type { Request, Response, NextFunction } from "express";

/**
 * Wraps an async Express route handler so rejected promises are passed
 * to `next()` and reach the global error handler, instead of crashing
 * the process or hanging the request.
 *
 * Pairs directly with globalErrorHandler — use both together.
 *
 * router.get('/users/:id', asyncHandler(async (req, res) => {
 *   const user = await db.user.findUnique({ where: { id: req.params.id } })
 *   if (!user) throwError(ERRORS.NOT_FOUND)
 *   res.json(user)
 * }))
 */
export const asyncHandler =
  (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>) =>
  (req: Request, res: Response, next: NextFunction): void => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };

import type { Request, Response, NextFunction } from "express";
import { z, ZodError } from "zod";

import { AppError } from "./app-error.js";
import { HTTP_STATUS } from "./http-status.js";
import { ERRORS } from "./errors.js";

/**
 * Express error-handling middleware. Register this LAST, after all routes
 * and other middleware — Express identifies error handlers by their
 * 4-argument signature, and only calls the first one that matches.
 *
 * app.use(globalErrorHandler)
 */
export const globalErrorHandler = (
  err: unknown,
  req: Request,
  res: Response,
  // oxlint-disable-next-line @typescript-eslint/no-unused-vars
  next: NextFunction
) => {
  // -------------------------
  // Custom AppError — expected, operational errors
  // -------------------------
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      success: false,
      data: null,
      message: err.message
    });
  }

  // -------------------------
  // Zod validation error
  // -------------------------
  if (err instanceof ZodError) {
    return res.status(HTTP_STATUS.BAD_REQUEST).json({
      success: false,
      data: null,
      message: ERRORS.VALIDATION_FAILED.message,
      errors: z.treeifyError(err)
    });
  }

  // -------------------------
  // Unknown / unhandled errors — never leak details to the client
  // -------------------------
  logUnhandledError(err, req);

  return res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
    success: false,
    data: null,
    message: ERRORS.INTERNAL_SERVER_ERROR.message
  });
};

/**
 * Single seam for unhandled-error logging. Swap this out for a
 * structured logger (e.g. Blockend's `logger` block) without touching
 * the control flow above.
 */
function logUnhandledError(err: unknown, req: Request): void {
  // oxlint-disable-next-line no-console
  console.error("[UNHANDLED ERROR]", {
    method: req.method,
    path: req.path,
    error: err
  });
}

export { AppError } from "./app-error.js";
export { ERRORS } from "./errors.js";
export type { ErrorKey } from "./errors.js";
export { HTTP_STATUS } from "./http-status.js";
export type { HttpStatus } from "./http-status.js";
export { throwError } from "./throw-error.js";
export { globalErrorHandler } from "./global-error-handler.js";
export { asyncHandler } from "./async-handler.js";