HawkStorage abstraction added

packages/core/src/index.ts

@@ -0,0 +1 @@
+export type { HawkStorage } from './storages/hawk-storage';

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;
+}

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": {

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);
+    }
+  }
+}

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();
+  });
+});

packages/javascript/tsconfig.test.json

@@ -2,7 +2,8 @@
   "extends": "./tsconfig.json",
   "compilerOptions": {
     "outDir": null,
-    "declaration": false
+    "declaration": false,
+    "types": ["vitest/globals"]
   },
   "include": [
     "src/**/*",

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"