performance-helpers 1.0.0 → 1.0.1

package/guides/powerSlidingWindow.md

@@ -1,63 +0,0 @@
-# PowerSlidingWindow
-
-A sliding-window rate limiter that allows up to `capacity` events per `windowMs`.
-
-## Constructor
-
-| option | type | default | description |
-|---|---:|---:|---|
-| `capacity` | `number` | `1` | Maximum allowed events in a window.
-| `windowMs` | `number` | `1000` | Window size in milliseconds.
-
-## API
-
-- `tryConsume(n = 1)` — Attempt to consume `n` slots (default `1`) in the current rolling window. Returns `true` when the requested slots are available and the call consumes them; otherwise returns `false`.
-
-- `available()` — Return the current number of available slots in the window. This performs a prune of stale timestamps before reporting.
-
-- `reset()` — Clear internal state and timestamp queue, effectively refilling the window.
-
-## Example
-
-```javascript
-import { PowerSlidingWindow } from '../src/helpers/powerSlidingWindow.js';
-import { PowerPool } from '../src/index.js';
-
-const limiter = new PowerSlidingWindow({ capacity: 5, windowMs: 1000 });
-if (limiter.tryConsume()) {
-  // allowed
-} else {
-  // rate limited
-}
-```
-
-### Example: cooperating with `PowerPool`
-
-Use a `PowerSlidingWindow` to cap how many tasks you dispatch into a `PowerPool` within a rolling window. This example enqueues tasks and keeps a `pending` list for items that must wait until quota becomes available.
-
-```javascript
-const limiter = new PowerSlidingWindow({ capacity: 2, windowMs: 1000 });
-const pool = new PowerPool(MyWorker, { size: 2 });
-
-const pending = [];
-function scheduleTask(payload) {
-  if (limiter.tryConsume()) {
-    pool.postMessage({ task: 'do', payload });
-  } else {
-    pending.push(payload);
-  }
-}
-
-for (let i = 0; i < 10; i++) scheduleTask({ i });
-
-// Periodically attempt to drain pending tasks when the window slides.
-const interval = setInterval(() => {
-  while (pending.length && limiter.tryConsume()) {
-    pool.postMessage({ task: 'do', payload: pending.shift() });
-  }
-  if (!pending.length) clearInterval(interval);
-}, 200);
-
-await pool.drain();
-pool.terminate();
-```

package/guides/powerSubscriberSet.md

@@ -1,48 +0,0 @@
-# PowerSubscriberSet
-
-Shared subscriber registry used by `PowerEventBus` and `PowerObserver`.
-
-`PowerSubscriberSet` manages listener bookkeeping with optional weak references, once-listeners, and max listener limits. It is useful when you need a reusable listener collection that can prune dead weak refs and keep listener delivery simple.
-
-## Constructor
-
-| option | type | default | description |
-|---|---:|---|---|
-| `weak` | `boolean` | `false` | Use `WeakRef`-backed entries when available to allow listeners to be garbage collected. |
-| `maxListeners` | `number` | `0` | Maximum number of live listeners (0 means unlimited). |
-
-## API
-
-- `add(fn)` — Add a listener and return an unsubscribe callback.
-- `addOnce(fn)` — Add a one-time listener that removes itself after invocation.
-- `delete(fn)` — Remove a listener by the original function (or once-wrapper).
-- `clear()` — Remove all listeners.
-- `values()` — Return a safe array copy of currently live listeners.
-- `[Symbol.iterator]()` — Iterate live listeners in insertion order.
-
-## Example
-
-```js
-import { PowerSubscriberSet } from '../src/helpers/powerSubscriberSet.js';
-
-const subs = new PowerSubscriberSet({ weak: true, maxListeners: 10 });
-
-const listener = (value) => {
-  console.log('event value', value);
-};
-
-const unsubscribe = subs.add(listener);
-subs.addOnce(() => console.log('called once'));
-
-for (const fn of subs) {
-  fn('payload');
-}
-
-unsubscribe();
-```
-
-## Notes
-
-- When `weak: true` is enabled, stale weak references are cleaned up automatically during `values()` and iteration.
-- `addOnce()` works with both strong and weak listeners, and removes the listener after it runs.
-- `PowerSubscriberSet` is intended as a low-level building block for event and observer implementations rather than a general-purpose public utility.

package/guides/powerTTLMap.md

