Add server-side BuildError

Author: webstackdev

src/components/scripts/errors/__tests__/assertions.spec.ts

@@ -5,7 +5,7 @@
 import { describe, expect, test } from 'vitest'
 import { ClientScriptError } from '@components/scripts/errors/ClientScriptError'
 import { isError, isErrorEvent, isPromiseRejectionEvent, isClientScriptError } from '@components/scripts/errors/assertions'
-import { PromiseRejectionEvent } from '@lib/@types/PromiseRejectionEvent'
+import { PromiseRejectionEvent } from '@components/scripts/@types/PromiseRejectionEvent'
 
 const voidFn = () => {}
 

src/components/scripts/errors/__tests__/converters.spec.ts

@@ -14,7 +14,7 @@ import {
   normalizeMessage,
 } from '@components/scripts/errors/converters'
 import { isString } from '@components/scripts/assertions/primitives'
-import { PromiseRejectionEvent } from '@lib/@types/PromiseRejectionEvent'
+import { PromiseRejectionEvent } from '@components/scripts/@types/PromiseRejectionEvent'
 
 const voidFn = () => {}
 

src/components/scripts/errors/assertions.ts

@@ -2,7 +2,7 @@
  * Error-related assertions
  */
 import { ClientScriptError } from './ClientScriptError'
-import type { PromiseRejectionEvent } from '@lib/@types/PromiseRejectionEvent'
+import type { PromiseRejectionEvent } from '@components/scripts/@types/PromiseRejectionEvent'
 
 export function isError(error: unknown): error is Error {
   if (typeof error === 'object' && (error as Error).name === 'Error') return true

src/components/scripts/errors/converters.ts

@@ -39,7 +39,7 @@ export const normalizeMessage = (message: unknown): ClientScriptErrorParams => {
   }
 }
 
