@reservamos/browser-analytics 1.1.8-alpha.0 → 1.1.8-alpha.1

package/src/util/pendingWork.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPendingWorkQueue } from './pendingWork';
+
+describe('bounded pending work', () => {
+  let ready: boolean;
+  let signal: () => void;
+  let detach: ReturnType<typeof vi.fn>;
+  beforeEach(() => {
+    vi.useFakeTimers();
+    ready = false;
+    signal = () => undefined;
+    detach = vi.fn();
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+  function queue(maxActive = 1) {
+    return createPendingWorkQueue({
+      isReady: () => ready,
+      subscribe: (notify) => {
+        signal = notify;
+        return detach;
+      },
+      maxEntries: 2,
+      maxBytes: 10,
+      maxActive,
+      lifetime: 60000,
+      wait: 5000,
+      stage: 'readiness',
+    });
+  }
+  const work = (run: () => void | Promise<void>, bytes = 1) => ({
+    eventName: 'Test',
+    bytes,
+    isCurrent: () => true,
+    run,
+  });
+
+  it('resolves the foreground wait but retains unsent work for readiness at 5.2 seconds', async () => {
+    const run = vi.fn();
+    const pending = queue().enqueue(work(run));
+    await vi.advanceTimersByTimeAsync(5000);
+    await expect(pending).resolves.toBeUndefined();
+    expect(run).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(200);
+    ready = true;
+    signal();
+    signal();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(run).toHaveBeenCalledOnce();
+    expect(detach).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('never retries after a provider accepts and throws, including reentrant readiness', async () => {
+    const q = queue();
+    const run = vi.fn(() => {
+      signal();
+      throw new Error('accepted then threw');
+    });
+    const pending = q.enqueue(work(run));
+    ready = true;
+    signal();
+    signal();
+    await pending;
+    await vi.advanceTimersByTimeAsync(60000);
+    signal();
+    expect(run).toHaveBeenCalledOnce();
+    expect(JSON.stringify(vi.mocked(console.error).mock.calls)).not.toContain(
+      'accepted then threw',
+    );
+  });
+
+  it('keeps separate legitimate equal-payload calls', async () => {
+    const q = queue(2);
+    const run = vi.fn();
+    const first = q.enqueue(work(run));
+    const second = q.enqueue(work(run));
+    ready = true;
+    signal();
+    await Promise.all([first, second]);
+    expect(run).toHaveBeenCalledTimes(2);
+  });
+
+  it('expires without submission and cleans up its subscription and timer', async () => {
+    const run = vi.fn();
+    const pending = queue().enqueue(work(run));
+    await vi.advanceTimersByTimeAsync(60000);
+    await pending;
+    ready = true;
+    signal();
+    expect(run).not.toHaveBeenCalled();
+    expect(detach).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('evicts the oldest waiting work at capacity and rejects oversized work', async () => {
+    const q = queue();
+    const runs = [vi.fn(), vi.fn(), vi.fn(), vi.fn()];
+    const promises = runs.map((run, i) =>
+      q.enqueue(work(run, i === 3 ? 11 : 4)),
+    );
+    ready = true;
+    signal();
+    await Promise.all(promises);
+    expect(runs[0]).not.toHaveBeenCalled();
+    expect(runs[1]).toHaveBeenCalledOnce();
+    expect(runs[2]).toHaveBeenCalledOnce();
+    expect(runs[3]).not.toHaveBeenCalled();
+  });
+
+  it('invalidates waiting work before identity changes can submit it', async () => {
+    let current = true;
+    const run = vi.fn();
+    const pending = queue().enqueue({ ...work(run), isCurrent: () => current });
+    current = false;
+    signal();
+    await pending;
+    ready = true;
+    signal();
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it('enforces the byte budget before the entry-count budget is reached', async () => {
+    const q = queue();
+    const first = vi.fn();
+    const second = vi.fn();
+    const old = q.enqueue(work(first, 6));
+    const retained = q.enqueue(work(second, 6));
+    ready = true;
+    signal();
+    await Promise.all([old, retained]);
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledOnce();
+  });
+
+  it('suppresses expired active effects without exceeding actual provider concurrency', async () => {
+    const q = queue();
+    ready = true;
+    let finish!: () => void;
+    let active!: () => boolean;
+    const first = q.enqueue({
+      ...work(() => undefined),
+      run: (isActive) => {
+        active = isActive;
+        return new Promise<void>((resolve) => {
+          finish = resolve;
+        });
+      },
+    });
+    await vi.advanceTimersByTimeAsync(60000);
+    await first;
+    expect(active()).toBe(false);
+    const run = vi.fn();
+    const second = q.enqueue(work(run));
+    expect(run).not.toHaveBeenCalled();
+    finish();
+    await second;
+    expect(run).toHaveBeenCalledOnce();
+  });
+});

package/src/util/pendingWork.ts

@@ -0,0 +1,148 @@
+interface PendingWork {
+  eventName: string;
+  bytes: number;
+  isCurrent: () => boolean;
+  run: (isActive: () => boolean) => void | Promise<void>;
+}
+
+interface QueueOptions {
+  isReady: () => boolean;
+  subscribe: (notify: () => void) => () => void;
+  maxEntries: number;
+  maxBytes: number;
+  maxActive: number;
+  lifetime: number;
+  wait: number;
+  stage: 'readiness' | 'fingerprint';
+}
+
+interface Entry extends PendingWork {
+  state: 'waiting' | 'active' | 'closed';
+  deadline: number;
+  foregroundDeadline: number;
+  resolve?: () => void;
+}
+
+/** Retains bounded local work and claims each entry once, before invoking it. */
+export function createPendingWorkQueue(options: QueueOptions) {
+  const entries = new Set<Entry>();
+  let bytes = 0;
+  let active = 0;
+  let draining = false;
+  let unsubscribe: (() => void) | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  function diagnostic(entry: PendingWork, reason: string): void {
+    console.error('Tracking recovery diagnostic', {
+      eventName: entry.eventName,
+      stage: options.stage,
+      reason,
+    });
+  }
+
+  function resolveForeground(entry: Entry): void {
+    entry.resolve?.();
+    entry.resolve = undefined;
+  }
+
+  function close(entry: Entry, reason?: string): void {
+    if (entry.state === 'closed') return;
+    entry.state = 'closed';
+    entries.delete(entry);
+    bytes -= entry.bytes;
+    resolveForeground(entry);
+    if (reason) diagnostic(entry, reason);
+  }
+
+  function schedule(): void {
+    clearTimeout(timer);
+    timer = undefined;
+    if (entries.size === 0) {
+      unsubscribe?.();
+      unsubscribe = undefined;
+      return;
+    }
+    let next = Infinity;
+    for (const entry of entries) {
+      next = Math.min(next, entry.deadline);
+      if (entry.resolve) next = Math.min(next, entry.foregroundDeadline);
+    }
+    timer = setTimeout(drain, Math.max(0, next - Date.now()));
+  }
+
+  function drain(): void {
+    if (draining) return;
+    draining = true;
+    try {
+      for (const entry of entries) {
+        if (!entry.isCurrent()) close(entry, 'identity_changed');
+        else if (Date.now() >= entry.deadline) close(entry, 'timeout');
+        else if (entry.resolve && Date.now() >= entry.foregroundDeadline) {
+          resolveForeground(entry);
+        }
+      }
+      for (const entry of entries) {
+        if (active >= options.maxActive || !options.isReady()) break;
+        if (entry.state !== 'waiting') continue;
+        // No await before this claim: reentrant or repeated signals cannot replay it.
+        entry.state = 'active';
+        active++;
+        const isActive = () =>
+          entry.state === 'active' &&
+          Date.now() < entry.deadline &&
+          entry.isCurrent();
+        const finish = (failed = false) => {
+          if (failed && isActive()) diagnostic(entry, 'failed');
+          close(entry);
+          // An expired remote call still occupies its physical concurrency slot.
+          active--;
+          drain();
+        };
+        try {
+          void Promise.resolve(entry.run(isActive)).then(
+            () => finish(),
+            () => finish(true),
+          );
+        } catch {
+          finish(true);
+        }
+      }
+    } finally {
+      draining = false;
+      schedule();
+    }
+  }
+
+  function enqueue(work: PendingWork): Promise<void> {
+    if (work.bytes > options.maxBytes) {
+      diagnostic(work, 'capacity');
+      return Promise.resolve();
+    }
+    while (
+      entries.size >= options.maxEntries ||
+      bytes + work.bytes > options.maxBytes
+    ) {
+      const oldest = [...entries].find((entry) => entry.state === 'waiting');
+      if (!oldest) {
+        diagnostic(work, 'capacity');
+        return Promise.resolve();
+      }
+      close(oldest, 'capacity');
+    }
+    return new Promise((resolve) => {
+      const entry: Entry = {
+        ...work,
+        state: 'waiting',
+        deadline: Date.now() + options.lifetime,
+        foregroundDeadline: Date.now() + options.wait,
+        resolve,
+      };
+      entries.add(entry);
+      bytes += entry.bytes;
+      unsubscribe ??= options.subscribe(drain);
+      drain();
+    });
+  }
+
+  return { enqueue };
+}

package/src/util/snapshotEventData.ts

@@ -0,0 +1,15 @@
+/** Copies serializable event structures without replacing array undefined values with null. */
+export function snapshotEventData<T>(value: T): T {
+  if (Array.isArray(value))
+    return value.map((item: unknown) => snapshotEventData(item)) as T;
+  if (value instanceof Date) return new Date(value.getTime()) as T;
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        snapshotEventData(item),
+      ]),
+    ) as T;
+  }
+  return value;
+}