feat(data-structures): stabilize Deque

async/unstable_channel.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2026 the Deno authors. MIT license.
 // This module is browser compatible.
 
-import { Deque } from "@std/data-structures/unstable-deque";
+import { Deque } from "@std/data-structures/deque";
 
 /** Internal node for the FIFO sender waiting queue. */
 interface SenderNode<T> {

data_structures/deno.json

@@ -8,9 +8,9 @@
     "./binary-search-tree": "./binary_search_tree.ts",
     "./unstable-binary-search-tree": "./unstable_binary_search_tree.ts",
     "./comparators": "./comparators.ts",
+    "./deque": "./deque.ts",
     "./red-black-tree": "./red_black_tree.ts",
     "./unstable-2d-array": "./unstable_2d_array.ts",
-    "./unstable-rolling-counter": "./unstable_rolling_counter.ts",
-    "./unstable-deque": "./unstable_deque.ts"
+    "./unstable-rolling-counter": "./unstable_rolling_counter.ts"
   }
 }

data_structures/unstable_deque.ts → data_structures/deque.ts

@@ -9,8 +9,6 @@ const MIN_SHRINK_CAPACITY = 64;
  * following the `ReadonlyArray` / `ReadonlyMap` / `ReadonlySet` pattern.
  * A `Deque<T>` is directly assignable to `ReadonlyDeque<T>`.
  *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
  * @typeParam T The type of the values stored in the deque.
  */
 export type ReadonlyDeque<T> = Pick<
@@ -65,11 +63,9 @@ function nextPowerOfTwo(n: number): number {
  * | toArray()     | O(n)         | O(n)        |
  * | Deque.from()  | O(n)         | O(n)        |
  *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
  * @example Usage
  * ```ts
- * import { Deque } from "@std/data-structures/unstable-deque";
+ * import { Deque } from "@std/data-structures/deque";
  * import { assertEquals } from "@std/assert";
  *
  * const deque = new Deque<number>();
@@ -95,11 +91,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Creates an empty deque, optionally populated from an iterable.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Creating an empty deque
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque<number>();
@@ -108,7 +102,7 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    *
    * @example Creating a deque from an iterable
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -167,11 +161,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * The number of elements in the deque.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Getting the length
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -187,11 +179,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Checks if the deque contains no elements.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Checking if the deque is empty
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque<number>();
@@ -210,11 +200,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Append one or more values to the back of the deque.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Pushing values to the back
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque<number>();
@@ -243,11 +231,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * in argument order, so `pushFront(1, 2, 3)` results in front-to-back order
    * `[1, 2, 3, ...existing]`.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Pushing values to the front
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([4, 5]);
@@ -276,11 +262,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Remove and return the back element, or `undefined` if the deque is empty.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Popping from the back
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -303,11 +287,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Remove and return the front element, or `undefined` if the deque is empty.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Popping from the front
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -332,11 +314,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * front to back. The gap is closed by shifting whichever side (front or back)
    * has fewer elements to move, so removals near either end are fast.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Removing the first even number
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3, 4]);
@@ -360,11 +340,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * `undefined` for out-of-range indices. The gap is closed by shifting
    * whichever side (front or back) has fewer elements to move.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Removing by index
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([10, 20, 30, 40]);
@@ -374,7 +352,7 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    *
    * @example Removing with a negative index
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([10, 20, 30, 40]);
@@ -395,11 +373,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * Return the first element matching the predicate, scanning from front to
    * back, without removing it. Returns `undefined` if no match is found.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Finding the first even number
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3, 4]);
@@ -421,11 +397,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * Return the index of the first element matching the predicate, scanning
    * from front to back. Returns `-1` if no match is found.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Finding the index of the first even number
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3, 4]);
@@ -445,11 +419,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * Return the front element without removing it, or `undefined` if the deque
    * is empty.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Peeking at the front
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -468,11 +440,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * Return the back element without removing it, or `undefined` if the deque
    * is empty.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Peeking at the back
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -492,11 +462,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * indices count from the back (`-1` is the last element). Returns `undefined`
    * for out-of-range indices.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Accessing elements by index
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([10, 20, 30, 40]);
@@ -519,11 +487,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * {@link https://tc39.es/ecma262/#sec-samevaluezero | SameValueZero}
    * comparison (like {@linkcode Array.prototype.includes}).
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Checking for membership
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -533,7 +499,7 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    *
    * @example NaN is found (SameValueZero semantics)
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, NaN, 3]);
@@ -555,11 +521,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Remove all elements and release the backing buffer.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Clearing the deque
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -581,11 +545,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * {@linkcode Array.prototype.filter}. The predicate is called once per
    * element in front-to-back order.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Retaining only odd numbers
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3, 4, 5]);
@@ -617,11 +579,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * Return a shallow copy of the deque's contents as an array, in
    * front-to-back order.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Converting to an array
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -641,11 +601,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Create a new deque from an array-like, iterable, or existing deque.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Creating a deque from an array
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = Deque.from([1, 2, 3]);
@@ -654,7 +612,7 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    *
    * @example Creating a deque from an existing deque
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const original = new Deque([1, 2, 3]);
@@ -673,11 +631,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * Create a new deque from an array-like, iterable, or existing deque, with
    * a mapping function applied to each element.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Creating a deque with a mapping function
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = Deque.from([1, 2, 3], { map: (v) => v * 10 });
@@ -756,11 +712,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    * Iterate over the deque's elements from front to back. Non-destructive
    * (unlike {@linkcode BinaryHeap}).
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Iterating over the deque
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -778,11 +732,9 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
   /**
    * Iterate over the deque's elements from back to front.
    *
-   * @experimental **UNSTABLE**: New API, yet to be vetted.
-   *
    * @example Iterating in reverse
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque([1, 2, 3]);
@@ -802,7 +754,7 @@ export class Deque<T> implements Iterable<T>, ReadonlyDeque<T> {
    *
    * @example Usage
    * ```ts
-   * import { Deque } from "@std/data-structures/unstable-deque";
+   * import { Deque } from "@std/data-structures/deque";
    * import { assertEquals } from "@std/assert";
    *
    * const deque = new Deque<number>();

data_structures/unstable_deque_test.ts → data_structures/deque_test.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2026 the Deno authors. MIT license.
 
 import { assertEquals, assertStrictEquals, assertThrows } from "@std/assert";
-import { Deque, type ReadonlyDeque } from "./unstable_deque.ts";
+import { Deque, type ReadonlyDeque } from "./deque.ts";
 import { MyMath } from "./_test_utils.ts";
 
 // -- Construction --

data_structures/mod.ts

@@ -28,4 +28,5 @@
 export * from "./binary_heap.ts";
 export * from "./binary_search_tree.ts";
 export * from "./comparators.ts";
+export * from "./deque.ts";
 export * from "./red_black_tree.ts";