circular_buffer_js

circular_buffer_js

npm install --save-dev circular_buffer_js

• Documentation
  • Main functional documentation
• Build history

Typescript implementation of a circular buffer, and JS compiles to a es6 module minified, es6 commonjs minified, es6 iife minified, and es6 iife full.

1. Well tested.
   • 100% coverage, 100% property coverage.
2. Tiny.
   • The es6 minified module build is currently 1.4k.
3. Dependency-free.
   • Only dev-time deps like typescript are involved.

API

You should consider viewing the real documentation, but:

// yields a buffer of fixed size `size`
const cb  = new circular_buffer(size),
      cb2 = circular_buffer.from([1,2,3]);

cb.push(item);       // inserts `item` at end of `cb`, then returns `item`
cb.shove(item);      // inserts `item` at end of `cb`; remove if needed, returns removed
cb.pop();            // removes and returns first element
cb.at(location);     // shows the element at 0-indexed offset `location`
cb.pos(location);    // shows the element at run-indexed offset `location`
cb.offset();         // shows the delta from 0-indexed to head
cb.indexOf(item);    // returns the index of the first `item`, or -1
cb.find(pred);       // return the the first match or undefined
cb.every(pred);      // tests if every queue element satisfies the predicate
cb.some(pred);       // tests if at least one element satisfies the predicate
cb.fill(item);       // maxes `length` and sets every element to `item`
cb.clear();          // empties the container
cb.reverse();        // reverses the container
cb.resize(size,pE);  // change to new size, truncating if required; pE to prefer end
cb.toArray();        // return an array of the current contents of the queue

cb.first;            // returns the first value in the queue; throws when empty
cb.last;             // returns the last value in the queue; throws when empty
cb.isFull;           // returns `true` if no space left; `false` otherwise
cb.isEmpty;          // returns `true` if no space remains; `false` otherwise
cb.available;        // returns the number of spaces remaining currently
cb.capacity;         // returns the total `size` allocated
cb.length;           // returns the amount of space currently used

What is this?

This is a circular buffer (or cycle buffer, ring queue, etc.) It was written because a library I wanted to use had a native buggy implementation, so I provided something more trustworthy.

A circular buffer is a fixed size buffer that allows you to push and pop forever, as a first in first out queue-like structure. Circular buffers are more efficient than queues, but can overflow.

Basic usage

import { circular_buffer } from 'circular_buffer_js';

const cb = new circular_buffer(3);  // [ , , ]

cb.push(1); // ok: [1, , ]
cb.push(2); // ok: [1,2, ]
cb.push(3); // ok: [1,2,3]

cb.at(0); // 1
cb.first; // 1
cb.last;  // 3

cb.push(4); // throws - full! ; [1,2,3]

cb.pop(); // 1: [2,3, ]
cb.at(0); // 2: [2,3, ]

cb.push(4); // ok: [2,3,4]
cb.push(5); // throws - full! ; [2,3,4]

cb.pop(); // 2: [3,4, ]
cb.pop(); // 3: [4, , ]
cb.pop(); // 4: [ , , ]

cb.pop(); // throws - empty! ; [ , , ]

Typescript

It's typescript, so you can also

import { circular_buffer } from 'circular_buffer_js';
const cb = new circular_buffer<number>(3);

Node CommonJS

And there's a CommonJS build, so you can

const cbuf            = require('circular_buffer_js'),
      circular_buffer = new cbuf.circular_buffer;

Browser <script>

There're also two iife builds - both regular and minified - so that you can use this in older browsers, or from CDN.

<script defer type="text/javascript" src="circular_buffer_js.min.js"></script>
<script defer type="text/javascript">

  window.onload = () => {

    console.log(
      `Using circular buffer version ${circular_buffer.version}`
    );

                      // package      // class
    const mybuf = new circular_buffer.circular_buffer(5);

  };

</script>

Alternatives

If this doesn't meet your needs, please try:

• ring-buffer-ts
• CBuffer
• ringbuffer.js
• qlist
• fixed-size-list
• circular-buffer
• cyclist
• cyclic-buffer
• bsh-circular-buffer
• cbarrick-circular-buffer
• limited-cache