performance-helpers 1.0.0

package/test/powerRateLimit.atomic.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { PowerRateLimit } from '../src/helpers/powerRateLimit.js';
+
+describe('PowerRateLimit atomic semantics', () => {
+  it('rolls back prior reservations when a later limiter fails', () => {
+    let released = false;
+    const okLimiter = {
+      reserve: (n) => ({ reserved: n }),
+      release: (token) => {
+        if (token && token.reserved) released = true;
+      },
+    };
+
+    const failingLimiter = {
+      reserve: () => null,
+    };
+
+    const pr = new PowerRateLimit([okLimiter, failingLimiter], { atomic: true });
+    const ok = pr.tryConsume(1, { atomic: true });
+    expect(ok).toBe(false);
+    expect(released).toBe(true);
+  });
+});
+
+// Fake limiter without available(), but supporting tryConsume and addTokens (undo)
+class FakeUndoLimiter {
+  constructor(tokens = 0) {
+    this.tokens = tokens;
+  }
+  tryConsume(n) {
+    if (this.tokens >= n) {
+      this.tokens -= n;
+      return true;
+    }
+    return false;
+  }
+  addTokens(n) {
+    this.tokens += n;
+  }
+}
+
+// Fake limiter without available() and without undo support
+class FakeNoUndoLimiter {
+  constructor(tokens = 0) {
+    this.tokens = tokens;
+  }
+  tryConsume(n) {
+    if (this.tokens >= n) {
+      this.tokens -= n;
+      return true;
+    }
+    return false;
+  }
+}
+
+describe('PowerRateLimit atomic semantics', () => {
+  it('rolls back prior commits when a later limiter fails and supports undo', () => {
+    const a = new FakeUndoLimiter(1);
+    const b = new FakeNoUndoLimiter(0);
+    const r = new PowerRateLimit([a, b], { atomic: true });
+
+    const ok = r.tryConsume(1);
+    expect(ok).toBe(false);
+    // a should have been rolled back to 1 token
+    expect(a.tokens).toBe(1);
+  });
+
+  it('refuses atomic consume when a limiter lacks undo capability', () => {
+    const a = new FakeNoUndoLimiter(1);
+    const b = new FakeNoUndoLimiter(1);
+    const r = new PowerRateLimit([a, b], { atomic: true });
+
+    // both have tokens=1 but they lack available() and undo, so atomic cannot be guaranteed
+    const ok = r.tryConsume(1);
+    expect(ok).toBe(false);
+    // ensure no side-effects
+    expect(a.tokens).toBe(1);
+    expect(b.tokens).toBe(1);
+  });
+});

