performance-helpers 1.0.0 → 1.0.1

package/test/powerMemoizer.memoize.test.js

@@ -1,100 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerMemoizer } from '../src/helpers/powerCache.js';
-
-describe('PowerMemoizer.memoize', () => {
-  it('throws when memoize is called with a non-function', () => {
-    const pm = new PowerMemoizer();
-    expect(() => pm.memoize(null)).toThrow(TypeError);
-  });
-
-  it('memoizes sync function via memoize() and attaches helpers', () => {
-    let calls = 0;
-    const fn = (x) => {
-      calls++;
-      return x + 1;
-    };
-    const pm = new PowerMemoizer();
-    const memo = pm.memoize(fn);
-    expect(memo(1)).toBe(2);
-    expect(calls).toBe(1);
-    expect(memo(1)).toBe(2);
-    expect(calls).toBe(1);
-    // helpers
-    expect(typeof memo.get).toBe('function');
-    expect(memo.get(1)).toBe(2);
-    expect(typeof memo.has).toBe('function');
-    expect(memo.has(1)).toBe(true);
-    expect(typeof memo.delete).toBe('function');
-    expect(memo.delete(1)).toBe(true);
-    expect(memo.has(1)).toBe(false);
-    expect(typeof memo.stats).toBe('function');
-    expect(memo.stats()).toHaveProperty('size');
-    expect(memo.cache).toBe(pm.cache);
-    expect(memo.original).toBe(fn);
-    expect(typeof memo.clear).toBe('function');
-    memo.clear();
-    expect(memo(1)).toBe(2);
-    expect(calls).toBe(2);
-  });
-
-  it('memoized function is instanceof PowerMemoizer', () => {
-    const pm = new PowerMemoizer();
-    const memo = pm.memoize((x) => x);
-    expect(memo instanceof PowerMemoizer).toBe(true);
-  });
-
-  it('honors per-wrapper ttl and weight options', async () => {
-    // TTL override
-    let calls = 0;
-    const fn = (x) => {
-      calls++;
-      return x;
-    };
-    const pm = new PowerMemoizer();
-    const memo = pm.memoize(fn, { ttl: 5 });
-    expect(memo(1)).toBe(1);
-    expect(calls).toBe(1);
-    expect(memo(1)).toBe(1);
-    expect(calls).toBe(1);
-    await new Promise((r) => setTimeout(r, 10));
-    expect(memo(1)).toBe(1);
-    expect(calls).toBe(2);
-
-    // Weight override with rejection by cache
-    let calls2 = 0;
-    const fn2 = (x) => {
-      calls2++;
-      return { v: x };
-    };
-    const pm2 = new PowerMemoizer(undefined, {
-      cacheOptions: { maxWeight: 1, rejectOversized: true },
-    });
-    const memo2 = pm2.memoize(fn2, { weight: 2 });
-    // first call returns value but should not be cached due to oversized weight
-    const a = memo2(1);
-    expect(a).toEqual({ v: 1 });
-    expect(calls2).toBe(1);
-    // second call should invoke original again because caching was rejected
-    const b = memo2(1);
-    expect(b).toEqual({ v: 1 });
-    expect(calls2).toBe(2);
-  });
-
-  it('uses constructor default memoize options when per-call ttl/weight are omitted', async () => {
-    let calls = 0;
-    const pm = new PowerMemoizer(undefined, { ttl: 5 });
-    const memo = pm.memoize((value) => {
-      calls += 1;
-      return value;
-    });
-
-    expect(memo('x')).toBe('x');
-    expect(memo('x')).toBe('x');
-    expect(calls).toBe(1);
-
-    await new Promise((resolve) => setTimeout(resolve, 10));
-
-    expect(memo('x')).toBe('x');
-    expect(calls).toBe(2);
-  });
-});

package/test/powerMemoizer.test.js

