{"id":15672798,"url":"https://github.com/stonecypher/circular_buffer_js","last_synced_at":"2025-05-06T21:49:31.170Z","repository":{"id":40622356,"uuid":"322425089","full_name":"StoneCypher/circular_buffer_js","owner":"StoneCypher","description":"Fast TS/JS implementation of a circular buffer (aka ring queue, cyclic list, etc.)  Extremely well tested.","archived":false,"fork":false,"pushed_at":"2022-06-27T05:52:20.000Z","size":482,"stargazers_count":15,"open_issues_count":3,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-15T02:18:20.144Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StoneCypher.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-17T22:12:45.000Z","updated_at":"2022-08-21T11:09:53.000Z","dependencies_parsed_at":"2022-09-16T14:10:36.573Z","dependency_job_id":null,"html_url":"https://github.com/StoneCypher/circular_buffer_js","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneCypher%2Fcircular_buffer_js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneCypher%2Fcircular_buffer_js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneCypher%2Fcircular_buffer_js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneCypher%2Fcircular_buffer_js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StoneCypher","download_url":"https://codeload.github.com/StoneCypher/circular_buffer_js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252776506,"owners_count":21802463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T15:32:07.517Z","updated_at":"2025-05-06T21:49:31.146Z","avatar_url":"https://github.com/StoneCypher.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# circular_buffer_js\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/StoneCypher/circular_buffer_js/blob/master/LICENSEs)\n[![NPM Version](https://img.shields.io/npm/v/circular_buffer_js.svg?style=flat)]()\n[![Coveralls](https://img.shields.io/coveralls/StoneCypher/circular_buffer_js.svg?style=flat)]()\n[![Issues](https://img.shields.io/github/issues-raw/StoneCypher/circular_buffer_js.svg?maxAge=25000)](https://github.com/StoneCypher/circular_buffer_js/issues)\n[![GitHub contributors](https://img.shields.io/github/contributors/StoneCypher/circular_buffer_js.svg?style=flat)]()\n\n```\nnpm install --save-dev circular_buffer_js\n```\n\n* [Documentation](https://stonecypher.github.io/circular_buffer_js/docs/)\n    * [Main functional documentation](https://stonecypher.github.io/circular_buffer_js/docs/classes/circular_buffer.circular_buffer-1.html)\n* [Build history](https://github.com/StoneCypher/circular_buffer_js/actions)\n\n`Typescript` implementation of a circular buffer, and JS compiles to a es6\nmodule minified, es6 commonjs minified, es6 iife minified, and es6 iife full.\n\n1. Well tested.\n    * 100% coverage, 100% property coverage.\n1. Tiny.\n    * The `es6` minified module build is currently 1.4k.\n1. Dependency-free.\n    * Only dev-time deps like `typescript` are involved.\n\n\n\n\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n## API\n\nYou should consider viewing the\n[real documentation](https://stonecypher.github.io/circular_buffer_js/docs/classes/circular_buffer.circular_buffer-1.html),\nbut:\n\n```typescript\n// yields a buffer of fixed size `size`\nconst cb  = new circular_buffer(size),\n      cb2 = circular_buffer.from([1,2,3]);\n\ncb.push(item);       // inserts `item` at end of `cb`, then returns `item`\ncb.shove(item);      // inserts `item` at end of `cb`; remove if needed, returns removed\ncb.pop();            // removes and returns first element\ncb.at(location);     // shows the element at 0-indexed offset `location`\ncb.pos(location);    // shows the element at run-indexed offset `location`\ncb.offset();         // shows the delta from 0-indexed to head\ncb.indexOf(item);    // returns the index of the first `item`, or -1\ncb.find(pred);       // return the the first match or undefined\ncb.every(pred);      // tests if every queue element satisfies the predicate\ncb.some(pred);       // tests if at least one element satisfies the predicate\ncb.fill(item);       // maxes `length` and sets every element to `item`\ncb.clear();          // empties the container\ncb.reverse();        // reverses the container\ncb.resize(size,pE);  // change to new size, truncating if required; pE to prefer end\ncb.toArray();        // return an array of the current contents of the queue\n\ncb.first;            // returns the first value in the queue; throws when empty\ncb.last;             // returns the last value in the queue; throws when empty\ncb.isFull;           // returns `true` if no space left; `false` otherwise\ncb.isEmpty;          // returns `true` if no space remains; `false` otherwise\ncb.available;        // returns the number of spaces remaining currently\ncb.capacity;         // returns the total `size` allocated\ncb.length;           // returns the amount of space currently used\n```\n\n\n\n\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n## What is this?\n\nThis is a circular buffer (or cycle buffer, ring queue, etc.)  It was written\nbecause a library I wanted to use had a native buggy implementation, so I\nprovided something more trustworthy.\n\nA circular buffer is a fixed size buffer that allows you to push and pop\nforever, as a first in first out queue-like structure.  Circular buffers are\nmore efficient than queues, but can overflow.\n\n\n\n\u003cbr/\u003e\n\n### Basic usage\n\n```javascript\nimport { circular_buffer } from 'circular_buffer_js';\n\nconst cb = new circular_buffer(3);  // [ , , ]\n\ncb.push(1); // ok: [1, , ]\ncb.push(2); // ok: [1,2, ]\ncb.push(3); // ok: [1,2,3]\n\ncb.at(0); // 1\ncb.first; // 1\ncb.last;  // 3\n\ncb.push(4); // throws - full! ; [1,2,3]\n\ncb.pop(); // 1: [2,3, ]\ncb.at(0); // 2: [2,3, ]\n\ncb.push(4); // ok: [2,3,4]\ncb.push(5); // throws - full! ; [2,3,4]\n\ncb.pop(); // 2: [3,4, ]\ncb.pop(); // 3: [4, , ]\ncb.pop(); // 4: [ , , ]\n\ncb.pop(); // throws - empty! ; [ , , ]\n```\n\n\n\n\u003cbr/\u003e\n\n### Typescript\n\nIt's typescript, so you can also\n\n```typescript\nimport { circular_buffer } from 'circular_buffer_js';\nconst cb = new circular_buffer\u003cnumber\u003e(3);\n```\n\n\n\n\u003cbr/\u003e\n\n### Node CommonJS\n\nAnd there's a CommonJS build, so you can\n\n```javascript\nconst cbuf            = require('circular_buffer_js'),\n      circular_buffer = new cbuf.circular_buffer;\n```\n\n\n\n\u003cbr/\u003e\n\n### Browser \u0026lt;script\u0026gt;\n\nThere're also two `iife` builds - both regular and minified - so that you can\nuse this in older browsers, or from CDN.\n\n```html\n\u003cscript defer type=\"text/javascript\" src=\"circular_buffer_js.min.js\"\u003e\u003c/script\u003e\n\u003cscript defer type=\"text/javascript\"\u003e\n\n  window.onload = () =\u003e {\n\n    console.log(\n      `Using circular buffer version ${circular_buffer.version}`\n    );\n\n                      // package      // class\n    const mybuf = new circular_buffer.circular_buffer(5);\n\n  };\n\n\u003c/script\u003e\n```\n\n\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n## Alternatives\n\nIf this doesn't meet your needs, please try:\n\n* [ring-buffer-ts](https://www.npmjs.com/package/ring-buffer-ts)\n* [CBuffer](https://www.npmjs.com/package/CBuffer)\n* [ringbuffer.js](https://www.npmjs.com/package/ringbufferjs)\n* [qlist](https://www.npmjs.com/package/qlist)\n* [fixed-size-list](https://www.npmjs.com/package/fixed-size-list)\n* [circular-buffer](https://www.npmjs.com/package/circular-buffer)\n* [cyclist](https://www.npmjs.com/package/cyclist)\n* [cyclic-buffer](https://www.npmjs.com/package/cyclic-buffer)\n* [bsh-circular-buffer](https://www.npmjs.com/package/bsh-circular-buffer)\n* [cbarrick-circular-buffer](https://www.npmjs.com/package/cbarrick-circular-buffer)\n* [limited-cache](https://www.npmjs.com/package/limited-cache)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstonecypher%2Fcircular_buffer_js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstonecypher%2Fcircular_buffer_js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstonecypher%2Fcircular_buffer_js/lists"}