package/test/powerRateLimit.extra.test.js

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi } from 'vitest';
+import { PowerRateLimit } from '../src/helpers/powerRateLimit.js';
+
+describe('PowerRateLimit extra branches', () => {
+  it('constructor requires an array', () => {
+    expect(() => new PowerRateLimit({})).toThrow(TypeError);
+  });
+
+  it('tryConsume with 0 returns true', () => {
+    const r = new PowerRateLimit([]);
+    expect(r.tryConsume(0)).toBe(true);
+  });
+
+  it('fast available() check returns false when any limiter reports insufficient', () => {
+    const limiter = { available: () => 0, tryConsume: vi.fn(() => true) };
+    const r = new PowerRateLimit([limiter]);
+    expect(r.tryConsume(1)).toBe(false);
+  });
+
+  it('available() returns the minimum available across child limiters', () => {
+    const a = { available: () => 5, tryConsume: vi.fn(() => true) };
+    const b = { available: () => 2, tryConsume: vi.fn(() => true) };
+    const r = new PowerRateLimit([a, b]);
+    expect(r.available()).toBe(2);
+  });
+
+  it('available() returns Infinity when no limiters are configured', () => {
+    const r = new PowerRateLimit([]);
+    expect(r.available()).toBe(Infinity);
+  });
+
+  it('available() returns 0 when any child limiter lacks available()', () => {
+    const a = { available: () => 5, tryConsume: vi.fn(() => true) };
+    const b = { tryConsume: vi.fn(() => true) };
+    const r = new PowerRateLimit([a, b]);
+    expect(r.available()).toBe(0);
+  });
+
+  it('reserve and release work across atomic limiters', () => {
+    const l1 = { reserve: vi.fn((n) => ({ n })), release: vi.fn() };
+    const l2 = { tryConsume: vi.fn(() => true), rollback: vi.fn() };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    const token = r.reserve(1);
+    expect(token).toEqual({ n: 1 });
+    expect(l1.reserve).toHaveBeenCalledWith(1);
+    r.release(token);
+    expect(l1.release).toHaveBeenCalledWith(token);
+    expect(l2.rollback).toHaveBeenCalledWith(1);
+  });
+
+  it('rollback aliases release', () => {
+    const l1 = { reserve: vi.fn((n) => ({ n })), release: vi.fn() };
+    const l2 = { tryConsume: vi.fn(() => true), rollback: vi.fn() };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    const token = r.reserve(1);
+    expect(token).not.toBeNull();
+    r.rollback(token);
+    expect(l1.release).toHaveBeenCalledWith(token);
+    expect(l2.rollback).toHaveBeenCalledWith(1);
+  });
+
+  it('reserve returns null when atomic reservation cannot be guaranteed', () => {
+    const a = { reserve: vi.fn((n) => ({ n })), release: vi.fn() };
+    const b = { tryConsume: vi.fn(() => false), rollback: vi.fn() };
+    const r = new PowerRateLimit([a, b], { atomic: true });
+    expect(r.reserve(1)).toBeNull();
+    expect(a.release).toHaveBeenCalled();
+  });
+
+  it('reserve returns a zero token for non-positive requests and release ignores zero-ish input', () => {
+    const l = { release: vi.fn(), rollback: vi.fn(), addTokens: vi.fn() };
+    const r = new PowerRateLimit([l], { atomic: true });
+
+    expect(r.reserve(0)).toEqual({ n: 0 });
+    r.release(null);
+    r.release({ n: 0 });
+    r.release(0);
+
+    expect(l.release).not.toHaveBeenCalled();
+    expect(l.rollback).not.toHaveBeenCalled();
+    expect(l.addTokens).not.toHaveBeenCalled();
+  });
+
+  it('release falls back to addTokens when release and rollback are unavailable or throw', () => {
+    const limiter = {
+      release: vi.fn(() => {
+        throw new Error('release failed');
+      }),
+      rollback: vi.fn(() => {
+        throw new Error('rollback failed');
+      }),
+      addTokens: vi.fn(),
+    };
+    const r = new PowerRateLimit([limiter]);
+
+    r.release(2);
+
+    expect(limiter.release).toHaveBeenCalled();
+    expect(limiter.rollback).toHaveBeenCalledWith(2);
+    expect(limiter.addTokens).toHaveBeenCalledWith(2);
+  });
+
+  it('reset swallows limiter reset errors and rollback remains a public alias', () => {
+    const limiter = {
+      reset: vi.fn(() => {
+        throw new Error('reset failed');
+      }),
+      rollback: vi.fn(),
+    };
+    const r = new PowerRateLimit([limiter]);
+
+    expect(() => r.reset()).not.toThrow();
+    r.rollback({ n: 3 });
+
+    expect(limiter.reset).toHaveBeenCalled();
+    expect(limiter.rollback).toHaveBeenCalledWith(3);
+  });
+
+  it('atomic consume returns false when a limiter lacks undo capability', () => {
+    const a = { available: () => 10, tryConsume: vi.fn(() => true) };
+    // b lacks available and any undo primitives
+    const b = { tryConsume: vi.fn(() => true) };
+    const r = new PowerRateLimit([a, b], { atomic: true });
+    expect(r.tryConsume(1)).toBe(false);
+  });
+
+  it('reserve + tryConsume commit succeeds and calls reserve', () => {
+    const l1 = { reserve: vi.fn(() => ({ t: true })), release: vi.fn() };
+    // provide a noop rollback so pre-check allows atomic path
+    const l2 = { tryConsume: vi.fn(() => true), rollback: vi.fn() };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    expect(r.tryConsume(1)).toBe(true);
+    expect(l1.reserve).toHaveBeenCalled();
+    expect(l2.tryConsume).toHaveBeenCalled();
+  });
+
+  it('undo is attempted when a later limiter fails', () => {
+    const l1 = { reserve: vi.fn(() => ({ t: true })), release: vi.fn() };
+    const l2 = { tryConsume: vi.fn(() => false), rollback: vi.fn() };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    expect(r.tryConsume(1)).toBe(false);
+    // release should have been called as part of rollback attempts
+    expect(l1.release).toHaveBeenCalled();
+  });
+});

