evnty/build/ring-buffer.d.ts

Async-first, reactive event handling library for complex event flows in browser and Node.js

/**
 * @internal Fixed-size circular buffer that grows in powers of two when full.
 * Provides O(1) push/pop/shift/unshift and supports wrap-around iteration.
 */
export declare class RingBuffer<T> {
    #private;
    readonly [Symbol.toStringTag] = "RingBuffer";
    /**
     * Creates a RingBuffer from an array of values.
     * @param values - The values to initialize the buffer with
     * @returns A new RingBuffer containing the values
     */
    static from<T>(values: T[]): RingBuffer<T>;
    /**
     * Creates a ring buffer with at least the requested capacity (rounded up to power of two).
     */
    constructor(capacity?: number);
    /**
     * The number of items currently in the buffer.
     */
    get length(): number;
    /**
     * Logical position of the buffer's left edge (total items ever shifted).
     * Monotonically increasing - useful for cursor-based consumers.
     */
    get left(): number;
    /**
     * Logical position of the buffer's right edge (left + length).
     * Represents the next logical index for push.
     */
    get right(): number;
    /**
     * Returns true if the buffer has wrapped around (head > tail).
     */
    isWrapped(): boolean;
    /**
     * Returns true if the buffer contains no items.
     */
    isEmpty(): boolean;
    /**
     * Ensures the underlying storage can hold at least `capacity` items.
     * Preserves existing order when the buffer is wrapped.
     */
    grow(capacity?: number): void;
    /**
     * Appends a value at the tail, growing if full.
     */
    push(value: T): this;
    /**
     * Inserts a value at the head, growing if full.
     */
    unshift(value: T): this;
    /**
     * Returns the value at the given index without removing it.
     * Index 0 is the head, index length-1 is the tail.
     */
    peek(index: number): T | undefined;
    /**
     * Returns the value at the given logical index without removing it.
     * Logical index is based on total push/shift history (cursor-friendly).
     */
    peekAt(logicalIndex: number): T | undefined;
    /**
     * Removes and returns the value at the head, or undefined if empty.
     */
    shift(): T | undefined;
    /**
     * Removes n values from the head.
     */
    shiftN(n: number): number;
    /**
     * Removes and returns the value at the tail, or undefined if empty.
     */
    pop(): T | undefined;
    /**
     * Clears all entries. Optionally keeps current capacity instead of resetting to default.
     */
    clear(preserveCapacity?: boolean): this;
    [Symbol.iterator](): Iterator<T, void, unknown>;
}