Rate Limiting, Throttling and Quota Management Questions

class TokenBucket {
  constructor({ capacity, refillRate }) {
    this.capacity = capacity;           // max tokens (burst)
    this.refillRate = refillRate;       // tokens per second
    this.tokens = capacity;             // current available tokens (lazy)
    this.last = Date.now();             // last refill timestamp (ms)
    this.queue = [];                    // waiting requests: {count, resolve}
    this.timer = null;
  }

  // refill tokens based on elapsed time (lazy)
  _refill() {
    const now = Date.now();
    const elapsed = (now - this.last) / 1000;
    if (elapsed <= 0) return;
    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
    this.last = now;
  }

  // attempt immediate removal
  tryRemove(count = 1) {
    this._refill();
    if (count <= this.tokens) {
      this.tokens -= count;
      return true;
    }
    return false;
  }

  // remove with waiting; returns Promise resolving when tokens are removed
  remove(count = 1) {
    if (count > this.capacity) {
      return Promise.reject(new Error('Requested count exceeds capacity'));
    }
    this._refill();
    if (count <= this.tokens) {
      this.tokens -= count;
      return Promise.resolve();
    }
    return new Promise((resolve) => {
      this.queue.push({ count, resolve });
      // ensure single timer is scheduled to process queue when tokens become available
      if (!this.timer) this._scheduleNext();
    });
  }

  // compute ms until at least 'need' tokens available
  _msUntil(need) {
    this._refill();
    if (need <= this.tokens) return 0;
    const missing = need - this.tokens;
    return Math.ceil((missing / this.refillRate) * 1000);
  }

  // schedule timer to wake earliest waiter
  _scheduleNext() {
    if (this.queue.length === 0) { this.timer = null; return; }
    const nextNeed = this.queue[0].count;
    const ms = this._msUntil(nextNeed);
    this.timer = setTimeout(() => {
      this.timer = null;
      this._refill();
      // process as many queued requests as possible
      while (this.queue.length > 0 && this.queue[0].count <= this.tokens) {
        const req = this.queue.shift();
        this.tokens -= req.count;
        req.resolve();
      }
      // if still queued, schedule next wake
      if (this.queue.length > 0) this._scheduleNext();
    }, Math.max(0, ms));
  }
}

function rateLimit(fn, maxCalls, perMilliseconds) {
  const queue = [];
  let calls = 0;
  let windowStart = Date.now();

  function tryDrain() {
    const now = Date.now();
    // reset window if elapsed
    if (now - windowStart >= perMilliseconds) {
      windowStart = now;
      calls = 0;
    }
    while (calls < maxCalls && queue.length) {
      const { context, args, resolve, reject } = queue.shift();
      calls++;
      try {
        resolve(fn.apply(context, args));
      } catch (err) {
        reject(err);
      }
    }
    if (queue.length) {
      // schedule next attempt when window expires
      const wait = Math.max(0, perMilliseconds - (Date.now() - windowStart));
      setTimeout(tryDrain, wait);
    }
  }

  return function (...args) {
    const context = this;
    return new Promise((resolve, reject) => {
      queue.push({ context, args, resolve, reject });
      // start draining immediately if possible
      tryDrain();
    });
  };
}