refactor(core): Extract shared modules and utilities

- fetchTimer function moved to @hawk.so/core
- Sanitizer moved to @hawk.so/core (except Element handling)
- SanitizerTypeHandler feature added
- browser Element SanitizerTypeHandler added
- StackParser moved to @hawk.so/core
- Transport moved to @hawk.so/core
- event utility functions moved to @hawk.so/core
- selector utility functions moved to @hawk.so/core
- validation utility functions moved to @hawk.so/core
- EventRejectedError moved to @hawk.so/core
- suppress error-logs by StackParser in tests

Author: Reversean

packages/javascript/src/errors.ts packages/core/src/errors.tspackages/javascript/src/errors.ts renamed to packages/core/src/errors.ts

@@ -3,3 +3,11 @@ export type { RandomGenerator } from './utils/random';
 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 type { SanitizerTypeHandler } 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';

packages/core/src/index.ts

@@ -1,4 +1,4 @@
-import { log } from '@hawk.so/core';
+import { log } from '../logger/logger';
 
 /**
  * Sends AJAX request and wait for some time.

…ges/javascript/src/modules/fetchTimer.ts packages/core/src/modules/fetch-timer.tspackages/javascript/src/modules/fetchTimer.ts renamed to packages/core/src/modules/fetch-timer.ts packages/javascript/src/modules/fetchTimer.ts renamed to packages/core/src/modules/fetch-timer.ts

@@ -1,12 +1,32 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { isPlainObject } from '../utils/validation';
+
+/**
+ * Custom type handler for Sanitizer.
+ *
+ * Allows user to register their own formatters from external packages.
+ */
+export interface SanitizerTypeHandler {
+  /**
+   * Checks if this handler should be applied to given value
+   *
+   * @returns `true`
+   */
+  check: (target: any) => boolean;
+
+  /**
+   * Formats the value into a sanitized representation
+   */
+  format: (target: any) => any;
+}
+
 /**
  * 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
    */
@@ -28,13 +48,31 @@ export default class Sanitizer {
    */
   private static readonly maxArrayLength: number = 10;
 
+  /**
+   * Custom type handlers registered via {@link registerHandler}.
+   *
+   * Checked in {@link sanitize} before built-in type checks.
+   */
+  private static readonly customHandlers: SanitizerTypeHandler[] = [];
+
   /**
    * Check if passed variable is an object
    *
    * @param target - variable to check
    */
   public static isObject(target: any): boolean {
-    return Sanitizer.typeOf(target) === 'object';
+    return isPlainObject(target);
+  }
+
+  /**
+   * Register a custom type handler.
+   * Handlers are checked before built-in type checks, in reverse registration order
+   * (last registered = highest priority).
+   *
+   * @param handler - handler to register
+   */
+  public static registerHandler(handler: SanitizerTypeHandler): void {
+    Sanitizer.customHandlers.unshift(handler);
   }
 
   /**
@@ -60,19 +98,21 @@ export default class Sanitizer {
      */
     if (Sanitizer.isArray(data)) {
       return this.sanitizeArray(data, depth + 1, seen);
+    }
 
-      /**
-       * If value is an Element, format it as string with outer HTML
-       * HTMLDivElement -> "<div ...></div>"
-       */
-    } else if (Sanitizer.isElement(data)) {
-      return Sanitizer.formatElement(data);
+    // Check additional handlers provided by env-specific modules or users
+    // to sanitize some additional cases (e.g. specific object types)
+    for (const handler of Sanitizer.customHandlers) {
+      if (handler.check(data)) {
+        return handler.format(data);
+      }
+    }
 
-      /**
-       * If values is a not-constructed class, it will be formatted as "<class SomeClass>"
-       * class Editor {...} -> <class Editor>
-       */
-    } else if (Sanitizer.isClassPrototype(data)) {
+    /**
+     * If values is a not-constructed class, it will be formatted as "<class SomeClass>"
+     * class Editor {...} -> <class Editor>
+     */
+    if (Sanitizer.isClassPrototype(data)) {
       return Sanitizer.formatClassPrototype(data);
 
       /**
@@ -131,7 +171,9 @@ export default class Sanitizer {
    * @param depth - current depth of recursion
    * @param seen - Set of already seen objects to prevent circular references
    */
-  private static sanitizeObject(data: { [key: string]: any }, depth: number, seen: WeakSet<object>): Record<string, any> | '<deep object>' | '<big object>' {
+  private static sanitizeObject(data: {
+    [key: string]: any
+  }, depth: number, seen: WeakSet<object>): Record<string, any> | '<deep object>' | '<big object>' {
     /**
      * If the maximum depth is reached, return a placeholder
      */
@@ -205,24 +247,6 @@ export default class Sanitizer {
     return typeof target === 'string';
   }
 
-  /**
-   * Return string representation of the object type
-   *
-   * @param object - object to get type
-   */
-  private static typeOf(object: any): string {
-    return Object.prototype.toString.call(object).match(/\s([a-zA-Z]+)/)[1].toLowerCase();
-  }
-
-  /**
-   * Check if passed variable is an HTML Element
-   *
-   * @param target - variable to check
-   */
-  private static isElement(target: any): boolean {
-    return target instanceof Element;
-  }
-
   /**
    * Return name of a passed class
    *
@@ -248,31 +272,12 @@ export default class Sanitizer {
    */
   private static trimString(target: string): string {
     if (target.length > Sanitizer.maxStringLen) {
-      return target.substr(0, Sanitizer.maxStringLen) + '…';
+      return target.substring(0, Sanitizer.maxStringLen) + '…';
     }
 
     return target;
   }
 
-  /**
-   * Represent HTML Element as string with it outer-html
-   * HTMLDivElement -> "<div ...></div>"
-   *
-   * @param target - variable to format
-   */
-  private static formatElement(target: Element): string {
-    /**
-     * Also, remove inner HTML because it can be BIG
-     */
-    const innerHTML = target.innerHTML;
-
-    if (innerHTML) {
-      return target.outerHTML.replace(target.innerHTML, '…');
-    }
-
-    return target.outerHTML;
-  }
-
   /**
    * Represent not-constructed class as "<class SomeClass>"
    *

…ages/javascript/src/modules/sanitizer.ts packages/core/src/modules/sanitizer.tspackages/javascript/src/modules/sanitizer.ts renamed to packages/core/src/modules/sanitizer.ts packages/javascript/src/modules/sanitizer.ts renamed to packages/core/src/modules/sanitizer.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];
     }

…es/javascript/src/modules/stackParser.ts packages/core/src/modules/stack-parser.tspackages/javascript/src/modules/stackParser.ts renamed to packages/core/src/modules/stack-parser.ts packages/javascript/src/modules/stackParser.ts renamed to packages/core/src/modules/stack-parser.ts

@@ -0,0 +1,8 @@
+import type { CatcherMessage, 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>;
+}

packages/core/src/transports/transport.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,

packages/javascript/src/utils/event.ts packages/core/src/utils/event.tspackages/javascript/src/utils/event.ts renamed to packages/core/src/utils/event.ts

@@ -1,14 +1,13 @@
-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';
 
 /**
  * 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 +29,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;
@@ -40,22 +39,23 @@ export function validateContext(context: EventContext | undefined): boolean {
 }
 
 /**
- * Checks if value is a plain object (not array, Date, etc.)
+ * Checks if value is a plain object (not null, array, Date, Map, etc.)
  *
  * @param value - value to check
+ * @returns `true` if value is a plain object, otherwise `false`
  */
-function isPlainObject(value: unknown): value is Record<string, unknown> {
+export 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 +64,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 +82,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');
 }