@b9g/http-errors 0.1.4 → 0.2.0-beta.0

package/README.md

@@ -1,14 +1,14 @@
 # @b9g/http-errors
-
-**Standard HTTP error responses for ServiceWorker applications. Returns proper Response objects with status codes, not thrown exceptions.**
+**Standard HTTP error classes with native cause support and automatic serialization**
 
 ## Features
 
-- **ServiceWorker Compatible**: Returns Response objects perfect for `event.respondWith()`
-- **Standard HTTP Status Codes**: Pre-defined functions for all common HTTP errors
-- **No Exceptions**: Functional approach - return errors, don't throw them
-- **TypeScript Support**: Full type definitions for all error classes
 - **Universal**: Works in browsers, Node.js, Bun, and edge platforms
+- **Response Protocol**: Implements `toResponse()` for automatic HTTP response conversion
+- **Structured Logging**: Built-in `toJSON()` for clean error serialization
+- **Standard HTTP Status Codes**: Pre-defined classes for all common HTTP errors
+- **TypeScript Support**: Full type definitions for all error classes
+- **Error Chaining**: Native `cause` support for error context
 
 ## Installation
 
@@ -18,336 +18,162 @@ npm install @b9g/http-errors
 
 ## Quick Start
 
-```javascript
-import { 
-  NotFound, 
-  BadRequest, 
-  Unauthorized, 
-  InternalServerError 
-} from '@b9g/http-errors';
-
-// Create error responses
-const notFound = NotFound('Page not found');
-const badRequest = BadRequest('Invalid input data');
-const unauthorized = Unauthorized('Authentication required');
-const serverError = InternalServerError('Database connection failed');
-
-// All return Response objects
-console.log(notFound instanceof Response); // true
-console.log(notFound.status); // 404
-```
-
-## Available Error Classes
-
-### Client Errors (4xx)
-
 ```javascript
 import {
-  BadRequest,           // 400
-  Unauthorized,         // 401
-  PaymentRequired,      // 402
-  Forbidden,           // 403
-  NotFound,            // 404
-  MethodNotAllowed,    // 405
-  NotAcceptable,       // 406
-  RequestTimeout,      // 408
-  Conflict,            // 409
-  Gone,                // 410
-  LengthRequired,      // 411
-  PreconditionFailed,  // 412
-  PayloadTooLarge,     // 413
-  URITooLong,          // 414
-  UnsupportedMediaType, // 415
-  RangeNotSatisfiable, // 416
-  ExpectationFailed,   // 417
-  ImATeapot,           // 418
-  UnprocessableEntity, // 422
-  TooManyRequests,     // 429
+  NotFound,
+  BadRequest,
+  Unauthorized,
+  InternalServerError
 } from '@b9g/http-errors';
-```
-
-### Server Errors (5xx)
-
-```javascript
-import {
-  InternalServerError, // 500
-  NotImplemented,      // 501
-  BadGateway,          // 502
-  ServiceUnavailable,  // 503
-  GatewayTimeout,      // 504
-  HTTPVersionNotSupported, // 505
-} from '@b9g/http-errors';
-```
-
-## Usage Examples
-
-### Basic Error Responses
-
-```javascript
-import { NotFound, BadRequest } from '@b9g/http-errors';
-
-// Simple message
-const error1 = NotFound('User not found');
-
-// With additional details
-const error2 = BadRequest('Invalid email format', {
-  field: 'email',
-  code: 'INVALID_FORMAT'
-});
-```
-
-### Router Integration
 
