performance-helpers 1.0.0 → 1.0.1

package/test/powerCache.touch.test.js

@@ -1,46 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerCache } from '../src/helpers/powerCache.js';
-
-function delay(ms) {
-  return new Promise((res) => setTimeout(res, ms));
-}
-
-describe('PowerCache.touch()', () => {
-  it('updates recency without changing value', () => {
-    const c = new PowerCache();
-    c.set('a', 1);
-    c.set('b', 2);
-    // MRU order should be b, a
-    const before = Array.from(c.entries('MRU')).map(([k]) => k);
-    expect(before).toEqual(['b', 'a']);
-
-    const ok = c.touch('a');
-    expect(ok).toBe(true);
-    const after = Array.from(c.entries('MRU')).map(([k]) => k);
-    expect(after).toEqual(['a', 'b']);
-    // value unchanged
-    expect(c.get('a')).toBe(1);
-  });
-
-  it('returns false and removes expired entries', async () => {
-    const c = new PowerCache();
-    // set with very short TTL
-    c.set('x', 42, { ttl: 5 });
-    await delay(20);
-    // now expired
-    const ok = c.touch('x');
-    expect(ok).toBe(false);
-    expect(c.get('x')).toBeUndefined();
-  });
-
-  it('refreshes TTL when provided', async () => {
-    const c = new PowerCache();
-    c.set('k', 'v', { ttl: 10 });
-    // touch with longer ttl
-    const ok = c.touch('k', 1000);
-    expect(ok).toBe(true);
-    // wait for original TTL to have passed but before refreshed TTL
-    await delay(50);
-    expect(c.get('k')).toBe('v');
-  });
-});

package/test/powerChunking.branches.extra.test.js