@@ -1,85 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerMemoizer } from '../src/helpers/powerCache.js';
-
-describe('PowerMemoizer', () => {
-  it('caches sync function results', () => {
-    let calls = 0;
-    const fn = (a) => {
-      calls++;
-      return a * 2;
-    };
-    const pm = new PowerMemoizer();
-    const memo = pm.memoize(fn);
-    expect(memo(2)).toBe(4);
-    expect(calls).toBe(1);
-    expect(memo(2)).toBe(4);
-    expect(calls).toBe(1);
-  });
-
-  it('dedupes concurrent async calls and caches result', async () => {
-    let calls = 0;
-    const fn = async (x) => {
-      calls++;
-      await new Promise((r) => setTimeout(r, 10));
-      return x * 3;
-    };
-    const pm = new PowerMemoizer();
-    const memo = pm.memoize(fn);
-    const p1 = memo(3);
-    const p2 = memo(3);
-    // same in-flight promise
-    expect(p1).toBe(p2);
-    const res = await p1;
-    expect(res).toBe(9);
-    expect(calls).toBe(1);
-    // subsequent call returns cached value (not a new invocation)
-    const r2 = await Promise.resolve(memo(3));
-    expect(r2).toBe(9);
-    expect(calls).toBe(1);
-  });
-
-  it('does not cache rejected promises', async () => {
-    let calls = 0;
-    const fn = async () => {
-      calls++;
-      await new Promise((r) => setTimeout(r, 1));
-      throw new Error('boom');
-    };
-    const pm = new PowerMemoizer();
-    const memo = pm.memoize(fn);
-    await expect(memo()).rejects.toThrow('boom');
-    await expect(memo()).rejects.toThrow('boom');
-    expect(calls).toBe(2);
-  });
-
-  it('honors TTL and expires entries', async () => {
-    let calls = 0;
-    const fn = (x) => {
-      calls++;
-      return x;
-    };
-    const pm = new PowerMemoizer(undefined, { ttl: 5 });
-    const memo = pm.memoize(fn);
-    expect(memo(1)).toBe(1);
-    expect(calls).toBe(1);
-    await new Promise((r) => setTimeout(r, 10));
-    expect(memo(1)).toBe(1);
-    expect(calls).toBe(2);
-  });
-
-  it('delete and clear remove cached entries', () => {
-    let calls = 0;
-    const fn = (x) => {
-      calls++;
-      return x;
-    };
-    const pm = new PowerMemoizer();
-    const memo = pm.memoize(fn);
-    expect(memo(5)).toBe(5);
-    memo.delete(5);
-    expect(memo(5)).toBe(5);
-    expect(calls).toBe(2);
-    memo.clear();
-    expect(memo(6)).toBe(6);
-  });
-});

package/test/powerObserver.test.js

