rotatable-array

Three tiny, zero‑dependency circular rotators for TypeScript / JavaScript:

• RotatableArray<T>: an immutable, non‑empty round‑robin view over a backing array.
• RotatableMutatableArray<T>: a mutable, non-empty round-robin array with add/remove.
• RotatableSet<T>: a mutable, unique‑item round‑robin set with O(1) add/remove/next.

---

Install

npm i rotatable-array

---

Quick Start

import { RotatableMutatableArray, RotatableArray, RotatableSet } from "rotatable-array";

const rot = new RotatableArray(["A", "B", "C"]);
console.log(rot.next());      // A
console.log(rot.peek(1));     // B
console.log(rot.next());      // B
console.log(rot.previous());  // B
console.log(rot.move(1));     // C

const mut = new RotatableMutatableArray(["A", "B"]);
mut.add("C");
mut.removeAt(1);
console.log(mut.next());      // A

const set = new RotatableSet([1, 2, 3]);
set.addToFurthest(4);          // Set-style append (unique, returns this)
set.addToFurthest(4);          // no-op for duplicates
console.log(set.getFurthestItem()); // 4
console.log(set.getFurthestItem(1)); // 3
console.log(set.next());      // 1

Iteration

for (const x of rot)      // infinite round-robin
  console.log(x);

for (const x of rot.cycle())  // one full pass then stops
  console.log(x);

for (const x of set)      // infinite round-robin (like rot)
  console.log(x);

for (const x of set.cycle())  // one full pass then stops
  console.log(x);

---

API

RotatableArray

method	summary
next()	return current, advance (wraps)
peek(offset=0)	inspect relative to cursor
move(offset)	jump ±offset, return new current
previous()	move(-1) shortcut
setIndex(i) / resetIndex()	absolute cursor jumps
toArray()	snapshot copy of backing store
length	item count
Symbol.iterator	infinite iterator (never done)
cycle()	one full pass starting at cursor

RotatableSet

Unique, ordered, circular set. All operations below are O(1) unless noted. The cursor always points at the item that next() will return.
getFurthestItem(index=0) is the item farthest ahead in next() order (i.e. previous), offset further backward by index (wraps).

method	summary
addToFurthest(item)	Set‑style append (unique), returns this
addToNext(item)	add and make it next returned by next()
add(item)	alias of addToFurthest(item)
delete(item)	Set‑style delete, returns boolean
next()	return current, advance (wraps)
peek()	read current without advancing
getFurthestItem(index=0)	item farthest from cursor; index steps farther back (wraps, O(1) when index is 0, otherwise O(index mod size))
has(item)	membership check
isEmpty	whether the set has zero items
clear()	remove all items
toArray() (O(n))	snapshot in rotation order starting from cursor
toSet() (O(n))	finite snapshot as native Set (in insertion order)
size	item count
Symbol.iterator	infinite iterator (never done)
cycle() (O(n))	one full pass starting at cursor

Note: because the iterator is infinite, use toArray(), toSet(), or cycle() for finite snapshots.

RotatableMutatableArray

Mutable, ordered, circular array. Inherits all RotatableArray methods and adds:

method	summary
push(item) / add(item)	append to end, returns new length
insert(index, item)	insert at absolute index, returns new length
removeAt(index)	remove by absolute index, returns removed item (throws if last item)

Note: the array must always contain at least one element; removeAt throws if it would become empty.