Package Exports

circular_buffer_js
circular_buffer_js/dist/circular_buffer.cjs.min.js
circular_buffer_js/dist/circular_buffer.esm.min.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (circular_buffer_js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

circular_buffer_js

npm install --save-dev circular_buffer_js

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

Well tested.
- 100% coverage, 100% property coverage.
Tiny.
- The es6 minified module build is currently 1.4k.
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`, removing 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);   // change capacity to new size, truncating if required
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: