@toolbuilder/ring-buffer

RingBuffer

RingBuffer implements classic fixed length ring buffer (aka circular queue). For the ring buffer use case, RingBuffer is a drop in replacement for Array because push, pop, unshift, shift, and length match the signature of Array. For buffer operation either use push/shift or unshift/pop together.

RingBuffer is substantially faster than Array for the ring buffer use case. Newer versions of Node are much faster overall, and have improved dramatically for this use case. Using Node v22.11.0, relative times for the same number of push/shift operations are:

• RingBuffer: 205ms
• Array: 767ms
• @toolbuilder/list: 624ms - a doubly linked list

RingBuffer is a minimal implementation developed for use with Await-For-It iterable queues.

There are two related buffers:

• DynamicRingBuffer that efficiently grows and shrinks as items are added and removed.
• PriorityBuffer that uses your comparator to buffer items in priority order.

There are lots of ring buffer implementations on NPM. This implementation:

• Drop in replacement for Array for the ring buffer use case.
• Provides both export and module properties in package.json for ES bundlers.
• Provides Symbol.iterator generator.
• ES dual module that provides CommonJS and ES implementations.

Installation

npm install --save @toolbuilder/ring-buffer

Getting Started

The API documentation is here. This is a quick example to get you started.

import { RingBuffer } from '@toolbuilder/ring-buffer'
const log = console.log

const ringBuffer = new RingBuffer(10) // max length 10
log(ringBuffer.length) // prints 0

;['A', 'B', 'C'].forEach(x => ringBuffer.push(x))
log(ringBuffer.length) // prints 3
log(ringBuffer.front()) // prints 'A'
log(ringBuffer.back()) // prints 'C'
log(ringBuffer.shift()) // pulls 'A' off the front and prints 'A'
log(ringBuffer.length) // prints 2
log([...ringBuffer]) // prints ['B', 'C']
log(ringBuffer.length) // prints 2

Performance

There is a simplistic performance test:

# from package root:
node test/ringbuffer_perf.js

Alternatives

There are lots of alternatives on npm.

Contributing

Contributions are welcome. Please create a pull request.

• I use pnpm instead of npm.
• Package verification requires pnpm to be installed globally.
  • npm install -g pnpm
  • pnpm install --frozen-lockfile to get the dependencies as published
  • pnpm test to run unit tests
  • pnpm run check:packfile generates pack file to run unit tests against Node ES and CommonJS projects, as well as Electron.
  • pnpm run check:performance to run the performance test
  • pnpm run check validates the package is ready for commit
  • pnpm run release updates the changelog based on conventional commits, commits the update, and tags

Issues

This project uses Github issues.

License

MIT