package/test/powerRateLimit.functions.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi } from 'vitest';
+import PowerRateLimit from '../src/helpers/powerRateLimit.js';
+
+describe('PowerRateLimit functions and undo paths', () => {
+  it('returns false when available() throws', () => {
+    const bad = {
+      available: () => {
+        throw new Error('boom');
+      },
+      tryConsume: () => true,
+    };
+    const r = new PowerRateLimit([bad]);
+    expect(r.tryConsume(1)).toBe(false);
+  });
+
+  it('throws TypeError when limiter missing tryConsume in fast-path', () => {
+    const lim = { available: () => 10 };
+    const r = new PowerRateLimit([lim]);
+    expect(() => r.tryConsume(1)).toThrow(TypeError);
+  });
+
+  it('rollback calls release when a reserve later throws', () => {
+    const l1 = { reserve: () => ({ tok: true }), release: vi.fn() };
+    const l2 = {
+      reserve: () => {
+        throw new Error('reserve fail');
+      },
+      release: vi.fn(),
+    };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    expect(r.tryConsume(1)).toBe(false);
+    expect(l1.release).toHaveBeenCalled();
+  });
+
+  it('undo uses rollback/addTokens/reset fallback when necessary', () => {
+    const l1 = { available: () => 10, tryConsume: () => true, reset: vi.fn() };
+    const l2 = { tryConsume: () => false, rollback: vi.fn() };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    expect(r.tryConsume(1)).toBe(false);
+    expect(l1.reset).toHaveBeenCalled();
+  });
+
+  it('undo swallows errors from release/rollback', () => {
+    const l1 = {
+      reserve: () => ({ tok: true }),
+      release: () => {
+        throw new Error('boom release');
+      },
+    };
+    const l2 = {
+      tryConsume: () => {
+        throw new Error('boom try');
+      },
+      rollback: () => {
+        throw new Error('boom rollback');
+      },
+    };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    // should return false and not throw despite undo errors
+    expect(r.tryConsume(1)).toBe(false);
+  });
+
+  it('direct _undoCommit release/rollback/addTokens/reset paths are exercised', async () => {
+    const r = new PowerRateLimit([]);
+
+    const rel = { release: vi.fn() };
+    await r._undoCommit({ l: rel, method: 'reserve', token: 't' }, 1);
+    expect(rel.release).toHaveBeenCalledWith('t');
+
+    const rb = { rollback: vi.fn() };
+    await r._undoCommit({ l: rb, method: 'tryConsume' }, 2);
+    expect(rb.rollback).toHaveBeenCalledWith(2);
+
+    const at = { addTokens: vi.fn() };
+    await r._undoCommit({ l: at, method: 'tryConsume' }, 3);
+    expect(at.addTokens).toHaveBeenCalledWith(3);
+
+    const rs = { reset: vi.fn() };
+    await r._undoCommit({ l: rs, method: 'tryConsume' }, 4);
+    expect(rs.reset).toHaveBeenCalled();
+  });
+
+  it('throws TypeError and rolls back when atomic fallback limiter missing tryConsume or reserve', () => {
+    // first limiter reserves successfully
+    const l1 = { reserve: () => ({ t: true }), release: vi.fn() };
+    // second limiter lacks reserve and tryConsume but has addTokens (pre-check passes)
+    const l2 = { addTokens: () => {} /* no tryConsume or reserve */ };
+    const r = new PowerRateLimit([l1, l2], { atomic: true });
+    expect(() => r.tryConsume(1)).toThrow(TypeError);
+    // ensure rollback attempted for l1
+    expect(l1.release).toHaveBeenCalled();
+  });
+
+  it('calls limiter.reset via _undoCommit and reset()', async () => {
+    const l = { reset: vi.fn() };
+    const r = new PowerRateLimit([l]);
+    // call public reset()
+    r.reset();
+    expect(l.reset).toHaveBeenCalled();
+
+    // call private undo path that falls back to reset
+    l.reset.mockClear();
+    await r._undoCommit({ l, method: 'tryConsume' }, 1);
+    expect(l.reset).toHaveBeenCalled();
+  });
+});

