Add exhaustive sampling and rename the default export to consecutiveUniqueRandom (#25)

Author: Richienb

index.d.ts

@@ -1,13 +1,13 @@
 /**
 Generate random numbers that are consecutively unique.
 
-@returns Returns a function, that when called, will return a random number that is never the same as the previous.
+@returns A function, that when called, will return a random number that is never the same as the previous.
 
 @example
 ```
-import uniqueRandom from 'unique-random';
+import {consecutiveUniqueRandom} from 'unique-random';
 
-const random = uniqueRandom(1, 10);
+const random = consecutiveUniqueRandom(1, 10);
 
 console.log(random(), random(), random());
 //=> 5 2 6
@@ -17,9 +17,9 @@ The returned function is also an iterable which consumes from the same source as
 
 @example
 ```
-import uniqueRandom from 'unique-random';
+import {consecutiveUniqueRandom} from 'unique-random';
 
-const random = uniqueRandom(1, 10);
+const random = consecutiveUniqueRandom(1, 10);
 
 for (const number of random) {
 	console.log(number);
@@ -31,4 +31,39 @@ for (const number of random) {
 }
 ```
 */
-export default function uniqueRandom(minimum: number, maximum: number): (() => number) & {[Symbol.iterator](): Iterator<number>};
+export function consecutiveUniqueRandom(minimum: number, maximum: number): (() => number) & {[Symbol.iterator](): Iterator<number>};
+
+/**
+Generate random numbers that do not repeat until the entire range has appeared.
+
+@return A function, that when called, will return a random number that is never the same as any previously returned until the entire range of possible numbers has been returned.
+
+@example
+```
+import {exhaustiveUniqueRandom} from 'unique-random';
+
+const random = exhaustiveUniqueRandom(1, 10);
+
+console.log(random(), random(), random());
+//=> 5 2 6
+```
+
+The returned function is also an iterable which consumes from the same source as the function:
+
+@example
+```
+import {exhaustiveUniqueRandom} from 'unique-random';
+
+const random = exhaustiveUniqueRandom(1, 10);
+
+for (const number of random) {
+	console.log(number);
+
+	// The unique numbers will be iterated over infinitely
+	if (stopCondition) {
+		break;
+	}
+}
+```
+*/
+export function exhaustiveUniqueRandom(minimum: number, maximum: number): (() => number) & {[Symbol.iterator](): Iterator<number>};

index.js

@@ -1,14 +1,24 @@
-export default function uniqueRandom(minimum, maximum) {
-	let previousValue;
+function * range(minimum, maximum) {
+	for (let number = minimum; number <= maximum; number++) {
+		yield number;
+	}
+}
 
-	function random() {
-		const number = Math.floor(
-			(Math.random() * (maximum - minimum + 1)) + minimum,
-		);
+function randomInteger(minimum, maximum) {
+	return Math.floor(Math.random() * (maximum - minimum + 1)) + minimum;
+}
+
+function randomIntegerWithout(minimum, maximum, excludedValue) {
+	const number = randomInteger(minimum, maximum - 1);
+
+	return number >= excludedValue ? number + 1 : number;
+}
 
-		previousValue = (number === previousValue && minimum !== maximum) ? random() : number;
+function makeCallable(generator) {
+	const iterator = generator();
 
-		return previousValue;
+	function random() {
+		return iterator.next().value;
 	}
 
 	random[Symbol.iterator] = function * () {
@@ -19,3 +29,53 @@ export default function uniqueRandom(minimum, maximum) {
 
 	return random;
 }
+
+export function consecutiveUniqueRandom(minimum, maximum) {
+	return makeCallable(function * () {
+		if (minimum === maximum) {
+			while (true) {
+				yield minimum;
+			}
+		}
+
+		let previousValue = randomInteger(minimum, maximum);
+		yield previousValue;
+
+		while (true) {
+			previousValue = randomIntegerWithout(minimum, maximum, previousValue);
+			yield previousValue;
+		}
+	});
+}
+
+export function exhaustiveUniqueRandom(minimum, maximum) {
+	return makeCallable(function * () {
+		if (minimum === maximum) {
+			while (true) {
+				yield minimum;
+			}
+		}
+
+		let unconsumedValues = [...range(minimum, maximum)];
+
+		while (true) {
+			while (unconsumedValues.length > 1) {
+				yield unconsumedValues.splice(
+					randomInteger(0, unconsumedValues.length - 1),
+					1,
+				)[0];
+			}
+
+			const [previousValue] = unconsumedValues;
+
+			yield previousValue;
+
+			unconsumedValues = [...range(minimum, maximum)];
+
+			yield unconsumedValues.splice(
+				randomIntegerWithout(0, unconsumedValues.length - 1, previousValue - minimum),
+				1,
+			)[0];
+		}
+	});
+}

index.test-d.ts

@@ -1,11 +1,20 @@
 import {expectAssignable, expectType} from 'tsd';
-import uniqueRandom from './index.js';
+import {consecutiveUniqueRandom, exhaustiveUniqueRandom} from './index.js';
 
-const random = uniqueRandom(1, 10);
+const random1 = consecutiveUniqueRandom(1, 10);
 
-expectAssignable<() => number>(random);
-expectType<number>(random());
+expectAssignable<() => number>(random1);
+expectType<number>(random1());
 
-for (const number of random) {
+for (const number of random1) {
+	expectType<number>(number);
+}
+
+const random2 = exhaustiveUniqueRandom(1, 10);
+
+expectAssignable<() => number>(random2);
+expectType<number>(random2());
+
+for (const number of random2) {
 	expectType<number>(number);
 }

readme.md

@@ -13,26 +13,32 @@ npm install unique-random
 ## Usage
 
 ```js
-import uniqueRandom from 'unique-random';
+import {consecutiveUniqueRandom} from 'unique-random';
 
-const random = uniqueRandom(1, 10);
+const random = consecutiveUniqueRandom(1, 10);
 
 console.log(random(), random(), random());
 //=> 5 2 6
 ```
 
 ## API
 
-### uniqueRandom(minimum, maximum)
+### consecutiveUniqueRandom(minimum, maximum)
 
-Returns a function, that when called, will return a random number that is never the same as the previous.
+Generate random numbers that are consecutively unique.
+
+### exhaustiveUniqueRandom(minimum, maximum)
+
+Generate random numbers that do not repeat until the entire range has appeared.
+
+Both `consecutiveUniqueRandom` and `exhaustiveUniqueRandom` return a function, that when called, will return the generated number.
 
 The returned function is also an iterable which consumes from the same source as the function:
 
 ```js
-import uniqueRandom from 'unique-random';
+import {exhaustiveUniqueRandom} from 'unique-random';
 
-const random = uniqueRandom(1, 10);
+const random = exhaustiveUniqueRandom(1, 10);
 
 for (const number of random) {
 	console.log(number);

test.js

@@ -1,15 +1,13 @@
 import test from 'ava';
 import assertInRange from './assert-in-range.js';
-import uniqueRandom from './index.js';
+import {consecutiveUniqueRandom, exhaustiveUniqueRandom} from './index.js';
 
-test('main', t => {
+function testConsecutiveUniqueness(t, uniqueRandom) {
 	const random = uniqueRandom(1, 10);
-	let count = 1000;
-	let currentValue;
 	let previousValue;
 
-	while (--count > 0) {
-		currentValue = random();
+	for (let count = 0; count < 1000; count++) {
+		const currentValue = random();
 
 		assertInRange(t, currentValue, {start: 1, end: 10});
 		if (previousValue !== undefined) {
@@ -18,14 +16,48 @@ test('main', t => {
 
 		previousValue = currentValue;
 	}
+}
 
-	t.pass();
+test('consecutiveUniqueRandom - main', t => {
+	testConsecutiveUniqueness(t, consecutiveUniqueRandom);
 });
 
-test('iterator', t => {
+test('consecutiveUniqueRandom - iterator', t => {
 	t.plan(3); // In case the for-of loop doesn't run
 
-	const random = uniqueRandom(1, 10);
+	const random = consecutiveUniqueRandom(1, 10);
+
+	for (const number of random) { // eslint-disable-line no-unreachable-loop
+		assertInRange(t, number, {start: 1, end: 10});
+		break;
+	}
+
+	const {value, done} = random[Symbol.iterator]().next();
+
+	assertInRange(t, value, {start: 1, end: 10});
+	t.false(done);
+});
+
+test('exhaustiveUniqueRandom - main', t => {
+	const random = exhaustiveUniqueRandom(1, 5);
+	const seenValuesCount = new Map(Array.from({length: 5}, (_, index) => [index + 1, 0]));
+
+	for (let count = 1; count <= 10; count++) {
+		const value = random();
+		assertInRange(t, value, {start: 1, end: 5});
+		t.true(seenValuesCount.get(value) < 2, 'Value should only appear twice');
+		seenValuesCount.set(value, seenValuesCount.get(value) + 1);
+	}
+});
+
+test('exhaustiveUniqueRandom - consecutive uniqueness', t => {
+	testConsecutiveUniqueness(t, exhaustiveUniqueRandom);
+});
+
+test('exhaustiveUniqueRandom - iterator', t => {
+	t.plan(3); // In case the for-of loop doesn't run
+
+	const random = exhaustiveUniqueRandom(1, 10);
 
 	for (const number of random) { // eslint-disable-line no-unreachable-loop
 		assertInRange(t, number, {start: 1, end: 10});