Added ring buffer.

Author: uhop

ARCHITECTURE.md

@@ -50,6 +50,7 @@ src/                      # All source code (ESM)
 ├── queue.js              # Queue — adapter class wrapping a ValueList
 ├── stack.js              # Stack — adapter class wrapping a ValueList
 ├── deque.js              # Deque — double-ended adapter wrapping a ValueList
+├── ring-buffer.js        # RingBuffer — array-backed deque on a circular buffer
 ├── skip-list.js          # SkipList — probabilistic ordered container
 ├── list-utils.js         # Utility functions: push/append values, find, remove
 ├── list-helpers.js       # Node/range normalization helpers

README.md

@@ -13,6 +13,7 @@ Data structures included:
 - **Heaps** — min heap, leftist heap, skew heap, pairing heap (O(1) push/merge, decrease-key by handle), indexed heap (O(1) membership, update/remove by handle).
 - **Caches** — LRU, LFU, FIFO, random eviction. Includes a decorator for functions, methods, and getters.
 - **Queue, Stack, and Deque** — list-backed adapters; the deque adds O(1) both-end operations and `rotate()`.
+- **Ring buffer** — array-backed deque on a circular buffer: fastest raw throughput, O(1) random access, optional keep-last-N bounded mode.
 - **Splay tree** — self-adjusting binary search tree.
 - **Skip list** — probabilistic ordered container: expected O(log n) search/insert/remove, floor/ceil, ordered and range iteration.
 - **Utilities** — push/append values, find, remove, validate, and more.

bench/bench-queues.js

@@ -0,0 +1,46 @@
+import Deque from '../src/deque.js';
+import RingBuffer from '../src/ring-buffer.js';
+
+const SIZE = 1_000,
+  CYCLES = 10_000,
+  data = Array.from({length: SIZE}, (_, i) => i);
+
+// all three share push (back) / shift (front) names
+const churn = makeContainer => n => {
+  let container;
+  for (let i = 0; i < n; ++i) {
+    container = makeContainer();
+    for (let j = 0; j < CYCLES; ++j) {
+      container.push(j);
+      container.shift();
+    }
+  }
+  return container;
+};
+
+const fillDrain = makeContainer => n => {
+  let container;
+  for (let i = 0; i < n; ++i) {
+    container = makeContainer();
+    for (let j = 0; j < CYCLES; ++j) container.push(j);
+    while (container.length || container.size) container.shift();
+  }
+  return container;
+};
+
+const makeArray = () => data.slice(),
+  makeDeque = () => {
+    const deque = new Deque();
+    deque.pushValuesBack(data);
+    return deque;
+  },
+  makeRing = () => RingBuffer.from(data);
+
+export default {
+  'churn 1k: Array': churn(makeArray),
+  'churn 1k: Deque (list)': churn(makeDeque),
+  'churn 1k: RingBuffer': churn(makeRing),
+  'fill+drain 10k: Array': fillDrain(() => []),
+  'fill+drain 10k: Deque (list)': fillDrain(() => new Deque()),
+  'fill+drain 10k: RingBuffer': fillDrain(() => new RingBuffer())
+};

llms-full.txt

@@ -665,6 +665,54 @@ Accepts a list instance (adopted) or a list class (instantiated). The list must
 
 ---
 
