performance-helpers 1.0.0 → 1.0.1

package/guides/powerBuffer.md

@@ -1,86 +0,0 @@
-# Buffer helpers
-
-Lightweight helpers for encoding/decoding JSON to/from binary (Uint8Array / ArrayBuffer / Node Buffer).
-
-`powerBuffer` provides tiny, allocation-friendly helpers optimized for passing JSON payloads through transferable binary buffers (for example, when posting messages to Workers). It prefers zero-copy views for ArrayBuffer/TypedArray inputs and falls back to `TextEncoder`/`TextDecoder` (or Node `Buffer`) when available.
-
-## o2u8(obj)
-
-Encode a value to a `Uint8Array` (UTF-8 JSON).
-
-- `obj` — Any value to encode. If the value is already a `Uint8Array`/TypedArray/ArrayBuffer it will be returned or converted to a view.
-
-Returns: `Uint8Array` — UTF-8 encoded bytes. Throws if no encoder is available in the environment.
-
-Example
-```javascript
-import { o2u8, u82o } from '../src/helpers/powerBuffer.js';
-
-// encode a JSON payload to transferable Uint8Array and post to a worker
-const payload = { id: 42, name: 'big-image', meta: { size: 1024 * 1024 } };
-const bytes = o2u8(payload);
-// `bytes.buffer` can be transferred to a Worker to avoid structured-clone copies
-worker.postMessage(bytes, [bytes.buffer]);
-```
-
-## u82o(buf)
-
-Decode a binary buffer (Uint8Array/ArrayBuffer/Buffer) containing JSON UTF-8 to a JS value.
-
-- `buf` — The binary input to decode. Accepted types: `Uint8Array`, `ArrayBuffer`, TypedArray, or Node `Buffer`.
-
-Returns: parsed JS value. Throws `TypeError` for unsupported input types or malformed UTF-8 JSON.
-
-Example — worker receiver
-
-```javascript
-import { u82o } from '../src/helpers/powerBuffer.js';
-
-self.onmessage = (e) => {
-    // decode transferable Uint8Array back to JS value
-    const obj = u82o(e.data);
-    // process obj
-};
-```
-
-## o2b(obj)
-
-Encode to an `ArrayBuffer` (legacy API). Returns an owning ArrayBuffer (slice if necessary).
-
-Parameters: same as `o2u8`.
-
-Returns: `ArrayBuffer`.
-
-## b2o(buf)
-
-Legacy wrapper around `u82o` for ArrayBuffer/TypedArray/Buffer.
-
-## Recommendations
-
-- Use `o2u8`/`u82o` when sending/receiving structured JSON through `postMessage` to make use of transferables and reduce copy overhead.
-
-```javascript
-// worker.js
-self.onmessage(e => {
-    const json_input = u82o(e.data);
-    ...
-    const output = o2u8(json_output);
-    self.postMessage(output, [output.buffer])
-})
-```
-
-```javascript
-// worker.js
-self.onmessage = (e) => {
-    const jsonInput = u82o(e.data);
-    const result = process(jsonInput);
-    const out = o2u8(result);
-    self.postMessage(out, [out.buffer]);
-};
-
-// main thread
-worker.onmessage = (e) => {
-    const jsonOut = u82o(e.data);
-    handleResult(jsonOut);
-};
-```

package/guides/powerBulkhead.md

