leaky-bucket

Note

This is one of 203 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
• Status
• Installation
• Dependencies
• API
• Authors
• License

About

Configurable, counter-based Leaky Bucket abstractions for generalized rate-limiting purposes.

Leaky Buckets 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.

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
// ...

In addition to individual LeakyBuckets, 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

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Installation

yarn add @thi.ng/leaky-bucket

ESM import:

import * as lb from "@thi.ng/leaky-bucket";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/leaky-bucket"></script>

JSDelivr documentation

For Node.js REPL:

const lb = await import("@thi.ng/leaky-bucket");

Package sizes (brotli'd, pre-treeshake): ESM: 624 bytes

Dependencies

• @thi.ng/api

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

API

Generated API docs

import { LeakyBucketMap } from "@thi.ng/leaky-bucket";

const buckets = new LeakyBucketMap({
    maxBuckets: 2,
    capacity: 3,
    leakInterval: 1000,
});

buckets.update("a") // true
buckets.update("a") // true
buckets.update("a") // true

// max capacity=3 reached
buckets.update("a"); // false

// another bucket
buckets.update("b"); // true

// max buckets=2 reached
buckets.update("c"); // false

// wait > 1000ms, buckets have leaked...

// bucket A has capacity again
buckets.update("a"); // true

// bucket B has been removed (since emtpy)
buckets.has("b"); // false

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-leaky-bucket,
  title = "@thi.ng/leaky-bucket",
  author = "Karsten Schmidt",
  note = "https://thi.ng/leaky-bucket",
  year = 2025
}

License

© 2025 Karsten Schmidt // Apache License 2.0