Implement HttpError class for standardized error handling

[thehabes]

Summary

Create a custom HttpError class to standardize error throwing across the codebase. This builds on the error handling improvements from PR #423 and will make the centralized error middleware more effective.

Background

PR #423 introduced centralized error middleware in app.js that:

• Logs errors with color-coded output (red for 5xx, yellow for 4xx)
• Logs stack traces for 500 errors (with file paths and line numbers)
• Returns consistent JSON responses to clients

However, the codebase currently has inconsistent error patterns:

Current Pattern 1 - Good but verbose (utilities/shared.js)

const error = new Error(`Layer with ID '${layerId}' not found...`)
error.status = 404
throw error

Current Pattern 2 - Missing status codes (classes/User/User.js)

throw new Error(`User with _id ${this._id} not found`)
// This becomes a 500 error when it should be 404

Proposed Solution

Create utilities/HttpError.js:

/**
 * Custom HTTP Error class for consistent error handling across the API.
 * Thrown errors are caught by centralized middleware in app.js.
 * 
 * @example
 * throw new HttpError(404, 'User not found')
 * throw new HttpError(400, 'Invalid request body')
 * throw new HttpError(403, 'Not authorized to access this project')
 */
export class HttpError extends Error {
  constructor(status, message) {
    super(message)
    this.status = status
    this.name = 'HttpError'
    Error.captureStackTrace(this, this.constructor)
  }
}

export default HttpError

Usage

Before (3 lines):

const error = new Error(`Project with ID '${projectId}' not found`)
error.status = 404
throw error

After (1 line):

throw new HttpError(404, `Project with ID '${projectId}' not found`)

Files to Update

File	Current Errors	Notes
utilities/shared.js	6 errors with .status	Refactor to HttpError
classes/User/User.js	9 plain Error throws	Add proper status codes
classes/Line/Line.js	1 plain Error throw	Add proper status code
classes/Project/Project.js	Check for errors	Add proper status codes
Other class files	Audit needed	Standardize all

Benefits

• Stack traces preserved - Full file paths and line numbers in pm2 logs
• Consistent status codes - No more accidental 500s for 404 situations
• Cleaner code - One-liner instead of three lines
• Better debugging - All errors flow through centralized middleware
• Simpler routes - Less try/catch boilerplate needed

Acceptance Criteria

• Create utilities/HttpError.js with JSDoc documentation
• Update utilities/shared.js to use HttpError (6 locations)
• Audit and update class files to use HttpError with appropriate status codes
• Update centralized middleware to recognize HttpError if needed
• All existing tests pass
• Add unit tests for HttpError class

Related

• Builds on PR Error Catching and Logging In Routes #423 (Error catching and logging)
• Issue Error Logging #422 (Original error logging request)

[thehabes]

Extract RERUM fetch-with-error-handling into a shared helper

The RERUM fetch pattern (fetch → check resp.ok → parse error text → throw with status 502 → catch network errors → throw generic 502) is now duplicated 6 times across Page.js and Line.js:

• Page.#loadAnnotationPageDataFromRerum()
• Page.#savePageToRerum() (fetch existing)
• Line.#saveLineToRerum() (fetch existing)
• Line.#loadAnnotationDataFromRerum()

Each is ~15 lines of nearly identical code. Consider extracting a shared utility:

// utilities/rerum.js

export async function fetchFromRerum(uri) {
    const resp = await fetch(uri).catch(networkErr => {
        const err = new Error(`500: ${uri} - A RERUM error occurred`)
        err.status = 502
        throw err
    })
    if (resp.ok) return resp.json()
    let msg
    try { msg = `${resp.status ?? 500}: ${uri} - ${await resp.text()}` }
    catch { msg = `500: ${uri} - A RERUM error occurred` }
    const err = new Error(msg)
    err.status = 502
    throw err
}

[thehabes]

This has become outdated and will be rewritten for the updated codebase.