refactor(javascript): normalize browser error event extraction

Author: FeironoX5

packages/javascript/src/addons/consoleCatcher.ts

@@ -3,7 +3,7 @@
  */
 import type { ConsoleLogEvent } from '@hawk.so/types';
 import Sanitizer from '../modules/sanitizer';
-import { stringifyRejectionReason } from '../utils/event';
+import { getErrorFromErrorEvent } from '../utils/error';
 
 /**
  * Maximum number of console logs to store
@@ -196,13 +196,15 @@ export class ConsoleCatcher {
    * @param event - The error event or promise rejection event to convert
    */
   private createConsoleEventFromError(event: ErrorEvent | PromiseRejectionEvent): ConsoleLogEvent {
+    const capturedError = getErrorFromErrorEvent(event);
+
     if (event instanceof ErrorEvent) {
       return {
         method: 'error',
         timestamp: new Date(),
-        type: event.error?.name || 'Error',
-        message: event.error?.message || event.message,
-        stack: event.error?.stack || '',
+        type: capturedError.type || 'Error',
+        message: capturedError.title,
+        stack: (capturedError.rawError as Error)?.stack || '',
         fileLine: event.filename
           ? `${event.filename}:${event.lineno}:${event.colno}`
           : '',
@@ -213,8 +215,8 @@ export class ConsoleCatcher {
       method: 'error',
       timestamp: new Date(),
       type: 'UnhandledRejection',
-      message: stringifyRejectionReason(event.reason),
-      stack: event.reason?.stack || '',
+      message: capturedError.title,
+      stack: (capturedError.rawError as Error)?.stack || '',
       fileLine: '',
     };
   }

packages/javascript/src/catcher.ts

@@ -10,12 +10,13 @@ import type {
   EventContext,
   JavaScriptAddons,
   Json,
-  VueIntegrationAddons
+  VueIntegrationAddons,
 } from '@hawk.so/types';
 import type { JavaScriptCatcherIntegrations } from './types/integrations';
 import { EventRejectedError } from './errors';
 import { isErrorProcessed, markErrorAsProcessed } from './utils/event';
-import { getErrorFromErrorEvent } from './utils/error';
+import type { CapturedError } from './utils/error';
+import { fillCapturedError, getErrorFromErrorEvent } from './utils/error';
 import { BrowserRandomGenerator } from './utils/random';
 import { ConsoleCatcher } from './addons/consoleCatcher';
 import { BreadcrumbManager } from './addons/breadcrumbs';
@@ -222,7 +223,7 @@ export default class Catcher {
    * @param [context] - any additional data to send
    */
   public send(message: Error | string, context?: EventContext): void {
-    void this.formatAndSend(message, undefined, context);
+    void this.formatAndSend(fillCapturedError(message), undefined, context);
   }
 
   /**
@@ -234,7 +235,7 @@ export default class Catcher {
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public captureError(error: Error | string, addons?: JavaScriptCatcherIntegrations): void {
-    void this.formatAndSend(error, addons);
+    void this.formatAndSend(fillCapturedError(error), addons);
   }
 
   /**
@@ -247,7 +248,7 @@ export default class Catcher {
     this.vue = new VueIntegration(
       vue,
       (error: Error, addons: VueIntegrationAddons) => {
-        void this.formatAndSend(error, {
+        void this.formatAndSend(fillCapturedError(error), {
           vue: addons,
         });
       },
@@ -345,21 +346,21 @@ export default class Catcher {
    * @param context - any additional data passed by user
    */
   private async formatAndSend(
-    error: Error | string,
+    error: CapturedError,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     integrationAddons?: JavaScriptCatcherIntegrations,
     context?: EventContext
   ): Promise<void> {
     try {
-      const isAlreadySentError = isErrorProcessed(error);
+      const isAlreadySentError = isErrorProcessed(error.rawError);
 
       if (isAlreadySentError) {
         /**
          * @todo add debug build and log this case
          */
         return;
       } else {
-        markErrorAsProcessed(error);
+        markErrorAsProcessed(error.rawError);
       }
 
       const errorFormatted = await this.prepareErrorFormatted(error, context);
@@ -402,16 +403,17 @@ export default class Catcher {
    * @param error - error to format
    * @param context - any additional data passed by user
    */
-  private async prepareErrorFormatted(error: Error | string, context?: EventContext): Promise<CatcherMessage> {
+  private async prepareErrorFormatted(error: CapturedError, context?: EventContext): Promise<CatcherMessage> {
+    const { title, type, rawError } = error;
     let payload: HawkJavaScriptEvent = {
-      title: this.getTitle(error),
-      type: this.getType(error),
+      title,
+      type,
       release: this.getRelease(),
       breadcrumbs: this.getBreadcrumbsForEvent(),
       context: this.getContext(context),
       user: this.getUser(),
-      addons: this.getAddons(error),
-      backtrace: await this.getBacktrace(error),
+      addons: this.getAddons(rawError),
+      backtrace: await this.getBacktrace(rawError),
       catcherVersion: this.version,
     };
 
@@ -463,44 +465,6 @@ export default class Catcher {
     };
   }
 
-  /**
-   * Return event title
-   *
-   * @param error - event from which to get the title
-   */
-  private getTitle(error: Error | string): string {
-    const notAnError = !(error instanceof Error);
-
-    /**
-     * Case when error is 'reason' of PromiseRejectionEvent
-     * and reject() provided with text reason instead of Error()
-     */
-    if (notAnError) {
-      return error.toString() as string;
-    }
-
-    return (error as Error).message;
-  }
-
-  /**
-   * Return event type: TypeError, ReferenceError etc
-   *
-   * @param error - caught error
-   */
-  private getType(error: Error | string): HawkJavaScriptEvent['type'] {
-    const notAnError = !(error instanceof Error);
-
-    /**
-     * Case when error is 'reason' of PromiseRejectionEvent
-     * and reject() provided with text reason instead of Error()
-     */
-    if (notAnError) {
-      return null;
-    }
-
-    return (error as Error).name;
-  }
-
   /**
    * Release version
    */
@@ -590,7 +554,7 @@ export default class Catcher {
    *
    * @param error - event from which to get backtrace
    */
-  private async getBacktrace(error: Error | string): Promise<HawkJavaScriptEvent['backtrace']> {
+  private async getBacktrace(error: unknown): Promise<HawkJavaScriptEvent['backtrace']> {
     const notAnError = !(error instanceof Error);
 
     /**
@@ -613,9 +577,9 @@ export default class Catcher {
   /**
    * Return some details
    *
-   * @param {Error|string} error — caught error
+   * @param {Error} error — caught error
    */
-  private getAddons(error: Error | string): HawkJavaScriptEvent['addons'] {
+  private getAddons(error: unknown): HawkJavaScriptEvent['addons'] {
     const { innerWidth, innerHeight } = window;
     const userAgent = window.navigator.userAgent;
     const location = window.location.href;
@@ -649,9 +613,9 @@ export default class Catcher {
   /**
    * Compose raw data object
    *
-   * @param {Error|string} error — caught error
+   * @param {Error} error — caught error
    */
-  private getRawData(error: Error | string): Json | undefined {
+  private getRawData(error: unknown): Json | undefined {
     if (!(error instanceof Error)) {
       return;
     }
@@ -672,7 +636,10 @@ export default class Catcher {
    * @param errorFormatted - Hawk event prepared for sending
    * @param integrationAddons - extra addons
    */
-  private appendIntegrationAddons(errorFormatted: CatcherMessage, integrationAddons: JavaScriptCatcherIntegrations): void {
+  private appendIntegrationAddons(
+    errorFormatted: CatcherMessage,
+    integrationAddons: JavaScriptCatcherIntegrations
+  ): void {
     Object.assign(errorFormatted.payload.addons, integrationAddons);
   }
 }

packages/javascript/src/utils/error.ts

@@ -1,55 +1,105 @@
 import Sanitizer from '../modules/sanitizer';
 
 /**
- * Extracts and normalizes error from ErrorEvent or PromiseRejectionEvent
+ * Represents a captured error in a normalized form.
  *
- * @param event - The error or promise rejection event
+ * Motivation:
+ * - `Error | string` is unclear and hard to work with.
+ * - Fields can be filled from an event or from the error itself.
+ */
+export type CapturedError = {
+  /** Human-readable error message used as a title in the dashboard */
+  title: string;
+  /** Error type (e.g. 'TypeError', 'NetworkError'), or null if unknown */
+  type: string | null;
+  /** The original (unsanitized) value — use for instanceof checks and backtrace parsing only */
+  rawError: unknown;
+};
+
+/**
+ * Extracts a human-readable title from an unknown sanitized error.
+ * Prefers `.message` on objects, falls back to the value itself for strings,
+ * and serializes everything else.
+ *
+ * @param safeError - Sanitized error value (any shape)
+ * @returns A non-empty string title, or undefined if the value is nullish or empty
  */
-export function getErrorFromErrorEvent(event: ErrorEvent | PromiseRejectionEvent): Error | string {
-  /**
-   * Promise rejection reason is recommended to be an Error, but it can be a string:
-   * - Promise.reject(new Error('Reason message')) ——— recommended
-   * - Promise.reject('Reason message')
-   */
-  let error = (event as ErrorEvent).error || (event as PromiseRejectionEvent).reason;
-
-  /**
-   * Case when error triggered in external script
-   * We can't access event error object because of CORS
-   * Event message will be 'Script error.'
-   */
-  if (event instanceof ErrorEvent && error === undefined) {
-    error = (event as ErrorEvent).message;
+function getTitleFromError(safeError: unknown): string | undefined {
+  if (safeError == null) {
+    return undefined;
   }
 
-  /**
-   * Case when error rejected with an object
-   * Using a string instead of wrapping in Error is more natural,
-   * it doesn't fake the backtrace, also prefix added for dashboard readability
-   */
-  if (error instanceof Object && !(error instanceof Error) && event instanceof PromiseRejectionEvent) {
-    // Extra sanitize is needed to handle objects with circular references before JSON.stringify
-    error = `Promise rejected with ${JSON.stringify(Sanitizer.sanitize(error))}`;
+  const message =
+    typeof safeError === 'object' && 'message' in safeError ? (safeError as Error).message : safeError;
+
+  if (typeof message === 'string') {
+    return message || undefined;
   }
 
-  return Sanitizer.sanitize(error);
+  try {
+    return JSON.stringify(message);
+  } catch {
+    // If no JSON global is available, fall back to string conversion
+    return String(message);
+  }
+}
+
+/**
+ * Extracts an error type name from an unknown sanitized error.
+ * Returns `.name` only when it is a non-empty string (e.g. 'TypeError').
+ *
+ * @param safeError - Sanitized error value (any shape)
+ * @returns The error name string, or undefined if absent or empty
+ */
+function getTypeFromError(safeError: unknown): string | undefined {
+  const name = (safeError as Error)?.name;
+
+  return name || undefined;
 }
 
 /**
- * Converts a promise rejection reason to a string message.
+ * Constructs a CapturedError from an unknown error value and optional fallbacks.
  *
- * String(obj) gives "[object Object]" and JSON.stringify("str")
- * adds unwanted quotes.
+ * @param error - Any value thrown or rejected
+ * @param fallbackValues - Fallback values from event if they can't be extracted from the error
+ * @returns A normalized `CapturedError` object
+ */
+export function fillCapturedError(
+  error: unknown,
+  fallbackValues: { title?: string; type?: string } = {}
+): CapturedError {
+  const sanitizedError = Sanitizer.sanitize(error);
+
+  return {
+    title: getTitleFromError(sanitizedError) || fallbackValues.title || '<unknown error>',
+    type: getTypeFromError(sanitizedError) || fallbackValues.type || null,
+    rawError: error,
+  };
+}
+
+/**
+ * Extracts and normalizes error from ErrorEvent or PromiseRejectionEvent.
+ * Handles CORS-restricted errors (where event.error is undefined) by falling back to event.message.
  *
- * @param reason - The rejection reason from PromiseRejectionEvent
+ * @param event - The error or promise rejection event
+ * @returns A normalized CapturedError object
  */
-export function stringifyRejectionReason(reason: unknown): string {
-  if (reason instanceof Error) {
-    return reason.message;
+export function getErrorFromErrorEvent(event: ErrorEvent | PromiseRejectionEvent): CapturedError {
+  if (event.type === 'error') {
+    event = event as ErrorEvent;
+
+    return fillCapturedError(event.error, {
+      title: event.message && `'${event.message}' at ${event.filename || '<unknown file>'}:${event.lineno}:${event.colno}`,
+    });
   }
-  if (typeof reason === 'string') {
-    return reason;
+
+  if (event.type === 'unhandledrejection') {
+    event = event as PromiseRejectionEvent;
+
+    return fillCapturedError(event.reason, {
+      type: 'UnhandledRejection',
+    });
   }
 
-  return JSON.stringify(Sanitizer.sanitize(reason));
+  return fillCapturedError(undefined);
 }

packages/javascript/tests/catcher.global-handlers.test.ts

@@ -80,7 +80,7 @@ describe('Catcher', () => {
       await wait();
 
       expect(sendSpy).toHaveBeenCalledOnce();
-      expect(getLastPayload(sendSpy).title).toBe('Script error.');
+      expect(getLastPayload(sendSpy).title).toBe("'Script error.' at <unknown file>:0:0");
     });
 
     it('should capture unhandled promise rejections', async () => {