lifecycle-utils
    Preparing search index...

    Class AsyncQueue<T>

    An async queue that allows you to wait for items to become available when the queue is empty.

    shift retrieves the first locally queued item, falling back to queues in the parent chain (if a parent is set). If no item is available, it waits until one is pushed.

    When waiting, the request is registered with the current queue and all parent queues, and the first one to provide an item satisfies the request.

    Pushing adds the item to the current queue, unless forwardPushesToParent is enabled.

    import {AsyncQueue} from "lifecycle-utils";

    const queue = new AsyncQueue([1]);

    queue.push(2);
    console.log(await queue.shift()); // 1
    console.log(await queue.shift()); // 2

    setTimeout(() => queue.push(3), 100);

    console.log(await queue.shift()); // 3

    import {AsyncQueue, sleep} from "lifecycle-utils";

    const queue = new AsyncQueue([1, 2]);
    const child = new AsyncQueue([9], {parent: queue});

    console.log(queue.length); // 2
    console.log(child.length); // 1

    await Promise.all([
        child.withItem(async (item) => {
            console.log(item); // 9
            await sleep(1000);
        }),
        child.withItem(async (item) => {
            console.log(item); // 1
            await sleep(1000);
        })
    ]);
    console.log(queue.length); // 1 - [2]
    console.log(child.length); // 2 - [9, 1]


    const childPromise = child.withItem(async (item) => {
        console.log(item); // 9
        await sleep(1000);
    });

    // drain the child and route returned items to the parent
    child.drainToParent();
    child.forwardPushesToParent = true;
    console.log(queue.length); // 2 - [2, 1]
    console.log(child.length); // 0

    await childPromise;
    console.log(queue.length); // 3 - [2, 1, 9]
    console.log(child.length); // 0

    Type Parameters

    • T

    Implements

    Index

    Constructors

    constructor

    Accessors

    first forwardPushesToParent isEmpty last length parent pendingRequests

    Methods

    [iterator] acquire at clear delete dequeue drainToParent enqueue entries indexOf lastIndexOf peek push rejectPendingRequests shift toArray tryDequeue tryShift values withItem

    Constructors

    Accessors

    • get first(): T | undefined

      The first (next) item in the queue, or undefined when the queue is empty.

      Time complexity: O(1).

      Returns T | undefined

    • get forwardPushesToParent(): boolean

      Whether to route pushes to the parent queue.

      Only relevant when a parent queue is set.

      Returns boolean

    • set forwardPushesToParent(value: boolean): void

      Set whether to route pushes to the parent queue.

      Can only be set when a parent queue is set.

      Parameters

      • value: boolean

      Returns void

    • get isEmpty(): boolean

      Whether the queue is empty.

      Time complexity: O(1).

      Returns boolean

    • get last(): T | undefined

      The last item in the queue, or undefined when the queue is empty.

      Time complexity: O(1).

      Returns T | undefined

    • get length(): number

      The number of values currently in the queue.

      Time complexity: O(1).

      Returns number

    • get pendingRequests(): number

      The number of pending requests waiting for values to be added to the queue.

      Time complexity: O(1).

      Returns number

    Methods

    • 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.

      Returns IterableIterator<T>

    • Get the next item in the queue, waiting for one to be added if the queue is empty.

      The item is wrapped in an AsyncQueueItemLease, which enqueues the item again when disposed.

      Time complexity: O(1) amortized, with occasional O(n) compaction. Cancelling a pending request is O(n).

      Parameters

      • Optionalsignal: AbortSignal

      Returns Promise<AsyncQueueItemLease<T>>

      import {AsyncQueue} from "lifecycle-utils";
      const queue = new AsyncQueue<number>([42]);

      {
          using lease = await queue.acquire();
          console.log(lease.item); // 42
          console.log(queue.length); // 0
      }

      console.log(queue.length); // 1

    • Returns the item at the given index without removing it.

      Negative indexes count backwards from the end of the queue.

      Time complexity: O(1).

      Parameters

      • index: number

      Returns T | undefined

    • Removes all values from the queue.

      Time complexity: O(1).

      Returns void

    • 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.

      Parameters

      • start: number
      • Optionalend: number

      Returns number

    • Alias to shift.

      Time complexity: O(1) amortized without a parent, with occasional O(n) compaction. Cancelling a pending request is O(n). O(h) to traverse the parent chain.

      Parameters

      • Optionalsignal: AbortSignal

      Returns Promise<T>

    • If a parent queue is set, moves all items from the current queue to it.

      Time complexity: O(n).

      Returns void

    • Alias to push.

      Time complexity: O(1) amortized. O(h) to traverse the parent chain.

      Parameters

      • item: T

      Returns void

    • Returns an iterator over index-value pairs in the queue.

      Time complexity: O(n) for a full iteration and O(1) per value.

      Returns IterableIterator<[number, T]>

    • Returns the index of the first occurrence of a value in the queue, or -1 when it is not found.

      Time complexity: O(n).

      Parameters

      • item: T
      • fromIndex: number = 0

      Returns 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).

      Parameters

      • item: T
      • OptionalfromIndex: number

      Returns number

    • The first (next) item in the queue, or undefined when the queue is empty (alias to first).

      Time complexity: O(1).

      Returns T | undefined

    • Adds an item to the end of the queue. If there is a pending request, the item is immediately delivered to the oldest pending request instead of being added to the queue.

      Time complexity: O(1) amortized. O(h) to traverse the parent chain.

      Parameters

      • item: T

      Returns void

    • Reject all the pending requests with the given reason.

      Time complexity: O(n), where n is the number of pending requests.

      Parameters

      • Optionalreason: unknown

      Returns void

    • Removes and returns the first (next) item in the queue, and if the queue is empty, waits for an item to be added first and then returns that item.

      Time complexity: O(1) amortized without a parent, with occasional O(n) compaction. Cancelling a pending request is O(n). O(h) to traverse the parent chain.

      Parameters

      • Optionalsignal: AbortSignal

      Returns Promise<T>

    • Returns the queue values as a new array.

      Time complexity: O(n).

      Returns T[]

    • Alias to tryShift.

      Time complexity: O(1) amortized without a parent, with occasional O(n) compaction. O(h) to traverse the parent chain.

      Returns T | undefined

    • Removes and returns the first (next) value in the queue without waiting for an item to be added if the queue is empty.

      Returns undefined when the queue is empty.

      Time complexity: O(1) amortized without a parent, with occasional O(n) compaction. O(h) to traverse the parent chain.

      Returns T | undefined

    • 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.

      Returns IterableIterator<T>

    • Run a callback with the next item in the queue, and if the queue is empty, wait for an item to be added first and then run the callback with that item.

      When the callback is done, the item is enqueued again.

      The return value of the callback is returned to the caller.

      Time complexity: O(1) amortized, with occasional O(n) compaction. Cancelling a pending request is O(n).

      Type Parameters

      • R

      Parameters

      • callback: (item: T) => R | PromiseLike<R>

      Returns Promise<R>

    • Run a callback with the next item in the queue, and if the queue is empty, wait for an item to be added first and then run the callback with that item.

      When the callback is done, the item is enqueued again.

      The return value of the callback is returned to the caller.

      Time complexity: O(1) amortized, with occasional O(n) compaction. Cancelling a pending request is O(n).

      Type Parameters

      • R

      Parameters

      • signal: AbortSignal | undefined
      • callback: (item: T) => R | PromiseLike<R>

      Returns Promise<R>

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods