performance-helpers 1.0.0 → 1.0.1

package/test/powerBatch.branches.extra.test.js

@@ -1,122 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerBatch } from '../src/helpers/powerBatch.js';
-
-describe('PowerBatch branches extra', () => {
-  it('constructor throws when handler not a function', () => {
-    expect(() => new PowerBatch(null)).toThrow();
-  });
-
-  it('flush returns resolved promise when empty and not scheduled', async () => {
-    const b = new PowerBatch(async () => {});
-    // ensure empty
-    expect(b.size).toBe(0);
-    const res = await b.flush();
-    expect(res).toBeUndefined();
-  });
-
-  it('add schedules handler and resolves regular add promise', async () => {
-    let called = false;
-    const b = new PowerBatch(async (items) => {
-      called = true;
-      expect(items.length).toBeGreaterThan(0);
-    });
-    const p = b.add(1);
-    await p;
-    // wait a tick for handler
-    await new Promise((r) => setTimeout(r, 10));
-    expect(called).toBe(true);
-  });
-
-  it('flush returns a promise that rejects when handler throws', async () => {
-    const b = new PowerBatch(async () => {
-      throw new Error('boom');
-    });
-    b.add(1);
-    await expect(b.flush()).rejects.toThrow('boom');
-  });
-
-  it('clear rejects pending add promises and empties queue', async () => {
-    let called = false;
-    const b = new PowerBatch(async () => {
-      called = true;
-    });
-    const promise = b.add(1);
-    b.clear();
-    await expect(promise).rejects.toThrow('PowerBatch cleared before flush');
-    await new Promise((r) => setTimeout(r, 10));
-    expect(called).toBe(false);
-    expect(b.size).toBe(0);
-  });
-
-  it('creates a fresh pending batch for items added while the handler is running', async () => {
-    const calls = [];
-    let releaseFirstBatch;
-    const firstBatchGate = new Promise((resolve) => {
-      releaseFirstBatch = resolve;
-    });
-
-    const b = new PowerBatch(async (items) => {
-      calls.push(items.slice());
-      if (calls.length === 1) {
-        await firstBatchGate;
-      }
-    });
-
-    const first = b.add('a');
-    await Promise.resolve();
-    const second = b.add('b');
-    releaseFirstBatch();
-
-    await Promise.all([first, second]);
-
-    expect(calls).toEqual([['a'], ['b']]);
-  });
-
-  it('normalizes invalid maxSize and scheduling options', async () => {
-    const calls = [];
-    const b = new PowerBatch(
-      async (items) => {
-        calls.push(items.slice());
-      },
-      { maxSize: 0, scheduling: 'invalid' }
-    );
-
-    b.add(1);
-    b.add(2);
-    await b.flush();
-
-    expect(calls).toEqual([[1, 2]]);
-  });
-
-  it('flush re-schedules queued work if a pending batch exists but the scheduler was canceled', async () => {
-    const calls = [];
-    const b = new PowerBatch(async (items) => {
-      calls.push(items.slice());
-    });
-
-    const addPromise = b.add('x');
-    b._scheduler.cancel();
-
-    await b.flush();
-    await addPromise;
-
-    expect(calls).toEqual([['x']]);
-  });
-
-  it('resolves orphaned pending promises on empty internal runs and rethrows handler errors without pending state', async () => {
-    const b = new PowerBatch(async () => {});
-    const pending = b.add('x');
-    b._queue.clear();
-
-    await b._runBatch();
-    await expect(pending).resolves.toBeUndefined();
-    expect(b._pending).toBeNull();
-
-    const b2 = new PowerBatch(async () => {
-      throw new Error('boom');
-    });
-    b2._queue.push('y');
-
-    await expect(b2._runBatch()).rejects.toThrow('boom');
-  });
-});

package/test/powerBatch.test.js