-```javascript
-import { Router } from '@b9g/router';
-import { NotFound, BadRequest, Unauthorized } from '@b9g/http-errors';
+// Throw as exceptions
+throw new NotFound('Page not found');
+throw new BadRequest('Invalid input data');
 
-const router = new Router();
+// Or convert to Response objects
+const error = new NotFound('Page not found');
+return error.toResponse(); // Response with status 404
 
-router.get('/users/:id', async (request, context) => {
-  const { id } = context.params;
-  
-  // Validate input
-  if (!id || isNaN(Number(id))) {
-    return BadRequest('Invalid user ID');
-  }
-  
-  // Check authentication
-  if (!request.headers.get('authorization')) {
-    return Unauthorized('Authentication required');
-  }
-  
-  // Find user
-  const user = await db.users.find(id);
-  if (!user) {
-    return NotFound('User not found');
-  }
-  
-  return Response.json(user);
-});
+// In development, get detailed error pages
+return error.toResponse(true); // HTML page with stack trace
 ```
 
-### Middleware Error Handling
+## API
 
-```javascript
-router.use(async function* (request, context) {
-  try {
-    return yield request;
-  } catch (error) {
-    console.error('Request failed:', error);
-    return InternalServerError('Something went wrong');
-  }
-});
-```
+### HTTPError Class
 
-### Custom Error Details
+Base class for all HTTP errors. Extends `Error`.
 
 ```javascript
-import { BadRequest, Conflict } from '@b9g/http-errors';
-
-// With error code
-const validationError = BadRequest('Validation failed', {
-  code: 'VALIDATION_ERROR',
-  fields: ['email', 'password']
-});
-
-// With retry information
-const rateLimitError = TooManyRequests('Rate limit exceeded', {
-  retryAfter: 60,
-  limit: 100,
-  window: 3600
+import { HTTPError } from '@b9g/http-errors';
+
+const error = new HTTPError(404, 'Resource not found', {
+  cause: originalError,        // Error that caused this
+  headers: {                    // Custom headers for response
+    'Cache-Control': 'no-store'
+  },
+  expose: true                  // Whether to expose message to client
 });
 
-// With conflict details
-const duplicateError = Conflict('Email already exists', {
-  field: 'email',
-  value: 'user@example.com'
-});
+error.status;        // 404
+error.message;       // 'Resource not found'
+error.expose;        // true (client errors default to true, server errors to false)
+error.headers;       // { 'Cache-Control': 'no-store' }
 ```
 
-## Exports
-
-### Classes
-
-- `HTTPError` - Base HTTP error class (extends Error)
-- `NotHandled` - Special error for unhandled requests
-
-### Client Error Classes (4xx)
-
-- `BadRequest` (400)
-- `Unauthorized` (401)
-- `Forbidden` (403)
-- `NotFound` (404)
-- `MethodNotAllowed` (405)
-- `Conflict` (409)
-- `UnprocessableEntity` (422)
-- `TooManyRequests` (429)
-
-### Server Error Classes (5xx)
-
-- `InternalServerError` (500)
-- `NotImplemented` (501)
-- `BadGateway` (502)
-- `ServiceUnavailable` (503)
-- `GatewayTimeout` (504)
-
-### Functions
-
-- `createHTTPError(status, message?, options?)` - Create an HTTPError with a specific status code
-- `isHTTPError(value)` - Type guard to check if a value is an HTTPError
-
-### Types
-
-- `HTTPErrorOptions` - Options for HTTPError constructor
+### Methods
 
-### Default Export
+#### `toResponse(isDev?: boolean): Response`
 
-- `createHTTPError` - Factory function for creating HTTP errors
+Converts the error to an HTTP Response object.
 
-## API Reference
+- In development mode (`isDev = true`): Returns HTML page with stack trace
+- In production mode: Returns plain text with minimal information
 
-### Error Classes
+```javascript
+const error = new NotFound('Page not found');
 
-All error functions follow the same signature:
+// Production response
+error.toResponse();      // Response { status: 404, body: 'Page not found' }
 
-```typescript
-function ErrorName(message?: string, details?: any): Response
+// Development response with stack trace
+error.toResponse(true);  // Response { status: 404, body: '<html>...</html>' }
 ```
 
-#### Parameters
+#### `toJSON(): object`
 
-- `message` (optional): Human-readable error message
-- `details` (optional): Additional error details (serialized as JSON)
-
-#### Returns
-
-Returns a `Response` object with:
-- Appropriate HTTP status code
-- `Content-Type: application/json`
-- JSON body containing error information
-
-### Response Format
+Converts the error to a plain object for logging and serialization.
 
 ```javascript
