Non-Repeating ID Rotator

Build a helper that surfaces a non-repeating, random rotation over a provided list of IDs. The rotator must allow both callable access and iteration over the same underlying stream.

Capabilities

Callable selections avoid immediate repeats

• Consecutive next() calls always return different IDs while staying within the provided list. @test

Iterator shares state with calls

• Using the rotator in a for...of loop yields the same sequence as chained next() calls, consuming shared state so interleaving the two never produces back-to-back duplicates. @test

Sequence helper respects continuity

• Calling sequence(count) returns the next count IDs in order, with no consecutive duplicates, and subsequent next() continues from where sequence left off. @test

Single-item stability

• When initialized with a single ID, next(), iteration, and sequence always return that lone value. @test

Implementation

@generates

API

export interface IdRotator extends Iterable<string> {
  next(): string;
  sequence(count: number): string[];
  [Symbol.iterator](): Iterator<string>;
}

export function createIdRotator(ids: string[]): IdRotator;

Dependencies { .dependencies }

unique-random { .dependency }

Provides consecutively unique random value generation for bounded ranges.