@@ -1,79 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerBatch } from '../src/helpers/powerBatch.js';
-
-describe('PowerBatch', () => {
-  it('coalesces synchronous adds into a single handler call', async () => {
-    const calls = [];
-    const handler = async (items) => {
-      calls.push(items.slice());
-    };
-    const b = new PowerBatch(handler);
-    b.add(1);
-    b.add(2);
-    await b.flush();
-    expect(calls.length).toBe(1);
-    expect(calls[0]).toEqual([1, 2]);
-  });
-
-  it('flushes immediately when maxSize is reached', async () => {
-    const calls = [];
-    const handler = (items) => calls.push(items.slice());
-    const b = new PowerBatch(handler, { maxSize: 2 });
-    b.add('a');
-    await b.add('b'); // this should trigger immediate flush
-    expect(calls.length).toBe(1);
-    expect(calls[0]).toEqual(['a', 'b']);
-  });
-
-  it('flush waits for async handler completion', async () => {
-    const calls = [];
-    const handler = async (items) => {
-      await new Promise((r) => setTimeout(r, 10));
-      calls.push(items.slice());
-    };
-    const b = new PowerBatch(handler);
-    b.add(42);
-    await b.flush();
-    expect(calls.length).toBe(1);
-    expect(calls[0]).toEqual([42]);
-  });
-
-  it('add returns a promise that resolves after the handler completes', async () => {
-    const calls = [];
-    const handler = async (items) => {
-      await new Promise((r) => setTimeout(r, 10));
-      calls.push(items.slice());
-    };
-    const b = new PowerBatch(handler);
-    const promise = b.add('x');
-    expect(promise).toBeInstanceOf(Promise);
-    await promise;
-    expect(calls).toEqual([['x']]);
-  });
-
-  it('add resolves after async handler completion when maxSize triggers immediate flush', async () => {
-    const calls = [];
-    const handler = async (items) => {
-      await new Promise((r) => setTimeout(r, 10));
-      calls.push(items.slice());
-    };
-    const b = new PowerBatch(handler, { maxSize: 2 });
-    const promise = b.add('a');
-    const promise2 = b.add('b');
-    expect(promise).toBeInstanceOf(Promise);
-    expect(promise2).toBeInstanceOf(Promise);
-    await Promise.all([promise, promise2]);
-    expect(calls).toEqual([['a', 'b']]);
-  });
-
-  it('accepts scheduling option (macrotask) and preserves basic behavior', async () => {
-    const calls = [];
-    const handler = (items) => calls.push(items.slice());
-    const b = new PowerBatch(handler, { scheduling: 'macrotask' });
-    b.add('x');
-    b.add('y');
-    await b.flush();
-    expect(calls.length).toBe(1);
-    expect(calls[0]).toEqual(['x', 'y']);
-  });
-});

package/test/powerBuffer.test.js

@@ -1,125 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-
-describe('powerBuffer', () => {
-  it('encodes and decodes plain objects', async () => {
-    const mod = await import('../src/helpers/powerBuffer.js');
-    const { o2u8, u82o } = mod;
-    const obj = { a: 1, b: 'x' };
-    const u8 = o2u8(obj);
-    expect(u8).toBeInstanceOf(Uint8Array);
-    const decoded = u82o(u8);
-    expect(decoded).toEqual(obj);
-  });
-
-  it('accepts ArrayBuffer and returns Uint8Array view', async () => {
-    const { o2u8 } = await import('../src/helpers/powerBuffer.js');
-    const buf = new ArrayBuffer(4);
-    const view = new Uint8Array(buf);
-    view[0] = 1;
-    const u8 = o2u8(buf);
-    expect(u8).toBeInstanceOf(Uint8Array);
-    expect(u8[0]).toBe(1);
-  });
-
-  it('o2b and b2o roundtrip', async () => {
-    const { o2b, b2o } = await import('../src/helpers/powerBuffer.js');
-    const obj = { z: [1, 2, 3], s: 'hello' };
-    const ab = o2b(obj);
-    expect(ab).toBeInstanceOf(ArrayBuffer);
-    const out = b2o(ab);
-    expect(out).toEqual(obj);
-  });
-
-  it('falls back to Buffer-based encoder/decoder when TextEncoder/TextDecoder are absent', async () => {
-    // Reload module with globals stubbed
-    vi.resetModules();
-    const origTE = global.TextEncoder;
-    const origTD = global.TextDecoder;
-    try {
-      // remove TextEncoder/TextDecoder to force Buffer fallback
-      // @ts-ignore
-      global.TextEncoder = undefined;
-      // @ts-ignore
-      global.TextDecoder = undefined;
-      const mod = await import('../src/helpers/powerBuffer.js');
-      const { o2u8, u82o } = mod;
-      const obj = { fallback: true };
-      const u8 = o2u8(obj);
-      expect(u8).toBeInstanceOf(Uint8Array);
-      const decoded = u82o(u8);
-      expect(decoded).toEqual(obj);
-    } finally {
-      // restore
-      // @ts-ignore
-      global.TextEncoder = origTE;
-      // @ts-ignore
-      global.TextDecoder = origTD;
-    }
-  });
-
-  it('returns the same Uint8Array instance when passed through', async () => {
-    const { o2u8 } = await import('../src/helpers/powerBuffer.js');
-    const ua = new Uint8Array([1, 2, 3]);
-    const out = o2u8(ua);
-    expect(out).toBe(ua);
-  });
-
-  it('handles typed-array views and o2b produces a sliced ArrayBuffer when offset present', async () => {
-    const mod = await import('../src/helpers/powerBuffer.js');
-    const { o2u8, o2b } = mod;
-    const buf = new ArrayBuffer(8);
-    const view = new Uint8Array(buf, 2, 4);
-    view.set([9, 8, 7, 6]);
-    const u8 = o2u8(view);
-    expect(u8).toBeInstanceOf(Uint8Array);
-    const ab = o2b(view);
-    expect(ab).toBeInstanceOf(ArrayBuffer);
-    expect(ab.byteLength).toBe(u8.byteLength);
-    expect(ab).not.toBe(u8.buffer);
-  });
-
-  it('u82o accepts Node Buffer and decodes to object', async () => {
-    const { u82o } = await import('../src/helpers/powerBuffer.js');
-    const obj = { foo: 'bar' };
-    // Node Buffer path
-    const buf = Buffer.from(JSON.stringify(obj));
-    const out = u82o(buf);
-    expect(out).toEqual(obj);
-  });
-
-  it('u82o throws for unsupported input types', async () => {
-    const { u82o } = await import('../src/helpers/powerBuffer.js');
-    expect(() => u82o('not-a-buffer')).toThrow(TypeError);
-  });
-
-  it('throws when no encoder/decoder available (simulated)', async () => {
-    // reload module with globals removed so getEncoder/getDecoder return null
-    vi.resetModules();
-    const origTE = global.TextEncoder;
-    const origTD = global.TextDecoder;
-    const origBuf = global.Buffer;
-    try {
-      // remove global encoders/Buffer
-      // @ts-ignore
-      global.TextEncoder = undefined;
-      // @ts-ignore
-      global.TextDecoder = undefined;
-      // @ts-ignore
-      global.Buffer = undefined;
-
-      const mod = await import('../src/helpers/powerBuffer.js');
-      const { o2u8, u82o } = mod;
-      expect(() => o2u8({ a: 1 })).toThrow(/No TextEncoder or Buffer available/);
-      const u = new Uint8Array([1, 2, 3]);
-      expect(() => u82o(u)).toThrow(/No TextDecoder or Buffer available/);
-    } finally {
-      // restore
-      // @ts-ignore
-      global.TextEncoder = origTE;
-      // @ts-ignore
-      global.TextDecoder = origTD;
-      // @ts-ignore
-      global.Buffer = origBuf;
-    }
-  });
-});

