refactor: implement epoch clock logic (#1204)

Author: BioPhoton

packages/utils/src/lib/clock-epoch.int.test.ts

@@ -0,0 +1,99 @@
+import process from 'node:process';
+import { threadId } from 'node:worker_threads';
+import { describe, expect, it } from 'vitest';
+import { defaultClock, epochClock } from './clock-epoch.js';
+
+describe('epochClock', () => {
+  it('should create epoch clock with defaults', () => {
+    const c = epochClock();
+    expect(c).toStrictEqual(
+      expect.objectContaining({
+        tid: threadId,
+        pid: process.pid,
+        timeOriginMs: performance.timeOrigin,
+      }),
+    );
+    expect(c.fromEpochMs).toBeFunction();
+    expect(c.fromEpochUs).toBeFunction();
+    expect(c.fromPerfMs).toBeFunction();
+    expect(c.fromEntryStartTimeMs).toBeFunction();
+    expect(c.fromDateNowMs).toBeFunction();
+  });
+
+  it('should support performance clock by default for epochNowUs', () => {
+    const c = epochClock();
+    expect(c.timeOriginMs).toBe(performance.timeOrigin);
+    const nowUs = c.epochNowUs();
+    expect(nowUs).toBe(Math.round(nowUs));
+    const expectedUs = Date.now() * 1000;
+
+    expect(nowUs).toBeWithin(expectedUs - 2000, expectedUs + 1000);
+  });
+
+  it('should convert epoch milliseconds to microseconds correctly', () => {
+    const c = epochClock();
+    const epochMs = Date.now();
+
+    const result = c.fromEpochMs(epochMs);
+    expect(result).toBeInteger();
+    expect(result).toBe(Math.round(epochMs * 1000));
+  });
+
+  it('should convert epoch microseconds to microseconds correctly', () => {
+    const c = epochClock();
+    const epochUs = Date.now() * 1000;
+    const expectedUs = Math.round(epochUs);
+
+    const result = c.fromEpochUs(epochUs);
+    expect(result).toBe(expectedUs);
+    expect(result).toBe(Math.round(result));
+  });
+
+  it('should convert performance milliseconds to epoch microseconds correctly', () => {
+    const c = epochClock();
+    const perfMs = performance.now();
+    const expectedUs = Math.round((c.timeOriginMs + perfMs) * 1000);
+
+    const result = c.fromPerfMs(perfMs);
+    expect(result).toBe(expectedUs);
+    expect(result).toBeInteger();
+  });
+
+  it('should convert entry start time milliseconds to epoch microseconds correctly', () => {
+    const c = epochClock();
+    const entryStartMs = performance.mark('fromPerfMs').startTime;
+    const expectedUs = Math.round((c.timeOriginMs + entryStartMs) * 1000);
+
+    const result = c.fromEntryStartTimeMs(entryStartMs);
+    expect(result).toBe(expectedUs);
+    expect(result).toBe(Math.round(result));
+  });
+
+  it('should convert Date.now milliseconds to epoch microseconds correctly', () => {
+    const c = epochClock();
+    const dateNowMs = Date.now();
+
+    const result = c.fromDateNowMs(dateNowMs);
+    expect(result).toBe(Math.round(dateNowMs * 1000));
+    expect(result).toBe(Math.round(result));
+  });
+});
+
+describe('defaultClock', () => {
+  it('should have valid defaultClock export', () => {
+    const c = defaultClock;
+    expect(c).toStrictEqual(
+      expect.objectContaining({
+        tid: threadId,
+        pid: process.pid,
+        timeOriginMs: performance.timeOrigin,
+      }),
+    );
+
+    expect(c.fromEpochMs).toBeFunction();
+    expect(c.fromEpochUs).toBeFunction();
+    expect(c.fromPerfMs).toBeFunction();
+    expect(c.fromEntryStartTimeMs).toBeFunction();
+    expect(c.fromDateNowMs).toBeFunction();
+  });
+});

packages/utils/src/lib/clock-epoch.ts

@@ -0,0 +1,63 @@
+import process from 'node:process';
+import { threadId } from 'node:worker_threads';
+
+export type Microseconds = number;
+export type Milliseconds = number;
+
+const msToUs = (ms: number): Microseconds => Math.round(ms * 1000);
+const usToUs = (us: number): Microseconds => Math.round(us);
+
+/**
+ * Defines clock utilities for time conversions.
+ * Handles time origins in NodeJS and the Browser
+ * Provides process and thread IDs.
+ * @param init
+ */
+export type EpochClockOptions = {
+  pid?: number;
+  tid?: number;
+};
+
+/**
+ * Creates epoch-based clock utility.
+ * Epoch time has been the time since January 1, 1970 (UNIX epoch).
+ * Date.now gives epoch time in milliseconds.
+ * performance.now() + performance.timeOrigin when available is used for higher precision.
+ */
+export function epochClock(init: EpochClockOptions = {}) {
+  const pid = init.pid ?? process.pid;
+  const tid = init.tid ?? threadId;
+
+  const timeOriginMs = performance.timeOrigin;
+
+  const epochNowUs = (): Microseconds =>
+    msToUs(timeOriginMs + performance.now());
+
+  const fromEpochUs = usToUs;
+
+  const fromEpochMs = msToUs;
+
+  const fromPerfMs = (perfMs: Milliseconds): Microseconds =>
+    msToUs(timeOriginMs + perfMs);
+
+  const fromEntryStartTimeMs = fromPerfMs;
+  const fromDateNowMs = fromEpochMs;
+
+  return {
+    timeOriginMs,
+    pid,
+    tid,
+
+    epochNowUs,
+    msToUs,
+    usToUs,
+
+    fromEpochMs,
+    fromEpochUs,
+    fromPerfMs,
+    fromEntryStartTimeMs,
+    fromDateNowMs,
+  };
+}
+
+export const defaultClock = epochClock();

packages/utils/src/lib/clock-epoch.unit.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import { defaultClock, epochClock } from './clock-epoch.js';
+
+describe('epochClock', () => {
+  it('should create epoch clock with defaults', () => {
+    const c = epochClock();
+    expect(c.timeOriginMs).toBe(500_000);
+    expect(c.tid).toBe(2);
+    expect(c.pid).toBe(10_001);
+    expect(c.fromEpochMs).toBeFunction();
+    expect(c.fromEpochUs).toBeFunction();
+    expect(c.fromPerfMs).toBeFunction();
+    expect(c.fromEntryStartTimeMs).toBeFunction();
+    expect(c.fromDateNowMs).toBeFunction();
+  });
+
+  it('should use pid options', () => {
+    expect(epochClock({ pid: 999 })).toStrictEqual(
+      expect.objectContaining({
+        pid: 999,
+      }),
+    );
+  });
+
+  it('should use tid options', () => {
+    expect(epochClock({ tid: 888 })).toStrictEqual(
+      expect.objectContaining({
+        tid: 888,
+      }),
+    );
+  });
+
+  it('should support performance clock by default for epochNowUs', () => {
+    const c = epochClock();
+    expect(c.timeOriginMs).toBe(500_000);
+    expect(c.epochNowUs()).toBe(1_000_000_000); // timeOrigin + (Date.now() - timeOrigin) = Date.now()
+  });
+
+  it.each([
+    [1_000_000_000, 1_000_000_000],
+    [1_001_000_000, 1_001_000_000],
+    [999_000_000, 999_000_000],
+  ])('should convert epoch microseconds to microseconds', (us, result) => {
+    const c = epochClock();
+    expect(c.fromEpochUs(us)).toBe(result);
+  });
+
+  it.each([
+    [1_000_000, 1_000_000_000],
+    [1_001_000.5, 1_001_000_500],
+    [999_000.4, 999_000_400],
+  ])('should convert epoch milliseconds to microseconds', (ms, result) => {
+    const c = epochClock();
+    expect(c.fromEpochMs(ms)).toBe(result);
+  });
+
+  it.each([
+    [0, 500_000_000],
+    [1000, 501_000_000],
+  ])(
+    'should convert performance milliseconds to microseconds',
+    (perfMs, expected) => {
+      expect(epochClock().fromPerfMs(perfMs)).toBe(expected);
+    },
+  );
+
+  it('should convert entry start time to microseconds', () => {
+    const c = epochClock();
+    expect([
+      c.fromEntryStartTimeMs(0),
+      c.fromEntryStartTimeMs(1000),
+    ]).toStrictEqual([c.fromPerfMs(0), c.fromPerfMs(1000)]);
+  });
+
+  it('should convert Date.now() milliseconds to microseconds', () => {
+    const c = epochClock();
+    expect([
+      c.fromDateNowMs(1_000_000),
+      c.fromDateNowMs(2_000_000),
+    ]).toStrictEqual([1_000_000_000, 2_000_000_000]);
+  });
+
+  it('should maintain conversion consistency', () => {
+    const c = epochClock();
+
+    expect({
+      fromEpochUs_2B: c.fromEpochUs(2_000_000_000),
+      fromEpochMs_2M: c.fromEpochMs(2_000_000),
+      fromEpochUs_1B: c.fromEpochUs(1_000_000_000),
+      fromEpochMs_1M: c.fromEpochMs(1_000_000),
+    }).toStrictEqual({
+      fromEpochUs_2B: 2_000_000_000,
+      fromEpochMs_2M: 2_000_000_000,
+      fromEpochUs_1B: 1_000_000_000,
+      fromEpochMs_1M: 1_000_000_000,
+    });
+  });
+
+  it.each([
+    [1_000_000_000.1, 1_000_000_000],
+    [1_000_000_000.4, 1_000_000_000],
+    [1_000_000_000.5, 1_000_000_001],
+    [1_000_000_000.9, 1_000_000_001],
+  ])('should round microseconds correctly', (value, result) => {
+    const c = epochClock();
+    expect(c.fromEpochUs(value)).toBe(result);
+  });
+});
+
+describe('defaultClock', () => {
+  it('should have valid defaultClock export', () => {
+    expect({
+      tid: typeof defaultClock.tid,
+      timeOriginMs: typeof defaultClock.timeOriginMs,
+    }).toStrictEqual({
+      tid: 'number',
+      timeOriginMs: 'number',
+    });
+  });
+});

testing/test-setup-config/src/lib/vitest-setup-files.ts

@@ -25,6 +25,8 @@ const UNIT_TEST_SETUP_FILES = [
   '../../testing/test-setup/src/lib/logger.mock.ts',
   '../../testing/test-setup/src/lib/git.mock.ts',
   '../../testing/test-setup/src/lib/portal-client.mock.ts',
+  '../../testing/test-setup/src/lib/process.setup-file.ts',
+  '../../testing/test-setup/src/lib/clock.setup-file.ts',
   ...CUSTOM_MATCHERS,
 ] as const;
 

testing/test-setup/src/lib/clock.setup-file.ts

@@ -0,0 +1,37 @@
+import { type MockInstance, afterEach, beforeEach, vi } from 'vitest';
+
+const MOCK_DATE_NOW_MS = 1_000_000;
+const MOCK_TIME_ORIGIN = 500_000;
+
+const dateNow = MOCK_DATE_NOW_MS;
+const performanceTimeOrigin = MOCK_TIME_ORIGIN;
+
+/* eslint-disable functional/no-let */
+let dateNowSpy: MockInstance<[], number> | undefined;
+let performanceNowSpy: MockInstance<[], number> | undefined;
+/* eslint-enable functional/no-let */
+
+beforeEach(() => {
+  dateNowSpy = vi.spyOn(Date, 'now').mockReturnValue(dateNow);
+  performanceNowSpy = vi
+    .spyOn(performance, 'now')
+    .mockReturnValue(dateNow - performanceTimeOrigin);
+
+  vi.stubGlobal('performance', {
+    ...performance,
+    timeOrigin: performanceTimeOrigin,
+  });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+
+  if (dateNowSpy) {
+    dateNowSpy.mockRestore();
+    dateNowSpy = undefined;
+  }
+  if (performanceNowSpy) {
+    performanceNowSpy.mockRestore();
+    performanceNowSpy = undefined;
+  }
+});

testing/test-setup/src/lib/process.setup-file.ts

@@ -0,0 +1,21 @@
+import process from 'node:process';
+import { afterEach, beforeEach, vi } from 'vitest';
+
+export const MOCK_PID = 10_001;
+export const MOCK_TID = 2;
+
+vi.mock('node:worker_threads', () => ({
+  get threadId() {
+    return MOCK_TID;
+  },
+}));
+
+const processMock = vi.spyOn(process, 'pid', 'get');
+
+beforeEach(() => {
+  processMock.mockReturnValue(MOCK_PID);
+});
+
+afterEach(() => {
+  processMock.mockClear();
+});