@@ -1,155 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerChunker } from '../src/helpers/powerChunking.js';
-import { PowerPool } from '../src/helpers/powerPool.js';
-import { o2u8 } from '../src/helpers/powerBuffer.js';
-
-describe('PowerChunker branches extra', () => {
-  it('throws when missing iterable or fn not function', () => {
-    expect(() => new PowerChunker(null, () => {})).toThrow();
-    expect(() => new PowerChunker([1, 2, 3], null)).toThrow();
-  });
-
-  it('processes array and emits error objects for thrown items', async () => {
-    const items = [1, 2, 3];
-    const messages = [];
-    const pool = new PowerChunker(
-      items,
-      (item) => {
-        if (item === 2) throw new Error('boom');
-        return item * 2;
-      },
-      { chunkSize: 2 }
-    );
-    pool.onmessage = (e) => messages.push(e.data);
-    await pool.drain();
-    // At least one message should contain an error result for the thrown item
-    const allResults = messages.flatMap((m) => m.results || []);
-    expect(allResults.some((r) => r && r.error)).toBe(true);
-  });
-
-  it('streams an iterator and returns the pool instance when iterable throws', async () => {
-    function* badGen() {
-      yield 1;
-      yield 2;
-      throw new Error('stream fail');
-    }
-    const pool = new PowerChunker(badGen(), (n) => n + 1);
-    // ensure we get a pool back and drain resolves without throwing
-    expect(pool).toBeTruthy();
-    await pool.drain();
-  });
-
-  it('handles async item functions and preserves correlationId on direct pool posts', async () => {
-    const pool = new PowerChunker([], async (item) => item * 2, { chunkSize: 2 });
-
-    const payload = await new Promise((resolve) => {
-      pool.onmessage = (e) => resolve(e.data);
-      pool.postMessage({ chunk: [2, 4], correlationId: 'cid-1' });
-    });
-
-    expect(payload.processed).toBe(2);
-    expect(payload.results).toEqual([4, 8]);
-    expect(payload.correlationId).toBe('cid-1');
-    pool.terminate();
-  });
-
-  it('continues streaming when pool.postMessage throws for a chunk', async () => {
-    const original = PowerPool.prototype.postMessage;
-    let calls = 0;
-
-    PowerPool.prototype.postMessage = function patchedPostMessage(...args) {
-      calls += 1;
-      if (calls === 1) throw new Error('chunk dispatch failed');
-      return original.apply(this, args);
-    };
-
-    try {
-      const values = function* () {
-        yield 1;
-        yield 2;
-        yield 3;
-      };
-
-      const seen = [];
-      const pool = new PowerChunker(values(), (value) => value + 1, { chunkSize: 1 });
-      pool.onmessage = (e) => {
-        seen.push(...(e.data.results || []));
-      };
-
-      await pool.drain();
-      expect(seen.length).toBeGreaterThan(0);
-      expect(seen).toContain(3);
-      expect(seen).toContain(4);
-      pool.terminate();
-    } finally {
-      PowerPool.prototype.postMessage = original;
-    }
-  });
-
-  it('decodes transferable chunk payloads and supports inline worker add/remove listeners', async () => {
-    const pool = new PowerChunker([], (value) => value + 1, {
-      poolOptions: { size: 1, minSize: 1, lazy: false },
-    });
-
-    try {
-      const worker = pool.workers[0].worker._underlying;
-      const seen = [];
-      const onMessage = (e) => seen.push(e.data);
-      worker.addEventListener('message', onMessage);
-
-      worker.postMessage(o2u8({ chunk: [2], correlationId: 'buf-1' }));
-      await new Promise((resolve) => setTimeout(resolve, 10));
-
-      expect(seen[0]).toMatchObject({
-        processed: 1,
-        results: [3],
-        correlationId: 'buf-1',
-      });
-
-      worker.removeEventListener('message', onMessage);
-      worker.postMessage(o2u8({ chunk: [5] }));
-      await new Promise((resolve) => setTimeout(resolve, 10));
-
-      expect(seen).toHaveLength(1);
-    } finally {
-      pool.terminate();
-    }
-  });
-
-  it('routes inline worker failures to onerror and stops processing after terminate()', async () => {
-    const pool = new PowerChunker([], (value) => value + 1, {
-      poolOptions: { size: 1, minSize: 1, lazy: false },
-    });
-
-    try {
-      const worker = pool.workers[0].worker._underlying;
-      const errors = [];
-      const messages = [];
-      const onError = (err) => errors.push(err);
-      worker.addEventListener('error', onError);
-      worker.onmessage = () => {
-        throw new Error('message handler failed');
-      };
-
-      worker.postMessage({ chunk: [1] });
-      await new Promise((resolve) => setTimeout(resolve, 10));
-      expect(errors.some((err) => /message handler failed/.test(String(err && err.message)))).toBe(
-        true
-      );
-
-      worker.onmessage = (e) => messages.push(e.data);
-      worker.postMessage(o2u8(null));
-      await new Promise((resolve) => setTimeout(resolve, 10));
-      expect(errors.length).toBeGreaterThanOrEqual(2);
-
-      worker.terminate();
-      worker.postMessage({ chunk: [9] });
-      await new Promise((resolve) => setTimeout(resolve, 10));
-      expect(messages).toHaveLength(0);
-
-      worker.removeEventListener('error', onError);
-    } finally {
-      pool.terminate();
-    }
-  });
-});

package/test/powerChunking.errors.test.js