package/test/powerRateLimit.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { PowerThrottle } from '../src/helpers/powerThrottle.js';
+import { PowerSlidingWindow } from '../src/helpers/powerSlidingWindow.js';
+import PowerRateLimit from '../src/helpers/powerRateLimit.js';
+
+describe('PowerRateLimit', () => {
+  it('succeeds only when all underlying limiters allow', () => {
+    const t = new PowerThrottle({ capacity: 1, tokens: 1, refillRate: 0 });
+    const w = new PowerSlidingWindow({ capacity: 2, windowMs: 10000 });
+    const r = new PowerRateLimit([t, w]);
+
+    expect(r.tryConsume()).toBe(true);
+    // throttle consumed (capacity 1) so next immediate attempt should fail
+    expect(r.tryConsume()).toBe(false);
+  });
+
+  it('respects sliding-window when throttle has higher capacity', () => {
+    const t = new PowerThrottle({ capacity: 5, tokens: 5, refillRate: 0 });
+    const w = new PowerSlidingWindow({ capacity: 1, windowMs: 10000 });
+    const r = new PowerRateLimit([t, w]);
+
+    expect(r.tryConsume()).toBe(true);
+    // sliding window capacity is 1, so second immediate attempt is blocked
+    expect(r.tryConsume()).toBe(false);
+  });
+
+  it('reset resets underlying limiters', () => {
+    const t = new PowerThrottle({ capacity: 1, tokens: 0, refillRate: 0 });
+    const w = new PowerSlidingWindow({ capacity: 1, windowMs: 10000 });
+    const r = new PowerRateLimit([t, w]);
+
+    // nothing available initially
+    expect(r.tryConsume()).toBe(false);
+    // reset should restore underlying limiters to default/full state
+    r.reset();
+    expect(r.tryConsume()).toBe(true);
+  });
+});

