@se-oss/circular-buffer/dist/index.d.ts

Circular Buffer implementation for JavaScript

declare class CircularBuffer<T = number> {
    private readonly buffer;
    private readonly capacity;
    private filled;
    private writeIndex;
    /**
     * CircularBuffer stores up to `capacity` elements in a FIFO manner.
     * Internally uses an array of length `capacity`, overwriting oldest values when full.
     * @template T Type of items stored (defaults to `number`).
     * @param capacity Total slots in the buffer (must be >= 2).
     * @throws {Error} If capacity is less than 2.
     *
     * @example
     * ```ts
     * // Create a buffer for 5 numbers
     * const buf = new CircularBuffer<number>(5);
     * buf.put(10);
     * buf.put(20);
     * console.log(buf.size()); // 2
     * ```
     */
    constructor(capacity: number);
    /**
     * Check whether the buffer has no elements.
     * @returns `true` if empty, `false` otherwise.
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<string>(3);
     * console.log(buf.isEmpty()); // true
     * buf.put('a');
     * console.log(buf.isEmpty()); // false
     * ```
     */
    isEmpty(): boolean;
    /**
     * Check whether the buffer has wrapped around and is full.
     * @returns `true` if full, `false` otherwise.
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<number>(3);
     * buf.put(1).put(2).put(3);
     * console.log(buf.isFull()); // true
     * ```
     */
    isFull(): boolean;
    /**
     * Insert a value at the next write position. Overwrites oldest if buffer was full.
     * @param val Item to store.
     * @returns The buffer instance (chainable).
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<number>(3);
     * buf.put(1).put(2).put(3);
     * console.log(buf.toArray()); // [1, 2, 3]
     * buf.put(4);
     * console.log(buf.toArray()); // [2, 3, 4] // 1 overwritten
     * ```
     */
    put(val: T): this;
    /**
     * Insert a value at an arbitrary index relative to the start of stored data.
     * @param val Item to store.
     * @param index Index within current data (supports negative indexing).
     * @returns The buffer instance (chainable).
     * @throws {Error} If index is out of bounds.
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<string>(4);
     * buf.put('a').put('b').put('c');
     * buf.putAt('x', 1);
     * console.log(buf.toArray()); // ['a', 'x', 'c']
     * ```
     */
    putAt(val: T, index: number): this;
    /**
     * Remove all contents, resetting to empty state.
     * @returns The buffer instance (chainable).
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<number>(3);
     * buf.put(1).put(2);
     * buf.clear();
     * console.log(buf.isEmpty()); // true
     * ```
     */
    clear(): this;
    /**
     * Number of elements currently stored in FIFO order.
     * @returns Count between `0` and `capacity`.
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer(3);
     * buf.put(1);
     * console.log(buf.size()); // 1
     * ```
     */
    size(): number;
    /**
     * Access stored item by index (supports negative indexing).
     * @param index Index within current data.
     * @returns Item at that position.
     * @throws {Error} If index is out of bounds.
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<string>(3);
     * buf.put('one').put('two');
     * console.log(buf.at(0));  // 'one'
     * console.log(buf.at(-1)); // 'two'
     * ```
     */
    at(index: number): T;
    [Symbol.iterator](): IterableIterator<T>;
    private iterator;
    /**
     * Execute a callback for each element in FIFO order.
     * @param callback Called with (value, index) for each stored item.
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<number>(3);
     * buf.put(10).put(20);
     * buf.forEach((v, i) => console.log(i, v));
     * // Logs: 0 10 \n 1 20
     * ```
     */
    forEach(callback: (data: T, index: number) => void): void;
    /**
     * Convert buffer contents to a linear array in FIFO order.
     * @returns New array of stored items.
     *
     * @example
     * ```ts
     * const buf = new CircularBuffer<number>(3);
     * buf.put(5).put(6).put(7);
     * console.log(buf.toArray()); // [5, 6, 7]
     * ```
     */
    toArray(): T[];
    private relativeIndex;
}

export { CircularBuffer };