+## Module: RingBuffer (`list-toolkit/ring-buffer.js`)
+
+Array-backed double-ended queue on a circular buffer — contiguous, O(1) at both ends, O(1) random access, no allocation at steady state. Shares the Deque API (drop-in replacements for each other); measured ~5× faster than Array/list-deque on steady-state queue churn.
+
+```js
+import RingBuffer from 'list-toolkit/ring-buffer.js';
+
+const queue = new RingBuffer();
+queue.push(1).push(2);
+queue.shift(); // 1 — Array-parity names without Array.shift's O(n)
+
+const lastFive = new RingBuffer({capacity: 5}); // bounded: keeps the last 5 pushed
+```
+
+### Constructor
+
+```js
+new RingBuffer({capacity?, initialCapacity?} = {})
+```
+
+`capacity` — hard bound: pushing onto a full buffer evicts from the opposite end (keep-last-N). Omit for a growable buffer. `initialCapacity` — allocation hint (default 16, rounded to a power of two).
+
+### Properties
+
+- `isEmpty` — true if empty.
+- `isFull` — true when a bounded buffer reached capacity.
+- `size` — number of elements.
+- `capacity` — the bound, or Infinity when growable.
+- `front` / `back` — first/last element value.
+
+### Methods
+
+- `peekFront()` / `peekBack()` — first/last value.
+- `at(index)` — O(1) random access; negative counts from the back (like `Array#at`).
+- `pushFront(value)` — add to front (evicts back when bounded+full). Aliases: `unshift`, `addFront`.
+- `pushBack(value)` — add to back (evicts front when bounded+full). Aliases: `push`, `add`, `addBack`.
+- `popFront()` — remove from front. Aliases: `shift`, `removeFront`.
+- `popBack()` — remove from back. Aliases: `pop`, `removeBack`.
+- `pushValuesFront(values)` / `pushValuesBack(values)` — bulk adds.
+- `rotate(n = 1)` — Python `deque.rotate` semantics; O(1) when the ring is physically full, else ≤ size/2 moves.
+- `clear()` — remove all (keeps the allocation, releases references).
+- `[Symbol.iterator]()` / `getReverseIterator()` — iterate front-to-back / back-to-front.
+- `RingBuffer.from(values, options?)` — create from an iterable.
+
+Popped slots are cleared, so the ring never pins dead references. Choose the list-backed `Deque` when stable node identity matters; choose `RingBuffer` for throughput.
+
+---
+
 ## Module: SplayTree (`list-toolkit/tree/splay-tree.js`)
 
 Self-adjusting binary search tree. Frequently accessed elements move to the root.

llms.txt