@@ -1,177 +0,0 @@
-import { expect } from 'chai';
-import { describe, it } from 'vitest';
-import { PowerChunker } from '../src/helpers/powerChunking.js';
-
-describe('PowerChunking error handling', () => {
-  it('emits per-item normalized error objects for sync throws and async rejections', async () => {
-    const items = [1, 2, 3, 4];
-    // 2 throws sync with code, 3 rejects async with code
-    const fn = (item) => {
-      if (item === 2) {
-        const e = new Error('sync fail');
-        e.code = 'SYNC_CODE';
-        throw e;
-      }
-      if (item === 3) {
-        const e = new Error('async fail');
-        e.code = 'ASYNC_CODE';
-        return Promise.reject(e);
-      }
-      return item * 10;
-    };
-
-    const pool = new PowerChunker(items, fn, { poolOptions: { size: 2 }, chunkSize: 2 });
-
-    const chunkResults = [];
-    pool.onmessage = (e) => {
-      if (e && e.data) chunkResults.push(e.data);
-    };
-
-    await pool.drain();
-
-    // flatten per-item results
-    const all = chunkResults.flatMap((c) => c.results || []);
-
-    // should contain two errors (SYNC_CODE and ASYNC_CODE) and two numeric results
-    const codes = all
-      .filter((r) => r && r.error)
-      .map((r) => r.code)
-      .sort();
-    expect(codes).to.include('SYNC_CODE');
-    expect(codes).to.include('ASYNC_CODE');
-
-    const numbers = all.filter((r) => !r || !r.error);
-    // two successful items 1 and 4 -> 10 and 40
-    expect(numbers).to.include(10);
-    expect(numbers).to.include(40);
-
-    pool.terminate();
-  });
-
-  it('surfaces batch dispatch failures via pool error listeners', async () => {
-    const pool = new PowerChunker([1, 2, 3], (item) => item, {
-      chunkSize: 1,
-      poolOptions: {
-        size: 1,
-        minSize: 1,
-        maxSize: 1,
-        maxTasksPerWorker: 0,
-        taskQueue: true,
-        queuePolicy: 'reject',
-        lazy: false,
-      },
-    });
-
-    const errors = [];
-    pool.addEventListener('error', (err) => errors.push(err));
-
-    await Promise.resolve();
-    await new Promise((resolve) => setTimeout(resolve, 0));
-
-    expect(errors.length).to.be.greaterThan(0);
-    expect(errors[0]).to.include({ code: 'ECHUNKDISPATCH', mode: 'batch' });
-
-    pool.terminate();
-  });
-
-  it('reports global failed chunk indexes across array dispatch windows', async () => {
-    const items = Array.from({ length: 20 }, (_, i) => i + 1);
-    const pool = new PowerChunker(items, (item) => item, {
-      chunkSize: 1,
-      poolOptions: {
-        size: 1,
-        minSize: 1,
-        maxSize: 1,
-        maxTasksPerWorker: 0,
-        taskQueue: true,
-        queuePolicy: 'reject',
-        lazy: false,
-      },
-    });
-
-    const errors = [];
-    pool.addEventListener('error', (err) => errors.push(err));
-
-    await Promise.resolve();
-    await new Promise((resolve) => setTimeout(resolve, 0));
-
-    const batchErrors = errors.filter(
-      (err) => err && err.code === 'ECHUNKDISPATCH' && err.mode === 'batch'
-    );
-    expect(batchErrors.length).to.be.greaterThan(0);
-    for (const err of batchErrors) {
-      expect(Array.isArray(err.failedChunks)).to.equal(true);
-      for (const idx of err.failedChunks) {
-        expect(Number.isInteger(idx)).to.equal(true);
-        expect(idx).to.be.at.least(0);
-        expect(idx).to.be.below(items.length);
-      }
-    }
-
-    pool.terminate();
-  });
-
-  it('surfaces stream dispatch failures via pool error listeners', async () => {
-    function* items() {
-      yield 1;
-      yield 2;
-      yield 3;
-    }
-
-    const pool = new PowerChunker(items(), (item) => item, {
-      chunkSize: 1,
-      poolOptions: {
-        size: 1,
-        minSize: 1,
-        maxSize: 1,
-        maxTasksPerWorker: 0,
-        taskQueue: true,
-        queuePolicy: 'reject',
-        lazy: false,
-      },
-    });
-
-    const errors = [];
-    pool.addEventListener('error', (err) => errors.push(err));
-
-    await Promise.resolve();
-    await new Promise((resolve) => setTimeout(resolve, 0));
-
-    expect(
-      errors.some((err) => err && err.code === 'ECHUNKDISPATCH' && err.mode === 'stream')
-    ).to.equal(true);
-
-    pool.terminate();
-  });
-
-  it('emits stream-iterate errors when the input iterable throws', async () => {
-    function* badItems() {
-      yield 1;
-      throw new Error('iter boom');
-    }
-
-    const pool = new PowerChunker(badItems(), (item) => item, {
-      chunkSize: 1,
-      poolOptions: {
-        size: 1,
-        minSize: 1,
-        maxSize: 1,
-        taskQueue: true,
-        queuePolicy: 'enqueue',
-        lazy: false,
-      },
-    });
-
-    const errors = [];
-    pool.addEventListener('error', (err) => errors.push(err));
-
-    await Promise.resolve();
-    await new Promise((resolve) => setTimeout(resolve, 0));
-
-    expect(
-      errors.some((err) => err && err.code === 'ECHUNKDISPATCH' && err.mode === 'stream-iterate')
-    ).to.equal(true);
-
-    pool.terminate();
-  });
-});

