Arc Error Utilities*

*This readme was AI generated.

Lightweight HTTP-style error classes and a helper for throwing by status code.
Provides clean, consistent error handling for APIs, middlewares, and service layers.

✨ Features

• Named error classes with HTTP status and optional debug payloads
• throwByStatus() helper to raise the correct error by HTTP code
• Consistent structure for API responses and error logging
• Zero dependencies, fully compatible with Node or browser builds

📦 Installation

npm install arc-errors

🧩 Exported Classes

| Class | Status | Typical Use | |----------------|--------|----------------------------------| | BadRequest | 400 | Invalid input, schema failure | | Unauthorized | 401 | Authentication required/failed | | NotFound | 404 | Resource not found | | RateLimit | 429 | Too many requests (rate limited) | | ServerError | 500 | Internal server issues | | AuthRedirect | 302 | Login or re-auth redirect |

Each extends Error and adds a numeric status plus optional debug data.

🧠 throwByStatus(status, message?, debug?, throwOn500?)

Automatically throws the right subclass for the given HTTP code.

import {
  throwByStatus,
  BadRequest,
  Unauthorized,
  NotFound,
  RateLimit,
  ServerError,
  AuthRedirect
} from 'arc-errors';

// Example
throwByStatus(404);               // → throws new NotFound('Not found')
throwByStatus(400, 'Invalid');    // → throws new BadRequest('Invalid')
throwByStatus(401, 'No token');   // → throws new Unauthorized('No token')
throwByStatus(429, 'Too fast');   // → throws new RateLimit('Too fast')

// Custom debug payload
throwByStatus(500, 'DB down', { node: 3 });

// Suppress throwing for 500s (e.g. logging-only)
throwByStatus(500, 'Optional', { trace: 'x' }, false);

| Status | Behavior | |---------|-----------| | 302 | AuthRedirect | | 400 | BadRequest | | 401 | Unauthorized | | 404 | NotFound | | 429 | RateLimit | | 500 | ServerError (skipped if _throwOn500 === false) | | 200 / 204 | No throw | | Other | No throw |

🧪 Example: Express Middleware

app.use((req, res, next) => {
  try {
    if (!req.user) throw new Unauthorized('Login required');
    next();
  } catch (err) {
    res.status(err.status || 500).json({
      error: err.message,
      debug: err.debug ?? null
    });
  }
});

🧰 Custom Usage

You can also instantiate directly:

throw new BadRequest('Invalid body', { body: req.body });
throw new RateLimit('Too many attempts', { ip: req.ip });
throw new ServerError('DB connection failed', { retry: true });

🧱 Error Serialization (for APIs)

If you return these errors from an API, a common pattern is:

function serializeError(err) {
  return {
    status: err.status || 500,
    message: err.message,
    ...(err.debug && { debug: err.debug })
  };
}

// Example
try {
  throw new NotFound('User missing', { id: 123 });
} catch (err) {
  const response = serializeError(err);
  // Send as JSON response
  // res.status(response.status).json(response);
}

✅ Testing

Comprehensive Jest tests are included. Run:

npm test

📄 License

This project is released under The Unlicense, placing it in the public domain.