refactor(core): Logger abstraction added

Author: Reversean

packages/browser/src/index.ts

@@ -1 +1,2 @@
-export { HawkLocalStorage } from './storages/hawk-local-storage'
+export { HawkLocalStorage } from './storages/hawk-local-storage';
+export { createBrowserLogger } from './utils/logger';

packages/browser/src/utils/logger.ts

@@ -0,0 +1,52 @@
+import type { Logger, LogType } from '@hawk.so/core';
+
+/**
+ * Creates a browser console logger with Hawk branding and styled output.
+ *
+ * The logger outputs to `window.console` with a dark label badge
+ * containing the Hawk version. Messages are formatted with CSS
+ * styling for better visibility in browser developer tools.
+ *
+ * @param version - Version string to display in log messages.
+ * @param style - Optional CSS style for the message text (default: 'color: inherit').
+ * @returns Logger function implementation for browser environments.
+ *
+ * @example
+ * ```typescript
+ * import { createBrowserLogger } from '@hawk.so/browser';
+ * import { setLogger } from '@hawk.so/core';
+ *
+ * const logger = createBrowserLogger('3.2.0');
+ * setLogger(logger);
+ *
+ * // Custom styling
+ * const styledLogger = createBrowserLogger('3.2.0', 'color: blue; font-weight: bold');
+ * ```
+ */
+export function createBrowserLogger(version: string, style = 'color: inherit'): Logger {
+  return (msg: string, type: LogType = 'log', args?: unknown): void => {
+    if (!('console' in window) || !window.console[type]) {
+      return;
+    }
+
+    const editorLabelText = `Hawk (${version})`;
+    const editorLabelStyle = `line-height: 1em;
+            color: #fff;
+            display: inline-block;
+            line-height: 1em;
+            background-color: rgba(0,0,0,.7);
+            padding: 3px 5px;
+            border-radius: 3px;
+            margin-right: 2px`;
+
+    try {
+      if (['time', 'timeEnd'].includes(type)) {
+        console[type](`( ${editorLabelText} ) ${msg}`);
+      } else if (args) {
+        console[type](`%c${editorLabelText}%c ${msg} %o`, editorLabelStyle, style, args);
+      } else {
+        console[type](`%c${editorLabelText}%c ${msg}`, editorLabelStyle, style);
+      }
+    } catch (ignored) {}
+  };
+}

packages/browser/tests/logger.test.ts

@@ -0,0 +1,78 @@
+import { beforeEach, afterEach, describe, it, expect, vi } from 'vitest';
+import { createBrowserLogger } from '../src';
+
+describe('createBrowserLogger', () => {
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should log message with default type', () => {
+    const logger = createBrowserLogger('1.0.0');
+
+    logger('Test message');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      '%cHawk (1.0.0)%c Test message',
+      expect.stringContaining('background-color'),
+      'color: inherit'
+    );
+  });
+
+  it('should log message with specified type', () => {
+    const logger = createBrowserLogger('2.0.0');
+
+    logger('Warning message', 'warn');
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '%cHawk (2.0.0)%c Warning message',
+      expect.stringContaining('background-color'),
+      'color: inherit'
+    );
+  });
+
+  it('should log error with args', () => {
+    const logger = createBrowserLogger('3.0.0');
+    const errorObj = new Error('Test error');
+
+    logger('Error occurred', 'error', errorObj);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '%cHawk (3.0.0)%c Error occurred %o',
+      expect.stringContaining('background-color'),
+      'color: inherit',
+      errorObj
+    );
+  });
+
+  it('should handle time/timeEnd types', () => {
+    const consoleTimeSpy = vi.spyOn(console, 'time').mockImplementation(() => {});
+    const logger = createBrowserLogger('4.0.0');
+
+    logger('Timer started', 'time');
+
+    expect(consoleTimeSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Hawk (4.0.0)')
+    );
+
+    consoleTimeSpy.mockRestore();
+  });
+
+  it('should not throw when console method is unavailable', () => {
+    const logger = createBrowserLogger('5.0.0');
+
+    expect(() => {
+      // @ts-expect-error - testing invalid type
+      logger('Test', 'invalidType');
+    }).not.toThrow();
+  });
+});

packages/core/src/index.ts

@@ -1,3 +1,5 @@
 export type { HawkStorage } from './storages/hawk-storage';
 export type { UserManager } from './users/user-manager';
 export { StorageUserManager } from './users/storage-user-manager';