-{
-  "error": {
-    "type": "NotFound",
-    "message": "User not found",
-    "status": 404,
-    "details": {
-      // Any additional details provided
-    }
-  }
-}
-```
+const error = new BadRequest('Invalid email', {
+  headers: { 'X-Custom': 'value' }
+});
 
-## TypeScript Support
+JSON.stringify(error);
+// {
+//   "name": "BadRequest",
+//   "message": "Invalid email",
+//   "status": 400,
+//   "statusCode": 400,
+//   "expose": true,
+//   "headers": { "X-Custom": "value" }
+// }
 
-Full TypeScript definitions included:
+### Client Error Classes (4xx)
 
-```typescript
-import type { ErrorResponse } from '@b9g/http-errors';
+```javascript
+import {
+  BadRequest,           // 400
+  Unauthorized,         // 401
+  Forbidden,            // 403
+  NotFound,             // 404
+  MethodNotAllowed,     // 405
+  Conflict,             // 409
+  UnprocessableEntity,  // 422
+  TooManyRequests       // 429
+} from '@b9g/http-errors';
 
-function handleError(): ErrorResponse {
-  return NotFound('Resource not found');
-}
+// All accept message and options
+throw new Unauthorized('Invalid credentials', {
+  headers: { 'WWW-Authenticate': 'Bearer realm="api"' }
+});
 
-// ErrorResponse extends Response
-const response: Response = handleError();
+throw new TooManyRequests('Rate limit exceeded', {
+  headers: { 'Retry-After': '60' }
+});
 ```
 
-## Integration Examples
-
-### API Error Handling
+### Server Error Classes (5xx)
 
 ```javascript
-import { 
-  BadRequest, 
-  NotFound, 
-  Conflict, 
-  InternalServerError 
+import {
+  InternalServerError,  // 500
+  NotImplemented,       // 501
+  BadGateway,           // 502
+  ServiceUnavailable,   // 503
+  GatewayTimeout        // 504
 } from '@b9g/http-errors';
 
-router.post('/api/users', async (request) => {
-  try {
-    const data = await request.json();
-    
-    // Validation
-    if (!data.email) {
-      return BadRequest('Email is required');
-    }
-    
-    // Check for existing user
-    const existing = await db.users.findByEmail(data.email);
-    if (existing) {
-      return Conflict('Email already registered');
-    }
-    
-    // Create user
-    const user = await db.users.create(data);
-    return Response.json(user, { status: 201 });
-    
-  } catch (error) {
-    return InternalServerError('Failed to create user');
-  }
+// Server errors default to expose: false
+throw new InternalServerError('Database connection failed', {
+  cause: dbError  // Chain the original error
 });
 ```
 
-### Auth Middleware
+### Functions
+
+#### `isHTTPError(value): value is HTTPError`
+
+Type guard to check if a value is an HTTPError.
 
 ```javascript
-import { Unauthorized, Forbidden } from '@b9g/http-errors';
+import {isHTTPError} from '@b9g/http-errors';
 
-const authMiddleware = async function* (request, context) {
-  const token = request.headers.get('authorization');
-  
-  if (!token) {
-    return Unauthorized('Authentication required');
-  }
-  
-  try {
-    const user = await verifyToken(token);
-    context.user = user;
-    return yield request;
-  } catch (error) {
-    return Forbidden('Invalid or expired token');
+try {
+  // ...
+} catch (err) {
+  if (isHTTPError(err)) {
+    return err.toResponse();
   }
-};
-
-router.use('/api/admin/*', authMiddleware);
+  throw err;
+}
 ```
 
-### Input Validation
+### Types
 