package/test/powerChunking.test.js

@@ -1,39 +0,0 @@
-import { expect } from 'chai';
-import { describe, it } from 'vitest';
-import { PowerChunker } from '../src/helpers/powerChunking.js';
-
-describe('PowerChunking helper', () => {
-  it('processes all items in chunks and returns processed counts (awaitResponse)', async () => {
-    const items = Array.from({ length: 50 }, (_, i) => i + 1);
-    const processed = [];
-    const fn = (item) => {
-      processed.push(item);
-    };
-    const pool = new PowerChunker(items, fn, { poolOptions: { size: 2 } });
-    expect(pool && typeof pool.postMessageBatch === 'function').to.equal(true);
-    // wait until the pool has finished processing all chunks
-    await pool.drain();
-    // ensure the fn ran for each item
-    expect(processed.length).to.equal(items.length);
-    pool.terminate();
-  });
-
-  it('uses explicit chunkSize when provided', () => {
-    const items = Array.from({ length: 10 }, (_, i) => i);
-    const fn = () => {};
-    const pool = new PowerChunker(items, fn, { poolOptions: { size: 2 }, chunkSize: 3 });
-    // Each processed chunk emits one `message` event; wait for drain and verify
-    let messageCount = 0;
-    let totalProcessed = 0;
-    pool.onmessage = (e) => {
-      messageCount++;
-      if (e && e.data && e.data.processed) totalProcessed += e.data.processed;
-    };
-    return pool.drain().then(() => {
-      // Ensure all items were processed and at least the expected number of chunk messages occurred
-      expect(totalProcessed).to.equal(items.length);
-      expect(messageCount).to.be.at.least(Math.ceil(items.length / 3));
-      pool.terminate();
-    });
-  });
-});

package/test/powerCircuit.observability.test.js

@@ -1,71 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import PowerCircuit from '../src/helpers/powerCircuit.js';
-import { PowerEventBus } from '../src/helpers/powerEventBus.js';
-
-describe('PowerCircuit observability', () => {
-  it('calls onStateChange callback when state transitions occur', async () => {
-    const calls = [];
-    const cb = new PowerCircuit({
-      threshold: 1,
-      timeout: 10,
-      onStateChange: (s, r) => calls.push([s, r]),
-    });
-
-    // cause a failure to open the circuit
-    await cb.call(() => Promise.reject(new Error('fail'))).catch(() => {});
-
-    // after one failure threshold=1 -> should open
-    expect(calls.length).toBeGreaterThanOrEqual(1);
-    expect(calls[0][0]).toBe('open');
-    expect(calls[0][1]).toBe('thresholdExceeded');
-
-    // advance through timeout by waiting
-    await new Promise((res) => setTimeout(res, 15));
-
-    // next call should cause half-open then success -> closed
-    await cb.call(() => Promise.resolve('ok'));
-
-    // find closed event
-    const closed = calls.find(([s]) => s === 'closed');
-    expect(closed).toBeTruthy();
-  });
-
-  it('swallows errors thrown by onStateChange and event bus observers', async () => {
-    const bus = new PowerEventBus();
-    bus.on('stateChange', () => {
-      throw new Error('bus observer failed');
-    });
-
-    const cb = new PowerCircuit({
-      threshold: 1,
-      timeout: 10,
-      eventBus: bus,
-      onStateChange() {
-        throw new Error('callback failed');
-      },
-    });
-
-    await expect(cb.call(() => Promise.reject(new Error('fail')))).rejects.toThrow('fail');
-    expect(cb.state).toBe('open');
-  });
-
-  it('emits stateChange on provided PowerEventBus', async () => {
-    const bus = new PowerEventBus();
-    const events = [];
-    bus.on('stateChange', (payload) => events.push(payload));
-
-    const cb = new PowerCircuit({ threshold: 1, timeout: 10, eventBus: bus });
-
-    await cb.call(() => Promise.reject(new Error('boom'))).catch(() => {});
-
-    expect(events.length).toBeGreaterThanOrEqual(1);
-    expect(events[0].state).toBe('open');
-    expect(events[0].reason).toBe('thresholdExceeded');
-
-    await new Promise((res) => setTimeout(res, 15));
-    await cb.call(() => Promise.resolve('ok'));
-
-    const closedEvent = events.find((e) => e.state === 'closed');
-    expect(closedEvent).toBeTruthy();
-  });
-});