@@ -1,129 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerObserver } from '../src/helpers/powerObserver.js';
-
-describe('PowerObserver', () => {
-  it('notifies subscribers asynchronously and returns unsubscribe', async () => {
-    const obs = new PowerObserver(1);
-    let called = 0;
-    const unsub = obs.subscribe((next, prev) => {
-      expect(prev).toBe(1);
-      expect(next).toBe(2);
-      called++;
-    });
-    obs.value = 2;
-    await Promise.resolve();
-    expect(called).toBe(1);
-    unsub();
-    obs.value = 3;
-    await Promise.resolve();
-    expect(called).toBe(1);
-  });
-
-  it('clear removes all subscribers and size reflects count', () => {
-    const obs = new PowerObserver('a');
-    const sub = () => {};
-    obs.subscribe(sub);
-    obs.subscribe(() => {});
-    expect(obs.size).toBe(2);
-    obs.clear();
-    expect(obs.size).toBe(0);
-  });
-
-  it('throws on invalid subscriber', () => {
-    const obs = new PowerObserver(0);
-    expect(() => obs.subscribe(null)).toThrow();
-  });
-
-  it('respects distinct and map options', async () => {
-    const obs = new PowerObserver(2, { distinct: true, map: (v) => v % 2 });
-    let calls = 0;
-    obs.subscribe(() => {
-      calls++;
-    });
-    obs.value = 4; // maps 0 -> previous 0 -> no notify
-    await Promise.resolve();
-    expect(calls).toBe(0);
-    obs.value = 5; // maps 1 -> notify
-    await Promise.resolve();
-    expect(calls).toBe(1);
-  });
-
-  it('allows setting map function via .map()', async () => {
-    const obs = new PowerObserver(1);
-    obs.map((v) => v * 2);
-    let called = 0;
-    obs.subscribe((n, p) => {
-      expect(n).toBe(4);
-      expect(p).toBe(2);
-      called++;
-    });
-    obs.value = 2;
-    await Promise.resolve();
-    expect(called).toBe(1);
-  });
-
-  it('supports sync delivery and swallows subscriber errors', () => {
-    const obs = new PowerObserver(1, { async: false });
-    const seen = [];
-    obs.subscribe(() => {
-      throw new Error('listener failed');
-    });
-    obs.subscribe((next, prev) => {
-      seen.push([prev, next]);
-    });
-
-    obs.value = 2;
-
-    expect(seen).toEqual([[1, 2]]);
-  });
-
-  it('coalesces multiple async writes into the latest next value while preserving the first prev', async () => {
-    const obs = new PowerObserver(1);
-    const seen = [];
-    obs.subscribe((next, prev) => {
-      seen.push([prev, next]);
-    });
-
-    obs.value = 2;
-    obs.value = 3;
-    await Promise.resolve();
-
-    expect(seen).toEqual([[1, 3]]);
-  });
-
-  it('drain aliases flush and map(null) clears the mapping function', async () => {
-    const obs = new PowerObserver(2, { async: 'macrotask', map: (v) => v * 2 });
-    const seen = [];
-    obs.subscribe((next, prev) => {
-      seen.push([prev, next]);
-    });
-
-    obs.map(null);
-    obs.value = 4;
-    obs.drain();
-
-    expect(seen).toEqual([[2, 4]]);
-  });
-
-  it('throws when map is set to a non-function value', () => {
-    const obs = new PowerObserver(1);
-    expect(() => obs.map(123)).toThrow('map must be a function');
-  });
-
-  it('supports macrotask scheduling and flush()', async () => {
-    const obs = new PowerObserver(1, { async: 'macrotask' });
-    let called = 0;
-    obs.subscribe((n, p) => {
-      expect(p).toBe(1);
-      expect(n).toBe(2);
-      called++;
-    });
-    obs.value = 2;
-    // macrotask: microtask await won't observe it
-    await Promise.resolve();
-    expect(called).toBe(0);
-    // flush synchronously
-    obs.flush();
-    expect(called).toBe(1);
-  });
-});

package/test/powerPermitGate.test.js

@@ -1,66 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerPermitGate } from '../src/helpers/powerPermitGate.js';
-
-describe('PowerPermitGate', () => {
-  it('acquires permits immediately when available', async () => {
-    const gate = new PowerPermitGate({ capacity: 2 });
-    const release = await gate.acquire();
-    expect(typeof release).toBe('function');
-    expect(gate.available).toBe(1);
-    expect(gate.pending).toBe(0);
-    release();
-    expect(gate.available).toBe(2);
-  });
-
-  it('queues callers when permits are exhausted', async () => {
-    const gate = new PowerPermitGate({ capacity: 1 });
-    const firstRelease = await gate.acquire();
-    const pending = gate.acquire();
-    expect(gate.pending).toBe(1);
-    let resolved = false;
-
-    const promise = pending.then((release) => {
-      resolved = true;
-      release();
-    });
-
-    expect(resolved).toBe(false);
-    firstRelease();
-    await promise;
-    expect(gate.pending).toBe(0);
-    expect(resolved).toBe(true);
-    expect(gate.available).toBe(1);
-  });
-
-  it('rejects acquire when the wait queue is full', async () => {
-    const gate = new PowerPermitGate({ capacity: 1, queueCapacity: 1 });
-    await gate.acquire();
-    gate.acquire();
-    await expect(gate.acquire()).rejects.toThrow('PowerPermitGate queue is full');
-  });
-
-  it('tryAcquire returns null when no permit is available', () => {
-    const gate = new PowerPermitGate({ capacity: 1 });
-    const release = gate.tryAcquire();
-    expect(typeof release).toBe('function');
-    expect(gate.tryAcquire()).toBeNull();
-    release();
-    expect(gate.tryAcquire()).not.toBeNull();
-  });
-
-  it('reset clears waiters and restores available permits', async () => {
-    const gate = new PowerPermitGate({ capacity: 1, queueCapacity: 2 });
-    const firstRelease = await gate.acquire();
-    const pending = gate.acquire();
-    let rejected = false;
-    pending.catch((err) => {
-      rejected = err && err.message === 'PowerPermitGate reset';
-    });
-
-    gate.reset({ available: 1, reason: new Error('PowerPermitGate reset') });
-    expect(gate.available).toBe(1);
-    await Promise.resolve();
-    expect(rejected).toBe(true);
-    firstRelease();
-  });
-});