@@ -1,61 +0,0 @@
-# PowerBulkhead
-
-A partitioned executor that isolates noisy workloads into separate concurrency lanes.
-
-Use `PowerBulkhead` when you need to protect critical work from a noisy producer or a hot key. Tasks routed to one partition will queue and run independently from tasks in other partitions.
-
-## Constructor
-
-| option | type | default | description |
-|---|---:|---:|---|
-| `partitions` | `number` | `4` | Number of isolated execution partitions. Work in different partitions does not compete for the same concurrency slots.
-| `maxConcurrency` | `number` | `1` | Maximum concurrent tasks allowed per partition.
-| `queueCapacity` | `number` | `100` | Maximum number of tasks that may wait in the queue across all partitions.
-| `partitioner` | `Function` | `null` | Optional function `(key) => partitionIndex` used to route a task based on a custom key.
-
-## API
-
-- `run(task, options)` — Enqueue a task for execution. When the chosen partition has available concurrency, the task runs immediately; otherwise it waits in that partition's queue.
-- `tryRun(task, options)` — Attempt immediate execution and return a `Promise` if the partition has capacity, or `null` if it would have to queue.
-- `drain()` — Wait until all active and queued tasks complete.
-- `partitions` — Number of configured partitions.
-- `maxConcurrency` — Maximum concurrent tasks per partition.
-- `queueCapacity` — Maximum queue size across all partitions.
-- `active` — Number of tasks currently running.
-- `pending` — Number of tasks currently queued.
-- `isFull` — `true` when the helper has reached its global queue capacity.
-
-## Example
-
-```js
-import { PowerBulkhead } from '../src/helpers/powerBulkhead.js';
-
-const bulkhead = new PowerBulkhead({
-  partitions: 3,
-  maxConcurrency: 2,
-  queueCapacity: 20,
-});
-
-async function submitWork(item, partitionKey) {
-  return bulkhead.run(() => {
-    // any work can be async
-    return fetch(`/api/resource/${item.id}`).then((res) => res.json());
-  }, { partitionKey });
-}
-
-const results = await Promise.all([
-  submitWork({ id: 1 }, 'critical'),
-  submitWork({ id: 2 }, 'critical'),
-  submitWork({ id: 3 }, 'background'),
-]);
-
-await bulkhead.drain();
-console.log('all work finished');
-```
-
-## Notes
-
-- `PowerBulkhead` uses an internal `PowerQueue` for each partition to keep queued tasks O(1) on enqueue/dequeue.
-- Tasks with the same `partitionKey` are routed to the same partition by default, so noisy or bursty keys can be isolated from healthier lanes.
-- If `queueCapacity` is reached, `run()` rejects immediately with `PowerBulkhead queue is full`.
-- Because partitions do not steal capacity from each other, a hot partition cannot block progress in other partitions.

package/guides/powerCache.md

