refactor(core): Extract shared modules and utilities

Reversean · Reversean · commit 005f3e165f4c · 2026-03-05T12:07:55.000+03:00
diff --git a/packages/core/src/errors.ts b/packages/core/src/errors.ts
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -2,3 +2,10 @@ export type { HawkStorage } from './storages/hawk-storage';
 export { HawkUserManager } from './users/hawk-user-manager';
 export type { Logger, LogType } from './logger/logger';
 export { isLoggerSet, setLogger, resetLogger, log } from './logger/logger';
+export { Sanitizer } from './modules/sanitizer';
+export { StackParser } from './modules/stack-parser';
+export { buildElementSelector } from './utils/selector';
+export type { Transport } from './transports/transport';
+export { EventRejectedError } from './errors';
+export { isErrorProcessed, markErrorAsProcessed } from './utils/event';
+export { isPlainObject, validateUser, validateContext, isValidEventPayload, isValidBreadcrumb } from './utils/validation';
diff --git a/packages/core/src/modules/fetch-timer.ts b/packages/core/src/modules/fetch-timer.ts
diff --git a/packages/core/src/modules/sanitizer.ts b/packages/core/src/modules/sanitizer.ts
@@ -1,12 +1,14 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { isPlainObject } from '../utils/validation';
+
 /**
  * This class provides methods for preparing data to sending to Hawk
  * - trim long strings
  * - represent html elements like <div ...> as "<div>" instead of "{}"
  * - represent big objects as "<big object>"
  * - represent class as <class SomeClass> or <instance of SomeClass>
  */