package/test/powerPool.autoTransfer.test.js

@@ -1,100 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { PowerPool } from '../src/helpers/powerPool.js';
-
-describe('PowerPool auto-transfer behavior', () => {
-  it('postMessage without transfer encodes object and passes ArrayBuffer in transfer list', async () => {
-    class MockUnderlying {
-      constructor() {
-        this.onmessage = null;
-        this.postMessage = vi.fn((msg) => {
-          // echo back after a tick to simulate worker reply
-          setTimeout(() => {
-            if (this.onmessage) this.onmessage({ data: msg });
-          }, 0);
-        });
-        this.terminate = vi.fn();
-      }
-    }
-
-    const pool = new PowerPool(MockUnderlying, { size: 1, idleTimeout: 1000 });
-    try {
-      const sent = { hello: 'x'.repeat(2000) };
-      const p = new Promise((resolve) => {
-        pool.onmessage = (e) => resolve(e.data);
-      });
-
-      const ok = pool.postMessage(sent);
-      expect(ok).toBe(true);
-
-      // wait for reply
-      const decoded = await p;
-      expect(decoded).toEqual(sent);
-
-      const underlying = pool.workers[0].worker._underlying || pool.workers[0]._underlying;
-      expect(underlying).toBeTruthy();
-      const call = underlying.postMessage.mock.calls[0];
-      expect(call).toBeTruthy();
-      const [argMsg, argTransfer] = call;
-      // message should be a Uint8Array and transfer should include its buffer
-      expect(argMsg).toBeInstanceOf(Uint8Array);
-      expect(Array.isArray(argTransfer)).toBe(true);
-      expect(argTransfer.length).toBeGreaterThanOrEqual(1);
-      expect(argTransfer[0]).toBe(argMsg.buffer);
-    } finally {
-      pool.terminate();
-    }
-  });
-
-  it('postMessage with explicit empty transfer array still forwards the encoded buffer', () => {
-    class MockUnderlying {
-      constructor() {
-        this.onmessage = null;
-        this.postMessage = vi.fn();
-        this.terminate = vi.fn();
-      }
-    }
-
-    const pool = new PowerPool(MockUnderlying, { size: 1, idleTimeout: 1000 });
-    try {
-      const ok = pool.postMessage({ hello: 'world' }, []);
-      expect(ok).toBe(true);
-
-      const underlying = pool.workers[0].worker._underlying || pool.workers[0]._underlying;
-      expect(underlying).toBeTruthy();
-      const call = underlying.postMessage.mock.calls[0];
-      expect(call).toBeTruthy();
-      const [argMsg, argTransfer] = call;
-      expect(argMsg).toBeInstanceOf(Uint8Array);
-      expect(argTransfer).toEqual([argMsg.buffer]);
-    } finally {
-      pool.terminate();
-    }
-  });
-
-  it('broadcast without transfer encodes per-worker and provides transferable buffers', () => {
-    class MockUnderlying {
-      constructor() {
-        this.onmessage = null;
-        this.postMessage = vi.fn();
-        this.terminate = vi.fn();
-      }
-    }
-
-    const pool = new PowerPool(MockUnderlying, { size: 3, idleTimeout: 1000 });
-    try {
-      pool.broadcast({ ping: 'pong'.repeat(500) });
-      for (const w of pool.workers) {
-        const underlying = w.worker._underlying || w._underlying;
-        expect(underlying).toBeTruthy();
-        const call = underlying.postMessage.mock.calls[0];
-        expect(call).toBeTruthy();
-        const [argMsg, argTransfer] = call;
-        expect(argMsg).toBeInstanceOf(Uint8Array);
-        expect(Array.isArray(argTransfer)).toBe(true);
-        expect(argTransfer[0]).toBe(argMsg.buffer);
-      }
-    } finally {
-      pool.terminate();
-    }
-  });
-});

