refactor(core): Extract sanitizer module

- Sanitizer moved to @hawk.so/core (except Element handling)
- SanitizerTypeHandler feature added
- browser Element SanitizerTypeHandler added
- type-guards utils moved from sanitizer
- type-guards utils covered with tests

Author: Reversean

packages/core/src/index.ts

@@ -4,4 +4,5 @@ export { HawkUserManager } from './users/hawk-user-manager';
 export type { Logger, LogType } from './logger/logger';
 export { isLoggerSet, setLogger, resetLogger, log } from './logger/logger';
 export { validateUser, validateContext, isValidEventPayload, isValidBreadcrumb } from './utils/validation';
-export { isPlainObject } from './utils/type-guards';
+export { isPlainObject, isArray, isClassPrototype, isClassInstance, isString } from './utils/type-guards';
+export { Sanitizer } from './modules/sanitizer';

…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,32 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { isArray, isClassInstance, isClassPrototype, isPlainObject, isString } from '../utils/type-guards';
+
+/**
+ * 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
    */
@@ -29,12 +49,21 @@ export default class Sanitizer {
   private static readonly maxArrayLength: number = 10;
 
   /**
-   * Check if passed variable is an object
+   * Custom type handlers registered via {@link registerHandler}.
    *
-   * @param target - variable to check
+   * Checked in {@link sanitize} before built-in type checks.
    */
-  public static isObject(target: any): boolean {
-    return Sanitizer.typeOf(target) === 'object';
+  private static readonly customHandlers: SanitizerTypeHandler[] = [];
+
+  /**
+   * 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);
   }
 
   /**
@@ -45,59 +74,39 @@ export default class Sanitizer {
    * @param seen - Set of already seen objects to prevent circular references
    */
   public static sanitize(data: any, depth = 0, seen = new WeakSet<object>()): any {
-    /**
-     * Check for circular references on objects and arrays
-     */
+    // Check for circular references on objects and arrays
     if (data !== null && typeof data === 'object') {
       if (seen.has(data)) {
         return '<circular>';
       }
       seen.add(data);
     }
 
-    /**
-     * If value is an Array, apply sanitizing for each element
-     */
-    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);
-
-      /**
-       * If values is a not-constructed class, it will be formatted as "<class SomeClass>"
-       * class Editor {...} -> <class Editor>
-       */
-    } else if (Sanitizer.isClassPrototype(data)) {
-      return Sanitizer.formatClassPrototype(data);
-
-      /**
-       * If values is a some class instance, it will be formatted as "<instance of SomeClass>"
-       * new Editor() -> <instance of Editor>
-       */
-    } else if (Sanitizer.isClassInstance(data)) {
-      return Sanitizer.formatClassInstance(data);
-
-      /**
-       * If values is an object, do recursive call
-       */
-    } else if (Sanitizer.isObject(data)) {
-      return Sanitizer.sanitizeObject(data, depth + 1, seen);
-
-      /**
-       * If values is a string, trim it for max-length
-       */
-    } else if (Sanitizer.isString(data)) {
-      return Sanitizer.trimString(data);
+
+    // If value is an Array, apply sanitizing for each element
+    if (isArray(data)) return this.sanitizeArray(data, depth + 1, seen);
+
+    // 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 number, boolean and other primitive, leave as is
-     */
+    // If values is a not-constructed class, it will be formatted as "<class SomeClass>"
+    // class Editor {...} -> <class Editor>
+    if (isClassPrototype(data)) return Sanitizer.formatClassPrototype(data);
+
+    // If values is a some class instance, it will be formatted as "<instance of SomeClass>"
+    // new Editor() -> <instance of Editor>
+    if (isClassInstance(data)) return Sanitizer.formatClassInstance(data);
+
+    // If values is an object, do recursive call
+    if (isPlainObject(data)) return Sanitizer.sanitizeObject(data, depth + 1, seen);
+
+    // If values is a string, trim it for max-length
+    if (isString(data)) return Sanitizer.trimString(data);
+
+    // If values is a number, boolean and other primitive, leave as is
     return data;
   }
 
@@ -131,7 +140,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
      */
@@ -157,72 +168,6 @@ export default class Sanitizer {
     return result;
   }
 
-  /**
-   * Check if passed variable is an array
-   *
-   * @param target - variable to check
-   */
-  private static isArray(target: any): boolean {
-    return Array.isArray(target);
-  }
-
-  /**
-   * Check if passed variable is a not-constructed class
-   *
-   * @param target - variable to check
-   */
-  private static isClassPrototype(target: any): boolean {
-    if (!target || !target.constructor) {
-      return false;
-    }
-
-    /**
-     * like
-     * "function Function {
-     *   [native code]
-     * }"
-     */
-    const constructorStr = target.constructor.toString();
-
-    return constructorStr.includes('[native code]') && constructorStr.includes('Function');
-  }
-
-  /**
-   * Check if passed variable is a constructed class instance
-   *
-   * @param target - variable to check
-   */
-  private static isClassInstance(target: any): boolean {
-    return target && target.constructor && (/^class \S+ {/).test(target.constructor.toString());
-  }
-
-  /**
-   * Check if passed variable is a string
-   *
-   * @param target - variable to check
-   */
-  private static isString(target: any): boolean {
-    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 +193,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>"
    *

packages/core/src/utils/type-guards.ts

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
 /**
  * Checks if value is a plain object (not null, array, Date, Map, etc.)
  *
@@ -12,3 +14,55 @@ export function isPlainObject(value: unknown): value is Record<string, unknown>
 
   return proto === Object.prototype || proto === null;
 }
+
+/**
+ * Check if passed variable is an array
+ *
+ * @param value - variable to check
+ * @returns `true` if value is an array, otherwise `false`
+ */
+export function isArray(value: any): value is any[] {
+  return Array.isArray(value);
+}
+
+/**
+ * Check if passed variable is a not-constructed class
+ *
+ * @param value - variable to check
+ * @returns `true` if value is a class prototype, otherwise `false`
+ */
+export function isClassPrototype(value: any): boolean {
+  if (!value || !value.constructor) {
+    return false;
+  }
+
+  /**
+   * like
+   * "function Function {
+   *   [native code]
+   * }"
+   */
+  const constructorStr = value.constructor.toString();
+
+  return constructorStr.includes('[native code]') && constructorStr.includes('Function');
+}
+
+/**
+ * Check if passed variable is a constructed class instance
+ *
+ * @param value - variable to check
+ * @returns `true` if value is a class instance, otherwise `false`
+ */
+export function isClassInstance(value: any): boolean {
+  return !!(value && value.constructor && (/^class \S+ {/).test(value.constructor.toString()));
+}
+
+/**
+ * Check if passed variable is a string
+ *
+ * @param value - variable to check
+ * @returns `true` if value is a string, otherwise `false`
+ */
+export function isString(value: any): value is string {
+  return typeof value === 'string';
+}

…vascript/tests/modules/sanitizer.test.ts …ges/core/tests/modules/sanitizer.test.tspackages/javascript/tests/modules/sanitizer.test.ts renamed to packages/core/tests/modules/sanitizer.test.ts packages/javascript/tests/modules/sanitizer.test.ts renamed to packages/core/tests/modules/sanitizer.test.ts

@@ -1,33 +1,7 @@
-import { describe, it, expect } from 'vitest';
-import Sanitizer from '../../src/modules/sanitizer';
+import { describe, expect, it } from 'vitest';
+import { Sanitizer } from '../../src';
 
 describe('Sanitizer', () => {
-  describe('isObject', () => {
-    it('should return true for a plain object', () => {
-      expect(Sanitizer.isObject({})).toBe(true);
-    });
-
-    it('should return false for an array', () => {
-      expect(Sanitizer.isObject([])).toBe(false);
-    });
-
-    it('should return false for a string', () => {
-      expect(Sanitizer.isObject('x')).toBe(false);
-    });
-
-    it('should return false for a boolean', () => {
-      expect(Sanitizer.isObject(true)).toBe(false);
-    });
-
-    it('should return false for null', () => {
-      expect(Sanitizer.isObject(null)).toBe(false);
-    });
-
-    it('should return false for undefined', () => {
-      expect(Sanitizer.isObject(undefined)).toBe(false);
-    });
-  });
-
   describe('sanitize', () => {
     it('should pass through strings within the length limit', () => {
       expect(Sanitizer.sanitize('hello')).toBe('hello');
@@ -85,14 +59,6 @@ describe('Sanitizer', () => {
       expect(result.a.b.c.d.e).toBe('<deep object>');
     });
 
-    it('should format HTML elements as a string starting with tag', () => {
-      const el = document.createElement('div');
-      const result = Sanitizer.sanitize(el);
-
-      expect(typeof result).toBe('string');
-      expect(result).toMatch(/^<div/);
-    });
-
     it('should format a class (not constructed) as "<class Name>"', () => {
       class Foo {}