-```javascript
-import { BadRequest } from '@b9g/http-errors';
-
-function validateUser(data) {
-  const errors = [];
-  
-  if (!data.email) errors.push('email is required');
-  if (!data.password) errors.push('password is required');
-  if (data.password && data.password.length < 8) {
-    errors.push('password must be at least 8 characters');
-  }
-  
-  if (errors.length > 0) {
-    return BadRequest('Validation failed', { errors });
-  }
-  
-  return null; // Valid
+```typescript
+interface HTTPErrorOptions {
+  /** Original error that caused this HTTP error */
+  cause?: Error;
+  /** Custom headers to include in the error response */
+  headers?: Record<string, string>;
+  /** Whether error details should be exposed to clients (defaults based on status) */
+  expose?: boolean;
+  /** Additional properties to attach to the error */
+  [key: string]: any;
 }
-
-router.post('/register', async (request) => {
-  const data = await request.json();
-  
-  const validationError = validateUser(data);
-  if (validationError) return validationError;
-  
-  // Process valid data...
-});
 ```
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@b9g/http-errors",
-  "version": "0.1.4",
-  "description": "Standard HTTP error responses for ServiceWorker applications. Returns proper Response objects with status codes, not thrown exceptions.",
+  "version": "0.2.0-beta.0",
+  "description": "Standard HTTP error classes with native cause support and automatic serialization",
   "keywords": [
     "http",
     "errors",
@@ -14,8 +14,7 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@b9g/libuild": "^0.1.11",
-    "bun-types": "latest"
+    "@b9g/libuild": "^0.1.18"
   },
   "type": "module",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -1,10 +1,7 @@
 /**
- * Modern HTTP error classes for Shovel
- * Lightweight alternative to http-errors with native Error cause support
- */
-/**
- * Options for creating HTTP errors
+ * Standard HTTP error classes with native cause support and automatic serialization
  */
+/** Options for creating HTTP errors */
 export interface HTTPErrorOptions {
     /** Original error that caused this HTTP error */
     cause?: Error;
@@ -12,18 +9,14 @@ export interface HTTPErrorOptions {
     headers?: Record<string, string>;
     /** Whether the error details should be exposed to clients (defaults based on status) */
     expose?: boolean;
-    /** Additional properties to attach to the error */
-    [key: string]: any;
 }
-/**
- * Base HTTP error class
- */
+/** Base HTTP error class */
 export declare class HTTPError extends Error {
     readonly status: number;
-    readonly statusCode: number;
     readonly expose: boolean;
     readonly headers?: Record<string, string>;
     constructor(status: number, message?: string, options?: HTTPErrorOptions);
+    get statusCode(): number;
     /**
      * Convert error to a plain object for serialization
      */
@@ -35,21 +28,17 @@ export declare class HTTPError extends Error {
         expose: boolean;
         headers: Record<string, string>;
     };
-}
-/**
- * Special error for middleware fallthrough (not an HTTP error)
- */
-export declare class NotHandled extends Error {
-    constructor(message?: string);
+    /**
+     * Convert error to an HTTP Response
+     * In development mode, shows detailed error page with stack trace
+     * In production mode, shows minimal error message
+     */
+    toResponse(isDev?: boolean): Response;
 }
 /**
  * Check if a value is an HTTP error
  */
 export declare function isHTTPError(value: any): value is HTTPError;
-/**
- * Create an HTTP error with the given status code
- */
-export declare function createHTTPError(status: number, message?: string, options?: HTTPErrorOptions): HTTPError;
 export declare class BadRequest extends HTTPError {
     constructor(message?: string, options?: HTTPErrorOptions);
 }
@@ -89,4 +78,3 @@ export declare class ServiceUnavailable extends HTTPError {
 export declare class GatewayTimeout extends HTTPError {
     constructor(message?: string, options?: HTTPErrorOptions);
 }
-export default createHTTPError;

package/src/index.js

@@ -1,6 +1,6 @@
 /// <reference types="./index.d.ts" />
 // src/index.ts
-var STATUS_CODES = {
+var STATUS_CODE_DEFAULTS = {
   // 4xx Client Errors
   400: "Bad Request",
   401: "Unauthorized",
@@ -44,20 +44,23 @@ var STATUS_CODES = {
   510: "Not Extended",
   511: "Network Authentication Required"
 };
+var HTTP_ERROR = /* @__PURE__ */ Symbol.for("shovel.http-error");
 var HTTPError = class extends Error {
   status;
-  statusCode;
   expose;
   headers;
   constructor(status, message, options = {}) {
-    const defaultMessage = STATUS_CODES[status] || "Unknown Error";
+    const defaultMessage = STATUS_CODE_DEFAULTS[status] || "Unknown Error";
     super(message || defaultMessage, { cause: options.cause });
     this.name = this.constructor.name;
-    this.status = this.statusCode = status;
+    this.status = status;
     this.expose = options.expose ?? status < 500;
     this.headers = options.headers;
     Object.assign(this, options);
   }
+  get statusCode() {
+    return this.status;
+  }
   /**
    * Convert error to a plain object for serialization
    */
@@ -71,24 +74,54 @@ var HTTPError = class extends Error {
       headers: this.headers
     };
   }
-};
-var NotHandled = class extends Error {
-  constructor(message = "Request not handled by middleware") {
-    super(message);
-    this.name = "NotHandled";
+  /**
+   * Convert error to an HTTP Response
+   * In development mode, shows detailed error page with stack trace
+   * In production mode, shows minimal error message
+   */
+  toResponse(isDev) {
+    const headers = new Headers(this.headers);
+    if (isDev && this.expose) {
+      headers.set("Content-Type", "text/html; charset=utf-8");
+      const statusText = STATUS_CODE_DEFAULTS[this.status] || "Unknown Error";
+      const html = `<!DOCTYPE html>
+<html>
+<head>
+  <title>${this.status} ${escapeHTML(statusText)}</title>
+  <style>
+    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+    h1 { color: ${this.status >= 500 ? "#c00" : "#e67700"}; }
+    .message { font-size: 1.2em; color: #333; }
+    pre { background: #f5f5f5; padding: 1rem; overflow-x: auto; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>${this.status} ${escapeHTML(statusText)}</h1>
+  <p class="message">${escapeHTML(this.message)}</p>
+  <pre>${escapeHTML(this.stack || "No stack trace available")}</pre>
+</body>
+</html>`;
+      return new Response(html, {
+        status: this.status,
+        statusText,
+        headers
+      });
+    }
+    headers.set("Content-Type", "text/plain; charset=utf-8");
+    const body = this.expose ? this.message : STATUS_CODE_DEFAULTS[this.status] || "Unknown Error";
+    return new Response(body, {
+      status: this.status,
+      statusText: STATUS_CODE_DEFAULTS[this.status],
+      headers
+    });
   }
 };
-function isHTTPError(value) {
-  if (value instanceof HTTPError)
-    return true;
-  if (!(value instanceof Error))
-    return false;
-  const hasStatus = "status" in value && typeof value.status === "number";
-  const hasStatusCode = "statusCode" in value && typeof value.statusCode === "number";
-  return hasStatus && hasStatusCode && value.status === value.statusCode;
+HTTPError.prototype[HTTP_ERROR] = true;
+function escapeHTML(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
-function createHTTPError(status, message, options) {
-  return new HTTPError(status, message, options);
+function isHTTPError(value) {
+  return !!(value && value[HTTP_ERROR]);
 }
 var BadRequest = class extends HTTPError {
   constructor(message, options) {
@@ -155,7 +188,6 @@ var GatewayTimeout = class extends HTTPError {
     super(504, message, options);
   }
 };
-var src_default = createHTTPError;
 export {
   BadGateway,
   BadRequest,
@@ -166,13 +198,10 @@ export {
   InternalServerError,
   MethodNotAllowed,
   NotFound,
-  NotHandled,
   NotImplemented,
   ServiceUnavailable,
   TooManyRequests,
   Unauthorized,
   UnprocessableEntity,
-  createHTTPError,
-  src_default as default,
   isHTTPError
 };