package/test/powerPool.autoscale.extra.test.js

@@ -1,88 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerPool } from '../src/helpers/powerPool.js';
-
-// Lightweight mock underlying that reports a fixed processing duration
-class MockUnderlyingWithDuration {
-  constructor() {
-    this.onmessage = null;
-    this.postMessage = () => {
-      // respond on next tick with a reported duration
-      setTimeout(() => {
-        if (this.onmessage)
-          this.onmessage({ data: { duration: MockUnderlyingWithDuration.responseDuration } });
-      }, 1);
-    };
-    this.terminate = () => {};
-  }
-}
-
-describe('PowerPool autoscale - extra behaviors', () => {
-  it('multi-step scaling: adds up to `stepUp` workers in one tick', async () => {
-    MockUnderlyingWithDuration.responseDuration = 200;
-
-    const pool = new PowerPool(MockUnderlyingWithDuration, {
-      size: 1,
-      minSize: 1,
-      maxSize: 8,
-      lazy: false,
-      taskQueue: true,
-      autoScale: {
-        intervalMs: 50,
-        targetMs: 50,
-        alpha: 0.5,
-        cooldownMs: 10,
-        hysteresis: 0.1,
-        stepUp: 3,
-      },
-    });
-
-    try {
-      // post many tasks to ensure EWMA rises
-      for (let i = 0; i < 12; i++) pool.postMessage({ i });
-
-      // wait several ticks
-      await new Promise((r) => setTimeout(r, 400));
-
-      // should have added at least stepUp workers in a single tick
-      expect(pool.workers.length).toBeGreaterThanOrEqual(1 + 3);
-    } finally {
-      pool.terminate();
-    }
-  });
-
-  it('backoff: backoff multiplier increases after scale action', async () => {
-    MockUnderlyingWithDuration.responseDuration = 10;
-
-    const pool = new PowerPool(MockUnderlyingWithDuration, {
-      size: 8,
-      minSize: 1,
-      maxSize: 8,
-      lazy: false,
-      taskQueue: true,
-      autoScale: {
-        intervalMs: 50,
-        targetMs: 50,
-        alpha: 0.5,
-        cooldownMs: 50,
-        hysteresis: 0.1,
-        backoffFactor: 4,
-        backoffMaxMultiplier: 8,
-        backoffResetMs: 1000,
-      },
-    });
-
-    try {
-      // Start at max size so normal auto-growth cannot add workers.
-      for (let i = 0; i < 8; i++) pool.postMessage({ i });
-
-      // wait enough time for at least one scale action
-      await new Promise((r) => setTimeout(r, 200));
-
-      // internal multiplier should have increased from 1 when autoscale scaled down
-      expect(pool._autoScaleBackoffMultiplier).toBeGreaterThanOrEqual(1);
-      expect(pool._autoScaleBackoffMultiplier).toBeGreaterThanOrEqual(4);
-    } finally {
-      pool.terminate();
-    }
-  });
-});

package/test/powerPool.autoscale.test.js

