title: '@smallbiz/errors' description: Shared ApiError helpers for SmallBiz Innovation projects.

@smallbiz/errors

Utility package providing ApiError, serialization helpers, and convenience factories for common HTTP scenarios.

Installation

pnpm add @smallbiz/errors

Usage

Throw an ApiError (or use one of the factories) inside Cloudflare Workers and return a serialized JSON response with handleApiError:

import { badRequest, handleApiError } from '@smallbiz/errors';

export default {
  async fetch(request: Request): Promise<Response> {
    try {
      const payload = await request.json();
      if (!payload.imageId) {
        throw badRequest('imageId is required', 'missing_image_id');
      }
      return Response.json({ ok: true });
    } catch (error) {
      return handleApiError(error, { request });
    }
  },
};

handleApiError automatically attaches cf-ray/x-request-id headers, includes stack traces for server errors, and generates a response body with the status, code, message, and optional details block.

Use normalizeError when you need to coerce user-supplied errors into the shared shape without sending a response immediately.

Testing

Vitest suites cover serialization, helper factory behavior, and normalization logic:

pnpm test --filter @smallbiz/errors