-export default class Sanitizer {
+export class Sanitizer {
   /**
    * Maximum string length
    */
@@ -34,7 +36,7 @@ export default class Sanitizer {
    * @param target - variable to check
    */
   public static isObject(target: any): boolean {
-    return Sanitizer.typeOf(target) === 'object';
+    return isPlainObject(target);
   }
 
   /**
diff --git a/packages/core/src/modules/stack-parser.ts b/packages/core/src/modules/stack-parser.ts
@@ -1,12 +1,12 @@
 import type { StackFrame } from 'error-stack-parser';
 import ErrorStackParser from 'error-stack-parser';
 import type { BacktraceFrame, SourceCodeLine } from '@hawk.so/types';
-import fetchTimer from './fetchTimer';
+import fetchTimer from './fetch-timer';
 
 /**
  * This module prepares parsed backtrace
  */
-export default class StackParser {
+export class StackParser {
   /**
    * Prevents loading one file several times
    * name -> content
@@ -48,7 +48,7 @@ export default class StackParser {
     try {
       if (!frame.fileName) {
         return null;
-      };
+      }
 
       if (!this.isValidUrl(frame.fileName)) {
         return null;
@@ -118,9 +118,9 @@ export default class StackParser {
   /**
    * Downloads source file
    *
-   * @param {string} fileName - name of file to download
+   * @param fileName - name of file to download
    */
-  private async loadSourceFile(fileName): Promise<string | null> {
+  private async loadSourceFile(fileName: string): Promise<string | null> {
     if (this.sourceFilesCache[fileName] !== undefined) {
       return this.sourceFilesCache[fileName];
     }
diff --git a/packages/core/src/transports/transport.ts b/packages/core/src/transports/transport.ts
@@ -0,0 +1,9 @@
+import type { CatcherMessage } from '@hawk.so/types';
+import { CatcherMessageType } from '@hawk.so/types';
+
+/**
+ * Transport interface — anything that can send a CatcherMessage
+ */
+export interface Transport<T extends CatcherMessageType> {
+  send(message: CatcherMessage<T>): Promise<void>;
+}
diff --git a/packages/core/src/utils/event.ts b/packages/core/src/utils/event.ts
@@ -1,12 +1,12 @@
-import { log } from '@hawk.so/core';
+import { log } from '../logger/logger';
 
 /**
  * Symbol to mark error as processed by Hawk
  */
 const errorSentShadowProperty = Symbol('__hawk_processed__');
 
 /**
- * Check if the error has alrady been sent to Hawk.
+ * Check if the error has already been sent to Hawk.
  *
  * Motivation:
  * Some integrations may catch errors on their own side and then normally re-throw them down.
@@ -20,7 +20,7 @@ export function isErrorProcessed(error: unknown): boolean {
     return false;
   }
 
-  return error[errorSentShadowProperty] === true;
+  return (error as Record<symbol, unknown>)[errorSentShadowProperty] === true;
 }
 
 /**
@@ -35,7 +35,7 @@ export function markErrorAsProcessed(error: unknown): void {
     }
 
     Object.defineProperty(error, errorSentShadowProperty, {
-      enumerable: false, // Prevent from beight collected by Hawk
+      enumerable: false,  // Prevent from being collected by Hawk
       value: true,
       writable: true,
       configurable: true,
diff --git a/packages/core/src/utils/selector.ts b/packages/core/src/utils/selector.ts
diff --git a/packages/core/src/utils/validation.ts b/packages/core/src/utils/validation.ts
@@ -1,14 +1,20 @@
-import { log } from '@hawk.so/core';
-import type { AffectedUser, Breadcrumb, EventContext, EventData, JavaScriptAddons } from '@hawk.so/types';
-import Sanitizer from '../modules/sanitizer';
+import { log } from '../logger/logger';
+import type { AffectedUser, Breadcrumb, EventAddons, EventContext, EventData } from '@hawk.so/types';
+
+/**
+ * Returns true if value is a plain object (not null, array, Date, Map, etc.)
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Object.prototype.toString.call(value) === '[object Object]';
+}
 
 /**
  * Validates user data - basic security checks
  *
  * @param user - user data to validate
  */
 export function validateUser(user: AffectedUser): boolean {
-  if (!user || !Sanitizer.isObject(user)) {
+  if (!user || !isPlainObject(user)) {
     log('validateUser: User must be an object', 'warn');
 
     return false;
@@ -30,7 +36,7 @@ export function validateUser(user: AffectedUser): boolean {
  * @param context - context data to validate
  */
 export function validateContext(context: EventContext | undefined): boolean {
-  if (context && !Sanitizer.isObject(context)) {
+  if (context && !isPlainObject(context)) {
     log('validateContext: Context must be an object', 'warn');
 
     return false;
@@ -39,23 +45,14 @@ export function validateContext(context: EventContext | undefined): boolean {
   return true;
 }
 
-/**
- * Checks if value is a plain object (not array, Date, etc.)
- *
- * @param value - value to check
- */
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return Object.prototype.toString.call(value) === '[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).
+ * Additionally, validates `backtrace` shape if present (must be an array).
  *
  * @param payload - value to validate
  */
-export function isValidEventPayload(payload: unknown): payload is EventData<JavaScriptAddons> {
+export function isValidEventPayload(payload: unknown): payload is EventData<EventAddons> {
   if (!isPlainObject(payload)) {
     return false;
   }
@@ -64,11 +61,7 @@ export function isValidEventPayload(payload: unknown): payload is EventData<Java
     return false;
   }
 
-  if (payload.backtrace !== undefined && !Array.isArray(payload.backtrace)) {
-    return false;
-  }
-
-  return true;
+  return !(payload.backtrace !== undefined && !Array.isArray(payload.backtrace));
 }
 
 /**
@@ -86,9 +79,5 @@ export function isValidBreadcrumb(breadcrumb: unknown): breadcrumb is Breadcrumb
     return false;
   }
 
-  if (breadcrumb.timestamp !== undefined && typeof breadcrumb.timestamp !== 'number') {
-    return false;
-  }
-
-  return true;
+  return !(breadcrumb.timestamp !== undefined && typeof breadcrumb.timestamp !== 'number');
 }
diff --git a/packages/core/tests/utils/validation.test.ts b/packages/core/tests/utils/validation.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { validateUser, validateContext, isValidEventPayload, isValidBreadcrumb } from '../../src/utils/validation';
+import { validateUser, validateContext, isValidEventPayload, isValidBreadcrumb } from '@hawk.so/core';
 
 // Suppress log output produced by log() calls inside validation failures.
 vi.mock('@hawk.so/core', () => ({ log: vi.fn(), isLoggerSet: vi.fn(() => true), setLogger: vi.fn() }));
diff --git a/packages/javascript/src/addons/breadcrumbs.ts b/packages/javascript/src/addons/breadcrumbs.ts
@@ -2,10 +2,7 @@
  * @file Breadcrumbs module - captures chronological trail of events before an error
  */
 import type { Breadcrumb, BreadcrumbLevel, BreadcrumbType, Json, JsonNode } from '@hawk.so/types';
-import Sanitizer from '../modules/sanitizer';
-import { buildElementSelector } from '../utils/selector';
-import { log } from '@hawk.so/core';
-import { isValidBreadcrumb } from '../utils/validation';
+import { Sanitizer, buildElementSelector, log, isValidBreadcrumb } from '@hawk.so/core';
 
 /**
  * Default maximum number of breadcrumbs to store
diff --git a/packages/javascript/src/addons/consoleCatcher.ts b/packages/javascript/src/addons/consoleCatcher.ts
@@ -2,7 +2,7 @@
  * @file Module for intercepting console logs with stack trace capture
  */
 import type { ConsoleLogEvent } from '@hawk.so/types';
-import Sanitizer from '../modules/sanitizer';
+import { Sanitizer } from '@hawk.so/core';
 
 /**
  * Maximum number of console logs to store
diff --git a/packages/javascript/src/catcher.ts b/packages/javascript/src/catcher.ts
@@ -1,24 +1,33 @@
 import Socket from './modules/socket';
-import Sanitizer from './modules/sanitizer';
-import StackParser from './modules/stackParser';
-import type { CatcherMessage, HawkInitialSettings, BreadcrumbsAPI, Transport } from './types';
+import type { BreadcrumbsAPI, CatcherMessage, HawkInitialSettings, HawkJavaScriptEvent, Transport } from './types';
 import { VueIntegration } from './integrations/vue';
 import { id } from './utils/id';
 import type {
   AffectedUser,
+  DecodedIntegrationToken,
+  EncodedIntegrationToken,
   EventContext,
   JavaScriptAddons,
-  VueIntegrationAddons,
-  Json, EncodedIntegrationToken, DecodedIntegrationToken
+  Json,
+  VueIntegrationAddons
 } from '@hawk.so/types';
-import type { JavaScriptCatcherIntegrations } from './types/integrations';
-import { EventRejectedError } from './errors';
-import type { HawkJavaScriptEvent } from './types';
-import { isErrorProcessed, markErrorAsProcessed } from './utils/event';
+import type { JavaScriptCatcherIntegrations } from '@/types';
 import { ConsoleCatcher } from './addons/consoleCatcher';
 import { BreadcrumbManager } from './addons/breadcrumbs';
-import { validateUser, validateContext, isValidEventPayload } from './utils/validation';
-import { HawkUserManager, setLogger, isLoggerSet, log } from '@hawk.so/core';
+import {
+  EventRejectedError,
+  HawkUserManager,
+  isErrorProcessed,
+  isLoggerSet,
+  isValidEventPayload,
+  log,
+  markErrorAsProcessed,
+  Sanitizer,
+  setLogger,
+  StackParser,
+  validateContext,
+  validateUser
+} from '@hawk.so/core';
 import { HawkLocalStorage } from './storages/hawk-local-storage';
 import { createBrowserLogger } from './logger/logger';
 
@@ -54,7 +63,7 @@ export default class Catcher {
   /**
    * Catcher Type
    */
-  private readonly type: string = 'errors/javascript';
+  private readonly type = 'errors/javascript' as const;
 
   /**
    * User project's Integration Token
@@ -504,7 +513,7 @@ export default class Catcher {
      * and reject() provided with text reason instead of Error()
      */
     if (notAnError) {
-      return null;
+      return undefined;
     }
 
     return (error as Error).name;
@@ -514,7 +523,7 @@ export default class Catcher {
    * Release version
    */
   private getRelease(): HawkJavaScriptEvent['release'] {
-    return this.release !== undefined ? String(this.release) : null;
+    return this.release !== undefined ? String(this.release) : undefined;
   }
 
   /**
@@ -573,7 +582,7 @@ export default class Catcher {
   private getBreadcrumbsForEvent(): HawkJavaScriptEvent['breadcrumbs'] {
     const breadcrumbs = this.breadcrumbManager?.getBreadcrumbs();
 
-    return breadcrumbs && breadcrumbs.length > 0 ? breadcrumbs : null;
+    return breadcrumbs && breadcrumbs.length > 0 ? breadcrumbs : undefined;
   }
 
   /**
@@ -613,15 +622,15 @@ export default class Catcher {
      * and reject() provided with text reason instead of Error()
      */
     if (notAnError) {
-      return null;
+      return undefined;
     }
 
     try {
       return await this.stackParser.parse(error as Error);
     } catch (e) {
       log('Can not parse stack:', 'warn', e);
 
-      return null;
+      return undefined;
     }
   }
 
@@ -688,6 +697,6 @@ export default class Catcher {
    * @param integrationAddons - extra addons
    */
   private appendIntegrationAddons(errorFormatted: CatcherMessage, integrationAddons: JavaScriptCatcherIntegrations): void {
-    Object.assign(errorFormatted.payload.addons, integrationAddons);
+    Object.assign(errorFormatted.payload.addons!, integrationAddons);
   }
 }
diff --git a/packages/javascript/src/modules/socket.ts b/packages/javascript/src/modules/socket.ts
@@ -1,6 +1,5 @@
 import { log } from '@hawk.so/core';
-import type { CatcherMessage } from '@/types';
-import type { Transport } from '../types/transport';
+import type { CatcherMessage, Transport } from '@/types';
 
 /**
  * Custom WebSocket wrapper class
diff --git a/packages/javascript/src/types/catcher-message.ts b/packages/javascript/src/types/catcher-message.ts
@@ -1,21 +1,6 @@
-import type { HawkJavaScriptEvent } from './event';
+import type { CatcherMessage as HawkCatcherMessage } from '@hawk.so/types';
 
 /**
  * Structure describing a message sending by Catcher
  */
-export interface CatcherMessage {
-  /**
-   * User project's Integration Token
-   */
-  token: string;
-
-  /**
-   * Hawk Catcher name
-   */
-  catcherType: string;
-
-  /**
-   * All information about the event
-   */
-  payload: HawkJavaScriptEvent;
-}
+export type CatcherMessage = HawkCatcherMessage<'errors/javascript'>;
diff --git a/packages/javascript/src/types/event.ts b/packages/javascript/src/types/event.ts
diff --git a/packages/javascript/src/types/hawk-initial-settings.ts b/packages/javascript/src/types/hawk-initial-settings.ts
diff --git a/packages/javascript/src/types/transport.ts b/packages/javascript/src/types/transport.ts
