From ffff7d64264d526145f361d705133803404cccab Mon Sep 17 00:00:00 2001 From: Reversean Date: Wed, 25 Feb 2026 20:03:49 +0300 Subject: [PATCH 1/6] test(catcher): Catcher covered with tests --- packages/javascript/package.json | 2 + packages/javascript/tests/catcher.test.ts | 642 ++++++++++++++++++++++ yarn.lock | 109 +++- 3 files changed, 751 insertions(+), 2 deletions(-) create mode 100644 packages/javascript/tests/catcher.test.ts diff --git a/packages/javascript/package.json b/packages/javascript/package.json index 22e9827c..66543c23 100644 --- a/packages/javascript/package.json +++ b/packages/javascript/package.json @@ -21,6 +21,7 @@ "build": "vite build", "stats": "size-limit > stats.txt", "test": "vitest run", + "test:coverage": "vitest run --coverage", "test:watch": "vitest", "lint": "eslint --fix \"src/**/*.{js,ts}\"" }, @@ -43,6 +44,7 @@ }, "devDependencies": { "@hawk.so/types": "0.5.8", + "@vitest/coverage-v8": "^4.0.18", "jsdom": "^28.0.0", "vite": "^7.3.1", "vite-plugin-dts": "^4.2.4", diff --git a/packages/javascript/tests/catcher.test.ts b/packages/javascript/tests/catcher.test.ts new file mode 100644 index 00000000..3f2b184b --- /dev/null +++ b/packages/javascript/tests/catcher.test.ts @@ -0,0 +1,642 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; +import Catcher from '../src/catcher'; +import { BreadcrumbManager } from '../src/addons/breadcrumbs'; +import type { Transport } from '../src'; + +const TEST_TOKEN = 'eyJpbnRlZ3JhdGlvbklkIjoiOTU3MmQyOWQtNWJhZS00YmYyLTkwN2MtZDk5ZDg5MGIwOTVmIiwic2VjcmV0IjoiZTExODFiZWItMjdlMS00ZDViLWEwZmEtZmUwYTM1Mzg5OWMyIn0='; +const wait = (): Promise => new Promise((r) => setTimeout(r, 0)); + +// StackParser is mocked to prevent real network calls to source files in the jsdom environment. +const mockParse = vi.hoisted(() => vi.fn().mockResolvedValue([])); +vi.mock('../src/modules/stackParser', () => ({ + default: class { + parse = mockParse; + }, +})); + +// ─── Tests ─────────────────────────────────────────────────────────────────── + +describe('Catcher', () => { + beforeEach(() => { + localStorage.clear(); + mockParse.mockResolvedValue([]); + // eslint-disable-next-line @typescript-eslint/no-explicit-any + (BreadcrumbManager as any).instance = null; + }); + + // ── Error delivery ──────────────────────────────────────────────────────── + // + // The Catcher's primary responsibility: capture errors and forward them to + // the configured transport with identifying metadata. + describe('error delivery', () => { + it('should deliver an Error instance via transport with matching title', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).send(new Error('something broke')); + await wait(); + + expect(sendSpy).toHaveBeenCalledOnce(); + expect(sendSpy.mock.calls[0][0].token).toBe(TEST_TOKEN); + expect(sendSpy.mock.calls[0][0].catcherType).toBe('errors/javascript'); + expect(getLastPayload(sendSpy).title).toBe('something broke'); + }); + + it('should deliver a string-based error via transport with matching title', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).send('unhandled rejection reason'); + await wait(); + + expect(sendSpy).toHaveBeenCalledOnce(); + expect(sendSpy.mock.calls[0][0].token).toBe(TEST_TOKEN); + expect(sendSpy.mock.calls[0][0].catcherType).toBe('errors/javascript'); + expect(getLastPayload(sendSpy).title).toBe('unhandled rejection reason'); + }); + + it('should not deliver the same Error instance twice', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + const error = new Error('duplicate'); + + hawk.send(error); + hawk.send(error); + await wait(); + + expect(sendSpy).toHaveBeenCalledTimes(1); + }); + + it('should deliver distinct Error instances independently', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.send(new Error('first')); + hawk.send(new Error('second')); + await wait(); + + expect(sendSpy).toHaveBeenCalledTimes(2); + }); + + it('should deliver string errors without deduplication', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.send('reason'); + hawk.send('reason'); + await wait(); + + expect(sendSpy).toHaveBeenCalledTimes(2); + }); + }); + + // ── User identity ───────────────────────────────────────────────────────── + // + // The Catcher tracks who caused the error. When no user is configured it + // falls back to a generated anonymous ID that persists across events. + describe('user identity', () => { + let warnSpy: ReturnType; + + beforeEach(() => { + warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + }); + + afterEach(() => { + warnSpy.mockRestore(); + }); + + it('should generate a stable anonymous ID when no user is configured', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.send(new Error('first')); + await wait(); + const id1 = getLastPayload(sendSpy).user?.id; + + hawk.send(new Error('second')); + await wait(); + const id2 = getLastPayload(sendSpy).user?.id; + + expect(id1).toBeTruthy(); + expect(id1).toBe(id2); + }); + + it('should include the user configured via setUser()', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.setUser({ id: 'user-1', name: 'Alice' }); + hawk.send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).user).toMatchObject({ id: 'user-1', name: 'Alice' }); + }); + + it('should include the user configured via constructor', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport, { user: { id: 'user-2' } }).send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).user).toMatchObject({ id: 'user-2' }); + }); + + it('should ignore setUser when called with null', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.setUser({ id: 'valid' }); + hawk.setUser(null as never); + hawk.send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).user?.id).toBe('valid'); + }); + + it('should ignore setUser when the user has no id', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.setUser({ id: 'valid' }); + hawk.setUser({} as never); + hawk.send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).user?.id).toBe('valid'); + }); + + it('should revert to an anonymous identity after clearUser()', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.setUser({ id: 'user-1' }); + hawk.clearUser(); + hawk.send(new Error('e')); + await wait(); + + const user = getLastPayload(sendSpy).user; + + expect(user?.id).toBeTruthy(); + expect(user?.id).not.toBe('user-1'); + }); + }); + + // ── Context enrichment ──────────────────────────────────────────────────── + // + // The Catcher attaches contextual information to every event: an optional + // release version and arbitrary developer-supplied context data. + describe('context enrichment', () => { + let warnSpy: ReturnType; + + beforeEach(() => { + warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + }); + + afterEach(() => { + warnSpy.mockRestore(); + }); + + it('should include the release version when configured', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport, { release: '1.2.3' }).send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).release).toBe('1.2.3'); + }); + + it('should omit the release when not configured', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).release).toBeFalsy(); + }); + + it('should include global context set via setContext()', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.setContext({ env: 'production' }); + hawk.send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).context).toMatchObject({ env: 'production' }); + }); + + it('should include per-send context passed to send()', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).send(new Error('e'), { requestId: 'abc123' }); + await wait(); + + expect(getLastPayload(sendSpy).context).toMatchObject({ requestId: 'abc123' }); + }); + + it('should ignore setContext when called with a non-object value', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport); + + hawk.setContext({ original: true }); + hawk.setContext(42 as never); + hawk.send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).context).toMatchObject({ original: true }); + }); + + it('should merge global and per-send context, per-send wins on key collision', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport, { context: { key: 'global', shared: 1 } }); + + hawk.send(new Error('e'), { key: 'local', extra: 2 }); + await wait(); + + expect(getLastPayload(sendSpy).context).toMatchObject({ + key: 'local', + shared: 1, + extra: 2, + }); + }); + }); + + // ── Breadcrumbs trail ───────────────────────────────────────────────────── + // + // The Catcher maintains a chronological trail of events leading up to the + // error. The trail is included in delivered events only when non-empty. + describe('breadcrumbs trail', () => { + it('should include recorded breadcrumbs in delivered events', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport, { breadcrumbs: {} }); + + hawk.breadcrumbs.add({ message: 'button clicked', timestamp: Date.now() }); + hawk.send(new Error('e')); + await wait(); + + const breadcrumbs = getLastPayload(sendSpy).breadcrumbs; + + expect(Array.isArray(breadcrumbs)).toBe(true); + expect(breadcrumbs[0].message).toBe('button clicked'); + }); + + it('should omit breadcrumbs when none have been recorded', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport, { breadcrumbs: {} }).send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).breadcrumbs).toBeFalsy(); + }); + + it('should return an empty array from breadcrumbs.get when breadcrumbs are disabled', () => { + const { transport } = createTransport(); + + expect(createCatcher(transport).breadcrumbs.get()).toEqual([]); + }); + + it('should omit breadcrumbs cleared before the event was sent', async () => { + const { sendSpy, transport } = createTransport(); + const hawk = createCatcher(transport, { breadcrumbs: {} }); + + hawk.breadcrumbs.add({ message: 'click', timestamp: Date.now() }); + hawk.breadcrumbs.clear(); + hawk.send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).breadcrumbs).toBeFalsy(); + }); + }); + + // ── Integration addons ──────────────────────────────────────────────────── + // + // Framework integrations (Vue, Nuxt, etc.) attach extra addons when + // reporting errors via captureError(). These are merged into the payload + // alongside the standard browser addons. + describe('integration addons via captureError()', () => { + it('should merge integration-specific addons into the delivered event', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).captureError(new Error('e'), { + vue: { component: '', props: {}, lifecycle: 'mounted' }, + }); + await wait(); + + expect(getLastPayload(sendSpy).addons).toMatchObject({ + vue: { component: '', props: {}, lifecycle: 'mounted' }, + }); + }); + + it('should preserve standard browser addons when integration addons are merged', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).captureError(new Error('e'), { + vue: { component: '', props: {}, lifecycle: 'mounted' }, + }); + await wait(); + + const addons = getLastPayload(sendSpy).addons; + + expect(addons.userAgent).toBeDefined(); + expect(addons.url).toBeDefined(); + }); + }); + + // ── Constructor variants ────────────────────────────────────────────────── + // + // The Catcher can be initialised with either a full settings object or a + // bare string token as a shorthand. + describe('constructor', () => { + it('should accept a plain string as a shorthand for the token', async () => { + const sendSpy = vi.fn().mockResolvedValue(undefined); + const transport: Transport = { send: sendSpy }; + + const hawk = new Catcher({ + token: TEST_TOKEN, + disableGlobalErrorsHandling: true, + breadcrumbs: false, + consoleTracking: false, + transport, + }); + + hawk.send(new Error('shorthand')); + await wait(); + + expect(sendSpy).toHaveBeenCalledOnce(); + expect(sendSpy.mock.calls[0][0].token).toBe(TEST_TOKEN); + }); + + it('should warn and silently do nothing when no token is provided', async () => { + const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + + const hawk = new Catcher({ token: '' } as never); + + hawk.send(new Error('no-token')); + await wait(); + + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining('Integration Token is missed'), + expect.anything(), + expect.anything() + ); + + warnSpy.mockRestore(); + }); + + it('should construct without error when given a bare token string', () => { + const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); + const addELSpy = vi.spyOn(window, 'addEventListener').mockImplementation(() => undefined); + + expect(() => new Catcher(TEST_TOKEN)).not.toThrow(); + + addELSpy.mockRestore(); + consoleSpy.mockRestore(); + }); + + it('should throw when the integration token contains malformed JSON', () => { + // getIntegrationId() tries JSON.parse(atob(token)); malformed JSON triggers the catch path. + expect(() => new Catcher({ token: btoa('not-json') })).toThrow('Invalid integration token.'); + }); + + it('should throw when the integration token has no integrationId field', () => { + // Valid base64 JSON but missing the integrationId property — inner guard throws. + const tokenWithoutId = btoa(JSON.stringify({ secret: 'abc' })); + + expect(() => new Catcher({ token: tokenWithoutId })).toThrow('Invalid integration token.'); + }); + }); + + // ── test() convenience method ───────────────────────────────────────────── + describe('test()', () => { + it('should send a predefined test error event via transport', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).test(); + await wait(); + + expect(sendSpy).toHaveBeenCalledOnce(); + expect(getLastPayload(sendSpy).title).toContain('Hawk JavaScript Catcher test message'); + }); + }); + + // ── Global error handlers ───────────────────────────────────────────────── + // + // When disableGlobalErrorsHandling is not set, the Catcher listens to + // window 'error' and 'unhandledrejection' events. + describe('global error handlers', () => { + const addedListeners: Array<[string, EventListenerOrEventListenerObject]> = []; + + beforeEach(() => { + const origAddEL = window.addEventListener.bind(window); + + vi.spyOn(window, 'addEventListener').mockImplementation( + (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => { + if (type === 'error' || type === 'unhandledrejection') { + addedListeners.push([type, listener]); + } + return origAddEL(type, listener, options as AddEventListenerOptions); + } + ); + }); + + afterEach(() => { + vi.restoreAllMocks(); + for (const [type, listener] of addedListeners) { + window.removeEventListener(type, listener as EventListener); + } + addedListeners.length = 0; + }); + + it('should capture errors from window error events', async () => { + const { sendSpy, transport } = createTransport(); + + new Catcher({ + token: TEST_TOKEN, + breadcrumbs: false, + consoleTracking: false, + transport, + // disableGlobalErrorsHandling not set → handlers registered + }); + + window.dispatchEvent( + new ErrorEvent('error', { error: new Error('global error'), message: 'global error' }) + ); + await wait(); + + expect(sendSpy).toHaveBeenCalledOnce(); + expect(getLastPayload(sendSpy).title).toBe('global error'); + }); + + it('should capture CORS script errors where error object is unavailable', async () => { + const { sendSpy, transport } = createTransport(); + + new Catcher({ + token: TEST_TOKEN, + breadcrumbs: false, + consoleTracking: false, + transport, + }); + + // CORS case: error property is undefined, only message is available. + window.dispatchEvent( + new ErrorEvent('error', { error: undefined, message: 'Script error.' }) + ); + await wait(); + + expect(sendSpy).toHaveBeenCalledOnce(); + expect(getLastPayload(sendSpy).title).toBe('Script error.'); + }); + + it('should capture unhandled promise rejections', async () => { + const { sendSpy, transport } = createTransport(); + + new Catcher({ + token: TEST_TOKEN, + breadcrumbs: false, + consoleTracking: false, + transport, + }); + + window.dispatchEvent( + new PromiseRejectionEvent('unhandledrejection', { + promise: Promise.resolve() as Promise, + reason: new Error('rejected'), + }) + ); + await wait(); + + expect(sendSpy).toHaveBeenCalledOnce(); + expect(getLastPayload(sendSpy).title).toBe('rejected'); + }); + }); + + // ── Transport failure ───────────────────────────────────────────────────── + describe('transport failure', () => { + it('should log a warning when transport.send rejects', async () => { + const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); + const transport: Transport = { + send: vi.fn().mockRejectedValue(new Error('network error')), + }; + + createCatcher(transport).send(new Error('e')); + await wait(); + + expect(errorSpy).toHaveBeenCalledWith( + expect.stringContaining('WebSocket sending error'), + expect.anything(), + expect.anything(), + expect.anything() + ); + + errorSpy.mockRestore(); + }); + + it('should log a warning when beforeSend throws unexpectedly', async () => { + const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const { transport } = createTransport(); + + createCatcher(transport, { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + beforeSend: () => { throw new Error('beforeSend crashed'); }, + } as never).send(new Error('e')); + await wait(); + + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining('Unable to send error'), + expect.anything(), + expect.anything(), + expect.anything() + ); + + warnSpy.mockRestore(); + }); + }); + + // ── Environment addons ──────────────────────────────────────────────────── + // + // Browser-specific data collected from window (URL, GET params, debug info). + describe('environment addons', () => { + it('should include GET parameters when the URL has a query string', async () => { + vi.stubGlobal('location', { + ...window.location, + search: '?foo=bar&baz=qux', + href: 'http://localhost/?foo=bar&baz=qux', + }); + + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).send(new Error('e')); + await wait(); + + expect(getLastPayload(sendSpy).addons.get).toEqual({ foo: 'bar', baz: 'qux' }); + + vi.unstubAllGlobals(); + }); + + it('should include raw error data in debug mode', async () => { + const { sendSpy, transport } = createTransport(); + const error = new Error('debug error'); + + createCatcher(transport, { debug: true }).send(error); + await wait(); + + expect(getLastPayload(sendSpy).addons.RAW_EVENT_DATA).toMatchObject({ + name: 'Error', + message: 'debug error', + stack: expect.any(String), + }); + }); + + it('should not include raw error data for string errors even in debug mode', async () => { + const { sendSpy, transport } = createTransport(); + + createCatcher(transport, { debug: true }).send('string reason'); + await wait(); + + expect(getLastPayload(sendSpy).addons.RAW_EVENT_DATA).toBeUndefined(); + }); + }); + + // ── Backtrace ───────────────────────────────────────────────────────────── + describe('backtrace', () => { + it('should omit backtrace when stack parsing throws', async () => { + mockParse.mockRejectedValueOnce(new Error('parse failed')); + + const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const { sendSpy, transport } = createTransport(); + + createCatcher(transport).send(new Error('stack parse failure')); + await wait(); + + expect(getLastPayload(sendSpy).title).toBe('stack parse failure'); + expect(sendSpy).toHaveBeenCalledOnce(); + + warnSpy.mockRestore(); + }); + }); +}); + +// ─── Helpers ───────────────────────────────────────────────────────────────── + +function createTransport() { + const sendSpy = vi.fn().mockResolvedValue(undefined); + const transport: Transport = { send: sendSpy }; + + return { sendSpy, transport }; +} + +/** Returns the payload of the last call to transport.send. */ +function getLastPayload(spy: ReturnType) { + const calls = spy.mock.calls; + + return calls[calls.length - 1][0].payload; +} + +function createCatcher(transport: Transport, options: Record = {}) { + return new Catcher({ + token: TEST_TOKEN, + disableGlobalErrorsHandling: true, + breadcrumbs: false, + consoleTracking: false, + transport, + ...options, + }); +} diff --git a/yarn.lock b/yarn.lock index b4ec9e55..eacf26a2 100644 --- a/yarn.lock +++ b/yarn.lock @@ -80,7 +80,7 @@ __metadata: languageName: node linkType: hard -"@babel/parser@npm:^7.23.5, @babel/parser@npm:^7.28.5": +"@babel/parser@npm:^7.23.5, @babel/parser@npm:^7.28.5, @babel/parser@npm:^7.29.0": version: 7.29.0 resolution: "@babel/parser@npm:7.29.0" dependencies: @@ -101,6 +101,13 @@ __metadata: languageName: node linkType: hard +"@bcoe/v8-coverage@npm:^1.0.2": + version: 1.0.2 + resolution: "@bcoe/v8-coverage@npm:1.0.2" + checksum: 10c0/1eb1dc93cc17fb7abdcef21a6e7b867d6aa99a7ec88ec8207402b23d9083ab22a8011213f04b2cf26d535f1d22dc26139b7929e6c2134c254bd1e14ba5e678c3 + languageName: node + linkType: hard + "@csstools/color-helpers@npm:^6.0.1": version: 6.0.1 resolution: "@csstools/color-helpers@npm:6.0.1" @@ -590,6 +597,7 @@ __metadata: resolution: "@hawk.so/javascript@workspace:packages/javascript" dependencies: "@hawk.so/types": "npm:0.5.8" + "@vitest/coverage-v8": "npm:^4.0.18" error-stack-parser: "npm:^2.1.4" jsdom: "npm:^28.0.0" vite: "npm:^7.3.1" @@ -708,7 +716,7 @@ __metadata: languageName: node linkType: hard -"@jridgewell/trace-mapping@npm:^0.3.24": +"@jridgewell/trace-mapping@npm:^0.3.24, @jridgewell/trace-mapping@npm:^0.3.31": version: 0.3.31 resolution: "@jridgewell/trace-mapping@npm:0.3.31" dependencies: @@ -1385,6 +1393,30 @@ __metadata: languageName: node linkType: hard +"@vitest/coverage-v8@npm:^4.0.18": + version: 4.0.18 + resolution: "@vitest/coverage-v8@npm:4.0.18" + dependencies: + "@bcoe/v8-coverage": "npm:^1.0.2" + "@vitest/utils": "npm:4.0.18" + ast-v8-to-istanbul: "npm:^0.3.10" + istanbul-lib-coverage: "npm:^3.2.2" + istanbul-lib-report: "npm:^3.0.1" + istanbul-reports: "npm:^3.2.0" + magicast: "npm:^0.5.1" + obug: "npm:^2.1.1" + std-env: "npm:^3.10.0" + tinyrainbow: "npm:^3.0.3" + peerDependencies: + "@vitest/browser": 4.0.18 + vitest: 4.0.18 + peerDependenciesMeta: + "@vitest/browser": + optional: true + checksum: 10c0/e23e0da86f0b2a020c51562bc40ebdc7fc7553c24f8071dfb39a6df0161badbd5eaf2eebbf8ceaef18933a18c1934ff52d1c0c4bde77bb87e0c1feb0c8cbee4d + languageName: node + linkType: hard + "@vitest/expect@npm:4.0.18": version: 4.0.18 resolution: "@vitest/expect@npm:4.0.18" @@ -1846,6 +1878,17 @@ __metadata: languageName: node linkType: hard +"ast-v8-to-istanbul@npm:^0.3.10": + version: 0.3.11 + resolution: "ast-v8-to-istanbul@npm:0.3.11" + dependencies: + "@jridgewell/trace-mapping": "npm:^0.3.31" + estree-walker: "npm:^3.0.3" + js-tokens: "npm:^10.0.0" + checksum: 10c0/0667dcb5f42bd16f5d50b8687f3471f9b9d000ea7f8808c3cd0ddabc1ef7d5b1a61e19f498d5ca7b1285e6c185e11d0ae724c4f9291491b50b6340110ce63108 + languageName: node + linkType: hard + "astral-regex@npm:^2.0.0": version: 2.0.0 resolution: "astral-regex@npm:2.0.0" @@ -3602,6 +3645,13 @@ __metadata: languageName: node linkType: hard +"html-escaper@npm:^2.0.0": + version: 2.0.2 + resolution: "html-escaper@npm:2.0.2" + checksum: 10c0/208e8a12de1a6569edbb14544f4567e6ce8ecc30b9394fcaa4e7bb1e60c12a7c9a1ed27e31290817157e8626f3a4f29e76c8747030822eb84a6abb15c255f0a0 + languageName: node + linkType: hard + "http-cache-semantics@npm:^4.1.1": version: 4.2.0 resolution: "http-cache-semantics@npm:4.2.0" @@ -3997,6 +4047,34 @@ __metadata: languageName: node linkType: hard +"istanbul-lib-coverage@npm:^3.0.0, istanbul-lib-coverage@npm:^3.2.2": + version: 3.2.2 + resolution: "istanbul-lib-coverage@npm:3.2.2" + checksum: 10c0/6c7ff2106769e5f592ded1fb418f9f73b4411fd5a084387a5410538332b6567cd1763ff6b6cadca9b9eb2c443cce2f7ea7d7f1b8d315f9ce58539793b1e0922b + languageName: node + linkType: hard + +"istanbul-lib-report@npm:^3.0.0, istanbul-lib-report@npm:^3.0.1": + version: 3.0.1 + resolution: "istanbul-lib-report@npm:3.0.1" + dependencies: + istanbul-lib-coverage: "npm:^3.0.0" + make-dir: "npm:^4.0.0" + supports-color: "npm:^7.1.0" + checksum: 10c0/84323afb14392de8b6a5714bd7e9af845cfbd56cfe71ed276cda2f5f1201aea673c7111901227ee33e68e4364e288d73861eb2ed48f6679d1e69a43b6d9b3ba7 + languageName: node + linkType: hard + +"istanbul-reports@npm:^3.2.0": + version: 3.2.0 + resolution: "istanbul-reports@npm:3.2.0" + dependencies: + html-escaper: "npm:^2.0.0" + istanbul-lib-report: "npm:^3.0.0" + checksum: 10c0/d596317cfd9c22e1394f22a8d8ba0303d2074fe2e971887b32d870e4b33f8464b10f8ccbe6847808f7db485f084eba09e6c2ed706b3a978e4b52f07085b8f9bc + languageName: node + linkType: hard + "jiti@npm:^2.4.2": version: 2.6.1 resolution: "jiti@npm:2.6.1" @@ -4013,6 +4091,13 @@ __metadata: languageName: node linkType: hard +"js-tokens@npm:^10.0.0": + version: 10.0.0 + resolution: "js-tokens@npm:10.0.0" + checksum: 10c0/a93498747812ba3e0c8626f95f75ab29319f2a13613a0de9e610700405760931624433a0de59eb7c27ff8836e526768fb20783861b86ef89be96676f2c996b64 + languageName: node + linkType: hard + "js-tokens@npm:^4.0.0": version: 4.0.0 resolution: "js-tokens@npm:4.0.0" @@ -4249,6 +4334,26 @@ __metadata: languageName: node linkType: hard +"magicast@npm:^0.5.1": + version: 0.5.2 + resolution: "magicast@npm:0.5.2" + dependencies: + "@babel/parser": "npm:^7.29.0" + "@babel/types": "npm:^7.29.0" + source-map-js: "npm:^1.2.1" + checksum: 10c0/924af677643c5a0a7d6cdb3247c0eb96fa7611b2ba6a5e720d35d81c503d3d9f5948eb5227f80f90f82ea3e7d38cffd10bb988f3fc09020db428e14f26e960d7 + languageName: node + linkType: hard + +"make-dir@npm:^4.0.0": + version: 4.0.0 + resolution: "make-dir@npm:4.0.0" + dependencies: + semver: "npm:^7.5.3" + checksum: 10c0/69b98a6c0b8e5c4fe9acb61608a9fbcfca1756d910f51e5dbe7a9e5cfb74fca9b8a0c8a0ffdf1294a740826c1ab4871d5bf3f62f72a3049e5eac6541ddffed68 + languageName: node + linkType: hard + "make-fetch-happen@npm:^15.0.0": version: 15.0.3 resolution: "make-fetch-happen@npm:15.0.3" From 90d2fb661561219f004be633d8f64fa67bcbe6cc Mon Sep 17 00:00:00 2001 From: Reversean Date: Wed, 25 Feb 2026 20:03:59 +0300 Subject: [PATCH 2/6] test(catcher): Validation utils covered with tests --- .../javascript/tests/utils/validation.test.ts | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 packages/javascript/tests/utils/validation.test.ts diff --git a/packages/javascript/tests/utils/validation.test.ts b/packages/javascript/tests/utils/validation.test.ts new file mode 100644 index 00000000..e277815a --- /dev/null +++ b/packages/javascript/tests/utils/validation.test.ts @@ -0,0 +1,101 @@ +import { describe, it, expect, vi } from 'vitest'; +import { validateUser, validateContext, isValidEventPayload, isValidBreadcrumb } from '../../src/utils/validation'; + +// Suppress console output produced by log() calls inside validation failures. +vi.mock('../src/utils/log', () => ({ default: vi.fn() })); + +describe('validateUser', () => { + it('should return false when user is null', () => { + expect(validateUser(null as never)).toBe(false); + }); + + it('should return false when user is a primitive (not an object)', () => { + expect(validateUser('alice' as never)).toBe(false); + }); + + it('should return false when user has no id property', () => { + expect(validateUser({} as never)).toBe(false); + }); + + it('should return false when user.id is a whitespace-only string', () => { + expect(validateUser({ id: ' ' } as never)).toBe(false); + }); + + it('should return false when user.id is not a string', () => { + expect(validateUser({ id: 42 } as never)).toBe(false); + }); + + it('should return true for a valid user object with an id', () => { + expect(validateUser({ id: 'user-1' })).toBe(true); + }); +}); + +describe('validateContext', () => { + it('should return false when context is a non-object primitive', () => { + expect(validateContext(42 as never)).toBe(false); + }); + + it('should return false when context is an array', () => { + expect(validateContext([] as never)).toBe(false); + }); + + it('should return true when context is undefined', () => { + expect(validateContext(undefined)).toBe(true); + }); + + it('should return true when context is a plain object', () => { + expect(validateContext({ env: 'production' })).toBe(true); + }); +}); + +describe('isValidEventPayload', () => { + it('should return false when payload is not a plain object', () => { + expect(isValidEventPayload('string')).toBe(false); + }); + + it('should return false when title is missing', () => { + expect(isValidEventPayload({})).toBe(false); + }); + + it('should return false when title is an empty string', () => { + expect(isValidEventPayload({ title: ' ' })).toBe(false); + }); + + it('should return false when backtrace is present but not an array', () => { + expect(isValidEventPayload({ title: 'oops', backtrace: 'not-an-array' })).toBe(false); + }); + + it('should return true when backtrace is an array', () => { + expect(isValidEventPayload({ title: 'oops', backtrace: [] })).toBe(true); + }); + + it('should return true for a minimal valid payload', () => { + expect(isValidEventPayload({ title: 'oops' })).toBe(true); + }); +}); + +describe('isValidBreadcrumb', () => { + it('should return false when breadcrumb is not a plain object', () => { + expect(isValidBreadcrumb('not-an-object')).toBe(false); + }); + + it('should return false when message is missing', () => { + expect(isValidBreadcrumb({})).toBe(false); + }); + + it('should return false when message is a whitespace-only string', () => { + expect(isValidBreadcrumb({ message: ' ' })).toBe(false); + }); + + it('should return false when timestamp is present but not a number', () => { + expect(isValidBreadcrumb({ message: 'click', timestamp: 'noon' })).toBe(false); + }); + + it('should return true when timestamp is a valid number', () => { + expect(isValidBreadcrumb({ message: 'click', timestamp: Date.now() })).toBe(true); + }); + + it('should return true when timestamp is absent', () => { + expect(isValidBreadcrumb({ message: 'click' })).toBe(true); + }); +}); From 591724ab5bc8413a07b04c25ff63debcf891d8aa Mon Sep 17 00:00:00 2001 From: Reversean Date: Mon, 16 Feb 2026 22:28:52 +0300 Subject: [PATCH 3/6] refactor(core): HawkStorage abstraction added --- packages/core/src/index.ts | 1 + packages/core/src/storages/hawk-storage.ts | 26 +++++++ packages/javascript/package.json | 1 + .../src/storages/hawk-local-storage.ts | 35 +++++++++ .../tests/storages/hawk-local-storage.test.ts | 75 +++++++++++++++++++ packages/javascript/tsconfig.test.json | 3 +- yarn.lock | 3 +- 7 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 packages/core/src/storages/hawk-storage.ts create mode 100644 packages/javascript/src/storages/hawk-local-storage.ts create mode 100644 packages/javascript/tests/storages/hawk-local-storage.test.ts diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index e69de29b..6a701ebc 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -0,0 +1 @@ +export type { HawkStorage } from './storages/hawk-storage'; diff --git a/packages/core/src/storages/hawk-storage.ts b/packages/core/src/storages/hawk-storage.ts new file mode 100644 index 00000000..ad200161 --- /dev/null +++ b/packages/core/src/storages/hawk-storage.ts @@ -0,0 +1,26 @@ +/** + * Abstract key–value storage contract used by Hawk internals to persist data across sessions. + */ +export interface HawkStorage { + /** + * Returns the value associated with the given key, or `null` if none exists or on error. + * + * @param key - Storage key to look up. + */ + getItem(key: string): string | null; + + /** + * Persists a value under the given key. Must not throw on failure. + * + * @param key - Storage key. + * @param value - Value to store. + */ + setItem(key: string, value: string): void; + + /** + * Removes the entry for the given key. Must not throw on failure. + * + * @param key - Storage key to remove. + */ + removeItem(key: string): void; +} diff --git a/packages/javascript/package.json b/packages/javascript/package.json index 66543c23..75db15ae 100644 --- a/packages/javascript/package.json +++ b/packages/javascript/package.json @@ -40,6 +40,7 @@ }, "homepage": "https://github.com/codex-team/hawk.javascript#readme", "dependencies": { + "@hawk.so/core": "workspace:^", "error-stack-parser": "^2.1.4" }, "devDependencies": { diff --git a/packages/javascript/src/storages/hawk-local-storage.ts b/packages/javascript/src/storages/hawk-local-storage.ts new file mode 100644 index 00000000..c0362ea9 --- /dev/null +++ b/packages/javascript/src/storages/hawk-local-storage.ts @@ -0,0 +1,35 @@ +import type { HawkStorage } from '@hawk.so/core'; +import log from '../utils/log.ts'; + +/** + * {@link HawkStorage} implementation backed by the browser's {@linkcode localStorage}. + */ +export class HawkLocalStorage implements HawkStorage { + /** @inheritDoc */ + public getItem(key: string): string | null { + try { + return localStorage.getItem(key); + } catch (e) { + log('HawkLocalStorage: getItem failed', 'error', e); + return null; + } + } + + /** @inheritDoc */ + public setItem(key: string, value: string): void { + try { + localStorage.setItem(key, value); + } catch (e) { + log('HawkLocalStorage: setItem failed', 'error', e); + } + } + + /** @inheritDoc */ + public removeItem(key: string): void { + try { + localStorage.removeItem(key); + } catch (e) { + log('HawkLocalStorage: removeItem failed', 'error', e); + } + } +} diff --git a/packages/javascript/tests/storages/hawk-local-storage.test.ts b/packages/javascript/tests/storages/hawk-local-storage.test.ts new file mode 100644 index 00000000..a9ea1e58 --- /dev/null +++ b/packages/javascript/tests/storages/hawk-local-storage.test.ts @@ -0,0 +1,75 @@ +import type { Mock } from 'vitest'; +import { beforeEach, afterEach, describe, it, expect, vi } from 'vitest'; +import { HawkLocalStorage } from '../../src/storages/hawk-local-storage'; + +describe('HawkLocalStorage', () => { + let getItemSpy: Mock<(key: string) => string | null>; + let setItemSpy: Mock<(key: string, value: string) => void>; + let removeItemSpy: Mock<(key: string) => void>; + let storage: HawkLocalStorage; + + beforeEach(() => { + localStorage.clear(); + storage = new HawkLocalStorage(); + getItemSpy = vi.spyOn(Storage.prototype, 'getItem'); + setItemSpy = vi.spyOn(Storage.prototype, 'setItem'); + removeItemSpy = vi.spyOn(Storage.prototype, 'removeItem'); + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + it('should return null when key does not exist', () => { + expect(storage.getItem('foo')).toBeNull(); + expect(getItemSpy).toHaveBeenCalledOnce(); + }); + + it('should return value when key exists in storage', () => { + localStorage.setItem('foo', 'bar'); + + expect(storage.getItem('foo')).toEqual('bar'); + expect(getItemSpy).toHaveBeenCalledWith('foo'); + }); + + it('should persist item via setItem()', () => { + storage.setItem('foo', 'bar'); + + expect(setItemSpy).toHaveBeenCalledWith('foo', 'bar'); + expect(localStorage.getItem('foo')).toEqual('bar'); + }); + + it('should remove item via removeItem()', () => { + localStorage.setItem('foo', 'bar'); + storage.removeItem('foo'); + + expect(removeItemSpy).toHaveBeenCalledWith('foo'); + expect(localStorage.getItem('foo')).toBeNull(); + }); + + it('should not affect other keys when removing', () => { + localStorage.setItem('foo', 'bar'); + storage.removeItem('baz'); + + expect(removeItemSpy).toHaveBeenCalledWith('baz'); + expect(localStorage.getItem('foo')).toEqual('bar'); + }); + + it('should return null when getItem throws', () => { + getItemSpy.mockImplementation(() => { throw new Error('SecurityError'); }); + + expect(storage.getItem('foo')).toBeNull(); + }); + + it('should not throw when setItem throws', () => { + setItemSpy.mockImplementation(() => { throw new Error('QuotaExceededError'); }); + + expect(() => storage.setItem('foo', 'bar')).not.toThrow(); + }); + + it('should not throw when removeItem throws', () => { + removeItemSpy.mockImplementation(() => { throw new Error('SecurityError'); }); + + expect(() => storage.removeItem('foo')).not.toThrow(); + }); +}); diff --git a/packages/javascript/tsconfig.test.json b/packages/javascript/tsconfig.test.json index 166c4473..38db19a8 100644 --- a/packages/javascript/tsconfig.test.json +++ b/packages/javascript/tsconfig.test.json @@ -2,7 +2,8 @@ "extends": "./tsconfig.json", "compilerOptions": { "outDir": null, - "declaration": false + "declaration": false, + "types": ["vitest/globals"] }, "include": [ "src/**/*", diff --git a/yarn.lock b/yarn.lock index eacf26a2..a2aacdff 100644 --- a/yarn.lock +++ b/yarn.lock @@ -583,7 +583,7 @@ __metadata: languageName: node linkType: hard -"@hawk.so/core@workspace:packages/core": +"@hawk.so/core@workspace:^, @hawk.so/core@workspace:packages/core": version: 0.0.0-use.local resolution: "@hawk.so/core@workspace:packages/core" dependencies: @@ -596,6 +596,7 @@ __metadata: version: 0.0.0-use.local resolution: "@hawk.so/javascript@workspace:packages/javascript" dependencies: + "@hawk.so/core": "workspace:^" "@hawk.so/types": "npm:0.5.8" "@vitest/coverage-v8": "npm:^4.0.18" error-stack-parser: "npm:^2.1.4" From d0c4bffdca2dc526c8e3ca1209c72db6ac8b6c5a Mon Sep 17 00:00:00 2001 From: Reversean Date: Thu, 12 Feb 2026 20:59:50 +0300 Subject: [PATCH 4/6] refactor(core): HawkUserManager added --- .github/workflows/main.yml | 4 +- package.json | 2 + packages/core/package.json | 12 +++- packages/core/src/index.ts | 1 + packages/core/src/users/hawk-user-manager.ts | 71 ++++++++++++++++++ .../tests/users/hawk-user-manager.test.ts | 72 +++++++++++++++++++ packages/core/tsconfig.test.json | 13 ++++ packages/core/vitest.config.ts | 15 ++++ packages/javascript/src/catcher.ts | 57 ++++++--------- packages/javascript/vite.config.ts | 1 + packages/javascript/vitest.config.ts | 1 + yarn.lock | 3 + 12 files changed, 215 insertions(+), 37 deletions(-) create mode 100644 packages/core/src/users/hawk-user-manager.ts create mode 100644 packages/core/tests/users/hawk-user-manager.test.ts create mode 100644 packages/core/tsconfig.test.json create mode 100644 packages/core/vitest.config.ts diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index fade8851..1881dea1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -22,13 +22,15 @@ jobs: CI_JOB_NUMBER: 2 steps: - uses: actions/checkout@v1 + with: + fetch-depth: 0 - name: Use Node.js from .nvmrc uses: actions/setup-node@v6 with: node-version-file: '.nvmrc' - run: corepack enable - run: yarn install - - run: yarn workspace @hawk.so/javascript test + - run: yarn test:modified origin/${{ github.event.pull_request.base.ref }} build: runs-on: ubuntu-latest diff --git a/package.json b/package.json index 01c1ec1d..d59466ec 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,8 @@ "dev": "yarn workspace @hawk.so/javascript dev", "build:all": "yarn workspaces foreach -Apt run build", "build:modified": "yarn workspaces foreach --since=\"$@\" -Rpt run build", + "test:all": "yarn workspaces foreach -Apt run test", + "test:modified": "yarn workspaces foreach --since=\"$@\" -Rpt run test", "stats": "yarn workspace @hawk.so/javascript stats", "lint": "eslint -c ./.eslintrc.cjs packages/*/src --ext .ts,.js --fix", "lint-test": "eslint -c ./.eslintrc.cjs packages/*/src --ext .ts,.js" diff --git a/packages/core/package.json b/packages/core/package.json index e06be1d4..6797c920 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -17,7 +17,10 @@ } }, "scripts": { - "build": "vite build" + "build": "vite build", + "test": "vitest run", + "test:coverage": "vitest run --coverage", + "lint": "eslint --fix \"src/**/*.{js,ts}\"" }, "repository": { "type": "git", @@ -33,8 +36,13 @@ "url": "https://github.com/codex-team/hawk.javascript/issues" }, "homepage": "https://github.com/codex-team/hawk.javascript#readme", + "dependencies": { + "@hawk.so/types": "0.5.8" + }, "devDependencies": { + "@vitest/coverage-v8": "^4.0.18", "vite": "^7.3.1", - "vite-plugin-dts": "^4.2.4" + "vite-plugin-dts": "^4.2.4", + "vitest": "^4.0.18" } } diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 6a701ebc..1a05cf1f 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -1 +1,2 @@ export type { HawkStorage } from './storages/hawk-storage'; +export { HawkUserManager } from './users/hawk-user-manager'; diff --git a/packages/core/src/users/hawk-user-manager.ts b/packages/core/src/users/hawk-user-manager.ts new file mode 100644 index 00000000..7c965c33 --- /dev/null +++ b/packages/core/src/users/hawk-user-manager.ts @@ -0,0 +1,71 @@ +import type { AffectedUser } from '@hawk.so/types'; +import type { HawkStorage } from '../storages/hawk-storage'; + +/** + * Storage key used to persist the auto-generated user ID. + */ +export const HAWK_USER_ID_KEY = 'hawk-user-id'; + +/** + * Manages the affected user identity. + * + * Manually provided users are kept in memory only (they don't change restarts). + * {@link HawkStorage} is used solely to persist the auto-generated ID + * so it survives across sessions. + */ +export class HawkUserManager { + /** + * In-memory user set explicitly via {@link setUser}. + */ + private user: AffectedUser | null = null; + + /** + * Underlying storage used to persist auto-generated user ID. + */ + private readonly storage: HawkStorage; + + /** + * @param storage - Storage backend to use for persistence. + */ + constructor(storage: HawkStorage) { + this.storage = storage; + } + + /** + * Returns the current affected user, or `null` if none is available. + * + * Priority: in-memory user > persisted user ID. + */ + public getUser(): AffectedUser | null { + if (this.user) { + return this.user; + } + const storedId = this.storage.getItem(HAWK_USER_ID_KEY); + return storedId ? { id: storedId } : null; + } + + /** + * Sets the user explicitly (in memory only). + * + * @param user - The affected user provided by the application. + */ + public setUser(user: AffectedUser): void { + this.user = user; + } + + /** + * Persists an auto-generated user ID to storage. + * + * @param id - The generated ID to persist. + */ + public persistGeneratedId(id: string): void { + this.storage.setItem(HAWK_USER_ID_KEY, id); + } + + /** + * Clears the explicitly set user, falling back to the persisted user ID. + */ + public clear(): void { + this.user = null; + } +} diff --git a/packages/core/tests/users/hawk-user-manager.test.ts b/packages/core/tests/users/hawk-user-manager.test.ts new file mode 100644 index 00000000..3ef9a72f --- /dev/null +++ b/packages/core/tests/users/hawk-user-manager.test.ts @@ -0,0 +1,72 @@ +import { describe, it, expect, beforeEach, vi } from 'vitest'; +import { HawkUserManager } from '../../src'; +import type { HawkStorage } from '../../src'; + +describe('HawkUserManager', () => { + let storage: HawkStorage; + let manager: HawkUserManager; + + beforeEach(() => { + storage = { + getItem: vi.fn().mockReturnValue(null), + setItem: vi.fn(), + removeItem: vi.fn(), + }; + manager = new HawkUserManager(storage); + }); + + it('should return null when no user is set and storage is empty', () => { + expect(manager.getUser()).toBeNull(); + }); + + it('should return in-memory user set via setUser()', () => { + const user = { id: 'user-1', name: 'Ryan Gosling', url: 'https://example.com', photo: 'https://example.com/photo.png' }; + + manager.setUser(user); + + expect(manager.getUser()).toEqual(user); + expect(storage.setItem).not.toHaveBeenCalled(); + }); + + it('should not touch storage when setUser() is called', () => { + manager.setUser({ id: 'user-1' }); + + expect(storage.setItem).not.toHaveBeenCalled(); + expect(storage.removeItem).not.toHaveBeenCalled(); + }); + + it('should return anonymous user from storage when no in-memory user is set', () => { + vi.mocked(storage.getItem).mockReturnValue('anon-123'); + + expect(manager.getUser()).toEqual({ id: 'anon-123' }); + expect(storage.getItem).toHaveBeenCalledWith('hawk-user-id'); + }); + + it('should prefer in-memory user over persisted anonymous ID', () => { + vi.mocked(storage.getItem).mockReturnValue('anon-123'); + manager.setUser({ id: 'explicit-user' }); + + expect(manager.getUser()).toEqual({ id: 'explicit-user' }); + }); + + it('should persist anonymous ID via persistGeneratedId()', () => { + manager.persistGeneratedId('anon-456'); + + expect(storage.setItem).toHaveBeenCalledWith('hawk-user-id', 'anon-456'); + }); + + it('should clear in-memory user and fall back to persisted anonymous ID', () => { + vi.mocked(storage.getItem).mockReturnValue('anon-123'); + manager.setUser({ id: 'user-1' }); + manager.clear(); + + expect(manager.getUser()).toEqual({ id: 'anon-123' }); + }); + + it('should return null after clear() when no anonymous ID is persisted', () => { + manager.setUser({ id: 'user-1' }); + manager.clear(); + + expect(manager.getUser()).toBeNull(); + }); +}); diff --git a/packages/core/tsconfig.test.json b/packages/core/tsconfig.test.json new file mode 100644 index 00000000..38db19a8 --- /dev/null +++ b/packages/core/tsconfig.test.json @@ -0,0 +1,13 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": null, + "declaration": false, + "types": ["vitest/globals"] + }, + "include": [ + "src/**/*", + "tests/**/*", + "vitest.config.ts" + ] +} diff --git a/packages/core/vitest.config.ts b/packages/core/vitest.config.ts new file mode 100644 index 00000000..aee26683 --- /dev/null +++ b/packages/core/vitest.config.ts @@ -0,0 +1,15 @@ +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + test: { + globals: true, + include: ['tests/**/*.test.ts'], + typecheck: { + tsconfig: './tsconfig.test.json', + }, + coverage: { + provider: 'v8', + include: ['src/**/*.ts'], + }, + }, +}); diff --git a/packages/javascript/src/catcher.ts b/packages/javascript/src/catcher.ts index b18d8683..63bcb29b 100644 --- a/packages/javascript/src/catcher.ts +++ b/packages/javascript/src/catcher.ts @@ -4,7 +4,6 @@ import log from './utils/log'; import StackParser from './modules/stackParser'; import type { CatcherMessage, HawkInitialSettings, BreadcrumbsAPI, Transport } from './types'; import { VueIntegration } from './integrations/vue'; -import { id } from './utils/id'; import type { AffectedUser, EventContext, @@ -19,6 +18,9 @@ import { isErrorProcessed, markErrorAsProcessed } from './utils/event'; import { ConsoleCatcher } from './addons/consoleCatcher'; import { BreadcrumbManager } from './addons/breadcrumbs'; import { validateUser, validateContext, isValidEventPayload } from './utils/validation'; +import { HawkUserManager } from '@hawk.so/core'; +import { HawkLocalStorage } from './storages/hawk-local-storage'; +import { id } from './utils/id'; /** * Allow to use global VERSION, that will be overwritten by Webpack @@ -62,11 +64,6 @@ export default class Catcher { */ private readonly release: string | undefined; - /** - * Current authenticated user - */ - private user: AffectedUser; - /** * Any additional data passed by user for sending with all messages */ @@ -111,6 +108,11 @@ export default class Catcher { */ private readonly breadcrumbManager: BreadcrumbManager | null; + /** + * Current authenticated user manager instance + */ + private readonly userManager: HawkUserManager = new HawkUserManager(new HawkLocalStorage()); + /** * Catcher constructor * @@ -126,7 +128,9 @@ export default class Catcher { this.token = settings.token; this.debug = settings.debug || false; this.release = settings.release !== undefined ? String(settings.release) : undefined; - this.setUser(settings.user || Catcher.getGeneratedUser()); + if (settings.user) { + this.setUser(settings.user); + } this.setContext(settings.context || undefined); this.beforeSend = settings.beforeSend; this.disableVueErrorHandler = @@ -189,27 +193,6 @@ export default class Catcher { } } - /** - * Generates user if no one provided via HawkCatcher settings - * After generating, stores user for feature requests - */ - private static getGeneratedUser(): AffectedUser { - let userId: string; - const LOCAL_STORAGE_KEY = 'hawk-user-id'; - const storedId = localStorage.getItem(LOCAL_STORAGE_KEY); - - if (storedId) { - userId = storedId; - } else { - userId = id(); - localStorage.setItem(LOCAL_STORAGE_KEY, userId); - } - - return { - id: userId, - }; - } - /** * Send test event from client */ @@ -272,14 +255,14 @@ export default class Catcher { return; } - this.user = user; + this.userManager.setUser(user); } /** - * Clear current user information (revert to generated user) + * Clear current user information */ public clearUser(): void { - this.user = Catcher.getGeneratedUser(); + this.userManager.clear(); } /** @@ -565,10 +548,16 @@ export default class Catcher { } /** - * Current authenticated user + * Returns the current user if set, otherwise generates and persists an anonymous ID. */ - private getUser(): HawkJavaScriptEvent['user'] { - return this.user || null; + private getUser(): AffectedUser { + const user = this.userManager.getUser(); + if (user) { + return user; + } + const generatedId = id(); + this.userManager.persistGeneratedId(generatedId); + return { id: generatedId }; } /** diff --git a/packages/javascript/vite.config.ts b/packages/javascript/vite.config.ts index 47fe52e7..65b622e0 100644 --- a/packages/javascript/vite.config.ts +++ b/packages/javascript/vite.config.ts @@ -26,6 +26,7 @@ export default defineConfig(() => { fileName: 'hawk', }, rollupOptions: { + external: ['@hawk.so/core'], plugins: [ license({ thirdParty: { diff --git a/packages/javascript/vitest.config.ts b/packages/javascript/vitest.config.ts index 47ad6a2c..68e2cda4 100644 --- a/packages/javascript/vitest.config.ts +++ b/packages/javascript/vitest.config.ts @@ -14,5 +14,6 @@ export default defineConfig({ alias: { '@/types': path.resolve(__dirname, './src/types'), }, + conditions: ['source'], }, }); diff --git a/yarn.lock b/yarn.lock index a2aacdff..65b88ef1 100644 --- a/yarn.lock +++ b/yarn.lock @@ -587,8 +587,11 @@ __metadata: version: 0.0.0-use.local resolution: "@hawk.so/core@workspace:packages/core" dependencies: + "@hawk.so/types": "npm:0.5.8" + "@vitest/coverage-v8": "npm:^4.0.18" vite: "npm:^7.3.1" vite-plugin-dts: "npm:^4.2.4" + vitest: "npm:^4.0.18" languageName: unknown linkType: soft From 70d214e2bf57d0025e145cc1b90ba7c881f67d8e Mon Sep 17 00:00:00 2001 From: Reversean Date: Thu, 12 Feb 2026 21:30:14 +0300 Subject: [PATCH 5/6] refactor(core): Logger abstraction added --- packages/core/src/index.ts | 2 + packages/core/src/logger/logger.ts | 68 +++++++++++++++ packages/core/tests/logger/logger.test.ts | 86 +++++++++++++++++++ packages/javascript/src/addons/breadcrumbs.ts | 2 +- packages/javascript/src/catcher.ts | 13 ++- packages/javascript/src/logger/logger.ts | 61 +++++++++++++ packages/javascript/src/modules/fetchTimer.ts | 2 +- packages/javascript/src/modules/socket.ts | 2 +- .../src/storages/hawk-local-storage.ts | 2 +- packages/javascript/src/utils/event.ts | 2 +- packages/javascript/src/utils/log.ts | 46 ---------- packages/javascript/src/utils/validation.ts | 2 +- packages/javascript/tests/breadcrumbs.test.ts | 18 ++-- .../javascript/tests/logger/logger.test.ts | 78 +++++++++++++++++ .../javascript/tests/utils/validation.test.ts | 4 +- 15 files changed, 322 insertions(+), 66 deletions(-) create mode 100644 packages/core/src/logger/logger.ts create mode 100644 packages/core/tests/logger/logger.test.ts create mode 100644 packages/javascript/src/logger/logger.ts delete mode 100644 packages/javascript/src/utils/log.ts create mode 100644 packages/javascript/tests/logger/logger.test.ts diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 1a05cf1f..4781ef8f 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -1,2 +1,4 @@ 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'; diff --git a/packages/core/src/logger/logger.ts b/packages/core/src/logger/logger.ts new file mode 100644 index 00000000..c45dffaf --- /dev/null +++ b/packages/core/src/logger/logger.ts @@ -0,0 +1,68 @@ +/** + * 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; + +/** + * Checks if logger instance has been registered. + */ +export function isLoggerSet(): boolean { + return loggerInstance !== 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; +} + +/** + * Clears the registered logger instance. + */ +export function resetLogger(): void { + loggerInstance = null; +} + +/** + * 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); + } +} diff --git a/packages/core/tests/logger/logger.test.ts b/packages/core/tests/logger/logger.test.ts new file mode 100644 index 00000000..0d79fdb7 --- /dev/null +++ b/packages/core/tests/logger/logger.test.ts @@ -0,0 +1,86 @@ +import { describe, it, expect, vi, beforeEach } from 'vitest'; + +/** + * Each test gets a fresh module instance via vi.resetModules() so that + * the module-level loggerInstance starts as null. + */ +describe('Logger', () => { + beforeEach(() => { + vi.resetModules(); + }); + + it('should return false from isLoggerSet when no logger has been registered', async () => { + const { isLoggerSet } = await import('../../src/logger/logger'); + + expect(isLoggerSet()).toBe(false); + }); + + it('should return true from isLoggerSet after setLogger is called', async () => { + const { isLoggerSet, setLogger } = await import('../../src/logger/logger'); + + setLogger(vi.fn()); + + expect(isLoggerSet()).toBe(true); + }); + + it('should not throw when log is called with no logger registered', async () => { + const { log } = await import('../../src/logger/logger'); + + expect(() => log('test message')).not.toThrow(); + }); + + it('should forward msg, type, and args to the registered logger', async () => { + const { setLogger, log } = await import('../../src/logger/logger'); + const mockLogger = vi.fn(); + + setLogger(mockLogger); + log('something went wrong', 'warn', { code: 42 }); + + expect(mockLogger).toHaveBeenCalledOnce(); + expect(mockLogger).toHaveBeenCalledWith('something went wrong', 'warn', { code: 42 }); + }); + + it('should pass undefined for omitted type and args', async () => { + const { setLogger, log } = await import('../../src/logger/logger'); + const mockLogger = vi.fn(); + + setLogger(mockLogger); + log('simple'); + + expect(mockLogger).toHaveBeenCalledWith('simple', undefined, undefined); + }); + + it('should replace a previously registered logger when setLogger is called again', async () => { + const { setLogger, log } = await import('../../src/logger/logger'); + const first = vi.fn(); + const second = vi.fn(); + + setLogger(first); + setLogger(second); + log('msg'); + + expect(first).not.toHaveBeenCalled(); + expect(second).toHaveBeenCalledWith('msg', undefined, undefined); + }); + + it('should clear the registered logger when resetLogger is called', async () => { + const { isLoggerSet, setLogger, resetLogger } = await import('../../src/logger/logger'); + + setLogger(vi.fn()); + expect(isLoggerSet()).toBe(true); + + resetLogger(); + expect(isLoggerSet()).toBe(false); + }); + + it('should become a no-op after resetLogger is called', async () => { + const { setLogger, resetLogger, log } = await import('../../src/logger/logger'); + const mockLogger = vi.fn(); + + setLogger(mockLogger); + resetLogger(); + log('msg'); + + expect(mockLogger).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/javascript/src/addons/breadcrumbs.ts b/packages/javascript/src/addons/breadcrumbs.ts index faa14a8e..1e4f0b9b 100644 --- a/packages/javascript/src/addons/breadcrumbs.ts +++ b/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'; /** diff --git a/packages/javascript/src/catcher.ts b/packages/javascript/src/catcher.ts index 63bcb29b..42b4bff1 100644 --- a/packages/javascript/src/catcher.ts +++ b/packages/javascript/src/catcher.ts @@ -1,9 +1,9 @@ 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'; +import { id } from './utils/id'; import type { AffectedUser, EventContext, @@ -18,15 +18,22 @@ import { isErrorProcessed, markErrorAsProcessed } from './utils/event'; import { ConsoleCatcher } from './addons/consoleCatcher'; import { BreadcrumbManager } from './addons/breadcrumbs'; import { validateUser, validateContext, isValidEventPayload } from './utils/validation'; -import { HawkUserManager } from '@hawk.so/core'; +import { HawkUserManager, setLogger, isLoggerSet, log } from '@hawk.so/core'; import { HawkLocalStorage } from './storages/hawk-local-storage'; -import { id } from './utils/id'; +import { createBrowserLogger } from "./logger/logger"; /** * Allow to use global VERSION, that will be overwritten by Webpack */ declare const VERSION: string; +/** + * Registers a global logger instance if not already done. + */ +if (!isLoggerSet()) { + setLogger(createBrowserLogger(VERSION)); +} + /** * Hawk JavaScript Catcher * Module for errors and exceptions tracking diff --git a/packages/javascript/src/logger/logger.ts b/packages/javascript/src/logger/logger.ts new file mode 100644 index 00000000..922f9aec --- /dev/null +++ b/packages/javascript/src/logger/logger.ts @@ -0,0 +1,61 @@ +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} Logger function implementation for browser environments. + * + * @example + * ```TypeScript + * import { createBrowserLogger } from '@hawk.so/javascript'; + * 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'); + * setLogger(styledLogger); + * ``` + */ +export function createBrowserLogger(version: string, style = 'color: inherit'): Logger { + return (msg: string, type: LogType = 'log', args?: unknown): void => { + if (!('console' in window)) { + return; + } + + const editorLabelText = `Hawk (${version})`; + const editorLabelStyle = `line-height: 1em; + color: #fff; + display: inline-block; + background-color: rgba(0,0,0,.7); + padding: 3px 5px; + border-radius: 3px; + margin-right: 2px`; + + try { + switch (type) { + case 'time': + case 'timeEnd': + console[type](`( ${editorLabelText} ) ${msg}`); + break; + case 'log': + case 'warn': + case 'error': + case 'info': + if (args !== undefined) { + console[type](`%c${editorLabelText}%c ${msg} %o`, editorLabelStyle, style, args); + } else { + console[type](`%c${editorLabelText}%c ${msg}`, editorLabelStyle, style); + } + break; + } + } catch (ignored) {} + }; +} diff --git a/packages/javascript/src/modules/fetchTimer.ts b/packages/javascript/src/modules/fetchTimer.ts index bd32bd6c..a17c1d47 100644 --- a/packages/javascript/src/modules/fetchTimer.ts +++ b/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. diff --git a/packages/javascript/src/modules/socket.ts b/packages/javascript/src/modules/socket.ts index eb64b599..cbc662aa 100644 --- a/packages/javascript/src/modules/socket.ts +++ b/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'; diff --git a/packages/javascript/src/storages/hawk-local-storage.ts b/packages/javascript/src/storages/hawk-local-storage.ts index c0362ea9..753c73b4 100644 --- a/packages/javascript/src/storages/hawk-local-storage.ts +++ b/packages/javascript/src/storages/hawk-local-storage.ts @@ -1,5 +1,5 @@ import type { HawkStorage } from '@hawk.so/core'; -import log from '../utils/log.ts'; +import { log } from '@hawk.so/core'; /** * {@link HawkStorage} implementation backed by the browser's {@linkcode localStorage}. diff --git a/packages/javascript/src/utils/event.ts b/packages/javascript/src/utils/event.ts index 3882c272..63741533 100644 --- a/packages/javascript/src/utils/event.ts +++ b/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 diff --git a/packages/javascript/src/utils/log.ts b/packages/javascript/src/utils/log.ts deleted file mode 100644 index 4087d903..00000000 --- a/packages/javascript/src/utils/log.ts +++ /dev/null @@ -1,46 +0,0 @@ -/** - * Logger module - * - * @example - * log('We got an error', 'error') - */ - -/** - * Allow to use global VERSION, that will be overwritten by Webpack - */ -declare const VERSION: string; - -/** - * Custom logger - * - * @param {string} msg - message - * @param {string} type - logging type 'log'|'warn'|'error'|'info' - * @param {*} [args] - argument to log with a message - * @param {string} style - additional styling to message - */ -// eslint-disable-next-line @typescript-eslint/no-explicit-any -export default function log(msg: string, type = 'log', args?: any, style = 'color: inherit'): 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) {} -} diff --git a/packages/javascript/src/utils/validation.ts b/packages/javascript/src/utils/validation.ts index c0f9f664..293cafc6 100644 --- a/packages/javascript/src/utils/validation.ts +++ b/packages/javascript/src/utils/validation.ts @@ -1,4 +1,4 @@ -import log from './log'; +import { log } from '@hawk.so/core'; import type { AffectedUser, Breadcrumb, EventContext, EventData, JavaScriptAddons } from '@hawk.so/types'; import Sanitizer from '../modules/sanitizer'; diff --git a/packages/javascript/tests/breadcrumbs.test.ts b/packages/javascript/tests/breadcrumbs.test.ts index f02d7dcb..7afec05c 100644 --- a/packages/javascript/tests/breadcrumbs.test.ts +++ b/packages/javascript/tests/breadcrumbs.test.ts @@ -1,6 +1,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import { BreadcrumbManager } from '../src/addons/breadcrumbs'; import type { Breadcrumb } from '@hawk.so/types'; +import * as core from '@hawk.so/core'; function resetManager(): void { // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -8,15 +9,15 @@ function resetManager(): void { } describe('BreadcrumbManager', () => { - let warnSpy: ReturnType; + let logSpy: ReturnType; beforeEach(() => { resetManager(); - warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + logSpy = vi.spyOn(core, 'log').mockImplementation(() => {}); }); afterEach(() => { - warnSpy.mockRestore(); + logSpy.mockRestore(); }); it('should return empty array when no breadcrumbs added', () => { @@ -118,15 +119,15 @@ describe('BreadcrumbManager', () => { }); describe('beforeBreadcrumb', () => { - let warnSpy: ReturnType; + let logSpy: ReturnType; beforeEach(() => { resetManager(); - warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + logSpy = vi.spyOn(core, 'log').mockImplementation(() => {}); }); afterEach(() => { - warnSpy.mockRestore(); + logSpy.mockRestore(); }); it('should store modified breadcrumb when hook returns changed object', () => { @@ -183,10 +184,9 @@ describe('beforeBreadcrumb', () => { // Assert expect(m.getBreadcrumbs()[0].message).toBe('original'); - expect(warnSpy).toHaveBeenCalledWith( + expect(logSpy).toHaveBeenCalledWith( expect.stringContaining('Invalid beforeBreadcrumb value'), - expect.anything(), - expect.anything() + 'warn' ); }); diff --git a/packages/javascript/tests/logger/logger.test.ts b/packages/javascript/tests/logger/logger.test.ts new file mode 100644 index 00000000..df4477bc --- /dev/null +++ b/packages/javascript/tests/logger/logger.test.ts @@ -0,0 +1,78 @@ +import { beforeEach, afterEach, describe, it, expect, vi } from 'vitest'; +import { createBrowserLogger } from '../../src/logger/logger'; + +describe('createBrowserLogger', () => { + let consoleLogSpy: ReturnType; + let consoleWarnSpy: ReturnType; + let consoleErrorSpy: ReturnType; + + 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(); + }); +}); diff --git a/packages/javascript/tests/utils/validation.test.ts b/packages/javascript/tests/utils/validation.test.ts index e277815a..20d02944 100644 --- a/packages/javascript/tests/utils/validation.test.ts +++ b/packages/javascript/tests/utils/validation.test.ts @@ -1,8 +1,8 @@ import { describe, it, expect, vi } from 'vitest'; import { validateUser, validateContext, isValidEventPayload, isValidBreadcrumb } from '../../src/utils/validation'; -// Suppress console output produced by log() calls inside validation failures. -vi.mock('../src/utils/log', () => ({ default: vi.fn() })); +// 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() })); describe('validateUser', () => { it('should return false when user is null', () => { From b4018fb5a3da2bdefccac9bc0be0c4a09924d7a7 Mon Sep 17 00:00:00 2001 From: Reversean Date: Tue, 3 Mar 2026 19:52:18 +0300 Subject: [PATCH 6/6] refactor(core): Extract shared modules and utilities --- packages/{javascript => core}/src/errors.ts | 0 packages/core/src/index.ts | 7 +++ .../src/modules/fetch-timer.ts} | 0 .../src/modules/sanitizer.ts | 6 ++- .../src/modules/stack-parser.ts} | 10 ++-- packages/core/src/transports/transport.ts | 9 ++++ .../{javascript => core}/src/utils/event.ts | 8 +-- .../src/utils/selector.ts | 0 .../src/utils/validation.ts | 41 ++++++-------- .../tests/utils/validation.test.ts | 2 +- packages/javascript/src/addons/breadcrumbs.ts | 5 +- .../javascript/src/addons/consoleCatcher.ts | 2 +- packages/javascript/src/catcher.ts | 45 +++++++++------- packages/javascript/src/modules/socket.ts | 3 +- .../javascript/src/types/catcher-message.ts | 19 +------ packages/javascript/src/types/event.ts | 53 +------------------ .../src/types/hawk-initial-settings.ts | 2 +- packages/javascript/src/types/transport.ts | 7 ++- 18 files changed, 83 insertions(+), 136 deletions(-) rename packages/{javascript => core}/src/errors.ts (100%) rename packages/{javascript/src/modules/fetchTimer.ts => core/src/modules/fetch-timer.ts} (100%) rename packages/{javascript => core}/src/modules/sanitizer.ts (98%) rename packages/{javascript/src/modules/stackParser.ts => core/src/modules/stack-parser.ts} (95%) create mode 100644 packages/core/src/transports/transport.ts rename packages/{javascript => core}/src/utils/event.ts (80%) rename packages/{javascript => core}/src/utils/selector.ts (100%) rename packages/{javascript => core}/src/utils/validation.ts (67%) rename packages/{javascript => core}/tests/utils/validation.test.ts (98%) diff --git a/packages/javascript/src/errors.ts b/packages/core/src/errors.ts similarity index 100% rename from packages/javascript/src/errors.ts rename to packages/core/src/errors.ts diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 4781ef8f..c9c0b32e 100644 --- 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/javascript/src/modules/fetchTimer.ts b/packages/core/src/modules/fetch-timer.ts similarity index 100% rename from packages/javascript/src/modules/fetchTimer.ts rename to packages/core/src/modules/fetch-timer.ts diff --git a/packages/javascript/src/modules/sanitizer.ts b/packages/core/src/modules/sanitizer.ts similarity index 98% rename from packages/javascript/src/modules/sanitizer.ts rename to packages/core/src/modules/sanitizer.ts index a02172d0..dadd3fff 100644 --- a/packages/javascript/src/modules/sanitizer.ts +++ b/packages/core/src/modules/sanitizer.ts @@ -1,4 +1,6 @@ /* 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 @@ -6,7 +8,7 @@ * - represent big objects as "" * - represent class as or */ -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/javascript/src/modules/stackParser.ts b/packages/core/src/modules/stack-parser.ts similarity index 95% rename from packages/javascript/src/modules/stackParser.ts rename to packages/core/src/modules/stack-parser.ts index f7ee32f8..8ea7518c 100644 --- a/packages/javascript/src/modules/stackParser.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 { + private async loadSourceFile(fileName: string): Promise { 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 new file mode 100644 index 00000000..5ed26727 --- /dev/null +++ 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 { + send(message: CatcherMessage): Promise; +} diff --git a/packages/javascript/src/utils/event.ts b/packages/core/src/utils/event.ts similarity index 80% rename from packages/javascript/src/utils/event.ts rename to packages/core/src/utils/event.ts index 63741533..ad381418 100644 --- a/packages/javascript/src/utils/event.ts +++ b/packages/core/src/utils/event.ts @@ -1,4 +1,4 @@ -import { log } from '@hawk.so/core'; +import { log } from '../logger/logger'; /** * Symbol to mark error as processed by Hawk @@ -6,7 +6,7 @@ import { log } from '@hawk.so/core'; 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)[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/javascript/src/utils/selector.ts b/packages/core/src/utils/selector.ts similarity index 100% rename from packages/javascript/src/utils/selector.ts rename to packages/core/src/utils/selector.ts diff --git a/packages/javascript/src/utils/validation.ts b/packages/core/src/utils/validation.ts similarity index 67% rename from packages/javascript/src/utils/validation.ts rename to packages/core/src/utils/validation.ts index 293cafc6..7fd45185 100644 --- a/packages/javascript/src/utils/validation.ts +++ b/packages/core/src/utils/validation.ts @@ -1,6 +1,12 @@ -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 { + return Object.prototype.toString.call(value) === '[object Object]'; +} /** * Validates user data - basic security checks @@ -8,7 +14,7 @@ import Sanitizer from '../modules/sanitizer'; * @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 { - 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 { +export function isValidEventPayload(payload: unknown): payload is EventData { if (!isPlainObject(payload)) { return false; } @@ -64,11 +61,7 @@ export function isValidEventPayload(payload: unknown): payload is EventData ({ 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 index 1e4f0b9b..972ba205 100644 --- 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 index 29519eaa..f5742b7e 100644 --- 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 index 42b4bff1..04d95a13 100644 --- 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,7 +622,7 @@ export default class Catcher { * and reject() provided with text reason instead of Error() */ if (notAnError) { - return null; + return undefined; } try { @@ -621,7 +630,7 @@ export default class Catcher { } 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 index cbc662aa..ed3c1947 100644 --- 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 index d892e22a..84507534 100644 --- 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 index 82dec497..89eee08c 100644 --- a/packages/javascript/src/types/event.ts +++ b/packages/javascript/src/types/event.ts @@ -1,55 +1,6 @@ -import type { AffectedUser, BacktraceFrame, EventContext, EventData, JavaScriptAddons, Breadcrumb } from '@hawk.so/types'; - -/** - * Event data with JS specific addons - */ -type JSEventData = EventData; +import type { CatcherMessagePayload } from '@hawk.so/types'; /** * Event will be sent to Hawk by Hawk JavaScript SDK - * - * The listed EventData properties will always be sent, so we define them as required in the type */ -export type HawkJavaScriptEvent = Omit & { - /** - * Event type: TypeError, ReferenceError etc - * null for non-error events - */ - type: string | null; - - /** - * Current release (aka version, revision) of an application - */ - release: string | null; - - /** - * Breadcrumbs - chronological trail of events before the error - */ - breadcrumbs: Breadcrumb[] | null; - - /** - * Current authenticated user - */ - user: AffectedUser | null; - - /** - * Any other information collected and passed by user - */ - context: EventContext; - - /** - * Catcher-specific information - */ - addons: JavaScriptAddons; - - /** - * Stack - * From the latest call to the earliest - */ - backtrace: BacktraceFrame[] | null; - - /** - * Catcher version - */ - catcherVersion: string; -}; +export type HawkJavaScriptEvent = CatcherMessagePayload<'errors/javascript'>; diff --git a/packages/javascript/src/types/hawk-initial-settings.ts b/packages/javascript/src/types/hawk-initial-settings.ts index 987cdf4c..96b7fc75 100644 --- a/packages/javascript/src/types/hawk-initial-settings.ts +++ b/packages/javascript/src/types/hawk-initial-settings.ts @@ -1,6 +1,6 @@ import type { EventContext, AffectedUser } from '@hawk.so/types'; import type { HawkJavaScriptEvent } from './event'; -import type { Transport } from './transport'; +import type { Transport } from '@/types'; import type { BreadcrumbsOptions } from '../addons/breadcrumbs'; /** diff --git a/packages/javascript/src/types/transport.ts b/packages/javascript/src/types/transport.ts index f2237dca..c8df0709 100644 --- a/packages/javascript/src/types/transport.ts +++ b/packages/javascript/src/types/transport.ts @@ -1,8 +1,7 @@ -import type { CatcherMessage } from './catcher-message'; +import type { Transport as HawkTransport } from '@hawk.so/core'; /** - * Transport interface — anything that can send a CatcherMessage + * Transport interface — anything that can send a {@link CatcherMessage}. */ -export interface Transport { - send(message: CatcherMessage): Promise; +export interface Transport extends HawkTransport<'errors/javascript'> { }