refactor: replace hasRequiredEventFields with isValidEventPayload for payload validation

Author: Dobrunia

src/index.ts

@@ -14,30 +14,11 @@ import type {
 } from '@hawk.so/types';
 import EventPayload from './modules/event.js';
 import { BreadcrumbManager, type BreadcrumbInput, type BreadcrumbHint } from './modules/breadcrumbs.js';
+import { isValidEventPayload } from './modules/validate-event.js';
 import type { AxiosResponse } from 'axios';
 import axios from 'axios';
 import { VERSION } from './version.js';
 
-/**
- * Checks if value is a plain object (not array, Date, etc.)
- */
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return Object.prototype.toString.call(v) === '[object Object]';
-}
-
-/**
- * Minimal required fields check:
- * - payload must be a plain object
- * - payload.title must be a non-empty string
- */
-function hasRequiredEventFields(v: unknown): v is { title: string } {
-  if (!isPlainObject(v)) {
-    return false;
-  }
-
-  return typeof v.title === 'string' && v.title.trim() !== '';
-}
-
 /**
  * Class for throwing errors inside unhandledRejection processor
  */
@@ -290,31 +271,20 @@ class Catcher {
       }
 
       /**
-       * If user returned nothing — keep original payload
+       * If user returned a value — use it; if undefined (no return / in-place mutation) — keep payload reference
        */
-      if (result !== undefined) {
-        /**
-         * Accept only payloads that still have required fields (minimal check)
-         */
-        if (hasRequiredEventFields(result)) {
-          payload = result as EventData<NodeJSAddons>;
-        } else {
-          console.warn(
-            `[Hawk] beforeSend returned invalid payload. ` +
-            `Keeping original payload. Received: ${Object.prototype.toString.call(result)}`
-          );
-        }
-      }
+      const candidate = result ?? payload;
 
-      /**
-       * Final safety check:
-       * protects from in-place mutation of `payload` when beforeSend returns undefined
-       */
-      if (!hasRequiredEventFields(payload)) {
-        console.warn('[Hawk] payload corrupted after beforeSend, event dropped');
+      if (!isValidEventPayload(candidate)) {
+        console.warn(
+          '[Hawk] beforeSend produced invalid payload (missing required fields), event dropped. '
+          + `Received: ${Object.prototype.toString.call(candidate)}`
+        );
 
         return;
       }
+
+      payload = candidate;
     }
 
     void this.sendErrorFormatted({

src/modules/validate-event.ts

@@ -0,0 +1,34 @@
+import type { EventData, NodeJSAddons } from '@hawk.so/types';
+
+/**
+ * Checks if value is a plain object (not array, Date, etc.)
+ *
+ * @param v - value to check
+ */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return Object.prototype.toString.call(v) === '[object Object]';
+}
+
+/**
+ * Runtime check for required EventData fields.
+ * Per @hawk.so/types EventData, `title` is the only non-optional field.
+ * Additionally validates `backtrace` shape if present (must be an array).
+ *
+ * @param v - value to validate
+ */
+// eslint-disable-next-line jsdoc/require-jsdoc -- type guard documented above
+export function isValidEventPayload(v: unknown): v is EventData<NodeJSAddons> {
+  if (!isPlainObject(v)) {
+    return false;
+  }
+
+  if (typeof v.title !== 'string' || v.title.trim() === '') {
+    return false;
+  }
+
+  if (v.backtrace !== undefined && !Array.isArray(v.backtrace)) {
+    return false;
+  }
+
+  return true;
+}