@@ -76,6 +76,7 @@ All heaps support `less` or `compare` for ordering. Common API: `push(value)`, `
 - **Queue** (`list-toolkit/queue.js`) — FIFO queue adapter. Methods: `add`/`push`/`enqueue`, `remove`/`pop`/`dequeue`, `peek`, `top`, `clear`.
 - **Stack** (`list-toolkit/stack.js`) — LIFO stack adapter. Methods: `push`, `pop`, `peek`, `top`, `clear`.
 - **Deque** (`list-toolkit/deque.js`) — double-ended queue adapter. Methods: `pushFront`/`unshift`, `pushBack`/`push`, `popFront`/`shift`, `popBack`/`pop`, `peekFront`/`peekBack`, `rotate(n)`, `clear`. O(1) at both ends.
+- **RingBuffer** (`list-toolkit/ring-buffer.js`) — array-backed deque on a circular buffer, same API as Deque plus `at(index)` (O(1) random access) and optional `{capacity}` bounded keep-last-N mode. Fastest queue/deque for raw throughput.
 
 ### Trees
 

src/ring-buffer.d.ts

@@ -0,0 +1,165 @@
+/** Options for configuring a ring buffer. */
+export interface RingBufferOptions {
+  /** Hard bound: pushing onto a full buffer evicts from the opposite end (keep-last-N semantics). Omit for an unbounded, growable buffer. */
+  capacity?: number;
+  /** Initial slot allocation hint for the growable mode (default 16; rounded up to a power of two). */
+  initialCapacity?: number;
+}
+
+/**
+ * Array-backed double-ended queue on a circular buffer: contiguous storage,
+ * O(1) push/pop/peek at both ends, O(1) random access via `at()`, and no
+ * allocation at steady state. Shares the `Deque` API (including the Array-parity
+ * aliases `push`/`pop`/`shift`/`unshift`), so the two are drop-in replacements
+ * for each other; the list-backed `Deque` keeps stable node identity, the ring
+ * buffer wins on throughput and memory locality.
+ *
+ * With `{capacity}` the buffer is bounded: pushing onto a full buffer evicts the
+ * element at the opposite end — a "keep the last N" sliding window.
+ */
+export class RingBuffer<V = unknown> {
+  /** Hard bound, or `Infinity` when growable. */
+  capacity: number;
+  /** The backing array (a power-of-two ring). */
+  array: (V | undefined)[];
+  /** Index of the front element in `array`. */
+  head: number;
+  /** Number of elements. */
+  size: number;
+
+  /** @param options - Capacity semantics. */
+  constructor(options?: RingBufferOptions);
+
+  /** Whether the buffer has no elements. */
+  get isEmpty(): boolean;
+
+  /** Whether the buffer reached its `capacity` (always `false` when growable). */
+  get isFull(): boolean;
+
+  /** The front element without removing it, or `undefined` if empty. */
+  get front(): V | undefined;
+
+  /** The back element without removing it, or `undefined` if empty. */
+  get back(): V | undefined;
+
+  /** The front element without removing it, or `undefined` if empty. */
+  peekFront(): V | undefined;
+
+  /** The back element without removing it, or `undefined` if empty. */
+  peekBack(): V | undefined;
+
+  /**
+   * Random access by position in O(1). Negative indices count from the back
+   * (like `Array.prototype.at`).
+   * @param index - Position from the front (or from the back when negative).
+   * @returns The element, or `undefined` when out of range.
+   */
+  at(index: number): V | undefined;
+
+  /**
+   * Add a value to the front. Evicts the back element when bounded and full.
+   * @param value - Value to add.
+   * @returns `this` for chaining.
+   */
+  pushFront(value: V): this;
+
+  /** Alias for {@link pushFront}. */
+  unshift(value: V): this;
+
+  /** Alias for {@link pushFront}. */
+  addFront(value: V): this;
+
+  /**
+   * Add a value to the back. Evicts the front element when bounded and full.
+   * @param value - Value to add.
+   * @returns `this` for chaining.
+   */
+  pushBack(value: V): this;
+
+  /** Alias for {@link pushBack}. */
+  push(value: V): this;
+
+  /** Alias for {@link pushBack}. */
+  add(value: V): this;
+
+  /** Alias for {@link pushBack}. */
+  addBack(value: V): this;
+
+  /**
+   * Remove and return the front value.
+   * @returns The front value, or `undefined` if empty.
+   */
+  popFront(): V | undefined;
+
+  /** Alias for {@link popFront}. */
+  shift(): V | undefined;
+
+  /** Alias for {@link popFront}. */
+  removeFront(): V | undefined;
+
+  /**
+   * Remove and return the back value.
+   * @returns The back value, or `undefined` if empty.
+   */
+  popBack(): V | undefined;
+
+  /** Alias for {@link popBack}. */
+  pop(): V | undefined;
+
+  /** Alias for {@link popBack}. */
+  removeBack(): V | undefined;
+
+  /**
+   * Add multiple values to the front (in iteration order, so they end up reversed).
+   * @param values - Iterable of values.
+   * @returns `this` for chaining.
+   */
+  pushValuesFront(values: Iterable<V>): this;
+
+  /**
+   * Add multiple values to the back.
+   * @param values - Iterable of values.
+   * @returns `this` for chaining.
+   */
+  pushValuesBack(values: Iterable<V>): this;
+
+  /**
+   * Rotate: positive `n` moves `n` elements from the back to the front (Python
+   * `deque.rotate` semantics), negative from the front to the back. O(1) when the
+   * ring is physically full (a head shift), otherwise at most `size / 2` moves.
+   * @param n - Number of positions (default 1).
+   * @returns `this` for chaining.
+   */
+  rotate(n?: number): this;
+
+  /**
+   * Remove all elements (keeps the current allocation).
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /**
+   * Grow the backing array (doubling). Called automatically; exposed for pre-sizing.
+   * @returns `this` for chaining.
+   */
+  grow(): this;
+
+  /** Iterate over values from front to back. */
+  [Symbol.iterator](): IterableIterator<V>;
+
+  /**
+   * Iterate over values from back to front.
+   * @returns An iterable of values.
+   */
+  getReverseIterator(): Iterable<V>;
+
+  /**
+   * Build a RingBuffer from an iterable.
+   * @param values - Values to add at the back.
+   * @param options - Capacity semantics.
+   * @returns A new RingBuffer.
+   */
+  static from<V = unknown>(values: Iterable<V>, options?: RingBufferOptions): RingBuffer<V>;
+}
+
+export default RingBuffer;