performance-helpers

Highly tuned lightweight toolbox for high-performance Node/browser code: zero-copy buffer helpers for worker messaging, an environment-agnostic worker abstraction (WorkerAgnostic), an LRU TTL cache with a memoizer, a fully-featured worker pool wrapper, a tiny runtime debug logger, and much more:

Caching

• PowerCache: Caching (LRU + TTL + weight) and memoizing. An in-memory, memory-efficient LRU cache with TTL, weighted eviction and an optional reusable node pool.
• PowerTTLMap: Map with per-key TTL. Lightweight Map-like store where keys expire lazily on access.

Parallelizing

• PowerPool: Worker pool. A small, dependency-free worker pool that wraps underlying Worker instances.
• PowerChunker: Chunk + pool helper. Convenience helper to chunk iterables and process items via a PowerPool.
• PowerBulkhead: Partitioned executor. Isolate noisy workloads into separate lanes so one hot partition cannot starve the rest.
• PowerCircuit: Circuit breaker. Small circuit breaker to protect external services from cascading failures.
• PowerRetry: Retry with backoff. Helper for retrying flaky async operations with configurable backoff and jitter.
• PowerDeadline: Timeout, retry budget, and cancellation. Wrap async work with per-attempt timeouts, overall deadlines, and retry policy.
• PowerHistogram: Lock-free percentile estimator. Compact in-process histogram for latency telemetry and estimated percentiles.
• PowerBackpressure: Producer-facing backpressure controller. Gate producers with adaptive refill and bounded waiting.
• PowerBatch: Microtask coalescing dispatcher. Coalesce synchronous calls into compact batches for bulk operations.
• PowerLatch: Counting barrier. Simple barrier that resolves when a count reaches zero. Useful for coordinating out-of-band task completions.
• PowerThrottle: A token-bucket limiter. A tiny rate limiter useful for pacing external work or cooperating with PowerPool. New: supports reserve()/release() for reservation-style workflows.
• PowerRateLimit: Compose multiple limiters. Combine PowerThrottle, PowerSlidingWindow and others; supports an atomic option to attempt atomic consumes across composed limiters.
• PowerSlidingWindow: Sliding-window limiter. A simple rolling-window limiter for quota-style rate limiting.
• PowerQueue: O(1) ring-buffer queue. A resizable, high-performance queue intended for use in PowerPool and other high-throughput scenarios.
• PowerSemaphore: Async concurrency gate. Lightweight semaphore for limiting concurrent I/O and fan-out workloads.
• PowerEventBus: Typed micro event bus. Lightweight pub/sub for intra-process coordination between helpers.

Logging

• PowerLogger: Gated logging. Simple runtime debug gate and in-memory counters useful for lightweight instrumentation and tests.

Utils

• PowerBuffer: Encode/decode JS objects to transferables for worker messaging. Lightweight helpers for encoding/decoding JSON to/from binary (Uint8Array / ArrayBuffer / Node Buffer).
• PowerDefer: Deferred promise primitive. Small utility that separates a Promise from its resolve/reject functions.
• PowerPermitGate: Permit queue helper. Low-level concurrency gate that manages permits and FIFO waiters for building semaphore or backpressure primitives.
• PowerScheduler: Work coalescing scheduler. Lightweight scheduler for batching deferred work into a single microtask or macrotask flush.
• PowerSubscriberSet: Shared listener registry. Internal subscriber helper with optional weak references and once-listener support.
• PowerObserver: Lightweight reactive value. Tiny observable primitive for synchronous subscriptions to a single value.
• Now utilities: high-resolution timers and measure helpers — nowMs(), measureSync(), measureAsync() and timing best-practices.
• Errors utilities: recommended error shapes and patterns — guidance for attaching duration, correlationId and structured diagnostics to errors and responses.

When to use what

Check the Quick Guide

Quick start

Requirements: Node.js and npm.

Install dependencies:

npm install

Install the package from npm for direct use in your project:

npm install --save performance-helpers
# or
yarn add performance-helpers

Run tests:

npm run test

Run coverage (v8):

npm run test:coverage

Quality bar

Helpers intended to be Tier 1 in this repository should meet a consistent bar:

• dedicated guide plus README coverage
• concise JSDoc for public constructor options and methods
• focused regression tests for edge cases and failure paths
• repo-wide coverage stays above the Vitest thresholds, and Tier 1 promotion work raises the helper's own file coverage to the same bar
• no known open correctness bugs in the public contract

Helpers that remain larger or more experimental can stay as advanced helpers, but Tier 1 helpers should be predictable, narrow in scope, and cheap to maintain.

Current classification notes:

• PowerPool is an advanced helper by design. It has a broader surface area than the narrow Tier 1 primitives, so coverage and maintenance expectations should be interpreted with that scope in mind.
• PowerRateLimit is treated as a metric outlier for function coverage. Its public behavior and rollback paths are heavily covered; the remaining low function number is not currently considered a release blocker on its own.
• Promotion work should prioritize public correctness, narrow APIs, and edge-case coverage before chasing residual coverage misses in broad orchestration helpers.

Build (Vite):

npm run build

Generate docs (Typedoc):

npm run docs

Usage examples

Import everything from the package entry:

import {
  o2b,
  o2u8,
  u82o,
  b2o,
  PowerCache,
  PowerMemoizer,
  PowerTimedCache,
  PowerPool,
  PowerLogger,
  PowerThrottle,
  PowerSlidingWindow,
  PowerRateLimit,
  PowerQueue,
  PowerSemaphore,
  PowerDefer,
  PowerTTLMap,
  nowMs,
  measureSync,
  measureAsync,
  PowerCircuit,
  PowerRetry,
  PowerDeadline,
  PowerHistogram,
  PowerBackpressure,
  PowerBatch,
  PowerBulkhead,
  PowerLatch,
  PowerObserver,
  PowerEventBus,
} from 'performance-helpers';

Import a single helper or utility when you want the smallest possible bundle:

import { PowerCache } from 'performance-helpers/powerCache';
import { nowMs } from 'performance-helpers/now';
import { normalizeError } from 'performance-helpers/errors';

The package is marked as side-effect free, so bundlers can treeshake unused exports from the root entry as well.

CDN usage

You can import the package directly from a CDN for quick demos. Example using unpkg (ES module support):

<script type="module">
  import { PowerMemoizer } from 'https://unpkg.com/performance-helpers@latest?module';
  const fetchUser = async (id) => fetch(`/users/${id}`).then((r) => r.json());
  const pm = new PowerMemoizer(fetchUser);
  console.log(await pm.run(1));
</script>

Or using jsDelivr:

<script type="module">
  import { PowerCache } from 'https://cdn.jsdelivr.net/npm/performance-helpers@latest/dist/index.js';
  const cache = new PowerCache();
  cache.set('a', 1);
  console.log(cache.get('a'));
</script>

UMD example (script tag):

<script src="https://unpkg.com/performance-helpers@latest/dist/performance-helpers.umd.js"></script>
<script>
  // UMD builds attach a global. Use the global that your build exposes.
  const lib = window.PerformanceHelpers;
  const { PowerCache } = lib || {};
  const cache = new PowerCache();
  cache.set('a', 2);
  console.log(cache.get('a'));
</script>

Worker support: Node and the browser

WorkerAgnostic (re-exported from performance-helpers/WorkerAgnostic) gives you one transparent API for spawning and talking to a worker whether you are on Node.js (worker_threads) or in a browser / Web Worker context (Web Worker). PowerPool uses it under the hood, so the pool is environment-agnostic too.

import WorkerAgnostic, { detectEnv, preloadNode } from 'performance-helpers/WorkerAgnostic';

console.log(detectEnv()); // 'node' | 'browser' | 'webworker' | 'unknown'

const worker = new WorkerAgnostic('./myWorker.js', { type: 'module' });
worker.addEventListener('message', (ev) => console.log(ev.data));
worker.postMessage({ hello: 'world' });
await worker.terminate();

What is transparent:

• Worker creation from a path string, a factory function, or a constructor — the correct native worker is chosen for the runtime.
• The event model (addEventListener/removeEventListener and Node-style on/off) and postMessage(message, transfer) transfer lists.
• Message payloads are normalized to { data } (Node delivers the value directly; Web Workers deliver a MessageEvent whose payload is on .data).
• terminate() always returns a Promise.

Caveats you should know:

1. Pure-ESM Node + string-source workers need one await preloadNode() call before constructing the worker (or set globalThis.Worker, or pass a factory function). This is the only non-transparent seam. CJS/vitest, factory-function sources, and all browser paths do not need it.

   import WorkerAgnostic, { preloadNode } from 'performance-helpers/WorkerAgnostic';
   await preloadNode();
   const worker = new WorkerAgnostic('./myWorker.js', { type: 'module' });

2. Transparency covers creation and messaging, not your worker's internals. WorkerAgnostic spawns the correct native worker and unifies the API, but the worker source file you write must still be valid for its target runtime (Node worker_threads uses parentPort; a browser worker uses self.onmessage). It does not transpile worker code between environments.

3. Browser usage requires a bundler or an ESM CDN. The package ships as raw ESM source (no prebuilt UMD/browser bundle is required for the worker layer). In a bundler or a <script type="module"> from a CDN, WorkerAgnostic resolves the worker URL against import.meta.url / document.currentScript / location.href and falls back to the plain string.

API docs

See the full API documentation

License

MIT.