+export type { Logger, LogType } from './utils/logger';
+export { setLogger, log } from './utils/logger';

packages/core/src/utils/logger.ts

@@ -0,0 +1,54 @@
+/**
+ * Log level type for categorizing log messages.
+ *
+ * Includes standard console methods supported in both browser and Node.js:
+ * - Standard levels: `log`, `warn`, `error`, `info`
+ * - Performance timing: `time`, `timeEnd`
+ */
+export type LogType = 'log' | 'warn' | 'error' | 'info' | 'time' | 'timeEnd';
+
+/**
+ * Logger function interface for environment-specific logging implementations.
+ *
+ * Implementations should handle message formatting, output styling,
+ * and platform-specific logging mechanisms (e.g., console, file, network).
+ *
+ * @param msg - The message to log.
+ * @param type - Log level/severity (default: 'log').
+ * @param args - Additional data to include with the log message.
+ */
+export interface Logger {
+  (msg: string, type?: LogType, args?: unknown): void;
+}
+
+/**
+ * Global logger instance, set by environment-specific packages.
+ */
+let loggerInstance: Logger | null = null;
+
+/**
+ * Registers the environment-specific logger implementation.
+ *
+ * This should be called once during application initialization
+ * by the environment-specific package.
+ *
+ * @param logger - Logger implementation to use globally.
+ */
+export function setLogger(logger: Logger): void {
+  loggerInstance = logger;
+}
+
+/**
+ * Logs a message using the registered logger implementation.
+ *
+ * If no logger has been registered via {@link setLogger}, this is a no-op.
+ *
+ * @param msg - Message to log.
+ * @param type - Log level (default: 'log').
+ * @param args - Additional arguments to log.
+ */
+export function log(msg: string, type?: LogType, args?: unknown): void {
+  if (loggerInstance) {
+    loggerInstance(msg, type, args);
+  }
+}

packages/javascript/src/addons/breadcrumbs.ts

@@ -4,7 +4,7 @@
 import type { Breadcrumb, BreadcrumbLevel, BreadcrumbType, Json, JsonNode } from '@hawk.so/types';
 import Sanitizer from '../modules/sanitizer';
 import { buildElementSelector } from '../utils/selector';
-import log from '../utils/log';
+import { log } from '@hawk.so/core';
 import { isValidBreadcrumb } from '../utils/validation';
 
 /**

packages/javascript/src/catcher.ts

@@ -1,6 +1,5 @@
 import Socket from './modules/socket';
 import Sanitizer from './modules/sanitizer';
-import log from './utils/log';
 import StackParser from './modules/stackParser';
 import type { CatcherMessage, HawkInitialSettings, BreadcrumbsAPI, Transport } from './types';
 import { VueIntegration } from './integrations/vue';
@@ -19,8 +18,8 @@ import { ConsoleCatcher } from './addons/consoleCatcher';
 import { BreadcrumbManager } from './addons/breadcrumbs';
 import { validateUser, validateContext, isValidEventPayload } from './utils/validation';
 import type { UserManager } from '@hawk.so/core';
-import { StorageUserManager } from '@hawk.so/core';
-import { HawkLocalStorage } from '@hawk.so/browser';
+import { StorageUserManager, setLogger, log } from '@hawk.so/core';
+import { HawkLocalStorage, createBrowserLogger } from '@hawk.so/browser';
 import { id } from './utils/id';
 
 /**
@@ -120,6 +119,8 @@ export default class Catcher {
    * @param {HawkInitialSettings|string} settings - If settings is a string, it means an Integration Token
    */
   constructor(settings: HawkInitialSettings | string) {
+    setLogger(createBrowserLogger(VERSION));
+
     if (typeof settings === 'string') {
       settings = {
         token: settings,

packages/javascript/src/modules/fetchTimer.ts

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

packages/javascript/src/modules/socket.ts

@@ -1,4 +1,4 @@
-import log from '../utils/log';
+import { log } from '@hawk.so/core';
 import type { CatcherMessage } from '@/types';
 import type { Transport } from '../types/transport';
 

packages/javascript/src/utils/event.ts

@@ -1,4 +1,4 @@
-import log from './log';
+import { log } from '@hawk.so/core';
 
 /**
  * Symbol to mark error as processed by Hawk