Non-Repeating Number Stream

Creates a callable + iterable random number stream over an inclusive integer range, with configurable uniqueness guarantees.

Capabilities

Unique number streams support two strategies: 'cycle' (default) emits every in-range value once per cycle before any repeat, and 'no-repeat' only forbids back-to-back duplicates while sampling infinitely.

Cycle through range without repeats

• With the default strategy, successive draws over [1, 3] return a permutation of {1, 2, 3} before any value repeats; the fourth draw differs from the third and belongs to [1, 3]. @test

Mixed iteration and calls share state

• After one direct draw, iterating two more values still yields three distinct numbers before any repeat when the range is [1, 3]. @test

Consecutive-only uniqueness

• When strategy is "no-repeat", repeated draws over [10, 11] alternate between 10 and 11 without ever returning the same number twice in a row across calls and iteration. @test

Degenerate range stability

• When minimum equals maximum (e.g., 5), both direct calls and iteration always produce that single value. @test

Implementation

@generates

API

export type UniqueNumberStream = (() => number) & Iterable<number>;

export interface UniqueNumberStreamOptions {
  strategy?: 'cycle' | 'no-repeat';
}

export function buildUniqueNumberStream(
  minimum: number,
  maximum: number,
  options?: UniqueNumberStreamOptions
): UniqueNumberStream;

Dependencies { .dependencies }

unique-random { .dependency }

Provides callable + iterable random number streams with range-bound uniqueness guarantees. @satisfied-by