package/test/powerRetry.attemptTimeout.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import PowerRetry from '../src/helpers/powerRetry.js';
+
+describe('PowerRetry attemptTimeout', () => {
+  it('times out a slow attempt and retries according to maxAttempts', async () => {
+    const start = Date.now();
+    const fn = () => new Promise((res) => setTimeout(res, 1000)); // never resolves within attemptTimeout
+    const opts = {
+      maxAttempts: 2,
+      attemptTimeout: 50,
+      baseDelay: 1,
+      backoff: 'fixed',
+      jitter: false,
+    };
+
+    let thrown = null;
+    try {
+      await PowerRetry.run(fn, opts);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeTruthy();
+    // should have taken at least attemptTimeout * maxAttempts (with tiny delays)
+    expect(Date.now() - start).toBeGreaterThanOrEqual(50);
+  });
+
+  it('treats a timed-out attempt as a failed attempt and succeeds on retry', async () => {
+    let call = 0;
+    const fn = () =>
+      new Promise((res) => {
+        call += 1;
+        if (call === 1) {
+          // first attempt stalls
+          return; // never resolves
+        }
+        res('ok');
+      });
+
+    const opts = {
+      maxAttempts: 3,
+      attemptTimeout: 30,
+      baseDelay: 1,
+      backoff: 'fixed',
+      jitter: false,
+    };
+
+    const res = await PowerRetry.run(fn, opts);
+    expect(res).toBe('ok');
+    expect(call).toBeGreaterThanOrEqual(2);
+  });
+});

package/test/powerRetry.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { PowerRetry } from '../src/helpers/powerRetry.js';
+
+describe('PowerRetry', () => {
+  it('throws a TypeError when fn is not callable', async () => {
+    await expect(PowerRetry.run(null)).rejects.toThrow('fn must be a function');
+  });
+
+  it('retries failed attempts up to maxAttempts and succeeds', async () => {
+    let calls = 0;
+    const fn = async () => {
+      calls++;
+      if (calls < 3) throw new Error('fail');
+      return 'ok';
+    };
+
+    const res = await PowerRetry.run(fn, { maxAttempts: 4, baseDelay: 1, jitter: false });
+    expect(res).toBe('ok');
+    expect(calls).toBe(3);
+  });
+
+  it('rejects after exhausting attempts', async () => {
+    let calls = 0;
+    const fn = async () => {
+      calls++;
+      throw new Error('bad');
+    };
+
+    await expect(
+      PowerRetry.run(fn, { maxAttempts: 2, baseDelay: 1, jitter: false })
+    ).rejects.toThrow('bad');
+    expect(calls).toBe(2);
+  });
+
+  it('honors retryIf predicate', async () => {
+    let calls = 0;
+    const fn = async () => {
+      calls++;
+      const e = new Error('oops');
+      e.status = 400;
+      throw e;
+    };
+
+    await expect(
+      PowerRetry.run(fn, {
+        maxAttempts: 3,
+        baseDelay: 1,
+        jitter: false,
+        retryIf: (err) => err.status >= 500,
+      })
+    ).rejects.toThrow('oops');
+    expect(calls).toBe(1);
+  });
+
+  it('supports instance-level default options merged with per-call overrides', async () => {
+    let calls = 0;
+    const retry = new PowerRetry({ maxAttempts: 4, baseDelay: 1, jitter: false });
+    const fn = async () => {
+      calls += 1;
+      if (calls < 2) throw new Error('retry me');
+      return 'ok';
+    };
+
+    const res = await retry.run(fn, { backoff: 'fixed' });
+    expect(res).toBe('ok');
+    expect(calls).toBe(2);
+  });
+
+  it('treats boolean retryIf values as fixed retry policy', async () => {
+    let calls = 0;
+    const fn = async () => {
+      calls += 1;
+      throw new Error('still bad');
+    };
+
+    await expect(
+      PowerRetry.run(fn, { maxAttempts: 3, baseDelay: 1, jitter: false, retryIf: false })
+    ).rejects.toThrow('still bad');
+    expect(calls).toBe(1);
+  });
+
+  it('swallows onRetry callback errors and continues retrying', async () => {
+    let calls = 0;
+    const fn = async () => {
+      calls += 1;
+      if (calls < 2) throw new Error('transient');
+      return 'ok';
+    };
+
+    const res = await PowerRetry.run(fn, {
+      maxAttempts: 2,
+      baseDelay: 1,
+      jitter: false,
+      onRetry() {
+        throw new Error('observer failed');
+      },
+    });
+
+    expect(res).toBe('ok');
+    expect(calls).toBe(2);
+  });
+
+  it('fails fast when maxAttempts is non-positive', async () => {
+    let calls = 0;
+    const fn = async () => {
+      calls += 1;
+      throw new Error('bad-attempts');
+    };
+
+    await expect(
+      PowerRetry.run(fn, { maxAttempts: -3, baseDelay: 1, jitter: false })
+    ).rejects.toThrow('maxAttempts must be a positive finite number');
+    expect(calls).toBe(0);
+  });
+
+  it('fails fast when maxAttempts is not finite', async () => {
+    await expect(PowerRetry.run(async () => 'ok', { maxAttempts: Number.NaN })).rejects.toThrow(
+      'maxAttempts must be a positive finite number'
+    );
+  });
+});

package/test/powerScheduler.test.js

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi } from 'vitest';
+import { PowerScheduler } from '../src/helpers/powerScheduler.js';
+
+describe('PowerScheduler', () => {
+  it('throws when constructed without a flush function', () => {
+    expect(() => new PowerScheduler(null)).toThrow(TypeError);
+  });
+
+  it('schedules a microtask flush and invokes the callback once', async () => {
+    let called = 0;
+    const scheduler = new PowerScheduler(() => {
+      called += 1;
+    });
+
+    scheduler.schedule();
+    scheduler.schedule();
+    expect(scheduler.scheduled).toBe(true);
+    await Promise.resolve();
+    expect(called).toBe(1);
+    expect(scheduler.scheduled).toBe(false);
+  });
+
+  it('supports flushing immediately before the scheduled callback runs', async () => {
+    let called = 0;
+    const scheduler = new PowerScheduler(() => {
+      called += 1;
+    });
+
+    scheduler.schedule();
+    expect(scheduler.scheduled).toBe(true);
+    scheduler.flush();
+    expect(called).toBe(1);
+    expect(scheduler.scheduled).toBe(false);
+    await Promise.resolve();
+    expect(called).toBe(1);
+  });
+
+  it('cancels a scheduled flush and prevents callback invocation', async () => {
+    let called = 0;
+    const scheduler = new PowerScheduler(() => {
+      called += 1;
+    });
+
+    scheduler.schedule();
+    expect(scheduler.scheduled).toBe(true);
+    scheduler.cancel();
+    expect(scheduler.scheduled).toBe(false);
+    await Promise.resolve();
+    expect(called).toBe(0);
+  });
+
+  it('supports macrotask scheduling', async () => {
+    let called = 0;
+    const scheduler = new PowerScheduler(
+      () => {
+        called += 1;
+      },
+      { scheduling: 'macrotask' }
+    );
+
+    scheduler.schedule();
+    expect(scheduler.scheduled).toBe(true);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(called).toBe(1);
+    expect(scheduler.scheduled).toBe(false);
+  });
+
+  it('flush and cancel are no-ops when nothing is scheduled', () => {
+    const scheduler = new PowerScheduler(() => {});
+
+    expect(() => scheduler.flush()).not.toThrow();
+    expect(() => scheduler.cancel()).not.toThrow();
+    expect(scheduler.scheduled).toBe(false);
+  });
+
+  it('swallows callback errors by default without logging to console.error', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const scheduler = new PowerScheduler(() => {
+        throw new Error('flush failed');
+      });
+
+      scheduler.schedule();
+      await Promise.resolve();
+
+      expect(errorSpy).not.toHaveBeenCalled();
+      expect(scheduler.scheduled).toBe(false);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it('calls onError when provided and continues scheduling safely', async () => {
+    const onError = vi.fn();
+    const scheduler = new PowerScheduler(
+      () => {
+        throw new Error('flush failed');
+      },
+      { onError }
+    );
+
+    scheduler.schedule();
+    await Promise.resolve();
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(scheduler.scheduled).toBe(false);
+  });
+
+  it('swallows onError hook failures', async () => {
+    const scheduler = new PowerScheduler(
+      () => {
+        throw new Error('flush failed');
+      },
+      {
+        onError: () => {
+          throw new Error('hook failed');
+        },
+      }
+    );
+
+    scheduler.schedule();
+    await Promise.resolve();
+
+    expect(scheduler.scheduled).toBe(false);
+  });
+});