dankgrinder 4.9.9 → 5.0.1

package/lib/structures.js

@@ -0,0 +1,725 @@
+/**
+ * Advanced data structures used across the entire codebase.
+ *
+ * Contents:
+ *   BloomFilter     – O(1) probabilistic set membership (cooldown pre-check)
+ *   LRUCache        – O(1) get/set bounded cache (doubly-linked list + HashMap)
+ *   RingBuffer      – O(1) fixed-size FIFO, zero GC pressure (log storage)
+ *   Trie            – O(k) prefix search tree (item name matching)
+ *   AhoCorasick     – O(n+m+z) multi-pattern string matcher (item/pattern detection)
+ *   TokenBucket     – O(1) rate limiter (anti-rate-limit)
+ *   EMA             – O(1) exponential moving average (earnings/win-rate tracking)
+ *   SlidingWindow   – O(1) amortized time-based event counter (commands/sec)
+ *   MinHeap         – O(log n) priority queue (command scheduling)
+ *   VoseAlias       – O(1) weighted random sampling (safe button selection)
+ *   StringPool      – O(1) string interning / deduplication (memory savings)
+ *   BitSet          – O(1) compact boolean array (flag management)
+ *   ObjectPool      – O(1) reusable object allocator (reduce GC pressure)
+ */
+
+'use strict';
+
+// ═══════════════════════════════════════════════════════════════
+// BloomFilter – probabilistic set membership, O(1) insert/query
+// False positives possible, false negatives impossible.
+// Used for fast cooldown pre-check before hitting Redis.
+// ═══════════════════════════════════════════════════════════════
+class BloomFilter {
+  constructor(size = 1024, hashCount = 3) {
+    this.size = size;
+    this.hashCount = hashCount;
+    this.bits = new Uint32Array(Math.ceil(size / 32));
+  }
+
+  _hash(str, seed) {
+    let h = seed;
+    for (let i = 0; i < str.length; i++) {
+      h = (h * 31 + str.charCodeAt(i)) | 0;
+    }
+    return ((h & 0x7fffffff) % this.size) >>> 0;
+  }
+
+  add(key) {
+    for (let i = 0; i < this.hashCount; i++) {
+      const idx = this._hash(key, i * 0x9e3779b9);
+      this.bits[idx >>> 5] |= (1 << (idx & 31));
+    }
+  }
+
+  has(key) {
+    for (let i = 0; i < this.hashCount; i++) {
+      const idx = this._hash(key, i * 0x9e3779b9);
+      if ((this.bits[idx >>> 5] & (1 << (idx & 31))) === 0) return false;
+    }
+    return true;
+  }
+
+  clear() {
+    this.bits.fill(0);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// LRUCache – Least Recently Used cache with O(1) get/set/delete
+// Uses a doubly-linked list for ordering + Map for O(1) lookup.
+// ═══════════════════════════════════════════════════════════════
+class LRUCache {
+  constructor(capacity = 128) {
+    this.capacity = capacity;
+    this.map = new Map();
+    this.head = { key: null, val: null, prev: null, next: null };
+    this.tail = { key: null, val: null, prev: null, next: null };
+    this.head.next = this.tail;
+    this.tail.prev = this.head;
+  }
+
+  _remove(node) {
+    node.prev.next = node.next;
+    node.next.prev = node.prev;
+  }
+
+  _addToFront(node) {
+    node.next = this.head.next;
+    node.prev = this.head;
+    this.head.next.prev = node;
+    this.head.next = node;
+  }
+
+  get(key) {
+    const node = this.map.get(key);
+    if (!node) return undefined;
+    this._remove(node);
+    this._addToFront(node);
+    return node.val;
+  }
+
+  set(key, val) {
+    if (this.map.has(key)) {
+      const node = this.map.get(key);
+      node.val = val;
+      this._remove(node);
+      this._addToFront(node);
+      return;
+    }
+    const node = { key, val, prev: null, next: null };
+    this.map.set(key, node);
+    this._addToFront(node);
+    if (this.map.size > this.capacity) {
+      const lru = this.tail.prev;
+      this._remove(lru);
+      this.map.delete(lru.key);
+    }
+  }
+
+  delete(key) {
+    const node = this.map.get(key);
+    if (!node) return false;
+    this._remove(node);
+    this.map.delete(key);
+    return true;
+  }
+
+  has(key) { return this.map.has(key); }
+  get size() { return this.map.size; }
+  clear() { this.map.clear(); this.head.next = this.tail; this.tail.prev = this.head; }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// RingBuffer – Fixed-size circular buffer, O(1) push/get
+// No array shifting, no GC pressure from old elements.
+// ═══════════════════════════════════════════════════════════════
+class RingBuffer {
+  constructor(capacity = 64) {
+    this.buf = new Array(capacity);
+    this.capacity = capacity;
+    this.head = 0;
+    this.count = 0;
+  }
+
+  push(item) {
+    const idx = (this.head + this.count) % this.capacity;
+    this.buf[idx] = item;
+    if (this.count < this.capacity) {
+      this.count++;
+    } else {
+      this.head = (this.head + 1) % this.capacity;
+    }
+  }
+
+  get(i) {
+    if (i < 0 || i >= this.count) return undefined;
+    return this.buf[(this.head + i) % this.capacity];
+  }
+
+  toArray() {
+    const arr = new Array(this.count);
+    for (let i = 0; i < this.count; i++) {
+      arr[i] = this.buf[(this.head + i) % this.capacity];
+    }
+    return arr;
+  }
+
+  get length() { return this.count; }
+
+  last(n = 1) {
+    const start = Math.max(0, this.count - n);
+    const result = [];
+    for (let i = start; i < this.count; i++) {
+      result.push(this.get(i));
+    }
+    return result;
+  }
+
+  clear() { this.head = 0; this.count = 0; this.buf.fill(undefined); }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Trie – Prefix search tree, O(k) insert/search/startsWith
+// Used for fast item name matching and autocomplete.
+// ═══════════════════════════════════════════════════════════════
+class Trie {
+  constructor() {
+    this.root = { children: new Map(), value: null, isEnd: false };
+  }
+
+  insert(key, value = true) {
+    let node = this.root;
+    for (const ch of key.toLowerCase()) {
+      if (!node.children.has(ch)) {
+        node.children.set(ch, { children: new Map(), value: null, isEnd: false });
+      }
+      node = node.children.get(ch);
+    }
+    node.isEnd = true;
+    node.value = value;
+  }
+
+  search(key) {
+    let node = this.root;
+    for (const ch of key.toLowerCase()) {
+      if (!node.children.has(ch)) return null;
+      node = node.children.get(ch);
+    }
+    return node.isEnd ? node.value : null;
+  }
+
+  startsWith(prefix) {
+    let node = this.root;
+    for (const ch of prefix.toLowerCase()) {
+      if (!node.children.has(ch)) return [];
+      node = node.children.get(ch);
+    }
+    const results = [];
+    const dfs = (n, path) => {
+      if (n.isEnd) results.push({ key: path, value: n.value });
+      for (const [ch, child] of n.children) dfs(child, path + ch);
+    };
+    dfs(node, prefix.toLowerCase());
+    return results;
+  }
+
+  containsInText(text) {
+    const lower = text.toLowerCase();
+    const matches = [];
+    for (let i = 0; i < lower.length; i++) {
+      let node = this.root;
+      for (let j = i; j < lower.length; j++) {
+        if (!node.children.has(lower[j])) break;
+        node = node.children.get(lower[j]);
+        if (node.isEnd) {
+          matches.push({ start: i, end: j + 1, value: node.value });
+        }
+      }
+    }
+    return matches;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AhoCorasick – Multi-pattern string matching, O(n + m + z)
+// n = text length, m = total pattern chars, z = number of matches.
+// Builds a finite automaton with failure links (like KMP for multiple patterns).
+// Used to detect "need item", "cooldown", "captcha" etc. in one pass.
+// ═══════════════════════════════════════════════════════════════
+class AhoCorasick {
+  constructor() {
+    this.goto = [new Map()];
+    this.fail = [0];
+    this.output = [[]];
+    this.built = false;
+  }
+
+  addPattern(pattern, tag = pattern) {
+    let state = 0;
+    for (const ch of pattern.toLowerCase()) {
+      if (!this.goto[state].has(ch)) {
+        const next = this.goto.length;
+        this.goto.push(new Map());
+        this.fail.push(0);
+        this.output.push([]);
+        this.goto[state].set(ch, next);
+      }
+      state = this.goto[state].get(ch);
+    }
+    this.output[state].push(tag);
+    this.built = false;
+  }
+
+  build() {
+    const queue = [];
+    for (const [ch, s] of this.goto[0]) {
+      this.fail[s] = 0;
+      queue.push(s);
+    }
+    while (queue.length > 0) {
+      const r = queue.shift();
+      for (const [ch, s] of this.goto[r]) {
+        queue.push(s);
+        let state = this.fail[r];
+        while (state !== 0 && !this.goto[state].has(ch)) state = this.fail[state];
+        this.fail[s] = this.goto[state].has(ch) ? this.goto[state].get(ch) : 0;
+        if (this.fail[s] === s) this.fail[s] = 0;
+        this.output[s] = this.output[s].concat(this.output[this.fail[s]]);
+      }
+    }
+    this.built = true;
+  }
+
+  search(text) {
+    if (!this.built) this.build();
+    const lower = text.toLowerCase();
+    const results = [];
+    let state = 0;
+    for (let i = 0; i < lower.length; i++) {
+      const ch = lower[i];
+      while (state !== 0 && !this.goto[state].has(ch)) state = this.fail[state];
+      state = this.goto[state].has(ch) ? this.goto[state].get(ch) : 0;
+      for (const tag of this.output[state]) {
+        results.push({ index: i, tag });
+      }
+    }
+    return results;
+  }
+
+  hasAny(text) {
+    if (!this.built) this.build();
+    const lower = text.toLowerCase();
+    let state = 0;
+    for (let i = 0; i < lower.length; i++) {
+      const ch = lower[i];
+      while (state !== 0 && !this.goto[state].has(ch)) state = this.fail[state];
+      state = this.goto[state].has(ch) ? this.goto[state].get(ch) : 0;
+      if (this.output[state].length > 0) return this.output[state][0];
+    }
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// TokenBucket – Rate limiter, O(1) consume/refill
+// Allows burst up to capacity, refills at steady rate.
+// ═══════════════════════════════════════════════════════════════
+class TokenBucket {
+  constructor(capacity, refillRate, refillIntervalMs = 1000) {
+    this.capacity = capacity;
+    this.tokens = capacity;
+    this.refillRate = refillRate;
+    this.refillIntervalMs = refillIntervalMs;
+    this.lastRefill = Date.now();
+  }
+
+  _refill() {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    const tokensToAdd = (elapsed / this.refillIntervalMs) * this.refillRate;
+    this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
+    this.lastRefill = now;
+  }
+
+  consume(n = 1) {
+    this._refill();
+    if (this.tokens >= n) {
+      this.tokens -= n;
+      return true;
+    }
+    return false;
+  }
+
+  waitTime(n = 1) {
+    this._refill();
+    if (this.tokens >= n) return 0;
+    const deficit = n - this.tokens;
+    return Math.ceil((deficit / this.refillRate) * this.refillIntervalMs);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// EMA – Exponential Moving Average, O(1) update/read
+// Smooths noisy data (earnings per command, win rates).
+// ═══════════════════════════════════════════════════════════════
+class EMA {
+  constructor(alpha = 0.1) {
+    this.alpha = alpha;
+    this.value = null;
+    this.count = 0;
+  }
+
+  update(sample) {
+    this.count++;
+    if (this.value === null) {
+      this.value = sample;
+    } else {
+      this.value = this.alpha * sample + (1 - this.alpha) * this.value;
+    }
+    return this.value;
+  }
+
+  get() { return this.value ?? 0; }
+  reset() { this.value = null; this.count = 0; }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SlidingWindowCounter – Time-based event rate, O(1) amortized
+// Counts events within a sliding window (e.g., commands per minute).
+// Uses two half-windows for smooth approximation.
+// ═══════════════════════════════════════════════════════════════
+class SlidingWindowCounter {
+  constructor(windowMs = 60000) {
+    this.windowMs = windowMs;
+    this.currentCount = 0;
+    this.previousCount = 0;
+    this.currentStart = Date.now();
+  }
+
+  _advance() {
+    const now = Date.now();
+    const elapsed = now - this.currentStart;
+    if (elapsed >= this.windowMs) {
+      this.previousCount = this.currentCount;
+      this.currentCount = 0;
+      this.currentStart = now;
+    }
+  }
+
+  increment() {
+    this._advance();
+    this.currentCount++;
+  }
+
+  getRate() {
+    this._advance();
+    const elapsed = Date.now() - this.currentStart;
+    const weight = elapsed / this.windowMs;
+    return this.currentCount + this.previousCount * (1 - weight);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// MinHeap – Binary heap priority queue, O(log n) push/pop
+// ═══════════════════════════════════════════════════════════════
+class MinHeap {
+  constructor(comparator = (a, b) => a - b) {
+    this.heap = [];
+    this.cmp = comparator;
+  }
+
+  get size() { return this.heap.length; }
+
+  push(val) {
+    this.heap.push(val);
+    this._bubbleUp(this.heap.length - 1);
+  }
+
+  pop() {
+    if (this.heap.length === 0) return undefined;
+    const top = this.heap[0];
+    const last = this.heap.pop();
+    if (this.heap.length > 0) {
+      this.heap[0] = last;
+      this._sinkDown(0);
+    }
+    return top;
+  }
+
+  peek() { return this.heap[0]; }
+
+  _bubbleUp(i) {
+    while (i > 0) {
+      const parent = (i - 1) >>> 1;
+      if (this.cmp(this.heap[i], this.heap[parent]) < 0) {
+        [this.heap[i], this.heap[parent]] = [this.heap[parent], this.heap[i]];
+        i = parent;
+      } else break;
+    }
+  }
+
+  _sinkDown(i) {
+    const n = this.heap.length;
+    while (true) {
+      let smallest = i;
+      const left = 2 * i + 1;
+      const right = 2 * i + 2;
+      if (left < n && this.cmp(this.heap[left], this.heap[smallest]) < 0) smallest = left;
+      if (right < n && this.cmp(this.heap[right], this.heap[smallest]) < 0) smallest = right;
+      if (smallest !== i) {
+        [this.heap[i], this.heap[smallest]] = [this.heap[smallest], this.heap[i]];
+        i = smallest;
+      } else break;
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// VoseAlias – O(1) weighted random sampling after O(n) setup
+// Walker's alias method. Used for safe button selection with weights.
+// ═══════════════════════════════════════════════════════════════
+class VoseAlias {
+  constructor(weights) {
+    const n = weights.length;
+    const total = weights.reduce((a, b) => a + b, 0);
+    this.prob = new Float64Array(n);
+    this.alias = new Int32Array(n);
+    const scaled = weights.map(w => (w / total) * n);
+    const small = [], large = [];
+    for (let i = 0; i < n; i++) {
+      (scaled[i] < 1 ? small : large).push(i);
+    }
+    while (small.length > 0 && large.length > 0) {
+      const s = small.pop();
+      const l = large.pop();
+      this.prob[s] = scaled[s];
+      this.alias[s] = l;
+      scaled[l] = scaled[l] + scaled[s] - 1;
+      (scaled[l] < 1 ? small : large).push(l);
+    }
+    while (large.length > 0) this.prob[large.pop()] = 1;
+    while (small.length > 0) this.prob[small.pop()] = 1;
+  }
+
+  sample() {
+    const i = Math.floor(Math.random() * this.prob.length);
+    return Math.random() < this.prob[i] ? i : this.alias[i];
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// StringPool – String interning / deduplication, O(1) lookup
+// Repeated strings (Discord IDs, channel IDs) share one reference.
+// ═══════════════════════════════════════════════════════════════
+class StringPool {
+  constructor() {
+    this.pool = new Map();
+  }
+
+  intern(str) {
+    if (typeof str !== 'string') return str;
+    const existing = this.pool.get(str);
+    if (existing !== undefined) return existing;
+    this.pool.set(str, str);
+    return str;
+  }
+
+  get size() { return this.pool.size; }
+  clear() { this.pool.clear(); }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// BitSet – Compact boolean array using Uint32Array, O(1) ops
+// ═══════════════════════════════════════════════════════════════
+class BitSet {
+  constructor(size = 256) {
+    this.bits = new Uint32Array(Math.ceil(size / 32));
+    this.size = size;
+  }
+
+  set(i) { this.bits[i >>> 5] |= (1 << (i & 31)); }
+  clear(i) { this.bits[i >>> 5] &= ~(1 << (i & 31)); }
+  get(i) { return (this.bits[i >>> 5] & (1 << (i & 31))) !== 0; }
+  toggle(i) { this.bits[i >>> 5] ^= (1 << (i & 31)); }
+  clearAll() { this.bits.fill(0); }
+
+  popcount() {
+    let count = 0;
+    for (let i = 0; i < this.bits.length; i++) {
+      let v = this.bits[i];
+      v = v - ((v >> 1) & 0x55555555);
+      v = (v & 0x33333333) + ((v >> 2) & 0x33333333);
+      count += ((v + (v >> 4)) & 0x0f0f0f0f) * 0x01010101 >> 24;
+    }
+    return count;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// ObjectPool – Reusable object allocator, O(1) acquire/release
+// Avoids GC pressure from frequent small object allocation.
+// ═══════════════════════════════════════════════════════════════
+class ObjectPool {
+  constructor(factory, resetFn, maxSize = 64) {
+    this.factory = factory;
+    this.resetFn = resetFn;
+    this.pool = [];
+    this.maxSize = maxSize;
+  }
+
+  acquire() {
+    return this.pool.length > 0 ? this.pool.pop() : this.factory();
+  }
+
+  release(obj) {
+    if (this.pool.length < this.maxSize) {
+      this.resetFn(obj);
+      this.pool.push(obj);
+    }
+  }
+
+  get available() { return this.pool.length; }
+  prewarm(n) { for (let i = 0; i < n; i++) this.pool.push(this.factory()); }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// TimerWheel – Hashed timer wheel, O(1) schedule/cancel
+// At 10K accounts × 26 commands = 260K timers, individual setTimeout
+// creates 260K heap objects. TimerWheel uses a single flat circular
+// array — the same technique used by the Linux kernel and Kafka.
+// ═══════════════════════════════════════════════════════════════
+class TimerWheel {
+  constructor(buckets = 1024, tickMs = 100) {
+    this.buckets = buckets;
+    this.tickMs = tickMs;
+    this.wheel = new Array(buckets);
+    for (let i = 0; i < buckets; i++) this.wheel[i] = [];
+    this.current = 0;
+    this._nextId = 0;
+    this._interval = null;
+    this._pending = 0;
+  }
+
+  start() {
+    if (this._interval) return;
+    this._interval = setInterval(() => this._tick(), this.tickMs);
+    if (this._interval.unref) this._interval.unref();
+  }
+
+  stop() {
+    if (this._interval) { clearInterval(this._interval); this._interval = null; }
+  }
+
+  schedule(delayMs, callback) {
+    const ticks = Math.max(1, Math.round(delayMs / this.tickMs));
+    const slot = (this.current + ticks) & (this.buckets - 1);
+    const id = ++this._nextId;
+    this.wheel[slot].push({ cb: callback, id });
+    this._pending++;
+    return id;
+  }
+
+  cancel(id) {
+    for (let i = 0; i < this.buckets; i++) {
+      const bucket = this.wheel[i];
+      for (let j = 0; j < bucket.length; j++) {
+        if (bucket[j].id === id) {
+          bucket[j] = bucket[bucket.length - 1];
+          bucket.pop();
+          this._pending--;
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  _tick() {
+    this.current = (this.current + 1) & (this.buckets - 1);
+    const bucket = this.wheel[this.current];
+    if (bucket.length === 0) return;
+    const batch = bucket.splice(0);
+    this._pending -= batch.length;
+    for (let i = 0; i < batch.length; i++) {
+      try { batch[i].cb(); } catch {}
+    }
+  }
+
+  get pendingCount() { return this._pending; }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AsyncBatchQueue – Coalesces async operations into batches
+// At 10K accounts, individual Redis calls or API reports create
+// massive overhead. BatchQueue accumulates items and flushes them
+// in one call (e.g., Redis pipeline, bulk HTTP POST).
+// ═══════════════════════════════════════════════════════════════
+class AsyncBatchQueue {
+  constructor(flushFn, opts = {}) {
+    this.flushFn = flushFn;
+    this.maxSize = opts.maxSize || 50;
+    this.flushMs = opts.flushMs || 1000;
+    this.queue = [];
+    this._timer = null;
+  }
+
+  push(item) {
+    this.queue.push(item);
+    if (this.queue.length >= this.maxSize) {
+      this._flush();
+    } else if (!this._timer) {
+      this._timer = setTimeout(() => this._flush(), this.flushMs);
+      if (this._timer.unref) this._timer.unref();
+    }
+  }
+
+  _flush() {
+    if (this._timer) { clearTimeout(this._timer); this._timer = null; }
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0);
+    try { this.flushFn(batch); } catch {}
+  }
+
+  flush() { this._flush(); }
+  get pending() { return this.queue.length; }
+  destroy() { if (this._timer) clearTimeout(this._timer); this.queue.length = 0; }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// JitterBackoff – Decorrelated jitter (AWS-style), O(1)
+// Standard exponential backoff causes "thundering herd" when 10K
+// accounts retry simultaneously. Decorrelated jitter spreads them:
+//   sleep = min(cap, random_between(base, sleep_prev * 3))
+// This is the recommended strategy from AWS Architecture Blog.
+// ═══════════════════════════════════════════════════════════════
+class JitterBackoff {
+  constructor(baseMs = 1000, capMs = 30000) {
+    this.baseMs = baseMs;
+    this.capMs = capMs;
+    this._sleep = baseMs;
+    this.attempt = 0;
+  }
+
+  next() {
+    this._sleep = Math.min(this.capMs, this.baseMs + Math.random() * (this._sleep * 3 - this.baseMs));
+    this.attempt++;
+    return this._sleep;
+  }
+
+  reset() { this._sleep = this.baseMs; this.attempt = 0; }
+  get current() { return this._sleep; }
+}
+
+module.exports = {
+  BloomFilter,
+  LRUCache,
+  RingBuffer,
+  Trie,
+  AhoCorasick,
+  TokenBucket,
+  EMA,
+  SlidingWindowCounter,
+  MinHeap,
+  VoseAlias,
+  StringPool,
+  BitSet,
+  ObjectPool,
+  TimerWheel,
+  AsyncBatchQueue,
+  JitterBackoff,
+};