@jaypie/errors

Prerequisites: npm install jaypie or npm install @jaypie/errors

Overview

@jaypie/errors provides typed error classes that map to HTTP status codes and format as JSON:API errors.

Installation

npm install jaypie
# or
npm install @jaypie/errors

Quick Reference

Error Classes

Class	Status	Use Case
BadRequestError	400	Invalid input
UnauthorizedError	401	Authentication required
ForbiddenError	403	Permission denied
NotFoundError	404	Resource not found
MethodNotAllowedError	405	Wrong HTTP method
GoneError	410	Resource deleted
TeapotError	418	Easter egg
TooManyRequestsError	429	Rate limited
InternalError	500	Server error
ConfigurationError	500	Missing config
NotImplementedError	400	Feature not built
BadGatewayError	502	Upstream error
UnavailableError	503	Service down
GatewayTimeoutError	504	Upstream timeout
RejectedError	403	Request rejected

Utilities

Export	Purpose
isJaypieError	Type guard for Jaypie errors
jaypieErrorFromStatus	Create error from status code

Usage

Throwing Errors

Both syntaxes work:

import { BadRequestError, NotFoundError } from "jaypie";

// Function call (preferred)
throw BadRequestError("Missing required field");

// Constructor
throw new BadRequestError("Missing required field");

Preserving the Cause

Every error class takes cause as its second argument:

import { ConfigurationError } from "jaypie";

try {
  await getSecret(name);
} catch (error) {
  throw new ConfigurationError("Could not get or parse secret", {
    cause: error,
  });
}

The base JaypieError takes status and title alongside cause. The named classes take cause only, because status and title identify the class.

Error Properties

const error = NotFoundError("User not found");

error.status;         // 404
error.title;          // "Not Found"
error.name;           // "JaypieError"
error.message;        // "User not found"
error.detail;         // "User not found"
error.isJaypieError;  // true

Every Jaypie error carries the name JaypieError. Use instanceof, isJaypieError(error), or error.status to discriminate, not error.name.

JSON:API Body

const error = BadRequestError("Invalid email");
error.body();

Returns:

{
  "errors": [
    {
      "status": 400,
      "title": "Bad Request",
      "detail": "Invalid email"
    }
  ]
}

Checking Error Types

instanceof identifies a specific error class:

import { NotFoundError } from "jaypie";

try {
  await getUser(id);
} catch (error) {
  if (error instanceof NotFoundError) {
    return null;
  }
  throw error;
}

The check holds across the ESM and CommonJS builds, so an error raised inside a CommonJS package matches in an ESM package, and it holds when two copies of @jaypie/errors are installed. Class identity does not: compare with instanceof, never error.constructor === NotFoundError.

Type Guard

import { isJaypieError, InternalError } from "jaypie";

try {
  await riskyOperation();
} catch (error) {
  if (isJaypieError(error)) {
    return res.status(error.status).json(error.body());
  }
  throw InternalError();
}

From Status Code

import { jaypieErrorFromStatus } from "jaypie";

const error = jaypieErrorFromStatus(404, "Not found");
// Returns NotFoundError

Error Selection Guide

Client Errors (4xx)

Scenario	Error
Missing required field	BadRequestError
Invalid format	BadRequestError
No auth token	UnauthorizedError
Invalid auth	UnauthorizedError
No permission	ForbiddenError
Resource missing	NotFoundError
Wrong HTTP method	MethodNotAllowedError
Resource deleted	GoneError
Rate limited	TooManyRequestsError

Server Errors (5xx)

Scenario	Error
Missing env var	ConfigurationError
External API failed	BadGatewayError
External API timeout	GatewayTimeoutError
Maintenance mode	UnavailableError
Unexpected state	InternalError

Examples

Validation

import { BadRequestError } from "jaypie";

function validateEmail(email) {
  if (!email) {
    throw BadRequestError("Email is required");
  }
  if (!email.includes("@")) {
    throw BadRequestError("Invalid email format");
  }
}

Resource Not Found

import { NotFoundError } from "jaypie";

async function getUser(id) {
  const user = await db.users.findById(id);
  if (!user) {
    throw NotFoundError("User not found");
  }
  return user;
}

External Service

import { BadGatewayError, log } from "jaypie";

async function callPaymentService(data) {
  try {
    return await paymentApi.charge(data);
  } catch (error) {
    log.error("Payment service failed");
    log.var({ error: error.message });
    throw BadGatewayError();
  }
}

Configuration

import { ConfigurationError } from "jaypie";

function getDbUri() {
  const uri = process.env.MONGODB_URI;
  if (!uri) {
    throw ConfigurationError("MONGODB_URI not configured");
  }
  return uri;
}

Testing

import { matchers } from "@jaypie/testkit";
expect.extend(matchers);

it("throws BadRequestError for invalid input", () => {
  expect(() => validateEmail(null)).toThrowBadRequestError();
});

it("throws any Jaypie error", () => {
  expect(() => riskyOperation()).toThrowJaypieError();
});

Available Matchers

• toThrowJaypieError()
• toThrowBadRequestError()
• toThrowUnauthorizedError()
• toThrowForbiddenError()
• toThrowNotFoundError()
• toThrowInternalError()
• toThrowConfigurationError()
• toThrowBadGatewayError()
• toThrowUnavailableError()

Related

• Error Handling - Patterns and best practices
• Handler Lifecycle - Automatic error formatting
• Testing - Testing error conditions