{"_id":"@caelus-dts/circular-buffer","name":"@caelus-dts/circular-buffer","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@caelus-dts/circular-buffer","version":"0.1.0","description":"A TypeScript implementation of a circular buffer, a data structure that uses a single, fixed-size buffer as if it were connected end-to-end.","publishConfig":{"registry":"https://registry.npmjs.org/"},"main":"dist/cjs/index.js","module":"dist/es/index.js","types":"dist/types/index.d.ts","scripts":{"build":"vite build","test":"jest --detectOpenHandles"},"keywords":["circular buffer","ring buffer","data structure"],"author":{"name":"Caelus"},"license":"MIT","exports":{".":{"types":"./dist/types/index.d.ts","require":"./dist/cjs/index.js","import":"./dist/es/index.js","default":"./dist/es/index.js"}},"dependencies":{"@caelus-dts/iterable":"^1.0.0"},"devDependencies":{"@types/jest":"^29.5.14","jest":"^29.7.0","node-notifier":"^10.0.1","ts-jest":"^29.2.5","vite":"^6.0.5","vite-plugin-dts":"^4.4.0"},"repository":{"url":"git+https://github.com/caelus-lab/caelus-dts-circular_buffer.git"},"bugs":{"url":"https://github.com/caelus-lab/caelus-dts-circular_buffer/issues"},"homepage":"https://github.com/caelus-lab/caelus-dts-circular_buffer#readme","_id":"@caelus-dts/circular-buffer@0.1.0","gitHead":"5a102b55e713453ac044e67751e58334703fb49e","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-03sPOXPssXImxnnuyDLzWE6A65NQkhbw5jpzv3ehizHyxq7oYA+uTW7vPLxYoEyn8EhHRRcvurGplOFfekMZGA==","shasum":"6a2ecd3347efc78102b98155e0a5a364cdd60e8e","tarball":"https://registry.npmjs.org/@caelus-dts/circular-buffer/-/circular-buffer-0.1.0.tgz","fileCount":6,"unpackedSize":22188,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDb99JxXMNdov1m+N8dDKJP9nqKGF04RYJpC6xMYy5lHQIhAOf3k4O6lssCNhF4u0+3GC6GbFrXu6OAC4C1QWvWxHyM"}]},"_npmUser":{"name":"caelus-lib","email":"caelus.team@hotmail.com"},"directories":{},"maintainers":[{"name":"caelus-lib","email":"caelus.team@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/circular-buffer_0.1.0_1736283394246_0.778535745321381"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-07T20:56:34.163Z","0.1.0":"2025-01-07T20:56:34.446Z","modified":"2025-01-07T20:56:34.709Z"},"maintainers":[{"name":"caelus-lib","email":"caelus.team@hotmail.com"}],"description":"A TypeScript implementation of a circular buffer, a data structure that uses a single, fixed-size buffer as if it were connected end-to-end.","homepage":"https://github.com/caelus-lab/caelus-dts-circular_buffer#readme","keywords":["circular buffer","ring buffer","data structure"],"repository":{"url":"git+https://github.com/caelus-lab/caelus-dts-circular_buffer.git"},"author":{"name":"Caelus"},"bugs":{"url":"https://github.com/caelus-lab/caelus-dts-circular_buffer/issues"},"license":"MIT","readme":"# CircularBuffer\r\n\r\nA TypeScript implementation of a circular buffer, a data structure that uses a single, fixed-size buffer as if it were\r\nconnected end-to-end.\r\n\r\n* **Circular Buffer Property:** The buffer does not automatically wrap around when it reaches its capacity. However, if\r\n  it is configured with `overwrite: true`, it reuses empty spaces at the start as older data is overwritten.\r\n\r\n## Installation\r\n\r\n- using `npm`\r\n\r\n```shell\r\nnpm install @caelus-dts/circular-buffer\r\n```\r\n\r\n- using `yarn`\r\n\r\n```shell\r\nyarn add @caelus-dts/circular-buffer\r\n```\r\n\r\n- using `pnpm`\r\n\r\n```shell\r\npnpm add @caelus-dts/circular-buffer\r\n```\r\n\r\n## Usage\r\n```ts\r\nimport CircularBuffer from '@caelus-dts/circular-buffer';\r\n\r\n// Create a new CircularBuffer with a capacity of 5\r\nconst buffer = new CircularBuffer<number>(5);\r\n\r\n// Write values to the buffer\r\nbuffer.write(1);\r\nbuffer.write(2);\r\nbuffer.writeAll([3, 4, 5]);\r\n\r\n// Read values from the buffer\r\nconsole.log(buffer.read()); // Output: 1\r\nconsole.log(buffer.read()); // Output: 2\r\n\r\n// Check buffer status\r\nconsole.log(buffer.isEmpty);   // Output: false\r\nconsole.log(buffer.isFull);    // Output: true\r\nconsole.log(buffer.capacity);  // Output: 5\r\nconsole.log(buffer.size);     // Output: 5\r\n\r\n// Convert buffer to array\r\nconst array = buffer.toArray(); // array = [1, 2, 3, 4, 5]. buffer is not modified\r\nconst array2 = buffer.toArray(true); // array2 = [1, 2, 3, 4, 5], buffer is cleared\r\nconsole.log(buffer.isEmpty); // Output: true\r\n\r\n// Or Clear the buffer using .clear()\r\nbuffer.clear();\r\nconsole.log(buffer.isEmpty); // Output: true\r\n\r\n\r\n\r\n// Create a CircularBuffer from an iterable\r\nconst bufferFromArray = CircularBuffer.from([6, 7, 8, 9, 10], 3, { overwrite: true });\r\nconsole.log(bufferFromArray.toArray()) // Output: [8, 9, 10]\r\n\r\n\r\n// Dumping elements from the buffer\r\nconst dumped = bufferFromArray.dump();\r\nconsole.log(dumped); // 8\r\nconsole.log(bufferFromArray.toArray()) // Output: [9, 10, undefined]\r\n\r\n// Resizing the buffer\r\nbufferFromArray.resize(8);\r\nconsole.log(bufferFromArray.capacity); // 8\r\n\r\n\r\n```\r\n\r\n## Configuration\r\n\r\nThe `CircularBuffer` constructor accepts an optional configuration object (`CBConfig`) with the following properties:\r\n\r\n* `overwrite` (default: `false`): If `true`, when the buffer is full, writing new values will overwrite the oldest values. If `false`, writing new values when the buffer is full has no effect, and a warning is printed to the console if `warnOnFull` is `true`.\r\n\r\n* `warnOnFull` (default: `true`): If `true`, a warning message will be printed to the console when attempting to write to a full buffer when the overwrite option is set to false.  This has no effect if `overwrite` is `true`.\r\n\r\n* `notifyOnOverwrite` (default: `false`): If `true`, and if the `overwrite` option is also `false `, a warning will be logged to the console whenever a value is overwritten.\r\n\r\n\r\n## Error Handling\r\n\r\nIf you attempt to resize the buffer to a smaller capacity without setting the `force` parameter to `true` in the `resize` method, a `BufferNewCapacityIsSmallerError` (BNCIS) will be thrown.\r\n\r\n\r\n## API Reference\r\n\r\n### Constructor\r\n\r\n```ts\r\nnew CircularBuffer<T>(capacity: number, config?: CBConfig);\r\n```\r\n\r\n\r\n*   `capacity`: The maximum number of elements the buffer can hold.\r\n*   `config`:  Optional configuration object (see Configuration section above).\r\n\r\n### Methods\r\n*   **`capacity`**: Returns the buffer's capacity.\r\n*   **`clear()`**: Clears the buffer.\r\n*   **`dump()`**: Removes and returns the next value from the buffer.\r\n*   **`from<O>(values: Iterable<O>, capacity: number, config?: CBConfig)`**: Static method creating a circular buffer from iterable values.\r\n*   **`isFull`**: Returns `true` if the buffer is full, `false` otherwise.\r\n*   **`isEmpty`**: Returns `true` if the buffer is empty, `false` otherwise.\r\n*   **`read()`**: Reads and returns the next value from the buffer. Returns `undefined` if the buffer is empty.\r\n*   **`resize(newCapacity: number, force?: boolean)`**: Resizes the buffer.\r\n*   **`size`**: Returns the current number of elements in the buffer.\r\n*   **`toArray(clear?: boolean)`**: Converts the buffer to an array.\r\n*   **`write(value: T)`**: Writes a value to the buffer.\r\n*   **`writeAll(values: Iterable<T>)`**: Writes multiple values to the buffer from an iterable.\r\n\r\n## Iterating\r\n\r\n`CircularBuffer` extends `IterableElement`, making it iterable. You can use for...of loops to iterate over the elements:\r\n\r\n```typescript\r\nfor (const value of buffer) {\r\n    console.log(value);\r\n}\r\n```\r\n\r\n## Contributing Guidelines\r\n\r\nContributions are welcome! Please fork the repository and submit a pull request.\r\n\r\n## License Information\r\n\r\n[MIT License](LICENSE)","readmeFilename":"README.md"}