lifecycle-utils/dist/Queue.d.ts

A set of general utilities for the lifecycle of a JS/TS project/library

export type QueueOptions = {
    /**
     * Minimum number of consumed entries before the internal array can be compacted.
     *
     * Compaction only occurs when at least half of the backing array has been consumed.
     *
     * Defaults to `4096`.
     */
    compactAt?: number;
};
/**
 * An efficient queue implementation that allows you to enqueue and dequeue items in `O(1)` time complexity.
 *
 * ```typescript
 * import {Queue} from "lifecycle-utils";
 *
 * const queue = new Queue([1, 2, 3]);
 *
 * queue.push(4);
 * console.log(queue.shift()); // 1
 *
 * console.log(queue.first); // 2
 * console.log(queue.last); // 4
 * console.log(queue.length); // 3
 * console.log([...queue]); // [2, 3, 4]
 * ```
 */
export declare class Queue<const T> implements Iterable<T> {
    /**
     * Creates a new queue.
     *
     * **Time complexity:** `O(n)` with initial values, or `O(1)` without them.
     */
    constructor(values?: Iterable<T>, options?: QueueOptions);
    /**
     * The number of values in the queue.
     *
     * **Time complexity:** `O(1)`.
     */
    get length(): number;
    /**
     * Whether the queue is empty.
     *
     * **Time complexity:** `O(1)`.
     */
    get isEmpty(): boolean;
    /**
     * The first (next) value in the queue, or `undefined` when the queue is empty.
     *
     * **Time complexity:** `O(1)`.
     */
    get first(): T | undefined;
    /**
     * The last value in the queue, or `undefined` when the queue is empty.
     *
     * **Time complexity:** `O(1)`.
     */
    get last(): T | undefined;
    /**
     * Adds a value to the end of the queue.
     *
     * **Time complexity:** `O(1)` amortized.
     */
    push(item: T): void;
    /**
     * Removes and returns the first (next) value in the queue.
     *
     * Returns `undefined` when the queue is empty.
     *
     * **Time complexity:** `O(1)` amortized, with occasional `O(n)` compaction.
     */
    shift(): T | undefined;
    /**
     * Returns the value at the given index without removing it.
     *
     * Negative indexes count backwards from the end of the queue.
     *
     * **Time complexity:** `O(1)`.
     */
    at(index: number): T | undefined;
    /**
     * Deletes values from the queue starting at `start` and ending before `end`.
     *
     * When `end` is omitted, only the value at `start` is deleted.
     * Negative indexes count backwards from the end of the queue.
     *
     * Returns the number of deleted values.
     *
     * **Time complexity:** `O(k)` when deleting from either end, where `k` is the number of deleted values,
     * and `O(n)` when deleting from the middle.
     */
    delete(start: number, end?: number): number;
    /**
     * Returns the index of the first occurrence of a value in the queue, or `-1` when it is not found.
     *
     * **Time complexity:** `O(n)`.
     */
    indexOf(item: T, fromIndex?: number): number;
    /**
     * Returns the index of the last occurrence of a value in the queue, or `-1` when it is not found.
     *
     * **Time complexity:** `O(n)`.
     */
    lastIndexOf(item: T, fromIndex?: number): number;
    /**
     * Returns an iterator over index-value pairs in the queue.
     *
     * **Time complexity:** `O(n)` for a full iteration and `O(1)` per value.
     */
    entries(): IterableIterator<[number, T]>;
    /**
     * Returns an iterator over the values in the queue from first to last.
     *
     * **Time complexity:** `O(n)` for a full iteration and `O(1)` per value.
     */
    values(): IterableIterator<T>;
    /**
     * Returns the queue values as a new array.
     *
     * **Time complexity:** `O(n)`.
     */
    toArray(): T[];
    /**
     * Removes all values from the queue.
     *
     * **Time complexity:** `O(1)`.
     */
    clear(): void;
    /**
     * Returns an iterator over the values in the queue from first to last.
     *
     * **Time complexity:** `O(1)` to create the iterator, and `O(n)` for a full iteration.
     */
    [Symbol.iterator](): IterableIterator<T>;
}
//# sourceMappingURL=Queue.d.ts.map