performance-helpers 1.0.0 → 1.0.1

package/README.md

@@ -111,7 +111,7 @@ npm run docs
 
 ## Usage examples
 
-Importing from the package entry (or directly from `src/helpers/*` during development):
+Import everything from the package entry:
 
 ```javascript
 import {
@@ -147,6 +147,16 @@ import {
 } from 'performance-helpers';
 ```
 
+Import a single helper or utility when you want the smallest possible bundle:
+
+```javascript
+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):
@@ -187,7 +197,7 @@ UMD example (script tag):
 
 ## API docs
 
-Full API documentation [here](docs/README.md)
+See the [full API documentation](docs/README.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "performance-helpers",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Performance toolbox",
   "keywords": [
     "node",
@@ -38,13 +38,158 @@
   "author": "Abel Vázquez Montoro",
   "type": "module",
   "main": "src/index.js",
+  "module": "src/index.js",
   "types": "types/index.d.ts",
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE.md",
+    "package.json"
+  ],
+  "sideEffects": false,
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./src/index.js",
       "require": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./powerBackpressure": {
+      "types": "./types/helpers/powerBackpressure.d.ts",
+      "import": "./src/helpers/powerBackpressure.js",
+      "default": "./src/helpers/powerBackpressure.js"
+    },
+    "./powerBatch": {
+      "types": "./types/helpers/powerBatch.d.ts",
+      "import": "./src/helpers/powerBatch.js",
+      "default": "./src/helpers/powerBatch.js"
+    },
+    "./powerBuffer": {
+      "types": "./types/helpers/powerBuffer.d.ts",
+      "import": "./src/helpers/powerBuffer.js",
+      "default": "./src/helpers/powerBuffer.js"
+    },
+    "./powerBulkhead": {
+      "types": "./types/helpers/powerBulkhead.d.ts",
+      "import": "./src/helpers/powerBulkhead.js",
+      "default": "./src/helpers/powerBulkhead.js"
+    },
+    "./powerCache": {
+      "types": "./types/helpers/powerCache.d.ts",
+      "import": "./src/helpers/powerCache.js",
+      "default": "./src/helpers/powerCache.js"
+    },
+    "./powerChunking": {
+      "types": "./types/helpers/powerChunking.d.ts",
+      "import": "./src/helpers/powerChunking.js",
+      "default": "./src/helpers/powerChunking.js"
+    },
+    "./powerCircuit": {
+      "types": "./types/helpers/powerCircuit.d.ts",
+      "import": "./src/helpers/powerCircuit.js",
+      "default": "./src/helpers/powerCircuit.js"
+    },
+    "./powerDeadline": {
+      "types": "./types/helpers/powerDeadline.d.ts",
+      "import": "./src/helpers/powerDeadline.js",
+      "default": "./src/helpers/powerDeadline.js"
+    },
+    "./powerDefer": {
+      "types": "./types/helpers/powerDefer.d.ts",
+      "import": "./src/helpers/powerDefer.js",
+      "default": "./src/helpers/powerDefer.js"
+    },
+    "./powerEventBus": {
+      "types": "./types/helpers/powerEventBus.d.ts",
+      "import": "./src/helpers/powerEventBus.js",
+      "default": "./src/helpers/powerEventBus.js"
+    },
+    "./powerHistogram": {
+      "types": "./types/helpers/powerHistogram.d.ts",
+      "import": "./src/helpers/powerHistogram.js",
+      "default": "./src/helpers/powerHistogram.js"
+    },
+    "./powerLatch": {
+      "types": "./types/helpers/powerLatch.d.ts",
+      "import": "./src/helpers/powerLatch.js",
+      "default": "./src/helpers/powerLatch.js"
+    },
+    "./powerLogger": {
+      "types": "./types/helpers/powerLogger.d.ts",
+      "import": "./src/helpers/powerLogger.js",
+      "default": "./src/helpers/powerLogger.js"
+    },
+    "./powerObserver": {
+      "types": "./types/helpers/powerObserver.d.ts",
+      "import": "./src/helpers/powerObserver.js",
+      "default": "./src/helpers/powerObserver.js"
+    },
+    "./powerPermitGate": {
+      "types": "./types/helpers/powerPermitGate.d.ts",
+      "import": "./src/helpers/powerPermitGate.js",
+      "default": "./src/helpers/powerPermitGate.js"
+    },
+    "./powerPool": {
+      "types": "./types/helpers/powerPool.d.ts",
+      "import": "./src/helpers/powerPool.js",
+      "default": "./src/helpers/powerPool.js"
+    },
+    "./powerQueue": {
+      "types": "./types/helpers/powerQueue.d.ts",
+      "import": "./src/helpers/powerQueue.js",
+      "default": "./src/helpers/powerQueue.js"
+    },
+    "./powerRateLimit": {
+      "types": "./types/helpers/powerRateLimit.d.ts",
+      "import": "./src/helpers/powerRateLimit.js",
+      "default": "./src/helpers/powerRateLimit.js"
+    },
+    "./powerRetry": {
+      "types": "./types/helpers/powerRetry.d.ts",
+      "import": "./src/helpers/powerRetry.js",
+      "default": "./src/helpers/powerRetry.js"
+    },
+    "./powerScheduler": {
+      "types": "./types/helpers/powerScheduler.d.ts",
+      "import": "./src/helpers/powerScheduler.js",
+      "default": "./src/helpers/powerScheduler.js"
+    },
+    "./powerSemaphore": {
+      "types": "./types/helpers/powerSemaphore.d.ts",
+      "import": "./src/helpers/powerSemaphore.js",
+      "default": "./src/helpers/powerSemaphore.js"
+    },
+    "./powerSlidingWindow": {
+      "types": "./types/helpers/powerSlidingWindow.d.ts",
+      "import": "./src/helpers/powerSlidingWindow.js",
+      "default": "./src/helpers/powerSlidingWindow.js"
+    },
+    "./powerSubscriberSet": {
+      "types": "./types/helpers/powerSubscriberSet.d.ts",
+      "import": "./src/helpers/powerSubscriberSet.js",
+      "default": "./src/helpers/powerSubscriberSet.js"
+    },
+    "./powerThrottle": {
+      "types": "./types/helpers/powerThrottle.d.ts",
+      "import": "./src/helpers/powerThrottle.js",
+      "default": "./src/helpers/powerThrottle.js"
+    },
+    "./powerTTLMap": {
+      "types": "./types/helpers/powerTTLMap.d.ts",
+      "import": "./src/helpers/powerTTLMap.js",
+      "default": "./src/helpers/powerTTLMap.js"
+    },
+    "./now": {
+      "types": "./types/utils/now.d.ts",
+      "import": "./src/utils/now.js",
+      "default": "./src/utils/now.js"
+    },
+    "./errors": {
+      "types": "./types/utils/errors.d.ts",
+      "import": "./src/utils/errors.js",
+      "default": "./src/utils/errors.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {

package/src/index.js

@@ -14,6 +14,7 @@ export { PowerSubscriberSet } from './helpers/powerSubscriberSet.js';
 export { PowerSemaphore } from './helpers/powerSemaphore.js';
 export { PowerDefer } from './helpers/powerDefer.js';
 export { PowerTTLMap } from './helpers/powerTTLMap.js';
+export { normalizeError, formatErrorObj } from './utils/errors.js';
 export { nowMs, measureSync, measureAsync } from './utils/now.js';
 export { PowerCircuit } from './helpers/powerCircuit.js';
 export { PowerRetry } from './helpers/powerRetry.js';

package/.eslintrc.cjs

@@ -1,22 +0,0 @@
-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

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

package/CONTRIBUTING.md

@@ -1,178 +0,0 @@
-# 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/assets/1_Caching.md

@@ -1,4 +0,0 @@
-# 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

@@ -1,18 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

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

package/assets/4_Utils.md

@@ -1,10 +0,0 @@
-# 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

@@ -1,10 +0,0 @@
-[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

@@ -1,97 +0,0 @@
-# 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