-export interface stackMetadata {
+interface stackMetadata {
   fileName?: string | undefined
   lineNumber?: string | undefined
   columnNumber?: string | undefined

src/components/scripts/errors/handler.ts

@@ -39,9 +39,7 @@ export function handleScriptError(
       },
     })
   } else {
-    // For e2e testing to capture any error without needing timeouts
-    if (window._throw) throw clientError
-    // Otherwise log it for debugging
+    // Log it for debugging
     console.error(
       `[${context.scriptName}]${context.operation ? ` ${context.operation}` : ''}:`,
       clientError,

src/lib/errors/BuildError.ts

@@ -0,0 +1,172 @@
+/**
+ * Custom error class for build-time errors with enhanced context
+ *
+ * Used for errors that occur during build processes, compilation, file operations,
+ * and other build-time activities.
+ */
+
+export interface BuildErrorParams {
+  message: string
+  stack?: string | undefined
+  cause?: unknown
+  /** Build phase where the error occurred (e.g., 'compilation', 'optimization', 'bundling') */
+  phase?: string | undefined
+  /** File path where the error occurred */
+  filePath?: string | undefined
+  /** Build tool or process that encountered the error */
+  tool?: string | undefined
+  /** Line number in source file (for compilation errors) */
+  lineNumber?: number | undefined
+  /** Column number in source file (for compilation errors) */
+  columnNumber?: number | undefined
+  /** Exit code from build process */
+  exitCode?: number | undefined
+}
+
+/**
+ * Normalize various input types to BuildErrorParams
+ */
+function normalizeMessage(message: unknown): BuildErrorParams {
+  if (message instanceof Error) {
+    return {
+      message: message.message,
+      stack: message.stack,
+      cause: message.cause
+    }
+  }
+
+  if (typeof message === 'string') {
+    return { message }
+  }
+
+  if (message === undefined || message === null) {
+    return { message: '' }
+  }
+
+  return { message: String(message) }
+}
+
+export class BuildError extends Error {
+  phase?: string | undefined
+  filePath?: string | undefined
+  tool?: string | undefined
+  lineNumber?: number | undefined
+  columnNumber?: number | undefined
+  exitCode?: number | undefined
+
+  constructor(message?: unknown, context?: Partial<BuildErrorParams>) {
+    const data = normalizeMessage(message)
+    super(data.message || '')
+
+    /**
+     * Set error name as constructor name and make it not enumerable to
+     * keep native Error behavior
+     */
+    Object.defineProperty(this, 'name', {
+      value: 'BuildError',
+      enumerable: false,
+      configurable: true,
+    })
+
+    /** Fix the extended error prototype chain because TypeScript __extends can't */
+    Object.setPrototypeOf(this, new.target.prototype)
+
+    /** Remove constructor from stack trace in V8 */
+    if ('captureStackTrace' in Error) Error.captureStackTrace(this, BuildError)
+
+    /** V8 collects last 10 stack traces by default, this collects all */
+    if ('stackTraceLimit' in Error) Error.stackTraceLimit = Infinity
+
+    // Set core error properties
+    this.message = data.message || ''
+    this.cause = data.cause
+
+    // Set build-specific context from constructor parameter
+    if (context) {
+      this.phase = context.phase
+      this.tool = context.tool
+      this.exitCode = context.exitCode
+      this.filePath = context.filePath
+      this.lineNumber = context.lineNumber
+      this.columnNumber = context.columnNumber
+    }
+  }
+
+  /**
+   * Create a BuildError for compilation failures
+   */
+  static compilation(message: string, filePath?: string, lineNumber?: number, columnNumber?: number): BuildError {
+    return new BuildError(message, {
+      phase: 'compilation',
+      tool: 'typescript',
+      filePath,
+      lineNumber,
+      columnNumber
+    })
+  }
+
+  /**
+   * Create a BuildError for file operation failures
+   */
+  static fileOperation(message: string, filePath?: string, operation?: string): BuildError {
+    return new BuildError(message, {
+      phase: 'file-operation',
+      tool: operation || 'filesystem',
+      filePath
+    })
+  }
+
+  /**
+   * Create a BuildError for bundling/build tool failures
+   */
+  static bundling(message: string, tool?: string, exitCode?: number): BuildError {
+    return new BuildError(message, {
+      phase: 'bundling',
+      tool: tool || 'bundler',
+      exitCode
+    })
+  }
+
+  toJSON() {
+    return {
+      error: {
+        name: this.name,
+        message: this.message,
+        stack: this.stack,
+        phase: this.phase,
+        filePath: this.filePath,
+        tool: this.tool,
+        lineNumber: this.lineNumber,
+        columnNumber: this.columnNumber,
+        exitCode: this.exitCode
+      },
+    }
+  }
+
+  /**
+   * Format error for console output with build context
+   */
+  override toString(): string {
+    let output = `${this.name}: ${this.message}`
+
+    if (this.phase) output += ` [${this.phase}]`
+    if (this.tool) output += ` (${this.tool})`
+    if (this.filePath) {
+      output += `\n  at ${this.filePath}`
+      if (this.lineNumber) {
+        output += `:${this.lineNumber}`
+        if (this.columnNumber) output += `:${this.columnNumber}`
+      }
+    }
+    if (this.exitCode !== undefined) output += `\n  Exit code: ${this.exitCode}`
+
+    return output
+  }
+}
+
+/**
+ * Type guard to check if an error is a BuildError
+ */
+export function isBuildError(error: unknown): error is BuildError {
+  return error instanceof BuildError
+}

src/lib/errors/__tests__/BuildError.spec.ts

@@ -0,0 +1,166 @@
+/**
+ * Tests for error handling routines and custom errors
+ */
+import { describe, expect, test } from 'vitest'
+import { BuildError, isBuildError } from '@lib/errors/BuildError'
+
+describe(`BuildError class is constructible`, () => {
+  test(`Class is properly constructed`, () => {
+    try {
+      throw new BuildError(`Test error`)
+    } catch (err) {
+      if (!isBuildError(err)) throw new Error()
+      // The name property should be set to the error`s name
+      expect(err.name).toBe(`BuildError`)
+
+      // The error should be an instance of its class
+      expect(err).toBeInstanceOf(BuildError)
+
+      // The error should be an instance of builtin Error
+      expect(err).toBeInstanceOf(Error)
+
+      // toString should return the default error message formatting
+      expect(err.toString()).toBe(`BuildError: Test error`)
+
+      // The error should have recorded a stack
+      expect(err.stack).toEqual(expect.any(String))
+    }
+  })
+})
+
+describe(`BuildError has proper inheritance and props set`, () => {
+  test(`Instance`, () => {
+    expect(BuildError).toHaveInProtoChain(Error)
+  })
+
+  test(`Extended`, () => {
+    class SubError extends BuildError {}
+    const sut = new SubError(`test message`)
+    expect(SubError).toHaveInProtoChain(Error, BuildError)
+    //expect(sut).toHaveProperty(`name`, `SubError`)
+    expect(sut).toHaveProperty(`message`, `test message`)
+  })
+
+  test(`Extended with constructor`, () => {
+    class HttpError extends BuildError {
+      constructor(
+        /* eslint-disable-next-line no-unused-vars */
+        public code: number,
+        message?: string
+      ) {
+        super(message)
+      }
+    }
+    const sut = new HttpError(404, `test message`)
+    expect(HttpError).toHaveInProtoChain(Error, BuildError)
+    //expect(sut).toHaveProperty(`name`, `HttpError`)
+    expect(sut).toHaveProperty(`message`, `test message`)
+    expect(sut).toHaveProperty(`code`, 404)
+  })
+
+  test(`Extended with name`, () => {
+    class RenamedError extends BuildError {
+      constructor(name: string, message?: string) {
+        super(message)
+        Object.defineProperty(this, `name`, { value: name })
+      }
+    }
+    const sut = new RenamedError(`test`, `test message`)
+    expect(RenamedError).toHaveInProtoChain(Error, BuildError)
+    expect(sut).toHaveProperty(`name`, `test`)
+    expect(sut).toHaveProperty(`message`, `test message`)
+  })
+})
+
+describe(`BuildError construction works with new`, () => {
+  test(`Basic properties`, () => {
+    const sut = new BuildError(`test message`)
+    expect(sut).toHaveProperty(`name`, `BuildError`)
+    expect(sut).toHaveProperty(`message`, `test message`)
+  })
+
+  test(`Without message`, () => {
+    const sut = new BuildError()
+    expect(sut).toHaveProperty(`name`, `BuildError`)
+    expect(sut).toHaveProperty(`message`, ``)
+  })
+
+  test(`With build-specific properties`, () => {
+    const sut = new BuildError(`test message`, {
+      phase: 'compilation',
+      tool: 'astro',
+      exitCode: 1,
+      filePath: '/src/test.ts',
+      lineNumber: 10,
+      columnNumber: 5
+    })
+    expect(sut).toHaveProperty(`name`, `BuildError`)
+    expect(sut).toHaveProperty(`message`, `test message`)
+    expect(sut.phase).toBe('compilation')
+    expect(sut.tool).toBe('astro')
+    expect(sut.exitCode).toBe(1)
+    expect(sut.filePath).toBe('/src/test.ts')
+    expect(sut.lineNumber).toBe(10)
+    expect(sut.columnNumber).toBe(5)
+  })
+})
+
+describe(`toString behavior in logging`, () => {
+  test(`Outputs error with message when coerced to string`, () => {
+    expect(`${new BuildError(`Hello`)}`).toMatch(`BuildError: Hello`)
+  })
+})
+
+describe(`toJSON behavior overridden`, () => {
+  test(`Outputs structured JSON error with toJSON`, () => {
+    const sut = new BuildError(`test message`)
+    expect(sut.toJSON()).toEqual(
+      expect.objectContaining({
+        error: expect.objectContaining({
+          message: expect.any(String),
+          name: expect.any(String),
+          stack: expect.any(String),
+        }),
+      })
+    )
+  })
+})
+
+describe(`Static factory methods`, () => {
+  test(`compilation creates error with compilation phase`, () => {
+    const sut = BuildError.compilation(
+      `TypeScript compilation failed`,
+      '/src/component.ts',
+      15,
+      5
+    )
+    expect(sut.message).toBe('TypeScript compilation failed')
+    expect(sut.phase).toBe('compilation')
+    expect(sut.filePath).toBe('/src/component.ts')
+    expect(sut.lineNumber).toBe(15)
+    expect(sut.columnNumber).toBe(5)
+  })
+
+  test(`fileOperation creates error with file-operation phase`, () => {
+    const sut = BuildError.fileOperation(
+      `Could not read config file`,
+      '/astro.config.ts',
+      'read'
+    )
+    expect(sut.message).toBe('Could not read config file')
+    expect(sut.phase).toBe('file-operation')
+    expect(sut.filePath).toBe('/astro.config.ts')
+  })
+
+  test(`bundling creates error with bundling phase`, () => {
+    const sut = BuildError.bundling(
+      `Bundling failed`,
+      'vite',
+      1
+    )
+    expect(sut.message).toBe('Bundling failed')
+    expect(sut.phase).toBe('bundling')
+    expect(sut.tool).toBe('vite')
+    expect(sut.exitCode).toBe(1)
+  })
+})