@@ -1,269 +0,0 @@
-# LRU cache with TTL and Memoizer
-
-An in-memory, memory-efficient LRU cache with TTL, weighted eviction and an optional reusable node pool. Includes a small `PowerMemoizer` wrapper built on top of `PowerCache` for memoizing synchronous or Promise-returning functions.
-
-## PowerCache
-
-| option | type | default | description |
-|---|---:|---:|---|
-| `maxEntries` | `number` | `Infinity` | Maximum number of entries to retain. Older entries are evicted when exceeded. |
-| `maxWeight` | `number` | `Infinity` | Maximum total weight across all entries. Eviction occurs when exceeded. |
-| `weightFn` | `function(value):number` | `() => 1` | Compute the weight for a value when explicit `weight` not provided to `set`. |
-| `defaultTTL` | `number` | `60000` | Default time-to-live (ms) for entries. Use `null`/`Infinity` to disable expiration. |
-| `maxPoolSize` | `number` | `1000` | Maximum size of the internal node pool used to reuse nodes and reduce GC. |
-| `rejectOversized` | `boolean` | `false` | When `true`, inserting an item with weight > `maxWeight` will be rejected. |
-| `onEvict` | `function(key,value,reason)` | `null` | Callback invoked for evicted/deleted/rejected entries. `reason` is `'evicted'|'deleted'|'rejected-oversized'`. |
-| `onExpire` | `function(key,value)` | `null` | Callback invoked when an entry expires due to TTL. |
-| `initialPoolSize` | `number` | `0` | Prefill the internal node pool to reduce early allocations. |
-| `maxCleanupPerTick` | `number` | `100` | Max nodes scanned per cleanup tick for `startCleanup()`.
-| `eagerCleanupOnRead` | `boolean` | `false` | If `true`, `peek()` and `has()` will remove expired nodes when observed (opt-in behavior). |
-
-### API
-
-- `set(key, value, { ttl, weight })` — Add or update an entry. Accepts an optional `{ ttl, weight }` options object; returns `this` on success or `false` when insertion is rejected due to `rejectOversized`.
-
-- `get(key)` — Retrieve the stored value and mark the entry as recently used. Returns the value or `undefined` when missing or expired.
-
-- `peek(key)` — Read the value without affecting recency; returns `value | undefined`. When the cache is constructed with `eagerCleanupOnRead: true`, `peek()` will remove expired entries it encounters.
-
-- `has(key, { ignoreExpiry = false })` — Check whether a key exists and is not expired. When `ignoreExpiry` is true expired entries are considered present. When `eagerCleanupOnRead: true` the call will remove expired entries seen during the check.
-
-- `hasEqual(key, value, { ignoreExpiry = false, seen })` — Deep-equality compare the stored value against `value` using optimized fast paths for primitives, typed arrays, Maps/Sets, and cyclic-safe comparison. Respects the `ignoreExpiry` option. When performing many comparisons, pass a reusable `WeakMap` as `seen` or use `hasEqualWithSeen(key, value, seen)` to avoid per-call WeakMap allocations.
-
-- `delete(key)` — Remove an entry. Returns `true` when a key was removed.
-
-- `clear()` — Remove all entries and return nodes to the internal pool (no return value).
-
-- `cleanupExpiredUpTo(maxScan = Infinity)` — Scan up to `maxScan` nodes for expired entries and remove them; returns the number of nodes scanned in this pass.
-
-- `startCleanup(intervalOrOptions)` — Start a periodic, non-blocking cleanup loop. Accepts either a numeric interval (ms) or `{ interval, maxCleanupPerTick }` options.
-
-- `stopCleanup()` — Stop the periodic cleanup loop and clear internal timers.
-
-- `getOrSet(key, factory, { ttl, weight, staleWhileRevalidate })` — Atomically read-or-compute a value. If `factory` is a function its result (or resolved Promise) is stored and returned. When `staleWhileRevalidate` is enabled, an expired value can be returned immediately while refresh happens in the background.
-
-- `getOrSetAsync(key, asyncFactory, { ttl, weight, staleWhileRevalidate })` — Async read-or-compute with inflight deduplication: concurrent callers share the same in-flight Promise and the resolved value is cached when settled. With `staleWhileRevalidate: true`, an expired cached value is returned immediately and the async factory refreshes the cache behind the scenes.
-
-  ```javascript
-  const cache = new PowerCache({ defaultTTL: 1000 });
-  cache.set('user:1', { name: 'Alice' }, { ttl: 1000 });
-
-  // After the entry expires, staleWhileRevalidate returns the old value immediately
-  // and refreshes the cache in the background.
-  const stale = cache.getOrSet('user:1', () => fetchUser(1), {
-    staleWhileRevalidate: true,
-  });
-  ```
-
-- `resize({ maxEntries, maxWeight })` — Change cache caps and trigger eviction as needed.
-
-- `entries(order = 'MRU')` — Iterator yielding `[key, value]` pairs in MRU or LRU order. Useful for debugging or bulk exports.
-
-- `hitRate` (getter) — Convenience fraction `hits / (hits + misses)` (0 when no samples).
-
-- `setMany(entries, { ttl, weight })` — Bulk-insert multiple `[key, value]` pairs; performs a single eviction pass after insertion for efficiency.
-
-- `getMany(keys, { ignoreExpiry = false })` — Bulk get; returns a `Map` of found keys -> values.
-
-- `touch(key, ttl?)` — Refresh recency and optionally TTL for an existing key; returns `true` when the key existed and was not expired.
-
-- `stats()` — Return runtime statistics object: `{ size, weight, hits, misses, evictions, rejected, poolSize, expirations }`.
-
-- `hitRate` (getter) — Convenience fraction `hits / (hits + misses)` (0 when no samples).
-
-#### Iteration
-
-`PowerCache` implements the iterator protocol. Iterating the cache with `for...of` yields `[key, value]` pairs in MRU order (most-recently-used first):
-
-```javascript
-const c = new PowerCache();
-c.set('a', 1);
-c.set('b', 2);
-for (const [k, v] of c) {
-  console.log(k, v); // 'b' then 'a'
-}
-console.log('hit rate', c.hitRate);
-```
-
-### Opt-in: eager cleanup on read
-
-If you prefer reads to automatically remove expired entries when they are observed, construct the cache with `eagerCleanupOnRead: true`. This makes `peek()` and `has()` remove expired nodes seen during the check instead of leaving them until the periodic cleanup.
-
-```javascript
-import { PowerCache } from '../src/helpers/powerCache.js';
-
-const cache = new PowerCache({ defaultTTL: 1, eagerCleanupOnRead: true });
-cache.set('a', 1, { ttl: 1 });
-// wait for expiry
-await new Promise((r) => setTimeout(r, 5));
-console.log(cache.peek('a')); // undefined; the expired entry is removed
-console.log(cache.has('a', { ignoreExpiry: true })); // false (entry was removed)
-```
-
-Note: The library currently defaults to non-mutating read behavior (expired entries remain until cleanup). Changing the default to `eagerCleanupOnRead: true` would be a breaking change and should be done as part of a major-version bump.
-
-If you need LRU order, use `Array.from(c.entries('LRU'))` or the `entries('LRU')` iterator directly.
-
-### Example — caching API responses with async factory
-
-```javascript
-import { PowerCache } from '../src/helpers/powerCache.js';
-
-// Cache user profiles for 30s to avoid repeated HTTP calls
-const cache = new PowerCache({ maxEntries: 5000, defaultTTL: 30_000 });
-
-// Network-only fetch helper (separate from cache logic for clarity)
-async function fetchUserProfileFromNetwork(id) {
-  const res = await fetch(`https://api.example.com/users/${id}`);
-  if (!res.ok) throw new Error(`HTTP ${res.status}`);
-  return res.json();
-}
-
-// High-level cached accessor using getOrSetAsync (inflight dedupe + caching)
-async function fetchUserProfile(id) {
-  const key = `user:${id}`;
-  return cache.getOrSetAsync(
-    key,
-    () => fetchUserProfileFromNetwork(id),
-    { ttl: 30_000 }
-  );
-}
-
-// Concurrent callers for the same key share the inflight request (deduped)
-const [p1, p2] = await Promise.all([fetchUserProfile('alice'), fetchUserProfile('alice')]);
-
-// Stale-while-revalidate: return expired value immediately and refresh in background
-const profile = await cache.getOrSetAsync('user:alice', () => fetchUserProfileFromNetwork('alice'), {
-  staleWhileRevalidate: true,
-  ttl: 30_000,
-});
-console.log('profile', profile);
-
-// The cache will not store rejected promises; handle network errors explicitly
-try {
-  const bob = await fetchUserProfile('bob');
-  console.log('bob', bob.name);
-} catch (err) {
-  console.error('Failed to load profile', err);
-}
-```
-
-
-## PowerMemoizer
-
-Small memoization helper that uses a `PowerCache` instance internally. It deduplicates concurrent Promise-returning calls and does not cache rejected Promises.
-
-The constructor always returns a `PowerMemoizer` instance. Use the instance method `memoize(fn)` to create a callable memoized wrapper for a function. The returned memoized function has helper methods attached (`get`, `has`, `delete`, `clear`, `stats`, `cache`).
-
-#### Memoizer constructor params
-
-| param | type | default | description |
-|---|---:|---:|---|
-| `fn` | `Function?` | — | Optional function to register with the instance. The constructor will not return a bare function; call `pm.memoize(fn)` to obtain a memoized wrapper (the instance will create a convenience wrapper accessible via `pm.run()` when `fn` is supplied). |
-| `options.keyResolver` | `function(...args):string` | `(...args)=>JSON.stringify(args)` | Function mapping call args to a stable cache key. |
-| `options.cacheOptions` | `Object` | `{}` | Options forwarded to the underlying `PowerCache` constructor (e.g. `defaultTTL`, `maxEntries`, `weightFn`). |
-| `options.ttl` | `number?` | `undefined` | Default TTL (ms) used when caching results for the `fn` passed to the constructor. |
-| `options.weight` | `number?` | `undefined` | Default weight used when caching results for the `fn` passed to the constructor. |
-
-You can create an empty `PowerMemoizer` instance and memoize multiple functions that share the same underlying cache by calling `memoize(fn)`:
-
-```javascript
-// share a single cache across multiple functions
-const pm = new PowerMemoizer()
-const memoA = pm.memoize(fnA)
-const memoB = pm.memoize(fnB, { ttl: 5000 })
-```
-
-### Memoizer API
-
-- `get(...args)` — Retrieve the cached value for the resolved key, or `undefined` when missing.
-
-- `has(...args)` — Check presence in the memoizer's underlying cache.
-
-- `delete(...args)` — Remove a cached entry and any tracked inflight Promise; returns `true` when removed.
-
-- `clear()` — Clear the memoizer's cache and any inflight markers.
-
-- `memoize(fn)` — Wrap and return a memoized version of `fn` using this instance's cache. The returned function has helper methods attached (`get`, `has`, `delete`, `clear`, `stats`, `cache`).
-
-- `run(...args)` — Convenience alias that invokes the memoized wrapper created from the constructor-supplied function. If the `PowerMemoizer` was constructed without a function, `run()` will throw a `TypeError` instructing callers to use `memoize(fn)`.
-
-- `memoize(fn)` — Wrap and return a memoized version of `fn` using this instance's cache. The returned function has helper methods attached (`get`, `has`, `delete`, `clear`, `stats`, `cache`).
-
-### Example
-
-```javascript
-const fetchUserFn = async (id) => fetch(`/users/${id}`).then(r => r.json())
-// when constructing without an immediate function you must pass the
-// options as the *second* argument (first arg is the optional `fn`):
-const pm = new PowerMemoizer(undefined, { cacheOptions: { defaultTTL: 10_000 } })
-const memo = pm.memoize(fetchUserFn)
-// call the memoized function directly
-await memo(1)
-```
-
-### Fast key resolver
-
-For hot paths where most calls use simple scalar arguments (ids, numbers, short strings),
-use the built-in `simpleArgsKey` helper as a faster alternative to `JSON.stringify`:
-
-```javascript
-import { PowerMemoizer, simpleArgsKey } from '../src/helpers/powerCache.js'
-
-const fetchUserFn = async (id) => fetch(`/users/${id}`).then(r => r.json())
-// use the fast resolver for simple scalar args
-// when a function is supplied to the constructor the instance provides a
-// convenience `run()` alias that invokes the memoized wrapper:
-const pm = new PowerMemoizer(fetchUserFn, { keyResolver: simpleArgsKey })
-await pm.run(1)
-```
-
-`simpleArgsKey` performs a cheap, deterministic encoding for primitive args
-and falls back to `JSON.stringify` only when it encounters non-scalar values.
-
-## PowerTimedCache
-
-`PowerTimedCache` is a small convenience wrapper around `PowerCache` for the common
-pure-TTL use case. It constructs a `PowerCache` with the provided `ttl` used as
-the cache `defaultTTL` and automatically starts the periodic cleanup loop so
-callers don't have to wire `startCleanup()` manually.
-
-Use it when you only need simple time-based expiration and want a compact
-one-line construction pattern.
-
-Constructor signature
-
-```javascript
-new PowerTimedCache(ttl, { maxEntries, interval, maxCleanupPerTick, cacheOptions })
-```
-
-| option | type | default | description |
-|---|---:|---:|---|
-| `ttl` | `number` | — | Required. Default TTL (ms) for entries stored in the cache. |
-| `maxEntries` | `number` | `undefined` | Optional: forwarded to the underlying `PowerCache` constructor. |
-| `interval` | `number` | `undefined` | Optional cleanup interval (ms). When provided it is forwarded to `startCleanup()`; otherwise `startCleanup()` uses its own computed default. |
-| `maxCleanupPerTick` | `number` | `undefined` | Optional: when provided forwarded to `startCleanup()` to control nodes scanned per tick. |
-| `cacheOptions` | `Object` | `{}` | Additional options forwarded to `PowerCache` (e.g. `weightFn`, `maxWeight`, `rejectOversized`). |
-
-### Example
-
-```javascript
-import { PowerTimedCache } from '../src/helpers/powerCache.js';
-
-// entries expire after 60s; cleanup runs on the default cadence
-const tc = new PowerTimedCache(60_000, { maxEntries: 1000 });
-
-tc.set('k', 1);
-console.log(tc.get('k'));
-```
-
-### Notes
-
-- `PowerTimedCache` delegates all public `PowerCache` instance methods (for example `get`, `set`, `delete`, `clear`, `entries`, `stats`) to the underlying cache. Use `tc.cache` to access the raw `PowerCache` instance when you need advanced operations.
-- The wrapper exposes synchronous and async disposal hooks (`[Symbol.dispose]` and `[Symbol.asyncDispose]`) which delegate to the underlying cache
-
-## Recommendations
-
-- Use `PowerCache` for workloads with bounded memory or to avoid repeated expensive computations.
-- Provide a `weightFn` when storing large binary-like values to enable weight-based eviction.
-- Use `PowerMemoizer` for short-lived Promise caching where concurrent deduplication is desirable. Be careful with `keyResolver` for objects — prefer stable string keys or canonical serializers.

package/guides/powerChunking.md

@@ -1,130 +0,0 @@
-# PowerChunker
-
-A small helper that chunks an iterable and processes items via a `PowerPool`.
-
-Use `PowerChunker` when you have a large iterable to process and want to
-parallelize the work across a managed worker pool without writing the pool
-boilerplate yourself.
-
-## Constructor
-
-| option | type | default | description |
-|---|---:|---:|---|
-| `poolOptions` | `Object` | `{}` | Options forwarded to the `PowerPool` constructor (e.g. `size`, `minSize`, `maxSize`, `idleTimeout`). |
-| `postOptions` | `Object` | `{}` | Options forwarded to `PowerPool.postMessageBatch` (for example `awaitResponse`, `workerId`, `timeout`). |
-| `chunkSize` | `number` | `heuristic` | Explicit chunk size. When omitted the helper computes a conservative chunk size derived from `iterable.length` and pool size (aiming for roughly `poolSize * 4` in-flight chunks). |
-| `fnComplexity` | `'light'\|'medium'\|'heavy'` | `auto` | Hint about per-item work complexity that biases the computed `chunkSize`. When omitted the helper will attempt to analyze `fn`'s source to infer complexity (`'light'\|'medium'\|'heavy'`) and use that to bias chunking; falls back to `'medium'` on failure. |
-
-## API
-
-- Returns a `PowerPool` instance managing chunked work. The helper forwards `message` events from per-chunk processing to `pool.onmessage`.
-
-- `onmessage` / `addEventListener('message', cb)` — Receive per-chunk result events. Each event `data` contains `{ processed, results, correlationId? }`.
-
-- `postMessageBatch(items, options)` — The helper uses the underlying pool's `postMessageBatch` for array-mode enqueues; when using streaming mode the helper internally calls `postMessage({ chunk })` for each chunk. The return value mirrors `PowerPool.postMessageBatch` (array of booleans or Promises when awaiting responses).
-
-- `drain()` — Await until all queued and inflight chunk tasks have completed. (Inherited from returned `PowerPool` instance.)
-
-- `terminate()` / `shutdown()` — Terminate or shutdown the underlying pool; see `PowerPool` semantics for differences.
-
-
-## Example
-
-```javascript
-import { PowerChunker } from '../src/helpers/powerChunking.js';
-import { PowerLogger } from '../src/helpers/powerLogger.js';
-
-const data = Array.from({ length: 1000 }, (_, i) => ({ id: i, payload: `item-${i}` }));
-function process(item) {
-  // simulate per-item CPU/IO work; in production this would be heavy transform
-  return { id: item.id, processed: true };
-}
-
-// Create a chunker which internally creates a `PowerPool` sized for concurrency
-const pool = new PowerChunker(data, process, { poolOptions: { size: 4 } });
-
-const logger = new PowerLogger(1);
-const results = [];
-const errors = [];
-
-pool.onmessage = (e) => {
-  const chunk = e && e.data;
-  if (!chunk) return;
-  const items = Array.isArray(chunk.results) ? chunk.results : [];
-  for (const r of items) {
-    if (r && r.error) {
-      errors.push(r);
-      logger.error('chunk item error', r);
-    } else {
-      results.push(r);
-    }
-  }
-};
-
-// Wait until the pool is idle (all queued and inflight tasks finished)
-await pool.drain();
-// Pretty-print errors using the per-module logger (uncomment the import above in real code)
-// (example: log chunk processing errors if needed)
-console.log('Results:', results.length, 'Errors:', errors.length);
-pool.terminate();
-```
-
-## Real-world Example — bulk CSV processing
-
-```javascript
-import { PowerChunker } from '../src/helpers/powerChunking.js';
-
-// `readCsvRows` is a user helper that yields/returns many parsed rows.
-const rows = await readCsvRows('large-export.csv');
-
-// transform each row into the shape your backend expects
-async function transformRow(row) {
-  // validate/normalize fields, enrich, etc.
-  return { id: row.id, ts: Date.parse(row.time), payload: row.data };
-}
-
-// Create a chunker tuned for bulk DB writes. Use chunkSize to control
-// batch sizes sent to the worker-like handlers; chunker will post each
-// chunk as a single task to an internal pool which processes items and
-// emits a per-chunk `message` with `results`.
-const pool = new PowerChunker(rows, transformRow, {
-  poolOptions: { size: 4 },
-  chunkSize: 500,
-  postOptions: { awaitResponse: false }
-});
-
-const errors = [];
-pool.onmessage = (e) => {
-  const data = e && e.data;
-  if (!data || !Array.isArray(data.results)) return;
-  for (const r of data.results) {
-    if (r && r.error) errors.push(r);
-    else {
-      // collect or stream to a DB bulk-inserter here
-    }
-  }
-};
-
-// Wait until all work finishes, then perform any final bulk write or cleanup
-await pool.drain();
-if (errors.length) console.error('Some rows failed', errors.length);
-pool.terminate();
-```
-
-## Notes
-
-- This helper creates inline worker-like instances that execute `fn` in a
-  microtask (via `setTimeout`) so it works in environments without real Web
-  Workers. For real multi-threaded CPU-bound work use a real worker source and
-  a `PowerPool` directly.
-- The helper returns what `PowerPool.postMessageBatch` returns: an array of
-  per-chunk results (`true|false`) or Promises when `awaitResponse` is used.
-- When `fnComplexity` is not provided the helper will examine the source of `fn` and attempt
- - When `fnComplexity` is not provided the helper uses a lightweight heuristic to infer complexity:
-   it treats `AsyncFunction` or `GeneratorFunction` as `heavy` and uses the function's declared
-   arity (number of formal parameters) as a signal; otherwise it defaults to `medium`.
-   This approach avoids fragile source-parsing while providing a sensible bias for chunk sizing.
-- Each `message` event `data` includes:
-  - `processed`: number of items processed in the chunk
-  - `results`: array of per-item return values (or error objects `{ error: true, code, message, stack }`)
-  - `correlationId` when worker-level correlation was provided

package/guides/powerCircuit.md

@@ -1,84 +0,0 @@
-# PowerCircuit
-
-Simple circuit breaker primitive to protect external services from cascading failures.
-
-## Constructor
-
-`new PowerCircuit(options?)`
-
-## Options
-
-| Option | Type | Default | Description |
-|---|---:|---:|---|
-| `threshold` | `number` | `5` | Consecutive failure threshold to open the circuit. |
-| `timeout` | `number` (ms) | `30000` | Milliseconds to keep the circuit open before allowing a trial (`half-open`) call. |
-
-## API
-
-- `call(fn)` — Execute the provided function `fn` under circuit protection. Returns a `Promise` resolved with `fn`'s result or rejected if `fn` throws. When the circuit is open `call` will reject immediately with a circuit-open error.
-
-- `state` (getter) — One of `'closed' | 'open' | 'half-open'`, indicating the current circuit state.
-
-- `failures` (getter) — Number of consecutive failures that have been observed; this counter resets when a call succeeds.
-
-- `lastError` — The last error observed from a failed protected call (useful for diagnostics and logging).
-
-- `reset()` — Force the circuit into the `closed` state and clear internal counters/history.
-
-- `onStateChange` (constructor option) — Optional callback `(state, reason?)` invoked whenever the circuit transitions between states. The callback is called with the new state (`'closed'|'open'|'half-open'`) and an optional reason string such as `'thresholdExceeded'`, `'trialFailed'`, `'timeoutElapsed'`, `'success'`, or `'reset'`. User callback errors are swallowed by the circuit to avoid interfering with control flow.
-
-- `eventBus` (constructor option) — Optional instance of `PowerEventBus` to receive `stateChange` events. When provided the circuit will emit `{ state, reason }` objects on the bus under the `'stateChange'` event name.
-
-## Example
-
-```javascript
-import { PowerCircuit } from '../src/helpers/powerCircuit.js';
-
-// Real-world example: protect an HTTP fetch to a flaky external API.
-// Provide observability hooks: callback and an optional event bus.
-import { PowerEventBus } from '../src/helpers/powerEventBus.js';
-const bus = new PowerEventBus();
-
-const cb = new PowerCircuit({
-  threshold: 3,
-  timeout: 5_000,
-  onStateChange: (state, reason) => console.log('circuit state ->', state, reason),
-  eventBus: bus,
-});
-
-async function fetchWithCircuit(url, opts) {
-  return cb.call(async () => {
-    const res = await fetch(url, opts);
-    if (!res.ok) throw Object.assign(new Error('HTTP'), { status: res.status });
-    return res.json();
-  });
-}
-
-// Usage: this attempts the request; after 3 consecutive failures the circuit
-// opens and subsequent calls will immediately reject with `{ code: 'ECIRCUITOPEN' }`.
-async function doWork() {
-  try {
-    const data = await fetchWithCircuit('https://api.example.com/data');
-    console.log('got', data);
-  } catch (err) {
-    if (err && err.code === 'ECIRCUITOPEN') {
-      // fallback behavior while the circuit is open (serve cached data)
-      console.warn('service unavailable — serving stale cache');
-      return cache.get('latest') || { source: 'stale' };
-    }
-    console.error('request failed', err);
-    throw err;
-  }
-}
-```
-
-## Observability example
-
-You can subscribe to the `PowerEventBus` to centralize state-change handling across multiple circuits or components:
-
-```javascript
-bus.on('stateChange', ({ state, reason }) => {
-  // record metrics, raise alerts, or update UI
-  console.info('circuit-change', state, reason);
-});
-```