@@ -1,58 +0,0 @@
-# PowerTTLMap
-
-A lightweight Map-like with per-key TTL (milliseconds). Keys expire lazily on access and iteration.
-
-## Constructor
-
-| Option | Type | Default | Description |
-|---|---:|---:|---|
-| `defaultTTL` | `number` (ms) | `0` | Default TTL applied when `set(key, value)` is called without a `ttl`. `0` disables expiry. |
-| `onExpire` | `Function` | `undefined` | Optional callback called when an entry expires: `(key, value) => void`. Callback errors are swallowed. |
-
-## API
-
-- `set(key, value, ttl?)` — Set a value for `key`. Optionally provide `ttl` in milliseconds to override the map's `defaultTTL`. Returns the map instance to allow chaining.
-
-- `get(key)` — Retrieve the value for `key` or `undefined` if it is missing or expired. Access will lazily purge expired entries.
-
-- `has(key)` — Boolean indicating whether the key exists and is not expired.
-
-- `delete(key)` — Remove an entry. Returns `true` if an entry was removed.
-
-- `clear()` — Remove all entries immediately.
-
-- `touch(key, ttl?)` — Refresh the TTL of an existing key; returns `true` when the TTL was updated.
-
-- `size` (getter) — Number of non-expired entries; accessing this getter will purge expired entries lazily.
-
-- Iteration helpers: `entries()`, `keys()`, `values()` — Iterators over non-expired entries/keys/values respectively. `forEach(cb, thisArg?)` iterates non-expired entries calling `cb(value, key, map)`. `[Symbol.iterator]()` is an alias for `entries()`.
-
-## Example
-
-```javascript
-import { PowerTTLMap } from '../src/helpers/powerTTLMap.js';
-
-// Example — manage expirable object URLs for served images
-
-const urls = new PowerTTLMap(30_000); // default TTL 30s
-
-// Store an object URL for a generated image and revoke it on expiry
-function storePreview(id, objectUrl) {
-  urls.set(id, objectUrl);
-}
-
-urls.set('img-1', URL.createObjectURL(blob));
-
-// register onExpire to revoke underlying resources when entries age out
-const m = new PowerTTLMap(30_000);
-m.set('img-1', URL.createObjectURL(blob));
-m.onExpire = (key, value) => {
-  try {
-    URL.revokeObjectURL(value);
-  } catch (e) {
-    /* ignore */
-  }
-};
-
-if (m.has('img-1')) console.log('preview ready');
-```

package/guides/powerThrottle.md