package/test/powerCircuit.test.js

@@ -1,74 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerCircuit } from '../src/helpers/powerCircuit.js';
-
-describe('PowerCircuit', () => {
-  it('throws when fn is not a function', async () => {
-    const cb = new PowerCircuit();
-    await expect(cb.call(null)).rejects.toThrow('fn must be a function');
-  });
-
-  it('opens after threshold failures and short-circuits', async () => {
-    const cb = new PowerCircuit({ threshold: 2, timeout: 50 });
-    let fail = true;
-    const f = async () => {
-      if (fail) throw new Error('boom');
-      return 'ok';
-    };
-
-    await expect(cb.call(f)).rejects.toThrow('boom');
-    expect(cb.failures).toBe(1);
-    // second failure triggers open
-    await expect(cb.call(f)).rejects.toThrow('boom');
-    expect(cb.state).toBe('open');
-    expect(cb.failures).toBe(0);
-    expect(cb.lastError).toBeInstanceOf(Error);
-    // subsequent calls short-circuit
-    await expect(cb.call(f)).rejects.toHaveProperty('code', 'ECIRCUITOPEN');
-  });
-
-  it('allows trial after timeout and recovers on success', async () => {
-    const cb = new PowerCircuit({ threshold: 1, timeout: 50 });
-    // cause one failure to open
-    await expect(cb.call(() => Promise.reject(new Error('e1')))).rejects.toThrow();
-    expect(cb.state).toBe('open');
-    // wait for timeout to allow half-open
-    await new Promise((r) => setTimeout(r, 60));
-    expect(cb.state).toBe('half-open');
-    // now succeed
-    const res = await cb.call(() => Promise.resolve('ok'));
-    expect(res).toBe('ok');
-    expect(cb.state).toBe('closed');
-    expect(cb.failures).toBe(0);
-    expect(cb.lastError).toBe(null);
-  });
-
-  it('reopens when the half-open trial fails', async () => {
-    const cb = new PowerCircuit({ threshold: 1, timeout: 10 });
-
-    await expect(cb.call(() => Promise.reject(new Error('first fail')))).rejects.toThrow(
-      'first fail'
-    );
-    expect(cb.state).toBe('open');
-
-    await new Promise((r) => setTimeout(r, 15));
-    expect(cb.state).toBe('half-open');
-
-    await expect(cb.call(() => Promise.reject(new Error('trial fail')))).rejects.toThrow(
-      'trial fail'
-    );
-    expect(cb.state).toBe('open');
-    expect(cb.failures).toBe(0);
-  });
-
-  it('reset closes the circuit and clears failure state', async () => {
-    const cb = new PowerCircuit({ threshold: 1, timeout: 50 });
-    await expect(cb.call(() => Promise.reject(new Error('boom')))).rejects.toThrow('boom');
-    expect(cb.state).toBe('open');
-
-    cb.reset();
-
-    expect(cb.state).toBe('closed');
-    expect(cb.failures).toBe(0);
-    expect(cb.lastError).toBe(null);
-  });
-});

package/test/powerDeadline.test.js