package/test/powerBulkhead.test.js

@@ -1,210 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { PowerBulkhead } from '../src/helpers/powerBulkhead.js';
-
-describe('PowerBulkhead', () => {
-  it('exposes constructor-derived getters and saturation state', () => {
-    const bulkhead = new PowerBulkhead({ partitions: 3, maxConcurrency: 2, queueCapacity: 4 });
-    expect(bulkhead.partitions).toBe(3);
-    expect(bulkhead.maxConcurrency).toBe(2);
-    expect(bulkhead.queueCapacity).toBe(4);
-    expect(bulkhead.isFull).toBe(false);
-  });
-
-  it('executes tasks immediately while capacity remains in a partition', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 2, maxConcurrency: 2 });
-    const results = await Promise.all([
-      bulkhead.run(() => 1, { partitionKey: 'a' }),
-      bulkhead.run(() => 2, { partitionKey: 'a' }),
-    ]);
-
-    expect(results).toEqual([1, 2]);
-    expect(bulkhead.active).toBe(0);
-    expect(bulkhead.pending).toBe(0);
-  });
-
-  it('queues tasks when partition concurrency is exceeded and dispatches them in FIFO order', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 1, maxConcurrency: 1, queueCapacity: 10 });
-    const firstTask = bulkhead.run(
-      () =>
-        new Promise((resolve) => {
-          setTimeout(() => {
-            resolve('first');
-          }, 20);
-        })
-    );
-
-    const secondTask = bulkhead.run(() => 'second');
-
-    expect(bulkhead.pending).toBe(1);
-    expect(secondTask).toBeInstanceOf(Promise);
-
-    const result = await secondTask;
-    expect(result).toBe('second');
-    expect(await firstTask).toBe('first');
-    expect(bulkhead.pending).toBe(0);
-    expect(bulkhead.active).toBe(0);
-  });
-
-  it('updates active and pending counters as queued work starts running', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 1, maxConcurrency: 1, queueCapacity: 10 });
-    let releaseFirst;
-    let resolveFirstStarted;
-    const firstStarted = new Promise((resolve) => {
-      resolveFirstStarted = resolve;
-    });
-    let resolveSecondStarted;
-    const secondStarted = new Promise((resolve) => {
-      resolveSecondStarted = resolve;
-    });
-
-    const firstTask = bulkhead.run(
-      () =>
-        new Promise((resolve) => {
-          releaseFirst = () => resolve('first');
-          resolveFirstStarted();
-        })
-    );
-
-    const secondTask = bulkhead.run(async () => {
-      resolveSecondStarted();
-      return 'second';
-    });
-
-    expect(bulkhead.active).toBe(1);
-    expect(bulkhead.pending).toBe(1);
-
-    await firstStarted;
-    releaseFirst();
-    await secondStarted;
-
-    expect(bulkhead.active).toBe(1);
-    expect(bulkhead.pending).toBe(0);
-
-    await expect(secondTask).resolves.toBe('second');
-    await expect(firstTask).resolves.toBe('first');
-    expect(bulkhead.active).toBe(0);
-    expect(bulkhead.pending).toBe(0);
-  });
-
-  it('isolates noisy partitions so one partition queue does not block other partitions', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 2, maxConcurrency: 1, queueCapacity: 10 });
-    const executionOrder = [];
-
-    const hot1 = bulkhead.run(
-      () =>
-        new Promise((resolve) => {
-          executionOrder.push('hot-start');
-          setTimeout(() => {
-            executionOrder.push('hot-end');
-            resolve('hot');
-          }, 40);
-        }),
-      { partitionKey: 'hot' }
-    );
-
-    const hot2 = bulkhead.run(() => 'hot-queued', { partitionKey: 'hot' });
-
-    const cold = bulkhead.run(
-      () => {
-        executionOrder.push('cold');
-        return 'cold';
-      },
-      { partitionKey: 'cold' }
-    );
-
-    expect(bulkhead.pending).toBe(1);
-    expect(await cold).toBe('cold');
-    expect(await hot2).toBe('hot-queued');
-    expect(await hot1).toBe('hot');
-    expect(executionOrder).toEqual(['hot-start', 'cold', 'hot-end']);
-  });
-
-  it('rejects new tasks when global queue capacity is exceeded', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 1, maxConcurrency: 1, queueCapacity: 1 });
-
-    bulkhead.run(() => new Promise((resolve) => setTimeout(resolve, 20)));
-
-    const queued = bulkhead.run(() => 'queued');
-    expect(bulkhead.pending).toBe(1);
-    expect(bulkhead.isFull).toBe(true);
-
-    await expect(bulkhead.run(() => 'overflow')).rejects.toThrow('PowerBulkhead queue is full');
-    expect(await queued).toBe('queued');
-  });
-
-  it('tryRun throws for invalid tasks and returns null when partition is busy', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 1, maxConcurrency: 1, queueCapacity: 1 });
-
-    expect(() => bulkhead.tryRun(null)).toThrow('PowerBulkhead.tryRun() requires a function');
-
-    let release;
-    let resolveStarted;
-    const started = new Promise((resolve) => {
-      resolveStarted = resolve;
-    });
-    const running = bulkhead.run(
-      () =>
-        new Promise((resolve) => {
-          release = () => resolve('done');
-          resolveStarted();
-        })
-    );
-
-    await started;
-
-    expect(bulkhead.tryRun(() => 'later')).toBeNull();
-    release();
-    await expect(running).resolves.toBe('done');
-  });
-
-  it('tryRun executes immediately when capacity is available', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 2, maxConcurrency: 1 });
-    await expect(bulkhead.tryRun(() => 'ok')).resolves.toBe('ok');
-    expect(bulkhead.active).toBe(0);
-  });
-
-  it('drain resolves immediately when already idle', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 2, maxConcurrency: 1 });
-    await expect(bulkhead.drain()).resolves.toBeUndefined();
-  });
-
-  it('uses a custom partitioner when provided', async () => {
-    const seen = [];
-    const bulkhead = new PowerBulkhead({
-      partitions: 2,
-      maxConcurrency: 1,
-      partitioner(key) {
-        seen.push(key);
-        return 1;
-      },
-    });
-
-    await expect(bulkhead.run(() => 'ok', { partitionKey: 'custom' })).resolves.toBe('ok');
-    expect(seen).toEqual(['custom']);
-  });
-
-  it('drain() resolves after all active and queued tasks finish', async () => {
-    const bulkhead = new PowerBulkhead({ partitions: 1, maxConcurrency: 1, queueCapacity: 10 });
-    const results = [];
-
-    bulkhead.run(
-      () =>
-        new Promise((resolve) =>
-          setTimeout(() => {
-            results.push('first');
-            resolve('first');
-          }, 20)
-        )
-    );
-
-    bulkhead.run(() => {
-      results.push('second');
-      return 'second';
-    });
-
-    await bulkhead.drain();
-    expect(results).toEqual(['first', 'second']);
-    expect(bulkhead.active).toBe(0);
-    expect(bulkhead.pending).toBe(0);
-  });
-});