@@ -1,152 +0,0 @@
-# PowerThrottle
-
-A small token-bucket rate limiter useful for pacing work (API calls, renders, or cooperating with `PowerPool`).
-
-## Constructor
-
-| option | type | default | description |
-|---|---:|---:|---|
-| `capacity` | `number` | `1` | Maximum tokens the bucket can hold.
-| `tokens` | `number` | `capacity` | Initial token count (clamped to `capacity`).
-| `refillRate` | `number` | `0` | Tokens added per second (fractional accumulation supported).
-| `refillInterval` | `number` | `1000` | Internal bookkeeping interval (ms) used for refill math.
-
-## API
-
-- `tryConsume(n = 1)` — Attempt to consume `n` tokens (default `1`). Returns `true` when tokens were available and consumed; otherwise returns `false`.
-
-- `available()` — Return the current number of available tokens (performs a refill calculation before reporting).
-
-- `addTokens(n)` — Forcefully add up to `n` tokens to the bucket (clamped to `capacity`). Handy for tests or to manually replenish tokens.
-
-- `reset(count?)` — Reset the token count to `count`. When omitted the bucket is refilled to full `capacity`.
-
-- `reserve(n = 1)` — Reserve `n` tokens without committing them permanently. Returns a token object when successful (useful to later `release()` or `rollback()`), or `null` when reservation fails.
-
-- `release(tokenOrN)` — Release a prior reservation token or numeric token count back into the bucket. Accepts either a token returned from `reserve()` or a numeric value.
-
-- `rollback(nOrToken)` — Alias for `release()` for compatibility with undo patterns.
-
-## Example
-
-```javascript
-import { PowerThrottle } from '../src/helpers/powerThrottle.js';
-
-const limiter = new PowerThrottle({ capacity: 5, refillRate: 1 }); // burst 5, 1 token/sec
-const pending = [];
-
-async function sendEvent(payload) {
-  if (!limiter.tryConsume()) {
-    pending.push(payload);
-    return;
-  }
-
-  try {
-    await fetch('https://api.example.com/events', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(payload),
-    });
-  } catch (error) {
-    console.error('send failed', error);
-    pending.push(payload);
-  }
-}
-
-const drainInterval = setInterval(async () => {
-  while (pending.length && limiter.tryConsume()) {
-    const payload = pending.shift();
-    await sendEvent(payload);
-  }
-  if (!pending.length) {
-    clearInterval(drainInterval);
-  }
-}, 250);
-```
-
-### Example: cooperating with `PowerPool`
-
-Use a `PowerThrottle` to pace messages enqueued to a `PowerPool` so the pool only processes at most N tasks per second. This is useful when downstream rate limits or external APIs require pacing.
-
-```javascript
-// limiter: 3 tokens/sec, burst capacity 3
-const limiter = new PowerThrottle({ capacity: 3, refillRate: 3 });
-const pool = new PowerPool(MyWorker, { size: 2 });
-const pending = [];
-
-function scheduleTask(payload) {
-  // tryConsume returns true when a token is available
-  if (!limiter.tryConsume()) {
-    // requeue for later processing
-    pending.push(payload);
-    return;
-  }
-  // dispatch to the pool; optionally target a worker
-  pool.postMessage({ task: 'do', payload });
-}
-
-// enqueue tasks from some source
-for (let i = 0; i < 10; i++) scheduleTask({ i });
-
-// Periodically attempt to drain pending tasks when tokens become available.
-const drainInterval = setInterval(() => {
-  while (pending.length && limiter.tryConsume()) {
-    const p = pending.shift();
-    pool.postMessage({ task: 'do', payload: p });
-  }
-  // stop when no pending tasks
-  if (!pending.length) clearInterval(drainInterval);
-}, 200);
-
-// drain when done
-await pool.drain();
-pool.terminate();
-```
-
-### Reservation example
-
-You can reserve tokens when you need to prepare work that should only consume a token once the work is actually dispatched. This is useful when coordinating with composed limiters that expect an atomic reservation step.
-
-```javascript
-const limiter = new PowerThrottle({ capacity: 2, tokens: 2, refillRate: 0 });
-const token = limiter.reserve(1);
-if (token) {
-  // do preparation work (serialize payload, open resources)
-  // when ready to dispatch:
-  // if something goes wrong before dispatch, release the reservation
-  limiter.release(token);
-}
-```
-
-### Real-world: reserve before expensive serialization
-
-Use `reserve()` when you want to claim capacity before performing expensive
-preparation work (serialization, file reads). If preparation fails, release the
-reservation so the token is not consumed.
-
-```javascript
-const limiter = new PowerThrottle({ capacity: 3, refillRate: 3 });
-
-async function sendLargePayload(payload) {
-  const token = limiter.reserve(1);
-  if (!token) {
-    // no capacity: fallback (persist, retry later)
-    await persistForRetry(payload);
-    return false;
-  }
-
-  try {
-    // expensive synchronous or async serialization
-    const body = await heavySerialize(payload);
-    // dispatch network call (does not consume extra tokens)
-    await fetch('/api/upload', { method: 'POST', body });
-    return true;
-  } catch (err) {
-    // something went wrong during preparation or send
-    throw err;
-  } finally {
-    // always return the reserved token
-    limiter.release(token);
-  }
-}
-```

package/index.html

@@ -1,57 +0,0 @@
-<!doctype html>
-<html lang="en">
-
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width,initial-scale=1">
-  <title>performance-helpers</title>
-    <meta name="description" content="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 small worker pool wrapper, a tiny runtime debug logger, and much more.">
-
-  <meta property="og:title" content="performance-helpers">
-  <meta property="og:description" content="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 small worker pool wrapper, a tiny runtime debug logger, and much more.">
-  <meta property="og:type" content="website">
-  <meta property="og:image" content="https://abelvm.github.io/nimbiCMS/assets/logo.png">
-
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="performance-helpers">
-  <meta name="twitter:description" content="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 small worker pool wrapper, a tiny runtime debug logger, and much more.">
-  <meta name="twitter:image" content="https://abelvm.github.io/nimbiCMS/assets/logo.png">
-
-  <link rel="icon" href="./assets/logo.png">
-  <style>
-    html,
-    body,
-    #app {
-      height: 100vh;
-      max-height: 100vh;
-      margin: 0;
-      display: block;
-    }
-  </style>
-    <link rel="preload" href="https://unpkg.com/nimbi-cms@1.0.8/dist/nimbi-cms.css" as="style"
-        onload="this.rel='stylesheet'">
-    <noscript>
-        <link rel="stylesheet" href="https://unpkg.com/nimbi-cms@1.0.8/dist/nimbi-cms.css">
-    </noscript>
-    <script src="https://unpkg.com/nimbi-cms@1.0.8/dist/nimbi-cms.js"></script>
-</head>
-
-<body>
-  <div id="app"></div>
-  <script defer>
-    window.addEventListener('DOMContentLoaded', function () {
-      nimbiCMS.initCMS({
-          el: '#app',
-          contentPath: './',
-          indexDepth: 3,
-          defaultStyle: 'system',
-          homePage: 'README.md',
-          notFoundPage: 'assets/404.md',
-          navigationPage: 'assets/navigation.md',
-          debugLevel: 0,
-        });
-    });
-  </script>
-</body>
-
-</html>