@@ -1,136 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerPool } from '../src/helpers/powerPool.js';
-
-// Lightweight mock underlying used for the first autoscale test
-class MockUnderlying {
-  constructor() {
-    this.onmessage = null;
-    this.postMessage = () => {};
-    this.terminate = () => {};
-  }
-  addEventListener(type, cb) {
-    if (type === 'message') this.onmessage = cb;
-  }
-  removeEventListener() {}
-}
-
-describe('PowerPool autoscale', () => {
-  it('does not terminate workers with in-flight tasks during scale-down', () => {
-    const pool = new PowerPool(MockUnderlying, {
-      size: 2,
-      minSize: 0,
-      maxSize: 2,
-      lazy: false,
-      maxTasksPerWorker: 1,
-      idleTimeout: 1000,
-    });
-    try {
-      // simulate autoscale config without starting an interval
-      pool._autoScale = {
-        enabled: true,
-        intervalMs: 1000,
-        targetMs: 100,
-        alpha: 0.2,
-        cooldownMs: 100,
-        hysteresis: 0.5,
-        stepUp: 1,
-        stepDown: 2,
-        backoffFactor: 1,
-        backoffMaxMultiplier: 1,
-        backoffResetMs: 10000,
-      };
-      pool._autoScaleBackoffMultiplier = 1;
-
-      // set EWMA low to request scale-down
-      pool._ewmaLatency = 1;
-
-      // mark both workers as busy
-      pool.workers[0].tasks = 1;
-      pool.workers[1].tasks = 1;
-
-      pool._autoScaleTick();
-      // no idle workers -> none removed
-      expect(pool.workers.length).toBe(2);
-
-      // make one worker idle - it should be eligible for removal
-      pool.workers[1].tasks = 0;
-      pool._autoScaleTick();
-      expect(pool.workers.length).toBe(1);
-    } finally {
-      pool.terminate();
-    }
-  });
-});
-
-// Lightweight mock underlying that reports a fixed processing duration
-class MockUnderlyingWithDuration {
-  constructor() {
-    this.onmessage = null;
-    this.postMessage = () => {
-      // respond on next tick with a reported duration
-      setTimeout(() => {
-        if (this.onmessage)
-          this.onmessage({ data: { duration: MockUnderlyingWithDuration.responseDuration } });
-      }, 1);
-    };
-    this.terminate = () => {};
-  }
-}
-
-describe('PowerPool autoscale', () => {
-  it('scales up when observed EWMA latency exceeds target', async () => {
-    // heavy tasks reported as 200ms each
-    MockUnderlyingWithDuration.responseDuration = 200;
-
-    const pool = new PowerPool(MockUnderlyingWithDuration, {
-      size: 1,
-      minSize: 1,
-      maxSize: 4,
-      lazy: false,
-      taskQueue: true,
-      // aggressive autoscale tick for tests
-      autoScale: { intervalMs: 50, targetMs: 50, alpha: 0.5, cooldownMs: 100, hysteresis: 0.1 },
-    });
-
-    try {
-      // post multiple tasks to accumulate EWMA
-      for (let i = 0; i < 6; i++) pool.postMessage({ i });
-
-      // wait enough time for several autoscale ticks
-      await new Promise((r) => setTimeout(r, 500));
-
-      // pool should have scaled up at least one worker
-      expect(pool.workers.length).toBeGreaterThan(1);
-    } finally {
-      pool.terminate();
-    }
-  });
-
-  it('scales down when latency is low and queue is empty', async () => {
-    // light tasks reported as 1ms each
-    MockUnderlyingWithDuration.responseDuration = 1;
-
-    const pool = new PowerPool(MockUnderlyingWithDuration, {
-      size: 3,
-      minSize: 1,
-      maxSize: 4,
-      lazy: false,
-      taskQueue: true,
-      autoScale: { intervalMs: 50, targetMs: 50, alpha: 0.5, cooldownMs: 100, hysteresis: 0.1 },
-    });
-
-    try {
-      // run a few quick tasks to seed a low EWMA
-      for (let i = 0; i < 4; i++) pool.postMessage({ i });
-
-      // allow tasks to complete and autoscaler to observe low latencies
-      await new Promise((r) => setTimeout(r, 400));
-
-      // after cooldown and empty queue, pool should have shrunk toward minSize
-      expect(pool.workers.length).toBeLessThanOrEqual(2);
-      expect(pool.workers.length).toBeGreaterThanOrEqual(1);
-    } finally {
-      pool.terminate();
-    }
-  });
-});