@@ -1,140 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerDeadline } from '../src/helpers/powerDeadline.js';
-
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-describe('PowerDeadline', () => {
-  it('resolves when the function completes before timeout', async () => {
-    const value = await PowerDeadline.run(
-      async () => {
-        await delay(10);
-        return 'ok';
-      },
-      { attemptTimeout: 100 }
-    );
-
-    expect(value).toBe('ok');
-  });
-
-  it('rejects with ETIMEOUT when an attempt exceeds attemptTimeout', async () => {
-    await expect(
-      PowerDeadline.run(
-        async () => {
-          await delay(50);
-        },
-        { attemptTimeout: 10 }
-      )
-    ).rejects.toHaveProperty('code', 'ETIMEOUT');
-  });
-
-  it('rejects with EDEADLINE when totalTimeout is exceeded', async () => {
-    await expect(
-      PowerDeadline.run(
-        async () => {
-          await delay(100);
-        },
-        { maxAttempts: 3, totalTimeout: 50, retryDelay: 10 }
-      )
-    ).rejects.toHaveProperty('code', 'EDEADLINE');
-  });
-
-  it('retries failed attempts when retryIf returns true', async () => {
-    let calls = 0;
-    const value = await PowerDeadline.run(
-      async () => {
-        calls += 1;
-        if (calls < 2) throw new Error('try again');
-        return 'done';
-      },
-      { maxAttempts: 3, retryDelay: 5, retryIf: () => true }
-    );
-
-    expect(value).toBe('done');
-    expect(calls).toBe(2);
-  });
-
-  it('supports AbortSignal cancellation', async () => {
-    const controller = new AbortController();
-    const promise = PowerDeadline.run(
-      async () => {
-        await delay(50);
-      },
-      { signal: controller.signal, attemptTimeout: 100 }
-    );
-
-    controller.abort();
-    await expect(promise).rejects.toHaveProperty('code', 'EABORT');
-  });
-
-  it('propagates attempts metadata on rejection', async () => {
-    await expect(
-      PowerDeadline.run(
-        async () => {
-          throw new Error('bad');
-        },
-        { maxAttempts: 2, retryIf: () => false }
-      )
-    ).rejects.toMatchObject({ attempts: 1, attemptTimeout: null });
-  });
-
-  it('throws TypeError when fn is not callable', async () => {
-    await expect(PowerDeadline.run(null)).rejects.toThrow(TypeError);
-  });
-
-  it('rejects immediately when the abort signal is already aborted', async () => {
-    const controller = new AbortController();
-    controller.abort('user cancelled');
-
-    await expect(
-      PowerDeadline.run(async () => 'never', { signal: controller.signal, totalTimeout: 25 })
-    ).rejects.toMatchObject({
-      code: 'EABORT',
-      reason: 'user cancelled',
-      attempts: 1,
-      totalTimeout: 25,
-    });
-  });
-
-  it('treats boolean retryIf values as retry predicates', async () => {
-    let calls = 0;
-    const value = await PowerDeadline.run(
-      async () => {
-        calls += 1;
-        if (calls === 1) throw new Error('retry once');
-        return 'ok';
-      },
-      { maxAttempts: 2, retryIf: true }
-    );
-
-    expect(value).toBe('ok');
-    expect(calls).toBe(2);
-  });
-
-  it('merges instance defaults with per-call overrides', async () => {
-    let calls = 0;
-    const deadline = new PowerDeadline({ maxAttempts: 3, retryIf: true });
-    const value = await deadline.run(
-      async () => {
-        calls += 1;
-        if (calls < 2) throw new Error('retry from instance');
-        return 'done';
-      },
-      { retryDelay: 1 }
-    );
-
-    expect(value).toBe('done');
-    expect(calls).toBe(2);
-  });
-
-  it('stops before an attempt starts when the total deadline is already exhausted', async () => {
-    await expect(
-      PowerDeadline.run(
-        async () => {
-          await delay(10);
-          throw new Error('too late');
-        },
-        { maxAttempts: 3, totalTimeout: 1, retryDelay: 5, retryIf: true }
-      )
-    ).rejects.toMatchObject({ code: 'EDEADLINE' });
-  });
-});