Merge pull request #158 from codex-team/refactor/user-manager

UserManager abstraction added

Author: Reversean

.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

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"

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"
   }
 }

packages/core/src/index.ts

@@ -1 +1,3 @@
 export type { HawkStorage } from './storages/hawk-storage';
+export type { RandomGenerator } from './utils/random';
+export { HawkUserManager } from './users/hawk-user-manager';

packages/core/src/users/hawk-user-manager.ts

@@ -0,0 +1,88 @@
+import type { AffectedUser } from '@hawk.so/types';
+import type { HawkStorage } from '../storages/hawk-storage';
+import { id } from '../utils/id';
+import type { RandomGenerator } from '../utils/random';
+
+/**
+ * Storage key used to persist the auto-generated user ID.
+ */
+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.
+ *
+ * @remarks changes to user data in storage from outside manager are not tracked;
+ * for changes to take effect call {@link clear}.
+ */
+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;
+
+  /**
+   * Random generator used to produce anonymous user IDs.
+   */
+  private readonly randomGenerator: RandomGenerator;
+
+  /**
+   * @param storage - storage backend to use for persistence
+   * @param randomGenerator - utilities related to RandomGenerator generated values
+   */
+  constructor(
+    storage: HawkStorage,
+    randomGenerator: RandomGenerator
+  ) {
+    this.storage = storage;
+    this.randomGenerator = randomGenerator;
+  }
+
+  /**
+   * Returns current affected user if set, otherwise generates and persists an anonymous ID.
+   *
+   * Priority: in-memory user > persisted user ID.
+   *
+   * @returns set affected user or user with generated ID
+   */
+  public getUser(): AffectedUser {
+    if (this.user) {
+      return this.user;
+    }
+
+    let storedId = this.storage.getItem(HAWK_USER_ID_KEY);
+
+    if (!storedId) {
+      storedId = id(this.randomGenerator);
+      this.storage.setItem(HAWK_USER_ID_KEY, storedId);
+    }
+
+    this.user = { id: storedId };
+
+    return this.user!;
+  }
+
+  /**
+   * Sets the user explicitly (in memory only).
+   *
+   * @param user - The affected user provided by the application.
+   */
+  public setUser(user: AffectedUser): void {
+    this.user = user;
+  }
+
+  /**
+   * Clears the explicitly set user, falling back to the persisted user ID.
+   */
+  public clear(): void {
+    this.user = null;
+  }
+}

packages/core/src/utils/id.ts

@@ -0,0 +1,16 @@
+import type { RandomGenerator } from './random';
+
+/**
+ * Returns random string
+ *
+ * @param random
+ */
+export function id(random: RandomGenerator): string {
+  const validChars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+  const randomSequence = random
+    .getRandomNumbers(40)
+    .map(x => validChars.charCodeAt(x % validChars.length));
+
+  return String.fromCharCode.apply(null, randomSequence);
+}

packages/core/src/utils/random.ts

@@ -0,0 +1,13 @@
+/**
+ * Abstraction over random value generator.
+ * Allows platform-specific implementations to be injected wherever random values are needed.
+ */
+export interface RandomGenerator {
+    /**
+     * Generates sequence of random unsigned numbers.
+     *
+     * @param length - Length of generated sequence.
+     * @returns Array filled with random unsigned numbers.
+     */
+    getRandomNumbers(length: number): Uint8Array<ArrayBuffer>;
+}

packages/core/tests/users/hawk-user-manager.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { HawkUserManager } from '../../src';
+import type { HawkStorage, RandomGenerator } from '../../src';
+
+describe('HawkUserManager', () => {
+  let storage: HawkStorage;
+  let randomGenerator: RandomGenerator;
+  let manager: HawkUserManager;
+
+  beforeEach(() => {
+    storage = {
+      getItem: vi.fn().mockReturnValue(null),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    };
+    randomGenerator = {
+      getRandomNumbers: vi.fn().mockReturnValue(new Uint8Array(40).fill(42)),
+    };
+    manager = new HawkUserManager(storage, randomGenerator);
+  });
+
+  it('should return anonymous ID when no user is set and no ID is persisted', () => {
+    const user = manager.getUser();
+
+    expect(user.id).toBeTruthy();
+    expect(storage.setItem).toHaveBeenCalledWith('hawk-user-id', user.id);
+  });
+
+  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 affect 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 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 new anonymous ID after clear() when no ID is persisted', () => {
+    manager.setUser({ id: 'user-1' });
+    manager.clear();
+
+    const user = manager.getUser();
+
+    expect(user.id).toBeTruthy();
+    expect(storage.setItem).toHaveBeenCalledWith('hawk-user-id', user.id);
+  });
+});

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"
+  ]
+}

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