Merge pull request #1 from sentrychris/develop

v0.2.1

README.md

@@ -2,7 +2,12 @@
 
 ![CI Tests](https://github.com/sentrychris/circle-buffer/actions/workflows/tests.yml/badge.svg)
 
-A simple circular array buffer for efficient management of string data in JavaScript/TypeScript.
+A simple circular array buffer (also known as a ring buffer) for efficient management of string data in JavaScript/TypeScript.
+
+This simple module is designed to manage a fixed-size buffer efficiently, with the ability to 
+overwrite old data with new data as it arrives. This is useful in scenarios where memory usage 
+needs to be constant and predictable, such as in real-time data processing, streaming applications, 
+or when handling continuous data streams like logs, sensor data, or network packets.
 
 ## Installation
 
@@ -22,21 +27,29 @@ const buffer = new CircularBuffer({ limit: 5 });
 buffer.forward('A');
 buffer.forward('B');
 buffer.forward('C');
+buffer.forward('D');
+buffer.forward('E');
 
 // Get the current state of the buffer
-console.log(buffer.get()); // Output: 'ABC'
+buffer.current(); // Output: 'ABCDE'
 
 // Rewind the buffer
 buffer.rewind();
 
 // Get the updated buffer state
-console.log(buffer.get()); // Output: 'AB'
+buffer.current(); // Output: 'ABCD'
+
+// Get the buffer value at the specified position using index
+buffer.get(1); // Output: 'B'
+
+// Get the buffer value at the specified range using index and length
+buffer.range(0,2); // Output: 'AB'
 
 // Reset the buffer
 buffer.reset();
 
 // Get the buffer state after reset
-console.log(buffer.get()); // Output: ''
+buffer.current(); // Output: ''
 ```
 
 ## API
@@ -53,13 +66,24 @@ console.log(buffer.get()); // Output: ''
 
 #### Methods
 
-- `get(): string`
+- `current(): string`
+
+  Returns the current state of the buffer.
+
+- `get(index: number): string`
+
+  Returns the content at the specific position in the buffer.
+  - `index`: The index position in the buffer.
+
+- `range(start: number, length: number): string`
 
-  Returns a string representation of the current state of the circular buffer.
+  Returns the content at the specific range in the buffer.
+  - `start`: The starting position in the buffer.
+  - `length`: The length of the range to fetch.
 
 - `reset(): void`
 
-  Resets the circular buffer by filling it with empty strings.
+  Resets the buffer by filling it with empty strings.
 
 - `forward(value: string): void`
 

dist/CircularBuffer.d.ts

@@ -1,42 +1,74 @@
 /** @public */
 export declare class CircularBuffer {
     /**
-     * The buffer
+     * The buffer.
      */
     private buffer;
+
     /**
-     * The buffer limit
+     * The buffer size limit.
      */
     private limit;
+
     /**
-     * Create a new circular buffer
+     * Create a new circular buffer.
      *
-     * @param limit - the buffer size limit
-     * @throws if the provided limit is not a positive integer
+     * @param limit - the buffer size limit.
+     * @throws if the provided limit is not a positive integer.
      */
     constructor({ limit }: {
         limit: number;
     });
+
     /**
-     * Get the current state of the buffer
+     * Get the current state of the buffer.
+     *
+     * @returns the contents of the buffer.
      */
-    get(): string;
+    current(): string;
+
     /**
-     * Reset the buffer, fill it with empty strings
+     * Get the content at the specific position in the buffer.
+     *
+     * @param index - the position in the buffer.
+     * @returns the content at the specified position.
+     * @throws if the index is out of bounds.
+     */
+    get(index: number): string;
+
+    /**
+     * Get the content within a specific range in the buffer.
+     *
+     * @param start - the starting position of the range.
+     * @param len - the length of the range (exclusive).
+     * @returns the content within the specified range.
+     * @throws if the start or len indices are out of bounds.
+     */
+    range(start: number, len: number): string;
+
+    /**
+     * Reset the buffer, fill it with empty strings.
+     *
+     * @returns no return value.
      */
     reset(): void;
+
     /**
-     * Move the buffer forward by one position and add
-     * the provided value at the end of the buffer, if
-     * the buffer is full, the oldest value is removed
+     * Move the buffer forward by one position and add the provided
+     * value at the end of the buffer, if the buffer is full, the
+     * oldest value is removed.
      *
-     * @param value - the value to add to the buffer
+     * @param value - the value to add to the buffer.
+     * @returns no return value.
      */
     forward(value: string): void;
+
     /**
-     * Move the buffer backward by one position, removing
-     * the last value, if the buffer becomes empty, an empty
-     * string is added at the beginning
+     * Move the buffer backward by one position, removing the last
+     * value, if the buffer becomes empty, an empty string is added
+     * at the beginning.
+     *
+     * @returns no return value.
      */
     rewind(): void;
 }