performance-helpers 1.0.0

package/.eslintrc.cjs

@@ -0,0 +1,22 @@
+module.exports = {
+  env: {
+    es2021: true,
+    node: true,
+    browser: true,
+  },
+  parserOptions: {
+    ecmaVersion: 2021,
+    sourceType: 'module',
+  },
+  extends: [
+    'eslint:recommended',
+    'plugin:prettier/recommended'
+  ],
+  rules: {
+    semi: ['error', 'always'],
+    quotes: ['error', 'single'],
+    'no-unused-vars': ['warn'],
+    'no-empty': 'off',
+    'no-useless-catch': 'off',
+  },
+};

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

package/CONTRIBUTING.md

@@ -0,0 +1,178 @@
+# Contributing
+
+Thanks for contributing to `performance-helpers`.
+
+This project is a small, performance-focused JavaScript toolbox for Node.js and browser runtimes. Contributions should stay consistent with that goal: small APIs, predictable behavior, low overhead, and clear documentation.
+
+Repository: <https://github.com/AbelVM/performance-helpers>
+
+## Prerequisites
+
+- Node.js 16 or newer
+- npm
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+## Project layout
+
+- `src/helpers/`: helper implementations
+- `src/utils/`: small shared utilities
+- `test/`: Vitest coverage for helpers and edge cases
+- `guides/`: user-facing helper guides
+- `bench/`: benchmark runners and benchmark docs
+- `types/`: generated declaration output
+
+## Development workflow
+
+1. Make the smallest change that solves the problem.
+2. Keep public APIs stable unless the change explicitly requires API work.
+3. Add or update tests for behavior changes.
+4. Update the relevant guide or README entry when user-facing behavior changes.
+5. Run the relevant validation commands before opening a PR.
+
+## Useful commands
+
+Run tests:
+
+```bash
+npm run test
+```
+
+Run linting:
+
+```bash
+npm run lint
+```
+
+Auto-fix lint issues:
+
+```bash
+npm run lint:fix
+```
+
+Format source and markdown:
+
+```bash
+npm run format
+```
+
+Generate declaration files:
+
+```bash
+npm run types:generate
+```
+
+Build the project:
+
+```bash
+npm run build
+```
+
+Generate docs:
+
+```bash
+npm run docs
+```
+
+Run benchmarks:
+
+```bash
+npm run bench
+```
+
+Run the full validation pipeline:
+
+```bash
+npm run build:full
+```
+
+## Coding guidelines
+
+- Prefer plain JavaScript and small abstractions over framework-style layering.
+- Keep hot-path allocations and hidden work low.
+- Avoid adding dependencies unless there is a clear, durable payoff.
+- Preserve the existing naming style and file organization.
+- Write examples and docs using realistic usage patterns, not placeholder pseudocode.
+- When changing helper behavior, consider edge cases such as timeouts, cancellation, queue saturation, expiry, and cleanup.
+
+## Testing expectations
+
+- Add focused tests near the affected helper area in `test/`.
+- Cover both normal behavior and failure or edge cases.
+- Prefer narrow, explicit tests over large multi-concern tests.
+- If a helper has concurrency, timing, or retry behavior, test the boundary conditions.
+- Keep the repository-wide coverage baseline green; use helper-specific work to raise weaker files toward Tier 1.
+
+## Tier 1 helper checklist
+
+Use this checklist when promoting or maintaining a helper as Tier 1:
+
+- The helper has a dedicated guide and a README entry.
+- Public methods and constructor options have concise JSDoc with edge-case behavior spelled out.
+- Behavior-changing work includes focused regression tests.
+- The helper keeps per-file coverage at or above the repository targets during promotion, with branch coverage treated as mandatory.
+- Known correctness issues are fixed before broadening the API.
+- Performance-sensitive paths avoid avoidable allocations, duplicate clocks, and duplicated state machines.
+- If the helper composes other helpers, shared substrate should be reused instead of reimplemented.
+
+Helpers that cannot satisfy this bar without excessive complexity should stay advanced or internal until their scope is reduced.
+
+Current exceptions to treat deliberately rather than mechanically:
+
+- `PowerPool` is an advanced helper. Its scope is intentionally broader than most helpers here, so promotion work should focus on correctness, docs, and high-value edge cases instead of forcing it into the same maintenance profile as the smallest primitives.
+- `PowerRateLimit` currently has an anomalous function-coverage number despite strong public-path coverage. Do not treat that metric alone as proof of missing behavior unless a concrete branch or regression is identified.
+- For broad helpers, prefer documenting scope and trade-offs over adding low-value tests that only improve a report without increasing confidence.
+
+## Documentation expectations
+
+Update documentation when any of the following changes:
+
+- public API
+- constructor options
+- method semantics
+- examples
+- performance trade-offs
+- recommended helper combinations
+
+At minimum, check whether one of these files needs an update:
+
+- `README.md`
+- `guides/*.md`
+- `guides/metaGuide.md`
+
+## Pull requests
+
+A good pull request should include:
+
+- a clear problem statement
+- a concise summary of the change
+- tests for behavior changes
+- docs updates when user-facing behavior changed
+- notes about benchmark impact when performance-sensitive code changed
+
+If the change affects runtime cost, concurrency, or memory behavior, include benchmark numbers or at least a short explanation of the expected trade-off.
+
+## Scope guidance
+
+Good contributions:
+
+- bug fixes
+- test improvements
+- documentation clarifications
+- performance improvements with evidence
+- small, coherent helper enhancements
+
+Higher-risk changes that need extra care:
+
+- public API redesigns
+- new dependencies
+- behavior changes in core helpers like cache, pool, queue, retry, or rate limiting
+- changes that make examples or guides drift from the actual implementation
+
+## Questions
+
+If you are unsure whether a change fits the project, open an issue or draft PR with the intended API, behavior, and trade-offs before expanding the implementation.

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+**Copyright (c) 2026 Abel Vázquez Montoro**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# performance-helpers
+
+[![npm version](https://img.shields.io/npm/v/performance-helpers.svg)](https://www.npmjs.com/package/performance-helpers) [![npm downloads](https://img.shields.io/npm/dm/performance-helpers.svg)](https://www.npmjs.com/package/performance-helpers) [![GitHub stars](https://img.shields.io/github/stars/AbelVM/performance-helpers.svg)](https://github.com/AbelVM/performance-helpers/stargazers) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+
+![logo](assets/logo.png)
+
+Highly tuned lightweight toolbox for high-performance Node/browser code: zero-copy buffer helpers for worker messaging, 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](guides/powerCache.md). An in-memory, memory-efficient LRU cache with TTL, weighted eviction and an optional reusable node pool.
+- [PowerTTLMap: Map with per-key TTL](guides/powerTTLMap.md). Lightweight `Map`-like store where keys expire lazily on access.
+
+## Parallelizing
+
+- [PowerPool: Worker pool](guides/powerPool.md). A small, dependency-free worker pool that wraps underlying Worker instances.
+- [PowerChunker: Chunk + pool helper](guides/powerChunking.md). Convenience helper to chunk iterables and process items via a `PowerPool`.
+- [PowerBulkhead: Partitioned executor](guides/powerBulkhead.md). Isolate noisy workloads into separate lanes so one hot partition cannot starve the rest.
+- [PowerCircuit: Circuit breaker](guides/powerCircuit.md). Small circuit breaker to protect external services from cascading failures.
+- [PowerRetry: Retry with backoff](guides/powerRetry.md). Helper for retrying flaky async operations with configurable backoff and jitter.
+- [PowerDeadline: Timeout, retry budget, and cancellation](guides/powerDeadline.md). Wrap async work with per-attempt timeouts, overall deadlines, and retry policy.
+- [PowerHistogram: Lock-free percentile estimator](guides/powerHistogram.md). Compact in-process histogram for latency telemetry and estimated percentiles.
+- [PowerBackpressure: Producer-facing backpressure controller](guides/powerBackpressure.md). Gate producers with adaptive refill and bounded waiting.
+- [PowerBatch: Microtask coalescing dispatcher](guides/powerBatch.md). Coalesce synchronous calls into compact batches for bulk operations.
+- [PowerLatch: Counting barrier](guides/powerLatch.md). Simple barrier that resolves when a count reaches zero. Useful for coordinating out-of-band task completions.
+- [PowerThrottle: A token-bucket limiter](guides/powerThrottle.md). 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](guides/powerRateLimit.md). Combine `PowerThrottle`, `PowerSlidingWindow` and others; supports an `atomic` option to attempt atomic consumes across composed limiters.
+- [PowerSlidingWindow: Sliding-window limiter](guides/powerSlidingWindow.md). A simple rolling-window limiter for quota-style rate limiting.
+- [PowerQueue: O(1) ring-buffer queue](guides/powerQueue.md). A resizable, high-performance queue intended for use in `PowerPool` and other high-throughput scenarios.
+- [PowerSemaphore: Async concurrency gate](guides/powerSemaphore.md). Lightweight semaphore for limiting concurrent I/O and fan-out workloads.
+- [PowerEventBus: Typed micro event bus](guides/powerEventBus.md). Lightweight pub/sub for intra-process coordination between helpers.
+
+## Logging
+
+- [PowerLogger: Gated logging](guides/powerLogger.md). 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](guides/powerBuffer.md). Lightweight helpers for encoding/decoding JSON to/from binary (Uint8Array / ArrayBuffer / Node Buffer).
+- [PowerDefer: Deferred promise primitive](guides/powerDefer.md). Small utility that separates a `Promise` from its `resolve`/`reject` functions.
+- [PowerPermitGate: Permit queue helper](guides/powerPermitGate.md). Low-level concurrency gate that manages permits and FIFO waiters for building semaphore or backpressure primitives.
+- [PowerScheduler: Work coalescing scheduler](guides/powerScheduler.md). Lightweight scheduler for batching deferred work into a single microtask or macrotask flush.
+- [PowerSubscriberSet: Shared listener registry](guides/powerSubscriberSet.md). Internal subscriber helper with optional weak references and once-listener support.
+- [PowerObserver: Lightweight reactive value](guides/powerObserver.md). Tiny observable primitive for synchronous subscriptions to a single value.
+- [Now utilities: high-resolution timers and measure helpers](guides/now.md) — `nowMs()`, `measureSync()`, `measureAsync()` and timing best-practices.
+- [Errors utilities: recommended error shapes and patterns](guides/errors.md) — guidance for attaching `duration`, `correlationId` and structured diagnostics to errors and responses.
+
+## When to use what
+
+Check the [Quick Guide](guides/metaGuide.md)
+
+## Quick start
+
+Requirements: Node.js and npm.
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Install the package from npm for direct use in your project:
+
+```bash
+npm install --save performance-helpers
+# or
+yarn add performance-helpers
+```
+
+Run tests:
+
+```bash
+npm run test
+```
+
+Run coverage (v8):
+
+```bash
+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):
+
+```bash
+npm run build
+```
+
+Generate docs (Typedoc):
+
+```bash
+npm run docs
+```
+
+## Usage examples
+
+Importing from the package entry (or directly from `src/helpers/*` during development):
+
+```javascript
+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';
+```
+
+## CDN usage
+
+You can import the package directly from a CDN for quick demos. Example using unpkg (ES module support):
+
+```html
+<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:
+
+```html
+<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):
+
+```html
+<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>
+```
+
+## API docs
+
+Full API documentation [here](docs/README.md)
+
+## License
+
+[MIT](LICENSE.md).

package/assets/1_Caching.md

@@ -0,0 +1,4 @@
+# Caching
+
+- [PowerCache: Caching (LRU + TTL + weight) and memoizing](../guides/powerCache.md). An in-memory, memory-efficient LRU cache with TTL, weighted eviction and an optional reusable node pool.
+- [PowerTTLMap: Map with per-key TTL](../guides/powerTTLMap.md). Lightweight `Map`-like store where keys expire lazily on access.

package/assets/2_Parallelizing.md

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

package/assets/3_Logging.md

@@ -0,0 +1,3 @@
+# Logging
+
+- [PowerLogger: Gated logging](../guides/powerLogger.md). Simple runtime debug gate and in-memory counters useful for lightweight instrumentation and tests.

package/assets/404.md

@@ -0,0 +1,3 @@
+# Not found
+
+Go back to [home](../README.md)

package/assets/4_Utils.md

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

package/assets/navigation.md

@@ -0,0 +1,10 @@
+[home](README.md)
+[Quick Guide](guides/metaGuide.md)
+[Caching](assets/1_Caching.md)
+[Parallelizing](assets/2_Parallelizing.md)
+[Logging](assets/3_Logging.md)
+[Utils](assets/4_Utils.md)
+[API](docs/README.md)
+[Benchmark](bench/results.md)
+[Contributing](CONTRIBUTING.md)
+[License](LICENSE.md)

package/bench/README.md

@@ -0,0 +1,97 @@
+# Benchmarks
+
+Lightweight benchmarking helpers for `PowerPool` and `PowerCache`.
+
+This folder contains a small harness (`bench/run.js`) that measures:
+
+- single-threaded CPU-bound compute (baseline) with **p50/p95/p99** per-task latency
+- multi-worker `PowerPool` performance across pool sizes with **speedup vs single-threaded**
+- a simple `PowerCache` hit/miss benchmark
+- `PowerPool + PowerCache` optimized cache reuse patterns
+- `PowerPool` autoscaling performance
+- `PowerMemoizer` memoization overhead with duplicate keys
+- multiple real-world load profiles: `0%`, `25%`, `50%`, `75%`, and `100%` variable load
+- additional realistic scenario benchmarks, including:
+  - `Burstiness`: sudden bursts of work followed by short quiet periods
+  - `Mixed task sizes`: alternating light and heavy work items to mimic uneven request costs
+  - `Ramp traffic`: gradual ramp-up and ramp-down of task submission rates
+  - `Variable payload sizes`: payloads with different serialized sizes to exercise data movement
+  - `I/O bound`: tasks that include small async wait periods to simulate I/O latency
+  - `Thundering herd`: many tasks contending for the same cache key at once
+  - `Cache hit-ratio sweeps`: low/medium/high reuse ratios for cache-backed work
+  - `Cache warmup behavior`: cold vs warm cache performance for repeated workloads
+  - `Cache eviction under pressure`: tight maxEntries (20% of unique keys) measuring LRU overhead
+  - `Serial vs concurrent getOrSetAsync`: in-flight deduplication benefit quantified
+- **helper micro-benchmarks** for primitives not covered by the pool harness:
+  - `PowerRateLimit`: tryConsume throughput under rate (all pass) and over rate (~50% rejected)
+  - `PowerCircuit`: `call()` overhead in closed (happy path) vs open (fast-fail) state
+  - `PowerRetry`: `run()` overhead with 0 retries and 1 retry (baseDelay=0)
+  - `PowerSemaphore`: serial (limit=1) and concurrent (limit=8) permit acquisition
+  - `PowerBulkhead`: single partition vs 2-partition critical/background isolation
+  - `PowerBatch`: individual dispatch (maxSize=1) vs coalesced dispatch
+  - `PowerBackpressure`: acquire/release with no pressure and with capacity=100
+  - `PowerTTLMap`: set/get throughput with long TTL (no eviction) and short TTL (1 ms, high churn)
+  - `PowerEventBus`: `emit` fan-out throughput at 1 / 10 / 50 / 100 subscribers
+  - `PowerDeadline`: success path overhead and abort-path cost when task exceeds deadline
+  - `PowerSlidingWindow`: `tryConsume` throughput under capacity and at capacity
+  - `PowerQueue`: bulk push+shift and interleaved (ring-buffer steady state)
+- **historical delta comparison**: on each run, results are compared against the previous `results.json` and regressions/improvements > 5% are highlighted in the markdown
+
+Quick usage
+
+```bash
+# Run the full benchmark suite (profiles + cache + helpers)
+npm run bench
+
+# Run only the profile-based worker-pool benchmarks (across variable load mixes)
+npm run bench:pool
+
+# Run only the cache workload
+npm run bench:cache
+
+# Run the profile-based pool benchmark directly
+node bench/run.js profiles
+
+# Run only the realistic scenario benchmarks
+node bench/run.js scenarios
+
+# Run only the helper micro-benchmarks
+node bench/run.js helpers
+
+# Alias for the same profile benchmark flow
+node bench/run.js variable
+```
+
+Environment variables (defaults shown)
+
+- `BENCH_TASKS` (default: `1000`) — number of tasks submitted to the pool (or keys for cache benchmark)
+- `BENCH_ITERS` (default: `1000000`) — work per task (higher = heavier per-task CPU)
+- `BENCH_POOLS` (default: `1,2,4,8`) — comma-separated pool sizes when running pool benchmarks
+- `BENCH_POOL_TIMEOUT` (default: `0`) — ms timeout for each `PowerPool` run; set to `0` to disable timeout and let the pool run to completion
+- `BENCH_CACHE_DUPLICATE_KEYS` (default: `10`) — unique key count for cache getOrSetAsync duplicate-key benchmark
+- `BENCH_MEMOIZER_DUPLICATE_KEYS` (default: `10`) — unique key count for PowerMemoizer repeated-call benchmark
+- `BENCH_AUTOSCALE_CACHE_KEYS` (default: `10`) — unique key count for autoscale + cache duplicate-key benchmark
+- `BENCH_POOL_RUNS` (default: `3`) — repeat each pool/scenario variant N times and report the result closest to the median wall-clock time; set to `3` for more stable pool numbers at the cost of a ~3× longer run
+- `BENCH_RUNS` (default: `5`) — repeat each helper micro-benchmark N times and report the median; reduces measurement noise from OS jitter and JIT warm-up variance
+- `BENCH_HELPER_OPS` (default: `100000`) — operation count for each helper micro-benchmark variant
+
+Tips and notes
+
+- Start with small values during iteration: `BENCH_TASKS=2 BENCH_ITERS=10000` to validate changes quickly
+- Use `BENCH_POOL_TIMEOUT=0` when you expect long runs and don't want the harness to fall back to the plain `worker_threads` implementation
+- Use `BENCH_POOL_RUNS=3` for more stable pool benchmark numbers on a noisy machine (runs each pool variant 3 times, reports median)
+- Use `BENCH_RUNS=7` for even more stable helper micro-benchmark numbers on a noisy machine
+- Use `BENCH_HELPER_OPS=10000` to run a quick smoke test of all helpers
+- The harness writes human-readable results to `bench/results.md` and writes a machine-readable copy to `results.json` at the repository root; the markdown contains a link to that file
+
+Example quick smoke run
+
+```bash
+BENCH_TASKS=2 BENCH_ITERS=10000 BENCH_POOLS=1 BENCH_POOL_TIMEOUT=0 BENCH_HELPER_OPS=1000 node bench/run.js pool
+```
+
+Reproducibility
+
+- Run the same `BENCH_TASKS`, `BENCH_ITERS` and `BENCH_POOLS` across machines to compare relative performance
+- Benchmark results are noisy on shared machines; run multiple times and take median/mean as appropriate
+- The `Δ prev` column in the markdown shows changes relative to the previous `results.json` on disk — commit `results.json` to track regressions over time