No Partying Mariachis

    TypeScript icon, indicating that this package has built-in type declarations

    1.9.0 • Public • Published


    MIT License NPM Version Coveralls Issues GitHub contributors

    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.

    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.


    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;   // 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]; // 1
    cb.first; // 1
    cb.last;  // 3
    cb.push(4); // throws - full! ; [1,2,3]
    cb.pop(); // 1: [2,3, ]; // 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! ; [ , , ]


    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 = () => {
          `Using circular buffer version ${circular_buffer.version}`
                          // package      // class
        const mybuf = new circular_buffer.circular_buffer(5);


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


    npm i circular_buffer_js

    DownloadsWeekly Downloads






    Unpacked Size

    56 kB

    Total Files


    Last publish


    • stonecypher