@thi.ng/leaky-bucket 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-03-09T19:21:53Z
+- **Last updated**: 2025-03-10T08:53:05Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,16 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/leaky-bucket@0.2.0) (2025-03-10)
+
+#### 🚀 Features
+
+- add `.hasCapacity()` ([bdb13d2](https://github.com/thi-ng/umbrella/commit/bdb13d2))
+
+#### 🩹 Bug fixes
+
+- fix delta time handling in `.leak()` ([a42c9d5](https://github.com/thi-ng/umbrella/commit/a42c9d5))
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/leaky-bucket@0.1.0) (2025-03-09)
 
 #### 🚀 Features

package/README.md

@@ -24,11 +24,59 @@
 
 ## About
 
-Configurable, counter-based Leaky Bucket abstractions.
+Configurable, counter-based Leaky Bucket abstractions for generalized rate-limiting purposes.
+
+[Leaky Buckets](https://en.wikipedia.org/wiki/Leaky_bucket) are commonly used in
+communication networks for rate limiting, traffic shaping and bandwidth control,
+but are equally useful in other domains requiring similar constraints.
+
+A Leaky Bucket is a managed counter with an enforced maximum value (i.e. bucket
+capacity). The counter is incremented for each a new event to check if it
+can/should be processed. If the bucket capacity has already been reached, the
+bucket will report an overflow, which we can then handle accordingly (e.g. by
+dropping or queuing events). The bucket also has a configurable time interval at
+which the counter is decreasing (aka the "leaking" behavior) until it reaches
+zero again (i.e. until the bucket is empty). Altogether, this setup can be
+utilized to ensure both an average rate, whilst also supporting temporary
+bursting in a controlled fashion.
 
-Reference:
+```ts tangle:export/readme-1.ts
+import { LeakyBucket } from "@thi.ng/leaky-bucket";
+
+// create bucket w/ 1Hz mean target rate, burstable to 3Hz
+const bucket = new LeakyBucket({ capacity: 3, leakInterval: 1000 });
+
+let event = 0;
+let t0 = Date.now();
+
+// trigger events at 5Hz
+setInterval(() => {
+    event++;
+    // update bucket and only log successful events (discard the rest)
+    if (bucket.update()) {
+        console.log("time", Date.now() - t0, "/ event", event);
+    }
+}, 200);
+
+// time 200 / event 1   <-- initial burst
+// time 401 / event 2   <-- initial burst
+// time 601 / event 3   <-- initial burst
+// time 1003 / event 5  <-- average rate enforced
+// time 2007 / event 10
+// time 3012 / event 15
+// time 4017 / event 20
+// ...
+```
 
-- https://en.wikipedia.org/wiki/Leaky_bucket
+In addition to individual `LeakyBucket`s, this package also provides a
+`LeakyBucketMap` for managing multiple buckets in a key-value store, with shared
+configuration and more efficient updates (only using a single timer). Other
+features include:
+
+- enforces max number of active (non-empty) buckets
+- auto-pruning of empty buckets
+- auto-creation of new buckets
+- per-bucket capacity overrides
 
 ## Status
 
@@ -62,7 +110,7 @@ For Node.js REPL:
 const lb = await import("@thi.ng/leaky-bucket");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 591 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 624 bytes
 
 ## Dependencies
 
@@ -74,7 +122,7 @@ Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 
 [Generated API docs](https://docs.thi.ng/umbrella/leaky-bucket/)
 
-```ts tangle:export/readme-1.ts
+```ts tangle:export/readme-2.ts
 import { LeakyBucketMap } from "@thi.ng/leaky-bucket";
 
 const buckets = new LeakyBucketMap({
@@ -83,9 +131,9 @@ const buckets = new LeakyBucketMap({
     leakInterval: 1000,
 });
 
-buckets.update("a") //true
-buckets.update("a") //true
-buckets.update("a") //true
+buckets.update("a") // true
+buckets.update("a") // true
+buckets.update("a") // true
 
 // max capacity=3 reached
 buckets.update("a"); // false

package/index.d.ts

@@ -67,7 +67,18 @@ export declare class LeakyBucketMap<K> implements IRelease {
     lastLeak: number;
     timer: any;
     constructor(opts?: Partial<LeakyBucketMapOpts<K>>);
+    /**
+     * Returns true, if there's an active bucket for given `key`.
+     *
+     * @param key
+     */
     has(key: K): boolean;
+    /**
+     * Attempts to look up bucket for given `key` and returns it (or `undefined`
+     * if there's no active bucket for that key).
+     *
+     * @param key
+     */
     get(key: K): LeakyBucket | undefined;
     /**
      * Calls {@link LeakyBucket.update} for given bucket ID and returns its
@@ -84,6 +95,14 @@ export declare class LeakyBucketMap<K> implements IRelease {
      * @param capacity
      */
     update(key: K, capacity?: number | undefined): boolean;
+    /**
+     * Returns true if bucket for given `key` has free capacity, or if no such
+     * bucket yet exists, if the map itself has capacity for creating a new
+     * bucket.
+     *
+     * @param key
+     */
+    hasCapacity(key: K): boolean;
     /**
      * Leaks all bucket counters (taking into account current/given timestamp)
      * and removes those which emptied. If {@link LeakyBucketMapOpts.onEmpty} is
@@ -118,6 +137,10 @@ export declare class LeakyBucket implements IRelease {
      * capacity had already been reached.
      */
     update(): boolean;
+    /**
+     * Returns true if the bucket has free capacity.
+     */
+    hasCapacity(): boolean;
     /**
      * Leaks bucket's counter (taking into account current/given timestamp) and
      * then returns one of the following values:

package/index.js

@@ -13,9 +13,20 @@ class LeakyBucketMap {
   leakInterval;
   lastLeak = -1;
   timer;
+  /**
+   * Returns true, if there's an active bucket for given `key`.
+   *
+   * @param key
+   */
   has(key) {
     return this.buckets.has(key);
   }
+  /**
+   * Attempts to look up bucket for given `key` and returns it (or `undefined`
+   * if there's no active bucket for that key).
+   *
+   * @param key
+   */
   get(key) {
     return this.buckets.get(key);
   }
@@ -46,6 +57,17 @@ class LeakyBucketMap {
     }
     return true;
   }
+  /**
+   * Returns true if bucket for given `key` has free capacity, or if no such
+   * bucket yet exists, if the map itself has capacity for creating a new
+   * bucket.
+   *
+   * @param key
+   */
+  hasCapacity(key) {
+    const bucket = this.buckets.get(key);
+    return bucket ? bucket.level < bucket.capacity : this.buckets.size < this.maxBuckets;
+  }
   /**
    * Leaks all bucket counters (taking into account current/given timestamp)
    * and removes those which emptied. If {@link LeakyBucketMapOpts.onEmpty} is
@@ -101,6 +123,12 @@ class LeakyBucket {
     this.level++;
     return true;
   }
+  /**
+   * Returns true if the bucket has free capacity.
+   */
+  hasCapacity() {
+    return this.level < this.capacity;
+  }
   /**
    * Leaks bucket's counter (taking into account current/given timestamp) and
    * then returns one of the following values:
@@ -116,13 +144,13 @@ class LeakyBucket {
   leak(now = Date.now()) {
     const delta = now - this.lastLeak;
     if (delta < this.leakInterval || !this.level) return;
+    this.lastLeak = now;
     const loss = Math.floor(delta / this.leakInterval);
     if (this.level <= loss) {
       this.level = 0;
       return false;
     }
     this.level -= loss;
-    this.lastLeak = now;
     return true;
   }
   /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/leaky-bucket",
-  "version": "0.1.0",
-  "description": "Configurable, counter-based Leaky Bucket abstractions",
+  "version": "0.2.0",
+  "description": "Configurable, counter-based Leaky Bucket abstractions for generalized rate-limiting purposes",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -79,5 +79,5 @@
     "status": "alpha",
     "year": 2025
   },
-  "gitHead": "55987d581e4985b1c3091ba6be3f9b53a0c5eeea\n"
+  "gitHead": "1df585220c1dbfbcdd10f7a775917b052ced1437\n"
 }